275 lines
6.4 KiB
Markdown
275 lines
6.4 KiB
Markdown
---
|
||
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：文件结构规划
|
||
|
||
**目标**：规划将创建或修改的文件及其职责。
|
||
|
||
**设计原则**：
|
||
|
||
- 单一职责：每个文件应有单一明确职责
|
||
- 上下文友好：能在一个上下文窗口中理解的代码
|
||
- 聚焦文件：优先选择小而专注的文件
|
||
|
||
**输出格式**：
|
||
|
||
```markdown
|
||
## 文件结构
|
||
|
||
### 新建文件
|
||
|
||
- `path/to/new/file.ts` - 职责描述
|
||
|
||
### 修改文件
|
||
|
||
- `path/to/existing/file.ts` - 修改内容描述
|
||
|
||
### 测试文件
|
||
|
||
- `tests/path/to/test.ts` - 测试职责
|
||
```
|
||
|
||
**代码注释规划**：
|
||
|
||
**在文件结构规划中明确注释需求**：
|
||
|
||
对于每个新建或修改的文件，标注注释需求：
|
||
|
||
```markdown
|
||
### 新建文件
|
||
|
||
- `src/utils/helper.ts` - 职责描述
|
||
- 注释需求：需要为所有公共函数添加文档注释
|
||
- 复杂度：中等（包含复杂算法，需要详细注释）
|
||
```
|
||
|
||
**注释需求评估标准**：
|
||
|
||
- **高优先级**：公共 API、核心业务逻辑、复杂算法
|
||
- **中优先级**：工具函数、数据处理逻辑
|
||
- **低优先级**：简单工具函数、配置文件
|
||
|
||
**完成标准**：文件结构已规划，测试文件已明确，注释需求已评估，用户已确认
|
||
|
||
---
|
||
|
||
### 阶段 3：任务定义
|
||
|
||
**目标**：定义具体的实施任务。
|
||
|
||
**任务粒度**：每个步骤应对应一个操作（耗时 2-5 分钟）。
|
||
|
||
**任务结构**：
|
||
|
||
```markdown
|
||
### 任务 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`
|
||
|
||
**内容**：
|
||
|
||
```markdown
|
||
# [项目名称] 实施计划纲领
|
||
|
||
## 子系统划分
|
||
|
||
| 子系统 | 范围 | 依赖 | 状态 |
|
||
| ------- | ------ | ---- | ------ |
|
||
| 子系统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. 根据"下一步"继续执行
|