Agent Instructions

Most AI coding tools read project guidance from a file in the repo — historically each looked in a different place (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, …). Copy the same guidance into each one and the copies drift: a command changes in one file and the others keep telling agents the old way. The fix is one canonical source plus thin tool-specific shims (which include the canonical file). Give each durable rule one canonical home: the root core, a linked topic guide, or a nested instruction file. Keep genuine tool-specific quirks in a tool's own file.

The good news: AGENTS.md is now read by nearly every major tool — including GitHub Copilot — so shared guidance can have one maintained source without a per-tool copy.

The canonical file: AGENTS.md

AGENTS.md is the cross-tool standard — a plain-Markdown file at the repo root, read natively by a growing set of agents and editors (Codex, Cursor, Gemini CLI, and GitHub Copilot). Make it the entrypoint for durable, tool-neutral guidance:

• What the project is — one-paragraph purpose, the stack, where the important code lives.
• How to build, test, validate, and run — the exact commands an agent should use (and which one gates a PR). Be specific; agents run these verbatim.
• Conventions — code style, naming, commit/PR format, branch model, "definition of done".
• Do / don't — guardrails (never hand-edit generated files, never push to main, secret handling) and the project's non-obvious gotchas.
• Pointers — links to deeper docs rather than inlining them.

Write it tool-neutral: no "when you are Claude…" assumptions. Anything true only for one tool goes in that tool's file, not here. Keep it readable and scoped: always-loaded guidance consumes context even when most of it is unrelated to the task.

Nested AGENTS.md. In a monorepo or a large sub-package, drop an AGENTS.md in the subdirectory: tools that support the standard read the nearest one and let it take precedence over the root on conflicts. Reach for this before a path-scoped tool-specific file when the guidance is itself tool-neutral.

Keep the always-on file small

Measure bytes as well as lines. Codex's project_doc_max_bytes defaults to 32 KiB (32768 bytes) for the combined project instruction chain. Excess guidance is truncated or omitted; do not rely on an agent noticing missing rules. Leave room for nested files instead of filling the root to the cap. Check the effective configuration and loaded chain in each supported runtime. Codex instruction discovery.

Claude Code recommends under about 200 lines per CLAUDE.md, a readability target rather than the Codex byte limit. @ imports load with their referring file, so splitting the core into imported guides does not save context. Claude Code memory guidance.

Use three scopes, preserving each rule's authority and its trigger:

• Always-on core: the project map, essential commands, universal constraints, and a guide index.
• On-demand guides: detailed procedures needed only for a particular task. Link them normally; each index entry says when to read it, before taking the action it governs.
• Nested AGENTS.md: rules for one directory or product, linked from the core's project map.

For example, the core can contain:

Read each guide before doing the work its row names.

| Guide | Read before |
| --- | --- |
| [Release guide](docs/agent-guides/releases.md) | Preparing or publishing a release |
| [API instructions](src/api/AGENTS.md) | Changing API code |

With Claude Code's default instruction setting, a root CLAUDE.md suppresses native discovery of nested AGENTS.md files. Put a CLAUDE.md containing @AGENTS.md beside each nested file in that layout. Current Claude versions can read AGENTS.md directly when no project CLAUDE.md or CLAUDE.local.md takes precedence; verify the configured behavior before removing shims. Claude discovery and imports.

Run wc -c AGENTS.md and wc -l AGENTS.md as a quick root-file check. For larger repositories, add a small CI check for the chosen budget, the combined supported instruction chains, and missing guide/shim targets. Exercise a representative nested task in each supported tool to confirm it loads the applicable rules. A passing size check alone does not prove discovery or adherence.

Map each tool to its file

Shims need no upkeep. A shim (CLAUDE.md, GEMINI.md) just includes the canonical file, so it never drifts. Everything else reads AGENTS.md directly.

Copilot now reads AGENTS.md

GitHub Copilot used to be the exception that forced a second file — it couldn't read AGENTS.md, so you maintained a .github/copilot-instructions.md. That is no longer true:

