实现计划编写

编写实现计划：小粒度任务、路径规划、代码方案

Writing Implementation Plans

概述

编写全面的实现计划，假设实施者对代码库没有任何上下文背景。记录他们需要的一切：需要修改的文件、完整代码、测试命令、需要查看的文档、如何验证。给他们小粒度的任务。DRY、YAGNI、TDD、频繁提交。假设实施者是一个熟练的开发者，但对工具集或问题领域几乎一无所知。假设他们不太了解好的测试设计。

核心原则：好的计划让实现变得显而易见。如果有人需要猜测，计划就不完整。

使用场景

始终使用：

实施多步骤功能之前

分解复杂需求时

通过 subagent-driven-development 向子代理委派任务时

不要跳过：

功能看起来很简单时（假设会导致错误）

计划自己实现时（未来的你需要指导）

独自工作时（文档很重要）

小粒度任务粒度

每个任务 = 2-5 分钟的专注工作。每个步骤都是一个操作：

"编写失败的测试" — 步骤
"运行它确保它失败" — 步骤
"编写最少的代码让测试通过" — 步骤
"运行测试确保它们通过" — 步骤
"提交" — 步骤

太大：

### Task 1: 构建认证系统
[跨5个文件的50行代码]

合适大小：

### Task 1: 创建带 email 字段的 User 模型 [10行，1个文件]
Task 2: 给 User 添加密码哈希字段 [8行，1个文件]
Task 3: 创建密码哈希工具 [15行，1个文件]

计划文档结构

头部（必需）

每个计划必须以以下内容开头：

# [功能名称] 实现计划

> For Hermes: 使用 subagent-driven-development skill 逐任务实施此计划。

目标： [一句话描述这个构建什么]
架构： [2-3句话描述方法]
技术栈： [关键技术和库]

---

任务结构

每个任务遵循此格式：

### Task N: [描述性名称]

目标： 这个任务完成什么（一句话）
验证： 如何知道它完成（命令或检查）
文件：
  - [文件路径] — [要做什么，5-15行]

如果遇到阻碍：
  调试命令：[命令]
  常见问题：[链接到相关任务或文档]

文件级别详细程度

小文件（≤100行）：直接包含完整代码

大文件（>100行）：包含你需要修改的特定部分

文件：

src/auth/user.js — 添加 register() 方法

  

  // 在这个位置添加（大约第15行）
  async function register(email, password) {
    // TODO: 实现注册逻辑
  }
  

与 subagent-driven-development 集成

计划完成后，使用 subagent-driven-development 逐任务实施：

delegate_task(
  goal="按照计划实施 Task 1: 创建 User 模型",
  context=read_file("plans/[feature-name].md"),
  toolsets=["file", "terminal", "search"]
)

计划中的每个任务应该足够小，子代理可以在 2-5 分钟内完成。

好的计划示例

# 用户注册实现计划

> For Hermes: 使用 subagent-driven-development skill 逐任务实施此计划。

目标： 用户可以通过邮箱密码注册账户
架构： JWT 认证，用户密码 bcrypt 哈希存储
技术栈： Node.js, Express, SQLite, bcrypt, jsonwebtoken

---

Task 1: 创建 User 模型

目标： 建立用户数据模型和数据库表
验证： sqlite3 db/test.db ".schema users" 显示 users 表存在
文件：

models/user.js — 创建 User 模型类 [20行]
db/init.sql — 添加 users 表创建语句 [10行]


如果遇到阻碍：
  调试命令：cat db/test.db | sqlite3 ".tables"
  常见问题：参见 Task 2 的数据库初始化部分

Task 2: 添加密码哈希功能

目标： 注册时安全存储密码
验证： node -e "require('./utils/hash').hash('test').then(h => console.log(h.length))" 显示60字符哈希
文件：

utils/hash.js — bcrypt 哈希工具 [15行]


如果遇到阻碍：
  调试命令：npm list bcrypt
  常见问题：确保 bcrypt 版本兼容 Node.js 版本

Task 3: 创建注册 API 端点

目标： POST /api/register 接受邮箱密码并创建用户
验证： curl -X POST http://localhost:3000/api/register -d '{"email":"test@test.com","password":"abc123"}' 返回用户对象（无密码字段）
文件：

routes/auth.js — 添加注册路由 [25行]
app.js — 注册 auth 路由 [1行]


如果遇到阻碍：
  调试命令：curl http://localhost:3000/api/register -v
  常见问题：检查 app.js 中间件顺序

Task 4: 添加注册验证

目标： 验证邮箱格式和密码强度
验证： 无效输入返回 400 和错误信息
文件：

utils/validate.js — 验证函数 [20行]
更新 routes/auth.js 在哈希前添加验证 [5行]


如果遇到阻碍：
  调试命令：curl -X POST http://localhost:3000/api/register -d '{"email":"bad","password":"x"}'
  常见问题：验证函数在 models 层还是 routes 层更合适？

Task 5: 编写集成测试

目标： 验证完整注册流程
验证： pytest tests/test_auth.py -v 全部通过
文件：

tests/test_auth.py — 注册测试 [30行]


如果遇到阻碍：
  调试命令：pytest tests/test_auth.py::test_register_success -v
  常见问题：测试数据库隔离 — 每个测试使用独立数据库

---

常见陷阱

任务太大
如果任务描述超过 3 行，它可能太大。拆分成多个任务。

缺少验证步骤
没有验证步骤的计划是无效的。实施者需要知道何时完成。

假设上下文
"更新控制器" — 更新什么？更新哪里？不明确。

跳过"明显"任务
"只需添加字段" — 这包括前端、测试、文档吗？每个相关文件都要列出。

忽略错误处理
计划应包含常见错误场景和调试命令。

计划模板

# [功能名称] 实现计划

> For Hermes: 使用 subagent-driven-development skill 逐任务实施此计划。

目标： [一句话]
架构： [方法]
技术栈： [技术]

---

Task 1: [任务名称]

目标： [完成什么]
验证： [验证命令]
文件：
  - [文件] — [做什么，N行]

如果遇到阻碍：
  调试命令：[命令]
  常见问题：[参考]

[继续 Task 2...]


计划审查清单

在标记计划完成前检查：
每个任务是否在 2-5 分钟内完成？
每个任务是否有验证步骤？
文件路径和代码是否完整？
是否包含错误处理和调试命令？
是否与 subagent-driven-development 正确集成？
技术栈是否与项目一致？

计划不完整？ 返回并完善，直到不需要猜测为止。