Writing Plans
Overview
Write comprehensive implementation plans assuming the engineer has zero context for the codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
Assume they are a skilled developer, but know almost nothing about the toolset or problem domain. Assume they don't know good test design very well.
Core principle: Plans must be executable without asking questions.
The Iron Law
NO VAGUE STEPS - EVERY STEP IS A SPECIFIC ACTION
"Add validation" is not a step. "Write test for empty email, run it, implement check, run it, commit" - that's 5 steps.
Bite-Sized Task Granularity
Each step is one action (2-5 minutes):
-
"Write the failing test" - step
-
"Run it to make sure it fails" - step
-
"Implement the minimal code to make the test pass" - step
-
"Run the tests and make sure they pass" - step
-
"Commit" - step
Not a step:
-
"Add authentication" (too vague)
-
"Implement the feature" (multiple actions)
-
"Test it" (which tests? how?)
Plan Document Header
Every plan MUST start with this header:
[Feature Name] Implementation Plan
For Claude: REQUIRED: Follow this plan task-by-task using TDD. Design: See
docs/plans/YYYY-MM-DD-<feature>-design.mdfor full specification.
Goal: [One sentence describing what this builds]
Architecture: [2-3 sentences about approach]
Tech Stack: [Key technologies/libraries]
Prerequisites: [What must exist before starting]
If a design document exists, always reference it in the header.
Task Structure
Task N: [Component Name]
Files:
- Create:
exact/path/to/file.ts - Modify:
exact/path/to/existing.ts:123-145 - Test:
tests/exact/path/to/test.ts
Step 1: Write the failing test
test('specific behavior being tested', () => {
const result = functionName(input);
expect(result).toBe(expected);
});
Step 2: Run test to verify it fails
Run: npm test tests/path/test.ts -- --grep "specific behavior"
Expected: FAIL with "functionName is not defined"
Step 3: Write minimal implementation
function functionName(input: InputType): OutputType {
return expected;
}
Step 4: Run test to verify it passes
Run: npm test tests/path/test.ts -- --grep "specific behavior"
Expected: PASS
Step 5: Commit
git add tests/path/test.ts src/path/file.ts
git commit -m "feat: add specific feature"
## Context is King (Cole Medin Principle)
**The plan must contain ALL information for a single-pass implementation.**
A developer with zero codebase context should be able to execute the plan WITHOUT asking any questions.
### Context References Section (MUST READ!)
**Every plan MUST include a Context References section:**
```markdown
## Relevant Codebase Files
### Patterns to Follow
- `src/components/Button.tsx` (lines 15-45) - Component structure pattern
- `src/services/api.ts` (lines 23-67) - API service pattern
### Configuration Files
- `tsconfig.json` - TypeScript settings
- `.env.example` - Environment variables needed
### Related Documentation
- `docs/architecture.md#authentication` - Auth flow overview
- `README.md#running-tests` - Test commands
Why: Claude forgets context. External docs get stale. File:line references are always accurate.
Validation Levels
Match validation depth to plan complexity:
Level
Name
Commands
When
1
Syntax & Style
npm run lint
, tsc --noEmit
Every task
2
Unit Tests
npm test
Low-Medium risk
3
Integration Tests
npm run test:integration
Medium-High risk
4
Manual Validation
User flow walkthrough
High-Critical risk
Include specific validation commands in each task step.
Requirements Checklist
Before writing a plan:
- Problem statement clear
- Users identified
- Functional requirements listed
- Non-functional requirements listed (performance, security, scale)
- Constraints documented
- Success criteria defined
- Existing code patterns understood
- Context References section prepared with file:line references
Risk Assessment Table
For each identified risk:
Risk
Probability (1-5)
Impact (1-5)
Score
Mitigation
API timeout
3
4
12
Retry with backoff
Invalid input
4
2
8
Validation layer
Auth bypass
2
5
10
Security review
Score = Probability × Impact. Address risks with score > 8 first.
Risk-Based Testing Matrix
Match testing depth to task risk:
Task Risk
Example
Tests Required
Trivial
Typo fix, docs update
None
Low
Single file change, utility function
Unit tests only
Medium
Multi-file feature, new component
Unit + Integration tests
High
Cross-service, auth, state management
Unit + Integration + E2E tests
Critical
Payments, security, data migrations
All tests + Security audit
How to assess risk:
- How many files touched? (1 = low, 3+ = medium, cross-service = high)
- Is it auth/payments/security? (always high or critical)
- Is it user-facing? (medium minimum)
- Can it cause data loss? (high or critical)
Use this matrix when planning test steps. Don't over-test trivial changes. Don't under-test critical ones.
Functionality Flow Mapping
Before planning, document all flows:
User Flow:
1. User clicks [button]
2. System shows [form]
3. User enters [data]
4. System validates [input]
5. System saves [data]
6. System shows [confirmation]
Admin Flow:
1. Admin opens [dashboard]
2. Admin selects [item]
3. System shows [details]
4. Admin changes [setting]
5. System applies [change]
System Flow:
1. Request arrives at [endpoint]
2. Middleware validates [auth]
3. Controller calls [service]
4. Service queries [database]
5. Response returns [data]
Architecture Decision Records (ADR)
When comparing approaches, document the decision formally:
Use this format when a plan involves choosing between multiple valid approaches:
## ADR: [Decision Title]
**Context:** What situation or requirement prompted this decision?
**Decision:** What approach did we choose?
**Consequences:**
- **Positive:** [benefits of this choice]
- **Negative:** [tradeoffs we accept]
- **Alternatives Considered:** [what we didn't choose and why]
When to use ADR:
- Choosing between architectures (monolith vs microservices)
- Selecting libraries/frameworks (React vs Vue)
- Database decisions (SQL vs NoSQL)
- Authentication approaches (JWT vs sessions)
Save ADRs to: docs/decisions/ADR-NNN-title.md
Red Flags - STOP and Revise
If you find yourself:
- Writing "add feature" without exact file paths
- Skipping the test step
- Combining multiple actions into one step
- Using "etc." or "similar" instead of explicit steps
- Planning without understanding existing code patterns
- Creating steps that take more than 5 minutes
- Not including expected output for test commands
STOP. Revise the plan with more specific steps.
Rationalization Prevention
Excuse
Reality
"They'll know what I mean"
No they won't. Be explicit.
"Too much detail is annoying"
Vague plans cause bugs.
"Testing is obvious"
Write the test command.
"File paths are discoverable"
Write the exact path.
"Commits are implied"
Write when to commit.
"They can figure out edge cases"
List every edge case.
Output Format
# [Feature Name] Implementation Plan
> **For Claude:** REQUIRED: Follow this plan task-by-task using TDD.
**Goal:** [One sentence]
**Architecture:** [2-3 sentences]
**Tech Stack:** [Technologies]
**Prerequisites:** [Requirements]
---
## Phase 1: [Demonstrable Milestone]
> **Exit Criteria:** [What must be true when this phase is complete - e.g., "User can log in and receive JWT"]
### Task 1: [First Component]
**Files:**
- Create: `src/path/file.ts`
- Test: `tests/path/file.test.ts`
**Step 1:** Write failing test
[code block with test]
**Step 2:** Run test, verify fails
Run: `[command]`
Expected: FAIL
**Step 3:** Implement
[code block with implementation]
**Step 4:** Run test, verify passes
Run: `[command]`
Expected: PASS
**Step 5:** Commit
```bash
git add [files]
git commit -m "feat: [description]"
Task 2: [Second Component]
...
Risks
Risk
P
I
Score
Mitigation
...
...
...
...
...
Success Criteria
- All tests pass
- Feature works as specified
- No regressions
- Code reviewed
## Save the Plan (MANDATORY)
**Two saves are required - plan file AND memory update:**
### Step 1: Save Plan File (Use Write tool - NO PERMISSION NEEDED)
First create directory
Bash(command="mkdir -p docs/plans")
Then save plan using Write tool (permission-free)
Write(file_path="docs/plans/YYYY-MM-DD--plan.md", content="[full plan content from output format above]")
Do NOT auto-commit — let the user decide when to commit
### Step 2: Update Memory (CRITICAL - Links Plan to Memory)
**Use Read-Edit-Verify with stable anchors:**
Step 1: READ
Read(file_path=".claude/cc10x/v10/activeContext.md")
Step 2: VERIFY anchors exist (## References, ## Recent Changes, ## Next Steps)
Step 3: EDIT using stable anchors
Add plan to References
Edit(file_path=".claude/cc10x/v10/activeContext.md",
old_string="## References",
new_string="## References\n- Plan: docs/plans/YYYY-MM-DD-<feature>-plan.md
")
Index the plan creation in Recent Changes
Edit(file_path=".claude/cc10x/v10/activeContext.md",
old_string="## Recent Changes",
new_string="## Recent Changes\n- Plan saved: docs/plans/YYYY-MM-DD--plan.md")
Make execution the default next step
Edit(file_path=".claude/cc10x/v10/activeContext.md",
old_string="## Next Steps",
new_string="## Next Steps\n1. Execute plan: docs/plans/YYYY-MM-DD--plan.md")
Step 4: VERIFY (do not skip)
Read(file_path=".claude/cc10x/v10/activeContext.md")
**Also append to progress.md using stable anchor:**
Read(file_path=".claude/cc10x/v10/progress.md")
Edit(file_path=".claude/cc10x/v10/progress.md",
old_string="## Completed",
new_string="## Completed\n- [x] Plan saved - docs/plans/YYYY-MM-DD--plan.md")
VERIFY (do not skip)
Read(file_path=".claude/cc10x/v10/progress.md")
**WHY BOTH:** Plan files are artifacts. Memory is the index. Without memory update, next session won't know the plan exists.
**This is non-negotiable.** Memory is the single source of truth.
## Router-Owned Task Tracking
The planner does **not** create execution tasks. Its job is to create the plan artifact and emit a router contract.
After planning:
- Save the plan file.
- Update memory with the plan reference.
- Let the router create workflow and execution tasks from the approved plan.
Do not instruct the planner to call `TaskCreate` or `TaskUpdate` for phase tracking.
## Plan-Task Linkage (Context Preservation)
**The relationship between Plan Files and Tasks:**
┌─────────────────────────────────────────────────────────────────────┐
│ PLAN FILE (Persistent - Source of Truth) │
│ Location: docs/plans/YYYY-MM-DD-{feature}-plan.md │
│ Contains: Full implementation details, TDD steps, file paths │
│ Survives: Session close, context compaction, conversation reset │
└─────────────────────────────────────────────────────────────────────┘
↕ task description includes the plan file path
┌─────────────────────────────────────────────────────────────────────┐
│ TASKS (Execution Engine) │
│ Contains: Status, dependencies, progress tracking │
│ Survives: Context compaction; can be shared across sessions via │
│ task list configuration (official Claude Code) │
└─────────────────────────────────────────────────────────────────────┘
**Plan path-in-description is CRITICAL:** If context compacts mid-execution, the task description contains enough info to:
1. Find the plan file
2. Locate the exact phase/task
3. Continue without asking questions
**Phase Exit Criteria are CRITICAL:** Each phase MUST have a demonstrable milestone (not arbitrary naming):
- ❌ "Phase 1: Foundation" - Vague, when is it done?
- ✅ "Phase 1: User can authenticate" - Demonstrable, testable
## Execution Handoff
After saving the plan, offer execution choice:
**"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**
**1. Subagent-Driven (this session)** - Fresh subagent per task, review between tasks, fast iteration
**2. Manual Execution** - Follow plan step by step, verify each step
**Which approach?"**