编写实施计划
概述
编写全面的实现计划，假设工程师对你的代码库毫无了解。记录他们需要知道的一切：每个任务要接触哪些文件、代码、测试、如何测试。将整个计划作为小任务呈现。
开始时声明： "我正在使用 writing-plans skill 来创建实现计划。"
保存计划到： docs/plans/YYYY-MM-DD-<feature-name>.md
小任务粒度
每个步骤是一个动作（2-5 分钟）：
- •"编写失败的测试" - 步骤
- •"运行它以确认失败" - 步骤
- •"编写使测试通过的最小代码" - 步骤
- •"运行测试确保通过" - 步骤
- •"提交" - 步骤
迭代式计划结构
第一阶段：高层计划
- •目标：明确要做什么
- •输出：3-5 个主要阶段的粗略描述
- •原则：先有整体框架，再逐个细化
第二阶段：里程碑细化
- •目标：每个里程碑独立成计划
- •输出：每个里程碑的详细任务列表
- •原则：可以逐个细化，不必一次性完成所有细节
第三阶段：任务细化
- •目标：每个任务 = 1 个独立步骤
- •最细粒度：2-5 分钟可完成
- •原则：越小越容易验证和调整
分阶段计划
对于较大需求，可以将计划分成多个阶段：
阶段划分原则
- •按依赖关系：核心功能 → 增强功能 → 高级功能
- •按价值交付：先完成可独立使用的功能
- •每个阶段独立完整：一个阶段内的任务闭环
阶段计划模板
markdown
## Phase 1: [阶段名称] **目标**：[一句话描述] **交付物**：[预期产出] ### 任务列表 - [ ] 任务1：... - [ ] 任务2：... ### 功能完整性检查 [对照需求检查本阶段功能点是否完整] ## Phase 2: [阶段名称] ...
执行要求
- •每个阶段都要完整细化：不能只列大纲，每个任务都要细化到 2-5 分钟
- •细化后才算完成：一个阶段的任务全部细化完，才能开始下一个阶段
- •阶段间可调整：后续阶段可以根据实际执行情况补充或调整
执行检查点
重要：确保每个任务都被执行，不遗漏。
任务标记格式
- •
[ ]- 待执行 - •
[x]- 已完成
执行流程
- •开始执行前：读取计划文档，检查任务完成状态
- •从第一个未完成任务继续：找到第一个
[ ]标记的任务开始执行 - •执行完成后：同步更新任务状态为
[x] - •定期检查：可以随时输入"检查计划进度"查看剩余任务
跨会话追踪
- •每次开始执行计划时，读取计划文档获取当前进度
- •计划文档就是进度记录，不需要额外文件
- •配合 git commit，计划文档本身就是完整的执行历史
功能完整性检查（任务细化补充）
重要：在完成任务细化后，必须进行功能完整性检查，基于功能类型主动思考可能的遗漏点。
思考引导
对于每类功能，AI 主动思考常见的功能点：
| 功能类型 | 通常需要考虑的功能点 |
|---|---|
| 管理类（CRUD） | 列表、新增、编辑、删除、分页、搜索 |
| 配置类 | 查看、编辑、校验、保存 |
| 报表类 | 列表、分页、筛选、导出 |
| 权限类 | 列表、授权、撤销、查看权限 |
检查清单
对于每个功能模块，识别所有需要实现的功能点：
markdown
## 功能完整性检查表 | 模块 | 功能点 | 是否实现 | 任务编号 | |------|--------|----------|----------| | 租户管理 | 列表查看 | [ ] | 任务1 | | 租户管理 | 新增租户 | [ ] | 任务2 | | 租户管理 | 编辑租户 | [ ] | 任务3 | | 租户管理 | 删除租户 | [ ] | 任务4 | | 租户管理 | 批量删除 | [ ] | - |
功能点分类标准
| 类别 | 说明 | 示例 |
|---|---|---|
| P0（必须） | 核心 CRUD | 列表、新增、编辑、删除 |
| P1（建议） | 批量操作 | 批量删除、批量导入 |
| P2（可选） | 高级功能 | 导出、统计、审计日志 |
检查流程
- •列出所有模块 - 从需求/设计中识别所有功能模块
- •识别功能点 - 对每个模块，列出所有操作（CRUD + 批量 + 其他）
- •分配任务 - 确保每个功能点都有对应的任务
- •标记优先级 - P0 必须有任务，P1/P2 可选
- •用户确认 - 与用户核对是否有遗漏
常见功能点遗漏
以下功能点经常被遗漏，务必检查：
- • 列表分页
- • 搜索/筛选
- • 新增/编辑表单验证
- • 删除确认
- • 批量操作
- • 导入/导出
- • 权限控制
- • 状态变更（启用/禁用）
- • 详情查看
- • 关联数据展示
输出要求
在计划文档的"计划头部"之后添加"功能完整性检查"章节：
markdown
## 功能完整性检查 ### 模块：租户管理 | 功能点 | 优先级 | 任务编号 | 备注 | |--------|--------|----------|------| | 列表查看 | P0 | 任务1 | 分页+搜索 | | 新增租户 | P0 | 任务2 | 表单验证 | | 编辑租户 | P0 | 任务3 | 数据回显 | | 删除租户 | P0 | 任务4 | 软删除 | | 批量删除 | P1 | - | 暂不实现 | | 启用/禁用 | P1 | - | 暂不实现 | **已确认遗漏功能：** [如有]
开始创建计划前：检查需求文档
重要：在创建实施计划之前，必须先检查相关需求文档，确保计划满足所有必要条件。
步骤 1：查找相关需求
- •扫描
docs/requirements/目录下的所有需求文档 - •识别与当前计划主题相关或可能冲突的需求
- •区分：
- •直接相关：此计划必须满足的需求
- •间接相关：可能影响此计划的需求
- •不相关：与此计划无关的需求
步骤 2：分析冲突
检查以下可能的冲突：
- •新功能是否与已有功能重复？
- •新功能是否修改/扩展已有功能？
- •是否有相互矛盾的验收标准？
- •是否有数据模型变更冲突？
步骤 3：在计划中标注
如果发现相关需求或潜在冲突，在计划头部标注：
markdown
**关联需求：** - 直接相关：需求A（必须满足） - 间接相关：需求B（需注意） **潜在冲突：** - 需求C 与本计划有数据模型冲突，建议确认
步骤 4：与用户确认
如果发现潜在冲突或不确定的情况：
- •告知用户发现了哪些相关需求
- •指出可能的冲突点
- •确认是否需要调整计划或需求
计划确认（重要）
在保存计划之前，必须进行计划确认
为什么需要确认
- •用户描述可能存在不清晰、有矛盾的地方
- •提前发现计划遗漏或问题
- •减少因理解偏差导致的返工
确认流程
- •
整理成清晰的步骤列表
- •把计划整理成易读的步骤
- •列出每个阶段的主要任务
- •
列出可能的问题
- •需求不清晰的地方
- •可能存在冲突的地方
- •计划可能遗漏的地方
- •
与用户确认
markdown### 计划确认 **我整理的计划步骤：** 1. [步骤1] 2. [步骤2] 3. [步骤3] **可能存在的问题：** - [问题1：xxx] - [问题2：xxx] **请您确认：** - 以上理解是否正确？ - 有什么需要补充或修改的？
确认原则
- •复杂任务必须确认：涉及多个模块、多个阶段的任务
- •简单任务可以跳过：单一功能、简单实现的任务
- •记录确认内容：确认后记录在计划文档中
场景判断
| 场景 | 是否需要确认 |
|---|---|
| 新功能开发 | ✅ 需要 |
| Bug 修复 | ⚠️ 看复杂度 |
| 简单修改 | ❌ 跳过 |
| 重构 | ✅ 需要 |
计划文档头部
每个计划必须包含 E2E 测试计划（有前端项目）：
注意：此要求仅适用于有前端的项目。纯后端项目跳过 E2E 测试计划。
markdown
## E2E 测试计划（有前端项目） ### 关键流程（有前端则覆盖） - [ ] 用户登录/登出 - [ ] 核心业务功能 ### 测试方式 - [ ] 使用 Playwright - [ ] 使用 data-testid 选择器 - [ ] 失败时自动截图
每个计划必须以此头部开头：
markdown
# [功能名称] 实现计划 > **For Claude:** 必需子技能：使用 executing-plans 逐个任务实现此计划。 **目标：** [一句话描述要构建什么] **架构：** [2-3 句话描述方法] **技术栈：** [根据项目实际情况] **关联需求：** - 直接相关：[需求名称]（必须满足） - 间接相关：[需求名称]（需注意） - 潜在冲突：[如有] --- ## 风险评估 | 风险 | 严重程度 | 缓解措施 | |------|----------|----------| | [依赖版本冲突] | 高/中/低 | [具体措施] | | [数据库迁移失败] | 高/中/低 | [具体措施] | --- ## 里程碑验收标准 ### 里程碑 1：[名称] - [ ] 功能正常运行 - [ ] 单元测试覆盖率 > 80% - [ ] 无安全漏洞 ### 里程碑 2：[名称] - [ ] 集成测试通过 - [ ] 性能指标达标 - [ ] 代码审查通过 --- ## 审查节点 - **任务级**：每个任务完成后子代理自审 - **里程碑级**：里程碑完成后提交审查 - **整体级**：计划执行前整体审查 ---
任务结构
markdown
### 任务 N：[组件名称]
**依赖：**
- 前置任务：任务X, 任务Y（必须先完成）
- 可并行任务：任务A, 任务B（可并行执行）
- 外部依赖：[npm包名/版本]、[API端点]、[配置文件]
**文件：**
- 创建：`exact/path/to/file.ts`
- 修改：`exact/path/to/existing.ts:123-145`
- 测试：`tests/exact/path/to/test.ts`
- **E2E 测试（有前端项目）**：`tests/e2e/specs/xxx.spec.ts`
**风险提示：** [此项可能的风险及缓解措施]
**回滚步骤（涉及数据/结构变更时必须）：**
1. `git checkout src/path/file.ts`
2. `python scripts/rollback_migration.py`
**步骤 N：E2E 测试（有前端项目且是关键功能则必须）**
如果有前端项目且涉及用户界面，需要添加 E2E 测试：
```typescript
test('功能名称', async ({ page }) => {
await page.goto('/feature');
// 验证关键交互
await expect(page.locator('[data-testid="xxx"]')).toBeVisible();
});
步骤 1：编写失败的测试
typescript
function test_specific_behavior() {
const result = function(input)
expect(result).toBe(expected)
}
步骤 2：运行测试验证失败
运行：npm test tests/path/test.ts
预期：FAIL with "function not defined"
步骤 3：编写最小实现
typescript
function function(input) {
return expected
}
步骤 4：运行测试验证通过
运行：npm test tests/path/test.ts
预期：PASS
步骤 4.5：快速验证（每个任务必须）
在运行测试前，先尝试运行或验证生成的代码，确保无明显错误：
| 语言 | 验证方式 |
|---|---|
| JavaScript/TypeScript | node --check src/path/file.ts 或直接运行 |
| Python | python -m py_compile src/path/file.py |
| Go | go build src/path/file.go |
| Rust | rustc --check src/path/file.rs |
| Java | javac src/path/File.java |
核心目标：确保代码无语法错误、导入错误，再继续。
如果验证失败（语法错误、导入错误），修复后再继续。
步骤 5：提交
bash
git add tests/path/test.ts src/path/file.ts git commit -m "feat: add specific feature"
记住
- •始终使用精确的文件路径
- •完整代码在计划中（不是"添加验证"）
- •精确命令带预期输出
- •DRY, YAGNI, TDD, 频繁提交
计划调整
何时调整
- •里程碑完成后对照原始需求检查
- •发现计划遗漏的步骤
- •需求有变化
- •发现新的依赖或风险
调整流程
- •暂停当前进度
- •分析需要调整的部分
- •与用户确认调整方案
- •更新计划后继续执行
调整原则
- •计划是活的，可以细化
- •不要害怕调整，迭代才能完善
- •每次调整都要有明确理由
执行交接
保存计划后，提供执行选择：
"计划完成并保存到 docs/plans/<filename>.md。三个执行选项：
1. 子代理驱动（本会话） - 每个任务分配新的子代理，串行执行，任务间审查
2. 混合执行（本会话） - 分析任务依赖关系，可并行任务同时执行，串行任务按顺序执行
3. 并行会话（单独） - 在新会话中打开 executing-plans，批量执行带检查点
推荐逻辑：
- •如果计划中有可并行的独立任务 → 推荐"混合执行"
- •如果所有任务都是串行依赖 → 推荐"子代理驱动"
- •如果想在单独会话中执行 → 选择"并行会话"
选择哪个方法？"
如果选择子代理驱动：
- •使用 subagent-driven-development 技能
- •保持在本会话
- •每个任务 + 代码审查的新子代理
如果选择混合执行：
- •使用 executing-plans skill 的混合模式
- •分析任务依赖，识别可并行任务
- •同时启动多个子代理处理并行任务
- •串行任务按顺序执行
- •如果没有可并行任务，自动退化为子代理驱动模式
如果选择并行会话：
- •引导用户在 worktree 中打开新会话
- •新会话使用 executing-plans 技能
关联需求文档（计划创建后）
创建实施计划后，完成以下操作：
- •查找当前相关的需求文档（
docs/requirements/目录下与计划主题匹配的文档） - •在需求文档末尾追加以下内容：
- •实施计划概要（2-3 句话）
- •计划文件链接：
docs/plans/YYYY-MM-DD-<feature-name>.md
- •更新"讨论进度"为"已完成"
- •告知用户已将计划关联到需求文档
注意：计划创建前的需求检查（识别关联/冲突）已经在"开始创建计划前：检查需求文档"步骤中完成。
进度追踪更新
创建实施计划后，同步更新进度文件：
- •更新
docs/plans/progress.md：
markdown
| [任务名] | writing-plans | ✅ 已完成 | YYYY-MM-DD | | [任务名] | executing-plans | 🔄 进行中 | YYYY-MM-DD |
- •添加执行阶段信息：
markdown
## 执行阶段 ### Phase 1: [名称] - 状态：🔄 进行中 - 开始时间：YYYY-MM-DD HH:MM - 预计完成：XXX #### 任务列表 - [ ] 任务 1 - [ ] 任务 2
- •确保与 brainstorming 阶段的进度衔接：
- •继承 brainstorming 创建的进度记录
- •继续更新同一任务的进度
计划执行完成后，需要更新以下文档：
- • API 文档（如有变更）：更新
docs/api/下的接口说明 - • README：更新功能说明和使用方法
- • 架构图：如有架构变更，更新
docs/architecture/下的图表 - • 数据库文档：如有表结构变更，更新
docs/database/下的 ER 图
注意： 文档更新应在代码审查通过后、提交前完成。
技术栈
根据项目实际情况确定。
- •测试覆盖率: 80%
工作流集成
- •brainstorming → 理解需求
- •writing-plans → 创建实施计划
- •executing-plans → 执行计划（带里程碑评审和调整机制）
- •verification-before-completion → 代码质量验证
- •execution-validation → 需求-实现对照验收
- •update-blueprint → 更新蓝图