spec-write · diff

git:20260808.cc3dbc1 to git:20260809.5529781

12 added, 7 removed. Audit A to A.

---

disable-model-invocation: true

name: spec-write

description: >

撰写代码实现计划（writer/plan.html）。由角色 spec-writer 调用。

触发条件：(1) 角色 spec-writer 需要创建设计方案、API 规范、数据模型、架构设计、重构方案，

(2) 用户说"创建 Spec"/"撰写设计文档"/"写技术规格"/"设计方案"，

(3) 当前 Spec 目录下需要新建 writer/plan.html。

注意：v2.0 起 writer/plan.html 不含测试计划章节（由 spec-tester 用 spec-test 单独创建），

execution_mode 固定为 single-agent，且仅表示实现阶段执行模式，不否定项目级角色协作。

如果目录下已有 executor/summary.html 且仍在该 Spec 的活跃分支内，应使用 spec-update 而非本 Skill；若原分支已合并/关闭，后续需求默认新建 Spec。

---

# Spec Write

## 运行契约

> 进入核心规则前先对齐这张表。它把本 Skill 当成一个有边界的循环单元：明确读什么、能动什么、怎么算完成、什么时候停、什么时候交还给人。

| 项 | 本 Skill 的约定 |

|----|----------------|

| 输入 | `explorer/exploration-report.html`、与 spec-tester 讨论的接口边界、TeamLead 提供的 Git 元数据、`html-report` skill 的报告契约 |

| 权限 | 只写 `writer/plan.html`（设计方案）；不写测试计划、不实现代码、不归档、不提交；目录分类错误时通过 TeamLead 请求修正 |

- | 验证 | plan 含 7 个必需章节、工作类型目录正确、命名为中文 `YYYYMMDD-HHMM-任务描述`、分支字段与当前分支一致、HTML 骨架与修订标记符合 `html-report` 规范 |

- | 停止 | plan 定稿且通过用户确认即停止，不在确认前编写代码、不"顺手"加 Spec 未要求的设计 |

+ | 验证 | plan 含 7 个必需章节、工作类型目录正确、命名为中文 `YYYYMMDD-HHMM-任务描述`、分支字段与当前分支一致、HTML 骨架与修订标记符合 `html-report` 规范；plan 必须含接口签名、数据结构、文件清单、每个任务的验证命令，缺任一项不得进入实现 |

+ | 停止 | plan 定稿且通过确认即停止，不在确认前编写代码、不"顺手"加 Spec 未要求的设计 |

| 升级 | 探索背景不足、接口边界与 spec-tester 无法对齐、或需求超出当前 Spec 范围时，交回 TeamLead 由用户决策 |

+ | 参考 | plan 定稿前 → 必读 `references/plan-quality.md` |

## 核心规则

- ### 用户确认（必须执行）

+ ### 确认方式随模式（必须执行）

- **重要**：完成 `writer/plan.html` 撰写后，**必须**使用当前运行环境的确认方式等待用户确认。

+ **确认方式随模式**：`gated` 模式下完成 `writer/plan.html` 撰写后必须用当前运行环境的确认方式向用户确认；`autopilot` 模式下由「plan 完备度闸门（接口签名/数据结构/文件清单/每任务验证命令四项齐备）+ Spec 自审四问全部通过」替代该确认，两者缺一不可放行。四项与四问的细则见 [references/plan-quality.md](references/plan-quality.md)。

+ `gated` 模式的确认话术：

```text

确认目标：writer/plan.html 已创建完成，请确认设计方案是否可以开始实现？

确认选项：

- 确认，开始实现

- 需要修改（请说明修改要求）

```

+ `autopilot` 模式下把闸门四项与自审四问的逐条结论写入账本，任一项不齐或任一问未过即停止，不得放行到实现阶段。

### 工作类型目录与命名规范

分类按**任务主意图**判断，不按“是否会改代码”判断。不要把 03 当默认目录。

| 目录 | 何时使用 | 不要用于 |

|------|----------|----------|

| `01-产品规划` | 产品/业务层规划：PRD、路线图、需求拆解、用户流程、里程碑、范围定义 | 已经确定要实现的具体代码改动 |

| `02-技术设计` | 技术结构设计：系统架构、数据模型、模块边界、服务层、技术选型、迁移方案、跨模块契约 | 单个功能的常规实现细节 |

| `03-能力交付` | 新增用户可感知能力：新功能、新接口、新页面、新集成、新工作流、新模块 | 修复已有行为、重构、性能优化、测试补充、配置/依赖问题 |

