planning-patterns

编写计划

概述

编写全面的实现计划，假设工程师对代码库一无所知，判断力也不太可靠。记录他们需要知道的一切：每项任务要修改哪些文件、需要编写哪些代码和测试、需要查阅哪些文档，以及如何测试。将完整计划拆分成易于执行的小任务。遵循 DRY、YAGNI 和 TDD。频繁提交。

计划就是提示词。 计划将由一个毫无先验背景的 AI Agent 执行。请像编写提示词一样编写计划：具体、完整、明确。如果其他 Agent 可能误解某个步骤，那么该步骤就不够具体。

假设执行者是一名熟练的开发者，但对工具集和问题领域几乎一无所知。假设他们不太了解如何设计好的测试。

核心原则： 计划必须能够直接执行，无需提问。

铁律

NO VAGUE STEPS - EVERY STEP IS A SPECIFIC ACTION

“添加验证”不是一个步骤。“为电子邮件为空的情况编写测试、运行测试、实现检查、再次运行测试、提交”——这才是 5 个步骤。

易执行的小任务粒度

每个步骤只做一件事（2～5 分钟）：

• “编写失败的测试”——一个步骤
• “运行测试，确认它失败”——一个步骤
• “编写最精简的代码，让测试通过”——一个步骤
• “运行测试，确认测试通过”——一个步骤
• “提交”——一个步骤

以下不算步骤：

• “添加身份验证”（太含糊）
• “实现该功能”（包含多个操作）
• “测试一下”（哪些测试？如何测试？）

将计划阶段视为有向无环图——每个阶段只能依赖前面的阶段，不能依赖后面的阶段。plan-review-gate 会强制执行此顺序。

拆分触发条件： 如果某个步骤涉及 3 个或更多文件，或需要用一个以上的句子描述，就将其拆分。如果一个阶段有超过 5 项任务，请考虑拆分该阶段。单个步骤以 2～5 分钟为目标；任务组（一个完整的 RED-GREEN-REFACTOR 周期）最长为 15 分钟。

计划文档标题

每份计划都必须以此标题开头：

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED: Follow this plan task-by-task using TDD.
> **Design:** See `docs/plans/YYYY-MM-DD-<feature>-design.md` for full specification.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Prerequisites:** [What must exist before starting]

**Durable Decisions:** [Foundational choices that apply across all phases — route structures, DB schema shape, key data models, auth approach, third-party service boundaries. Every phase references these.]

---

如果存在设计文档，务必在标题中引用它。

任务结构

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.ts`
- Modify: `exact/path/to/existing.ts:123-145`
- Test: `tests/exact/path/to/test.ts`

**Step 1: Write the failing test**

```typescript
test('specific behavior being tested', () => {
  const result = functionName(input);
  expect(result).toBe(expected);
});

步骤 2：运行测试，确认它失败

运行：npm test tests/path/test.ts -- --grep "specific behavior" 预期：失败，提示“functionName is not defined”

步骤 3：编写最精简的实现

function functionName(input: InputType): OutputType {
  return expected;
}

步骤 4：运行测试，确认它通过

运行：npm test tests/path/test.ts -- --grep "specific behavior" 预期：通过

步骤 5：提交

git add tests/path/test.ts src/path/file.ts
git commit -m "feat: add specific feature"

## Context is King (Cole Medin Principle)

**The plan must contain ALL information for a single-pass implementation.**

A developer with zero codebase context should be able to execute the plan WITHOUT asking any questions.

### Context References Section (MUST READ!)

**Every plan MUST include a Context References section:**

```markdown
## Relevant Codebase Files

### Patterns to Follow
- `src/components/Button.tsx` (lines 15-45) - Component structure pattern
- `src/services/api.ts` (lines 23-67) - API service pattern

### Configuration Files
- `tsconfig.json` - TypeScript settings
- `.env.example` - Environment variables needed

### Related Documentation
- `docs/architecture.md#authentication` - Auth flow overview
- `README.md#running-tests` - Test commands

原因： Claude 会忘记上下文。外部文档会过时。文件和行号引用始终准确。

提炼规则

计划必须使用提炼后的内容，而不是摘要。提炼 = 无损压缩，保留每个实体、关系、决策和约束。摘要 = 有损精简，会丢失具体信息。如果计划中的某个部分可以缩短，且不遗漏执行者需要的任何事实，就应提炼。如果缩短会导致信息缺失，就保留完整内容。检验方法：执行计划的 Agent 能否只凭这份计划完成工作，而无需重新查阅源文件？如果不能，说明计划提炼得还不够充分。

验证级别

根据计划的复杂度匹配验证深度：

级别	名称	命令	适用情况
1	语法与风格	npm run lint、tsc --noEmit	每项任务
2	单元测试	npm test	低至中风险
3	集成测试	npm run test:integration	中至高风险
4	手动验证	演练用户流程	高至严重风险

在每个任务步骤中写明具体的验证命令。

