There is a discipline that has become almost mandatory on codebases that work with AI agents. You write a CLAUDE.md, or an AGENTS.md, or whatever the file is called this week, and you fill it with the context you wish a new contributor had. Most of these files are too long. Most of what goes in them is discoverable by reading the code. And most of them grow rather than shrink, because documenting a convention feels like progress.
At EkoHacks we use a tighter rule, borrowed from Addy Osmani: the file is for landmines, and nothing else.
A landmine is a fact about the codebase that cannot be discovered by reading the code, will cost time or correctness if you step on it, and is operationally significant. Port numbers are a landmine. The directory tree is not. A silently enforced convention is a landmine. The conventions your linter catches are not.
Here are two examples from our own repo. One came out, one is still on the list.
The one that came out
The server CLAUDE.md had a five step procedure at the top. New webhook route, follow this exact order or signature verification silently fails.
- Extend the request type for raw body access.
- Set
config: { rawBody: true }. - Convert rawBody to string.
- Call
verifyGitHubSignature(rawBody, signature, secret). - Handlers take
(payload, logger), not(request, reply).
Step 4 is the actual security check. The other four steps are the ceremony around remembering to do step 4. Every new webhook was a chance to forget one of them, and "silently fails" was doing a lot of work in that sentence.
We replaced it with a Fastify plugin. The plugin reads a flag off the route config and runs the signature check as a preHandler. The route declares config: { webhookSignature: { secretEnv, header } } and that is the whole contract. Forgetting the check does not silently pass. It visibly omits a config key that sits right next to the route schema.
Five steps of documentation replaced by one config flag in code. The CLAUDE.md section was deleted the same day.
The one still on the list
Another line, still in the landmines section:
PostgreSQL runs on port 5433, not 5432, via
docker-compose.yml.
The port is non standard because several of us have a conventional Postgres running locally for other work. Docker assigns 5433 to dodge the clash. An agent that connects to 5432 finds a different database, gets confused, and writes the wrong data, or it fails loudly at a moment nobody is watching.
This one stays. The fix would be to switch to 5432 and live with the clash, or to make everyone reorganise their local Postgres. Neither is worth the move. The landmine is cheap to document and the fix is expensive. Keep.
The principle
A line in CLAUDE.md that tells you to remember to do a thing is a bug report against the codebase. The fact that you can train an agent to read the line and follow it does not mean the line is doing useful work. It means the line is masking a structural problem the code could fix.
When a landmine appears in the file, the first question is not "is this well phrased" but "can we delete it by changing the code." If yes, do that. If no, it earns its place. Most of the time the answer is yes, and most teams never ask.
We also moved 416 lines of hand written TypeScript types out of our frontend recently. The CLAUDE.md landmine was that the client types were manual and drifted from the server. The fix was an OpenAPI codegen pipeline. The line got reworded to describe the new automatic workflow, and the 416 lines of drifting types collapsed to about 115 that derive from the server's schema. Six bugs that had been shipping silently fell out as a side effect.
Both of these started as landmines and ended as refactors. Both of them shrank the CLAUDE.md in the process. That is the direction the file is supposed to go.
What the list is for
CLAUDE.md is not the onboarding document. It is not the architecture doc. It is not the style guide. It is a living list of friction nobody has fixed yet.
Every line is a ticket. Most tickets are cheap to close. The ones that stay are the ones where the cost of the fix is higher than the cost of the warning. You earn your landmines. You do not accumulate them.
When we start a new client project, we open the CLAUDE.md with a single sentence at the top. If you encounter something surprising or confusing, flag it. Over the first few weeks the file grows as the agent and the team notice traps. Then we go through it together and fix the ones we can. The file shrinks back down. That rhythm is the whole point.
The question to ask of any CLAUDE.md is not "what should go in it." It is "what can we take out." Answer that one honestly and the rest of the file writes itself.
