Field note · build record

How this repo's CLAUDE.md was built
— and why every line is in it

The CLAUDE.md is the first thing every Claude reads before touching this project. It is not documentation — it is latent-space conditioning: a compressed prior that steers all downstream work. So it wasn't written. It was mined, distilled, and won — from 23 real sessions of building this game, through a pipeline of five multi-agent workflows.

Source 23 sessions · 147 MB transcripts Method 5 workflows · ~35 subagents Output 1 CLAUDE.md + this explainer Built in an isolated git worktree

01The idea — a CLAUDE.md is a prior, not a README

Condition the latent space, don't just inform the reader

Every model response is a sample from a distribution. The text you put in front of the model before it works reshapes that distribution — it raises the probability of some behaviours (reproduce the bug as a number; fan out and verify) and lowers others (patch by vibes; declare victory early). A good CLAUDE.md is therefore engineered like a prompt, not filed like a doc. The user's word for the distilled store of proven moves was the "quantum DS" — the latent layer we wanted future work to collapse out of.

The design tension. The file has to do two jobs that pull in opposite directions: be a personality file (cast the reader as the orchestrator-owner of the project) and an orientation file (what the repo is, the standards, the toolchain) — while staying short enough to actually be read and durable enough not to rot. Most of the process below exists to resolve that tension with evidence instead of opinion.

147MB→464KB
transcript → corpus
96→24
raw → ranked techniques
5
candidate philosophies
3+5
judges + adversaries

02The process — five workflows, owner in the loop between each

Mine → Orient → Generate → Tournament → Finalize

It was deliberately not one mega-workflow. Splitting into five lets the orchestrator read each result, persist it as an artifact, and tune the next phase — and re-fire any single phase cheaply if a result disappoints. Control flow stays deterministic; judgement stays human-shaped.

WORKFLOW 1
MINE
7-lens multi-modal sweep over the corpus → dedup/rank synthesis → completeness critic. Output: the Technique Catalog.
WORKFLOW 2
ORIENT
5 parallel readers map the repo → a grounding lead that verifies every referenced artifact exists. Output: orientation brief + ground-truth manifest.
WORKFLOW 3
GENERATE
5 candidates drafted in parallel, each a distinct organizing philosophy, all fed the catalog + brief + owner read.
WORKFLOW 4
TOURNAMENT
Adversarial critic per candidate → 3-judge comparative panel → champion synthesis → red-team that re-verifies ground truth.
WORKFLOW 5
FINALIZE
Write CLAUDE.md, re-verify against the repo, build this explainer, commit in the worktree.
corpus ─▶ catalog.md ─┐   brief.md ─┐   ──▶ 5 candidates ──▶ champion ──▶ CLAUDE.md

Why a fresh extraction step came first

147 MB of JSONL is mostly tool-result noise — file dumps, diffs, screenshots. The signal the user asked for (prompting techniques) lives in two narrow slices: human-typed messages and the Task/Workflow prompts the assistant authored. A deterministic Node extractor (extract-corpus.mjs) pulled just those, unwrapped goal-hook boilerplate to its pure intent, and split the result into three streams — user prompts (144), orchestration prompts (32), task decompositions (60). 464 KB small enough that every mining agent could read its whole slice instead of guessing from a fragment.

03The concepts — the orchestration patterns, and why each one

pattern

Multi-modal sweep

Mining is a retrieval-precision problem. One agent on a blended blob surfaces generic advice. Seven agents, each with a single analytical lens (autonomy framing; verification demands; orchestration shapes; decomposition…), each read a focused slice. Each is blind to the others, so coverage beats redundancy. Synthesis dedups across them.

pattern

Survey → Judge → Synthesize

The repo's own canonical orchestration move (mined straight from the corpus): generate N independent single-axis proposals, score them against an explicit rubric, then synthesize one output — top candidate as the spine, best ideas of the rest grafted on. Used here to pick the CLAUDE.md.

pattern

Adversarial verify

A separate, skeptical pass whose job is to refute, not admire. Each candidate got a critic hunting staleness traps, vague directives, contradictions, and lines that would mislead a fresh Claude. Findings the synthesis must fix — not flattery.

pattern

Ground-truth manifest (anti-staleness)

The orientation lead and the red-team both ran ls/grep against the live repo before any path or command entered the file. A CLAUDE.md that references a script that doesn't exist is worse than silence — so nothing unverified survives.

pattern

Structured output contracts

Every mining/judging agent returned a strict JSON schema (validated at the tool-call layer, so the model retries on mismatch) — not prose to be re-parsed. The catalog and scores arrive as data the orchestrator can compute on.

pattern

Owner in the loop

Between each workflow the orchestrator read the result, cross-checked it against an independent read of the corpus (owner-read.md), and persisted artifacts. The agents propose; the owner decides. No black box.

04The catalog — the "quantum DS" distilled from 23 sessions

