You have an approved specification scoring ≥75/100 defining WHAT to build. But there's a gap before creating executable tasks. You need to answer HOW:
- Which components are required?
- How do they interact?
- What database changes are needed?
- Which existing code do we integrate with?
This is the technical plan - the bridge between specification and task decomposition.
A technical plan translates functional requirements into concrete technical decisions. It has 7 key sections.
Why: Prevents conflicting assumptions about layer responsibilities, duplicate validation, and architectural drift.
Common mistakes: Reversed dependencies (Service→API), skipping layers (API→DB), ambiguous validation location.
How to decide: Start from entry point → follow data transformations → identify decision points → validate against CLAUDE.md.
Why: Prevents N+1 queries, missing constraints, orphaned records, and performance issues.
Common mistakes: No indexes, missing NOT NULL, undefined relationships, ambiguous column types.
How to decide: Indexes for query patterns, NOT NULL for required data, relationships for navigation, FKs for referential integrity.
Why: Prevents inconsistent error codes, missing authorization, and security vulnerabilities.
Common mistakes: No error codes specified, missing authorization, unclear dependencies, ambiguous response formats.
How to decide: RESTful paths, map exceptions to HTTP status, specify all dependencies, check authorization before service layer.
Why: Prevents files in wrong directories, forgotten tests/migrations, and merge conflicts.
Common mistakes: Only listing new files, no test structure, missing migrations, incorrect paths.
How to decide: Follow existing structure, one file per concern, test mirrors production, list all modifications.
Why: Prevents reinventing functionality, breaking patterns, and import cycles.
Common mistakes: Creating new auth, direct DB access, custom error handling, ignoring CLAUDE.md patterns.
How to decide: Scan CLAUDE.md first → review existing models → check api/ for utilities → validate compliance.
Why: Prevents inadequate coverage, untested authorization, and missing edge cases.
Common mistakes: "Write some tests", no coverage targets, only unit OR integration, no error case testing.
How to decide: One test file per production file, repositories 95%+, services 90%+, APIs 85%+, test authorization and validation critically.
Why: Prevents authorization bypasses, injection attacks, and data leaks.
Common mistakes: No authorization, missing validation, raw SQL, returning ORM objects directly.
How to decide: Check authorization in service layer, validate all inputs, use ORM, always use Pydantic schemas, exclude sensitive fields.
Rule: Enough to make task decomposition obvious, but not implementation code.
❌ Too sparse: "Create comment system with FastAPI" → Can't decompose without guessing
❌ Too verbose: Full implementation code → This IS the code, not a plan
✅ Just right: "POST /api/tasks/{id}/comments, Router: src/api/comments.py, Dependencies: current_user + comment_service, Errors: 400/401/403/404" → Clear decisions, ready for tasks
Before task decomposition, validate:
- ✅ Follows repository pattern (API → Service → Repository → DB)
- ✅ Uses dependency injection
- ✅ Uses existing models/patterns from CLAUDE.md
- ✅ All components specified
- ✅ Can decompose into clear tasks
When to skip:
- Trivial changes (one field, simple bugs)
- Exploratory spikes
Always create for:
- New components/tables
- Multi-component features
- Architectural changes
Generating with Claude:
Technical plans bridge specification (WHAT) → task decomposition (executable work).
7 Required sections:
- Architecture - Component flow and data transformations
- Data Model - Schemas, constraints, indexes, relationships
- API - Endpoints, dependencies, errors, authorization
- Module Structure - New/modified files, tests, migrations
- Integration Points - Existing code to reuse
- Testing - Coverage targets by layer
- Security - Authorization, validation, data protection
Each section teaches:
- What to specify
- Why it matters
- Common mistakes
- Decision framework
Right detail level: Specific enough for task decomposition but not implementation code. Always validate against CLAUDE.md before proceeding.
