Writing A CLAUDE.md That Survives Contact

Most root instruction files are written once and never revised. Here is what to put in, what to keep out, and in what order.

Prerequisites

An agent that reads a root instruction file on every session. Somewhere to put files that are loaded conditionally.

Steps

1. Write identity first, and keep it operational. Not a personality sketch — an operating stance. Who it takes instructions from, what language, what tone, what it optimises for. Everything below is read through this, so vagueness here is expensive everywhere else.

2. Put hard rules immediately after, and cap them. Under 10. Each one line, each with the reason beside it. Position matters: a rule at line 300 competes for attention rather than winning on precedence, and the ones at the top are the ones that fire.

The reason is not optional. A rule without its cause gets deleted by a future reader who cannot see what it prevents.

3. Move everything conditional behind a trigger table. The always-loaded file should hold what applies to every session. Domain detail goes into separate files with a table saying when to load them:

| supplier question | supplier standard, ordering profile |

This is the single largest lever on quality. Longer context measurably degrades extraction, so a file that eagerly includes everything relevant competes with itself.

4. Write the response protocol as an ordered list with suppressors. What gets emitted, in what order, and what switches each part off. The suppressor half is what stops the agent from ignoring a request for brevity.

5. Add rules only after the second occurrence. Once is an incident. Twice is a pattern. A file seeded with imagined rules trains the agent to guard against things that never happen, and it is unreadable by month 3.

6. Pair every addition with a removal. New rule in, old rule out. If nothing can be retired, that is a signal the file has grown past the point where anyone can see what is already in it.

7. Date the file and log every change. A one-line changelog entry per edit, kept outside the file itself. Six months later the question is never what does this rule say but why was it added and is that still true, and only the changelog answers it.

8. Re-read it in full once a month. Not to edit — to notice. Contradictions, rules that have quietly stopped applying, sections that have grown past their usefulness. This is the only mechanism that catches drift, and it takes about 10 minutes.

Verify

Two tests, both cheap.

The stranger test: could someone who has never seen the system predict what the agent will do in 5 common situations by reading only this file? If not, something load-bearing is implicit.

The contradiction test: search for rules that could both apply to one situation and point different ways. In a file of any age there will be some, and they are invisible until looked for deliberately.

Troubleshooting

The agent ignores rules that are clearly written. Prompt text is the weakest enforcement there is. Move the important ones into checks that run — a hook, a build step, a gate — and accept that the file specifies behaviour rather than guaranteeing it.

The file keeps growing. Step 6 is not happening. Growth is the default and shrinking requires a rule of its own.

Sessions behave inconsistently. Look for two rules in tension before assuming model variance. In practice it is usually the file, not the model.

[Writing A CLAUDE.md That Survives Contact](https://stillvalid.dev/playbooks/writing-a-claude-md-that-survives) — stillvalid, SV-5449 (playbook, verified 2026-08-14)