AGENTS.md Playbook (Project Standard)

AGENTS.md is the entrypoint guide for automated contributors (AI coding agents and other automation) working inside a repository.

It should answer, quickly and unambiguously:

• What this repo is and how it’s structured
• What rules must be followed (security, migrations, scope boundaries)
• Where to find the “source of truth” docs for conventions and workflows
• How to work safely (verification, escalation, testing expectations)

Purpose

Use AGENTS.md to:

• Prevent agents from guessing architecture and conventions.
• Encode hard constraints (e.g., “do not create migrations unless told”).
• Reduce churn by standardizing how changes are planned, implemented, and verified.

Where it lives

• AGENTS.md must live at the repository root.
• It should be kept short enough to be read before meaningful changes.

When to create / update it

Create or update AGENTS.md when:

• A repo is new or onboarding is slow.
• Rules are repeatedly violated (migrations, security, scope creep).
• The architecture changes (services split, new modules, new workflows).
• New automation/agents are introduced.

Non-negotiable standards (what it must include)

AGENTS.md must include:

• Repo overview: what the repo is.
• Module map: a short, top-level folder map describing where to find key things in the project.
• Hard rules: security posture, migration ownership policy, escalation policy.
• Documentation workflow: “read docs first, verify against code, ask when unclear”.
• Definition of done: what a successful change looks like.
• Docs location: an explicit reference that the repo’s main documentation lives in the root docs/ folder, plus the entrypoint file to start from.

What not to put in AGENTS.md

• Secrets, tokens, credentials, private URLs.
• Customer/project-specific information that shouldn’t generalize.
• Long runbooks better suited to docs/ playbooks.

Relationship to other docs

• AGENTS.md is the front door.
• Detailed standards live in docs/ at the repo root (start from the project’s docs entrypoint).
• Git/GitHub workflow guidance (branches, worktrees, push/PR semantics, monorepo ↔ split repo sync) should link to: docs/playbooks/git/workflow.md (do not duplicate git rules per project).
• Trackers live in trackers/ and are used only when explicitly requested.