An agent writes faster than anyone can review, so the habits that keep a codebase honest matter more, not less: tests that prove behaviour, architecture that pays for itself, and review that reads the evidence. The encoding loop turns every catch into a rule the next session starts from.
An agent repeats whatever nothing stops. A code review catches a bad pattern. You fix it. Six sessions later the same pattern comes back, because nothing about that conversation persisted: not for the agent, not for the next person, not for future-you. The fix lived in a PR; the rule lived nowhere. And when a rule was written down, the code it described moved on, and the rule went on reading as true.
The encoding loop makes both a defect. A merged fix without its corresponding encoding is a half-finished job, and a rule nothing re-checks is a guess. The threshold for writing one down is a single question: if the next person could repeat this mistake, or would have to re-derive the rule from first principles, it belongs in writing.
Three engineering habits carry most of the weight, and each changes shape when an agent writes the code.
A test earns its place when it fails without the change it guards. In NextAurora that means integration tests against real databases and a real broker are the default for handlers, unit tests are kept for pure domain logic, every ownership rule is proven by a failure test that expects 404, not 403, and each test reads as arrange, act, assert with a narrative a newcomer can follow. In okl's Python canon it means mocking only what you own, and running one shared contract test over every implementation of an interface, fakes included.
With an agent, the tests are the judge. The agent writes the failing test before the change, a fix lands only with the test that fails without it, and a test the agent wrote gets the hardest read of all, because a test that cannot fail proves nothing. A green build is not the finish line either: the integration gap is what happened when every service passed its tests and the system still did not run end to end on a laptop.
Every structural choice has to pay for itself. NextAurora uses vertical slices held by architecture tests in place of a four-project Clean Architecture split (the argument), keeps the aggregate pattern for entities whose invariants someone actually observes, and chose its message transport with a portable decision guide. okl stayed on keyword search until a measured trigger fired, and each retrieval change since was measured before it shipped (the decision record).
With an agent, that judgment has to be written down, because an agent defaults to the ceremony in its training data: extra layers, interfaces nobody substitutes, repositories that exist to be mocked. The canon carries each decision with its reason, and architecture tests turn the important ones into build failures.
I review outside advice the way I review code. An article is audited on its examples as well as its advice: one microservices guide's own code contradicted its stated rules three times. A paper is read from the PDF, with page numbers, before it is cited; a claim needs two credible sources that agree; and "nobody does this" is scoped to what was actually read (okl's related-work page). An idea from outside reading becomes work only through a reviewed issue.
With an agent, the same review applies to everything it produces and everything it is told: read the code it actually wrote, check its claims against a source, and let reviewers with different lenses disagree before anything merges.
Rules are encoded on the softest surface that works, and promoted down the spectrum only when they earn it: when the soft version keeps getting missed.
| # | Surface | What goes here | Catches violations at… |
|---|---|---|---|
| 1 | Always-on canonCLAUDE.md | Invariants only, one line each, with a link to the deeper doc. Loaded into every session, so every byte is cognitive overhead for the model and the human. | Code-generation time |
| 2 | Deep referencedocs/ + paired diagrams | The why behind a rule, and the picture reviewers reason against. Read on demand, not every session. | Review and onboarding |
| 3 | Procedure rituals.claude/ commands, agents, skills | Multi-step motions worth a single keystroke, and a reviewer that starts with fresh context instead of the conversation that produced the code. | On invocation, before code lands |
| 4 | PR automation.coderabbit.yaml path_instructions | File-glob-scoped guidance that re-checks a rule at review time without re-deriving it. Non-blocking: a reviewer can dismiss it. | Every diff, automatically |
| 5 | Mechanical gateCI scripts, analyzers, tests, hooks | The build fails. Nobody has to notice, remember, or agree. | Merge time, loudly |
Those five cluster into three tiers, and the tiers are the point. Convention (1–2) relies on someone noticing, and noticing is the first thing that degrades under deadline. PR automation (3–4) fires on its own but can be dismissed. Mechanical gates (5) fail loudly and need no human in the loop at all. Most rules should never reach tier three. The ones that do are the ones that already bit twice.
NextAurora, a five-service .NET event-driven system you can break live, carries the five surfaces inside one repo:
The full inventory lists every tool, hook, agent and skill by the stage it fires in, with its gaps.
okl answers what no in-repo surface can. All five stop at the repo boundary, and all five decay: the code moves and what is written about it stops being true. okl keeps your coding agent true to your rules, specs and docs, keeps them true to the code, and keeps learning as you build: lessons are briefed before each task, proven by a check you choose, flagged when the code they cover changes, and carried to other repos through the packs they load. It runs here, in okl itself and in Quartzose, each with its own store. The measured effect (42% → 7% on tasks built to invite a known defect) and how much of the claim holds today are on the okl page and in its thesis.
These are the interesting ones. Each exists because something specific went wrong once, and each is a short script run in CI: the smallest mechanism that closes the hole.
Identifiers removed from the code (a retired transport’s API names, dead queue names, old metric names) must not survive in prose as if they were current. The compiler catches stale identifiers in code; nothing catches them in docs.
A messaging-transport swap left 15+ docs teaching the removed transport as current. Found by a human reading, not by a machine.
Source →Every relative markdown link to a local source file must resolve. Skips external URLs and anchors.
An architecture refactor deleted files that CLAUDE.md and the demo docs still cited by path.
Source →Every backtick-quoted repo path and every #L line anchor in the markdown must resolve. The broken-link audit only sees markdown links; this covers the paths written inline.
A drift sweep found 15 inline paths and 8 line anchors that had rotted past the link audit. Each one was a doc pointing a reader, or an agent, at code that had moved.
Source →Every COPY/ADD source path in every Dockerfile must exist in the build context.
A Dockerfile rotted silently for months after a refactor. The broken paths would only have failed at deploy time, so a live demo kept serving pre-refactor code.
Source →Every diagram exists as both an editable .excalidraw source and a rendered .svg. One without the other is a broken diagram: an SVG nobody can edit, or a source nobody can see on github.com.
Diagrams are the review surface, not a byproduct. Treating them as build artifacts is what keeps them true.
Source →Warns at 400 lines, fails at 500. Over budget, detail moves to docs/ or a skill and the canon keeps a headline plus a link.
The failure mode of every rule-encoding method is decay into the spec it replaced. A hard line count is the cheapest defense that actually holds.
Source →Bans plain List/Dictionary/HashSet/Queue/Stack as static fields. ConcurrentDictionary, ImmutableList, FrozenDictionary and Channel pass.
The one concurrency hazard an analyzer can’t catch: the difference between an immutable lookup table and shared mutable state is structural, not syntactic.
Source →Every queue constant reaches a publisher-side declaration; every listener is durable-inbox or inline; no inline topology literals.
Most integration tests stub the transport, so they cannot catch a queue that is declared but never bound.
Source →A tooling list that only grows is a smell. These were evaluated and left out, on the record:
| Tool | Why not |
|---|---|
| SonarQube (self-hosted) and SonarCloud (hosted) | The detection already runs at build time via SonarAnalyzer.CSharp, the same engine. A dashboard would add hosting overhead and a second place to look without adding findings. |
Spec Kit: /specify + /plan + /tasks | Per-feature spec authoring converts a compounding advantage into ceremony. Same lineage, opposite end of the stick. |
| MCP servers for project context | The canon, the paired docs and the greppable surfaces already give the agent persistent decision context, and they live in the repo, next to the code they describe. An external tool layer over decisions that already live in-repo is convergence in the wrong direction. OKL does ship an MCP server, and the line it draws is the same one: it carries only what has to cross a repo boundary, which no in-repo surface can. |
| A CI-generator skill | The CI works. Generating it again is anti-pragmatic. |
Every method eventually decays toward the thing it replaced. Agile decayed into spec-process-with-shorter-cycles. Spec-driven development started as goal-direction and decayed into 1,300-line specs. TDD decayed into coverage-gaming. There is no reason to assume this one is exempt, so the defenses are built in: a hard size budget on the canon so it can’t bloat into the spec it replaced; a drift audit so paraphrases stay aligned with the source; an explicit separation between lessons from this feature and what this feature must do, so the rule set never collapses into per-feature ceremony; and a promotion spectrum, so the rules that matter become loud failures rather than quiet conventions.
The claim isn’t that AI made the work faster. A 2025 controlled trial found experienced developers were measurably slower with AI while feeling faster. Being wrong while feeling fast is the whole failure in one sentence. The claim is narrower and testable: the build eventually enforces what used to be a fifteen-minute PR review conversation, and that conversation never has to happen again.