plan

计划模式

当用户想要计划而非执行时，使用此技能。

核心行为

本轮仅制定计划。

• 不要编写代码。
• 除计划 Markdown 文件外，不要编辑项目文件。
• 不要运行会修改内容的终端命令，不要提交、推送或执行外部操作。
• 必要时，可以使用只读命令或工具检查代码库或其他上下文。
• 交付内容是一份保存在当前工作区 .hermes/plans/ 下的 Markdown 计划。

输出要求

编写具体且可执行的 Markdown 计划。

适用时，请包含：

• 目标
• 当前上下文／假设
• 拟议方案
• 分步计划
• 可能需要修改的文件
• 测试／验证
• 风险、权衡和待解决问题

如果任务与代码有关，请注明准确的文件路径、可能的测试目标以及验证步骤。

保存位置

使用 write_file 将计划保存到以下路径：

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

该路径相对于当前工作目录／后端工作区。Hermes 文件工具会适配后端，因此使用此相对路径可确保计划保存在本地、docker、ssh、modal 和 daytona 后端对应的工作区中。

如果运行时提供了特定目标路径，请使用该路径。 否则，请在 .hermes/plans/ 下自行创建一个带时间戳且名称合适的文件。

交互风格

• 如果请求足够明确，直接编写计划。
• 如果 /plan 没有附带明确指令，请根据当前对话上下文推断任务。
• 如果任务确实缺少关键信息，请简短提问，而不要猜测。
• 保存计划后，简要说明计划内容和保存路径。

---

编写优质计划

本技能其余部分介绍如何编写一份优质的实施计划——也就是上述文件的内容。

概述

编写全面的实施计划时，应假设实施者对代码库一无所知，且判断力存疑。说明所有必要信息：需要修改哪些文件、完整代码、测试命令、需要查阅的文档以及验证方法。将工作拆分成小任务。遵循 DRY、YAGNI 和 TDD。频繁提交。

假设实施者是一名熟练开发者，但对工具集和问题领域知之甚少。也不要假设他们熟悉良好的测试设计。

核心原则： 优质计划应让实施过程一目了然。如果有人还需要猜测，说明计划不够完整。

何时需要完整的实施计划

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

• 实施多步骤功能
• 分解复杂需求
• 通过基于子 Agent 的开发方式委派给子 Agent

以下情况也不要跳过：

• 功能看起来很简单（假设错误也会导致缺陷）
• 你计划亲自实施（未来的你也需要指导）
• 独自工作（文档很重要）

细化任务粒度

每项任务应为 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 步：编写任务

按顺序创建任务：

1. 搭建／基础设施
2. 核心功能（每项均采用 TDD）
3. 边界情况
4. 集成
5. 清理／文档

步骤 5：补充完整细节

对于每项任务，请包含：

• 确切的文件路径（不要写“配置文件”，而要写 src/config/settings.py）
• 完整的代码示例（不要只写“添加验证”，而要提供实际代码）
• 确切的命令及预期输出
• 验证步骤，以证明任务正常运行

步骤 6：审查计划

检查：

• 任务顺序合理、逻辑清晰
• 每项任务都很小巧（2–5 分钟）
• 文件路径准确
• 代码示例完整（可直接复制粘贴）
• 命令准确，并附有预期输出
• 上下文完整
• 遵循 DRY、YAGNI、TDD 原则

原则

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 循环：

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

详情请参阅 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 个测试通过”

缺少文件路径

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

执行交接

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

“计划已完成并保存。准备好使用 subagent-driven-development 执行了吗？我会为每项任务分派一个全新的子 Agent，并进行两阶段审查（先检查规格符合性，再检查代码质量）。要继续吗？”

执行时，请使用 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

好的计划能让实现过程一目了然。