• Copilot code review reads AGENTS.md from the repo root (changelog, 2026-06-18).
• Copilot coding agent reads AGENTS.md too (root + nested, nearest-wins).

So AGENTS.md alone now covers Copilot, and a separate .github/copilot-instructions.md is optional, not required:

• Most repos can drop it and rely on AGENTS.md — one canonical file, no subset to keep in sync. Consolidating an existing copilot-instructions.md into AGENTS.md and deleting it is now a legitimate simplification. (It used to silently strip Copilot's guidance, because Copilot couldn't read AGENTS.md; that risk is gone.)
• Keep one only for a concrete reason. Copilot's coding agent treats .github/copilot-instructions.md as always-on context, so a short file there can pin the few rules you want weighted highest. If you keep it, make it a concise subset — short imperative rules, not a copy of AGENTS.md. Brevity is what makes the emphasis work; a long always-on file dilutes it. (Copilot code review's old ~4000-char instruction truncation was removed on 2026-06-12, so length is an emphasis concern now, not a hard limit.)
• Path-scoped rules live in .github/instructions/<area>.instructions.md (with an applyTo: frontmatter glob) — guidance for only part of the tree (tests, infra, a sub-package). Useful with or without a copilot-instructions.md; excludeAgent: "code-review" / "copilot-coding-agent" targets one consumer.

Keep them in sync (definition of done)

Shims (CLAUDE.md/GEMINI.md that @-include) never drift — that's their point. If you keep any hand-maintained second file (a Copilot subset, or a path-scoped .instructions.md), it can drift, so make sync part of done:

A change that touches a command, flag, path, label, generated-file list, validation step, or convention updates every instruction file that referenced it in the same PR — the AGENTS.md canonical text and any subset / path-scoped file.

A stale instruction file is worse than none: it actively misleads every future agent and reviewer. The surest way never to go stale is one canonical home per rule, with no hand-maintained copies.

Recipe: wire up a repo

1. Write AGENTS.md — the small, tool-neutral core and guide index (sections above). Put detailed procedures in linked guides and directory-specific rules in nested instruction files.
2. Add shims for include-capable tools you support:
   • CLAUDE.md → a single line: @AGENTS.md; include nested shims where that layout requires them.
   • GEMINI.md → include AGENTS.md the same way.
3. (Optional) .github/copilot-instructions.md — only if you want a few always-on rules weighted highest for Copilot's coding agent; keep it a concise subset, not a dump of AGENTS.md.
4. (Optional) .github/instructions/<area>.instructions.md with applyTo: globs for rules that apply to only part of the tree (tests, infra, a sub-package).
5. Record the sync rule in AGENTS.md if you kept any hand-maintained second file.
6. Check size and discovery for the root and representative nested instruction chains.

Pitfalls checklist

• ❌ Letting one always-loaded file grow beyond a tool's read limit — measure the combined chain, keep the core small, and route conditional detail through guides with explicit read-before triggers.
• ❌ Importing every guide with @ and calling it on-demand — imports still load eagerly.
• ❌ Assuming a nested AGENTS.md is visible to Claude when a root CLAUDE.md takes precedence — add the nested shim and verify discovery in the supported runtime.
• ❌ Duplicating full AGENTS.md content into CLAUDE.md/GEMINI.md — use a one-line include instead so there is a single source.
• ❌ Keeping a .github/copilot-instructions.md that just duplicates AGENTS.md — now that Copilot reads AGENTS.md, a full copy is pure drift risk; drop it, or trim it to a small focused subset.
• ❌ Putting new canonical guidance in a kept copilot-instructions.md — durable rules belong in AGENTS.md; a subset only re-emphasises a few of them.
• ❌ Letting any kept .github/copilot-instructions.md grow into a parallel rulebook — the old ~4000-char review truncation is gone, but a long always-on file dilutes the emphasis that justified keeping it; split path-specific rules into .instructions.md files.
• ❌ Putting tool-specific assumptions in AGENTS.md — keep it neutral; quirks go in that tool's file.
• ❌ Changing a command/path/convention in AGENTS.md without updating any kept subset in the same PR — that is how the files go stale.