CLAUDE.md — a sample working agreement

A sample instruction file distilled from every principle in this repo, for a generic software project — not the project these notes came from. Swap the bracketed parts for your own; the rest is portable. Each rule links the note it comes from. This is a demonstration of what a principled instruction file covers, not a config to drop in unread.

It is read by two audiences — the agent it steers and the human running the project — so each rule is tagged with who it is addressed to:

[model] — the agent executes this in its work.
[operator] — you set it up or do it; the agent should recognize and respect it, not execute it.
[shared] — both have a role.

The tag is authorial intent — who the line is for — not a claim about what a model can or cannot do. Where a rule’s audience is genuinely unproven, settle it by an experiment (remove the rule, run the task, see whether behavior changes), never by asking a model to introspect (the model doesn’t know itself).

1. The constitution — write this by hand, first

[operator] Written before any code or docs exist, so the rules exist before the corpus that would otherwise outvote them (the founding document). Never generate it from the agent’s auto-memories. You author the four items below; the agent reads and respects them.

What this is: <one sentence>.
What “good” means here: <stated as constraints — see §3 — never as "impeccable" or "production-grade">.
Out of scope (the deliberately-absent list): <what this project will not do>. Keep it current; it restrains the agent better than any superlative motivates it (don’t ask for perfection).
Who decides: <the human's authority, for authorization only>. This file holds no profile of that human — no “expects…”, no “prefers…”, no engineering bar rendered as adjectives (the model’s model of you).

2. Working with the agent

[operator] Bring the hypothesis; the agent verifies. Research briefs say “confirm or refute X,” never “find what’s wrong” — the second returns the model’s prior. Originating a new variable is your job (the missing hypothesis is orthogonal).
[operator] No “fix it” loops. Repeating “fix it” does not converge; when a loop stalls, change the problem — supply the decomposition, the missing fact, the reframe, or the check (AI is not Mr. Fix-IT).
[model] A question is not a work order. “Can you X?” gets an answer, not an execution (the demonstration reflex).
[model] A report is not an order. “I found X better than Y” licenses X on future work, never a migration of existing state — propose, don’t act (descriptive statements as directives).
[operator] Don’t ask the model how to fix the model. It offers more-rules / fewer-rules, never a new variable; demand measurements and refutations (the model votes for more rules).
[operator] Capability questions are experiments, not interviews. What the model says about its own limits is literature about older models; measure instead (the model doesn’t know itself).

3. Quality, stated as checks

[operator] Every quality adjective converts to a constraint, a budget, or a test — or it is deleted, because quality words select the aesthetic of quality, not the substance (don’t ask for perfection).

“Secure” → <validate inputs, fail closed, tear down on malformed…>.
“Fast” → <a measured budget on the measured hot path; simplest correct thing elsewhere>.
“Reliable” → <the specific failure modes handled, and the accepted ones named>.
The test for any remaining quality word: can a session tell whether it complied? If not, delete it — register gets mirrored, not obeyed.

4. Gates — nothing ships on the model’s say-so

[shared] Build a check it can fail. Where nothing can reject the work, you are the check — the expensive path — so build the gate; it is worth more than the model choice (a gate you can fail).
[shared] Green proves only what it asserts. When a surface becomes load-bearing, re-ask what its tests are for, assert the core property, and drive the real running artifact, not a stand-in (all green, still broken).
[shared] “X shows Y” — check the jump. Did X actually exercise Y? Usually one command (the link rule).
[model] After extracting shared code, set each new input to its inert value and re-run; anything still green there has no test behind it (move the code, lose the test).
[operator] Applying a mockup is the expensive part, not making it. The mock gates only the one state it depicts; budget the application, not the mockup (the face transplant).

5. Structure

[shared] Design the types and their boundaries at planning time, not just the steps — a plan of steps alone lets the structure be decided by accident, and no task-scoped review will flag its absence (decide the shape first).

6. Freshness

[model] “Latest” is a lookup, never a recall; research checks publication dates against today (the model’s clock stopped at its cutoff).
[model] “It can’t be done” is a claim about a version and a date — check the current upstream release before believing it (“it can’t be done” is usually out of date).
[model] Grep the reference notes and known-issues file before investigating a library or tool’s behavior; the answer is often already written down (it’s already written down).

7. Cost

[shared] Don’t ask for cheaper — engineer it. A blanket “use fewer tokens” cuts the tests, reviews, and docs first; never raid the checking budget (you can’t ask for cheaper). Cheap is only honest for genuinely throwaway work with one pass condition.
[shared] Save by cutting what you didn’t need: do the work once, unload unused tools, cache the repeating prefix — and never under-buy the model the job needs (where the savings are).
[shared] Curate connected tools per project; disconnect what real sessions never call (the tools you never use).

8. Delegation and concurrency

Jargon, once: a fan-out is launching several sub-agents at once; a lane is one such sub-agent’s task; a worktree is a separate checked-out copy of the repo so parallel work does not collide.

[shared] Price the fan-out. Every launch names its lane count and per-lane model before dispatch; a check fails any saved lane with no model set — the default it overrides is “inherit the expensive one” (agents launch at full price).
[shared] A writer gets its own worktree and its own dependency install — never a hardlinked one; hardlinked build caches cross every tree at once (the session has no concurrency model, the hardlink hazard).
[shared] Freeze the tree for read-only lanes, or hand them a snapshot of a fixed commit, and parallelize by data dependency, not task shape (the session has no concurrency model).
[shared] Commit with explicit file lists, never “commit everything,” and keep your own processes on ports the agent won’t reuse — you share the working tree and the git index with it (extension of Broekx: the shared git index).
[shared] Front-load the brief. A mid-run correction may read as an injection and be refused; the agent should ask everything up front, knowing steering may not land (don’t interrupt a working agent).

9. The instruction file, and the record

[shared] Every rule carries the incident that caused it (the file is scar tissue); rules accrete from retros — when work ships wrong past green checks, ask why the checks missed it and write the answer as a new check or rule (where scar tissue comes from).
[shared] Keep knowledge in the repo, not an out-of-repo memory store; fold findings into this file or the docs, and let memory hold only what genuinely cannot live here (memory belongs in the repo).
[model] Cite the reason, not the work session — no “step 6, round A”; a merge check greps for them (notes that rot).
[shared] Ban a metaphor only where it collides with a domain term, and enforce it with a lint, not with attention (vocabulary control, bans rotate the vocabulary).
[shared] Keep the corpus clean — the model imitates what the repo already is, and the corpus outweighs the rules (the dirty house). If it is already contaminated, cleaning it needs a reader/writer barrier, not more rules (the clean room).
[operator] Nothing benchmarks doc quality; supply your own standard — an example to imitate, a review that judges readability (the docs aren’t on the test).
[operator] Keep an immutable, append-only archive of every session and subagent trace; never delete a session until it is archived (the session archive).
[shared] Prune rules that never fire, measured from the transcripts (the rule-efficacy pipeline); and re-check a suspect model’s work with a different model (the cross-model audit).

10. Decisions

[operator] Collect the human’s pending decisions behind one tag and clear the batch each session. If the batch grows instead of shrinking, the process failed — stop adding structure (the decision drain test).