类生产环境验证规划

当请求涉及真实 API、预置数据、浏览器流程、后台任务或压力／负载行为时，在最终确定计划前阅读 references/live-verification-strategy.md。

使用该参考文档添加 ### Live Verification Strategy 章节，并注明：

• 测试框架清单路径
• 设置、重置、播种数据、健康检查和清理命令
• 第一方系统边界与外部依赖
• 使用 Given/When/Then 描述的具名验证场景
• 负载行为相关时的压力配置和通过阈值

不要悄悄将类生产环境验证降级为仅回放、仅单元测试或仅手动操作。如果尚不存在实时测试框架，请在计划中明确指出这一缺口。

需求检查清单

编写计划前：

• 问题陈述清晰
• 已确定用户
• 已列出功能需求
• 已列出非功能需求（性能、安全性、规模）
• 已记录约束
• 已定义成功标准
• 已了解现有代码模式
• 已准备包含文件:行号引用的上下文参考章节

计划完整性门槛

保存前，确认每个阶段均符合以下标准：

标准	检查
完成定义	退出标准可演示且可测试（而非“基础工作已完成”）
可衡量的交付物	每项任务均列出要创建／修改的确切文件及文件:行号
合理的估算	每项任务不超过 5 分钟；每个阶段不超过 1 小时
明确的依赖关系	阶段 N 仅引用前置阶段，不引用未来阶段
包含风险缓解措施	每项分数 > 8 的风险均有对应的缓解措施行
每个阶段均可测试	每个阶段的退出标准都能通过运行命令验证
跨阶段契约	阶段 N 的退出标准包含阶段 N+1 所需的确切数据形状、API 契约或文件结构

缺少任意一项的计划都不完整。请在保存前修订。

**退出标准示例：**不要写“阶段 1 在身份验证正常工作时完成”。应写“阶段 1 在运行 curl -X POST /api/auth/login -d '{"email":"[email protected]","password":"pass"}' returns 200 with {token: string}. 后返回 200，且响应包含 {token: string} 时完成。”具体的输入／输出示例可避免误解。

风险评估表

评分前，先将每项风险归入以下四个维度之一：

维度	评估内容
技术	超出团队经验的复杂性、未知库、集成方面的未知因素
时间线	估算的不确定性、资源可用性、外部依赖的交付日期
质量	测试缺口、回归影响范围、仅手动验证的步骤
安全性	漏洞暴露、身份验证范围、数据敏感性、合规要求

对每项已识别的风险：

风险	概率（1-5）	影响（1-5）	分数	缓解措施
API 超时	3	4	12	使用退避机制重试
输入无效	4	2	8	添加验证层
绕过身份验证	2	5	10	进行安全审查

分数 = 概率 × 影响。优先处理分数 > 8 的风险。

基于风险的测试矩阵

根据任务风险匹配测试深度：

任务风险	示例	所需测试
极低	修正文案、更新文档	无
低	单文件更改、工具函数	仅单元测试
中	多文件功能、新组件	单元测试 + 集成测试
高	跨服务、身份验证、状态管理	单元测试 + 集成测试 + E2E 测试
严重	支付、安全性、数据迁移	所有测试 + 安全审计

风险评估方法：

• 涉及多少个文件？（1 个 = 低，3 个以上 = 中，跨服务 = 高）
• 是否涉及身份验证／支付／安全性？（始终为高或严重）
• 是否面向用户？（最低为中）
• 是否可能导致数据丢失？（高或严重）

规划测试步骤时使用此矩阵。不要对极低风险的更改过度测试，也不要对严重风险的更改测试不足。

功能流程映射

规划前，请记录所有流程：

用户流程：

1. User clicks [button]
2. System shows [form]
3. User enters [data]
4. System validates [input]
5. System saves [data]
6. System shows [confirmation]

管理员流程：

1. Admin opens [dashboard]
2. Admin selects [item]
3. System shows [details]
4. Admin changes [setting]
5. System applies [change]

系统流程：

1. Request arrives at [endpoint]
2. Middleware validates [auth]
3. Controller calls [service]
4. Service queries [database]
5. Response returns [data]

架构决策记录（ADR）

比较方案时，请正式记录决策：

当计划涉及在多个可行方案之间做出选择时，请使用以下格式：

## ADR: [Decision Title]

**Context:** What situation or requirement prompted this decision?

**Decision:** What approach did we choose?

