task-planning

任务规划

概述

为对代码库毫无了解、设计判断能力不可靠的工程师，编写详尽的实现计划。把所有事情都写清楚：每项任务要修改哪些文件、确切代码、测试流程、相关文档，以及如何验证每个步骤。将计划拆分为细致且自成一体的任务。遵循 DRY、YAGNI、TDD。频繁提交。

假设工程师具备技术能力，但对项目的工具链或问题领域几乎一无所知。假设他们的测试设计能力较弱。

开始时宣布： “我将运用任务规划技能来制定实现计划。”

上下文： 这项工作应在专用工作树中进行（在意图发现阶段创建）。

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

首要原则

NO IMPLEMENTATION WITHOUT A PLAN FIRST

没有例外。没有变通办法。没有捷径。

适用场景

必须使用：

• 多步骤功能（涉及多个文件或行为）
• 涉及多个组件的 Bug 修复
• 跨模块边界的重构
• 任何需要跨文件协调测试、代码和提交的任务
• 意图发现环节产出了规格说明或设计方案时

无需使用：

• 范围明确的单行修复（拼写错误、配置值）
• 为现有代码添加单个测试
• 仅修改文档
• 在单个文件中重命名变量

是否想过“这项任务太简单，不需要计划”？只要涉及多个文件，就要编写计划。

开始流程

编写计划前，确认以下各项全部满足：

1. 设计已获批准——意图发现环节或人工协作者已确认方案
2. 范围已界定——你能列出所有将要变更的组件
3. 需求明确具体——你知道“完成”的标准是什么（验收标准，而非主观感受）
4. 技术栈已确定——你知道所涉及的语言、框架和库
5. 测试策略已明确——你知道如何验证每个部分
6. 工作树已启用——你正在隔离分支中工作，而非 main

有任何一项不明确？ 停下。返回意图发现环节，或咨询人工协作者。不要编写有遗漏的计划——遗漏会变成缺陷。

认知陷阱

自我安慰	实际情况
“太简单，不用写计划”	简单任务也藏着复杂问题。写计划只需 5 分钟，调试却要花上数小时。
“边做边想就行”	这叫临时拼凑。你会漏掉边缘情况，也会跳过验证步骤。
“规格说明就是计划”	规格说明描述做什么，计划则按步骤描述怎么做，并列出文件路径和命令。
“我已经知道该怎么做”	很好，把它写下来。要是确实一目了然，2 分钟就能写好计划。
“计划会拖慢我”	返工才会拖慢你。计划能避免返工，每次都能节省时间。
“做完之后再补计划”	实现完成后写的计划只是文档，不是真正的计划。它无法防止已经发生的错误。

防护准则

绝不：

• 编写“实现功能”或“添加验证”这类含糊步骤——要指定确切代码
• 在计划步骤中省略测试命令或预期输出
• 遗漏文件路径——每个步骤都必须列出确切路径
• 在计划保存并经过审查前开始实现

始终：

• 包含完整代码片段，而非仅描述代码
• 为每个验证步骤指定确切的 shell 命令及预期输出
• 列出所有将要创建、修改或删除的文件
• 每项任务最后都要包含提交步骤，并写明确切的提交消息

任务粒度

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

• “编写失败的测试”——一步
• “运行测试，确认其失败”——一步
• “编写能通过测试的最简代码”——一步
• “运行测试，确认其通过”——一步
• “提交”——一步

计划文档标题

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

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use godmode:task-runner to implement this plan task-by-task.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about the 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 failure**

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"
```

提醒事项

• 每个步骤都提供准确的文件路径
• 计划中包含完整代码（而非“添加验证”）
• 提供准确的命令及预期输出
• 按名称引用相关技能（例如，godmode:test-first）
• 遵循 DRY、YAGNI、TDD，并频繁提交

执行交接

保存计划后，向用户提供以下选项：

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

1. 委派执行（本次会话） - 我会为每项任务派出一个新的子 Agent，并在任务之间进行审查，以便快速迭代

2. 单独会话 - 使用 task-runner 开启新会话，分批执行并设置检查点

你想选择哪种方式？”

如果选择委派执行：

• 必需子技能： 使用 godmode:delegated-execution
• 留在本次会话中
• 每项任务都使用新的子 Agent，并进行代码审查

如果选择单独会话：

• 引导用户在工作树中开启新会话
• 必需子技能： 新会话使用 godmode:task-runner

关联

必需的工作流技能：

• godmode:intent-discovery - 产出供此技能使用的规格说明/设计
• godmode:workspace-isolation - 必需： 规划前设置隔离工作区
• godmode:task-runner - 执行此技能生成的计划
• godmode:delegated-execution - 使用同一会话中的子 Agent 执行任务的替代方式
• godmode:test-first - 计划中的每项任务都遵循 TDD 循环
• godmode:merge-protocol - 计划执行后完成开发

计划构建工作流

digraph plan_construction {
    rankdir=TB;
    node [shape=box, style=filled, fontname="Helvetica"];

    start [label="Task received", shape=ellipse, fillcolor="#e0e0e0"];
    check_scope [label="Multi-step?\nMultiple files?", shape=diamond, fillcolor="#ffffcc"];
    no_plan [label="No plan needed\nJust do it", fillcolor="#ccffcc"];
    gate [label="Entry Protocol\nAll 6 items verified?", shape=diamond, fillcolor="#ffffcc"];
    go_back [label="Return to\nintent-discovery\nor ask human", fillcolor="#ffcccc"];
    write_header [label="Write plan header\nGoal / Architecture / Stack", fillcolor="#cce5ff"];
    write_tasks [label="Write granular tasks\nFiles / Test / Implement / Verify / Commit", fillcolor="#cce5ff"];
    review [label="Review plan\nAll paths exact?\nAll code complete?", shape=diamond, fillcolor="#ffffcc"];
    fix_plan [label="Fill gaps\nin plan", fillcolor="#ffcccc"];
    save [label="Save to\ndocs/plans/", fillcolor="#ccffcc"];
    handoff [label="Offer execution\nchoice to human", fillcolor="#ccffcc"];

    start -> check_scope;
    check_scope -> no_plan [label="no"];
    check_scope -> gate [label="yes"];
    gate -> go_back [label="gaps"];
    gate -> write_header [label="all verified"];
    go_back -> gate [label="resolved"];
    write_header -> write_tasks;
    write_tasks -> review;
    review -> fix_plan [label="gaps found"];
    fix_plan -> review;
    review -> save [label="complete"];
    save -> handoff;
}