Writing AGENTS.md & CLAUDE.md That Actually Steer Agents

What you need to know

• These files are the agent's onboarding doc. AGENTS.md, CLAUDE.md, .cursor/rules and Copilot instructions are read automatically and prepended to the model's context, so they shape every edit the agent makes.
• AGENTS.md is becoming the portable standard. As of June 2026 a growing number of agents read a root-level AGENTS.md; Claude Code reads CLAUDE.md rather than AGENTS.md, and its memory docs recommend a CLAUDE.md that imports AGENTS.md so both share one source.
• Concise beats exhaustive. Every line costs tokens on every turn. Put commands, the architecture map and non-obvious rules in; leave restated obvious advice out.
• Treat it as living code. Test changes by running a task with and without the rule, fix it when the agent misbehaves, and keep nested files small in a monorepo.

What these files are, and why agents read them

An agent-context file is a plain Markdown document that your coding agent loads at the start of a session and keeps in context while it works. It is not a prompt you type; it is the standing brief the tool consults before it touches your repository. As of June 2026, and per each tool's own docs: when Claude Code opens a project it looks for CLAUDE.md; when Cursor runs it reads the files under .cursor/rules; GitHub Copilot reads .github/copilot-instructions.md; and a growing number of tools now read a single tool-agnostic file called AGENTS.md. These are evolving tools, so the exact filenames and load behaviour are worth confirming against the primary docs linked throughout.

The reason this matters is simple: a coding agent has no memory of your project between sessions and no way to know your conventions unless you tell it. Left to its own devices it will guess. It will run npm test when your team uses pnpm test, scaffold a component in the wrong directory, reach for a library you deliberately removed, or write British spelling into code identifiers where your codebase uses American. A good context file converts those guesses into knowledge, and that is the difference between an agent that drafts a clean pull request and one that generates a day of cleanup.

This is the practical face of a broader shift the industry has been calling context engineering — the discipline of curating what the model sees rather than wordsmithing a one-off prompt. Your AGENTS.md is the most reusable piece of context you own, because it applies to every task, every teammate and every CI run.

The convergence on AGENTS.md

For most of 2025 every tool invented its own filename, and teams using more than one agent ended up maintaining three or four documents that said roughly the same thing. The AGENTS.md standard emerged to fix that: a single, tool-agnostic Markdown file at the repository root that any compliant agent can read. As of June 2026 it has broad support across the major agents, and it is the file we recommend you treat as canonical.

Where does Claude Code's CLAUDE.md fit? Claude Code reads CLAUDE.md, and has done since launch. As of June 2026 its memory docs are explicit that it reads CLAUDE.md rather than AGENTS.md — but they recommend the same single-source pattern we do: if your repo already has an AGENTS.md, create a CLAUDE.md that imports it rather than maintaining a second copy that drifts. We show exactly how below. (Tool behaviour evolves, so confirm against the linked docs for the version you run.)

What to put in the file

Think of the file as the README you would give a sharp contractor on their first morning — someone competent who knows the languages but nothing about your repository. They do not need a tutorial on TypeScript; they need to know how to build, test and lint, where things live, and the handful of rules that are not obvious from the code. In priority order:

• Commands. The exact build, test, lint and type-check commands, copy-paste ready. Crucially, include how to run a single test file or case — agents waste enormous effort running the whole suite to check one change.
• How to run the project. Dev server command, required environment variables (names, not values), and any setup step that is not in package.json scripts.
• Architecture map. A short directory tour: what lives where, where the entry points are, which layer talks to which. Five or six lines, not a treatise.
• Code style and conventions. Only the non-obvious ones — your linter already enforces formatting. Things like "use the Result type, never throw in the domain layer" or "all API handlers return our ApiResponse envelope".
• Naming. File and symbol naming patterns the agent should match, especially anything your tooling does not catch.
• Commit and PR norms. Conventional Commits, the PR template, whether to update the changelog, who to tag.
• Explicit do and don't rules. "Do add a test for every new branch." "Don't edit files in generated/." Concrete, checkable instructions outperform vague encouragement.
• Security and secrets boundaries. Where secrets live, what the agent must never read or print, which files are off-limits.

A tight example AGENTS.md

Here is a complete, realistic root-level file for a mid-sized web service. Note how short it is — this is doing real work despite fitting on a single screen.

# AGENTS.md

## Project
Payments API for the UK and India markets. Node 20, TypeScript, Fastify, PostgreSQL.

## Commands
- Install:        pnpm install
- Dev server:     pnpm dev          # http://localhost:3000
- Build:          pnpm build
- Lint + format:  pnpm lint         # eslint + prettier, fails on warnings
- Type-check:     pnpm typecheck
- All tests:      pnpm test
- Single test:    pnpm test src/billing/invoice.test.ts
- One test case:  pnpm test -t "rounds VAT to 2 dp"

