Skip to content

Agent Handbook (Development Autonomy)

Date: 2026-02-08 Status: Draft

This file defines practical instructions that agents can follow during autonomous development.

Scope

  • Safe autonomous development in this repository.
  • No production-impacting actions without explicit approval.

Environments and Deployment Modes

  • Development environment is default for iterative work.
  • Production changes require explicit human approval and change context.
  • Keep deploy command references here (or link to runbook) with clear dev vs prod examples.

Logs and Diagnostics

  • Prefer service-level logs first, then infrastructure logs.
  • Standard workflow:
  • Identify service and environment.
  • Pull recent logs with bounded time windows.
  • Correlate by request ID/run ID/tenant/workspace.
  • Record concrete findings in the work summary.

Git Collaboration Workflow

  • Branch naming: codex/<scope>-<short-description>.
  • Keep commits small and reviewable.
  • Do not amend shared commits unless requested.
  • Do not force-push shared branches unless requested.
  • If unexpected repo changes are detected, stop and ask before proceeding.
  • Use layered instructions:
  • Root-level AGENTS.md for global repository policy.
  • Service-level services/<service>/AGENTS.md for local commands, test workflows, and caveats.
  • Service-level instructions should not conflict with root safety rules.
  • Each service-local file should link back to shared contracts and specs in /docs.

Change Safety Rules

  • Prefer additive changes over broad refactors.
  • Keep API and contract compatibility unless a linked ADR approves breaking change.
  • Update relevant docs with any behavior change.
  • Use PR checklist gates for docs impact and traceability to reduce drift over time.

Definition of Complete (for agent tasks)

  • Code change implemented.
  • Tests updated and run for affected scope.
  • Docs/specs/ADRs updated as needed.
  • Rollout risks and validation steps documented.