Instruction files: AGENTS.md and friends

The cheapest, highest-leverage context is a short file at the root of your repo that tells the agent how the project works. Most tools read one automatically at the start of every session.

Watch

The CLAUDE.md fileClaude · 3 min

The landscape

• AGENTS.md: an open, tool-agnostic convention. A plain Markdown "README for agents" with no required schema. Many coding tools read it, and in a monorepo the nearest file in the directory tree applies.
• CLAUDE.md: the equivalent for Claude Code, loaded as project memory, including from parent and nested folders.
• Cursor rules: project rules that Cursor includes in context.
• Copilot instructions: repository custom instructions for GitHub Copilot.

Details differ between tools and change quickly, so check the docs linked below. A common pattern is one shared source of truth plus a thin tool-specific file for anything that only applies to one tool.

What belongs in the file

Write only what the agent cannot easily infer by reading the code:

1. Commands: install, build, run, test (including a single test), lint, type-check.
2. Project map: two or three lines per major directory, and which are generated or off limits.
3. Conventions that are not obvious: error handling pattern, naming, preferred libraries, things to avoid and why.
4. Workflow rules: branch naming, commit style, what must pass before opening a PR.
5. Gotchas: the flaky test, the env var needed locally, the migration order.

What does not belong

• Anything a linter or formatter already enforces. Let the tool do it.
• Long architecture essays. Link to a doc the agent can open when needed.
• Vague advice ("write clean code").
• Secrets or credentials. These files are committed and read by many tools.
• Rules nobody tests. If you cannot tell when a rule is followed, remove it.

A compact example

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (http://localhost:3000)
- Test all: `pnpm test`  · one file: `pnpm test path/to/file.test.ts`
- Before finishing: `pnpm lint && pnpm typecheck && pnpm test`

## Layout
- `apps/web` — Next.js app. `packages/ui` — shared components.
- `packages/db/generated` — generated by `pnpm db:generate`. Never edit by hand.

## Conventions
- Data access goes through `packages/db`. Do not query the database from components.
- Use the `Result<T>` helper from `packages/utils` instead of throwing in domain code.
- New components need a story in `*.stories.tsx`.

## Gotchas
- `auth.test.ts` needs `AUTH_SECRET` set; see `.env.example`.

Keep it short and alive

Instruction files compete with the task for attention. A practical target is a page or two. Treat the file like code:

• Add a line when you catch the agent repeating a mistake in review.
• Delete lines that no longer help or that the model already follows.
• Review changes to it in pull requests.
• Use nesting for monorepos so each package carries only its own rules.

Resources

Check yourself

1. Write an instruction file for a repo you know, under 60 lines.
2. Run the same three tasks with and without it. Count mistakes and retries.
3. Remove every line you cannot link to a mistake it prevents. Re-run and compare.