Architecture Plan
Every architecture decision that stays in conversation history will be lost on the next session. This phase is about exploring the codebase and writing decisions to files — architecture plans, ADRs, CLAUDE.md — so every future session inherits them.
Phase 1 worked entirely with human-sourced input — meeting transcripts, customer feedback, stakeholder priorities. You didn't need to read a single line of code to synthesize requirements, write user stories, or decompose the backlog. The previous page in this phase (writing and validating the ACTIVE unit's spec) touched the codebase only lightly — enough to reference existing patterns. Architecture is different: it requires deep understanding of what already exists.
TaskFlow is a brownfield project — a working API with routes, handlers, and a data layer already in place. Before proposing where the new feature fits, Claude needs to understand the existing patterns. This is the first point in the curriculum where codebase exploration becomes critical.
| Phase | Codebase needed? | Why |
|---|---|---|
| Phase 1: Synthesize, prioritize, stories, backlog | No | Working with human-sourced input — requirements exist independently of code |
| Phase 2: Write the spec | Light | Spec references existing patterns, file structure, tech constraints |
| Phase 2: Architecture exploration | Critical | Cannot design without understanding existing routes, middleware, data layer, error handling |
| Phase 3: Implementation | Embedded | Claude reads code naturally as part of implementing — exploration is part of the workflow |
Codebase exploration isn't a one-time event. Each phase needs different depth. Phase 2 spec writing needs enough awareness to reference existing patterns. Phase 2 architecture needs deep structural understanding. Phase 3 implementation reads specific files as needed. The depth increases as you move from "what to build" to "how to build it."
When you ask Claude to explore the codebase before proposing architecture, it reads 5–10 files: route definitions, existing middleware, the data layer, error handling patterns, package.json dependencies. You'll see the agentic loop from Workshop 1 in action — Claude reads a file, decides what else it needs, reads another file, synthesizes its understanding, then proposes.
The key is to explore WITH PURPOSE. Don't ask Claude to "explore the codebase" in the abstract — ask it to "explore the codebase to understand where validation fits." Purpose-driven exploration is faster and produces more relevant architecture recommendations.
You just wrote and validated the ACTIVE unit's feature spec on the previous page. That file is the complete input for the architecture work below. Claude will read it, then explore the codebase, then propose where and how the feature fits.
The validated spec lives at docs/specs/task-comments.md. If you skipped ahead, scroll through it to see what a validated spec looks like before it becomes an architecture plan — requirements, user stories, acceptance criteria, and the full feature scope.
You have a validated spec at docs/specs/task-comments.md from the previous page. The TaskFlow API exists with routes, handlers, and JSON storage. Your job is to figure out WHERE and HOW the feature fits.
Step 1: Ask Claude to explore the codebase and propose an architecture plan.
Tell Claude:
Read the feature spec at docs/specs/task-comments.md.
Then explore the existing codebase — routes, middleware, handlers,
data layer, error handling patterns.
Based on what you find, write an architecture plan to
docs/architecture/task-comments.md covering:
- Current codebase structure (what you found)
- Where the new feature fits in the existing architecture
- Trade-offs for each approach you considered
- Recommended approach with rationale
- Impact on existing endpoints and data model
- Request/response shapes for new and affected endpoints
- Any concerns or questions for my review
Do not implement anything yet.Observe: Claude reads 5–10 files before writing the plan. It explores routes, data layer, middleware, and error patterns. Expect two outputs: (1) the architecture plan in docs/architecture/task-comments.md and (2) a list of open questions for your review — things like error format choices, test framework preference, or edge case handling. This is a good sign: Claude is flagging decisions that need human judgment rather than guessing.
Step 2 (only if Claude came back with questions): You have two options: (1) Answer them directly — "use vitest for testing, validate required fields first" — or (2) tell Claude to resolve them itself based on the codebase. Option 2 works surprisingly well and saves time. Either way, review the architecture plan — does the approach make sense? Is anything over-engineered? If Claude didn't raise any open questions, skip this step and move on.
Tell Claude:
I reviewed the architecture plan in docs/architecture/task-comments.md.
Address the concerns and open questions you raised —
resolve them the way you see fit based on the codebase.
If anything was over-engineered, simplify.
Update the plan in place.Observe: Claude re-reads the plan, resolves its own open questions with concrete decisions, and updates the file. This is the review-and-adjust pattern from Phase 1 — Claude proposes, you direct, the file captures the decision. Check that the concerns section is gone or resolved, not just acknowledged.
This is the first time Claude needed deep codebase understanding to do its job well. Phase 1 transformations worked from human input alone. Architecture requires reading the actual code. The quality of this plan directly depends on how thoroughly Claude explored — and you can verify by checking whether its recommendations match what you know about the codebase.
This is the full architecture plan Claude wrote after exploring the codebase. Notice the structure: it starts with what it found (current codebase analysis), identifies the key trade-off (three approaches to validation), recommends one with rationale, then details the error format, request/response shapes, and implementation plan. This is 500 lines of design that would have taken hours to write manually.
The completed architecture plan lives at docs/architecture/task-comments.md. It contains the codebase analysis, trade-offs, chosen approach, error format, response shapes, and implementation plan — the full design input for Phase 3.