## Architecture
- src/routes/    HTTP handlers. Thin. Validate input, call a service, return ApiResponse.
- src/services/  Business logic. No framework imports here.
- src/db/        Drizzle schema + queries. Migrations in src/db/migrations.
- src/lib/       Shared helpers. money.ts handles all currency maths.

## Conventions
- Every handler returns the ApiResponse<T> envelope from src/lib/response.ts.
- Money is stored and computed in integer minor units. Never use floats for currency.
- Throw AppError (src/lib/errors.ts) for expected failures; never throw raw Error.

## Do
- Add a Vitest test for every new branch of logic.
- Run `pnpm lint && pnpm typecheck` before declaring a task done.

## Don't
- Don't edit anything under src/db/migrations — generate new migrations instead.
- Don't read or print .env files. Use process.env names only.
- Don't add new dependencies without flagging it; we keep the tree small.

## Security
- Secrets live in .env (gitignored) and in the CI secret store. Never commit them.
- PII (card data, customer email) must never appear in logs.

The matching CLAUDE.md pointer

Rather than duplicate that content, give Claude Code a one-line file that defers to the canonical document. This keeps a single source of truth and means a change to AGENTS.md instantly reaches every tool.

# CLAUDE.md
@AGENTS.md

## Claude Code
# AGENTS.md (imported above) holds the build commands, architecture and conventions.
# Add only Claude-specific lines here. This file is committed;
# keep machine-specific bits in CLAUDE.local.md (gitignored).

As of June 2026, the @AGENTS.md syntax is how Claude Code imports another file's contents into context, per the Claude Code memory docs — so the pointer is not just a comment; Claude expands AGENTS.md at session start and then appends any Claude-specific lines below it. (Import syntax is a tool feature that can change, so check the docs for the version you run.) If your team prefers a single physical file, the docs note you can instead symlink CLAUDE.md to AGENTS.md where Claude-specific content is not needed. Either way, the rule is one source of truth, never two copies.

What to leave out

The most common mistake is treating the file as documentation rather than instruction. Every line you add is loaded into context on every single turn, so a bloated file is not just untidy — it dilutes the signal and raises your token bill. Leave out:

• Anything the agent already knows. It does not need a primer on what React is, how Git works, or why tests matter. Restating the obvious wastes context and trains the agent to skim.
• Generated or derivable facts. Do not paste your full dependency list or directory tree — the agent can read package.json and ls the repo. Point at where things are, do not transcribe them.
• Long prose explanations. A paragraph on the philosophy of your architecture is worth one crisp line: "services contain logic, routes stay thin". Agents act on instructions, not essays.
• Aspirations and vibes. "Write elegant, maintainable code" is unverifiable and ignored. Replace it with a concrete rule the agent can check.
• Volatile detail. Anything that changes weekly — sprint goals, the current ticket, today's deploy plan — belongs in the task prompt, not the standing file.

Hierarchy and scope: monorepos, precedence and personal files

A single file works for a single package. Real repositories — and most teams at a Bengaluru product company or a London scale-up are working in one — have several. The model the major agents converge on is a hierarchy: a root file holds workspace-wide rules, and each package can carry its own nested file with the rules that differ. When the agent edits a file, it applies the nearest context file and merges it with the ancestors above it, with the closer file winning on any conflict.

A nested monorepo example

Suppose a monorepo with a Next.js web app and a Python ML service. The root states what is universal; each package states only what is special.

