writing-plans

name	writing-plans
description	Use when you have a spec or requirements for a multi-step task, before touching code

编写计划

概述

编写全面的实施计划，假设工程师对我们的代码库零了解，且判断力存疑。记录他们需要知道的一切：每个任务需要修改哪些文件、代码、测试、可能需要查看的文档，以及如何测试。将整个计划分解为小任务。DRY（不要重复自己）。YAGNI（你不会需要它）。TDD（测试驱动开发）。频繁提交。

假设他们是有经验的开发者，但几乎不了解我们的工具集或问题领域。假设他们不太了解良好的测试设计。

开始时声明："我正在使用 writing-plans 技能来创建实施计划。"

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

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

• （用户对计划位置的偏好会覆盖此默认值）

范围检查

如果规范涵盖多个独立子系统，它应该在头脑风暴期间被分解为子项目规范。如果没有，建议将其分解为单独的计划——每个子系统一个。每个计划应该独立产出可工作、可测试的软件。

文件结构

在定义任务之前，规划出将创建或修改哪些文件，以及每个文件负责什么。这是确定分解决策的地方。

• 设计具有清晰边界和定义良好接口的单元。每个文件应该有一个明确的职责。
• 你最能理解的是可以一次性保持在上下文中的代码，当文件专注时，你的编辑更可靠。优先选择小型、专注的文件，而不是做太多事情的大型文件。
• 一起变化的文件应该放在一起。按职责拆分，而不是按技术层。
• 在现有代码库中，遵循已建立的模式。如果代码库使用大型文件，不要单方面重构——但如果你正在修改的文件已经变得难以管理，在计划中包含拆分是合理的。

此结构为任务分解提供依据。每个任务应该产出独立有意义的变更。

小任务粒度

每个步骤是一个动作（2-5分钟）：

• "编写失败的测试" - 步骤
• "运行它以确保它失败" - 步骤
• "实现使测试通过的最小代码" - 步骤
• "运行测试并确保它们通过" - 步骤
• "提交" - 步骤

计划文档头部

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

# [功能名称] 实施计划

> **对于代理工作者：**必需的子技能：使用 zjkycode:subagent-driven-development（推荐）或 zjkycode:executing-plans 来逐任务实施此计划。步骤使用复选框（`- [ ]`）语法进行跟踪。

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

**架构：**[2-3句话关于方法]

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

---

任务结构

### 任务 N：[组件名称]

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

- [ ] **步骤 1：编写失败的测试**

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

- [ ] **步骤 2：运行测试以验证它失败**

运行：`pytest tests/path/test.py::test_name -v`
预期：失败，显示 "function not defined"

- [ ] **步骤 3：编写最小实现**

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

- [ ] **步骤 4：运行测试以验证它通过**

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

- [ ] **步骤 5：提交**

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

不要使用占位符

每个步骤必须包含工程师需要的实际内容。这些是计划失败——永远不要写它们：

• "TBD"、"TODO"、"稍后实现"、"填写详情"
• "添加适当的错误处理"/"添加验证"/"处理边缘情况"
• "为上述编写测试"（没有实际测试代码）
• "类似于任务 N"（重复代码——工程师可能不按顺序阅读任务）
• 描述做什么但不展示如何做的步骤（代码步骤需要代码块）
• 引用任何任务中未定义的类型、函数或方法

记住

• 始终使用确切的文件路径
• 每个步骤中包含完整代码——如果步骤更改代码，展示代码
• 确切的命令和预期输出
• DRY、YAGNI、TDD、频繁提交

自我审查

编写完整计划后，用全新的眼光审视规范，对照规范检查计划。这是你自己运行的检查清单——不是子代理调度。

**1. 规范覆盖：**浏览规范中的每个部分/需求。你能指出实现它的任务吗？列出任何缺口。

**2. 占位符扫描：**在计划中搜索危险信号——上述"不要使用占位符"部分中的任何模式。修复它们。

**3. 类型一致性：**你在后续任务中使用的类型、方法签名和属性名称是否与早期任务中定义的匹配？任务 3 中调用的函数 clearLayers() 但任务 7 中是 clearFullLayers() 是一个 bug。

如果发现问题，内联修复。不需要重新审查——只需修复并继续。如果发现没有任务的规范需求，添加任务。

执行交接

保存计划后，提供执行选择：

"计划完成并保存到 docs/zjkycode/plans/<filename>.md。两种执行选项：

1. 子代理驱动（推荐） - 我为每个任务调度一个新子代理，在任务之间审查，快速迭代

2. 内联执行 - 使用 executing-plans 在此会话中执行任务，带检查点的批量执行

选择哪种方式？"

如果选择子代理驱动：

• **必需的子技能：**使用 zjkycode:subagent-driven-development
• 每个任务一个新子代理 + 两阶段审查

如果选择内联执行：

• **必需的子技能：**使用 zjkycode:executing-plans
• 带检查点的批量执行以供审查