Adding AGENTS.md or CLAUDE.md to one repository usually isn’t difficult. An agent needs to know how the project builds, how tests run, which directories are generated and which local conventions aren’t obvious from reading the code.
Put that somewhere predictable and the agent has less to rediscover every time it starts work. The bigger issue appears once dozens or hundreds of repositories have their own version. An authentication pattern changes centrally yet older instructions survive in repositories nobody remembers to update.
One team copies another team’s file and gradually edits it independently. Architecture documentation moves on while the agent instructions keep pointing at an earlier design because nothing has failed loudly enough to force anyone back into the file.
What AGENTS.md and CLAUDE.md should actually contain
AGENTS.md gives coding agents a predictable place to find repository-specific instructions such as setup commands, testing guidance and local conventions. Nested files can also give one part of a large repository different guidance from another.
CLAUDE.md fills a similar role for Claude Code. Anthropic recommends using it for project context such as architecture, commands and conventions, with instructions available at different scopes inside a project.
AGENTS.md is designed as a cross-agent format, while CLAUDE.md remains Claude Code's native project-instruction file. Recent Claude Code versions can also load AGENTS.md, depending on the project configuration, so teams using several coding agents increasingly have options for sharing the same underlying guidance rather than maintaining completely separate copies.
Perhaps the test command is unusual or database migrations have to go through a particular workflow. None of those are difficult instructions, but the agent still has to find them somewhere.
An architecture handbook, generic coding advice and instructions that only apply to today’s ticket are all different kinds of material. Put all of that in the same file and you soon have repository notes, company policy and ticket-specific instructions being maintained together.
An observability task doesn’t need evaluator methodology occupying context before it becomes relevant. That’s become a useful rule for us more broadly: keep the always-loaded context small, then make deeper knowledge easy for the agent to find when the task actually needs it.
One 2026 evaluation found repository context files tended to reduce task success while increasing inference cost by more than 20%. Agents were generally following the extra instructions, which often meant more exploration and more testing without a corresponding improvement in results.
Keeping standards consistent across 200 repositories
A single central file sounds attractive until repositories start needing different things.
If the company changes its approved authentication pattern, asking engineers to search 200 repositories for copied instructions obviously doesn’t scale. Keeping that standard centrally is sensible. An integration-test command used by one service belongs much closer to the service itself.
We don’t think consistency means forcing every repository to carry identical instructions. The useful goal is to keep the shared standard authoritative while making local differences explicit rather than letting them emerge through copied files.
A platform convention might apply to twenty services rather than the entire company, one repository may have a legitimate exception, and another team could be halfway through a migration with both an old internal library and its replacement still in active use.
Trying to remove every duplicate creates its own problems. Sometimes a small local instruction is easier to understand than a rule inherited from several teams away. What matters more is knowing which version wins when local and central guidance disagree.
One engineering standard may need to reach Claude Code, Cursor, Gemini CLI and whatever the team adopts next year. Rewriting the organisation’s engineering knowledge every time the interface changes turns tool choice into a documentation project.
Whoever owns the shared instruction still needs to know which repositories inherit it and where teams override it. Otherwise you can update the central file and still have repositories behaving differently.
When a standard no longer belongs in Markdown
Instruction files have a habit of collecting warnings because adding another sentence is easy.
An agent imports directly from a persistence layer the architecture team doesn’t want application code to use, so someone adds a note explaining the preferred boundary. Another mistake leads to stronger wording, then examples, then exceptions. Before long, several paragraphs are describing something the repository may already know how to reject mechanically.
OpenAI moved important architectural invariants in its Codex-heavy codebase into custom linters and structural tests rather than relying on documentation alone. Whether a rule still needs judgement is a useful dividing line you can use.
“Prefer this internal abstraction” can stay as guidance if exceptions are legitimate. If code in one layer is never allowed to depend on another, enforce it.
Our rule of thumb is that instructions are for things an agent still needs to interpret. Once a boundary can be checked mechanically and shouldn’t have exceptions, leaving it in Markdown is weaker than it needs to be.
That’s also where a Software Factory starts to matter more than the instruction file itself. Guidance can shape how an agent works, while linters, tests, policies and approval gates can enforce the boundaries the run isn’t allowed to negotiate.
A migration note might describe work completed six months ago and another line may duplicate a linter that now catches the problem automatically. Other instructions remain valuable precisely because they describe local knowledge that can’t be reduced to a deterministic check.
Without regular removal, AGENTS.md gradually turns into a history of every concern the repository has ever had. Each addition looked sensible on its own yet the accumulated file becomes harder for both engineers and agents to understand.
If you want to see how Orq.ai helps teams keep agent guidance, skills and enforcement consistent across repositories, book a demo.
