Back to Details

planning

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Structured Planning

结构化规划

Overview

概述

Structured planning converts vague requirements into approved, documented implementation plans before any code is written. It forces clarifying questions, approach comparison with trade-offs, and explicit user approval — preventing the most common cause of wasted effort: building the wrong thing. Every task, regardless of perceived simplicity, goes through this process.
Announce at start: "I'm using the planning skill to create a structured implementation plan."
结构化规划会在编写任何代码之前，将模糊的需求转化为经过批准、记录在案的实现方案。它强制要求澄清问题、对比不同方案的权衡，并获得用户明确批准——避免了开发工作浪费的最常见原因：开发了错误的功能。所有任务无论看起来多简单，都需要遵循该流程。
启动时说明： "我正在使用规划能力创建结构化的实现方案。"

Trigger Conditions

触发条件

  • User requests a new feature, enhancement, or change
  • A bug fix requires more than a one-line change
  • Refactoring work spanning multiple files
  • Any task where the approach is not already documented and approved
  • Transition from brainstorming skill with an approved design
  • /plan
    command invoked
  • 用户请求新功能、功能增强或变更
  • bug修复需要超过一行代码的改动
  • 跨多个文件的重构工作
  • 实现方案尚未记录并获得批准的任何任务
  • 从头脑风暴能力输出的已批准设计过渡到实现阶段
  • 触发
    /plan
    命令

Phase 1: Context Gathering

阶段1：上下文收集

Goal: Understand the codebase and existing patterns before asking questions.
  1. Read relevant files, docs, recent commits, and CLAUDE.md
  2. Check memory files for known project context, stack, and conventions
  3. Review existing plans in 
    docs/plans/
    for related work
  4. Identify existing patterns the new work should follow
  5. Note technical constraints discovered during exploration
STOP — Do NOT proceed to Phase 2 until:
  • You have explored the relevant parts of the codebase
  • You understand the existing architecture and patterns
  • You have checked memory files for prior decisions
目标： 在提问前先理解代码库和现有模式。
  1. 阅读相关文件、文档、近期提交记录和CLAUDE.md
  2. 检查记忆文件中已知的项目上下文、技术栈和规范
  3. 查阅
    docs/plans/
    目录下已有相关工作的规划文档
  4. 识别新工作需要遵循的现有模式
  5. 记录探索过程中发现的技术约束
停止——在满足以下条件前不要进入阶段2：
  • 你已经探索了代码库的相关部分
  • 你理解现有架构和模式
  • 你已经检查了记忆文件中的历史决策

Phase 2: Clarifying Questions

阶段2：问题澄清

Goal: Eliminate ambiguity by asking targeted questions one at a time.
  1. Ask ONE question per message — never overwhelm with multiple questions
  2. Prefer multiple choice questions when possible
  3. Study the codebase before asking — do not ask what you can discover
  4. Convert vague requirements into specific, testable criteria
目标： 通过一次提出一个针对性问题消除歧义。
  1. 每条消息只提一个问题——永远不要一次性抛出多个问题造成用户负担
  2. 尽可能使用选择题形式
  3. 提问前先研究代码库——不要提问你可以自行找到答案的问题
  4. 将模糊需求转化为具体的、可测试的标准

Question Category Priority

问题类别优先级

PriorityCategoryExample Question
1Purpose"What problem does this solve? Who is it for?"
2Success criteria"How will we know it works? What does 'done' look like?"
3Constraints"Are there performance, compatibility, or timeline constraints?"
4Non-goals"What should we explicitly NOT build?"
5Existing patterns"Should we follow the pattern used in X, or is a new approach needed?"
6Edge cases"What should happen when [boundary condition]?"
优先级类别示例问题
1目标"这个功能解决什么问题？面向的用户是谁？"
2成功标准"我们如何判断它可以正常运行？'完成'的定义是什么？"
3约束"是否有性能、兼容性或时间线方面的约束？"
4非目标"哪些功能是我们明确不需要开发的？"
5现有模式"我们应该遵循X中使用的模式，还是需要采用新方案？"
6边界情况"当出现[边界条件]时应该如何处理？"

