{/* 本页面由 website/scripts/generate-skill-docs.py 从技能 SKILL.md 自动生成。请编辑源 SKILL.md 而非本页面。 */}
编写计划
编写实现计划：小任务、路径、代码。
技能元数据
| 来源 | 内置（默认安装） |
| 路径 | skills/software-development/writing-plans |
| 版本 | 1.1.0 |
| 作者 | Hermes Agent（改编自 obra/superpowers） |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | planning, design, implementation, workflow, documentation |
| 相关技能 | subagent-driven-development, test-driven-development, requesting-code-review |
参考：完整 SKILL.md
:::info 以下是此技能被触发时 Hermes 加载的完整技能定义。这是技能激活时代理所看到的指令。 :::
编写实现计划
概述
编写全面的实现计划，假设实现者对代码库零了解且品味存疑。记录他们需要的一切：要触及哪些文件、完整代码、测试命令、要检查的文档、如何验证。给他们可消化的任务。DRY。YAGNI。TDD。频繁提交。
假设实现者是一名熟练的开发者，但对工具集或问题领域几乎一无所知。假设他们不太擅长良好的测试设计。
核心原则： 好的计划让实现变得显而易见。如果某人需要猜测，说明计划不完整。
使用时机
在以下情况前始终使用：
- 实现多步骤功能
- 分解复杂需求
- 通过 subagent-driven-development 委托给子代理
不要跳过的情况：
- 功能看似简单（假设导致 bug）
- 你计划自己实现（未来的你需要指导）
- 独自工作（文档很重要）
小任务粒度
每个任务 = 2-5 分钟的专注工作。
每步是一个操作：
- “编写失败测试” — 步骤
- “运行测试确保它失败” — 步骤
- “实现让测试通过的最简代码” — 步骤
- “运行测试确保它们通过” — 步骤
- “提交” — 步骤
太大：
### 任务 1：构建认证系统
[跨越 5 个文件的 50 行代码]合适的粒度：
### 任务 1：创建带邮箱字段的 User 模型
[10 行，1 个文件]
### 任务 2：为 User 添加密码哈希字段
[8 行，1 个文件]
### 任务 3：创建密码哈希工具
[15 行，1 个文件]计划文档结构
头部（必需）
每个计划必须以以下内容开头：
# [功能名称] 实现计划
> **对于 Hermes：** 使用 subagent-driven-development 技能逐任务实现此计划。
**目标：** [一句话描述此构建的内容]
**架构：** [2-3 句话说明方法]
**技术栈：** [关键技术/库]
---任务结构
每个任务遵循此格式：
### 任务 N：[描述性名称]
**目标：** 此任务完成的内容（一句话）
**文件：**
- 创建：`exact/path/to/new_file.py`
- 修改：`exact/path/to/existing.py:45-67`（如果已知行号）
- 测试：`tests/path/to/test_file.py`
**步骤 1：编写失败测试**
```python
def test_specific_behavior():
result = function(input)
assert result == expected
```
**步骤 2：运行测试验证失败**
运行：`pytest tests/path/test.py::test_specific_behavior -v`
预期：FAIL — "function not defined"
**步骤 3：编写最简实现**
```python
def function(input):
return expected
```
**步骤 4：运行测试验证通过**
运行：`pytest tests/path/test.py::test_specific_behavior -v`
预期：PASS
**步骤 5：提交**
```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```编写过程
步骤 1：理解需求
阅读和理解：
- 功能需求
- 设计文档或用户描述
- 验收标准
- 约束条件
步骤 2：探索代码库
使用 Hermes 工具了解项目：
search_files("*.py", target="files", path="src/")
search_files("similar_pattern", path="src/", file_glob="*.py")
search_files("*.py", target="files", path="tests/")
read_file("src/app.py")步骤 3：设计方法
决定：
- 架构模式
- 文件组织
- 所需依赖
- 测试策略
步骤 4：编写任务
按顺序创建任务：
- 设置/基础设施
- 核心功能（每个使用 TDD）
- 边界情况
- 集成
- 清理/文档
步骤 5：添加完整细节
为每个任务包括：
- 确切文件路径（不是”配置文件”而是
src/config/settings.py） - 完整代码示例（不是”添加验证”而是实际代码）
- 确切命令及预期输出
- 证明任务有效的验证步骤
步骤 6：审查计划
检查：
- 任务顺序合理且逻辑连贯
- 每个任务粒度合适（2-5 分钟）
- 文件路径准确
- 代码示例完整（可直接复制粘贴）
- 命令准确且含预期输出
- 没有遗漏上下文
- 应用了 DRY、YAGNI、TDD 原则
步骤 7：保存计划
mkdir -p docs/plans
git add docs/plans/
git commit -m "docs: add implementation plan for [feature]"原则
DRY（不要重复自己）
坏： 在 3 处复制粘贴验证 好： 提取验证函数，各处使用
YAGNI（你不会需要它）
坏： 为未来需求添加”灵活性” 好： 仅实现现在需要的
TDD（测试驱动开发）
每个生成代码的任务应包括完整的 TDD 循环：
- 编写失败测试
- 运行验证失败
- 编写最简代码
- 运行验证通过
频繁提交
每个任务后提交：
git add [files]
git commit -m "type: description"常见错误
模糊的任务
坏： “添加认证” 好： “创建带邮箱和密码哈希字段的 User 模型”
不完整的代码
坏： “步骤 1：添加验证函数” 好： “步骤 1：添加验证函数”后跟完整函数代码
缺少验证
坏： “步骤 3：测试它是否工作”
好： “步骤 3：运行 pytest tests/test_auth.py -v，预期：3 通过”
缺少文件路径
坏： “创建模型文件”
好： “创建：src/models/user.py”
执行交接
保存计划后，提供执行方式：
“计划已保存并完成。准备好使用 subagent-driven-development 执行——我将为每个任务分派一个全新的子代理，进行两阶段审查（规格合规性然后代码质量）。是否继续？”
执行时，使用 subagent-driven-development 技能：
- 每个任务使用全新
delegate_task，附完整上下文 - 每个任务后进行规格合规性审查
- 规格通过后进行代码质量审查
- 仅当两个审查都批准时才继续
记住
小任务（每个 2-5 分钟）
确切文件路径
完整代码（可复制粘贴）
确切命令及预期输出
验证步骤
DRY、YAGNI、TDD
频繁提交
好的计划让实现变得显而易见。