AI engineering is engineering.

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.

The problem it solves

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.

What I bring to it

Three engineering habits carry most of the weight, and each changes shape when an agent writes the code.

Tests that prove behaviour

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.

Pragmatic architecture, argued from evidence

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.

Review and research as a discipline

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.

Eight principles

  1. Encode every catch, on the smallest surface that holds it. The session that surfaces a non-obvious failure also writes it down, once, where it will be read. Every session ends by asking what was learned.
  2. Prompts advise; gates enforce. A rule starts on the softest surface that works and is promoted toward a failing build only when the soft version keeps getting missed (the five surfaces, below).
  3. Classify the change before you start. Novel work (a new boundary, a new transport, a change to the security model) gets me present while it is built; work that follows an established pattern gets reviewed at the gate. Reading a finished diff is not presence: by then the agent has filled the gaps nobody noticed.
  4. Prove, don't assert. A rule counts when a check I chose ran and passed, never because someone marked it true. A figure counts when a committed receipt backs it. Measurements are written down before they run, and a model never grades its own work.
  5. Treat disagreement between models as a signal to dig, not a vote to settle. Several reviewers with different lenses look at the same change, and where they split is where I look first.
  6. Fix the class, not the instance. When review finds the same kind of defect twice, name the rule, apply it everywhere it matters, and add one end-to-end test, instead of patching the next place the reviewer points at.
  7. Measure the whole population, not the slice you can see. Before quoting how accurate a safeguard is, count how much of what it protects it inspects at all. A precise check on a tenth of the problem is a tenth of a safeguard.
  8. Give every experiment a budget and a sunset. Building is cheap; the discipline is the stop. Each experiment declares its cost and its end before it starts, and when either runs out the default is to stop and write down what was learned.

Five surfaces, ordered by enforcement strength

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.

#SurfaceWhat goes hereCatches violations at…
1Always-on canon
CLAUDE.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
2Deep reference
docs/ + paired diagrams
The why behind a rule, and the picture reviewers reason against. Read on demand, not every session.Review and onboarding
3Procedure 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
4PR 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
5Mechanical gate
CI 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.

Two working instances

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.

The guards nobody ships off the shelf

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.

Tombstone audit

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 →

Broken-link audit

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 →

Doc-path audit

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 →

Broken-COPY audit

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 →

Diagram-pair audit

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 →

CLAUDE.md size budget

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 →

Static mutable collection audit

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 →

Messaging-topology audit

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 →

Considered and skipped

A tooling list that only grows is a smell. These were evaluated and left out, on the record:

ToolWhy 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 + /tasksPer-feature spec authoring converts a compounding advantage into ceremony. Same lineage, opposite end of the stick.
MCP servers for project contextThe 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 skillThe CI works. Generating it again is anti-pragmatic.

The decay problem

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.

Read further