AGENTS.md and CLAUDE.md best practices: one instruction file for every coding agent

The AGENTS.md format (“a README for agents”) is used by over 60,000 open-source projects and read by more than 20 tools, including OpenAI’s Codex, Cursor, VS Code, and GitHub Copilot. At one agent session per repository per day, a conservative rate for an active project, that works out to 60,000 machine readings of the format daily, each one delivered to a model as trusted instructions. Claude Code reads its own CLAUDE.md, and the two formats are similar enough that the right approach is maintaining one file rather than two.

I have been iterating on these files daily across several repositories for over a year. What follows is the guidance the official documentation specifies, together with the maintenance lessons that the documentation only hints at.

One source of truth: wiring AGENTS.md and CLAUDE.md together

If a repository serves multiple agents, duplicating instructions across two files invites drift. Anthropic’s docs are explicit about the interop pattern: “Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it.”

<!-- CLAUDE.md -->
@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

The @path import loads AGENTS.md at session start, and anything below the import is Claude-specific. A symlink (ln -s AGENTS.md CLAUDE.md) also works when there is nothing tool-specific to add; on Windows, however, symlinks require Administrator rights, so the import is the more portable choice.

Two details about imports matter for the size discussion below. Firstly, imports recurse (a file can import another) to a maximum depth of four hops. It should be noted that imported files still load at launch; splitting a bloated file into imports organizes it without reducing context cost. Secondly, import parsing skips code spans: writing @README in backticks mentions a path without importing it. I learned this by accidentally importing a README into every session for a week.

For a fresh repository, Claude Code’s /init generates a starter file by analyzing the codebase, and if an AGENTS.md already exists, it reads and incorporates it, along with other tools’ configs such as .cursorrules and .windsurfrules.

What belongs in the file

The AGENTS.md spec suggests sections: project overview, build and test commands, code style, testing instructions, security considerations. That skeleton is sound; the harder question is the filter, and here Anthropic’s guidance provides the most useful test I have found. For each line, ask “Would removing this cause Claude to make mistakes?” If not, cut it.

From a year of pruning my own files, the content that earns its place:

• Build/test/lint commands the agent can’t guess, including the flags (“run single tests, not the whole suite”)
• Facts that contradict defaults or appearances (“this endpoint 308-redirects and drops the POST body”, “the dev DB is NOT on the default port”)
• Repository etiquette: branch naming, commit format, what must never be committed
• Architecture decisions invisible from any single file (“all writes go through the queue, never direct to the table”)
• The workflow gates: “every entry ships via PR”, “always run X before claiming done”

The content that gets cut:

• Anything derivable by reading the code: the agent will read the code
• Standard conventions (“write tests”, “handle errors”): the model already knows
• API documentation, link it instead
• Anything that changes weekly: it will rot, and a wrong instruction is worse than none

Rot is the reason for that last cut. These files are trusted implicitly, so a stale instruction (“tests live in spec/” after the tests moved) produces confident wrong behavior, which is harder to debug than no instruction at all. Treat the file like code: review it when the agent misbehaves, and prune on every touch.

Size discipline: the 200-line rule

Anthropic’s docs give a concrete target: “target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.” The best-practices guide is more direct: “Bloated CLAUDE.md files cause Claude to ignore your actual instructions!”

This matches my experience, and it produces a counterintuitive maintenance rule: when an agent violates a written rule, the fix is usually deleting other rules, not emphasizing the violated one. Adherence is a budget; every line spends from it. My most reliable instruction file is also my shortest.

When content genuinely exceeds the budget, three mechanisms relieve it. (1) Path-scoped rules: .claude/rules/*.md files with paths: frontmatter load only when the agent touches matching files:

---
paths:
  - "src/api/**/*.ts"
---
# API rules
- All endpoints must include input validation

This is the only mechanism that actually reduces startup context; unconditional rules and imports all load at launch. (2) Skills: multi-step procedures (“how we do a release”) load on demand when invoked, costing nothing in sessions that do not need them. (3) HTML comments: <!-- maintainer notes --> are stripped before the content reaches the model, so annotations for humans carry no context cost.

Placement and precedence

