If you've used Claude Code, Codex, or Cursor for more than a few sessions, you've hit this: you explain the same architectural decision three times in three weeks, because the AI assistant that helped you make it the first time has no memory of that conversation anymore. Neither, six weeks later, do you.
That's not really an AI problem. It's a paper trail problem — the same one that existed before AI assistants, except AI-assisted development makes it worse, because decisions now get made and remade across dozens of short, disconnected sessions instead of a handful of long ones.
Most solo developers and small teams solve this with nothing at all. The alternative — adopting a full enterprise engineering process, with architecture review boards and change-control tickets — is wildly disproportionate for one person or a three-person team. What's missing is something in between: lightweight enough to actually use every day, structured enough that it survives your memory (and your AI's) resetting.
The four things that actually matter
After running this for months across real sessions, it comes down to four artifacts:
Architecture Decision Records (ADRs). One file per real decision: what was the problem, what options existed, what did you pick, why, and what would make you revisit it. The discipline isn't in the format — it's in writing down the rejected options and the reasoning, so "why didn't we just do X" has an answer that isn't "I don't remember."
Session reports. A short log at the end of each working session — what got done, what got decided, what's still open, and critically, a few sentences written for whoever opens the next session telling them exactly where things stand. This is the single highest-leverage artifact of the four. It's what replaces "let me re-explain the whole project" at the start of every session, human or AI.
A decision register. One running table indexing every ADR — status, date, one-line summary. "What did we decide about auth token expiry?" should be answerable by scanning one table, not grepping through a dozen files.
An engineering playbook. A short document defining how work actually moves — idea, design, approval, implementation, review, done — so an AI collaborator has a process to follow instead of improvising a different one every session.
Why this works better with AI assistants specifically
AI coding assistants are unusually good at using structured context if you hand it to them, and unusually bad at retaining it themselves. Point a fresh Claude Code or Codex session at your last session report and your decision register before you start, and it has in thirty seconds what would otherwise take you ten minutes of re-explaining — and it stops proposing solutions you already tried and rejected.
The failure mode to watch for is the opposite one: treating this as busywork and writing an ADR for every trivial choice. If everything becomes an ADR, nothing stands out as one. Write one when the decision is expensive to reverse, when two genuinely reasonable options existed, or when a future session (yours or the AI's) is likely to ask "why did we do it this way." Skip it otherwise.
Getting started
You don't need special tooling for this — four markdown files and a folder convention are the whole system, and it's tool-agnostic (works the same whether you're on Claude Code, Codex, Cursor, or nothing at all). You could rough out your own versions of the four artifacts this afternoon. If you'd rather start from templates that have already been refined across months of real use instead of drafting your own from a blank page, that's what I packaged into the AI Engineering Governance Kit. Either way — pick the four artifacts, write the first one today, and see if it's still paying for itself in a month.
Top comments (0)