CLAUDE.md Docs: A Drift-Detection Checklist
Keep CLAUDE.md instructions accurate with source checks, documentation drift detection, and a reviewable GitHub workflow.
- claude-md
- documentation-drift
- docs-as-code
- coding-agents
- mcp
A pull request renames test:integration to test:api. CI passes because the workflow changed too. Your onboarding guide still names the old command, and the next coding agent repeats it from CLAUDE.md. The code change shipped; the repository instructions missed the merge.
For claude.md docs, the useful maintenance question is which changes should trigger a review of each instruction. This checklist connects instructions to their evidence, separates agent context from human-facing documentation, and gives you a practical way to detect drift without demanding a documentation rewrite on every pull request.
Start with the drift checklist#
Use this checklist when a pull request changes build commands, test setup, repository conventions, or documented behavior. The paths below are illustrative; substitute your repository’s actual files.
- Find the changed source of truth. Check files such as
package.json,.github/workflows/ci.yml, configuration modules, and behavior tests. - Find instructions that depend on it. Search
CLAUDE.md,AGENTS.md,CONTRIBUTING.md, and relevant pages underdocs/. - Decide which audience needs an update. A changed test command affects agent instructions and contributor docs. A changed retry policy belongs in the behavior guide; the instruction file usually needs only a pointer.
- Verify the replacement against the branch. Run the documented command in a suitable environment or inspect the implementation and its tests. A working link alone proves little.
- Record a review decision. Update the affected documentation in the same pull request, or explain why the existing text remains correct. Keep a human responsible for accepting the change.
Treat this as a review checklist, not a rule that every source change requires a Markdown edit. Renaming a private variable rarely affects documentation. Removing a script that agents are instructed to run does.
The rest of the workflow makes those distinctions explicit enough that reviewers can apply them consistently.
Put each fact in the right place#
Keep one maintained home for each explanation. Instruction files can point to that home without reproducing the whole page. These options have different jobs; you may need several of them in one repository.
Human-facing documentation#
Human-facing documentation explains setup, behavior, tradeoffs, and recovery procedures. Use it when someone needs enough context to make a decision or complete a task without reconstructing the codebase.
Best for: Developer onboarding documentation, architecture explanations, contribution guides, and runbooks.
For example, docs/development/testing.md can explain how to start a local database, create test fixtures, and distinguish a failing assertion from a missing dependency. Give agents a route to that page rather than copying its troubleshooting section into every instruction file.
CLAUDE.md#
CLAUDE.md provides persistent project instructions for Claude Code. Use it for repository-specific commands, constraints, and directions that matter across tasks. Anthropic documents its loading behavior and file imports in How Claude remembers your project. (code.claude.com)
Best for: Teams that use Claude Code and need a maintained entry point to repository conventions.
For example, instruct Claude to inspect package.json before choosing a test command and to consult docs/development/testing.md before integration-test work. Keep the explanation of database fixtures in the guide.
AGENTS.md#
AGENTS.md is an instruction-file option for teams using multiple coding agents. Check each client’s actual support. Current Claude Code documentation describes both direct loading and an explicit @AGENTS.md import from CLAUDE.md; loading depends on configuration and the files present. (code.claude.com)
Best for: Shared repository instructions across clients that support the file.
For example, maintain common test and contribution rules in AGENTS.md, then use a small Claude-specific entry point where necessary. Avoid two independently edited copies of the same commands.
MCP context#
Model Context Protocol, or MCP, connects an AI application to server capabilities. Its primitives include tools and resources; resources can expose read-only context. The official TypeScript SDK documentation describes those distinctions. (ts.sdk.modelcontextprotocol.io)
Best for: Retrieving repository documentation that is too broad or changeable to keep in startup instructions.
For example, an agent can retrieve the webhook behavior guide through a documentation MCP server before changing delivery code. Require evidence about the repository and revision behind the answer. MCP provides access; your workflow still needs to establish freshness.
llms.txt#
llms.txt is a proposed format for giving agents background and links into a documentation website. The proposal describes a concise entry point with detail behind links. (llmstxt.org)
Best for: Helping agents discover published documentation for a library or product.
For example, publish links to your SDK authentication and migration guides. Keep private repository instructions elsewhere. Publishing an index does not verify the accuracy of the pages it references.
Make instructions traceable#
Consider an illustrative TypeScript service with src/webhooks/, API tests under test/api/, and a human-readable webhook guide. Its instruction file should tell an agent how to find reliable evidence and what to do when the evidence disagrees.
A small section might look like this:
## Testing changes
- Inspect package.json for the available test scripts.
- Follow docs/development/testing.md for required services and fixtures.
- For webhook behavior changes, inspect src/webhooks/ and test/api/.
- Review docs/webhooks.md when delivery or retry behavior changes.
- Report conflicts between instructions, tests, and implementation before
changing behavior merely to match a documentation claim.
This is an illustrative template, not a universal convention. A repository with a stable, verified command can list that command directly. The important part is that a reviewer can identify what supports it.
For more fragile instructions, add the reason. “Do not edit generated clients” is easier to maintain when it identifies the generator configuration and the supported regeneration command. “Never touch this directory” gives the next reviewer no basis for deciding whether the restriction still applies.
You can make that relationship explicit in ordinary prose:
## Generated API client
packages/client/src/generated/ is generated output.
Use the generation script declared in packages/client/package.json.
The schema input is api/openapi.yaml.
Review docs/sdk-generation.md when the schema or generator changes.
Avoid treating source paths as permanent guarantees. A path is a dependency that should be checked when files move. The benefit is that the dependency is now visible.
Start with instructions that have caused a failed task: a test command, an unsupported migration path, or a generated-file rule. You don’t need a catalog of every sentence before the workflow becomes useful.
Detect drift from changed evidence#
A practical documentation drift detection system starts with a narrow dependency map. It identifies documentation worth reviewing after a source change. It cannot infer from filenames alone whether the prose is wrong.
The following YAML is an illustrative repository-owned format, not configuration for an existing service:
# docs/context-dependencies.yml
# Illustrative format for a checker your team implements.
rules:
- sources:
- package.json
- .github/workflows/ci.yml
review:
- CLAUDE.md
- AGENTS.md
- docs/development/testing.md
reason: Build and test instructions may have changed.
- sources:
- src/webhooks/
- test/api/webhooks/
review:
- docs/webhooks.md
reason: Delivery behavior may have changed.
Use it as the basis for a small review check rather than a broad semantic gate.
- Compare the pull request with its base. Collect changed paths from the actual base and head commits. Account for renames and deletions. Do not assume the previous commit represents the whole pull request.
- Match paths to review targets. Start with exact files and a few directory prefixes. Report the matching rule and its reason so the author can judge relevance.
- Check mechanical facts. Verify that referenced files exist. Where commands are listed explicitly, check that their scripts still exist and run them in the intended test environment.
- Request a semantic decision. Ask whether the affected explanation or instruction is still accurate. Accept a specific reason for no documentation change.
- Escalate only proven failures. A deleted referenced file can justify a failing check. A changed directory should usually request review until your mapping is precise enough to support a stronger gate.
A useful review note says: “The build configuration changed; review these test instructions.” An unhelpful one says: “Change a docs file to continue.” The latter rewards cosmetic edits and teaches authors to ignore the check.
For a deliberate no-change decision, write something like: “The API test script still runs from the repository root. This pull request changes its internal filtering only.” That gives the reviewer something concrete to verify.
Start this GitHub documentation automation in advisory mode. Inspect its false positives before making it block merges. The surrounding docs-as-code workflow should keep the source change, documentation decision, and reviewer discussion together.
Catch false agreement between documents#
The non-obvious failure mode is agreement between stale documents.
Suppose docs/webhooks.md says delivery stops after three attempts. Someone copies that sentence into CLAUDE.md. Later, an implementation change adds a configurable retry limit. Neither document changes. An agent reads both and sees the same claim twice.
In this illustrative failure, the second document provides no independent evidence. It repeats the first document’s outdated assumption. A review process that checks only whether the documents agree will approve the wrong behavior description.
Prevent that by following claims back to implementation, configuration, and behavior tests. For the retry example, inspect the configuration default, the worker’s stopping condition, and tests for overrides. Also check whether “three attempts” counts the initial delivery. That distinction belongs in the behavior guide because it changes how a developer interprets a failed delivery.
The corresponding instruction can remain small: “Consult the webhook guide and verify retry behavior against the worker and tests before changing delivery logic.” Do not repeat the default unless it genuinely belongs in startup context and you are prepared to maintain it there.
Imports deserve the same scrutiny. Claude Code expands @path imports into context; splitting an instruction file into imports does not by itself reduce the loaded content. (code.claude.com) A large imported guide can preserve duplication while making the entry file appear short.
There is also a branch mismatch to catch. An agent working on a feature branch may retrieve documentation derived from the default branch. The retrieved answer can be accurate for that revision and wrong for the task. Ask which revision supports the claim. If the retrieval system cannot tell you, treat the result as orientation and verify against the checkout.
Test the workflow with a real change#
Before applying this across the repository, choose one maintenance change with an obvious documentation consequence. A renamed test script is a good candidate because you can check the result without debating architecture prose.
- Create a controlled change. On a test branch, rename the script and update its CI invocation. Keep the human guide and instruction file unchanged initially.
- Inspect the review signal. Confirm that the dependency check identifies the relevant documents. It should explain the relationship without claiming it has proved a semantic error.
- Update the maintained explanation. Correct the testing guide. Update an explicit instruction-file command if one exists; otherwise verify that its pointer and directions still work.
- Run a task from a fresh session. Ask the agent to identify the appropriate test command and required setup without editing application code. Inspect the files and commands it actually uses.
- Review and merge deliberately. A human checks the command, the setup instructions, and the documentation diff. A successful agent response is supporting evidence, not permission to skip review.
Also test a no-change case. Modify an internal implementation detail under a mapped directory and confirm that an author can explain why documentation remains accurate. A workflow that catches stale commands but cannot accommodate harmless refactoring will become expensive to maintain.
For developer onboarding documentation, run the same exercise from a clean checkout. Record prerequisites that your existing environment concealed: local services, seed data, environment variables, and credentials supplied through an approved process. Keep secrets out of instruction files and documentation examples.
The acceptance criterion is specific: a developer and an agent should reach the supported procedure from the repository’s entry points, and the reviewer should be able to trace that procedure to the branch under review. Use the separate guide on reviewing AI-generated documentation when the proposed prose needs a deeper claim-by-claim review.
Add maintained context where it helps#
Once the dependency map works, maintaining the underlying explanations becomes the recurring task. This is where Moxie Docs fits: it generates source-backed documentation from GitHub repositories, updates it as code changes, and provides repository context over MCP. Generated documentation, updates on merge, and MCP context are available on every plan. (moxiedocs.com)
An illustrative workflow is to keep concise repository instructions in Git, use maintained documentation for deeper explanations, and let agents retrieve relevant context through MCP. Review retrieved claims against the branch when the task changes behavior. You still need engineering judgment about intended behavior and undocumented constraints.
Start with the free plan if you want to evaluate the generated documentation and MCP context on one repository. Pro and Team add weekly Friday Recap and Cleanup automation. Cleanup PRs propose documentation fixes for human review; they do not merge automatically. (moxiedocs.com)
Evaluate the workflow against a merged change you understand. Check whether the resulting documentation reflects the source, whether an agent can find the relevant explanation, and whether a reviewer can assess any proposed correction. Keep the dependency map and acceptance tests independent of the product so you retain a clear definition of correctness.
The short version#
Choose one instruction that depends on changing code, identify its supporting files, and add a review trigger for those files. Exercise that trigger with a real pull request before expanding coverage. Keep detailed explanations in maintained documentation, make repository instructions point to them, and require a human decision when automation proposes a correction.
FAQ#
Should CLAUDE.md contain all repository documentation?#
Keep it focused on instructions and routes to relevant evidence. Put onboarding explanations, behavior details, and troubleshooting in their maintained guides. Copy a detail only when its value in startup context justifies another place to update.
Should we maintain both CLAUDE.md and AGENTS.md?#
Use both only when your clients or Claude-specific instructions require it. Avoid independent copies. Claude Code documents an explicit import approach, but verify the loading behavior in your installed version and configuration. (code.claude.com)
Can documentation drift detection block every stale claim?#
Design it to catch mechanical failures and request targeted review. Path mappings cannot establish that prose accurately describes behavior. Tests, source inspection, and a reviewer’s understanding remain necessary for that decision.
Does an MCP documentation server replace instruction files?#
Keep a small repository entry point even when deeper context is retrieved. Use it to state conventions, identify relevant documentation, and explain how to handle conflicting evidence. Evaluate retrieved context for repository identity and freshness before relying on it.
Republish or cite this article
You're welcome to republish this piece in full or in part. We just ask that you credit the original with a link back. See our republishing guidelines.
Attribution snippet
<p>This article was originally published on <a href="https://moxiedocs.com/blog/claude-md-docs-drift-detection-checklist">Moxie Docs</a>.</p>Cite this article
The Moxie Docs team. "CLAUDE.md Docs: A Drift-Detection Checklist." Moxie Docs, November 12, 2026, https://moxiedocs.com/blog/claude-md-docs-drift-detection-checklist.
Read next
How to Write the Perfect CLAUDE.md File for Claude Code
Claude Code relies on a CLAUDE.md file for instructions on build, test, and style conventions. Learn how to write, structure, and maintain a perfect CLAUDE.md that keeps your AI agent on track.
AGENTS.md and CLAUDE.md in a Monorepo: Where Instruction Files Go and Which One Wins
Coding agents resolve nested instruction files differently: AGENTS.md uses the closest file, Claude Code stacks every CLAUDE.md from the root down. How to lay out instruction files in a monorepo, what goes at each level, and how to stop them contradicting each other.