AGENTS.md Template for Coding Agents

A repository operating contract for coding agents: where truth lives, what may change, which commands prove the result, when to stop, and what evidence to hand back.

Copy the template below into your repository as AGENTS.md. Delete sections that do not control a real decision, add nested files only where scope changes, configure thin tool adapters, and verify discovery in a clean session.

The template

# AGENTS.md — [Project Name]

## Project overview

[What this repo does in 2–4 sentences.]
[Who it is for and what problem it solves.]

## Before you start

- Read these files first: [e.g. README.md, docs/architecture.md]
- Preferred change size: small and reviewable
- Do not change public APIs without updating tests and docs
- Do not modify credentials, secrets, or migration files

## Authority and source of truth

| Concern | Authoritative source |
|---|---|
| Public API | [schema, interface, or contract-test path] |
| Generated code | [generator command and source input] |
| Database shape | [schema or migration directory] |
| Product behavior | [tests, specification, or decision record] |

When sources disagree, stop and report the conflict.
Do not silently choose the most convenient file.

## Commands

| Command | What it does |
|---|---|
| npm install | Install dependencies |
| npm test | Run full test suite |
| npm run lint | Lint and format check |
| npm run typecheck | TypeScript type checking |
| npm run build | Production build |

## Architecture

- `src/` — [description]
- `src/api/` — [description]
- `src/domain/` — [description]
- `src/ui/` — [description]
- `tests/` — [description]
- `docs/` — [description]

## What not to touch

- `src/config/secrets.ts` — credentials, do not edit
- `db/migrations/` — talk to a human first
- `src/auth/` — security-sensitive, get approval

## Validation matrix

| Change type | Required checks |
|---|---|
| Docs only | npm run lint -- --fix |
| Frontend UI | npm test + npm run build |
| API change | npm test + integration tests |
| Refactor | Full test suite + typecheck + build |

## Task packet format

When picking up a task, use this structure:

```
Problem:

User outcome:

Relevant files:

Constraints:

Acceptance criteria:

Validation commands:

Out of scope:
```

## Decisions that are already made

- [Why this data-storage approach was chosen]
- [Why this architecture pattern]
- [What should NOT be revisited without a team discussion]

## Stop conditions

Stop and ask for direction when:

- the requested change conflicts with an authoritative contract;
- the only path requires editing a protected area;
- validation needs credentials or infrastructure that are unavailable;
- a generated file would need a manual edit instead of its generator;
- the scope expands beyond the stated acceptance criteria.

## Evidence handoff

Before finishing, report:

- files changed and the user-visible outcome;
- validation commands run and their results;
- checks not run, with the reason;
- assumptions, residual risks, and follow-up work.

How to use this template

1. Copy the template into your repo root as AGENTS.md
2. Fill in the project overview — 2–4 sentences, no prose
3. List the exact commands for install, test, lint, typecheck, build
4. Map the main directories and their purposes
5. Mark any safety boundaries — files or areas agents should not touch
6. Define your validation matrix — which checks prove which change types
7. Name the authoritative source for APIs, schemas, generated output, and product behavior
8. Record 2–3 non-obvious decisions agents should not reopen
9. Add stop conditions and an evidence handoff so uncertainty is surfaced instead of hidden

Use a root router, not one giant instruction file

The root file should contain repository-wide rules and route agents to the right local source. Put package-specific commands and boundaries in nested AGENTS.md files only when the scope genuinely changes.

repo/
├── AGENTS.md                 # shared authority, commands, boundaries
├── apps/
│   └── web/
│       └── AGENTS.md         # UI-specific checks and design-system rules
├── services/
│   └── api/
│       └── AGENTS.md         # API contracts, migrations, integration tests
└── docs/
    └── decisions/            # durable rationale linked from instructions

Do not duplicate the root file into every package. A nested file should add or narrow guidance for its subtree, not create a second competing repository contract.

Common mistakes to avoid

• Vague commands — "run tests" is not enough; say exactly which command and which outcomes
• Too broad — if the root mixes unrelated package rules, use nested files and link to deeper docs
• Task-specific context — temporary task details belong in the task packet or prompt, not here
• Missing authority — listing paths without saying which file wins forces agents to guess when sources conflict
• Manual generated-file edits — name the generator and source input so agents change the cause, not the output
• No stop conditions — an agent should know when uncertainty requires escalation rather than improvisation
• No review step — agent-ready does not mean agent-only; humans still review every change

Tool-specific notes

