AGENTS.md Template

A concise operating guide for AI coding agents. Put this file in the root of your repository so every agent session starts with the same context.

Copy the template below into your repo as AGENTS.md, then fill in your project-specific details. Keep it concise — agents read it at the start of every session.

The template

# AGENTS.md — [Project Name]

## Project overview

[What this repo does in 2–4 sentences. Who it is for. 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

## 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 |

## Story 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 you chose this数据库方案]
- [Why this architecture pattern]
- [What should NOT be revisited without a team discussion]

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. Record 2–3 non-obvious decisions agents should not reopen

Common mistakes to avoid

• Vague commands — "run tests" is not enough; say exactly which command and which outcomes
• Too long — if it is more than a screen, cut detail and link to docs
• Task-specific context — temporary task details belong in the story packet or prompt, not here
• No review step — agent-ready does not mean agent-only; humans still review every change

Tool-specific notes

• Claude Code — reads AGENTS.md on every claude code invocation; keep it at the root
• Cursor — place in .cursor/rules/ for cursor-agent compatible use
• Codex — some setups read from project instructions; check your agent config
• Aider — use --read agent-context-files to provide AGENTS.md context

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 answers five questions: what the project does, what commands prove a change is correct, what files or areas agents must not touch, which directories map to which concerns, and which decisions are already made and should not be reopened. Keep it under a screen of text and link to deeper docs when detail is needed.

How long should an AGENTS.md file be?

Aim for a single screen of text — roughly 60 to 120 lines. Anything longer and agents start skimming or ignoring sections. Put durable, repo-wide rules at the top. Link to architecture docs, decision records, and testing guides instead of inlining them.

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?

At the repository root: ./AGENTS.md. Some tools also pick up ./.github/AGENTS.md or ./docs/AGENTS.md, but the root location is the universal default. Keep it short enough that the file name alone signals "read me first".

Does Claude Code read AGENTS.md?

Yes. Claude Code reads AGENTS.md from the repository root at the start of every session. You can also drop tool-specific commands in .claude/commands.md for Claude Code-only behavior. The same AGENTS.md is also picked up by Codex-based tools, Aider (with --read), and most modern coding agents.

How is AGENTS.md different from Cursor rules?

AGENTS.md is a single file at the repo root that travels with the code and is read by every coding agent that enters the repo. Cursor rules live in .cursor/rules/ and apply only to the Cursor IDE on a given developer machine. Use AGENTS.md for repo-wide context. Use Cursor rules for personal IDE preferences that should not be committed to the repo.

Can I use this template for a small personal project?

Yes. Even a 200-line project benefits from a one-screen 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.