Writing AGENTS.md and CLAUDE.md Files That Agents Follow

Agent instruction files are the cheapest lever you have over how a coding agent behaves in your repository. Claude Code reads CLAUDE.md, Codex CLI reads AGENTS.md, Gemini CLI reads GEMINI.md, and several other tools read AGENTS.md or their own equivalent. Each is just Markdown, loaded at the start of a session, and each shapes every task the agent does afterwards.

Most of these files end up either too thin to help ("This is a Next.js app") or so long that the useful rules are buried under pasted documentation. This guide covers what to put in an instruction file, how to structure it, how to handle several agents at once, a set of real-looking examples, and the anti-patterns that make these files quietly stop working.

Key takeaways

• An instruction file should contain what an agent cannot cheaply discover and would otherwise get wrong: commands, boundaries, conventions, and how to verify work.
• Keep the root file short. Put area-specific rules in nested files next to the code they describe.
• Write rules as specific, checkable instructions ("money is integer cents"), not aspirations ("write clean code").
• If you use several agents, keep one source of truth and make the per-agent files point to it or be generated from it.
• Treat the file as code: review it, update it in the same pull request as the change it describes, and delete rules nobody needs.

Which file does which agent read

Agent	File it reads	Notes
Claude Code	CLAUDE.md	Root file plus files in subdirectories; a personal file in your user config applies to all projects. /init drafts one.
Codex CLI	AGENTS.md	Root and nested files; the file nearest the code is the most specific.
Gemini CLI	GEMINI.md	Loaded hierarchically from user, project, and subdirectory locations.
Other agents	Often AGENTS.md	Check each tool's documentation; many have adopted AGENTS.md as a shared convention.

The formats are all plain Markdown with no required schema. The differences are in file names and lookup rules, not in content.

What belongs in an instruction file

Think of the file as the note you would give a strong contractor on their first morning, written by someone who has watched contractors make the same mistakes. Six sections cover most needs.

1. A one-paragraph orientation

What the repository is and how it is split. Two or three sentences.

2. Commands

The exact commands to install, build, typecheck, lint, and test, including how to run a single test or a single package. This is the highest-value section, because agents verify their work by running these, and a wrong guess costs minutes per attempt.

3. Layout and boundaries

Where the main areas are and which ones must not depend on each other. Skip folders whose purpose is obvious from their name.

4. Conventions that are not enforced by tools

The rules a linter will not catch: integer cents for money, all database access through one module, feature flags read through a helper, error types to use. If a tool enforces it, leave it out.

5. Things not to touch

Generated code, vendored code, migrations, public contracts, and anything requiring another team's review.

6. Definition of done

What the agent should run and report before finishing.

A complete example

# AGENTS.md

Monorepo for the Acme storefront. `apps/web` is the Next.js site,
`apps/api` is a Node API (Fastify), `packages/*` are shared libraries.
pnpm workspaces; Node 20.

## Commands
- Install: `pnpm install`
- Typecheck everything: `pnpm -r typecheck`
- Test one package: `pnpm --filter @acme/cart test`
- Test one file: `pnpm --filter @acme/cart test -- src/totals.test.ts`
- Lint and fix: `pnpm lint --fix`
- Do not run `pnpm e2e` unless asked; it needs a running stack.

## Layout and boundaries
- `packages/cart`: pricing, discounts, totals. Pure functions, no I/O.
- `packages/db`: Drizzle schema and queries. Only `apps/api` may import it.
- `apps/web` talks to the API through `packages/api-client`, never by importing `apps/api`.

## Conventions
- Money is integer cents (`priceCents: number`). Never use floats for currency.
- Dates cross the API as ISO strings; convert with `packages/dates`.
- Errors returned from the API use `ApiError` from `packages/errors`.
- New feature flags go in `packages/flags/src/registry.ts`.

## Do not edit
- `packages/api-client/src/generated/**` (run `pnpm codegen`).
- `packages/db/migrations/**` (run `pnpm --filter @acme/db generate`).

## Before finishing
- Typecheck and test every package you changed.
- List the files you changed and any behavior change for existing callers.

That is around 40 lines and covers most mistakes an agent would make in this repo. Notice there is no description of React, no restated Fastify docs, and no style guide.

Nested files for local rules

A large repository has rules that only matter in one place. Put them next to the code:

# packages/cart/AGENTS.md

- Every exported function must have a table-driven test in `src/*.test.ts`.
- Rounding: use `roundHalfEven` from `src/rounding.ts`. Never `Math.round`.
- Discounts are applied in the order defined in `src/pipeline.ts`; do not reorder.

