Hi friends
Here's a tip for when you're setting up Claude Code (or any coding agent) in a real codebase, this came in clutch for me when I discovered our agent docs were actively generating broken code.
Most projects end up with four kinds of instruction files:
CLAUDE.md
/ AGENTS.md
files.claude/skills/...
).claude/agents/...
)And the same knowledge gets copy-pasted into all of them. Each copy drifts separately. When I finally audited every claim in ours against the actual code, it was worse than I thought:
beforeAll
, but the test setup file restores all mocks after every test. So the mock silently dies after test one.The docs looked complete. They were confidently wrong. And every wrong doc costs you a multi-thousand-token debug loop when the agent hits it.
It's all about when it loads and who needs it:
| Surface | Loads | Should own |
|---|---|---|
| CLAUDE.md / AGENTS.md | always, every session | rules true for every edit |
| Skill | on demand, per task type | deep how-to knowledge |
| Agent | when delegated | workflow and gates, not knowledge |
| Hook | enforced by code | rules that must never be skipped |
Four questions to route any piece of content:
Every fact lives in exactly one file. Everything else links to it.
Our drift existed precisely because one test template was pasted into three places and evolved independently. After the cleanup:
CLAUDE.md / AGENTS.md -> rules in 3 lines max + link to the skill
skill -> the deep patterns, citing real source files
agent -> workflow + "run the check command and observe it pass"
reference doc -> single home for the heavy API reference
So we can define the boundary in one sentence: if a pattern needs more than a few lines, it goes in the skill and CLAUDE.md gets a link.
This was the fun part. Docs claims are testable, so test them:
First, grep before you trust. Every example in your docs should exist in the codebase. Ours didn't:
grep -rl "prefetchQuery" src/ | wc -l # 0 uses
grep -rl "recommendedHelper" src/ | wc -l # 1 of 50 test files
Then run a retrieval test with a subagent. Give it ONLY the doc files, no repo access, and make it answer real implementation questions:
"Write a test for a component that fetches data."
"Which package does this component come from?"
"Where do global stores live?"
Grade the answers against the codebase. If the agent following your docs writes code that would fail, your docs failed the test, fix them before merging. We caught every regression this way, before it cost anyone a debug session.
this example demonstrates that agent docs are a system with semantics, not a wiki: put each fact where its model matches, keep one home per fact, and test docs like code.
Hope that helped!
Hash