AGENTS.md and CLAUDE.md: How to Write a Config File Your Agent Actually Uses

Writing a good config file is the highest-leverage, lowest-effort move in agentic coding. You set the context once and every session benefits: the agent stops guessing your test command, stops reformatting to its own defaults, stops editing the one directory you told it was off-limits. This page is the concrete craft behind the AI-Native "context & configuration" skill — one of the 17 AI-native skills we grade across the levels. Keeping durable project memory in CLAUDE.md / AGENTS.md is a defining signal of a Level 3 Agentic Developer, so this is worth getting right.

The core idea is the same across every tool, even though the mechanics differ: a config file carries the things an agent cannot infer from the code itself. The model already knows your language. It does not know that your tests need a specific flag, that you migrated off a library three months ago, or that infra/ is generated and must never be hand-edited. That gap is what the file fills.

The landscape: one philosophy, many files

Every major agent reads a project context file. They share a philosophy and split on filename and loading mechanics. Here is the map for 2026:

File	Tool(s)	Status
AGENTS.md	OpenAI Codex, Cursor, GitHub Copilot agent, + ~20 tools	Open cross-tool standard
CLAUDE.md	Claude Code	Claude Code's native format
GEMINI.md	Gemini CLI	Gemini's native format
.github/copilot-instructions.md	GitHub Copilot	Copilot's repo instructions
.cursor/rules (formerly .cursorrules)	Cursor	Cursor's rules format

The takeaway: AGENTS.md is the emerging single source of truth — one open spec that ~20 tools already read. The catch is that Claude Code does not read AGENTS.md natively; it only reads CLAUDE.md. So the canonical one-source-of-truth pattern is to keep AGENTS.md canonical and bridge to Claude with a tiny CLAUDE.md that imports it:

@AGENTS.md

<!-- Claude-specific notes can go below -->

A symlink works too (ln -s AGENTS.md CLAUDE.md), but on Windows prefer the @import — symlinks there need admin rights. Now you maintain one file, and both ecosystems read it.

What to actually put in it

GitHub's analysis of over 2,500 repositories ("How to write a great AGENTS.md") found that the configs that measurably help agents share six sections. In rough priority order:

1. Commands — placed early, with exact executable commands and flags (npm test, npm run build, pytest -v), not just tool names. This is the highest-ROI section: agents already know pytest exists; they don't know your project's required flags. Put it near the top.
2. Testing practices — how you test, what to run before committing, coverage expectations.
3. Project structure — where things live, so the agent stops hunting.
4. Code style — show one real code snippet, not three paragraphs of prose.
5. Git workflow — branch naming, commit conventions, PR rules.
6. Boundaries — what the agent must never touch (generated dirs, secrets, vendored code, migrations).

Notice the order of leverage. "Commands with flags" is first for a reason: it's the single thing the model most reliably cannot guess and most frequently gets wrong. If you write nothing else well, write that.

Include / exclude: the line-by-line test

Anthropic's memory docs draw an explicit two-column line. Use it as a filter for every line you're tempted to add.

Include	Exclude
Bash commands the agent can't guess	Anything inferable from the code
Code-style rules that differ from defaults	Standard language conventions the model already knows
Testing instructions / preferred test runner	Detailed API docs (link instead)
Repo etiquette (branch naming, PR conventions)	Frequently-changing info
Project-specific architectural decisions	Long explanations and tutorials
Dev-env quirks (required env vars)	File-by-file codebase descriptions
Non-obvious gotchas	Self-evident practices like "write clean code"

There's one test that collapses the whole table into a habit:

The per-line test: "Would removing this line cause the agent to make mistakes? If not, cut it."

Run that test on every line. "Use TypeScript" — the agent can see the .ts files; cut it. "Run database migrations with npm run db:migrate, never edit migrations/ by hand" — it could not have guessed that, and getting it wrong corrupts state; keep it.

Write it at the right altitude

Anthropic's context-engineering guidance distills good authoring into four principles.

1. Specificity / verifiability. Write rules concrete enough to check against the agent's output. Vague guidance can't be verified, so it can't be followed reliably.

• "Use 2-space indentation" — not "Format code properly."
• "Run npm test before committing" — not "Test your changes."
• "API handlers live in src/api/handlers/" — not "Keep files organized."

2. Right altitude. Aim between brittle hardcoded logic and vague hand-waving: "specific enough to guide behavior, flexible enough to be a strong heuristic." Too rigid and it breaks on the first edge case; too loose and it guides nothing.

3. Minimal-but-sufficient. Minimal does not mean short. It means giving enough context up front so the agent doesn't have to guess or re-discover — and nothing past that. Cut the filler, keep the load-bearing detail.

4. Structure. Use labeled sections — Markdown headers or XML tags. A scannable file is a file the agent (and your teammates) actually parse.

Keep it lean

The real reason to stay lean is the token budget. The config file loads in full every single session. It is not retrieved on demand; it's prepended to context at launch. So bloat has a direct, measured cost: a bloated CLAUDE.md measurably reduces instruction adherence. Anthropic's own framing is blunt — bloated CLAUDE.md files cause Claude to ignore your actual instructions. Every junk line you add makes your good lines weaker.

The targets are concrete:

• Anthropic targets under ~200 lines as a soft goal for CLAUDE.md.
• Codex enforces a hard 32 KiB cap on AGENTS.md (project_doc_max_bytes); oversized files are truncated, so anything past the cap silently doesn't load.

And a trap worth naming: imports do not save budget. An @imported file still loads into context at launch — you've split the file, not shrunk the footprint. To actually reduce what loads every session, offload conditionally-relevant content:

• Path-scoped rules for cross-cutting concerns that touch many files — they load only when the agent works in that path.
• Skills for on-demand procedures — they load only when invoked.
• Links for long or detailed reference material — point to it instead of inlining it.