Ten essence principles every Claude internalizes first

Mined from the corpus, deduped and ranked, then sharpened by a completeness critic. These are the irreducible core; the full ranked catalog of 24 (with [Sxx] evidence) lives in catalog.md.

  1. Turn the fuzzy feeling into a hard number. "Feels off / too mechanical / stuck" isn't actionable until it's a metric. Baseline on HEAD first, fix, re-measure. No fix claimed without a before→after number.
  2. Build a mover-faithful ground-truth oracle. An independent check (BFS reachability) is the only thing that catches the system lying about its own success — but it must honour the real consumer's exact rules, or it over-counts.
  3. Distrust your first answer; prove wins on held-out seeds. "Done" is a hypothesis. Run a skeptical pass that traces one concrete failing path; re-measure headline numbers on seeds you never tuned on.
  4. State results numbers-first, with a "what's still imperfect". Lead with the unflattering figure; call partial wins partial; log the risky change you correctly skipped and why.
  5. When stuck, instrument and dump — never speculate. Localize every cause to file:line and the exact tick. Patched the same area twice with no movement? Stop and propose a rebuild — thrashing means change approach.
  6. You own it end-to-end. Standing authority to rebuild any subsystem; default to acting, not asking; run goals to completion. Sky-high bar, simplest architecture that hits it.
  7. Ground every realism claim in a cited source, then map to code. Doctrine/physics → the file:line gap → concrete parameters → the harness metric that verifies it. Realism is checkable, not vibes.
  8. Audit the harness before trusting a green metric. A passing number is not a passing system. Confirm it asserts the real success condition and doesn't conflate "slow" with "stuck".
  9. Continuity lives in artifacts, not chat. Docs/wiki/manual/issues/progress are the done-gate. Mine git log + issues for what was already tried; never re-attempt a refuted approach.
  10. Keep the standing checks green; commit only when asked. Work on main by default — branch or worktree only when the owner asks (or to deconflict parallel agents, one-writer-per-file); tsc/build/smoke/balance green. Spend freely on rigor — under-investing in it is the only expensive mistake.

The 24 ranked techniques, by category

1verifyTurn the Fuzzy Feeling into a Hard Number
2verifyMover-Faithful Ground-Truth Oracle
3verifyProve It on Fresh, Held-Out Seeds
4commsHonest Results: Numbers First, Residual Named
5verifyAdversarial Verify as a Separate Pass
6verifyInstrument & Dump to file:line
7verifyAudit the Harness Itself
8mindsetStep-Back Confidence Check → Rebuild
9mindsetYou Own It End-to-End
10qualityThe Astonishment Bar + Simplicity Tie-Breaker
11qualityGround Realism in Cited Sources
12orchestrSurvey → Judge → Synthesize
13orchestrSubagent Prompt Contract
14orchestrRecon Phase + Do-Not-Re-Try List
15verifyVerify in the Real App, Not Just the Sim
16processDocs/Tutorials/Issues Current as Done-Gate
17processContinuity Lives in Artifacts
18verifyStanding Checks + Exhaustive Types
19decompPlan Spine: Baseline→Diagnose→Fix→Verify
20decompEach Task Bundles Build+Wire+Verify
21processBranch/Worktree + Parallel Deconfliction
22verifyBuild Whatever You Need to Verify
23qualitySelf-Critique Render Loop in the Agent
24verifyRe-baseline When Inputs Shift

05Anatomy of the final CLAUDE.md — why every section exists

Seven sections, ordered by what a fresh Claude needs first

The final file is 142 lines. It opens with identity, ends with pointers, and orders everything in between by urgency. Each block resolves a specific job — and each was kept because the tournament's judges and adversaries argued it earned its place.

Preamble — identity + the bar + the caveat

Casts the reader as the orchestrator-owner (the personality job), sets the emotional quality bar ("holy shit, an AI built this?"), licenses fun as a real criterion, and front-loads the one Next.js caveat. The bare @AGENTS.md line inlines that caveat into context every session — pointer + guarantee. It also tells the reader to translate the owner's speech-to-text dictation into an engineered prompt before acting — read intent, not transcript.

↳ encodes: You-Own-It-End-to-End · The Astonishment Bar · the AGENTS.md hook · read-intent-not-transcript

§1 · The Decision Protocol

A table that routes the reader to the right work-shape — solo / metricize / survey-judge-synthesize / tournament / adversarial-verify — before touching code. This is the literal answer to "what should every Claude see first": pick the shape, then act. Grafted from the console candidate; it was the panel's #1 must-graft.

↳ encodes: Don't-Trust-Yourself-Orchestrate · when-to-fan-out

§2 · What This Is (60-second orientation)

The orientation job: the soul (one master clock, "win every firefight and still lose the valley," combat is 100% AI) plus architecture-at-a-glance and the three-layer/one-bridge rule. Specifics that rot are pointed at (DESIGN.md, Architecture.md), not copied.