| `04-系统改进` | 让已有系统变正确或更稳：Bug、回归、报错、异常边界、性能瓶颈、安全问题、数据不一致、配置/依赖问题、无新能力的重构/清理/技术债 | 新增能力；纯架构方案且暂不实现 |

| `05-验证工程` | 独立验证工作：测试策略、回归验证、覆盖率提升、测试基础设施、端侧审计日志方案 | 某个功能 Spec 内配套生成的 tester/test-plan.html 与 tester/test-report.html |

| `06-已归档` | 已完成 Spec 的最终归档目录 | 新建 Spec 时手动选择；归档只由 spec-end 执行 |

#### 分类决策顺序

按以下顺序判断，命中即停止：

1. **同一活跃 Spec 分支内的小变化** → 不新建 Spec 目录，使用 `spec-update` 在原 Spec 目录追加更新产物

2. **只做测试/验证/审计证据建设** → `05-验证工程`

3. **修复、稳定性、性能、安全、重构、技术债** → `04-系统改进`

4. **架构、数据模型、模块边界、技术选型、迁移方案** → `02-技术设计`

5. **产品规划、PRD、流程、路线图、需求拆解** → `01-产品规划`

6. **新增用户可感知能力或新集成** → `03-能力交付`

#### 容易误判的边界

| 用户说法/任务 | 应归类 | 原因 |

|---------------|--------|------|

| “修一下登录失败问题” | `04-系统改进` | 修复已有能力，不是新增登录功能 |

| “优化列表加载速度” | `04-系统改进` | 性能改进，目标是让现有行为更好 |

| “重构认证模块但不改变功能” | `04-系统改进` | 无新增能力，属于技术债/稳定性 |

| “设计新的权限模型” | `02-技术设计` | 核心是模型和边界设计 |

| “实现权限模型里的角色管理接口” | `03-能力交付` | 新增具体可用能力 |

| “补齐订单模块回归测试” | `05-验证工程` | 主意图是测试覆盖 |

| “为支付流程新增审计日志功能” | `03-能力交付` | 新增系统能力；对应测试证据仍放同一 Spec 目录 |

| “修复支付审计日志缺失” | `04-系统改进` | 已有审计能力不正确或不完整 |

**文件夹命名**：`YYYYMMDD-HHMM-任务描述`（任务描述**必须中文**）

**路径示例**：

```

✅ spec/03-能力交付/20260104-0900-专业评价Agent设计/writer/plan.html

✅ spec/04-系统改进/20260104-1030-登录超时错误修复/writer/plan.html

✅ spec/02-技术设计/20260104-1100-权限模型重构方案/writer/plan.html

❌ spec/20260104-design/plan.html （未放入分类目录）

❌ spec/03-能力交付/20260104-feature/writer/plan.html （任务描述必须中文）

```

## 工作流程

| 步骤 | 操作 | 要点 |

|------|------|------|

| 1 | 读取 `html-report` skill | **撰写报告前必读**：HTML 骨架、frontmatter 双轨等价字段、双向关联、修订标记规范 |

| 2 | 读取 `explorer/exploration-report.html`（如有） | 了解背景、现状、历史经验 |

| 3 | 通过 TeamLead 与 spec-tester 讨论接口边界 | 确认异常处理、验收边界 |

| 4 | 复核当前 Spec 工作类型目录 | 按“分类决策顺序”检查 01-05 目录，发现错误时通过 TeamLead 请求修正目录 |

| 5 | 复核文件夹命名 | `YYYYMMDD-HHMM-中文任务描述` |

| 6 | 确认 writer 目录存在 | `writer/` 应由 spec-start 创建；缺失时创建，不重建整个 Spec 目录 |

| 7 | 选择正文模板 | 详见 [references/templates.md](references/templates.md) |

| 8 | 撰写 `writer/plan.html` | 复制 [references/plan-template.html](references/plan-template.html) 骨架，写入 TeamLead 提供的 Git 元数据 |

| 9 | 验证路径和命名 | 工作类型目录正确、日期时间当前、任务描述中文 |

| 10 | 自检 HTML | 浏览器能打开且样式生效、`rk-meta` 与 `<meta name="rk:*">` 字段一致、`rk-links` 有对应反链登记、无 `<style>` 与行内 `style=` |

| 11 | 保存文件 | `Write` 工具保存到目标路径 |

- | 12 | 等待用户确认 | **必须**使用当前运行环境的确认方式 |

+ | 12 | 等待确认 | `gated`：**必须**使用当前运行环境的确认方式；`autopilot`：以 plan 完备度闸门四项齐备 + Spec 自审四问全部通过替代，逐条结论落账本 |

