writing-plans

编写计划

概述

编写全面的实施计划时，假设工程师对我们的代码库一无所知，而且品味可能不怎么样。记录他们需要了解的一切：每项任务需要修改哪些文件、代码、测试、需要查阅的文档，以及如何测试。将完整计划拆分成易于完成的小任务。DRY。YAGNI。TDD。频繁提交。

假设他们是熟练的开发者，但几乎不了解我们的工具集或问题领域。假设他们还不太懂如何设计好的测试。

开始时宣布：“我正在使用 writing-plans 技能来创建实施计划。”

**上下文：**应在专用工作树中运行（由 brainstorming 技能创建）。

将计划保存到：docs/plans/YYYY-MM-DD-<feature-name>.md

易于完成的小任务粒度

每个步骤只做一件事（2-5 分钟）：

• “编写失败的测试”——一个步骤
• “运行测试，确认它失败”——一个步骤
• “编写最少的代码，让测试通过”——一个步骤
• “运行测试并确认通过”——一个步骤
• “提交”——一个步骤

计划文档标题

每份计划都必须以此标题开头：

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use the executing-plans 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: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

**Step 1: Write the failing test**

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

**Step 2: Run test to verify it fails**

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

**Step 3: Write minimal implementation**

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

**Step 4: Run test to verify it passes**

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

**Step 5: Commit**

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

请牢记

• 始终使用准确的文件路径
• 在计划中提供完整代码（不要只写“添加验证”）
• 提供准确的命令及预期输出
• 使用 @ 语法引用相关技能
• DRY、YAGNI、TDD、频繁提交

常见陷阱

1. 计划过于抽象（没有具体路径或命令）

**表现：**计划读起来很流畅，却缺少可执行的细节。像“添加验证”或“更新 API 处理程序”这样的步骤，会让工程师猜测应该修改哪个文件、哪个函数，或代码结构是什么。

为什么会失败：

• 工程师浪费时间寻找合适的文件或推断代码结构
• 不同工程师对抽象步骤的理解不同，导致返工
• 在有人开始实施之前，无法判断计划是否完整

如何改进：

• 始终提供准确的文件路径：src/handlers/user.ts，而不是“更新处理程序”
• 始终提供准确的命令：pytest tests/handlers/test_user.py -v，而不是“运行测试”
• 使用代码围栏提供完整代码，而不是伪代码
• 修改现有文件时提供行号：修改：src/handlers/user.ts:45-62

示例（错误与正确）：

❌ BAD: "Update the validation logic to handle email addresses"
✅ GOOD: "Modify: src/validators/email.py:12-18. Replace the regex pattern with: re.compile(r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$')"

---

2. 任务粒度不当（步骤太大或太小）

**表现：**步骤要么是含糊的庞大任务（“构建身份验证系统”），要么细碎到令人难以推进（“导入模块”“定义函数签名”“编写函数体”）。

为什么会失败：

• 步骤太大：工程师缺少指引，容易实现错误
• 步骤太小：频繁切换上下文；提交变得琐碎；难以追踪意图
• 无论哪种情况，都难以衡量和验证进展

如何改进：

• 以 2-5 分钟为目标：足够小，可以独立验证和提交；同时又足够有意义
• 将相关的微小步骤归到一个任务标题下，再用编号步骤拆分
• 每个步骤都应产出可提交到 Git 的更改
• 用这个标准检验：“我能否单独理解并验证这次提交？”

示例（错误与正确）：

❌ BAD:
  Step 1: Import json
  Step 2: Define function
  Step 3: Write body
  Step 4: Run test

✅ GOOD:
  Step 1: Write failing test for json parsing
  Step 2: Implement minimal function that passes test
  Step 3: Run test and verify PASS
  Step 4: Commit

---

3. 缺少验证步骤（无法确认任务是否成功）

**症状：**计划描述了要做什么，却从未说明如何验证是否正确完成。工程师完成某个步骤后，不确定它是否真的奏效。

失败原因：

• 静默失败：代码运行了，却产生错误结果，工程师没有发现
• 浪费调试时间：工程师不得不自行想出验证方法
• 计划无法可靠复用，因为成功标准含糊不清

修复方法：