Question Rules

提问规则

RuleRationale
One question per messagePrevents cognitive overload
Multiple choice preferredFaster to answer, reduces ambiguity
Research before askingRespect user's time — discover what you can
Testable criteriaVague answers lead to vague implementations
STOP — Do NOT proceed to Phase 3 until:
  • You understand the purpose and success criteria
  • You have identified constraints and non-goals
  • No critical ambiguities remain
规则原因
每条消息一个问题避免认知负担
优先使用选择题回答更快，减少歧义
提问前先调研尊重用户时间——自行查找可获得的信息
可测试的标准模糊的答案会导致模糊的实现
停止——在满足以下条件前不要进入阶段3：
  • 你理解了目标和成功标准
  • 你已经明确了约束和非目标
  • 没有遗留关键歧义

Phase 3: Approach Design

阶段3：方案设计

Goal: Propose 2-3 concrete approaches with trade-offs and a clear recommendation.
For each approach, include:
SectionContent
Architecture summary2-3 sentences describing the approach
Key filesExact paths to create/modify
DependenciesExternal deps or breaking changes
Trade-offsExplicit pros and cons
Effort estimateNumber of tasks (not hours)
Risk levelLow / Medium / High with explanation
目标： 提出2-3个具体的方案，说明各自的权衡，并给出明确的推荐选择。
每个方案需要包含以下内容：
模块内容
架构概述2-3句话描述方案
核心文件需要创建/修改的准确路径
依赖外部依赖或破坏性变更
权衡明确的优缺点
工作量预估任务数量（而非小时数）
风险等级低/中/高，并附带说明

Approach Selection Decision Table

方案选择决策表

FactorWeightHow to Evaluate
Alignment with existing patternsHighDoes it match current codebase conventions?
SimplicityHighFewest moving parts that meet requirements
TestabilityMediumCan each component be independently tested?
Future extensibilityLowOnly consider if user mentioned future plans
PerformanceVariesOnly if user specified performance constraints
Lead with your recommended approach. Explain why it is the best choice given the constraints. Present alternatives to show you considered the trade-off space.
STOP — Do NOT proceed to Phase 4 until:
  • You have proposed at least 2 approaches
  • Each approach has trade-offs documented
  • You have made a clear recommendation with reasoning
因素权重评估方式
与现有模式的一致性高是否符合当前代码库规范？
简洁性高满足需求的前提下，使用最少的动态组件
可测试性中每个组件是否可以独立测试？
未来可扩展性低仅当用户提到未来规划时才考虑
性能可变仅当用户明确提出性能约束时才考虑
首先说明你推荐的方案。 结合约束解释为什么它是最优选择。同时给出备选方案，说明你已经考虑了各种权衡。
停止——在满足以下条件前不要进入阶段4：
  • 你已经提出了至少2个方案
  • 每个方案都记录了权衡点
  • 你已经给出了带有论证的明确推荐

Phase 4: Plan Documentation

阶段4：规划文档编写

Goal: Write a detailed, executable plan document and get explicit approval.
目标： 编写详细的可执行规划文档，并获得明确批准。

Plan Document Format

规划文档格式

markdown
undefined
markdown
undefined

[Feature Name] Implementation Plan

[功能名称] 实现方案

Goal: [One sentence] Architecture: [2-3 sentences] Approach: [Which approach was chosen and why]
目标： [一句话描述] 架构： [2-3句话描述] 方案： [选择了哪个方案，以及选择原因]

Task N: [Component Name]

任务N: [组件名称]

Files:
  • Create: 
    exact/path/to/file.ext
  • Modify: 
    exact/path/to/existing.ext
  • Test: 
    tests/exact/path/to/test.ext
