Authoring AGENTS.md
AGENTS.md is the entry point for AI agents in a repository. Agent tools load it at the start of every session and limit how much instruction text they keep in context, so every line must earn its place.
Template: project-agents.template.md
Mandate
Every project must keep one AGENTS.md at the repository root.
AGENTS.md is the canonical filename. Do not copy the same rules into compatible filenames such as CLAUDE.md: duplicated instruction files drift apart and consume the context budget twice.
Put guidance in the right file
Put each kind of guidance where it belongs:
| Content | Where it belongs |
|---|---|
| Always-on commands, conventions, boundaries | AGENTS.md |
| Product background, onboarding, screenshots | README.md |
| Full development workflow and toolchain detail | DEVELOPMENT.md |
| Pull request, review, and validation requirements | CONTRIBUTING.md |
| Architectural invariants | ARCHITECTURE.md |
| A procedure needed only for one specific workflow | A separate document or agent skill, linked |
| Agent tool preferences, model defaults, autonomy level | That tool's own configuration file |
Do not paste run books, long reference documents, or task-specific notes into AGENTS.md. Link to the source of truth instead.
Structure
Open with one sentence naming what the project is and for whom, then order the sections by what an agent needs first, following the template:
- Commands — exact setup, run, single-test, test, lint, type check, build, regeneration, and full-validation commands; drop the lines the project does not have.
- Engineering standards — the shared guideline, plus project-specific overrides.
- Layout — one line per top-level directory, naming key modules.
- Boundaries — Always / Never / Ask first.
- Confirmed language policy — see Language Policy.
- Project conventions — the decisions an agent would not guess from the code.
- Depth links to
DEVELOPMENT.md,CONTRIBUTING.md, andARCHITECTURE.md.
Put commands first because agents need them right away. List both fast, targeted commands (such as running a single test file) and the full check (mise run check before committing), so the agent does not run the slowest command after every small edit.
Write verifiable rules
Every rule must state a behavior an agent can perform and a reviewer can check. Name the command, the path, or the condition.
Verifiable:
- Run `mise run test -- src/auth/token.test.ts` for changes under `src/auth/`.
- Never edit files under `src/generated/`; regenerate with `mise run codegen`.
- Ask before adding a dependency or changing an invariant in `ARCHITECTURE.md`.
Not verifiable, therefore useless:
- Be careful with the auth code.
- Make sure everything works.
- Follow best practices.
Nested files
Start with one root file. Add a nested AGENTS.md to a subdirectory only when that subtree genuinely differs:
- It uses a different package manager, test runner, or runtime.
- It contains generated code that must be regenerated rather than edited.
- It requires additional approval for operations such as migrations or deployments.
- It has UI or design-system rules that do not apply elsewhere.
A nested file lists only what differs in that directory and leaves everything else to the root file. Never repeat root rules in a nested file.
Keep it small
AGENTS.md is loaded at the start of every task, so every extra line costs context on every run.
- Put the most important rules at the top.
- Link to detail documents instead of copying them.
- Prefer automated checks over prose: do not restate rules that oxlint, prek, or CI already enforce.
- Move directory-specific guidance into a nested file instead of growing the root file.
Keep the root file short enough to read in one pass. When it grows too long, move details into linked files and cut what tools already enforce.
Never include
- Secrets, credentials, tokens, or private host names.
- Copies of documents that already exist elsewhere in the repository.
- Exhaustive directory inventories, which go stale on the next refactor.
- Temporary task notes that belong in an issue or pull request.
- Blanket instructions to skip validation.
Keep it current
Update AGENTS.md in the same change that alters its commands, layout, boundaries, or conventions.
A stale instruction is worse than a missing one: an agent follows it confidently and produces a change nobody asked for.