The principle is the same one the per-line test enforces, applied at the section level: if it's only sometimes relevant, it shouldn't be in the always-loaded file.

DESIGN.md: a team convention, not a standard

A DESIGN.md is the textbook application of "keep the config lean, link the detail." It's a separate design/architecture doc — the key decisions, the domain model, the architectural patterns, the why it's built this way — that your AGENTS.md @imports or references instead of inlining. That keeps the always-loaded config short while the deep context stays one hop away.

Be honest about its status, though: unlike AGENTS.md and CLAUDE.md, there is no primary source establishing DESIGN.md as a standard agent-config file. It's a powerful team convention, not a documented standard. Use it because it works for your team, not because a spec mandates it.

Scope & hierarchy

Both ecosystems layer files from broad to specific, but they resolve precedence differently.

CLAUDE.md has four scopes, loading broad → specific:

1. Managed policy — set by your org / IT, applies organization-wide.
2. User — ~/.claude/CLAUDE.md, applies across all your projects.
3. Project — ./CLAUDE.md, checked into git and shared with the team.
4. Local — ./CLAUDE.local.md, gitignored, for your personal overrides.

In monorepos, parent-directory files auto-load and child-directory files load on demand. Imports use the @path/to/file syntax (relative or absolute), nest up to 4 hops deep, and the parser skips code blocks so a path inside a fenced block isn't treated as an import.

AGENTS.md resolves closest-wins. Codex walks from the Git root down to your current working directory and concatenates the files it finds, root-first. Because closer files appear later, they override — closest file wins. In a monorepo you keep one AGENTS.md per package, and the one nearest the code being edited takes precedence. Above all of it: an explicit instruction in chat overrides every file.

And the cross-tool bridge from earlier ties the two systems together: keep AGENTS.md canonical, add a CLAUDE.md that does @AGENTS.md, and your hierarchy is shared across tools without duplication.

Advisory, not enforcement

Here's the nuance that saves you from a false sense of safety: these files are advisory context, not deterministic enforcement. They steer the agent; they don't bind it.

Emphasis words like IMPORTANT and YOU MUST measurably improve adherence — but they do not guarantee it. For requirements that must happen every single time (run the formatter, block a commit that fails tests, never write to main), the deterministic backstop is hooks (in Claude Code), not stronger wording in the config.

The rule of thumb: use the config for guidance and heuristics; reach for hooks the moment "the agent usually does this" isn't good enough and you need "the agent always does this."

Maintain it like code

A config file is a living artifact, not a one-time write. Treat it the way you treat the rest of the repo.

• Bootstrap with /init. Let the tool generate a first draft from your codebase, then refine it by hand — the generated version is a starting point, not the finished file.
• Review when things go wrong. Every time the agent does something dumb, ask whether a missing or misleading line in the config caused it.
• Prune regularly. Re-run the per-line test on the whole file. Lines that were load-bearing last quarter may be dead weight now.
• Test changes by behavior. Don't trust that an edit helped — observe whether the agent's behavior actually shifted. If you can't see the difference, the line probably isn't doing work.
• Check it into git. A shared, version-controlled config means the whole team contributes and benefits, and changes show up in review.

The most valuable habit is the self-improving loop: when the agent makes a mistake, add a single one-line rule so it doesn't repeat. Over a few weeks that loop converges your config on exactly the gotchas your project actually has — nothing more, nothing less.

A starter AGENTS.md

Here's a real, copy-paste skeleton with all six high-ROI sections filled with realistic placeholders. Swap in your specifics and delete anything that doesn't earn its place under the per-line test.

# AGENTS.md

## Commands
- Install: `npm ci`
- Dev server: `npm run dev`
- Test (all): `npm test`
- Test (single file): `npm test -- path/to/file.test.ts`
- Lint + autofix: `npm run lint -- --fix`
- Typecheck: `npm run typecheck`
- Build: `npm run build`

## Testing
- Run `npm test` and `npm run typecheck` before every commit.
- New code needs a test in the matching `*.test.ts` file.
- Integration tests need a running DB: `npm run db:up` first.

## Project structure
- `src/api/handlers/` — HTTP route handlers
- `src/services/` — business logic (no HTTP/DB code here)
- `src/db/` — schema + queries; migrations in `src/db/migrations/`
- `web/` — React frontend (separate AGENTS.md inside)

## Code style
- 2-space indentation, single quotes, no default exports.
- Throw typed errors from `src/errors.ts`, never bare `Error`.
```ts
// Good: typed error, narrow return
export async function getUser(id: string): Promise<User> {
  const user = await db.users.find(id);
  if (!user) throw new NotFoundError('user', id);
  return user;
}

Git workflow

• Branch from main: feature/<short-desc> or fix/<short-desc>.
• Conventional Commits (feat:, fix:, chore:).
• Open a PR; never push directly to main.

Boundaries

• NEVER edit src/db/migrations/ by hand — generate with npm run db:migrate:new.
• NEVER touch dist/, node_modules/, or *.generated.ts (all generated).
• NEVER commit secrets; required env vars are documented in .env.example.

For a single source of truth across tools, drop a one-line `CLAUDE.md` next to it containing `@AGENTS.md`, and link your deeper architecture notes (a `DESIGN.md`, your ADRs) rather than pasting them in.

## Where to go next

A lean, specific config file is one of the concrete behaviors that separates AI-assisted developers from genuinely AI-native ones. [Find your AI-native level](/quiz) in three minutes — it grades exactly this kind of craft — and when you're ready to wire up your toolchain, start from [the recommended ProCoders stack](/stack).

> **Related:** [the anatomy of a compound system](/compound-v/system) shows how ProCoders' Compound V assembles these ideas into a real, reviewed multi-agent workflow.