Steps:
  1. Write the failing test
  2. Run test to verify it fails
  3. Write minimal implementation
  4. Run test to verify it passes
  5. Commit
Verification: [Exact command to verify this task]
undefined
文件：
  • 创建：
    exact/path/to/file.ext
  • 修改：
    exact/path/to/existing.ext
  • 测试：
    tests/exact/path/to/test.ext
步骤：
  1. 编写失败的测试用例
  2. 运行测试确认失败
  3. 编写最小化实现代码
  4. 运行测试确认通过
  5. 提交代码
验证： [验证该任务完成的准确命令]
undefined

Plan Quality Checklist

规划质量检查清单

CriterionCheck
Every task has exact file pathsNo "somewhere in src/"
Every task has a verification commandNo "eyeball it"
Tasks are ordered by dependencyNo forward references
Tasks are 2-5 minutes eachNo "implement the whole module"
TDD steps are explicitRED-GREEN-REFACTOR per task
Save the plan to 
docs/plans/YYYY-MM-DD-<feature>.md
.
STOP — Do NOT proceed to Phase 5 until:
  • Plan document is written and saved
  • Every task has file paths, steps, and verification
  • User has explicitly approved the plan (said "yes", "approved", "go ahead", etc.)
标准检查结果
每个任务都有准确的文件路径没有"src/下的某个地方"这类描述
每个任务都有验证命令没有"肉眼检查"这类描述
任务按依赖关系排序没有前置引用
每个任务耗时2-5分钟没有"实现整个模块"这类大任务
TDD步骤明确每个任务遵循红-绿-重构流程
将规划保存到
docs/plans/YYYY-MM-DD-<feature>.md
。
停止——在满足以下条件前不要进入阶段5：
  • 规划文档已经编写完成并保存
  • 每个任务都有文件路径、步骤和验证方式
  • 用户已经明确批准方案（回复了"是"、"批准"、"开始"等内容）

Phase 5: Transition to Execution

阶段5：过渡到执行阶段

Goal: Hand off the approved plan to the appropriate execution skill.
目标： 将已批准的方案交付给对应的执行能力。

Transition Decision Table

过渡决策表

SituationNext SkillRationale
Standard implementation (< 10 tasks)
task-management
Sequential tracked execution
Large implementation (10+ independent tasks)
subagent-driven-development
Parallel execution with review gates
Autonomous development session
autonomous-loop
Ralph-style iterative execution
Single focused task
executing-plans
Direct plan execution
Invoke the chosen skill and pass the plan document path.
场景下一个使用的能力原因
标准实现（少于10个任务）
task-management
顺序跟踪执行
大型实现（10个以上独立任务）
subagent-driven-development
带审核关卡的并行执行
自主开发会话
autonomous-loop
Ralph风格的迭代执行
单个聚焦任务
executing-plans
直接执行方案
调用选中的能力并传入规划文档的路径。

Anti-Patterns / Common Mistakes

反模式/常见错误

Anti-PatternWhy It FailsCorrect Approach
"This is too simple to plan"Simple tasks have unexamined assumptionsPlan anyway — the plan can be short
"I already know the approach"Your approach may conflict with project patternsDocument it and get approval
"The user wants it fast"Bad code is slower than planned codePlanning prevents rework
"It's just a bug fix"Bug fixes need root cause analysisPlan the fix, not just the patch
"I'll plan as I go"That is improvising, not planningPlan first, execute second
Asking 5 questions at onceOverwhelms the user, gets vague answersOne question per message
Proposing only 1 approachNo trade-off analysis, may miss better optionsAlways propose 2-3 approaches
Vague file references"Update the tests" — which tests?Exact file paths always
Tasks that take 30+ minutesToo large to track and verifyBreak into 2-5 minute tasks
Starting code before approvalWastes effort if direction changesWait for explicit "yes"
反模式失败原因正确做法
"这个太简单了不需要规划"简单任务也存在未被检查的假设无论多简单都要做规划，规划可以很短
"我已经知道用什么方案了"你的方案可能和项目模式冲突记录方案并获得批准
"用户想要快速上线"糟糕的代码比规划好的代码开发更慢规划可以避免返工
"只是一个bug修复而已"bug修复需要根因分析规划修复方案，而不只是打补丁
"我可以边做边规划"这是即兴发挥，不是规划先规划，再执行
一次性问5个问题给用户造成负担，得到模糊的答案每条消息只提一个问题
只提1个方案没有权衡分析，可能错过更优选项永远提出2-3个方案
模糊的文件引用"更新测试用例"——到底是哪些测试？永远使用准确的文件路径
单个任务耗时30分钟以上太大难以跟踪和验证拆分成2-5分钟的小任务
获得批准前就开始写代码如果方向变化会浪费工作量等待明确的"批准"回复

