mcpField
W
writing-plans

writing-plans

github.com/nousresearch开发259.2k87 次安装1 天前更新
代码仓库

关于 writing-plans

writing-plans 是 Hermes 技能，可将功能需求整理为按顺序执行的实现计划。它面向开发者，强调细分任务、准确文件路径、完整示例、测试验证和频繁提交。

主要功能

  1. 01将工作拆分为 2–5 分钟任务
  2. 02注明文件路径并提供代码示例
  3. 03列出准确的测试与验证命令
  4. 04遵循 DRY、YAGNI 和 TDD
  5. 05建议每项任务后提交

适用场景

  1. 01编码前规划多步骤功能
  2. 02为委派复杂工作做准备
  3. 03记录实施者所需的测试与验证步骤

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/nousresearch/hermes-agent --skill writing-plans

安装后在 Claude Code 中输入/writing-plans确认已加载。

详细介绍

编写实施计划

概述

编写全面的实施计划时，假设实施者对代码库一无所知，判断力也不太可靠。记录他们需要了解的一切：要修改哪些文件、完整代码、测试命令、需要查看的文档以及验证方法。将任务拆分成易于完成的小步骤。遵循 DRY、YAGNI、TDD。频繁提交。

假设实施者是一名熟练的开发者，但对工具集和问题领域几乎一无所知。假设他们不太了解良好的测试设计。

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

何时使用

始终在以下情况之前使用：

  • 实施多步骤功能
  • 拆解复杂需求
  • 通过 subagent-driven-development 将任务委派给子 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 原则
步骤 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 循环：

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

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

频繁提交

每完成一个任务就提交：

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

常见错误

任务描述含糊

不好的做法： “添加身份验证” 好的做法： “创建 User 模型，包含 email 和 password_hash 字段”

代码不完整

不好的做法： “步骤 1：添加验证函数” 好的做法： “步骤 1：添加验证函数”，并附上完整的函数代码

缺少验证步骤

不好的做法： “步骤 3：测试它是否正常运行” 好的做法： “步骤 3：运行 pytest tests/test_auth.py -v，预期结果：3 passed”

缺少文件路径

不好的做法： “创建模型文件” 好的做法： “创建：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

好的计划应让实施过程一目了然。

评论

支持 Markdown