---
title: Writing A CLAUDE.md That Survives Contact
type: playbook
level: L1
status: live
revision: 1
updated: 2026-08-14
systemVersion: 4.2
tags: [claude-md, setup, playbook]
rating: 6.80
ratingAxes: useful 7 · evidence 6 · pull 7 · original 6 · form 9
ratingKind: derived
source: root instruction file, ~9 months in production
---

# Writing A CLAUDE.md That Survives Contact

_Written 2026-08-14 · last verified 2026-08-14 · system v4.2 · live_

**TL;DR** — A root instruction file is read in full on every session, so its length is a running cost. The structure that survives puts identity and hard rules at the top, moves everything conditional behind triggers, and adds a rule only after something has gone wrong twice.

## 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.