technical-planning（技术规划）

Technical Planning Skill

Create actionable implementation plans for features and tasks.

Core Principle

A good plan turns a vague goal into concrete, executable steps.

Planning vs Architecture

Technical Planning (this skill):

• Tactical: "How do I build feature X?"
• Specific implementation steps
• Days to weeks of work
• Breaks work into tasks
• Focuses on execution

Architecture Design (architecture-design skill):

• Strategic: "How should the system be structured?"
• High-level design decisions
• Weeks to months of impact
• Defines components and patterns
• Focuses on structure

Use planning for:

• Implementing specific features
• Breaking down work into tasks
• Sequencing implementation steps
• Estimating complexity

Use architecture for:

• Designing new systems
• Major refactors
• Technology choices
• Long-term strategy

The Planning Process

1. Understand Requirements

Clarify what success looks like:

• What exactly needs to be built?
• What problem does it solve?
• What are the acceptance criteria?
• What's in scope vs out of scope?

Ask questions:

• Who will use this?
• What's the expected behavior?
• What edge cases should be handled?
• Are there performance requirements?
• Security concerns?

2. Analyze Current State

Understand what exists:

• What code is already there?
• What patterns are in use?
• What can be reused?
• What needs to change?

Research:

# Find similar implementations
grep -r "similar_pattern" .

# Find related files
find . -name "*related*"

# Check existing tests
grep -r "test.*similar" test/

3. Break Down Into Tasks

Good tasks are:

• Specific: "Add user authentication" ❌ → "Create login API endpoint" ✅
• Testable: Clear success criteria
• Right-sized: Hours to days, not weeks
• Independent (when possible): Can be done in any order
• Ordered (when dependencies exist): Clear sequence

Task template:

### Task: [Specific deliverable]

**What:** [Concrete description]
**Why:** [Reasoning for this approach]
**Dependencies:** [None, or list of task numbers]
**Complexity:** S | M | L
**Success criteria:**
- [ ] Criterion 1
- [ ] Criterion 2

**Files affected:**
- `path/to/file1.ts`
- `path/to/file2.ts`

**Testing approach:**
[How to verify this works]

4. Identify Dependencies

Task dependencies:

• Blocks: Task A must finish before Task B starts
• Blocked by: Task B can't start until Task A finishes
• Related: Tasks that should coordinate

Example:

Task 1: Create database schema (no dependencies)
Task 2: Create API endpoint (depends on Task 1)
Task 3: Create UI component (depends on Task 2)
Task 4: Add tests (depends on Tasks 1-3)

Parallel vs Sequential:

Can be parallel:
  Task A: Frontend component
  Task B: Backend API
  (If API contract is defined)

Must be sequential:
  Task 1: Database migration
  Task 2: Update queries to use new schema
  (Task 2 depends on Task 1)

5. Estimate Complexity

Use relative sizing, not time:

• S (Small): 1-4 hours, straightforward
• M (Medium): 4-8 hours, moderate complexity
• L (Large): 1-2 days, complex or uncertain

If task is > L: Break it down further

Complexity factors:

• How well-understood is the requirement?
• How many unknowns?
• How many files need changes?
• Integration complexity?
• Testing complexity?

Examples:

• S: Add validation rule to existing form
• M: Create new API endpoint with tests
• L: Implement new payment provider integration

6. Define Testing Strategy

How will we verify it works?

• Unit tests for business logic
• Integration tests for API endpoints
• E2E tests for user workflows
• Manual testing steps

Example:

## Testing Strategy

**Unit tests:**
- Test validation logic
- Test calculation functions
- Test error handling

**Integration tests:**
- Test API endpoint with real database
- Test with various input scenarios
- Test error responses

**E2E tests:**
- User can complete full workflow
- Error messages display correctly
- Success case works end-to-end

**Manual testing:**
- [ ] Test in Chrome
- [ ] Test in Firefox
- [ ] Test on mobile

Plan Document Structure

# Implementation Plan: [Feature Name]

**Created:** YYYY-MM-DD
**Estimated complexity:** S | M | L | XL
**Status:** Draft | Approved | In Progress | Complete

## Goal

[One paragraph: What are we building and why?]

## Current State

