Skip to main content

Plan Phase - Architecture Decisions and ADRs

With your specification complete, you now face a new question: How will you actually build it? This is the essence of the Plan Phase - transforming the ‘What’ of your specification into the ‘How’ of architecture and implementation strategy.

/sp.plan generates an implementation plan that breaks your specification into:

  • Architectural components (core library, error handlers, type system, tests)
  • Implementation phases (build operations first, then tests, then documentation)
  • Dependencies (what must be built before what)
  • Design decisions (which ones matter enough to document)

This lesson teaches you how to work with generated plans and how to capture important architectural decisions using ADRs (Architectural Decision Records).

Understanding the /sp.plan Command​

/sp.plan analyzes your specification and generates a detailed implementation plan by:

  1. Breaking spec into components - Which parts of your spec need separate modules?
  2. Ordering dependencies - What must be built first?
  3. Identifying design decisions - Where are there multiple valid approaches?
  4. Proposing architecture - How should code be organized?

Input: Your specification (what the calculator must do)

Output: Implementation plan with:

  • Architecture overview
  • Implementation phases
  • Component breakdown
  • Dependencies and sequencing
  • Design decisions highlighted

The Cascade Effect: Detailed spec → detailed plan. Vague spec → vague plan.

💬 AI Colearning Prompt​

"Why does the Plan phase generate implementation strategy for ALL operations at once instead of planning each operation separately? What consistency benefits does this provide?"

Generating Your Implementation Plan​

Let's generate the plan for your calculator.

Step 1: Run /sp.plan​

In Claude Code, from your calculator-project directory:

/sp.plan

Create: architecture sketch, interfaces, data model, error handling, requirements.
Decisions needing: list important choices with options and tradeoffs.
Testing strategy: unit + integration tests based on acceptance criteria.

Technical details:
- Use a simple, functional approach where it makes sense
- Use Python 3.12+ type hints with | union syntax
- Follow TDD: write tests first, then implementation
- Organize code and tests according to your constitution rules

Agent Does:

  • Creates technical implementation plan
  • Defines data models and interfaces
  • Establishes testing strategy
  • Identifies architectural decisions
  • Generates quick-start.md and plan.md files

Why This Matters: The plan defines technical architecture for ALL operations at once. This ensures consistency - same type hints, same error handling, same testing approach. Much more efficient than planning each operation separately!

Step 2: Review Generated Plan​

The generated plan should include:

  • Architecture Overview: How code will be organized (one module? multiple? class-based?)
  • Implementation Phases: 3-5 phases building from simple to complex
  • Component Breakdown: Core operations, error handling, type validation, tests, docs
  • Sequencing: Operations before tests? Validation before operations?
  • Design Decisions: Where are there choices? (Class vs functions? Exception types? Precision handling?)

Understanding ADRs (Architectural Decision Records) (20 minutes)​

Planning exposes architectural decisions - choices about how to build that have long-term consequences.

What Is an ADR?​

An ADR documents:

  • The Decision: What choice did you make?
  • The Context: Why did you need to make this choice?
  • The Alternatives: What other options existed?
  • The Rationale: Why did you choose this over alternatives?
  • The Consequences: What are the long-term impacts?

When Should You Create an ADR?​

Create an ADR when:

  • The decision has long-term impact (affects code structure, not just style)
  • Multiple valid alternatives existed (not an obvious choice)
  • Future developers will question the decision
  • The decision constrains future choices (e.g., choosing a data structure)

Don't create ADRs for:

  • Style choices (naming conventions, formatting)
  • Obvious choices (of course we use Python!)
  • Temporary decisions (will revisit in 6 months)
  • Out-of-scope decisions (already decided by Constitution)

Creating ADRs for Your Calculator Plan​

Now let's identify and document the architectural decisions from your calculator plan.

/sp.adr review the generate plan and record key Architectural Decisions.

It will review the plan and record key architectural decisions in history/adr directory.

🎓 Expert Insight​

In AI-native development, ADRs aren't documentation debt—they're future leverage. When a teammate (or AI agent) asks "Why did we use ValueError instead of custom exceptions?", you point to the ADR. When requirements change and someone questions the architecture, the ADR explains the original constraints and tradeoffs. ADRs save hours of archaeological code reading by preserving the "why" alongside the "what."

🤝 Practice Exercise​

Ask your AI: "I've generated an implementation plan for my calculator. Can you review specs/calculator/plan.md and help me identify: (1) Which 2-3 decisions are architecturally significant (long-term impact, multiple alternatives, future questioning)? (2) Which decisions are trivial and don't need ADRs? (3) For one significant decision, what alternatives exist and what are the tradeoffs? Then help me draft an ADR for that decision."

Expected Outcome: Your AI should identify significant decisions (e.g., exception strategy, function vs class-based design, precision handling) versus trivial ones (e.g., naming conventions from Constitution), explain tradeoffs for each alternative, and help structure an ADR with clear context, decision, consequences, and alternatives sections.

Common Mistakes​

Mistake 1: Documenting Every Small Decision as ADR​

The Error: Creating ADRs for trivial choices like "Use snake_case for functions" or "Put tests in tests/ folder"

Why It's Wrong: ADRs are for architecturally significant decisions (long-term impact, multiple alternatives, future questioning). Trivial choices clutter your ADR history.

The Fix: Apply the three-part test:

  • Does this have long-term consequences?
  • Are there multiple viable alternatives?
  • Will someone ask "why did we choose this" in 6 months?

If not all three → Skip the ADR.

Mistake 2: Vague ADR Consequences​

The Error: ADR says "This approach is better" without explaining tradeoffs

Why It's Wrong: Future developers need to understand why you chose this and what you gave up.

The Fix: Document both positives and negatives:

  • ✅ "Pros: Simpler error handling. Cons: Less precise error messages for users."
  • ✅ "Alternatives considered: Exception hierarchy (rejected: overkill for 5 operations)"

Try With AI​

Ready to validate your implementation plan and architectural decisions? Test your planning work:

🔍 Explore Plan Completeness:

"Review my implementation plan at specs/calculator/plan.md. Does it address all requirements from the specification? Are the implementation phases in logical order? Identify any gaps: missing components, unclear dependencies, or phases that need more detail. Compare the plan against the spec to verify nothing was missed."

🎯 Practice ADR Evaluation:

"I created ADRs for my calculator project documenting [describe your decisions]. Evaluate each ADR: (1) Is this decision architecturally significant (affects multiple components or long-term maintainability)? (2) Does the ADR explain WHY this choice over alternatives? (3) Are trade-offs clearly documented? (4) What critical decisions am I missing that should have ADRs?"

🧪 Test Plan-to-Tasks Readiness:

"Based on my plan at specs/calculator/plan.md, simulate breaking it into tasks. For each implementation phase, can you create 3-5 atomic tasks? If you struggle to create clear tasks, identify which parts of my plan are too vague or need more detail. This tests if my plan is detailed enough for the Tasks phase."

🚀 Apply to Your Project:

"I'm planning [describe your project]. Help me identify architecturally significant decisions that need ADRs. For my project type, what decisions typically affect: (1) Long-term maintainability? (2) Multiple components? (3) Team coordination? (4) Technical debt? Draft an ADR template for my most critical decision."