The Proposal-Driven Cycle

You're three hours into a feature. The conversation with your AI assistant has drifted through a dozen tool calls, a detour into a bug that wasn't part of the plan, two context switches you didn't notice happening. You scroll back to find the thing you originally asked for. The thread is too long. You start over, except now you can't quite remember what you'd already decided, or why.

This happens to everyone who codes with AI long enough. The work itself goes fine — the AI writes decent code, finds bugs, suggests approaches. What falls apart is the record. Two days later you're looking at 400 lines of authentication logic and you can't reconstruct the reasoning that got you there. The git diff tells you what changed. It tells you nothing about why, or what you considered and rejected, or which parts were deliberate and which were the AI improvising.

I've been building with AI assistants for long enough to have made this mistake many, many times. What follows is the system I landed on — not because I designed it, but because it kept emerging from the wreckage of sessions where I didn't have it.

The cycle

Four phases, one document per task:

Proposal — what are we building and why? This is the thinking-out-loud part. What problem exists, what approaches could work, what trade-offs matter. The AI is good at helping here: "look at these three options and tell me what breaks."

Plan — how, specifically? Steps, sequence, scope. Claude Code generates plans natively; the move is to capture them rather than let them vanish when the conversation ends.

Execute — build it. The normal part.

Record — what did we actually build? This is the part most people skip, and it's the part that saves you. Immediately after the work ships, you (or the AI) append an "As Implemented" section to the same document. What changed, what diverged from the plan, what got deferred.

The document lives in your project root with a name like SFRONT-v0.46-Build-for-Deploy.md. The naming matters more than you'd think.

Why the naming matters

SFRONT is the project prefix. v0.46 puts it in sequence. Build-for-Deploy tells you what it covers. This sounds like bureaucracy until you've worked on a codebase with sixty of these documents and you need to find the one where you decided how authentication works.

The sequence numbers mean relevance decays naturally — older docs drift to the bottom of any sorted listing. The prefix means the doc still makes sense if it moves between repos, or if your CLAUDE.md file gets rewritten for a new phase of the project. The short title means you can reference it in a prompt without thinking: "see SFRONT-v0.22 for the taxonomy decisions."

When a batch gets old enough to be archival, one command moves them:

git mv SFRONT-v0.{20..29}*.md docs/

They're out of the way but still in the repo, still in the git history, still findable.

Scaling to the task

Not every task needs the same weight of documentation. The system flexes:

Small tasks get a single document covering several changes. A config tweak, a dependency update, a build fix — they share a doc. The "As Implemented" section might be three lines.

Typical features get one document each. Proposal at the top, plan in the middle, record at the bottom. This is the default and covers maybe 70% of the work.

Complex initiatives get multiple documents, phased. When I needed test coverage across 207 source files, that became eight work packages, each tracked in its own version doc, sequenced by risk and dependency. Each package got its own "As Implemented" section as it completed.

The decision about which level to use is yours. It's a judgment call, not a rule. If you're reaching for multiple documents, the task is probably complex enough to justify it. If you're debating whether something needs its own doc, it probably doesn't.

Anti-goals earn their keep

One pattern that showed up in the more complex docs and proved unexpectedly useful: explicit anti-goals. Not just what you're building, but what you're deliberately not building.

From a real implementation plan:

Goals: Format compatibility, content preservation, DRY implementation, zero breaking changes.

Anti-Goals: NOT replacing v1.34 export. NOT supporting custom metadata. NOT supporting direct import.

Without anti-goals, scope creeps in through the side door. The AI suggests a natural extension. You think "that's reasonable" and say yes. Three of those and you're building something different from what you planned. Anti-goals give you a line to point at: we decided not to do that. Decided, past tense, when we were still thinking clearly.

What this actually solves

The prescriptive half of the document (proposal, plan) goes stale the moment implementation diverges. That's fine — it was never meant to stay current. It captures what you intended, which is exactly the thing that's hardest to reconstruct later.

The retrospective half (the record) can't go stale because it describes something that already happened. Together they give you a before-and-after that answers the questions you actually have when you're lost: what did I ask for, what did I agree to, what shipped, where did it diverge.

None of this is revolutionary. It's a naming convention and a habit of writing things down before and after. But the gap between "I should document my AI coding sessions" and actually having a system that you use every time — that gap is where most of the value lives. The system has to be cheap enough to use without thinking about it. A version doc with a three-part name and an appended record section clears that bar.

The alternative is your memory, and your memory is worse than you think it is.