Anti-Rationalization Guards

反合理化约束

<HARD-GATE> Do NOT write any code, create any files, or take any implementation action until: 1. You have asked clarifying questions and understood the requirements 2. You have proposed approaches with trade-offs 3. The user has explicitly approved the plan
This applies to EVERY task regardless of perceived simplicity. </HARD-GATE>
Iron Law: NO CODE WITHOUT AN APPROVED PLAN. No exceptions. No "just this small thing." No "it's obvious."
If you catch yourself thinking any of the following, STOP immediately:
  • "Let me just quickly..." — No. Plan first.
  • "This doesn't need a full plan..." — Yes it does. The plan can be brief.
  • "I'll document it after..." — No. Document before.
<HARD-GATE> 在满足以下条件前，不要编写任何代码、创建任何文件，或采取任何实现动作： 1. 你已经提出了澄清问题并理解了需求 2. 你已经提出了带权衡的多个方案 3. 用户已经明确批准了规划
该规则适用于所有任务，无论看起来多简单。 </HARD-GATE>
铁律：没有批准的规划就不能写代码。 没有例外。不能有"就这一点点改动"、"这很明显"之类的借口。
如果你发现自己有以下想法，请立刻停止：
  • "我就快速弄一下..."——不行，先规划。
  • "这个不需要完整的规划..."——需要，规划可以很简短。
  • "我做完之后再补文档..."——不行，先写文档。

Subagent Dispatch Opportunities

Subagent调度场景

Task PatternDispatch ToWhen
Independent research tasks during planning
Agent
tool with 
subagent_type="Explore"
When gathering context from multiple codebase areas
Plan validation across architecture layers
Agent
tool dispatching 
planner
agent		When plan covers multiple system boundaries
After plan approval, independent implementation tasks
Agent
tool (multiple parallel, per 
dispatching-parallel-agents
skill)		When plan steps have no dependencies between them
Follow the 
dispatching-parallel-agents
skill protocol when dispatching.
任务模式调度到时机
规划阶段的独立调研任务
Agent
工具，设置
subagent_type="Explore"
需要从代码库多个区域收集上下文时
跨架构层的规划验证
Agent
工具调度
planner
agent		规划覆盖多个系统边界时
规划批准后，独立的实现任务
Agent
工具（多个并行，遵循
dispatching-parallel-agents
能力规范）		规划步骤之间没有依赖关系时
调度时遵循
dispatching-parallel-agents
能力协议。

Integration Points

集成点

SkillRelationshipWhen
brainstorming
Upstream — provides design contextPlanning follows brainstorming
task-management
Downstream — receives approved planStandard execution path
executing-plans
Downstream — executes plan directlySingle-task execution
subagent-driven-development
Downstream — parallel executionLarge independent task sets
autonomous-loop
Downstream — iterative executionRalph-style sessions
self-learning
Bidirectional — informs and learns from planningContext loading and pattern storage
verification-before-completion
Downstream — verifies plan completenessBefore claiming plan is done
task-decomposition
Complementary — provides WBS for complex plansWhen plan needs hierarchical breakdown
能力关系时机
brainstorming
上游——提供设计上下文规划在头脑风暴之后进行
task-management
下游——接收已批准的规划标准执行路径
executing-plans
下游——直接执行规划单任务执行场景
subagent-driven-development
下游——并行执行大型独立任务集场景
autonomous-loop
下游——迭代执行Ralph风格会话场景
self-learning
双向——为规划提供信息并从规划中学习上下文加载和模式存储
verification-before-completion
下游——验证规划完整性宣布规划完成之前
task-decomposition
互补——为复杂规划提供工作分解结构规划需要分层拆解时