Nested files keep the root file short and put rules in front of the agent exactly when it is working in that area. They also make ownership natural: the team that owns packages/cart owns its instruction file.

Writing rules that work

Agents follow specific, concrete instructions far more reliably than general guidance. Compare:

Weak	Strong
Write clean, maintainable code.	Keep functions under about 50 lines; extract helpers into the same file.
Be careful with money.	Money is integer cents (priceCents). Never use floats for currency.
Follow our architecture.	apps/web must not import from apps/api or packages/db.
Test your changes.	Run pnpm --filter <pkg> test for each package you changed.
Don't break things.	Before finishing, list callers of every function whose signature changed.

A good test for a rule: could a reviewer check in ten seconds whether the agent followed it? If not, rewrite it.

Explain the reason when a rule looks arbitrary. "Do not reorder discounts; the order is legally required in some regions" stops an agent from "simplifying" it, and helps the human who reads the file later.

Working with several agents

Teams increasingly run more than one agent. Keeping three files in sync by hand will fail. Options, from simplest:

1. One file, references from the others. Keep the content in AGENTS.md and make CLAUDE.md and GEMINI.md short files that tell the agent to read AGENTS.md. Claude Code supports importing other files from CLAUDE.md with an @path reference; check the current documentation for each agent's import support.
2. Symlinks. Point CLAUDE.md and GEMINI.md at AGENTS.md. Simple, but some tools and platforms handle symlinks inconsistently, so test it.
3. Generate. Keep a source file and a small script that writes each agent's file, adding any agent-specific lines. Run it in CI and fail if the outputs are stale.

#!/usr/bin/env bash
# scripts/sync-agent-files.sh
set -euo pipefail
for f in CLAUDE.md GEMINI.md; do
  { echo "<!-- generated from AGENTS.md; edit that file -->"; cat AGENTS.md; } > "$f"
done
git diff --exit-code CLAUDE.md GEMINI.md

Agent-specific content, such as "use the code-graph MCP tools before grep" for an agent that has that server configured, can live in a small per-agent section appended by the script.

Pointing agents at tools

If you have connected an MCP server, the instruction file is where you tell the agent to use it. Without a nudge, agents default to shell search.

## Code navigation
- For definitions, callers, and dependents, use the code-graph MCP tools first.
- Start non-trivial tasks by resolving the task description to files and symbols.
- Read the line ranges returned, not whole files.
- Use grep for config keys, docs, and string literals.

The setup for each agent is covered in our guides for Claude Code, Codex CLI, and Gemini CLI.

Anti-patterns

The pasted manual. Hundreds of lines of framework docs, API references, or a full directory tree. The agent pays for it on every turn and the real rules get lost. Link to docs if you must; do not inline them.

The aspirational file. "We value simplicity, testing, and clean architecture." Nothing an agent can act on.

The stale map. A layout description from before the last reorganization. Agents trust the file over the code more often than you would like. A wrong instruction file is worse than none.

The rule nobody enforces. If reviewers do not check a rule, agents will drift from it and nobody will notice. Either enforce it or delete it.

Secrets and environment details. Instruction files are committed. Never put tokens, internal URLs that should not be shared, or credentials in them.

Duplicating the linter. Formatting and import order belong to tools. Restating them wastes space and can conflict with the actual config.

One giant root file. Area rules for ten packages in one file. Split into nested files.

Prompt-injection-shaped content. Avoid copying text from issues or external sources into instruction files without reading it. Anything in the file is treated as instructions.

Maintaining the file

• Change it with the code. A pull request that moves a module or changes a command updates the instruction file too. Add it to your PR template checklist.
• Review it like code. Instruction file changes deserve the same scrutiny as config changes, because they affect every agent session.
• Learn from failures. When review catches an agent mistake that a rule would have prevented, add the rule. When a rule has not mattered in months, consider removing it.
• Test it with a newcomer. Ask someone new to the repo to read the file and then look at the code. Anything that surprised them is either missing or wrong.

Starting from nothing

If your repo has no instruction file today:

1. Run your agent's init command if it has one (Claude Code has /init) or write a skeleton with the six sections above.
2. Fill in commands first. Verify each one actually works.
3. Add three to five conventions that reviewers most often correct.
4. Add the do-not-edit list.
5. Ship it, then add rules only when a real mistake shows they are needed.

To decide what goes in the layout section, it helps to look at the architecture first. OpenVisio's Explore view shows the module graph and file tree of a repository, which makes it quicker to see which boundaries are worth writing down. The same graph is available to agents over MCP, which covers the structural questions so your instruction file does not have to.

A good instruction file is short, specific, and current. It will not make an agent understand your codebase, but it will stop it from making the same avoidable mistakes on every task.