编写计划

编写实施计划：细分任务、路径、代码。

技能元数据

来源	捆绑（默认安装）
路径	skills/software-development/writing-plans
版本	1.1.0
作者	Hermes 智能体（改编自 obra/superpowers）
许可证	MIT
平台	linux, macos, windows
标签	planning, design, implementation, workflow, documentation
相关技能	subagent-driven-development, test-driven-development, requesting-code-review

参考：完整 SKILL.md

信息

以下是当此技能被触发时，Hermes 加载的完整技能定义。这是技能激活时智能体看到的指令。

编写实施计划

概述

假设实施者对代码库零了解且品味存疑，编写全面的实施计划。记录他们需要知道的一切：需要修改哪些文件、完整的代码、测试命令、需要检查的文档、如何验证。为他们提供细分的任务。DRY。YAGNI。TDD。频繁提交。

假设实施者是熟练的开发者，但对工具集或问题领域知之甚少。假设他们不太了解良好的测试设计。

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

何时使用

务必在以下情况前使用：

• 实施多步骤功能
• 分解复杂需求
• 通过 subagent-driven-development 委托给子智能体

在以下情况不要跳过：

• 功能看似简单（假设会导致错误）
• 你打算自己实施（未来的你需要指导）
• 独自工作（文档很重要）

细分任务粒度

每个任务 = 2-5分钟的专注工作。

每一步都是一个操作：

• "编写失败的测试" — 一步
• "运行它以确保失败" — 一步
• "编写使测试通过的最小代码" — 一步
• "运行测试并确保通过" — 一步
• "提交" — 一步

过于笼统：

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

适当粒度：

### 任务 1：创建带邮箱字段的用户模型
[10行，1个文件]

### 任务 2：为用户模型添加密码哈希字段
[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`
预期结果：失败 — "function not defined"

**步骤 3：编写最小实现**

```python
def function(input):
    return expected
```

**步骤 4：运行测试以验证通过**

运行：`pytest tests/path/test.py::test_specific_behavior -v`
预期结果：通过

**步骤 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：编写任务

按顺序创建任务：

1. 设置/基础设施
2. 核心功能（每个都用 TDD）
3. 边缘情况
4. 集成
5. 清理/文档

步骤 5：添加完整细节

对于每个任务，包括：

• 准确的文件路径（不是"配置文件"，而是 src/config/settings.py）
• 完整的代码示例（不是"添加验证"，而是实际代码）
• 准确的命令 及预期输出
• 验证步骤 以证明任务有效

步骤 6：审查计划

检查：

• 任务顺序合理且逻辑清晰
• 每个任务细分（2-5分钟）
• 文件路径准确
• 代码示例完整（可直接复制粘贴）
• 命令准确并有预期输出
• 没有缺失上下文
• 应用了 DRY、YAGNI、TDD 原则

步骤 7：保存计划

mkdir -p docs/plans
# 将计划保存到 docs/plans/YYYY-MM-DD-feature-name.md
git add docs/plans/
git commit -m "docs: add implementation plan for [feature]"

原则

DRY（不要重复自己）

错误： 在3个地方复制粘贴验证逻辑 正确： 提取验证函数，到处使用

YAGNI（你不会需要它）

错误： 为未来的需求添加"灵活性" 正确： 只实现当前需要的功能

# 错误 — 违反 YAGNI
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email
        self.preferences = {}  # 还不需要！
        self.metadata = {}     # 还不需要！

# 正确 — YAGNI
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email

TDD（测试驱动开发）

每个产生代码的任务都应包含完整的 TDD 循环：

1. 编写失败的测试
2. 运行以验证失败
3. 编写最小代码
4. 运行以验证通过

详情请参阅 test-driven-development 技能。

频繁提交

每个任务后提交：

git add [文件]
git commit -m "类型: 描述"

常见错误

模糊的任务

错误： "添加认证" 正确： "创建带 email 和 password_hash 字段的用户模型"

不完整的代码

错误： "步骤 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
频繁提交

好的计划让实施显而易见。