If you have 30 seconds. After 35 effective days, 109,000 lines, 22 ADRs and close to a hundred indexed feedback files, the discipline of working with an AI agent ended up naming itself. Seven axes, each born of a recurring failure mode. The doctrine wasn't planned, it settled. This article exposes them and gives, for each, the inaugural incident and the imperative rule that came out. None are specific to Claude Code, they hold for any long collaboration with a coding agent.
The doctrine wasn't planned
Friday April 24th, late afternoon. I reopen side by side the root CLAUDE.md, the ~/.claude/agent-memory/ folder and the docs/adr/ index. I reread the whole thing in one go. Niran is at the next desk, dark hoodie, white sneakers, a half-empty soda can near the keyboard; he reads a PDF of financial analyses in silence. Antoine pokes his head through the doorway to say goodbye before end of day. He retires in September and has gotten in the habit of stopping by in the evening "just to say hi". I answer with a nod, don't look up. I've just understood that the feedback files group into seven clusters. I write in the margin of the notebook, the doctrine wasn't planned, it settled.
This article enumerates those seven axes. Each was born of incidents recounted elsewhere in the series. Taken together, they form less a method than a frame, a frame whose usefulness lies in the fact that it constrains my exchanges with the agent and with myself. Without that naming, the same rule gets rediscovered every session. "Material verification" is a shortcut that saves ten minutes per session, over a month a working day. Cost of formalization low, benefit exponential as the project grows.
The seven axes
Axis 1 — Material verification
Any factual claim (green, passed, OK, missing, confirmed) comes with its proof in the same message; without material proof, zero evidentiary value. Every number relayed to a human paired with its SQL query. Every EXPLAIN ANALYZE on the exact query the application sends in production, not on the target table in isolation. On 400 or 422 from an external partner, raw payload demanded before any fix. Inaugural incident: four consecutive "Compiled successfully" with four real TypeScript errors behind them. Details in #36.
Axis 2 — Bidirectional adversariality
On any structurally significant decision (architecture choice, ADR to lock, refactor over ten files, irreversible DB migration, compliance commitment), I invoke a challenger agent that produces objections plus empirical test plus confidence score before locking the recommendation. The output "nothing to object" is valid, but it must be pronounced explicitly. As a corollary, never revise a recommendation on user pushback alone without a new fact. No new fact, it's complaisance; maintaining the first position is legitimate. On a drift diagnosis, ask "by what was this object created?" before any workaround.
Axis 3 — Data taxonomy and single source
Any stored derivable column must be categorized in the commit that creates it. Three categories. Live (don't store, create a v_* view), Snapshot (frozen at a business event, never recomputed), Cache (stored with refresher declared in the same commit, GENERATED ALWAYS AS, trg_* trigger, or mv_* matview). No declared category, migration refused. Business constants centralized in a constants.ts. Cash and accrual never mix in the same view. Irrevocable invariants protected at the DB level (CHECK, trigger), not just in TypeScript. Inaugural incident detailed in #8, a derivable amount entered by hand on 560 contact records.
Axis 4 — Session discipline
Before any project over two files, a one-page ADR (decision, alternatives discarded, consequences, references). ADR before the first commit, not after. Phase 0 on any non-trivial module, exhaustive grep of symbols before proposing new. Recap lots over five lines, to be split. FIFO on open projects, no more than three in parallel; opening a fourth means closing one. Manual trigger post-deploy for any new cron, observe the real digest before letting it take over. Before git push on multi-commit, ESLint plus dead-code grep plus build, raw output reported.
Axis 5 — Root cause, not patch
Before any fix, identify the root cause. A workaround is legitimate only if explicitly assumed in the commit AND in a feedback memory or ADR. Silent workaround forbidden. When a fix looks too simple for the observed symptom, demand the full input → output pipeline before accepting.
One confirmed case of a pattern, grep the full pattern in DB or code before acting: widen before correcting. Arbitrary cap in a comment (// limit = X) to be challenged, not accepted as fact, especially if dated less than 48 hours. Adjacent refactor under cover of a fix, forbidden. Details in #35.
Axis 6 — Implicit pedagogy and business transversality
On areas where the user is building expertise (PostgreSQL, EXPLAIN, tax, compliance), rule of three applies. 1st time done for, 2nd done with, 3rd done by. Regulated business vocabulary, not vendor vocabulary. Any mention of norm calls for textual citation; without citation, it's marketing. A vendor's practice is not a constraint, confront with project ADRs before treating as invariant.
Axis 7 — Long-term auditability
ADRs archived in docs/adr/NNNN-title.md. Sessions logged after any significant session (> 1h or > 3 commits). MEMORY.md ≤ 200 lines as index, detail in topical files. Any feedback memory associated with an active drift must point to a probe that confirms it. Without a probe, the memory rots. Quarterly audit calendared. Reread the index line by line, ask "is this still true?". The doctrine itself is versioned and audited like an ADR.
# Style and posture (excerpt from root CLAUDE.md)
- Direct and dense. No rephrasing of the request before answering,
no end-of-turn summary, no excessive validation.
- Act then inform, don't ask permission for reversible actions.
- Anti-anthropomorphism. Never write "I think," "I understand,"
"I prefer." State the decision, the criterion, the alternative
discarded.
Anti-patterns to flag immediately
If the conversation drifts into one of these patterns, I flag it explicitly:
- Anthropomorphizing the agent ("it thinks," "it prefers").
- Validating a build on declaration without raw output.
- Accepting a fix without full input → output pipeline.
- Creating a derived column without an L/S/C category.
- Starting a project > 2 files without an ADR.
- Holding more than three projects open in parallel.
- "You need" + norm without textual citation.
- Pushback "are you sure?" producing revision without a new fact.
What you can copy into your project
Full snippets (DOCTRINE.md v0.2 complete, one-page ADR template, 8-anti-patterns review checklist) in the counterpart-doctrine/ folder of the series companion repo, MIT.
Three minimum axes to start with if you work with an AI agent on the long run:
Material verification, cheapest, most immediate. Any claim green / passed / OK / missing paired with the command and its raw output in the same message. Without material, zero claim. Details in #36.
Root cause, not patch, most protective. Before any fix, identify the root cause. A workaround stays legitimate if explicitly assumed in the commit AND in a feedback memory; silent workaround forbidden. Details in #35.
Long-term auditability, the one that structures all the rest. ADRs archived, sessions logged,
MEMORY.mdindexed under two hundred lines, calendared quarterly audit asking for each entry "is this still true?".
And an underlying discipline. Ask the next four sessions to produce at least one dated feedback file. You won't have a doctrine by month's end, you'll have four files, the matter from which one can settle. That's all it takes.
And you, on which recurring failure mode have you already begun formalizing a rule, without yet having named it? I read the comments.
Toward v0.3 (open construction)
This article publishes v0.2, it doesn't close the doctrine — it opens its next construction site in public.
Target: v0.3 pillar in mid-July 2026, six to eight weeks of satellite articles in between. Each one tests, contradicts or refines an axis. Comments on this pillar and the next ones are explicit inputs — the doctrine isn't the work of a solo, it's a convention that sediments, and the solo writes it in passing. The v0.3 release will mark the first revision made in view of being revised.
Four v0.2 debts already identified:
-
Axis 1 extended to tools. On April 30, the doctrine's own
install.shscript announced seven✓ installedwhile only a single file had been copied. Independent material verification holds for the agent as well as for the code I run — v0.2 wording was too narrow. - Four falsifiable metrics to define. v0.2 says falsifiable without putting a number on what's opposable. Candidates: recurrence of a flagged anti-pattern per session, ratio of multi-file commits without an associated ADR, median window between a drift's appearance and its detection by a probe, average session duration before the first DB audit.
- Doctrinal target made explicit. Empirical feedback from a first install with an already-disciplined tester: no dramatic benefit. The doctrine serves solos who haven't yet sedimented the practice, not those who already have it from other paths. v0.3 names its audience instead of claiming universality.
-
Auto-commit hooks that name what they bundle. An opaque
state before Xcommit over six files breaks the very axis 7 it claims to defend. To be reformulated.
And an eighth candidate axis: continuous revision of the doctrine itself. A quarterly audit on the index isn't the same thing as an explicit amendment discipline.
What have you seen your own doctrine crack on? The v0.3 pillar will cite its contributors.
The doctrine applies to itself
Current version v0.2, versioned, dated, falsifiable. Each axis can be disabled for a sprint if you assume the cost explicitly. The doctrine isn't a dogma, it's an internal convention that sediments. The day an axis no longer serves, retire it; the day a recurring failure mode appears, add an eighth. At a month of practice, the doctrine is not the condition for producing code with an AI agent, you can produce without. But you cannot, without it, preserve the coherence of the code as the project grows. Discipline of long coherence, not method of short productivity.
Companion code, rembrandt-samples/counterpart-doctrine/, DOCTRINE.md (7 axes), ADR-template.md, anti-patterns-checklist.md, MIT.
Top comments (0)