| 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
- 带检查点的批量执行以供审查
