How to Review and Version Coding Agent Instruction Files

Coding agent instructions need to change with the code they describe. A test command, directory convention, or migration rule may be correct when someone writes it and become misleading after a refactor. Keeping those instructions in version control gives you a history of edits. Keeping them accurate means checking them when the underlying code changes, even when the instruction file itself is absent from the diff.

If you're deciding which files to use, AGENTS.md vs CLAUDE.md vs .cursorrules explains what each agent loads. Once those files are in place, the maintenance question is how to keep their guidance consistent with the repository without turning every pull request into a full audit.

Review instructions when their assumptions change

Suppose an instruction says new API handlers belong in packages/api/src/handlers/. A refactor moves them elsewhere and updates the imports and tests, but leaves the instruction untouched. Passing CI would tell you something useful about the refactor. Unless a check also validates the documented path, it would not tell you whether that guidance is still correct.

The refactor is a good time to update the instruction because the author and reviewer have the relevant implementation in front of them. Keeping both edits in the same pull request also records why the rule changed. For a test command, compare the instruction with the package scripts and CI workflow. For a directory convention, look at the current layout and a recent implementation that follows it. If a rule no longer serves a purpose, remove it.

Cloudflare's coding agents produced plausible but wrong changes when they lacked local repository context. The team introduced AGENTS.md generation and AI-review checks to keep that context current, as our post A stale AGENTS.md is worse than no AGENTS.md covers in detail.

When an agent's output conflicts with a convention, check which instructions it loaded before changing the wording. Missing context, an outdated rule, and a valid rule the agent did not follow need different fixes. The resulting code diff alone may not distinguish them.

Route instruction changes to the team that knows the code

The team maintaining a service is well placed to review instructions about its tests and conventions. CODEOWNERS can route changes to that team, alongside ownership of the source directories. For example:

# Broad patterns first. The last matching pattern wins.
*.md                               @your-org/docs

/AGENTS.md                         @your-org/platform
/CLAUDE.md                         @your-org/platform
/.claude/rules/                    @your-org/platform

/services/payments/                @your-org/payments
/services/payments/AGENTS.md       @your-org/payments
/.cursor/rules/payments.mdc        @your-org/payments

GitHub's documentation states that "the last matching pattern takes the most precedence." Keep broad documentation patterns above the specific entries. Moving *.md @your-org/docs below them would override ownership for matching Markdown files, including AGENTS.md and CLAUDE.md. It would not match a .mdc file.

CODEOWNERS uses the version on the pull request's base branch. It requests reviews for changed files, so an entry for AGENTS.md does not by itself catch a code change that leaves that file stale. Draft pull requests also do not automatically request code owners until marked ready for review. Requiring owner approval before merge is a separate branch protection setting that someone with admin or owner permissions enables.

Check the rule against the implementation and nearby instructions

Useful wording gives the agent a decision it can apply and the reviewer something to verify. "Write clean code" leaves both to interpretation. "New API handlers go in packages/api/src/handlers/" is concrete enough to check, provided that path still reflects the team's convention.

Read the changed rule alongside the other instructions that load for the affected path, including parent-directory files. Claude Code's documentation warns that with contradictory instructions, "Claude may pick one arbitrarily." Resolve the conflict or make the scope explicit rather than assuming the agent will infer which rule you intended.

Temporary rules benefit from a removal condition. In CLAUDE.md, a block-level comment such as <!-- added for the 2026 migration, drop once services/legacy is gone --> gives maintainers a reason to revisit the rule. Claude Code strips these comments when injecting the file into context, though they remain visible when the file is read directly and comments inside code blocks are preserved.

Use code changes to focus maintenance

You don't need to reread every instruction for every change. Start with the assumptions the pull request affects. A directory move calls for checking rules that name the old path. A dependency upgrade may invalidate an API example or configuration flag. A build, test, or deploy change warrants checking the commands agents are told to run. An agent's incorrect pull request comment can also be a reason to trace the guidance it used.

Periodic audits provide another opportunity to find drift. In Claude Code v2.1.283 and later, /doctor prompt-audit proposes fixes for stale or conflicting content without applying them. Its default scope includes CLAUDE.md, CLAUDE.local.md, AGENTS.md, and the rules, skills, commands, subagents, and output styles under .claude/ and ~/.claude/. The audit requires the bundled /claude-api skill to be enabled. The documented default scope does not list .cursor/rules/, so account for those files separately. For other approaches, see Best Tools to Keep AGENTS.md Files Up to Date.

Keep durable guidance separate from session history

Package test commands, migration tools, handler locations, and branch naming conventions are useful candidates for shared instructions. A failed debugging attempt or a flaky run during an incident needs more context before it becomes guidance for future work. Keep those observations in an issue or session record with the date and commit they describe. If a finding proves useful repeatedly, verify it against current code before adding a rule. Team Memory for Coding Agents explores where those records belong.

Keeping the shared guidance focused also makes maintenance more manageable. Claude Code recommends fewer than 200 lines per CLAUDE.md and path-scoped .claude/rules/ for guidance needed only with matching files. The line count is a recommendation, not proof that a file is useful or accurate. A short instruction still needs checking when its assumptions change.

FAQ

Should an instruction change ship in the same pull request as the code?

Yes, when the code change invalidates the instruction. Keeping them together lets reviewers compare the rule with the implementation and preserves the reason for the update in version history. A new convention or an independently discovered correction can have its own pull request.

Can we require a code owner's approval before an instruction file merges?

A CODEOWNERS entry requests the owner's review. Requiring that approval before merge is a branch protection setting that someone with admin or owner permissions enables separately, and it applies to the branch rather than to a single path.

How do we review a repository that has AGENTS.md, CLAUDE.md, and Cursor rules?

Establish which files each agent loads for the affected path, then compare overlapping guidance for conflicts. Loading and precedence depend on the tool. AGENTS.md vs CLAUDE.md vs .cursorrules covers those differences.

Connect instruction maintenance to pull request review

For your next refactor, compare the affected instructions with the code before approving the change. That gives you a concrete starting point for deciding which rules need updating and who should review them.

Dosu supports this workflow by comparing code changes with published Documents and proposing edits when it identifies drift. To try it with an instruction file, an organization admin can create a Dosu Library, add the repository as a Source with Monitor enabled, and import the instruction file as a published Document. Suggested edits appear on the pull request, where your team can accept, edit, or decline them.

Turn off Auto Accept Review if updates should wait for explicit acceptance. To route accepted repository-backed edits through a separate sync pull request, also turn off Commit to Source PR. On that sync pull request, Dosu attempts to request review from the original pull request's author, skipping bot authors. These settings let the team review the proposed instruction change alongside the implementation that prompted it. Self-Documenting PRs are generally available for GitHub today, with support for other code hosts rolling out.