[What exists today that's relevant to this plan?]
[What needs to change?]
[What can be reused?]

## Proposed Approach

[High-level strategy: How will we build this?]
[Key technical decisions made]
[Alternatives considered and why not chosen]

## Tasks

### Phase 1: Foundation

#### Task 1.1: [Specific deliverable] (Complexity: S)

**What:** [Concrete description of what needs to be built]

**Why:** [Reasoning for this approach]

**Dependencies:** None

**Success criteria:**
- [ ] Criterion 1 (testable)
- [ ] Criterion 2 (testable)
- [ ] All tests pass

**Files affected:**
- `src/components/Feature.tsx` (create)
- `src/types/feature.ts` (update)

**Testing approach:**
- Unit test for component logic
- Integration test for data flow

---

#### Task 1.2: [Next task] (Complexity: M)

**What:** [Description]

**Why:** [Reasoning]

**Dependencies:** Task 1.1

**Success criteria:**
- [ ] Criterion 1
- [ ] Criterion 2

**Files affected:**
- `api/routes/feature.ts` (create)

**Testing approach:**
- Integration test for API endpoint

---

### Phase 2: Integration

[Additional tasks organized by phase]

## Testing Strategy

**Overall approach:**
[How we'll verify the entire feature works]

**Test coverage goals:**
- Critical paths: 100%
- Happy paths: 100%
- Edge cases: 80%

## Risks & Considerations

| Risk | Impact | Mitigation |
|------|--------|------------|
| Database migration fails | High | Test in staging first, have rollback plan |
| API performance slow | Medium | Add caching, monitor metrics |

## Out of Scope

**Explicitly NOT included in this plan:**
- [Feature A - deferred to v2]
- [Integration B - separate work]
- [Optimization C - premature]

## Open Questions

- [ ] Should we use library X or Y?
- [ ] What's the rate limit for the external API?
- [ ] Do we need to support IE11?

## Success Metrics

**How we'll know this is successful:**
- Feature ships to production
- All tests pass
- Performance meets requirements (< 200ms response)
- Zero critical bugs in first week

## References

- [Related documentation]
- [Design mockups]
- [API specifications]
- [Similar implementations]

Task Breakdown Strategies

By Layer

Frontend tasks:
- Task 1: Create UI component
- Task 2: Add form validation
- Task 3: Connect to API

Backend tasks:
- Task 4: Create API endpoint
- Task 5: Add business logic
- Task 6: Database queries

Infrastructure:
- Task 7: Update deployment config

By Feature Slice

User Authentication (vertical slice):
- Task 1: Login form (frontend)
- Task 2: Login API (backend)
- Task 3: Session management
- Task 4: E2E test for login flow

Password Reset (vertical slice):
- Task 5: Password reset form
- Task 6: Password reset API
- Task 7: Email notification
- Task 8: E2E test for reset flow

By Priority

Must Have (P0):
- Task 1: Core functionality
- Task 2: Critical path

Should Have (P1):
- Task 3: Nice to have feature
- Task 4: Enhancement

Could Have (P2):
- Task 5: Polish
- Task 6: Optimization

Planning Best Practices

Start Simple

Don't over-plan:

• Start with high-level tasks
• Add detail as you learn
• Plans evolve during implementation

Good enough:

• Plan should be clear enough to start
• Not every detail needs to be known upfront
• Iterate as you go

Make Tasks Actionable

Bad task:

- Improve performance

Good task:

### Task 3: Optimize database queries (Complexity: M)

**What:** Add indexes to users table for email and created_at columns

**Success criteria:**
- [ ] Query time reduced from 500ms to < 50ms
- [ ] Migration runs successfully
- [ ] No impact on existing queries

Document Decisions

Why matters:

## Why this approach?

We chose REST over GraphQL because:
1. Team is more familiar with REST
2. Simple CRUD operations don't need GraphQL flexibility
3. Can add GraphQL later if needed

**Trade-off:** Less flexible, but simpler to implement

Include Examples

Show, don't just tell:

## API Design

### Endpoint: POST /api/users

**Request:**

{ "email": "user@example.com", "name": "John Doe" }

**Response:**

{ "id": "123", "email": "user@example.com", "name": "John Doe", "createdAt": "2024-01-01T00:00:00Z" }

Common Planning Mistakes

❌ Too Vague

BAD:

- Implement user system
- Add features
- Make it work

❌ Too Detailed

BAD:

- Add import statement on line 5
- Declare variable on line 6
- Call function on line 7

❌ Missing Dependencies

BAD: Task 1: Create UI Task 2: Create API (But UI depends on API contract)

❌ No Success Criteria

BAD: Task: Add validation (How do we know when it's done?)

GOOD: Task: Add validation

- Email format validated
- Required fields checked
- Error messages displayed
- Tests pass

Integration with Other Skills

• Use simplicity-principles - Keep plan simple (KISS, YAGNI)
• Use architecture-design - For high-level structure decisions
• Use test-driven-development - Include testing in tasks
• Reference solid-principles, structural-design-principles for implementation guidance

Adaptive Planning

Plans are living documents:

• Update as you learn
• Add newly discovered tasks
• Remove tasks that aren't needed
• Adjust estimates based on reality

When to update plan:

• Discovered new requirement
• Found existing code to reuse
• Identified additional complexity
• Changed approach

Document changes:

## Plan Updates

**2024-01-15:** Added Task 3.1 - need to handle legacy data format
**2024-01-20:** Removed Task 2.3 - existing helper function covers this
**2024-01-22:** Increased Task 4 from S to M - more complex than expected

Planning Checklist

• Goal clearly stated
• Current state analyzed
• Approach decided and documented
• Tasks broken down
• Tasks are specific and actionable
• Dependencies identified
• Complexity estimated
• Success criteria defined for each task
• Testing strategy included
• Risks identified
• Out of scope explicitly stated
• Plan reviewed and approved

Remember

1. Plans are guides, not contracts - Adapt as you learn
2. Start simple, add detail - Don't over-plan
3. Make tasks actionable - Specific and testable
4. Document decisions - Explain the "why"
5. Include testing - How will we verify it works?

A good plan makes it easy to start coding.