---
name: writing-plans
description: 当有规格或需求的多步骤任务时使用，在接触代码之前
---

# 编写实现计划

## 概述

编写全面的实现计划，假设执行者对代码库零上下文且判断力有限。记录他们需要知道的一切：每个任务要接触哪些文件、代码、测试、可能需要检查的文档、如何测试。将整个计划作为小任务交付。DRY。YAGNI。TDD。频繁提交。

假设执行者是技术熟练的开发者，但对我们的工具或问题领域几乎一无所知。假设他们不太擅长测试设计。

**开始时宣布：** "我正在使用 writing-plans skill 创建实现计划。"

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

## 小粒度任务

**每个步骤是一个动作（2-5 分钟）：**
- "写失败的测试" - 一步
- "运行它确保它失败" - 一步
- "实现最小代码使测试通过" - 一步
- "运行测试确保它们通过" - 一步
- "提交" - 一步

## 计划文档头部

**每个计划必须以此头部开始：**

```markdown
# [功能名称] 实现计划

> **执行指令**：使用 `/vibe-execute` 命令启动自动执行流程。
> 执行过程中会自动创建 Task 系统，派发子代理，执行校验。

**目标**：[一句话描述要构建什么]

**架构**：[2-3 句话描述方案]

**技术栈**：[关键技术/库]

---
```

## 任务结构

```markdown
### Task N: [组件名称]

**文件：**
- 创建: `exact/path/to/file.py`
- 修改: `exact/path/to/existing.py:123-145`
- 测试: `tests/exact/path/to/test.py`

**Step 1: 写失败测试**

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

**Step 2: 运行测试验证失败**

运行: `pytest tests/path/test.py::test_name -v`
预期: FAIL，提示 "function not defined"

**Step 3: 写最小实现**

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

**Step 4: 运行测试验证通过**

运行: `pytest tests/path/test.py::test_name -v`
预期: PASS

**Step 5: 提交**

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

---
```

## 关键原则

- 始终使用精确的文件路径
- 计划中包含完整代码（不是"添加验证逻辑"）
- 精确的命令和预期输出
- 引用相关 skills
- DRY, YAGNI, TDD, 频繁提交

## 执行交接

保存计划后输出：

```
计划已完成并保存到 docs/plans/YYYY-MM-DD-<feature>-plan.md

下一步：执行 /vibe-execute 开始子代理驱动执行。
```

## 完成标准

```markdown
## 完成标准

1. 所有 Task 验收标准满足
2. 所有测试通过
3. 对照用户需求确认功能完整

## 校验

执行完成后，校验 Task 会自动：
1. 对比 design.md 和所有 Task metadata
2. 检测降级实现
3. 运行完整测试套件
4. 生成 Task 快照
```

## 常见错误

| 错误 | 正确做法 |
|------|----------|
| 模糊的文件路径 | 使用精确路径 `src/auth/login.py` |
| "添加验证逻辑" | 提供完整的验证代码 |
| 任务太大（>5 分钟） | 拆分成更小的步骤 |
| 跳过测试验证步骤 | 每个 Step 都要验证 |

## 危险信号 - 停下来

- 任务描述超过一屏
- 需要"理解"才能完成的任务
- 没有明确的验证命令
- 任务之间有隐含依赖

**这些都意味着：任务需要进一步拆分。**