writing-plan

name	writing-plan
description	实施计划创建技能，用于多步骤任务。在有规范或需求时，在直接接触代码前使用本技能。创建详细、可执行的实施计划。当用户提及"创建计划"、"实施计划"、"编写计划"、"规划"、"任务分解"或开始复杂的多步骤开发工作且有现有规范时触发本技能。
license	MIT
metadata	{"version":"3.0.1"}

编写计划技能

本技能用于创建多步骤开发任务的全面实施计划。在有规范或需求时，在直接接触任何代码之前使用。

---

核心原则

计划优先

在计划完成前，请勿：

• 调用任何实施技能
• 编写任何代码
• 创建或修改项目文件（计划文档除外）
• 采取任何实施行动

会话状态管理

使用统一的会话状态文件跟踪进度：

• 路径：design/.session-state.md
• 模板：references/session-state-template.md（共享）

操作时机：

• 技能激活时 → 创建/更新状态文件
• 完成阶段性成果后 → 更新状态文件
• 每轮对话开始时 → 读取状态文件恢复上下文
• 每个阶段完成后 → 更新状态文件

终止条件

本技能的唯一终止方式是完成计划文档并通知用户准备执行。

---

工作流程

阶段 1：上下文与范围分析

目标：理解规格文档，识别子系统。

执行动作：

1. 接收 brainstorming 传递的规格文档路径
2. 读取规格文档，理解需求
3. 评估是否涉及多个独立子系统

子系统识别标准：

特征	说明
独立数据模型	子系统有独立的数据结构
独立接口	子系统对外提供独立 API
独立部署	子系统可独立部署运行
清晰边界	子系统间通过明确接口通信

处理策略：

• 单一子系统 → 直接进入阶段 2
• 多个子系统 → 先创建纲领文件，再逐个子系统编写计划

完成标准：已理解需求，已识别子系统划分

---

阶段 2：文件结构规划

目标：规划将创建或修改的文件及其职责。

设计原则：

• 单一职责：每个文件应有单一明确职责
• 上下文友好：能在一个上下文窗口中理解的代码
• 聚焦文件：优先选择小而专注的文件

输出格式：

## 文件结构

### 新建文件

- `path/to/new/file.ts` - 职责描述

### 修改文件

- `path/to/existing/file.ts` - 修改内容描述

### 测试文件

- `tests/path/to/test.ts` - 测试职责

代码注释规划：

在文件结构规划中明确注释需求：

对于每个新建或修改的文件，标注注释需求：

### 新建文件

- `src/utils/helper.ts` - 职责描述
  - 注释需求：需要为所有公共函数添加文档注释
  - 复杂度：中等（包含复杂算法，需要详细注释）

注释需求评估标准：

• 高优先级：公共 API、核心业务逻辑、复杂算法
• 中优先级：工具函数、数据处理逻辑
• 低优先级：简单工具函数、配置文件

完成标准：文件结构已规划，测试文件已明确，注释需求已评估，用户已确认

---

阶段 3：任务定义

目标：定义具体的实施任务。

任务粒度：每个步骤应对应一个操作（耗时 2-5 分钟）。

任务结构：

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

**文件**：

- 创建：`path/to/file.ts`
- 测试：`tests/path/to/test.ts`

- [ ] **步骤 1**：编写失败测试
- [ ] **步骤 2**：运行测试验证失败
- [ ] **步骤 3**：编写最小实现
- [ ] **步骤 4**：运行测试验证通过

任务要求：

• 精确文件路径，无模糊引用
• 计划中包含完整代码，非占位符
• 精确命令及预期输出
• 测试优先方法（TDD）：每个任务必须先定义测试文件和测试用例

测试要求：

⚠️ 任务必须包含测试步骤，禁止以下情况：

• ❌ 只写实现代码，不写测试
• ❌ 测试文件路径为空或使用占位符
• ❌ 测试用例不完整或过于简单
• ❌ 跳过"编写失败测试"步骤

测试覆盖标准：

• 每个函数/方法至少有一个正向测试用例
• 边界条件必须有对应测试
• 错误处理路径必须有测试覆盖
• 测试文件必须在任务开始前创建

完成标准：所有任务已定义，每个任务都包含完整的测试计划，用户已确认

---

阶段 4：计划保存与确认

目标：保存计划文档，获得用户批准。

执行动作：

1. 保存计划到 design/plans/YYYY-MM-DD-<feature>.md
2. 请用户确认计划内容
3. 若用户批准，询问是否开始执行

标准话术：

"计划已完成并保存。请确认以下内容：

计划文档：design/plans/<filename>.md 任务总数：[数量]

确认后是否开始执行？"

---

阶段 5：执行交接

目标：调用 executing-plans 技能。

调用格式：

调用 executing-plans 技能，计划文档路径：<path>

终止：此阶段完成后，本技能结束。

---

多子系统处理

当识别到多个子系统时：

1. 创建纲领文件

路径：design/plans/YYYY-MM-DD-<topic>-outline.md

内容：

# [项目名称] 实施计划纲领

## 子系统划分

| 子系统  | 范围   | 依赖 | 状态   |
| ------- | ------ | ---- | ------ |
| 子系统A | [范围] | 无   | 待编写 |
| 子系统B | [范围] | A    | 待编写 |

## 执行顺序

1. 子系统A（无依赖）
2. 子系统B（依赖A）

## 共享组件

| 组件     | 使用子系统 | 定义位置      |
| -------- | ---------- | ------------- |
| [组件名] | A, B       | 子系统A计划中 |

2. 逐个子系统编写计划

每个子系统独立编写计划文档，完成后更新纲领文件状态。

---

参考指南

参考文档	用途
references/plan-template.md	计划模板
references/patterns.md	常见计划模式

---

常见问题

计划需要修改？

处理方式：

1. 在纲领文件中记录变更
2. 更新受影响的计划文档
3. 通知用户变更影响范围

对话中断后如何恢复？

处理方式：

1. 读取会话状态文件 design/.session-state.md
2. 根据"下一步"继续执行