plan-architecture

Architecture Planning

Step 1 — Discover conventions before designing

Read the codebase until you can answer: How are modules organized (by feature or by layer)? How do errors propagate? Where does validation live? How is the existing code tested? What naming style rules? Your design must read like the codebase's current author wrote it — deviations are review findings waiting to happen.

Step 2 — Compare options before choosing

For any non-trivial design decision, write 2–3 realistic options with trade-offs:

### Decision: <what>
- Option A: … | + simple, matches existing pattern X | − doesn't scale past Y
- Option B: … | + handles Y | − new dependency, more moving parts
→ Chosen: A, because Y is out of scope (see requirements).

Never present only one option — the first idea is rarely the best, and the comparison is what makes the plan reviewable. Tie every "chosen because" back to a confirmed requirement.

Step 3 — Define the contracts, then the component→files map

This is the step that makes the backlog sliceable and the review deterministic. Before writing tasks:

• Contract-first: pin down the seams between components — function/method signatures, data shapes (types/schemas), API request/response contracts, event/DB record shapes. Write them in PLAN.md concretely, not "a service that returns users". Once a boundary's contract is fixed, work on either side of it becomes independent and each task reviews against a stable contract instead of a moving target. Shared contracts (types, interfaces, schema/migration) become the FIRST tasks so everything downstream can build — and be reviewed — against them.
• Component → files map: for each component the change touches, list the exact files to create or modify. This is what the backlog slices along; keeping the per-component file sets disjoint is what later lets task-waves run tasks in parallel. Overlapping file sets = tasks that must serialize — call that out here.
• Codex is repo-blind: it sees only the prompt + files it opens. Name the exact existing files it should read for patterns (follow the shape of src/api/orders.ts), and spell out any repo-wide convention it can't infer from the task's files alone.