編寫計劃

當你擁有多步驟任務的規範或需求時使用。創建包含細粒度任務、確切文件路徑和完整代碼示例的綜合實施計劃。

技能元數據

來源	捆綁（默認安裝）
路徑	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：編寫任務

按順序創建任務：

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"

常見錯誤

模糊的任務

錯誤： “添加身份驗證” 正確： “創建具有 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

良好的計劃使實現一目瞭然。