I no longer treat AGENTS.md, CLAUDE.md, or Copilot instruction files as onboarding notes. They are part of the execution environment for coding agents. When they are precise, they shorten exploration and make reviews less surprising. When they drift, they quietly teach agents the wrong workflow at scale.
That matters because instruction files are no longer a niche convention. AGENTS.md is now presented as a shared Markdown format for coding agents, GitHub Copilot supports repository-wide, path-specific, and agent instructions, and Claude Code has its own CLAUDE.md memory model. The practical question is not whether to add one. It is how to keep it from becoming another stale README with more blast radius.
The evidence is mixed, which is the point
Two recent papers make the same engineering point from different directions. One study of 15,549 agentic pull requests across 148 projects found that instruction files did not automatically improve outcomes. After instructions appeared, 27.7 percent of projects improved merge rate by at least 20 percent, while 26.35 percent got worse. Longer, better structured files seemed more common in projects that improved, but the headline is simple: the file itself is not magic.
A second paper focused on configuration smells in AGENTS.md and CLAUDE.md files. In 100 popular repositories, it found lint leakage in 62 percent of files, context bloat in 42 percent, and skill leakage in 35 percent. Those labels match what I see in real repos. Instructions start as helpful shortcuts, then accumulate generic lint advice, duplicated product context, old command names, and tool-specific rituals that no longer apply.
That is why I prefer to review these files like production code. They change agent behavior, so they need ownership, scope, and tests.
Review the loading model first
Before arguing over wording, I want to know which agent will actually read which file.
GitHub Copilot now distinguishes three instruction surfaces. Repository-wide guidance lives in .github/copilot-instructions.md. Path-specific instructions live under .github/instructions as NAME.instructions.md. Agent instructions can use AGENTS.md, with the nearest file in the directory tree taking precedence. A root CLAUDE.md or GEMINI.md can also be used as a single-file fallback.
Claude Code is different. It reads CLAUDE.md, not AGENTS.md. Its docs recommend importing AGENTS.md from CLAUDE.md when a repo already uses AGENTS.md, which keeps shared rules in one place while leaving room for Claude-specific notes. Claude also states a boundary that every team should internalize: memory files are context, not enforcement. If a rule must block a tool call or command, use a hook or managed setting, not prose.
That distinction should shape the review. If a repo has AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, and path rules, the first task is a small precedence map. Which file applies to apps/cms? Which applies to database migrations? Which one wins if a chat prompt says the opposite? Without that map, reviewers are editing vibes.
Cut bloat by separating facts from procedures
My rule of thumb is that a top-level instruction file should answer four questions:
| Section | Keep | Move elsewhere |
|---|---|---|
| Repo shape | Apps, packages, ownership boundaries | Full architecture history |
| Commands | Verified build, lint, test, and local run paths | Every optional script |
| Conventions | Non-obvious rules that prevent bad diffs | Generic style advice the formatter enforces |
| Safety | Secrets, migrations, destructive commands, publish steps | Tool-specific reminders that change weekly |
The dangerous pattern is a 400-line file that mixes all of these with historical debugging notes. It feels comprehensive, but it spends context on material the agent does not need in every task. Claude recommends keeping CLAUDE.md under 200 lines, which is a good forcing function even if your primary agent is not Claude. If something is only relevant to one package, make it path scoped or nested. If it is a multi-step workflow, make it a separate runbook and link it only when the agent must use it.
This is the same lesson I argued in my rollout rules for CLI coding agents: adoption is not the hard part. Keeping the operating model inspectable is the hard part.
Add tests for instructions, not just code
Instructions should have acceptance checks. I do not mean a grand framework. I mean a small review ritual every time the file changes.
First, ask whether each command still runs from the location the file implies. If the instruction says pnpm build, verify whether the repo requires install, environment variables, or a package filter first. GitHub's own guidance for generating Copilot instructions explicitly asks the agent to validate build and test commands, document preconditions, and avoid task-specific advice. That is exactly the bar I want humans to apply before merging instruction changes.
Second, run a conflict scan. Search for repeated words like always, never, must, npm, pnpm, yarn, main, master, migration, deploy, and test. Conflicting hard rules are worse than missing rules because agents often choose one without telling you which assumption won.
Third, do a token budget pass. If a sentence restates something every developer already knows, remove it. If a sentence prevents a real recurring mistake, keep it. If a sentence only applies to one agent, label it or move it to that agent's file.
Fourth, add an expiry rule for temporary constraints. A line like “skip Playwright because CI is flaky” can survive for months and train every agent to avoid the one check you needed fixed. If the instruction is a workaround, give it an owner or a removal condition.
Use prose for guidance, controls for policy
Instruction files are excellent for steering. They are weak policy controls.
That boundary matters more as agents gain tools, MCP servers, remote sessions, and long-running task queues. I recently wrote about governing remote MCP servers, and the same principle applies here: do not rely on friendly text to enforce a security boundary. Prose can tell an agent to avoid destructive commands. A permissions layer, hook, sandbox, or database role is what actually limits damage.
So I split rules into two buckets during review. Behavioral guidance belongs in Markdown: prefer existing components, run the focused test first, stage commits by logical group. Enforcement belongs in tooling: deny commands, require approvals, restrict secrets, block network access, or scope credentials.
The best instruction files feel boring. They are short, concrete, scoped, and maintained by people who understand the repo. That is the goal. Not a universal agent manifesto, but a small operational contract that makes the next agent's first ten minutes better and its final diff easier to trust.