| name | feature-planner |
| description | Creates phase-based feature plans with quality gates and incremental delivery structure. Use when planning features, organizing work, breaking down tasks, creating roadmaps, or structuring development strategy. Keywords: plan, planning, phases, breakdown, strategy, roadmap, organize, structure, outline. |
Feature Planner
Purpose
Generate structured, phase-based plans where:
- Each phase delivers complete, runnable functionality
- Quality gates enforce validation before proceeding
- User approves plan before any work begins
- Progress tracked via markdown checkboxes
- Each phase is 1-4 hours maximum
Planning Workflow
Step 0: Load Project Context (MANDATORY)
CRITICAL: 플래닝 시작 전 반드시 CLAUDE.md를 읽어서 프로젝트 컨텍스트를 메모리에 로드한다.
- CLAUDE.md 읽기:
CLAUDE.md 파일을 Read 도구로 읽어서 전체 내용을 파악
- 핵심 원칙 확인: 아키텍처 핵심 원칙, 계층 구조, 네이밍 컨벤션 숙지
- 관련 시행령 식별: 기능과 관련된 시행령 문서(docs/standards/)가 있다면 함께 읽기
- E2E 테스트 헌법 확인: 테스트 작성이 포함된 플랜이라면 §6.2 E2E 테스트 헌법 숙지
⚠️ 이 단계를 건너뛰면 프로젝트 아키텍처와 맞지 않는 플랜이 생성될 수 있습니다.
Step 1: Requirements Analysis
- Read relevant files to understand codebase architecture
- Identify dependencies and integration points
- Assess complexity and risks
- Determine appropriate scope (small/medium/large)
Step 2: Phase Breakdown with TDD Integration
Break feature into 3-7 phases where each phase:
- Test-First: Write tests BEFORE implementation
- Delivers working, testable functionality
- Takes 1-4 hours maximum
- Follows Red-Green-Refactor cycle
- Has measurable test coverage requirements
- Can be rolled back independently
- Has clear success criteria
Phase Structure:
- Phase Name: Clear deliverable
- Goal: What working functionality this produces
- Test Strategy: What test types, coverage target, test scenarios
- Tasks (ordered by TDD workflow):
- RED Tasks: Write failing tests first
- GREEN Tasks: Implement minimal code to make tests pass
- REFACTOR Tasks: Improve code quality while tests stay green
- Quality Gate: TDD compliance + validation criteria
- Dependencies: What must exist before starting
- Coverage Target: Specific percentage or checklist for this phase
Step 2.5: Domain Classification & Naming Convention
플랜 파일은 도메인별 서브폴더 아래 ready/ 디렉토리에 생성한다.
파일명 형식
필수 형식: PLAN_{domain}-{feature}.md (kebab-case)
| 구성 요소 | 설명 | 예시 |
|---|
{domain} | 기능이 속하는 도메인 (단수형) | user, partner, subscription |
{feature} | 구현할 기능 (kebab-case) | authentication, excel-export, net-growth-statistics |
올바른 예시:
PLAN_user-authentication.md
PLAN_partner-excel-export.md
PLAN_subscription-net-growth-statistics.md
잘못된 예시:
PLAN_authentication.md (도메인 누락)
PLAN_user_authentication.md (snake_case 사용)
PLAN_UserAuthentication.md (PascalCase 사용)
전체 경로 형식
경로 형식: docs/plans/{domain}/ready/PLAN_{domain}-{feature}.md
도메인 결정 방법:
- 코드베이스의 도메인 패키지 구조를 확인한다 (
modules/domain/src/**/domain/*/)
- 기능이 속하는 도메인을 식별한다
- 도메인을 명확히 결정할 수 없는 경우 AskUserQuestion으로 사용자에게 질문한다
예시:
docs/plans/
├── subscription/
│ └── ready/
│ └── PLAN_subscription-net-growth-statistics.md
├── user/
│ └── ready/
│ └── PLAN_user-authentication.md
└── warehouse/
└── ready/
└── PLAN_warehouse-inventory-sync.md
연관 리소스 네이밍 (feature-impl, branch-review 연동)
플랜 파일명에서 PLAN_ prefix와 .md suffix를 제거한 이름이 일관되게 사용된다:
| 리소스 | 네이밍 패턴 | 예시 |
|---|
| 플랜 파일 | PLAN_{domain}-{feature}.md | PLAN_user-authentication.md |
| 브랜치 | feature/{domain}-{feature} | feature/user-authentication |
| 워크트리 | ../worktrees/feature/{domain}-{feature} | ../worktrees/feature/user-authentication |
| 리뷰 파일 | REVIEW_{domain}-{feature}.md | REVIEW_user-authentication.md |
Step 3: Plan Document Creation
Use plan-template.md to generate: docs/plans/<domain>/ready/PLAN_<feature-name>.md
Include:
- Overview and objectives
- Architecture decisions with rationale
- Complete phase breakdown with checkboxes
- Quality gate checklists
- Risk assessment table
- Rollback strategy per phase
- Progress tracking section
- Notes & learnings area
Step 4: User Approval
CRITICAL: Use AskUserQuestion to get explicit approval before proceeding.
Ask:
- "Does this phase breakdown make sense for your project?"
- "Any concerns about the proposed approach?"
- "Should I proceed with creating the plan document?"
Only create plan document after user confirms approval.
Step 5: Document Generation
- Create
docs/plans/<domain>/ready/ directory if not exists
- Generate plan document with all checkboxes unchecked
- Add clear instructions in header about quality gates
- Inform user of plan location and next steps
Quality Gate Standards
Each phase MUST validate these items before proceeding to next phase:
Build & Compilation:
Test-Driven Development (TDD):
Testing:
Code Quality:
Functionality:
Security & Performance:
Documentation:
Progress Tracking Protocol
Add this to plan document header:
**CRITICAL INSTRUCTIONS**: After completing each phase:
1. ✅ Check off completed task checkboxes
2. 🧪 Run all quality gate validation commands
3. ⚠️ Verify ALL quality gate items pass
4. 📅 Update "Last Updated" date
5. 📝 Document learnings in Notes section
6. ➡️ Only then proceed to next phase
⛔ DO NOT skip quality gates or proceed with failing checks
Phase Sizing Guidelines
Small Scope (2-3 phases, 3-6 hours total):
- Single component or simple feature
- Minimal dependencies
- Clear requirements
- Example: Add dark mode toggle, create new form component
Medium Scope (4-5 phases, 8-15 hours total):
- Multiple components or moderate feature
- Some integration complexity
- Database changes or API work
- Example: User authentication system, search functionality
Large Scope (6-7 phases, 15-25 hours total):
- Complex feature spanning multiple areas
- Significant architectural impact
- Multiple integrations
- Example: AI-powered search with embeddings, real-time collaboration
Risk Assessment
Identify and document:
- Technical Risks: API changes, performance issues, data migration
- Dependency Risks: External library updates, third-party service availability
- Timeline Risks: Complexity unknowns, blocking dependencies
- Quality Risks: Test coverage gaps, regression potential
For each risk, specify:
- Probability: Low/Medium/High
- Impact: Low/Medium/High
- Mitigation Strategy: Specific action steps
Rollback Strategy
For each phase, document how to revert changes if issues arise.
Consider:
- What code changes need to be undone
- Database migrations to reverse (if applicable)
- Configuration changes to restore
- Dependencies to remove
Test Specification Guidelines
Test-First Development Workflow
For Each Feature Component:
-
Specify Test Cases (before writing ANY code)
- What inputs will be tested?
- What outputs are expected?
- What edge cases must be handled?
- What error conditions should be tested?
-
Write Tests (Red Phase)
- Write tests that WILL fail
- Verify tests fail for the right reason
- Run tests to confirm failure
- Commit failing tests to track TDD compliance
-
Implement Code (Green Phase)
- Write minimal code to make tests pass
- Run tests frequently (every 2-5 minutes)
- Stop when all tests pass
- No additional functionality beyond tests
-
Refactor (Blue Phase)
- Improve code quality while tests remain green
- Extract duplicated logic
- Improve naming and structure
- Run tests after each refactoring step
- Commit when refactoring complete
Test Types
Unit Tests:
- Target: Individual functions, methods, classes
- Dependencies: None or mocked/stubbed
- Speed: Fast (<100ms per test)
- Isolation: Complete isolation from external systems
- Coverage: ≥80% of business logic
Integration Tests:
- Target: Interaction between components/modules
- Dependencies: May use real dependencies
- Speed: Moderate (<1s per test)
- Isolation: Tests component boundaries
- Coverage: Critical integration points
End-to-End (E2E) Tests:
- Target: Complete user workflows
- Dependencies: Real or near-real environment
- Speed: Slow (seconds to minutes)
- Isolation: Full system integration
- Coverage: Critical user journeys
Test Coverage Calculation
Coverage Thresholds (adjust for your project):
- Business Logic: ≥90% (critical code paths)
- Data Access Layer: ≥80% (repositories, DAOs)
- API/Controller Layer: ≥70% (endpoints)
- UI/Presentation: Integration tests preferred over coverage
Coverage Commands by Ecosystem:
jest --coverage
nyc report --reporter=html
pytest --cov=src --cov-report=html
coverage report
mvn jacoco:report
gradle jacocoTestReport
go test -cover ./...
go tool cover -html=coverage.out
dotnet test /p:CollectCoverage=true /p:CoverageReporter=html
reportgenerator -reports:coverage.xml -targetdir:coverage
bundle exec rspec --coverage
open coverage/index.html
phpunit --coverage-html coverage
Common Test Patterns
Arrange-Act-Assert (AAA) Pattern:
test 'description of behavior':
// Arrange: Set up test data and dependencies
input = createTestData()
// Act: Execute the behavior being tested
result = systemUnderTest.method(input)
// Assert: Verify expected outcome
assert result == expectedOutput
Given-When-Then (BDD Style):
test 'feature should behave in specific way':
// Given: Initial context/state
given userIsLoggedIn()
// When: Action occurs
when userClicksButton()
// Then: Observable outcome
then shouldSeeConfirmation()
Mocking/Stubbing Dependencies:
test 'component should call dependency':
// Create mock/stub
mockService = createMock(ExternalService)
component = new Component(mockService)
// Configure mock behavior
when(mockService.method()).thenReturn(expectedData)
// Execute and verify
component.execute()
verify(mockService.method()).calledOnce()
Test Documentation in Plan
In each phase, specify:
- Test File Location: Exact path where tests will be written
- Test Scenarios: List of specific test cases
- Expected Failures: What error should tests show initially?
- Coverage Target: Percentage for this phase
- Dependencies to Mock: What needs mocking/stubbing?
- Test Data: What fixtures/factories are needed?
Supporting Files Reference
Implementation Plan: [Feature Name]
Status: 🔄 In Progress
Started: YYYY-MM-DD
Last Updated: YYYY-MM-DD
Estimated Completion: YYYY-MM-DD
⚠️ CRITICAL INSTRUCTIONS: After completing each phase:
- ✅ Check off completed task checkboxes
- 🧪 Run all quality gate validation commands
- ⚠️ Verify ALL quality gate items pass
- 📅 Update "Last Updated" date above
- 📝 Document learnings in Notes section
- ➡️ Only then proceed to next phase
⛔ DO NOT skip quality gates or proceed with failing checks
📋 Overview
Feature Description
[What this feature does and why it's needed]
Success Criteria
User Impact
[How this benefits users or improves the product]
🏗️ Architecture Decisions
| Decision | Rationale | Trade-offs |
|---|
| [Decision 1] | [Why this approach] | [What we're giving up] |
| [Decision 2] | [Why this approach] | [What we're giving up] |
📦 Dependencies
Required Before Starting
External Dependencies
- Package/Library 1: version X.Y.Z
- Package/Library 2: version X.Y.Z
🧪 Test Strategy
Testing Approach
TDD Principle: Write tests FIRST, then implement to make them pass
Test Pyramid for This Feature
| Test Type | Coverage Target | Purpose |
|---|
| Unit Tests | ≥80% | Business logic, models, core algorithms |
| Integration Tests | Critical paths | Component interactions, data flow |
| E2E Tests | Key user flows | Full system behavior validation |
Test File Organization
test/
├── unit/
│ ├── [domain/business_logic]/
│ └── [data/models]/
├── integration/
│ └── [feature_name]/
└── e2e/
└── [user_flows]/
Coverage Requirements by Phase
- Phase 1 (Foundation): Unit tests for core models/entities (≥80%)
- Phase 2 (Business Logic): Logic + repository tests (≥80%)
- Phase 3 (Integration): Component integration tests (≥70%)
- Phase 4 (E2E): End-to-end user flow test (1+ critical path)
Test Naming Convention
Follow your project's testing framework conventions:
// Example structure (adapt to your framework):
describe/group: Feature or component name
test/it: Specific behavior being tested
// Arrange → Act → Assert pattern
🚀 Implementation Phases
Phase 1: [Foundation Phase Name]
Goal: [Specific working functionality this phase delivers]
Estimated Time: X hours
Status: ⏳ Pending | 🔄 In Progress | ✅ Complete
Tasks
🔴 RED: Write Failing Tests First
🟢 GREEN: Implement to Make Tests Pass
🔵 REFACTOR: Clean Up Code
Quality Gate ✋
⚠️ STOP: Do NOT proceed to Phase 2 until ALL checks pass
TDD Compliance (CRITICAL):
Build & Tests:
Code Quality:
Security & Performance:
Documentation:
Manual Testing:
Validation Commands (customize for your project):
[your test runner command]
[your coverage command]
[your linter command]
[your formatter check command]
[your type checker command]
[your build command]
[your dependency audit command]
Manual Test Checklist:
Phase 2: [Core Feature Phase Name]
Goal: [Specific deliverable]
Estimated Time: X hours
Status: ⏳ Pending | 🔄 In Progress | ✅ Complete
Tasks
🔴 RED: Write Failing Tests First
🟢 GREEN: Implement to Make Tests Pass
🔵 REFACTOR: Clean Up Code
Quality Gate ✋
⚠️ STOP: Do NOT proceed to Phase 3 until ALL checks pass
TDD Compliance (CRITICAL):
Build & Tests:
Code Quality:
Security & Performance:
Documentation:
Manual Testing:
Validation Commands:
[Same as Phase 1 - customize for your project]
Manual Test Checklist:
Phase 3: [Enhancement Phase Name]
Goal: [Specific deliverable]
Estimated Time: X hours
Status: ⏳ Pending | 🔄 In Progress | ✅ Complete
Tasks
🔴 RED: Write Failing Tests First
🟢 GREEN: Implement to Make Tests Pass
🔵 REFACTOR: Clean Up Code
Quality Gate ✋
⚠️ STOP: Do NOT proceed until ALL checks pass
TDD Compliance (CRITICAL):
Build & Tests:
Code Quality:
Security & Performance:
Documentation:
Manual Testing:
Validation Commands:
[Same as previous phases - customize for your project]
Manual Test Checklist:
⚠️ Risk Assessment
| Risk | Probability | Impact | Mitigation Strategy |
|---|
| [Risk 1: e.g., API changes break integration] | Low/Med/High | Low/Med/High | [Specific mitigation steps] |
| [Risk 2: e.g., Performance degradation] | Low/Med/High | Low/Med/High | [Specific mitigation steps] |
| [Risk 3: e.g., Database migration issues] | Low/Med/High | Low/Med/High | [Specific mitigation steps] |
🔄 Rollback Strategy
If Phase 1 Fails
Steps to revert:
- Undo code changes in: [list files]
- Restore configuration: [specific settings]
- Remove dependencies: [if any were added]
If Phase 2 Fails
Steps to revert:
- Restore to Phase 1 complete state
- Undo changes in: [list files]
- Database rollback: [if applicable]
If Phase 3 Fails
Steps to revert:
- Restore to Phase 2 complete state
- [Additional cleanup steps]
📊 Progress Tracking
Completion Status
- Phase 1: ⏳ 0% | 🔄 50% | ✅ 100%
- Phase 2: ⏳ 0% | 🔄 50% | ✅ 100%
- Phase 3: ⏳ 0% | 🔄 50% | ✅ 100%
Overall Progress: X% complete
Time Tracking
| Phase | Estimated | Actual | Variance |
|---|
| Phase 1 | X hours | Y hours | +/- Z hours |
| Phase 2 | X hours | - | - |
| Phase 3 | X hours | - | - |
| Total | X hours | Y hours | +/- Z hours |
📝 Notes & Learnings
Implementation Notes
- [Add insights discovered during implementation]
- [Document decisions that deviate from original plan]
- [Record helpful debugging discoveries]
Blockers Encountered
- Blocker 1: [Description] → [Resolution]
- Blocker 2: [Description] → [Resolution]
Improvements for Future Plans
- [What would you do differently next time?]
- [What worked particularly well?]
📚 References
Documentation
- [Link to relevant docs]
- [Link to API references]
- [Link to design mockups]
Related Issues
- Issue #X: [Description]
- PR #Y: [Description]
✅ Final Checklist
Before marking plan as COMPLETE:
📖 TDD Example Workflow
Example: Adding User Authentication Feature
Phase 1: RED (Write Failing Tests)
# Pseudocode - adapt to your testing framework
test "should validate user credentials":
// Arrange
authService = new AuthService(mockDatabase)
validCredentials = {username: "user", password: "pass"}
// Act
result = authService.authenticate(validCredentials)
// Assert
expect(result.isSuccess).toBe(true)
expect(result.user).toBeDefined()
// TEST FAILS - AuthService doesn't exist yet
Phase 2: GREEN (Minimal Implementation)
class AuthService:
function authenticate(credentials):
// Minimal code to make test pass
user = database.findUser(credentials.username)
if user AND user.password == credentials.password:
return Success(user)
return Failure("Invalid credentials")
// TEST PASSES - minimal functionality works
Phase 3: REFACTOR (Improve Design)
class AuthService:
function authenticate(credentials):
// Add validation
if not this.validateCredentials(credentials):
return Failure("Invalid input")
// Add error handling
try:
user = database.findUser(credentials.username)
// Use secure password comparison
if user AND this.secureCompare(user.password, credentials.password):
return Success(user)
return Failure("Invalid credentials")
catch DatabaseError as error:
logger.error(error)
return Failure("Authentication failed")
// TESTS STILL PASS - improved code quality
TDD Red-Green-Refactor Cycle Visualization
Phase 1: 🔴 RED
├── Write test for feature X
├── Run test → FAILS ❌
└── Commit: "Add failing test for X"
Phase 2: 🟢 GREEN
├── Write minimal code
├── Run test → PASSES ✅
└── Commit: "Implement X to pass tests"
Phase 3: 🔵 REFACTOR
├── Improve code quality
├── Run test → STILL PASSES ✅
├── Extract helper methods
├── Run test → STILL PASSES ✅
├── Improve naming
├── Run test → STILL PASSES ✅
└── Commit: "Refactor X for better design"
Repeat for next feature →
Benefits of This Approach
Safety: Tests catch regressions immediately
Design: Tests force you to think about API design first
Documentation: Tests document expected behavior
Confidence: Refactor without fear of breaking things
Quality: Higher code coverage from day one
Debugging: Failures point to exact problem area
Plan Status: 🔄 In Progress
Next Action: [What needs to happen next]
Blocked By: [Any current blockers] or None