Project
AGENT.md
A reusable planning methodology for building software with AI — two tracks, a small document set, and the disciplines that keep architectural control in human hands.
What it is
AGENT.md is a process I’ve refined over many projects for building medium-to-large software with AI coding assistants — without letting the AI quietly take the wheel on architecture. The trick: never let one AI both design and build. Design quality always loses to build velocity when they share a track.
So the work runs in two tracks that never merge — a planning track that designs and decides, and a coding track that executes one prepared phase at a time — glued together by a small set of living documents.
Updates
Build log
CLAUDE.md trim discipline
Added a soft 40k-character limit and the habit of moving tooling-specific notes to their own files, so the always-loaded rulebook stays focused on rules for writing code.
The two-track split
Settled the core idea — separate planning and coding tracks that never merge — and the stable document set that glues them together.
The file
AGENT.md, in full
Here’s the whole methodology as a single Markdown file. Drop it in your toolbox and start each project with a fresh CLAUDE.md written from scratch.
# AGENT.md — Planning Methodology for AI-Assisted Software Projects
> A reusable process for building medium-to-large software projects with AI coding assistants (Claude Code, Cursor, Cline, etc.) without losing architectural control. Designed for solo developers or small teams. Works for web apps, CLIs, libraries, anything with a multi-phase build.
>
> Refined over multiple foundation phases. Updated where the original methodology hit limits.
## The core idea
You do your software project in **two conversation tracks**:
- **Planning Claude** — a long-running chat where you design the system, make decisions, and write briefs. Nothing here runs code or writes implementation.
- **Coding Claude** — a separate CLI agent (Claude Code, for example) that executes one phase at a time against a prepared brief. Nothing here makes architectural decisions.
The tracks never merge. Planning Claude produces documents; Coding Claude reads them and writes code. When a phase is done, you return to Planning Claude with notes, and the next brief is written informed by what actually happened.
This separation is what makes the process work. An AI that's simultaneously designing and building will always trade design quality for build velocity, because that's the incentive gradient. Putting design on a different track with different pacing removes the trade.
## The two tracks
### Planning Claude
The architectural track. One long-running chat per planning context. Forces decisions through multiple-choice questions with named tradeoffs. Writes briefs. Updates the rulebook. Never writes code.
A good Planning Claude session feels like working with a careful, opinionated colleague who keeps asking "what about X?" until you can defend an answer. The output is documents that survive context resets — when the chat eventually maxes out or you put the project down for weeks, the documents carry the decisions forward.
### Coding Claude
The execution track. Fresh chat per phase. Reads the brief, builds, runs the acceptance checklist, writes phase notes, reports completion. Does not make architectural decisions; questions are sent back to Planning Claude.
A good Coding Claude session has a precise opening: read these files in order, give a numbered read-back of open questions and risks, wait for clearance before writing code. (More on this in the workflow section.)
## The document set
### Stable documents (edited rarely, deliberately)
1. **Product plan** (`plan.md` or similar). What the product is. Stage-level descriptions. Who uses each part, what each part does, what success looks like. No code, no schemas. Stable across the project.
2. **Decisions log** (`decisions.md`). ADR-style records of foundational choices: hosting, language stack, database, auth model, third-party services, localization scope. Each entry has date, status, context, decision, rationale, consequences. New decisions are appended; old ones are never edited even when superseded — a new entry references the old.
3. **Data model** (`data_model.md`). The nouns of the system and how they relate. Entity descriptions in prose plus one diagram. No column-level detail, no migrations, no types. Describes the shape of the world, not the schema.
4. **Key data contracts** (project-specific filenames). Wherever a central data structure or API contract has multiple components depending on it, it gets its own document. JSON shapes, IR formats, file schemas. More detailed than the data model — bugs here cascade.
5. **Sub-project plans** (when relevant). If one area of the project is substantially larger or riskier than the others, it gets its own planning document. Lives alongside the main docs and is referenced from the phase index.
6. **Phase index** (`phase_index.md`). One-page map of all phases. Each has a status (Pending / Ready / Done), a one-paragraph description, and pointers to its brief and notes files. Updated every time a phase finishes.
7. **Permanent rules file** (`CLAUDE.md`). The always-loaded context for Coding Claude. Pointer to the document hierarchy, phase discipline rules, immutable technical rules, ask-before-acting triggers, gotchas accumulated across phases, guidance on responding to the user.
### Per-phase documents (one set per phase)
Per-phase documents live in a dedicated `phases/` subfolder, not in the project root. Stable docs (plan, decisions, data model, phase index, CLAUDE.md) stay in root; the `phases/` folder contains only the brief+notes pairs that accumulate one per phase. Keeps the root navigable as the project grows past ~10 phases.
1. **Build brief** (`phases/phase_<n>_brief.md`). Specification for one phase. Written before the phase starts.
2. **Build notes** (`phases/phase_<n>_notes.md`). Written after the phase finishes. The bridge to the next phase.
### Auxiliary documents
When something falls outside the categories above, give it its own file rather than bloating one of the stable docs. Examples:
- `docs/browser_testing.md` — testing-tooling notes (synthetic event constraints, drag-event quirks). Lives outside `CLAUDE.md` so the always-loaded context stays focused on rules-for-writing-code.
- Audit documents (e.g., `dashboard_audit.md`) — read-only inventories of existing surfaces, written before a phase that restructures them.
## The workflow
### Phase 0 — planning
Before any code is written:
1. **Describe the product** in rough terms to Planning Claude. Accept pushback.
2. **Go through the decision questions.** Planning Claude presents multiple-choice questions at every architectural fork. Each gets answered before moving on. Don't defer decisions "until we need them" — the act of deciding forces the plan to be concrete.
3. **Write the stable document set.** Plan, decisions, data model, contracts.
4. **Write the phase index** — first pass at how the build decomposes into phases. Will be revised; the first pass doesn't have to be perfect.
5. **Write the Phase 1 brief** — usually scaffolding (repo layout, Docker, DB boot, framework stubs). Small, verifiable, no business logic.
6. **Write `CLAUDE.md`** — initial rulebook. Will grow; the first version should be opinionated about stack, conventions, and the ask-before-acting list.
### Phase N — execution
1. **Fresh Coding Claude session.** New chat, new context. Don't reuse the previous phase's session; the context will be polluted with completed work.
2. **Give the opening prompt.** Tell it which documents to read in what order. Demand a numbered read-back of open questions and risks before any code.
> We're starting Phase N of <project>. Before you write any code, read:
> 1. `CLAUDE.md`
> 2. `phase_index.md`
> 3. Every prior `phases/phase_<k>_notes.md`
> 4. The relevant stable docs for this phase
> 5. `phases/phase_<n>_brief.md`
>
> Before writing any code, read back to me your numbered open questions and risks (Q1, Q2, …, R1, R2, …). I'll answer each. Don't start coding until I confirm.
3. **Answer the read-back.** This is the cheapest error-correction point in the whole cycle. Several real bugs get caught here: misread tokens, misunderstood schemas, wrong defaults, conflicting conventions. Answer each numbered question explicitly; don't skip any.
4. **Let it build.** Watch for off-scope work; interrupt early if you see it.
5. **Let it run the acceptance checklist.** Don't accept a phase as done until the checks have actually been executed, not merely "should pass."
6. **Get the notes file.** Either Coding Claude writes it, or you write it after a brief post-mortem. Don't skip this — it's the bridge to phase N+1.
7. **Return to Planning Claude.** Share the notes. Update `CLAUDE.md` with new gotchas. Update the phase index to mark N done. Answer scoping questions for phase N+1.
8. **Write the phase N+1 brief.** Repeat.
## The asking discipline
Planning Claude's job is to force decisions, not to make them. Every architectural fork becomes a multiple-choice question with tradeoffs named. You choose; the document records the choice with rationale.
Questions are small, binary or 3–4-option, and mutually exclusive. "Do you want X or Y?" is a good question. "How should we design the auth system?" is a bad question — it's open-ended and the answer will be vague.
Good decision-prompting questions:
- "Which URL structure at launch: path-based, subdomains, or custom domains?"
- "Where should uploaded files live: local disk, S3-compatible, or self-hosted MinIO?"
- "Should the editor support HTML template editing from day one, or is that a later phase?"
Each question is accompanied by: the tradeoffs of each option, a recommendation, and the cost of changing the answer later. This lets you decide fast while understanding what you're trading.
## The scope discipline
Scope creep is the primary failure mode of AI-assisted work. The AI, left to its own devices, will build adjacent-seeming features because they feel obvious. Two mechanisms prevent this:
1. **Explicit non-goals in every brief.** Longer lists are better. Each line prevents an hour of off-scope work.
2. **Ask-before-acting triggers in `CLAUDE.md`.** New tables, new dependencies, new env vars, architectural patterns, touching auth or payment code — all require confirmation. This isn't suspicion; it's the human-in-the-loop where it matters most.
When the AI asks a genuine scoping question mid-phase, that's the discipline working. Answer, and fold the answer into the brief so the context survives a session reset.
## The gotchas discipline
Every non-trivial project discovers infrastructure quirks mid-build. Docker oddities, framework behaviours, tooling interactions, environment issues. Each one, once hit, gets captured in `CLAUDE.md` as a numbered gotcha with:
- The symptom.
- The cause.
- The fix or workaround.
- Which phase discovered it.
The habit: every time you think "we should remember this," add it to `CLAUDE.md`. Future phases inherit the learning automatically because `CLAUDE.md` is always loaded.
### When `CLAUDE.md` gets too big
`CLAUDE.md` grows over the project. Every gotcha discovered mid-build adds one entry. At some point — for one reference project, around 48k characters — performance degrades or context budgets bite. Trim discipline:
1. **Move tooling-specific notes to their own files.** Browser-automation testing constraints, CI quirks, etc. — these aren't "rules for writing code," they're "constraints when running tests." Lives in `docs/browser_testing.md` or similar. Coding Claude reads them when doing the task that needs them.
2. **Compress long gotchas to rule + why + fix essentials.** Full debugging walkthroughs and code examples live in the phase notes (which are linked from the gotcha entry). The CLAUDE.md entry just tells future Coding Claude *what to avoid* and *why*. The full debugging context is one filename away.
3. **Fold sub-notes into their parent gotcha.** Avoid maintaining standalone "Note on Gotcha 25" sections that accumulate sub-bullets — they grow unbounded and live next to the gotcha they extend. Compress and merge.
The 40k character mark is a useful soft limit. When you cross it, schedule a trim pass before the next phase.
## When to revise stable documents
The stable documents (plan, decisions, data model, contracts) should be edited rarely and deliberately. Legitimate reasons:
- **Scope change.** The product direction has shifted; the plan needs to reflect it.
- **Decision reversal.** A foundational choice was wrong; a new dated entry in `decisions.md` supersedes the old (the old one is not deleted).
- **Contract evolution.** A key data structure needs a new version. The contract document describes both versions and the migration.
- **New sub-project.** A chunk of work turns out to be bigger than a single phase; a sub-project plan is written and the phase index is updated.
Illegitimate reasons:
- **Mid-phase "oh we should note this."** Add it to `CLAUDE.md` or the phase notes, not the stable docs.
- **The AI suggesting an edit.** `CLAUDE.md`'s ask-before-acting list should include "editing the stable documents." The AI shouldn't touch them without permission.
## When to split or combine phases
If a phase starts feeling too big in the brief-writing stage — too many non-goals, too many distinct risk areas, acceptance criteria getting unwieldy — split it.
Heuristics for splitting:
- More than ~16 build steps in scope → probably two phases.
- Two genuinely independent risk profiles (e.g., auth + payments) → split, so a problem in one doesn't block the other.
- The acceptance checklist has more than ~30 items → probably two phases.
- The brief crosses ~700 lines → either too detailed (some content belongs elsewhere) or too big (split).
Splitting is cheap at the planning stage and expensive mid-build. Err toward splitting when in doubt.
## Anti-patterns
- **Writing all the briefs up front.** They'll be wrong. Phase N's brief should be informed by Phase N-1's notes.
- **Letting Coding Claude edit the stable documents without permission.** Even accurate edits this way normalize a pattern where the AI assumes document ownership.
- **Skipping the read-back summary.** Every phase's opening prompt should demand a numbered read-back of open questions and risks before coding. Every time. This is the cheapest defect-catching point in the cycle.
- **Skipping the acceptance checklist.** "Should work" is not "works." The checklist runs, or the phase isn't done.
- **Reusing a Coding Claude session across phases.** The context fills up with Phase N's work; the AI treats it as canonical when starting Phase N+1. Fresh session per phase.
- **Not writing notes.** Without notes, Phase N+1 will assume the brief is canonical. Drift between brief and reality compounds.
- **Deferring decisions "until we need them."** Deferred decisions become mid-phase interruptions that stall builds. Decide up front, even if imperfectly — imperfect decisions can be reversed in `decisions.md` with a new entry.
- **Writing massive briefs.** If a brief is over ~700 lines, something's wrong — either the phase is too big (split it), the brief has implementation detail that belongs in code (move it), or context that belongs elsewhere (move it).
- **Letting `CLAUDE.md` grow unbounded.** Past the soft 40k mark, schedule a trim pass.
## What this methodology costs
Roughly 25–35% of total project time goes into planning documents and briefs rather than code. For small solo projects this is too much overhead; use a lighter process. For anything with a multi-week lifecycle, the overhead pays back because:
- The AI produces much less wasted work.
- You catch design mistakes before they're in code.
- The project has its own documentation from the start, rather than as an afterthought.
- Onboarding another person is genuinely possible.
- You can put the project down for weeks and come back with full context.
## Starting a new project with this methodology
1. Start a Planning Claude chat. Describe the product in a paragraph.
2. Accept pushback. Clarify.
3. Go through decision questions one at a time.
4. Write the stable document set.
5. Write the phase index — a rough decomposition.
6. Write `CLAUDE.md` — initial rulebook.
7. Write the Phase 1 (scaffolding) brief.
8. Open Coding Claude with the opening prompt template.
9. Build Phase 1. Collect notes.
10. Return to Planning Claude. Repeat.
That's the whole thing. Everything else is iteration on the same loop.
## Quick reference — file inventory at any point in a project
After Phase N is complete, the project should have:
```
plan.md # stable, edited rarely
decisions.md # stable, append-only
data_model.md # stable
<contract>.md # one or more, stable
phase_index.md # updated each phase
CLAUDE.md # always-loaded; grows with gotchas
phases/ # all per-phase brief+notes pairs
phase_1_brief.md phase_1_notes.md
phase_2_brief.md phase_2_notes.md
...
phase_N_brief.md phase_N_notes.md
# Auxiliary files as needed:
docs/browser_testing.md # tooling notes
<audit>.md # read-only inventories
```
`CLAUDE.md` lists the stable documents at the top so Coding Claude knows where to look. Planning Claude reads everything; Coding Claude reads what `CLAUDE.md` directs it to read.
## On the "AGENT.md" file itself
This document is the methodology, not the project. It doesn't live in the project repo (where it would be misread as a project document); it lives outside, in your toolbox of process artifacts. Every new project starts with a fresh copy and the project's own `CLAUDE.md` written from scratch.
Update this file when a project teaches you something the methodology didn't have. Treat it as a living artifact — the kind of document that gets a little better every project.