Claude Code resolves instruction files by walking up the directory tree from the working directory, loading every CLAUDE.md and CLAUDE.local.md it finds, ordered “from the filesystem root down to your working directory”; everything concatenates rather than overriding. Files in subdirectories load lazily, only when the agent reads files there.

The full scope ladder, broadest first:

Scope	Location	Shared with
Managed policy	/Library/Application Support/ClaudeCode/ (macOS) etc.	whole org, can’t be excluded
User	~/.claude/CLAUDE.md	you, all projects
Project	./CLAUDE.md or ./.claude/CLAUDE.md	team, via git
Local	./CLAUDE.local.md (gitignored)	you, this project

Two consequences of this ladder come up constantly in my own setup. Personal quirks belong in user or local scope, never project scope; sandbox URLs do not belong in a teammate’s context. Monorepos work best with per-package files and a lean root: the root file holds what is true everywhere, and each package’s file loads only when the agent works there. If another team’s instructions pollute your sessions, claudeMdExcludes in settings skips them by glob. In addition, instructions closest to the working directory are read last, which is useful when a subproject needs to sharpen a root-level rule.

One caveat for multi-tool monorepos: the AGENTS.md spec is deliberately minimal and does not standardize nested-file precedence, so each tool decides how, or whether, to handle nesting. A toolchain that relies on nested instruction files therefore needs each agent verified against them individually.

Advisory instructions versus enforced configuration

The docs draw a line that took me several incidents to absorb: instruction files are “context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.” CLAUDE.md content arrives as a message the model reads and usually follows; under context pressure, “usually” fails.

My working split, refined through those failures, is that taste goes in the instruction file and safety goes in hooks and CI (continuous integration). Naming, style, and preferred patterns are taste, and violations there are cheap. “Never push to main”, “never touch the migrations folder”, and “this scan must pass before publish” are safety, and violations there are expensive, so they get deterministic enforcement, which a hook or CI script applies identically whether the context window is nearly empty or nearly full.

Every hook in my repositories exists because an advisory rule failed at least once. I cover this split in more depth in agentic coding best practices.

Maintenance: when to add, when to delete

Anthropic’s docs give the cleanest trigger list for adding that I have seen. Add an instruction when (1) the agent “makes the same mistake a second time”, (2) “you type the same correction… that you typed last session”, (3) a code review catches something the agent should have known, or (4) a new teammate would need the same context.

The symmetric trigger list for deleting, which nobody writes down, has held up equally well in my files. Delete a line when (1) the agent already behaves correctly without it (test by removing it), (2) it duplicates what the model knows anyway, (3) nobody remembers why it is there (git blame it; if the incident is fixed elsewhere, cut it), or (4) it is a multi-step procedure that should be a skill.

One operational note: project-root instruction files survive context compaction. After a long session compacts, Claude re-reads the root file from disk; conversation-only instructions do not survive. A correction made mid-session that still matters tomorrow therefore belongs in the file, not the chat.

A minimal skeleton that has held up

Distilled from the files I run (structure per the AGENTS.md spec, filters per the sections above):

# Project name: one line on what it is

## Commands
- build: `...`   test: `...` (single test: `...`)   lint: `...`

## Non-obvious facts
- 2-4 bullets: the things that WILL cause mistakes if unknown

## Rules
- The 3-5 rules with real consequences (each backed by a hook/CI
  gate if violation is expensive)

## Structure
- 3-5 bullets: where things live, only where non-obvious

In my files, twenty lines that each pass the removal test have produced better adherence than two hundred lines that do not. For what tool access to give agents once the instructions are right, see the MCP (Model Context Protocol) servers that earn their context cost.

TODO (July 2026): the adherence-versus-length claim above rests on my accumulated impressions, not on a controlled comparison. The test I plan to run: take the longest CLAUDE.md I maintain, prepare a cut under one third of its length, run the same scripted set of twenty tasks against both versions, and count violations of the five rules present in both files. If the counts come out close, the 200-line target is looser than its wording suggests; if the short file wins clearly, the deletion triggers above get promoted from advice to standing procedure.

---

Changelog: 2026-07-06: sourced the import-depth figure, de-aphorized the enforcement close, replaced an em-dash in the skeleton. 2026-07-05: rewritten in the house register; facts, sources, and structure unchanged. 2026-06-19: first published.