planning

结构化规划

概述

结构化规划会在编写任何代码之前，将模糊的需求转化为经过批准并记录在案的实施计划。它会要求提出澄清问题、比较不同方案及其权衡，并明确获得用户批准，从而避免最常见的精力浪费原因：做错了东西。无论任务看起来多么简单，都必须经过此流程。

开始时宣布：“我将使用规划技能来制定结构化实施计划。”

触发条件

• 用户请求新功能、增强功能或变更
• 修复 Bug 需要进行超过一行的改动
• 涉及多个文件的重构工作
• 任何尚无已记录并获批准方案的任务
• 从头脑风暴技能切换到已获批准的设计
• 调用了 /plan 命令

---

阶段 1：收集上下文

目标： 在提问之前了解代码库和现有模式。

1. 阅读相关文件、文档、近期提交和 CLAUDE.md
2. 检查记忆文件，了解已知的项目上下文、技术栈和约定
3. 查看 docs/plans/ 中与相关工作有关的现有计划
4. 确定新工作应遵循的现有模式
5. 记录探索过程中发现的技术限制

停止——在进入阶段 2 之前，不得继续：

• 已探索代码库的相关部分
• 已了解现有架构和模式
• 已检查记忆文件中的过往决策

---

阶段 2：澄清问题

目标： 通过一次提出一个有针对性的问题来消除歧义。

1. 每条消息只问一个问题——切勿一次提出多个问题
2. 尽可能优先使用选择题
3. 提问前先研究代码库——不要询问可以自行查明的内容
4. 将模糊的需求转化为具体、可测试的标准

问题类别优先级

优先级	类别	示例问题
1	目的	“这要解决什么问题？面向谁？”
2	成功标准	“我们如何确认它能正常工作？怎样才算‘完成’？”
3	限制条件	“是否有性能、兼容性或时间方面的限制？”
4	非目标	“有哪些内容明确不应该构建？”
5	现有模式	“应该遵循 X 使用的模式，还是需要采用新方案？”
6	边界情况	“在[边界条件]下应该如何处理？”

提问规则

规则	理由
每条消息只问一个问题	避免认知负担过重
优先使用选择题	回答更快，也能减少歧义
提问前先研究	尊重用户的时间——先自行查明可发现的内容
使用可测试的标准	模糊的回答会导致模糊的实现

停止——在进入阶段 3 之前，不得继续：

• 已了解目的和成功标准
• 已确定限制条件和非目标
• 不再存在关键歧义

---

阶段 3：设计方案

目标： 提出 2-3 个具体方案，说明权衡，并给出明确建议。

对每个方案，请包含：

部分	内容
架构概要	用 2-3 句话描述方案
关键文件	要创建或修改的确切路径
依赖项	外部依赖或破坏性变更
权衡	明确列出优缺点
工作量估算	任务数量（不是小时数）
风险级别	低 / 中 / 高，并说明原因

方案选择决策表

因素	权重	评估方式
与现有模式的一致性	高	是否符合当前代码库的约定？
简洁性	高	满足要求所需的最少组件
可测试性	中	能否独立测试每个组件？
未来可扩展性	低	仅在用户提及未来计划时考虑
性能	不定	仅在用户指定性能约束时考虑

首先提出你推荐的方案。 说明在当前约束下，它为何是最佳选择。列出备选方案，体现你考虑过各种权衡。

停止 — 在进入第 4 阶段之前，不要继续：

• 至少提出 2 个方案
• 记录每个方案的权衡
• 给出明确的推荐方案并说明理由

---

第 4 阶段：编写计划文档

目标： 编写一份详细、可执行的计划文档，并获得明确批准。

计划文档格式

# [Feature Name] Implementation Plan

**Goal:** [One sentence]
**Architecture:** [2-3 sentences]
**Approach:** [Which approach was chosen and why]

---

### Task N: [Component Name]

**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]

计划质量检查清单

标准	检查
每项任务都有准确的文件路径	不要写“在 src/ 的某个位置”
每项任务都有验证命令	不要写“目测检查”
任务按依赖关系排序	不要出现前向引用
每项任务耗时为 2–5 分钟	不要写“实现整个模块”
明确列出 TDD 步骤	每项任务都遵循 RED-GREEN-REFACTOR

将计划保存到 docs/plans/YYYY-MM-DD-<feature>.md。

停止 — 在进入第 5 阶段之前，不要继续：

• 已编写并保存计划文档
• 每项任务都包含文件路径、步骤和验证方式
• 用户已明确批准计划（表示“是”“批准”“开始”等）

---

第 5 阶段：转入执行