• 每个会改变行为的步骤都必须包含验证命令
• 验证命令必须包含预期输出或成功标志
• 对于测试：Expected: PASS。对于命令：Expected output: [actual output]
• 包含负面用例：“运行：pytest tests/... -v。预期：应因 'ValidationError' 而失败”

示例（错误 vs 正确）：

❌ BAD:
  Step 3: Implement the validation function

✅ GOOD:
  Step 3: Implement the validation function
  
  ```python
  def validate_email(email):
      pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
      return bool(re.match(pattern, email))
  ```

  Step 4: Run test to verify it passes
  
  Run: `pytest tests/validators/test_email.py::test_valid_email -v`
  Expected: `PASSED test_valid_email`

---

4. 违反 DRY 原则（在多个任务中重复指令）

**症状：**计划在多个任务中重复相同的指令（“运行完整测试套件”“导入 X 模块”“遵循命名约定”）。不同任务的步骤中出现相同的模板内容。

失败原因：

• 可维护性差：更新模式时需要修改多个地方
• 增加认知负担：工程师必须理解不同任务中的意图其实相同
• 容易出错：相同指令在不同位置可能略有差异，造成混淆

修复方法：

• 在计划顶部的“设置”或“先决条件”部分记录重复模式
• 在类似步骤中使用一致的命令语法和结构
• 链接到共享指令：“按照上方‘测试’部分的说明，运行：pytest ...”
• 如果某个模式确实重复出现，请思考：能否合并这些任务，或者是否有共享工具可以消除重复？

示例（错误 vs 正确）：

❌ BAD:
  Task 1: Write test, run `pytest tests/handlers/test_a.py -v`, commit
  Task 2: Write test, run `pytest tests/handlers/test_b.py -v`, commit
  Task 3: Write test, run `pytest tests/handlers/test_c.py -v`, commit

✅ GOOD:
  # Testing Pattern
  After each implementation, verify with: `pytest tests/handlers/test_<name>.py -v`
  Expected: All tests PASS
  
  Task 1: [test_a implementation]
  Task 2: [test_b implementation]
  Task 3: [test_c implementation]

---

5. 假设上下文 Agent 知道相关信息（框架细节、约定）

**症状：**计划提到“标准模式”“按我们一贯的做法”或“使用公司的约定”，却没有解释这些具体指什么。假设工程师了解框架快捷方式、命名约定或项目结构。

失败原因：

• 新加入的工程师或外部贡献者无从了解“这种模式”指什么
• 不同项目有不同约定，Agent 可能会混淆
• 工程师把时间花在反向摸索约定上，而不是遵循计划

修复方法：

• 在计划开头的“上下文”或“设置”部分明确说明约定
• 如果约定与框架有关，请指出具体约定：“Django 模型命名：class MyModel(models.Model)”
• 提供示例：“所有 API 处理程序都遵循以下模式：[示例文件 + 代码片段]”
• 如果某种模式是此代码库特有的，请简要说明，而不要假设他人了解

示例（错误 vs 正确）：

❌ BAD:
  Step 1: Create a handler using the standard pattern
  Step 2: Follow our naming convention for tests

✅ GOOD:
  Context: This project uses Flask. All handlers live in src/handlers/ and follow the pattern:
  ```python
  @app.route('/endpoint', methods=['POST'])
  def handle_endpoint():
      # Handler logic
      return jsonify({...})
  ```
  
  Step 1: Create handler in src/handlers/my_handler.py following the pattern above
  Step 2: Create test in tests/handlers/test_my_handler.py. Naming: test_<function_name>_<scenario>

---

执行交接

保存计划后，提供执行方式选项：

“计划已完成并保存到 docs/plans/<filename>.md。有两种执行方式：

1. 子 Agent 驱动（本次会话） - 我为每个任务派出一个新的子 Agent，并在任务之间审查，快速迭代

2. 并行会话（单独会话） - 使用 executing-plans 开启新会话，分批执行并设置检查点

你想采用哪种方式？”

如果选择子 Agent 驱动：

• 为每个任务启动一个子 Agent，在任务之间审查结果，快速迭代
• 留在本次会话中进行协调

如果选择并行会话：

• 引导他们在 git worktree 中开启新会话
• **必需的子技能：**新会话使用 executing-plans 技能