# Writing Plans

> Use when you have a spec or requirements for a multi-step task, before touching code

- Skill: `zouyangxiaohao111/writing-plans` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add zouyangxiaohao111/writing-plans`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zouyangxiaohao111/writing-plans/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: zouyangxiaohao111 (https://skillmd.com/u/zouyangxiaohao111)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zouyangxiaohao111/writing-plans

---


# 编写计划

## 概述

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

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

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

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

**计划保存位置：**`docs/zjkycode/plans/YYYY-MM-DD-<feature-name>.md`
- （用户对计划位置的偏好会覆盖此默认值）

## 范围检查

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

## 文件结构

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

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

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

## 小任务粒度

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

## 计划文档头部

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

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

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

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

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

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

---
```

## 任务结构

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