Does your CLAUDE.md match the real project?

A CLAUDE.md is a set of claims about a project: these commands work, these paths exist, these things must never be done, this is what finished means. Projects move; the file does not move with them unless someone makes it. A file that says npm test when the project switched to pnpm costs the agent a turn; a file that prohibits editing a directory that no longer exists teaches it that the rules are decorative. This week: read yours as an auditor, run what it says, and cut what is no longer true.

The problem

The file is read by the agent at the start of every session and trusted completely. Drift is invisible from inside a session: the agent does not know the command it was told to run has been renamed; it runs it, it fails, it guesses. Every stale line is a small tax on every task, and every rule the agent sees ignored (because the thing it prohibits cannot happen any more) lowers the weight of the rules that matter.

Prerequisites

• A project with a CLAUDE.md (or AGENTS.md) that has existed for more than a month.
• A shell in that project and the ability to run its commands.
• A scratch branch you can throw away.

Scope

One file, its imports, and the rules in it. The exercise is verification, then pruning. Adding new rules is out of scope this week — the point is to find out what is no longer true, not to write more things that might stop being true.

Safe inspection workflow

1. Run every command as written. Copy each command out of the file and run it. It works, or it does not. For each failure, find the current command and fix the line — or delete the line if the command is gone for good.
2. Check every path and name. Directories, files, tools, versions, environment names. ls each path. A mention of src/legacy/ when there is no such directory is a line to delete.
3. Read every prohibition and ask “can this still happen?” “Never edit the parent theme” in a project that no longer has one is noise. “Never write to the production database” in a project that still can is the most important line in the file. Keep the second kind; delete the first.
4. Test one rule. On a scratch branch, ask the agent to do the prohibited thing — plainly, as a user might by accident. Record what happened: it refused with a reason, it asked, or it did it. A rule that is not followed needs to be moved from prose to enforcement (a hook, a settings deny rule, a pre-commit check). See the guide's section on rules that get followed.
5. Check the definition of done. Does the file say what must be true before a task is finished? If it does, is it still what you want? If it does not, this is the one addition allowed this week: one line, in your words.
6. Measure. Line count before and after. Shorter is the usual outcome. If it is not shorter, write down why in the commit message.

Copyable prompt

Ask the agent to audit its own instructions. It reads and runs check commands; it does not edit the file — the edits are yours, because the file is a statement of what you want.

Audit CLAUDE.md (and any files it imports with @) against the repository as it is today. Do not edit CLAUDE.md or any other file.

1. Commands: extract every command the file tells you to run. Run each one exactly as written (read-only commands and test/lint/build commands are fine; skip anything that deploys, publishes, or writes outside the working tree, and say so). Report: command · exit status · first line of output or error.
2. Paths and names: for every file path, directory, tool or version the file mentions, check whether it exists in the repository or on this machine. Report each as present / missing / different.
3. Prohibitions: list each "do not" / "never" rule and say whether the thing it prohibits is still possible in this project, with one line of evidence.
4. Definition of done: quote what the file says must be true before a task is finished, or say that it does not say.
5. Length: line count, and which sections could be removed without losing a rule that is still true.
Output a table per section. Do not propose new rules; report what is stale.

Example evidence

An example written for this page.

Weekly Fix #4 — CLAUDE.md audit — 2026-10-08 — repo: shop-theme
Commands: 6 run · 4 ok · 2 fixed (npm test → npm run test:unit; theme check path)
Paths: 9 checked · 1 missing (sections/legacy-hero.liquid — removed in June; line deleted)
Prohibitions: 5 · 4 still apply · 1 stale ("never edit assets/vendor.js" — file gone; deleted)
Rule test: asked "push this to the live theme" on scratch branch → agent refused, cited the rule, offered the dev theme ✔
Definition of done: present; kept
Length: 142 → 118 lines
Commit: "CLAUDE.md: remove stale paths and one dead rule; fix test command"

Completion criteria

• Every command in CLAUDE.md was run as written and either worked or was corrected.
• Every path, file name and tool version it mentions exists today.
• Every prohibition still describes something the project needs prohibited; stale ones removed.
• One rule was tested on a scratch branch and the outcome recorded.
• The file is shorter, or the same length with a reason.

Common mistakes

• Reading instead of running. A command looks right until it is executed.
• Adding while auditing. Every addition is a future stale line. This week removes.
• Keeping rules for sentiment. “Never touch the old checkout” from a project that replaced its checkout is history, not a rule.
• Testing a rule with a hint. Ask for the prohibited thing the way a distracted user would, not with “I know this is against the rules, but”.

Go further

• A production CLAUDE.md for web development covers what belongs in the file, why length is the main failure mode, and how to write a rule that gets followed — with a generator for a project-specific section.
• The Website Operations Lab is the same discipline applied to a health report: verify before you act.