Specifying Behavior

What this book is

A prose file, read like any other prose

Claude Code reads instruction files called CLAUDE.md at the start of every session and loads their contents into context. From that point the instructions are available to every command in that run — but between commands the files are not re-read, and nothing about the format is parsed specially. Prose goes in, behavior comes out, and how good the behavior is depends entirely on how good the prose is. Most practitioners write the file once: a few rules, a style preference, a note about what the project does. Eventually behavior diverges from what the file says, and the practitioner assumes the model ignored it. That's rarely the real diagnosis.

This book treats behavioral specification as a craft with learnable failure modes, using eight real project files as source material — a deploy pipeline, a manuscript series, a memory system, a research workflow — each written for a distinct purpose with distinct rule types: routing rules in one, scope constraints in another, output format directives in a third. These are case material. Reading them surfaces the failure modes; copying their structure does not.

What you’ll learn

Eleven chapters, from mechanics to maintenance

• what-it-is — What CLAUDE.md is and how it loads: read once at session start, never re-read between commands, weighted by position like any other context.
• minimal — The three things a file needs before rules, tools, and pipeline notes to function as anything other than a collection of context-free commands.
• hard-rules — The gate pattern: marking instructions that must not be violated under any ordinary circumstance differently from ones that merely set a preference.
• role-domain — Role and domain rules: what a session's job is, what territory it operates in, and what sits outside it.
• content-rules — Content rules that govern what a session may say, distinct from role rules and from the deploy rules that govern what it may do.
• deploy-discipline — Why deploy rules share the same structure across unrelated production projects — a staging/production gate, a credential check, a scope confirmation — and what that structure protects against.
• incident-rule — The difference between a rule that states a prohibition and one that records why the prohibition exists, and why the second kind survives longer.
• limits — What CLAUDE.md structurally cannot enforce, and how to recognize a problem that needs a different mechanism before writing a rule for it anyway.
• maintaining — Managing a real collection of project instruction files as a record of decisions made at different times for different projects, not a template applied consistently.
• reading-your-own — Why a file that sat unopened since setup goes stale by default, and a test protocol for catching drift before it becomes a production problem.
• conclusion — The complete mechanical account: a prose file, read once, producing behavior — and why everything else is rule quality.

From the book

A preview

A CLAUDE.md written three months ago may describe a project that no longer exists in that form, and the model fills any gap it leaves with its own judgment — which is fine until it isn't.

Who it’s for

Anyone who has felt the gap between sounding right and working

This is for anyone running Claude against a real project file who has felt the gap between a CLAUDE.md that sounds right and one that actually works — and wants that gap to become specific, diagnosable, and fixable instead of mysterious. It pairs naturally with Hallway Rules (Book 28) for multi-agent routing constraints and Authority Gates (Book 29) for enforcing what a rule alone can't guarantee.

A longer excerpt is available to newsletter subscribers.

Buy Ebook on Amazon