AGENTS.md Strategy

Date: 2026-02-08 Status: Draft

AGENTS.md files provide executable local guidance for coding agents.

Where to Use Them

• Repository root AGENTS.md: global policy and defaults.
• Subdirectory AGENTS.md: area-specific constraints (service-specific test command, deployment caveats, ownership rules).

What Belongs in AGENTS.md

• Concrete, short, operational rules.
• Commands agents should run for validation.
• Safety constraints and escalation requirements.
• Paths to relevant spec docs.

What Does Not Belong in AGENTS.md

• Long-form architecture rationale.
• Full product vision.
• Detailed ADR-level trade-off discussions.

Relationship to the Docs Structure

• AGENTS.md is the execution layer.
• /docs is the system-of-record knowledge layer.
• Keep AGENTS concise and link back to docs for deeper context.

Suggested Pattern

• Root AGENTS.md links to:
• /docs/09-agent-operations/agent-handbook.md
• /docs/09-agent-operations/coding-values.md
• /docs/07-operations/ runbooks