• Claude Code — uses CLAUDE.md and .claude/rules/; reference the shared AGENTS.md contract from a thin CLAUDE.md adapter instead of duplicating it
• Cursor — supports root and nested AGENTS.md files; use version-controlled .cursor/rules/*.mdc for Cursor-specific behavior
• Codex — natively discovers layered AGENTS.md files from the project root toward the working directory; AGENTS.override.md can replace instructions at a level
• Aider — configure or pass AGENTS.md as a read-only context file; do not assume automatic discovery

Verify the template in a clean session

Do not declare the file complete because it reads well. Open a fresh agent session at the repository root and ask the agent to identify:

1. the authoritative source for one public contract;
2. the narrowest validation command for a small change;
3. one protected area and one explicit stop condition;
4. the applicable nested instructions for a package;
5. the evidence expected before handoff.

If the answers require guessing, the repository contract is incomplete. Repair the missing route or authority boundary, then repeat the probe.

Learn why this matters →

When to fill in which section

Not every section belongs in every repo. A quick decision guide:

• Solo side project (under 1,000 lines): Project overview, Commands, What not to touch. Skip the rest.
• Small team repo (1k–20k lines): All of the above plus Architecture map and Validation matrix.
• Multi-team production service: All sections, plus Decisions that are already made and a Story packet template.
• Library or framework: All sections, with extra weight on Public API stability and "do not change public APIs without updating tests and docs".

FAQ

What should be in an AGENTS.md file?

A useful AGENTS.md explains what the project does, where authoritative truth lives, what commands prove a change is correct, what files or areas agents must not touch, which directories map to which concerns, when the agent must stop, and what evidence it should hand back. Keep the root concise, use nested files for scoped rules, and link to deeper docs when detail is needed.

How long should an AGENTS.md file be?

There is no official line limit. Keep each file as short as possible while preserving the non-obvious instructions needed for its scope. Use nested files and linked documentation when one root file starts mixing unrelated package-specific rules.

Is AGENTS.md the same as README.md?

No. README.md is for humans joining the project. AGENTS.md is for coding agents entering the project. The two overlap, but README.md explains how to run, build, and contribute, while AGENTS.md encodes operating constraints, validation rules, and safety boundaries that an agent must respect on every change.

Where should AGENTS.md live in the repo?

Start at the repository root as ./AGENTS.md. In monorepos, add nested files inside packages that need more specific instructions. The closest applicable file normally supplies the most specific guidance, but exact discovery and precedence vary by tool.

Does Claude Code read AGENTS.md?

Not as its native project-memory file. Claude Code uses CLAUDE.md and .claude/rules/. Keep shared repository instructions in AGENTS.md, reference them from a small CLAUDE.md, and reserve .claude files for Claude-specific behavior.

How is AGENTS.md different from Cursor rules?

AGENTS.md is a portable repository contract supported by multiple tools. Cursor Project Rules are version-controlled .mdc files under .cursor/rules/ with Cursor-specific activation and scoping. Use AGENTS.md for shared repository truth and Project Rules for Cursor-only workflows or enforcement.

Can I use this template for a small personal project?

Yes. Even a 200-line project benefits from a concise AGENTS.md that says what the project does, which command runs the tests, and which files are risky. Small projects often have the worst repo context because nobody bothers to document anything, and agents fill the gap with guesses.

How do I keep AGENTS.md from going stale?

Treat it like code: review changes in pull requests, update it when an agent makes the same mistake twice, and link from it to decision records so the why lives in version control. When a section stops being useful, delete it. The file should always reflect the current operating contract, not the original author's good intentions.

Related pages

• What Is an Agent-Ready Repository? — the broader checklist that AGENTS.md is part of
• Context Engineering for Coding Agents — the framework that AGENTS.md implements
• Harness Engineering for Coding Agents — how AGENTS.md fits into the larger workflow
• How to Write an AGENTS.md That Actually Works — the writing guide that pairs with this template
• AGENTS.md vs Cursor Rules — when to use AGENTS.md and when to use IDE-specific rules
• How to Prepare Your Repository for Claude Code — Claude Code-specific setup that uses this template
• How to Prepare Your Repository for Codex — Codex-specific setup that uses this template
• Coding Agents Need Better Repositories, Not Just Better Prompts — the argument for why templates like this matter

See also: repository-harness — the open-source starting point that bundles this template with architecture notes, decision records, and a validation matrix.

Open the GitHub repo → The full agent-ready repository with this AGENTS.md, architecture map, validation matrix, and decision records lives at github.com/hoangnb24/repository-harness. Star it, fork it, and adapt the template to your own project.