AI coding assistants are fast — and left to their own devices, they’ll happily build the wrong thing, beautifully. AGENT.md is the process I use to keep architectural control while the AI writes the code.
The problem is simple: when a single AI both designs and builds, design quality always loses to build velocity — that’s just the incentive gradient. So I split the work into two tracks that never merge.
The core idea — two tracks
Planning Claude is a long-running chat that designs the system, forces decisions, and writes briefs — but never writes code. Coding Claude is a fresh CLI agent, one per phase, that reads a brief, builds exactly that, and writes notes — but never makes architectural decisions. Planning produces documents; Coding reads them and writes code. When a phase finishes, the notes go back to Planning, and the next brief is written knowing what actually happened.
The documents
The whole thing runs on a small, deliberate set of files:
plan.md— what the product is, at stage level. Stable.decisions.md— an append-only log of foundational choices (hosting, stack, auth…). Old entries are never edited, only superseded.data_model.md— the nouns of the system and how they relate, plus one diagram.phase_index.md— a one-page map of every phase and its status.CLAUDE.md— the always-loaded rulebook for Coding Claude: conventions, gotchas, and ask-before-acting triggers.phases/phase_N_brief.md+notes.md— one pair per phase.
The stable docs are edited rarely and on purpose; the briefs and notes accumulate one pair per phase. The documents are what survive a context reset — when a chat maxes out or I put the project down for weeks, they carry the decisions forward.
The loop
Every phase is the same loop: write the brief, start a fresh coding session, and demand a numbered read-back of open questions and risks before any code is written. That read-back is the cheapest place in the whole cycle to catch a bug — misread tokens, wrong defaults, conflicting conventions all surface here. Then let it build, run the acceptance checklist for real (“should pass” is not “passes”), capture the notes, and carry those into the next brief.
The disciplines that make it work
Asking. Planning Claude’s job is to force decisions, not make them. Every fork becomes a small multiple-choice question with the tradeoffs and the cost-of-changing-later spelled out. You decide fast; the document records the choice and the reasoning.
Scope. Scope creep is the number-one failure mode of AI-assisted work. Two guards keep it out: explicit non-goals in every brief (longer lists are better — each line prevents an hour of off-scope work), and ask-before-acting triggers in CLAUDE.md — new tables, new dependencies, touching auth or payments — that require a human yes.
Gotchas. Every infrastructure quirk discovered mid-build gets captured in CLAUDE.md as a numbered gotcha: symptom, cause, fix, and which phase found it. Future phases inherit the learning automatically, because CLAUDE.md is always loaded.
What it costs
Roughly a quarter to a third of project time goes into planning documents and briefs instead of code — and it pays for itself quickly: far less wasted AI work, design mistakes caught before they reach the codebase, real documentation from day one, and the ability to put the project down for weeks and return with full context.
This isn’t just theory. I built aidesign — a local, single-user tool where Claude generates live-previewed HTML/CSS mockups you shape by chatting — with exactly this method; the repo still carries its plan.md, decisions.md, and per-phase notes. A full write-up of that project is coming soon.
It’s a living document — every project teaches it something the methodology didn’t have yet. This is the short version; you can also find the full file on the AGENT.md project page.
Leave a Reply