# /AGENTS.md  (root — applies everywhere)
## Monorepo
pnpm workspaces. Packages live in apps/* and packages/*.
- Build everything:  pnpm -r build
- Conventional Commits required. Scope = package name, e.g. feat(web): ...

# ---------------------------------------------------------------

# /apps/web/AGENTS.md  (overrides + adds, for this app only)
## Web app
Next.js 15, App Router, Tailwind. Server Components by default.
- Dev:   pnpm --filter web dev
- Test:  pnpm --filter web test
- Don't add 'use client' unless the component needs state or effects.

# ---------------------------------------------------------------

# /apps/ml-service/AGENTS.md  (different language, different rules)
## ML service
Python 3.12, FastAPI, uv for deps. Type hints everywhere.
- Run:   uv run uvicorn app.main:app --reload
- Test:  uv run pytest tests/test_scoring.py::test_threshold   # single test
- Format: uv run ruff format && uv run ruff check --fix

Notice the nested files do not repeat the commit convention or the workspace layout — those live once at the root. Each nested file is three or four lines because it only states the delta. This is the discipline that keeps a monorepo's agent context manageable, and it pairs naturally with running focused agents per package — a topic we cover in our guide to subagent and multi-agent orchestration.

Personal versus shared

Commit the shared file. That is the whole point — every teammate in Mumbai, Manchester or anywhere else, plus every CI agent, gets identical behaviour from version control. Personal preferences are different. Your scratch directory, your local API base, a note that you prefer verbose explanations — none of that should land in a colleague's session or, worse, a pull request diff. Keep those in an untracked file. Claude Code reads CLAUDE.local.md for exactly this and you gitignore it; other tools have an equivalent. The boundary is: shared file for how the project works, local file for how you work.

The do/don't table

The same advice, condensed. Print it, pin it above your AGENTS.md, and check your file against it.

Do	Don't
State exact, copy-paste commands, including how to run a single test.	Assume the agent will infer the right command from package.json.
Write verifiable rules ("run lint before finishing").	Write vibes ("produce high-quality, elegant code").
Keep one source of truth; point CLAUDE.md at AGENTS.md.	Maintain three near-identical files that quietly drift apart.
Put workspace rules at the root, deltas in nested files.	Copy the full root file into every package.
Commit the shared file; gitignore personal context.	Commit your local scratch paths and editor quirks.
Keep it short — every line is loaded on every turn.	Treat it as exhaustive documentation with a table of contents.
Prune it when the agent misbehaves; test the change.	Let it go stale with commands and paths that no longer exist.
Name the off-limits areas (generated code, migrations, secrets).	Leave the agent to guess what it may safely edit.

Keeping the file effective

An agent-context file is a living document, not a one-time setup chore. Three habits keep it earning its place:

• Concise over exhaustive. Re-read it monthly and cut anything the agent now gets right without being told. A shorter file that is fully attended-to beats a long one that is half-skimmed.
• No contradictions. If one section says "throw AppError" and another says "return a Result", the agent will pick one at random and you will get inconsistent code. Audit for conflicts whenever you add a rule, especially across nested files.
• Keep it current. A stale command is worse than no command — it sends the agent confidently down the wrong path. When you change your test runner, your directory layout or your CI, update the file in the same commit.

The strongest signal that your file needs work is the agent itself. When it does something wrong — runs the legacy command, edits a generated file, reaches for a banned library — that is not just a bad turn; it is a missing or stale rule pointing straight at the fix. This feedback loop is the heart of getting more out of agents in general, which we explore further in how to get more from AI coding agents.

How to test whether your file changes behaviour

The uncomfortable truth is that much of what people write into these files does nothing. The only way to know is to test, and the test is mercifully simple: run the same realistic task twice, once with the rule present and once with it removed, each on a fresh session, and compare what the agent actually did.

Concretely:

• Pick a representative task — something you would genuinely ask the agent, like "add an endpoint that lists invoices for a customer".
• Run it on a clean session with your current file. Note the commands it ran, where it put files, the conventions it followed.
• Remove or change the rule under test, start a fresh session, and run the identical task. Compare.
• If the behaviour is the same either way, the rule is doing nothing. Either the agent already knew it (cut the line) or the rule is too vague to act on (rewrite it as a concrete, verifiable instruction).

This is the same empirical mindset that underpins spec-driven development and plan-first workflows: do not assume the agent understood you — give it a concrete target and check the result. If you have wired up slash commands and hooks, you can even codify a small "agent behaviour" check that runs a canned task and flags when the output drifts from what your rules intend.

Common failure modes

Almost every ineffective context file fails in one of five recognisable ways. Scan your own against this list:

• Too long. The file has grown into documentation. The agent attends to the start and the end and skims the middle, so the rule you care about is the one it misses. Fix: cut hard, split into nested files, link out for reference.
• Stale. Commands, paths or conventions that no longer match reality. The agent trusts the file over the repo and goes wrong with confidence. Fix: update in the same commit as the change, and re-test periodically.
• Vague. "Follow best practices", "write clean code". Unverifiable, so unactionable. Fix: replace each vibe with a concrete, checkable instruction.
• Contradictory. Two rules that cannot both hold, often across a root and a nested file. The agent picks inconsistently. Fix: audit for conflicts whenever you add a rule.
• Unverifiable by the agent. Instructions the agent has no way to confirm it followed — "make sure stakeholders are happy". The agent cannot check, so it cannot comply. Fix: keep instructions to things the agent can observe in the code or the tooling.

Get these right and the payoff is large and compounding. A good AGENTS.md is written once, costs a handful of lines per task, and quietly raises the floor on every change the agent makes — for every developer on the team and every automated run in CI. As of June 2026 it is among the highest-leverage half-hours you can spend on your codebase.

Primary references worth bookmarking: the AGENTS.md standard, the Claude Code memory documentation, the Cursor rules docs, and GitHub Copilot custom instructions.