Treat CLAUDE.md like a migration script, not a README

A developer argues that agent instruction files like CLAUDE.md, AGENTS.md and .cursorrules should be treated as runtime configuration rather than human-facing documentation, because agents read them as ground truth instead of cross-checking them. The writeup recommends reviewing instruction-file diffs as their own PRs, smoke-checking paths and commands after refactors, and pointing agents at live spec files instead of pasting API contract snapshots that drift. The author cites Powerduck, a local-first OpenAPI studio, as the approach of keeping the spec as a file on disk the agent re-reads each run.

I opened CLAUDE.md last week to ask an agent to fix a payments bug, and the first section described a folder layout we refactored away three sprints ago. The api/ directory that section kept pointing at is now packages/payments/ . The agent didn't notice. It built a plan around the old path, couldn't find the file, then started "adjusting" the test to match what it thought the code should do. That's the failure mode nobody tells you about when they show off their shiny agentic setup. Instruction files were written as READMEs for humans who would read them with a little healthy skepticism. Now they are runtime input that an agent treats as ground truth. A human who reads a stale README thinks "huh, this looks off." An agent thinks "this is the contract." Humans cross-check. You read the getting-started section, try the command, it fails, and you shrug and look at the actual Makefile . You don't file a bug against the README; you file a note to fix it someday, and then you move on. The README being 20% wrong was a mild embarrassment, not an outage. An agent doesn't cross-check. It reads the instruction file as the spec. If the file says routes live in api/routes.ts , the agent will happily create a new api/routes.ts next to the real one in packages/payments/src/routes.ts , and then wonder why nothing imports it. The agent isn't being stupid. It's doing exactly what you told it to, on the best information it has. 1. Review the diff on CLAUDE.md like any code change. The most common way these files rot is that the agent itself "updates the docs" in the same commit it ships a feature. That's not documentation; that's the agent rewriting the contract to make its current task easier. Treat instruction-file changes as their own PR, and ask: is this describing the system, or is it describing the agent's plan? 2. Smoke-check after a major refactor. When you rename a package, move a directory, or change an env var, re-read the instruction file the same way you'd re-run the build. The cheap version is: open it, look for paths and commands, and confirm they still exist. You don't need a linter for this; you need to not pretend the file self-updates. 3. Never paste a snapshot of a contract into the file. This is the one I see most. Someone copies three example request/response shapes into CLAUDE.md so the agent "has context." Two deploys later the real API returns a new field, the agent generates code against the pasted snapshot, and you get drift that shows up as a bug in production instead of a red CI job. If the agent needs to know the API contract, point it at the live spec file and let it read the current version. Pasting a snapshot guarantees the agent will trust something stale. 4. When the agent's plan contradicts the file, that's a signal. If the agent proposes a change that doesn't match what CLAUDE.md says, do not automatically trust the agent's interpretation of the codebase. Most of the time, the file is the thing that's lying. The code is ground truth; the instruction file is a note to a future collaborator. Treat it that way. The principle generalizes: any "source of truth" you paste into a context file will eventually drift. The moment that source is an API contract, keeping it as a live, local spec the agent re-reads every run matters a lot more than keeping it as a markdown snapshot. That's the whole reason we built Powerduck https://www.powerduck.com/ as a local-first OpenAPI studio: the spec stays the file on disk, the agent reads the current version, and the markdown never has a chance to lie. CLAUDE.md , AGENTS.md , .cursorrules — these aren't documentation anymore. They're runtime configuration written in English, and they rot at the same rate any config file rots if you never look at it. Review the diff, smoke-check after refactors, and never paste a snapshot of a contract the agent should read live. Your agent will be less confident, and your production system will be more correct.