One of the more interesting questions about AI-assisted development has little to do with how fast you can generate code. It's how you keep a model from confidently building the wrong thing - or shipping buggy code, drifting the architecture, reaching for off-pattern solutions - and how the project remembers why it was built the way it was. These are the conventions I've settled on over a year of shipping with AI assistants as the implementation layer.
The premise
I use AI agents as implementation workers inside an engineering system whose architecture, acceptance criteria, verification, and promotion rules are explicit. The division is not "human thinks, model types." Agents can plan, implement, diagnose, test, and review. The important boundary is that a worker does not get to define the evidence that proves its own work correct. A model will still assert an API behavior from memory that the vendor's docs contradict, re-derive a metric that's already stored, or lose the reason a decision was made between sessions. Those are process failures, and process is something software can enforce.
What follows started as a set of conventions, each one a response to a failure I actually hit. Some remain documentation rules; others are now implemented directly in Ratchetloop, the delivery pipeline I built around isolated work, deterministic checks, independent model-family review, persistent run evidence, and human-controlled promotion.
Durable decisions need a durable record
The artifact should fit the project. Large systems with consequential architecture choices use numbered Architecture Decision Records in Nygard form: context, decision, and consequences. Smaller tools can use a compact decision register instead. A bounded work sample may need no separate decision record at all if its design, plan, and task contracts already capture the meaningful choices.
The invariant is not "every repository has ADRs." It is that a load-bearing decision should survive the session and remain inspectable later, without inventing documentation whose only purpose is to satisfy a process checklist. In a project that uses ADRs, an accepted ADR is never silently rewritten; a later record supersedes it. In a compact decision register, earlier decisions remain visible and later changes are recorded explicitly.
The ADR convention itself was adopted after lean-optimizer-public and several earlier
repositories had already been released, so I do not retroactively add ADRs merely to make older
projects look consistent with a later process. Ratchetloop, for example, uses a compact
decision register; the smaller
leetcode-python work sample relies on its design, plan, task files,
tests, and run evidence rather than a ceremonial ADR set.
The value isn't documentation for its own sake. It's being able to read what was believed at decision time - including the alternatives that were on the table and the reasons they lost. Editing the record to match today's opinion destroys exactly the thing that makes it useful six months later, when a model (or a person) is about to reopen a question that was already settled for reasons no longer visible in the code.
A companion convention covers plans - the working notes for a task in flight. Plans are freely editable right up until the first commit that references them lands; after that, changes are appended as dated updates, never edited in place. Every plan closes with an outcome line: shipped with commit hashes, abandoned with a reason, or superseded. That single line is what connects a session's work to the durable record instead of letting it evaporate when the session ends.
A guard against the obvious failure mode: decision-record theater is worse than no decision record. Routine choices, bug fixes, style, and deliberately simple repositories do not need ceremonial artifacts. A durable record is for decisions that are expensive to reverse, surprising to a future reader, or that rule out an alternative someone would otherwise reach for.
Verify external claims before they harden into documents
This is the rule I'd keep if I could keep only one. Don't assert how an external system behaves from memory when that claim is about to land in a durable document. APIs, framework defaults, broker constraints, library behavior - fetch the published source, cite the URL inline, and only then write it down. Plans seed code; durable decision records commit the codebase to a direction. A wrong assumption in either one multiplies into wrong implementation.
This rule didn't come from theory. It came from getting caught.
The incident this rule is named after
A plan to restructure part of the system committed to several confident claims about a third-party framework's behavior - all drawn from the model's memory, none verified. A first verification round found multiple wrong API and behavioral claims, and that the plan had missed the vendor's own primary recommendation for the exact scenario entirely.
A second round, checking the alternative the rewrite had dismissed, found that the dismissed option was in fact endorsed by the vendor's staff with code examples - and surfaced a serious operational hazard the earlier drafts hadn't mentioned. The same recall-from-memory failure caught us twice in one session, on one decision: first on the chosen path, then on the rejected one.
The decision record for that change now documents both rounds. The cost of skipping verification, written into the rule, scales with how load-bearing and durable the document is.
If I'd put it in a pull-request description for a reviewer, it's a decision record. If I'd whisper it to a colleague onboarding the project, it's a memory note.
Three kinds of memory, routed on purpose
An AI-assisted project accumulates knowledge in at least three places, and the failure mode is letting them blur. The cross-project assistant memory drifts toward project facts it shouldn't own; design decisions get stranded in a session log nobody reads again. So the routing is explicit:
| Belongs in session / assistant memory | Belongs in a decision record |
|---|---|
| How I want to collaborate - commit small, don't restart services without asking | Design decisions with consequences for the code itself |
| Who I am and what I'm building, across projects | Reasoning about this codebase a future reader will need |
| Handoff context - what's in flight, what just shipped | "We chose A over B because…" - including deliberate non-action |
Where a repository has a hard-rules file, it carries the terse what - the standing constraints a session must not break. Rules with real architectural reasoning point to the durable artifact that holds the why: an ADR, a decision register, a design document, or another project-appropriate record. The guardrail stays scannable; the argument stays available.
The same principle now applies to execution state. A delivery run should not depend on a chat
transcript or one model's memory of what happened. In
Ratchetloop, the branch, isolated worktree,
append-only event log, checks, review result, and result.json are the durable record.
If a worker dies, a later run can inspect and continue from that state. The evidence belongs to
the software process, not to the session that produced it.
The artifacts
The exact files vary by project. The discipline is not a fixed directory layout; it is keeping the important constraints, decisions, plans, tests, and run evidence durable enough to constrain later work.
| Hard-rules file | Standing constraints, terminology, architecture must-knows, and known gotchas a fresh agent session should read before changing the system. |
| Decision record | ADRs for large systems when the choice warrants them; a compact DECISIONS.md,
design document, or other durable record for smaller projects. |
| Plan / task contract | Working specification for substantive changes: objective, acceptance criteria, scope, executable checks, and the evidence needed to call the work complete. |
| tests/ | A non-trivial change is not done until its tests pass. New behavior and bug fixes land with coverage; bug fixes land with a regression test. The suite is part of the contract the worker's output has to satisfy. |
| Run evidence | For automated delivery, logs, check results, review findings, commits, provenance, and final dispositions survive the model session that produced them. |
Where this came from
These conventions were forged across systems where a wrong assumption can produce a plausible, wrong result rather than an obvious exception. Strategy Assayer made that problem impossible to ignore; product work and agent-delivery tooling generalized the lessons. The method now has both demanding application evidence in Strategy Assayer and a reusable public implementation in Ratchetloop.
Generated output stats available on request.