AGENTS.md: Give Coding Agents Real Repo Context

Short answer: AGENTS.md is a Markdown file at the root of a repository that tells AI coding agents how your project actually works. It is an open convention, not a proprietary feature — agents that support it read the file at the start of a session. Put in it what a new contractor would need on day one: how to run the project, what the conventions are, and which things are load-bearing and must not be touched casually.

AGENTS.md is repository-level context: a checked-in Markdown file at the project root that supplies build commands, conventions, and constraints to any compatible coding agent. It replaces re-explaining the same setup in every new chat session and makes agent behaviour consistent across a team.

The problem it solves

Every agent session starts blind. It has a capable model and no idea that your tests need a database container, that src/generated/ must never be hand-edited, or that you use pnpm and not npm.

So people re-type the same paragraph. Ten times a week. Different people phrase it differently, and the agent behaves differently as a result.

AGENTS.md turns that paragraph into a file in the repo. It is versioned, reviewed like code, and identical for everyone.

Where it goes

Root of the repository, named exactly AGENTS.md. Most tools that support the convention look there first.

In a monorepo, put a root file for shared rules and a nested file per package for package-specific ones. The nearest file to the code being edited usually wins, which mirrors how .editorconfig and .gitignore already behave.

repo/
  AGENTS.md              # shared: toolchain, commit style, review rules
  apps/web/AGENTS.md     # frontend: component conventions, test command
  services/api/AGENTS.md # backend: migrations, error handling

What belongs in it

Section	Include	Why it matters
Commands	Install, run, test, lint, typecheck	Agents guess wrong and waste turns
Layout	Where the important code lives	Stops searching from scratch every time
Conventions	Naming, error handling, imports	Prevents style drift you then have to fix
Guardrails	Files and commands that are off limits	The highest-value section by far
Verification	How to prove a change works	Turns “looks right” into “tests pass”
Environment quirks	Required env vars, seeded data, ports	Eliminates the most common setup failure

A file you can copy

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 3000, needs `.env.local`)
- Tests: `pnpm test`  - run a single file: `pnpm test src/foo.test.ts`
- Lint: `pnpm lint --fix`
- Typecheck: `pnpm tsc --noEmit`

## Layout
- `src/app/` route handlers and pages
- `src/lib/` shared logic, no React imports allowed here
- `src/generated/` output of codegen - NEVER edit by hand
- `db/migrations/` append-only; never modify an existing migration

## Conventions
- TypeScript strict; no `any` without a comment explaining why
- Errors: throw typed errors from `src/lib/errors.ts`, do not return null
- Tests live next to the file they test

## Guardrails
- Do not run `db:reset` or `db:seed` - they wipe local data
- Do not touch `infra/` without an explicit instruction
- Do not upgrade dependencies as part of an unrelated change

## Verification
Before saying a task is done:
1. `pnpm lint`
2. `pnpm tsc --noEmit`
3. `pnpm test` for the touched area
Report the exact commands you ran and their output.

That is roughly forty lines. It will outperform a two-hundred-line version, because it is short enough to be read completely and specific enough to change behaviour.

What must not go in it

• Secrets. No tokens, no connection strings, no internal hostnames with credentials. The file is committed and often pasted into context.
• A copy of your documentation. Link to the docs instead. Duplicated content goes stale and agents trust stale content confidently.
• Personality instructions. “You are a senior engineer who…” does not change output quality the way a real constraint does.
• Everything you know. If the file takes two minutes to read, it will be skimmed or truncated. Both are worse than a short file.
• Rules with no enforcement. “Always write tests” is a wish. “`pnpm test` must pass before you report done” is a check.

The guardrails section earns its keep

Most agent incidents are not bad code. They are an agent doing something reasonable that happened to be destructive: resetting a database, regenerating files that were hand-patched, force-pushing a branch.

A short list of forbidden actions prevents nearly all of them. Write it as commands and paths, not as principles. “Be careful with the database” gives an agent nothing to check against.

Keep it current or delete it

Stale context is worse than no context. An agent that reads “tests run with npm test” after you migrated to pnpm will confidently run the wrong command and then invent an explanation for the failure.

Two habits that keep it honest: update the file in the same PR that changes the command, and review it quarterly like you review dependencies.

Does it actually work?

You can measure it, and you should. Three signals worth tracking before and after:

Signal	How to read it
Turns to first correct command	Lower means the commands section is working
Guardrail violations	Any occurrence means the rule is not specific enough
Review comments about style	Dropping means the conventions section landed

For repeatable tasks, encode them as eval cases: same task, same repo, run before and after a context change. That is the only way to tell a good instruction from a plausible-sounding one. The harness pattern is covered in building an LLM eval harness that runs in CI.

Relationship to MCP

They solve different problems and are often confused. AGENTS.md tells an agent about your repository. MCP gives an agent tools to reach systems outside the repository — a database, a ticket tracker, a documentation index.

A practical setup uses both: AGENTS.md for build and convention context, and an MCP server for anything the agent needs to query at runtime. If you are building the tool side, the MCP server guide covers the implementation.

Frequently asked questions

Is AGENTS.md an official standard?

It is an open convention rather than a formal specification, and it is supported across a growing set of coding agents. Treat it as a portable file: useful anywhere, guaranteed nowhere.

How long should it be?

Under about a hundred lines for most repositories. If yours is longer, you are probably documenting things that belong in linked docs.

Should I duplicate it per package in a monorepo?

Only the parts that differ. Duplicating the toolchain section across six packages guarantees five of them will be stale.

Does it replace code review?

No. It reduces the number of review comments about mechanics, so review time goes to design and correctness instead.

What if my agent ignores the file?

Usually because the file was too long to be fully included, or the rules were too vague to check. Shorten it, and rewrite every rule as a command or a path.

Can I keep it out of the repository?

You can, but you lose the thing that makes it work: everyone gets the same version, and changes get reviewed.

Sources

Convention and community guidance on repository-level agent context, including published practitioner write-ups from 2026. Checked 22 October 2026. Support varies by agent, so verify against your tool’s current documentation before relying on nested file precedence.

Last updated 22 October 2026.