Who maintains your Claude Code instructions, and how to tell they still help

How instruction files go wrong

Without an owner, a CLAUDE.md tends to drift the same way: review findings and incidents add lines, nobody removes any, and the file collects commands that were renamed, rules that contradict each other and workarounds for limits an older model had. Claude Code's documentation is specific about the cost: files over 200 lines consume more context and reduce adherence, and when two instructions contradict each other Claude may pick one arbitrarily.

The fix is ownership and a routine that removes entries, not a better template. Anthropic's guidance on context engineering recommends the smallest set of instructions that fully describes the expected behaviour, starting minimal and adding only for failure modes found in testing.

Who owns which file

Claude Code loads instructions from several scopes, and each needs a different owner. Claude Code's guide to large codebases says each directory's owner typically maintains its file, which can follow the code ownership you already have.

• Managed CLAUDE.md, deployed to every machine: the platform or security team, for organisation-wide guidance. Rules that must hold go into managed settings, because the file guides and does not enforce.
• Root CLAUDE.md or AGENTS.md: the team that owns the repository's build and conventions, usually platform or the tech lead.
• Package CLAUDE.md files and .claude/rules with paths: the team that owns that code, enforced through CODEOWNERS.
• CLAUDE.local.md and ~/.claude/CLAUDE.md: the individual engineer. These are not reviewed, so they must not carry team rules.
• Auto memory: written by Claude, stored per repository on one machine and not shared. Anything the team relies on belongs in a reviewed file instead.

Record why each entry exists

An entry nobody can explain is never removed. Claude Code strips block-level HTML comments from CLAUDE.md before the content reaches the model, so maintainer notes cost no context. We use them for the owner, the reason and how to check that the entry still works.

<!-- owner: @example-org/billing | added 2026-08 after review findings on float maths | check: billing replay tasks -->
- Represent amounts with the Money type in src/billing/money.ts. Never use floating point for money.

<!-- owner: @example-org/billing | added 2026-05 | revisit after the next model change -->
- Integration tests need `docker compose up db` before `pnpm test:integration`.

A review routine that removes as much as it adds

1. 1

   Review every edit like documentation

   Changes to instruction files go through pull requests with the file's code owner as a required reviewer, including changes Claude proposes itself.

2. 2

   Run an audit at a fixed interval

   Claude Code's /doctor prompt-audit, available from v2.1.283, reports references to missing files or commands, instructions written for older models and contradictions, and changes nothing until you approve the edits.

3. 3

   Revisit after model changes

   The large-codebase guide notes that instructions written around an older model's limitation can become overhead once a newer model handles the case on its own.

4. 4

   Check what actually loads

   Run /context to see which memory files loaded, and use an InstructionsLoaded hook to log when path rules and nested files load.

Testing whether an entry still helps

For entries that matter, run a small comparison. In a hypothetical billing package, take five past tasks that touch amounts and run each three times with the Money entry and three times without it, each run in an isolated copy whose history ends before the original change, with no later refs, auto memory or files from earlier runs. A script checks each diff for floating point arithmetic on amounts. Include tasks where the rule should not change anything, since Anthropic's evaluation guidance warns that one-sided test sets push behaviour in one direction.

Retire or move an entry when one of these holds:

• Runs with and without it behave the same, so the model already does it or ignores it.
• It names files or commands that no longer exist.
• A linter, hook or CI check enforces the same thing, which is stronger than a sentence.
• It matters for one area only, so it belongs in a path rule or a skill that loads on demand.

Where training fits

Ownership fails if engineers do not know when to add an entry. Claude Code's documentation gives a usable test: add one when Claude makes the same mistake twice, when review catches something Claude should have known, or when you type the same correction again. We practise exactly that in team training on your own repositories, after the ownership and review routine are in place.

Claude Code trainingControlling what context an agent carries