编写计划

当你拥有多步骤任务的规范或需求时使用。创建包含细粒度任务、确切文件路径和完整代码示例的综合实施计划。

技能元数据


来源	捆绑（默认安装）
路径	`skills/software-development/writing-plans`
版本	`1.1.0`
作者	Hermes Agent（改编自 obra/superpowers）
许可证	MIT
标签	`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 分钟的专注工作。

每个步骤是一个动作：

“编写失败的测试” — 步骤
“运行以确保其失败” — 步骤
“实现使测试通过的最小代码” — 步骤
“运行测试并确保它们通过” — 步骤
“提交” — 步骤

太大：

### Task 1: Build authentication system
[50 lines of code across 5 files]

合适的大小：

### Task 1: Create User model with email field
[10 lines, 1 file]

### Task 2: Add password hash field to User
[8 lines, 1 file]

### Task 3: Create password hashing utility
[15 lines, 1 file]

计划文档结构

标题（必需）

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

# [Feature Name] Implementation Plan

> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.

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

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

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

---

任务结构

每个任务遵循以下格式：

### Task N: [Descriptive Name]

**Objective:** What this task accomplishes (one sentence)

**Files:**
- Create: `exact/path/to/new_file.py`
- Modify: `exact/path/to/existing.py:45-67` (line numbers if known)
- Test: `tests/path/to/test_file.py`

**Step 1: Write failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

**Step 2: Run test to verify failure**

Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: FAIL — "function not defined"

**Step 3: Write minimal implementation**

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

**Step 4: Run test to verify pass**

Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: PASS

**Step 5: Commit**

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

编写流程

步骤 1：理解需求

阅读并理解：

功能需求
设计文档或用户描述
验收标准
约束条件

步骤 2：探索代码库

使用 Hermes 工具了解项目：

# Understand project structure
search_files("*.py", target="files", path="src/")

# Look at similar features
search_files("similar_pattern", path="src/", file_glob="*.py")

# Check existing tests
search_files("*.py", target="files", path="tests/")

# Read key files
read_file("src/app.py")

步骤 3：设计方法

决定：

架构模式
文件组织
所需依赖
测试策略

步骤 4：编写任务

按顺序创建任务：

设置/基础设施
核心功能（每个都采用 TDD）
边缘情况
集成
清理/文档

步骤 5：添加完整细节

对于每个任务，包括：

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

步骤 6：审查计划

检查：

任务是顺序且符合逻辑的
每个任务都是细粒度的（2-5 分钟）
文件路径是确切的
代码示例是完整的（可复制粘贴）
命令是确切的并包含预期输出
没有缺失上下文
应用了 DRY、YAGNI、TDD 原则

步骤 7：保存计划

mkdir -p docs/plans
# Save plan to docs/plans/YYYY-MM-DD-feature-name.md
git add docs/plans/
git commit -m "docs: add implementation plan for [feature]"

原则

DRY（不要重复自己）

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

YAGNI（你不会需要它）

错误： 为未来需求添加“灵活性” 正确： 仅实施当前所需的内容

# Bad — YAGNI violation
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email
        self.preferences = {}  # Not needed yet!
        self.metadata = {}     # Not needed yet!

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

TDD（测试驱动开发）

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

编写失败的测试
运行以验证失败
编写最小代码
运行以验证通过

详见 test-driven-development 技能。

频繁提交

在每个任务后提交：

git add [files]
git commit -m "type: description"

常见错误

模糊的任务

错误： “添加身份验证” 正确： “创建具有 email 和 password_hash 字段的 User 模型”

不完整的代码

不佳： “步骤 1：添加验证函数” 良好： “步骤 1：添加验证函数”，后附完整的函数代码

缺少验证

不佳： “步骤 3：测试其是否有效” 良好： “步骤 3：运行 pytest tests/test_auth.py -v，预期结果：3 passed”

缺少文件路径

不佳： “创建模型文件” 良好： “创建：src/models/user.py”

执行交接

保存计划后，提供执行方案：

“计划已完成并保存。准备使用 subagent-driven-development 执行——我将为每个任务派遣一个全新的子代理，并进行两阶段审查（先审查规范符合性，再审查代码质量）。是否继续？”

执行时，使用 subagent-driven-development 技能：

为每个任务使用完整上下文调用新的 delegate_task
每个任务完成后进行规范符合性审查
规范审查通过后进行代码质量审查
仅当两项审查均批准时才继续

切记

Bite-sized tasks (2-5 min each)
Exact file paths
Complete code (copy-pasteable)
Exact commands with expected output
Verification steps
DRY, YAGNI, TDD
Frequent commits

良好的计划使实现一目了然。

技能元数据​

参考：完整 SKILL.md​

编写实施计划

概述​

何时使用​

细粒度任务颗粒度​

计划文档结构​

标题（必需）​

任务结构​

编写流程​

步骤 1：理解需求​

步骤 2：探索代码库​

步骤 3：设计方法​

步骤 4：编写任务​

步骤 5：添加完整细节​

步骤 6：审查计划​

步骤 7：保存计划​

原则​

DRY（不要重复自己）​

YAGNI（你不会需要它）​

TDD（测试驱动开发）​

频繁提交​

常见错误​

模糊的任务​

不完整的代码​

缺少验证​

缺少文件路径​

执行交接​

切记​