↳ encodes: orientation · pillars · architecture pointers (anti-staleness)

§3 · The Laws (non-negotiable, evergreen)

Ten durable principles — the catalog's essence, distilled. No fix without a number; prove on held-out seeds; the oracle obeys the mover's rules; thrashing → rebuild; continuity lives in artifacts; never work on main. These hold regardless of code churn.

↳ encodes: the 10 essence principles (all evergreen)

§4 · Playbooks (concrete, numbered moves)

The laws turned into executable SOP — Verification, Bug-hunt, Orchestration, Verify-in-real-app, Plan-spine, Delivery. This is the section that won the tournament for the laws skeleton: judges scored it 10/10 on "techniques as standing procedure."

↳ encodes: Survey→Judge→Synthesize · Subagent Contract · Instrument-and-Dump · the verification suite

§5 · Build Whatever You Need to Verify

An explicit license: writing harnesses/probes is core work, never a detour; name throwaways scratch-* and delete them, but record the reproduction technique. Removes the hesitation that makes "verify as a number" not happen.

↳ encodes: Build-Whatever-You-Need · Spend-Freely-on-Rigor

§6 · The Done-Gate

Defines "done": standing checks green (tsc/build/smoke/balance), docs as a first-class deliverable, dated records, and commit conventions. The red-team made the mandatory trailer explicit after verifying nothing auto-adds it.

↳ encodes: Standing-Checks · Docs-as-Done-Gate · honest commit bodies

§7 · Deeper Pointers + gotchas

The anti-staleness tail: every volatile detail quarantined behind a pointer ("don't memorize the list — ls scripts/"), plus hard-won gotchas (TIC latch, reachability-snapping, LAND_COUNT) that close with "trust the code over the docs — including this file."

↳ encodes: Continuity-in-Artifacts · pointers-not-copies · reality-wins
The closing line is load-bearing. "Do not stop until the goal is verifiably complete — then iterate one more time… When this file and reality disagree, reality wins — fix this file." It fuses the user's "don't stop until done" with the catalog's "iterate once more" and makes the file self-correcting — the single best defense against staleness.

06The tournament — how the winner was chosen

Five philosophies, five adversaries, three judges, one synthesis

Each candidate got a dedicated adversarial critic hunting staleness traps and misleads, then a 3-judge panel scored all five comparatively across seven dimensions (max 210). The result was a near photo-finish — proof the upstream catalog + brief were strong inputs.

CandidateScore /210Judges' verdict
laws — Laws + Playbooks193 🏆Perfect 10s on technique-SOP, actionability, anti-staleness. The playbooks read like SOP a fresh Claude can execute step-by-step. Chosen as the spine.
opord — Commander-Intent192Strongest identity + voice; OPORD framing is native to a COIN sim. Lacked an explicit when-to-fan-out rule.
console — Operating Manual187The DECISION PROTOCOL table was the single best actionability artifact in the field — grafted into the winner.
firstfive — First Five Minutes185Best progressive-disclosure ordering + quarantined pointers tail. Voice the most conventional.
manifesto — Minimalist168Warmest voice, best caveat hook — but thinnest on orchestration depth; lower actionability.

The synthesis recipe — better than any single candidate

The synthesis lead didn't just crown the winner; it built a champion from the panel's must_graft list — the spine of one candidate with the best organ of each other:

spine

laws

10 evergreen Laws + numbered Playbooks — the durable + actionable core.

graft

console → §1

The Decision Protocol table + the tournament shape, as the entry point.

graft

opord → voice

"The bar is the success condition, not a metaphor" + commander tone.

graft

firstfive + manifesto

The length self-budget, the §7 pointers tail, and "the one caveat that breaks people."

The red-team earned its keep. The final pass didn't just polish — it ran ls/grep against the live repo and caught real factual errors the drafts had inherited: the civClear ROE gate is a method on CombatSim in combat.ts, not in friendly.ts as the brief stated; and the mandatory commit trailer is not auto-added — the author must include it. Both corrections survive in the shipped file. This is the catalog's own law #1 in action: a green claim is a hypothesis until an independent pass confirms it. (The owner then re-verified every high-risk claim a third time before shipping.)

07Keeping it alive — the anti-staleness design

A CLAUDE.md dies the day it references something that no longer exists. Three design choices fight that:

Principles over specifics

The bulk is evergreen technique (verify-as-a-number, orchestrate-don't-trust-yourself) that holds regardless of code churn.

Pointers, not copies

Volatile detail (architecture, weapon tables) stays in docs/ and is pointed to, never duplicated — one source of truth, so the file can't contradict the code.

Verified ground truth

Every script/command/path was confirmed to exist by Bash before it went in, and is re-checkable by re-running the ORIENT workflow whenever the repo shifts.