Back to Details

technical-planning

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Technical Planning Skill

技术规划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

规划 vs 架构设计

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
技术规划（本Skill）：
  • 战术层面："我该如何构建功能X？"
  • 具体的实施步骤
  • 耗时数天至数周的工作
  • 将工作拆解为任务
  • 聚焦执行
架构设计（architecture-design skill）：
  • 战略层面："系统应如何架构？"
  • 高层设计决策
  • 影响时长为数周至数月
  • 定义组件与模式
  • 聚焦结构
适用规划的场景：
  • 实现特定功能
  • 将工作拆解为任务
  • 规划实施步骤顺序
  • 评估复杂度
适用架构设计的场景：
  • 设计新系统
  • 重大重构
  • 技术选型
  • 长期战略

The Planning Process

规划流程

1. Understand Requirements

1. 理解需求

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

2. 分析当前状态

Understand what exists:
  • What code is already there?
  • What patterns are in use?
  • What can be reused?
  • What needs to change?
Research:
bash
undefined
了解现有情况：
  • 已有哪些代码？
  • 正在使用哪些模式？
  • 哪些内容可以复用？
  • 哪些内容需要修改？
调研操作：
bash
undefined

Find similar implementations

查找类似实现

grep -r "similar_pattern" .
grep -r "similar_pattern" .

Find related files

查找相关文件

find . -name "related"
find . -name "related"

Check existing tests

检查现有测试

grep -r "test.*similar" test/
undefined
grep -r "test.*similar" test/
undefined

3. Break Down Into Tasks

3. 拆解为任务

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:
markdown
undefined
优质任务的特点：
  • 具体明确："添加用户认证" ❌ → "创建登录API端点" ✅
  • 可测试：具备清晰的成功标准
  • 规模合理：耗时数小时至数天，而非数周
  • 尽量独立：可按任意顺序执行
  • 有序排列：存在依赖关系时需明确执行顺序
任务模板：
markdown
undefined

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]
undefined
内容：[具体描述] 原因：[采用此方案的理由] 依赖：[无，或列出任务编号] **复杂度：**S | M | L 成功标准：
  • 标准1
  • 标准2
涉及文件：
  • path/to/file1.ts
  • path/to/file2.ts
测试方案： [如何验证功能正常]
undefined

4. Identify Dependencies

4. 识别依赖关系

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)
任务依赖类型：
  • 阻塞：任务A完成后任务B才能开始
  • 被阻塞：任务B需等待任务A完成才能启动
  • 相关：需要协同推进的任务
示例：
任务1：创建数据库表结构（无依赖）
任务2：创建API端点（依赖任务1）
任务3：创建UI组件（依赖任务2）
任务4：添加测试（依赖任务1-3）
并行 vs 串行：
可并行执行：
  任务A：前端组件开发
  任务B：后端API开发
  （若API契约已定义）

必须串行执行：
  任务1：数据库迁移
  任务2：更新查询语句以适配新表结构
  （任务2依赖任务1）

5. Estimate Complexity

5. 评估复杂度

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
采用相对规模评估，而非时间：
  • S（小型）：1-4小时，流程清晰
  • M（中型）：4-8小时，复杂度中等
  • L（大型）：1-2天，复杂或存在不确定性
**若任务规模大于L：**进一步拆解
复杂度影响因素：
  • 需求的清晰程度？
  • 存在多少未知项？
  • 需要修改多少文件？
  • 集成复杂度？
  • 测试复杂度？
示例：
  • S：为现有表单添加验证规则
  • M：创建带测试的新API端点
  • L：集成新的支付提供商

6. Define Testing Strategy

6. 定义测试策略

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:
markdown
undefined
如何验证功能正常？
  • 业务逻辑的单元测试
  • API端点的集成测试
  • 用户流程的端到端测试
  • 手动测试步骤
示例：
markdown
undefined

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
undefined
单元测试：
  • 测试验证逻辑
  • 测试计算函数
  • 测试错误处理
集成测试：
  • 结合真实数据库测试API端点
  • 测试多种输入场景
  • 测试错误响应
端到端测试：
  • 用户可完成完整流程
  • 错误信息正确显示
  • 成功场景端到端可行
手动测试：
  • Chrome浏览器测试
  • Firefox浏览器测试
  • 移动端测试
undefined

Plan Document Structure

计划文档结构

markdown
undefined
markdown
undefined

Implementation Plan: [Feature Name]

实施计划：[功能名称]

Created: YYYY-MM-DD Estimated complexity: S | M | L | XL Status: Draft | Approved | In Progress | Complete
**创建时间：**YYYY-MM-DD **预估复杂度：**S | M | L | XL **状态：**草稿 | 已批准 | 进行中 | 已完成

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

阶段1：基础准备

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

任务1.1：[具体交付物]（复杂度：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
内容：[需构建内容的具体描述]
原因：[采用此方案的理由]
**依赖：**无
成功标准：
  • 标准1（可测试）
  • 标准2（可测试）
  • 所有测试通过
涉及文件：
  • src/components/Feature.tsx
    （新建）
  • src/types/feature.ts
    （更新）
测试方案：
  • 组件逻辑的单元测试
  • 数据流的集成测试

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

任务1.2：[下一任务]（复杂度：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
内容：[描述]
原因：[理由]
**依赖：**任务1.1
成功标准：
  • 标准1
  • 标准2
涉及文件：
  • api/routes/feature.ts
    （新建）