**Consequences:**
- **Positive:** [benefits of this choice]
- **Negative:** [tradeoffs we accept]
- **Alternatives Considered:** [what we didn't choose and why]

何时使用 ADR：

• 在不同架构之间做出选择（单体架构 vs 微服务）
• 选择库/框架（React vs Vue）
• 数据库决策（SQL vs NoSQL）
• 身份验证方案（JWT vs 会话）

将 ADR 保存到： docs/decisions/ADR-NNN-title.md

危险信号——停止并修改

如果你发现自己正在：

• 写“添加功能”，却没有注明准确的文件路径
• 跳过测试步骤
• 将多个操作合并为一个步骤
• 用“等等”或“类似”代替明确步骤
• 不了解现有代码模式就开始规划
• 创建耗时超过 5 分钟的步骤
• 未注明测试命令的预期输出

停止。修改计划，使步骤更加具体。

防止合理化

借口	实际情况
“他们会明白我的意思”	不会。请明确说明。
“细节太多会让人烦”	含糊的计划会导致错误。
“测试显而易见”	写出测试命令。
“文件路径可以找到”	写出准确路径。
“提交是默认的”	写明何时提交。
“他们能处理边缘情况”	列出所有边缘情况。
“计划还不够完美”	现在有个好计划，胜过永远没有完美计划。先交付，再在执行中迭代。

输出格式

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED: Follow this plan task-by-task using TDD.

**Goal:** [One sentence]

**Architecture:** [2-3 sentences]

**Tech Stack:** [Technologies]

**Prerequisites:** [Requirements]

**Durable Decisions:** [Foundational choices that apply across all phases — route structures, DB schema shape, key data models, auth approach, third-party service boundaries]

---



## Phase 1: [Demonstrable Milestone]

> **Exit Criteria:** [What must be true when this phase is complete - e.g., "User can log in and receive JWT"]

### Task 1: [First Component]

**Files:**
- Create: `src/path/file.ts`
- Test: `tests/path/file.test.ts`

**Step 1:** Write failing test
[code block with test]

**Step 2:** Run test, verify fails
Run: `[command]`
Expected: FAIL

**Step 3:** Implement
[code block with implementation]

**Step 4:** Run test, verify passes
Run: `[command]`
Expected: PASS

**Step 5:** Commit
```bash
git add [files]
git commit -m "feat: [description]"

任务 2：[第二个组件]

...

---

风险

风险	P	I	得分	缓解措施
...	...	...	...	...

---

成功标准

• 所有测试均通过
• 功能符合规范
• 没有回归问题
• 代码已审核

## Save the Plan (MANDATORY)

**One direct save is required - the plan file. Memory indexing is router-owned.**

### Step 1: Save Plan File (Use Write tool - NO PERMISSION NEEDED)

首先创建目录

Bash(command="mkdir -p docs/plans")

然后使用 Write 工具保存计划（无需权限）

Write(file_path="docs/plans/YYYY-MM-DD--plan.md", content="[上述输出格式中的完整计划内容]")

不要自动提交——由用户决定何时提交

### Step 2: Emit Router-Owned Memory Intent (CRITICAL)

Do **NOT** edit `.cc10x/v10/*.md` from this skill.

Instead, use the planner agent's existing `MEMORY_NOTES` contract only for durable learnings, deferred items, or verification context that is not already derivable from the planner contract.

**WHY BOTH:** The plan file is the artifact. Router-owned memory finalization derives plan indexing from `PLAN_FILE` and workflow state, so this skill must not invent a second memory serialization path.

## Router-Owned Task Tracking

The planner does **not** create execution tasks. Its job is to create the plan artifact and emit a router contract.

After planning:
- Save the plan file.
- Update memory with the plan reference.
- Let the router create workflow and execution tasks from the approved plan.

Do not instruct the planner to call `TaskCreate` or `TaskUpdate` for phase tracking.

## Plan-Task Linkage (Context Preservation)

**The relationship between Plan Files and Tasks:**

┌─────────────────────────────────────────────────────────────────────┐ │ 计划文件（持久化 - 事实来源） │ │ 位置：docs/plans/YYYY-MM-DD-{feature}-plan.md │ │ 内容：完整的实现细节、TDD 步骤、文件路径 │ │ 保留：会话关闭、上下文压缩、对话重置后仍然保留 │ └─────────────────────────────────────────────────────────────────────┘ ↕ 任务描述中包含计划文件路径 ┌─────────────────────────────────────────────────────────────────────┐ │ 任务（执行引擎） │ │ 内容：状态、依赖项、进度跟踪 │ │ 保留：上下文压缩后仍然保留；可通过任务列表配置在会话间共享 │ │ （官方 Claude Code） │ └─────────────────────────────────────────────────────────────────────┘

**Plan path-in-description is CRITICAL:** If context compacts mid-execution, the task description contains enough info to:
1. Find the plan file
2. Locate the exact phase/task
3. Continue without asking questions

**Phase Exit Criteria are CRITICAL:** Each phase MUST have a demonstrable milestone (not arbitrary naming):
- ❌ "Phase 1: Foundation" - Vague, when is it done?
- ✅ "Phase 1: User can authenticate" - Demonstrable, testable

## Execution Handoff

After saving the plan, offer execution choice:

**"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**

**1. Subagent-Driven (this session)** - Fresh subagent per task, review between tasks, fast iteration

**2. Manual Execution** - Follow plan step by step, verify each step

**Which approach?"**