目标： 将已批准的计划交接给合适的执行技能。

转接决策表

情况	下一项技能	理由
标准实现（少于 10 项任务）	task-management	按顺序跟踪执行
大型实现（10 项或更多独立任务）	subagent-driven-development	并行执行并设置审查关卡
自主开发会话	autonomous-loop	Ralph 风格的迭代执行
单一的聚焦任务	executing-plans	直接执行计划

调用选定的技能，并传入计划文档路径。

---

反模式 / 常见错误

反模式	失败原因	正确做法
“这个任务太简单，不需要计划”	简单任务也有未经审视的假设	仍然要做计划——计划可以很简短
“我已经知道该怎么做”	你的方案可能与项目模式冲突	记录方案并获得批准
“用户希望快点完成”	糟糕的代码比有计划的代码更耗时	计划能避免返工
“这只是修复一个 bug”	修复 bug 需要分析根本原因	规划修复过程，而不只是打补丁
“我边做边计划”	这是临场发挥，不是计划	先计划，再执行
一次提出 5 个问题	会让用户不堪重负，并得到含糊的回答	每条消息只问一个问题
只提出 1 个方案	缺少权衡分析，可能错过更好的选择	始终提出 2–3 个方案
文件引用含糊	“更新测试”——要更新哪些测试？	始终提供准确的文件路径
耗时超过 30 分钟的任务	任务太大，难以跟踪和验证	拆分为 2–5 分钟的小任务
未经批准就开始编写代码	如果方向改变，会白费功夫	等待明确答复“是”

反合理化防护

在满足以下条件之前，不要编写任何代码、创建任何文件或采取任何实施行动： 1. 你已提出澄清问题并理解需求 2. 你已提出不同方案及其权衡 3. 用户已明确批准计划

无论任务看起来多么简单，这都适用于每一项任务。

铁律：未经批准的计划，不写代码。 没有例外。不能说“就做这一点小事”。也不能说“这很明显”。

如果你发现自己在想以下任何事情，请立即停下：

• “我就快速……一下。”——不行。先制定计划。
• “这不需要完整计划……”——需要。计划可以很简短。
• “之后再补充文档……”——不行。先记录文档。

---

子 Agent 调度时机

任务模式	调度对象	时机
规划期间的独立研究任务	使用 subagent_type="Explore" 的 Agent 工具	从代码库的多个区域收集上下文时
跨架构层验证计划	调度 planner Agent 的 Agent 工具	计划涵盖多个系统边界时
计划获批后的独立实施任务	Agent 工具（多个并行任务，遵循 dispatching-parallel-agents 技能）	计划步骤之间没有依赖关系时

调度时遵循 dispatching-parallel-agents 技能的流程。

---

集成点

技能	关系	时机
brainstorming	上游 — 提供设计上下文	规划在头脑风暴之后进行
task-management	下游 — 接收获批的计划	标准执行路径
executing-plans	下游 — 直接执行计划	单任务执行
subagent-driven-development	下游 — 并行执行	大量相互独立的任务
autonomous-loop	下游 — 迭代执行	Ralph 式会话
self-learning	双向 — 为规划提供信息并从规划中学习	加载上下文和存储模式时
verification-before-completion	下游 — 验证计划是否完整	宣布计划完成之前
task-decomposition	互补 — 为复杂计划提供工作分解结构	计划需要分层拆解时

---

具体示例

示例：小型缺陷修复计划

# 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

### Task 1: Write failing test
**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"`

### Task 2: Fix the bug
**Files:** Modify: `src/components/LoginForm.tsx`
**Steps:** Add `setIsSubmitting(false)` to catch block in handleSubmit
**Verification:** `npm test -- --grep "LoginForm"` — all pass

示例：转换命令

计划获批后：

Plan approved and saved to docs/plans/2026-03-15-login-fix.md.
Invoking task-management skill to begin tracked execution.

---

验证关卡

在宣布计划完成之前，请验证：

1. 识别：计划文档存在于 docs/plans/
2. 执行：根据质量检查清单审查计划是否完整
3. 阅读：确认所有部分都已填写具体细节
4. 验证：用户已明确批准
5. 声明：只有此时才能转入实施阶段

---

核心原则

• DRY — 不要重复自己
• YAGNI — 不要构建当前还不需要的内容
• TDD — 在适用时先编写测试
• 频繁提交 — 每项任务完成后进行小型、原子化提交
• 精确路径 — 始终在计划中指定确切的文件路径

---

技能类型

RIGID — 每项实施任务都必须严格遵循此流程。各阶段按顺序进行，不容协商。未经批准的计划，不写代码。