name: plan description: “Plan mode: write an actionable markdown plan to .hermes/plans/, no execution. Bite-sized tasks, exact paths, complete code.” version: 2.0.0 author: Hermes Agent (writing-craft adapted from obra/superpowers) license: MIT platforms: [linux, macos, windows] metadata: hermes: tags: [planning, plan-mode, implementation, workflow, design, documentation] related_skills: [subagent-driven-development, test-driven-development, requesting-code-review]

计划模式

当用户希望获取计划而非直接执行代码时，可使用此技能。

核心行为

在本轮对话中，您仅负责制定计划。

• 不要编写代码。
• 除了计划相关的 Markdown 文件外，不得修改项目文件。
• 不要运行会修改状态的终端命令、执行提交、推送操作或进行任何外部操作。
• 如有需要，可使用只读命令/工具来查看仓库或其他相关内容。
• 您的输出应是一个保存在当前工作空间下的 .hermes/plans/ 目录中的 Markdown 计划文件。

输出要求

需编写一份具体且可操作的 Markdown 计划，其中应包含以下内容（如适用）：

• 目标
• 当前上下文/假设条件
• 建议的实现方案
• 逐步执行计划
• 可能会被修改的文件
• 测试/验证方法
• 风险、权衡因素及未解决的问题

如果任务与代码相关，还需注明具体的文件路径、可能的测试目标以及验证步骤。

保存位置

使用 write_file 函数将计划保存至以下路径：

• .hermes/plans/YYYY-MM-DD_HHMMSS-<slug>.md

该路径是相对于当前工作目录/后端工作空间而言的。Hermes 的文件工具具备后端感知功能，因此使用此相对路径可确保计划在本地、Docker、SSH、Modal 以及 Daytona 等各类后端环境中都与工作空间保持一致。

如果运行环境指定了特定目标路径，则直接使用该路径； 若未指定，则需在 .hermes/plans/ 目录下自行创建一个包含合理时间戳的文件名。

交互方式

• 若请求足够明确，可直接撰写计划。
• 若仅输入 /plan 而无明确指令，可从当前对话上下文中推断任务内容。
• 若信息确实不足，应提出简短的澄清问题而非自行猜测。
• 计划保存完成后，简要回复所制定的计划内容及保存路径。

如何编写优质的计划

本技能的后续内容将介绍如何撰写一份优秀的实施计划——即上述 Markdown 文件中所包含的内容。

概述

在编写实施计划时，应假设执行者对代码库完全不了解，且审美标准参差不齐。因此需详尽记录所有必要信息：需要修改的文件、完整代码、测试命令、需查阅的文档以及验证方法。同时要将任务拆分得尽可能小。遵循 DRY、YAGNI、TDD 原则，并频繁进行代码提交。

假设执行者虽是技术娴熟的开发者，但对相关工具集或问题领域几乎一无所知，且不太熟悉良好的测试设计方法。

核心原则： 一份优秀的计划能让实现过程一目了然。如果需要猜测，说明该计划还不够完善。

何时需要完整的实施计划

以下情况务必先制定完整计划：

• 实现多步骤功能
• 拆分复杂需求
• 通过子代理驱动开发的方式将任务分配给其他子代理

以下情况不可省略计划制定：

• 功能看似简单（但假设条件可能导致错误）
• 您打算亲自实现该功能（未来的自己需要指导）
• 独自工作时（文档记录至关重要）

任务颗粒度的要求

每个任务应控制在 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"
```

开发流程

第一步：理解需求

仔细阅读并掌握以下内容：

• 功能需求
• 设计文档或用户需求描述
• 验收标准
• 各项限制条件

第二步：探索代码库

利用 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步：编写任务

按顺序创建任务：

1. 基础设施搭建
2. 核心功能实现（每个功能均采用TDD测试驱动开发）
3. 边界情况处理
4. 系统集成
5. 代码清理与文档编写

第5步：补充完整细节

针对每项任务，需包含以下内容：

• 精确的文件路径（而非笼统地写“配置文件”，而应明确为 src/config/settings.py）
• 完整的代码示例（而非仅说明“添加验证逻辑”，而要提供实际代码）
• 带有预期输出结果的精确命令
• 能证明该任务已正常运行的验证步骤

第6步：审核计划

需检查以下要点：

• 任务顺序合理且逻辑连贯
• 每项任务的耗时控制在2-5分钟范围内
• 文件路径准确无误
• 代码示例完整，可直接复制粘贴使用
• 命令及预期输出均准确无误
• 无遗漏的背景信息
• 已遵循DRY、YAGNI及TDD开发原则

开发原则

DRY原则（不要重复自己）

错误做法： 在多个地方重复编写相同的验证代码
正确做法： 将验证逻辑提取为独立函数，然后在各处复用

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）

所有生成代码的任务都应遵循完整的测试驱动开发流程：

1. 编写失败的测试用例
2. 运行测试以确认确实失败
3. 编写最简的代码实现
4. 运行测试以确认测试通过

详情请参阅“test-driven-development”技能文档。

频繁提交代码

完成每个任务后都应立即提交代码：

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

常见错误

任务描述模糊

错误示例： “添加身份验证功能” 正确示例： “创建包含 email 和 password_hash 字段的 User 模型”

代码不完整

错误示例： “第一步：添加验证函数” 正确示例： “第一步：添加验证函数”，随后应给出完整的函数代码

缺少验证步骤

错误示例： “第三步：测试功能是否正常” 正确示例： “第三步：运行 pytest tests/test_auth.py -v，预期结果为：3 个测试通过”

未指定文件路径

错误示例： “创建模型文件” 正确示例： “创建文件：src/models/user.py”

执行交接流程

保存计划后，需明确说明执行方案：

“计划已完整保存。现在将采用子代理驱动开发模式进行执行——我会为每个任务分配一个全新的子代理，并依次进行两阶段审查（先检查是否符合规范，再评估代码质量）。是否继续？”

在执行过程中，请使用 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

完善的规划能让实施过程变得清晰明了。