### 步骤 7：writer/plan.html 内容要求（v2.0）

**v2.0 变更：移除测试计划章节**

`writer/plan.html` **不再包含**测试计划章节（由 spec-tester 用 spec-test 单独创建 `tester/test-plan.html`）。

`execution_mode` **固定为 `single-agent`**，仅表示 spec-executor 的实现阶段执行模式；项目级角色协作由 spec-init/spec-start 管理。

**必须包含的章节**：

1. 概述（背景、目标、范围）

2. 需求分析

3. 设计方案

4. 执行模式（固定 single-agent，说明这是实现阶段执行模式）

5. 实现步骤

6. 风险和依赖

7. 关联产物（双向：`rk-links` 正向 + `rk-backlinks` 反向）

原 frontmatter 字段一律双轨保留：机器可读写进 `<head>` 的 `<meta name="rk:*">` / `<link rel="rk-*">`，人可读镜像到 `.rk-meta`。字段清单与对照表详见 [references/plan-template.html](references/plan-template.html)，禁止因为"HTML 里看不见"就删字段。

**GitHub Flow 字段**（双轨保留：`<meta name="rk:*">` + `.rk-meta`）：

- `rk:git-branch`：必须使用 spec-start / git-work 创建的当前分支

- `rk:base-branch`：通常为 `main`

- `rk:pr-url`：创建 PR 前留空，由 spec-end 写回

- 如果项目无 Git 仓库或用户确认无分支模式，`rk:git-branch` 写 `none` 并在风险/依赖中说明

## 禁止与推荐

**禁止**：

- ❌ Spec 确认前开始编写代码

- ❌ 在 `writer/plan.html` 中包含测试计划章节（v2.0 起移除）

- ❌ 将 execution_mode 设为 agent-teams 或把该字段解释为整个工作流不使用角色协作

- ❌ 手写一个未创建的分支名

- ❌ 直接在 `spec/` 下创建文件夹（必须放入工作类型目录）

- ❌ 任务描述使用英文

- - ❌ 跳过用户确认步骤

+ - ❌ 跳过确认步骤（`gated` 下未向用户确认，或 `autopilot` 下未过 plan 完备度闸门与 Spec 自审四问就放行）

- ❌ 在报告 HTML 里写 `<style>`、行内 `style=` 或引用外部 CDN

- ❌ 用 Obsidian 专有语法（`[[wikilink]]`、`> [!note]` Callout、`#tag`）

- ❌ 迁移时丢掉原 frontmatter 字段，或只写单向链接不补反链

- ❌ 静默改写已确认报告内容（必须递增修订号 + 追加修订历史 + `ins`/`del` 标记）

**推荐**：

- ✅ 撰写前先读 `html-report` skill，按其骨架与类名产出

- ✅ 先读取 `explorer/exploration-report.html` 了解背景

- ✅ 通过 TeamLead 与 spec-tester 讨论接口边界

- ✅ 使用 html-report 的 `rk-cal` / `rk-verdict` 组件突出重点，修订遵循 `data-rev` 规范

- ✅ 原 frontmatter 字段双轨保留（`<meta name="rk:*">` + `.rk-meta`），关联产物双向（`rk-links` + `rk-backlinks`）

- ✅ 确认 `writer/plan.html` 的 `rk:git-branch` 与当前分支一致

## 后续流程

1. 更新当前 Spec 的 `lead/team-context.md` 共享区：在「任务进度」中追加或更新 spec-writer 自己的任务行，「产物」指向 `writer/plan.html`，「状态」标记为 `done`，填写「完成时间」和 `updated_by: spec-writer`

2. 把 plan 中的关键设计取舍写入「决策记录」：每个方案分叉记一行「议题」/「候选项」（含被否决项）/「结论」/「理由」，「拍板者」写 `spec-writer`（若该取舍由用户拍板则写 `user`）

3. 若写方案时遇到过程性问题（依赖缺失、探索报告信息不足、接口边界未定等），在「问题闭环记录」追加一行，「分类」选 `dependency` / `process` / `scope`

4. 只修改「任务进度」/「决策记录」/「问题闭环记录」，不要修改 TeamLead 控制面区块

- 3. 等待用户确认 `writer/plan.html`

+ 3. 等待 `writer/plan.html` 通过确认：`gated` 等用户确认，`autopilot` 以完备度闸门四项 + 自审四问的逐条结论落账本替代

4. 通知 TeamLead，TeamLead 触发实现阶段（spec-execute）

5. 如果是功能更新，使用 `spec-update` 执行