测试方案：
  • API端点的集成测试

Phase 2: Integration

阶段2：集成

[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%
整体方案： [我们将如何验证整个功能正常工作]
测试覆盖率目标：
  • 关键路径：100%
  • 正常场景：100%
  • 边缘场景：80%

Risks & Considerations

风险与考量

RiskImpactMitigation
Database migration failsHighTest in staging first, have rollback plan
API performance slowMediumAdd caching, monitor metrics
风险影响程度缓解措施
数据库迁移失败高先在预发布环境测试，制定回滚计划
API性能缓慢中添加缓存，监控指标

Out of Scope

范围之外

Explicitly NOT included in this plan:
  • [Feature A - deferred to v2]
  • [Integration B - separate work]
  • [Optimization C - premature]
本计划明确不包含的内容：
  • [功能A - 推迟至v2版本]
  • [集成B - 单独任务]
  • [优化C - 过早优化]

Open Questions

待解决问题

  • Should we use library X or Y?
  • What's the rate limit for the external API?
  • Do we need to support IE11?
  • 我们应使用库X还是Y？
  • 外部API的速率限制是多少？
  • 是否需要支持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
如何判断本计划成功：
  • 功能上线至生产环境
  • 所有测试通过
  • 性能符合要求（响应时间<200ms）
  • 上线第一周无严重bug

References

参考资料

  • [Related documentation]
  • [Design mockups]
  • [API specifications]
  • [Similar implementations]
undefined
  • [相关文档]
  • [设计原型]
  • [API规范]
  • [类似实现]
undefined

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
前端任务：
- 任务1：创建UI组件
- 任务2：添加表单验证
- 任务3：连接至API

后端任务：
- 任务4：创建API端点
- 任务5：添加业务逻辑
- 任务6：数据库查询

基础设施：
- 任务7：更新部署配置

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
用户认证（垂直切片）：
- 任务1：登录表单（前端）
- 任务2：登录API（后端）
- 任务3：会话管理
- 任务4：登录流程端到端测试

密码重置（垂直切片）：
- 任务5：密码重置表单
- 任务6：密码重置API
- 任务7：邮件通知
- 任务8：重置流程端到端测试

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
必须实现（P0）：
- 任务1：核心功能
- 任务2：关键路径

应该实现（P1）：
- 任务3：实用功能
- 任务4：功能增强

可以实现（P2）：
- 任务5：细节优化
- 任务6：性能优化

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:
undefined
糟糕的任务：
- 提升性能
优质的任务：
undefined

Task 3: Optimize database queries (Complexity: M)

任务3：优化数据库查询（复杂度：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
undefined
**内容：**为用户表的email和created_at字段添加索引
成功标准：
  • 查询时间从500ms缩短至<50ms
  • 迁移执行成功
  • 不影响现有查询
undefined

Document Decisions

记录决策

Why matters:
markdown
undefined
为何重要：
markdown
undefined

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
undefined
我们选择REST而非GraphQL的原因：
  1. 团队对REST更熟悉
  2. 简单的CRUD操作无需GraphQL的灵活性
  3. 后续可按需添加GraphQL支持
**权衡：**灵活性较低，但实现更简单
undefined

Include Examples

包含示例

Show, don't just tell:
markdown
undefined
展示而非仅描述：
markdown
undefined

API Design

API设计

Endpoint: POST /api/users

端点：POST /api/users

Request:
json
{
  "email": "user@example.com",
  "name": "John Doe"
}
Response:
json
{
  "id": "123",
  "email": "user@example.com",
  "name": "John Doe",
  "createdAt": "2024-01-01T00:00:00Z"
}
undefined
请求：
json
{
  "email": "user@example.com",
  "name": "John Doe"
}
响应：
json
{
  "id": "123",
  "email": "user@example.com",
  "name": "John Doe",
  "createdAt": "2024-01-01T00:00:00Z"
}
undefined

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


错误示例：

- 在第5行添加导入语句
- 在第6行声明变量
- 在第7行调用函数

❌ Missing Dependencies

❌ 遗漏依赖关系


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


错误示例：
任务1：创建UI
任务2：创建API
（但UI依赖API契约）

❌ 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

与其他Skill的集成

  • 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
  • 使用simplicity-principles - 保持计划简洁（KISS、YAGNI原则）
  • 使用architecture-design - 用于高层结构决策
  • 使用test-driven-development - 在任务中包含测试
  • 参考solid-principles、structural-design-principles获取实施指导

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:
markdown
undefined
计划是活文档：
  • 随着认知更新计划
  • 添加新发现的任务
  • 移除不需要的任务
  • 根据实际情况调整预估
何时更新计划：
  • 发现新需求
  • 找到可复用的现有代码
  • 识别到额外复杂度
  • 变更实现方案
记录变更：
markdown
undefined

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
undefined
**2024-01-15：**添加任务3.1 - 需要处理遗留数据格式 **2024-01-20：**移除任务2.3 - 现有辅助函数已覆盖该需求 **2024-01-22：**将任务4的复杂度从S调整为M - 比预期更复杂
undefined

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.
  1. 计划是指南，而非契约 - 随认知调整
  2. 从简开始，逐步细化 - 不要过度规划
  3. 让任务可落地 - 具体且可测试
  4. 记录决策 - 解释“为什么”
  5. 包含测试 - 如何验证功能正常？
一份优秀的计划能让编码工作轻松启动。