Concrete Examples

具体示例

Example: Small Bug Fix Plan

示例：小型Bug修复规划

markdown
undefined
markdown
undefined

Fix: Login button disabled state not clearing

修复：登录按钮禁用状态不清除问题

Goal: Fix login button remaining disabled after failed login attempt Architecture: State management bug in LoginForm component Approach: Reset 
isSubmitting
state in the catch block of handleSubmit
目标： 修复登录失败后登录按钮一直保持禁用的问题 架构： LoginForm组件的状态管理bug 方案： 在handleSubmit的catch块中重置
isSubmitting
状态

Task 1: Write failing test

任务1: 编写失败的测试用例

Files: Test: 
tests/components/LoginForm.test.tsx
Steps: Write test that submits invalid credentials and verifies button re-enables Verification: 
npm test -- --grep "re-enables button after failed login"
文件： 测试：
tests/components/LoginForm.test.tsx
步骤： 编写提交无效凭据后验证按钮重新启用的测试用例 验证： 
npm test -- --grep "re-enables button after failed login"

Task 2: Fix the bug

任务2: 修复bug

Files: Modify: 
src/components/LoginForm.tsx
Steps: Add 
setIsSubmitting(false)
to catch block in handleSubmit Verification: 
npm test -- --grep "LoginForm"
— all pass
undefined
文件： 修改：
src/components/LoginForm.tsx
步骤： 在handleSubmit的catch块中添加
setIsSubmitting(false)
验证： 
npm test -- --grep "LoginForm"
——所有用例通过
undefined

Example: Transition Command

示例：过渡命令

After plan approval:
Plan approved and saved to docs/plans/2026-03-15-login-fix.md.
Invoking task-management skill to begin tracked execution.
规划批准后：
规划已批准，保存到docs/plans/2026-03-15-login-fix.md。
调用task-management能力开始跟踪执行。

Verification Gate

验证关卡

Before claiming the plan is complete, verify:
  1. IDENTIFY: Plan document exists at 
    docs/plans/
  2. RUN: Review plan for completeness against quality checklist
  3. READ: Verify all sections are filled with specific details
  4. VERIFY: User has explicitly approved
  5. CLAIM: Only then transition to implementation
在宣布规划完成前，验证以下内容：
  1. 确认：规划文档已存在于
    docs/plans/
    目录
  2. 检查：对照质量检查清单确认规划完整性
  3. 阅读：确认所有章节都填写了具体细节
  4. 核实：用户已经明确批准
  5. 执行：仅在以上都满足后过渡到实现阶段

Key Principles

核心原则

  • DRY — Do not repeat yourself
  • YAGNI — Do not build what is not needed yet
  • TDD — Write tests first when applicable
  • Frequent commits — Small, atomic commits after each task
  • Exact paths — Always specify exact file paths in the plan
  • DRY — 不要重复代码
  • YAGNI — 不要开发当前还不需要的功能
  • TDD — 适用场景下先写测试用例
  • 频繁提交 — 每个任务完成后提交小型原子化的代码
  • 准确路径 — 规划中永远指定准确的文件路径

Skill Type

能力类型

RIGID — Follow this process exactly for every implementation task. The phases are sequential and non-negotiable. No code without an approved plan.
RIGID — 每个实现任务都必须严格遵循该流程。阶段是顺序执行的，不可协商。没有批准的规划不能写代码。