Spec Write
核心规则
用户确认（必须执行）
[!important] 完成 plan.md 撰写后，必须使用
AskUserQuestion工具等待用户确认。
AskUserQuestion(
questions=[{
"question": "plan.md 已创建完成，请确认设计方案是否可以开始实现？",
"header": "确认方案",
"multiSelect": false,
"options": [
{
"label": "确认，开始实现",
"description": "设计方案正确，可以开始执行实现"
},
{
"label": "需要修改",
"description": "设计方案需要调整，请说明修改要求"
}
]
}]
)
分类目录与命名规范
| 目录 | 用途 | 适用场景 |
|---|---|---|
01-项目规划 | PRD、流程设计、项目规划 | 新项目启动、功能规划 |
02-架构设计 | 架构、数据模型、服务层设计 | 架构设计、数据结构 |
03-功能实现 | 功能实现、API、集成方案 | 新功能开发、API 接口 |
04-问题修复 | Bug 修复、重构方案 | Bug 修复、代码重构 |
05-测试文档 | 测试计划、测试报告 | 测试准备、测试总结 |
06-已归档 | 已完成的 Spec（自动移动） | 由 spec-execute 归档 |
文件夹命名：YYYYMMDD-HHMM-任务描述（任务描述必须中文）
路径示例：
✅ spec/03-功能实现/20260104-0900-专业评价Agent设计/plan.md
❌ spec/20260104-design/plan.md （未放入分类目录）
❌ spec/03-功能实现/20260104-feature/plan.md （任务描述必须中文）
工作流程
| 步骤 | 操作 | 要点 |
|---|---|---|
| 1 | 读取 exploration-report.md（如有） | 了解背景、现状、历史经验 |
| 2 | 与 spec-tester 讨论接口边界 | 确认异常处理、验收边界 |
| 3 | 确定文档类型和分类目录 | 根据需求类型选择 01-05 目录 |
| 4 | 确定文件夹命名 | YYYYMMDD-HHMM-中文任务描述 |
| 5 | 创建文件夹 | mkdir -p "spec/分类目录/文件夹名" |
| 6 | 选择模板 | 详见 references/templates.md |
| 7 | 撰写 plan.md | 详见 references/plan-template.md |
| 8 | 验证路径和命名 | 分类目录正确、日期时间当前、任务描述中文 |
| 9 | 保存文件 | Write 工具保存到目标路径 |
| 10 | 等待用户确认 | 必须使用 AskUserQuestion 工具 |
步骤 7：plan.md 内容要求（v2.0）
[!important] v2.0 变更：移除测试计划章节 plan.md 不再包含测试计划章节（由 spec-tester 用 spec-test 单独创建 test-plan.md）。
execution_mode固定为single-agent（不再使用 agent-teams 模式）。
必须包含的章节：
- 概述（背景、目标、范围）
- 需求分析
- 设计方案
- 执行模式（固定 single-agent，说明理由）
- 实现步骤
- 风险和依赖
- 文档关联
Frontmatter 格式和字段说明详见 references/plan-template.md。
禁止与推荐
禁止：
- ❌ Spec 确认前开始编写代码
- ❌ 在 plan.md 中包含测试计划章节（v2.0 起移除）
- ❌ 将 execution_mode 设为 agent-teams
- ❌ 直接在
spec/下创建文件夹（必须放入分类目录） - ❌ 任务描述使用英文
- ❌ 跳过用户确认步骤
推荐：
- ✅ 先读取 exploration-report.md 了解背景
- ✅ 与 spec-tester 讨论接口边界
- ✅ 使用 Obsidian Callout 和双链增强文档
后续流程
- 等待用户确认 plan.md
- 通知 TeamLead，TeamLead 触发实现阶段（spec-execute）
- 如果是功能更新，使用
spec-update执行