module-spec-writer

name	module-spec-writer
description	基于已冻结的意图文档，为功能模块执行材料准备、生成设计文档或输出落地规范与契约文件。 触发场景：(1) 用户要求编写技术规格、编码规范或落地实现； (2) 用户提到"技术设计"、"编码规格"、"类型定义"、"接口契约"、"状态机实现"等关键词； (3) 模块设计流水线进入规格阶段，意图文档已冻结； (4) 用户要求生成设计文档或落地规范； (5) 用户要求将高层设计转化为包含精确类型定义、异常处理、状态机的代码级文档； (6) 用户要求生成或更新接口契约文件与索引。 按三步连续流程执行：材料准备与前置检查 → 生成设计文档 → 最终规格与契约输出。

Module Spec Writer

基于已冻结的意图文档，为功能模块生成两份技术文档：

• 设计文档（瘦身版）：技术实现思路、架构权衡、兼容性分析、设计原则兑现
• 落地规范：精确的类型定义、接口契约、状态转换表、异常阈值、验收测试场景

流水线关系：意图文档（冻结）→ 材料准备 → 技术预研 → 设计文档 → 契约协调 → 落地规范 + 契约 module-spec-writer 必须以已冻结的意图文档为输入，禁止跳过意图文档直接生成技术规格。

---

核心原则

• 意图文档为强制门控：未冻结的意图文档 → 立即终止，不得继续。
• 意图缺陷零容忍：发现技术不可行项 → 触发回退机制，无权自行妥协。
• 外部接口先锁定：对外接口经契约协调后锁定（【已锁定】），内部实现不得修改。
• 中文输出：所有面向用户的文本使用中文，代码与专有名词除外。

---

前置输入

参数	说明
module_id	模块编号
module_name	模块名称
module_group	所属分组（已标准化为目录前缀）
incremental_mode	增量模式：full_design / design_docs_only_intent_frozen

---

执行流程

本 Skill 按三个连续步骤执行。每步完成后自然进入下一步。

步骤 1：输入准备与前置检查

目标：验证输入完备性，检测意图缺陷，执行项目级一致性扫描。

1. 检查已有产物：检查目标路径下设计文档是否已存在。若已存在，说明本模块曾在先前运行中完成过本步骤 → 跳过子步骤 2-3（意图文档校验和意图缺陷初筛），仅执行子步骤 4-5（收集材料路径和项目级一致性检查）。

2. 读取上游产物：定位并读取已冻结的意图文档（位于模块目录 docs/功能设计/[序号]-[分组]/[编号]-[名称]/[编号]-[名称]-意图文档.md）。

3. 意图文档校验：

   • 检查文档存在性。缺失 → 上报 ERROR，说明缺失文件路径。
   • 检查冻结状态（文档内标注"已冻结"且有冻结时间）。未冻结 → 上报 ERROR。

4. 意图缺陷初筛：扫描意图文档中的业务约束和验收标准，判断是否存在明显技术不可行项：

   • 性能指标无法达成
   • 与项目技术栈根本性冲突
   • 业务规则自相矛盾
   • 若发现意图缺陷 → 触发回退机制（见下方），不得继续后续步骤。

5. 收集材料路径：定位并记录以下路径（仅记录，不读取内容）：

   • 技术栈设计文档：docs/项目名称-技术栈设计.md
   • 功能模块全拆解表：docs/功能设计/功能模块全拆解.md
   • 模块依赖关系分析：docs/功能设计/模块依赖关系分析.md
   • 契约索引：docs/功能设计/_contracts.md
   • 已有规格文档：扫描 docs/功能设计/ 下所有 [编号]-[名称]-落地规范.md
   • 路径格式严格遵守 directory-convention.md，[序号] 和 [分组] 从 功能模块全拆解.md 章节标题提取并标准化。

6. 项目级一致性检查：

   • 扫描已有规格文档的模块编号、状态定义、接口命名。
   • 检查同名异构类型、状态定义冲突、循环依赖迹象。
   • 将发现的问题追加写入 docs/功能设计/_sync-issues.md（按时间戳分节，不覆盖已有内容）。
   • 若无问题，确保 _sync-issues.md 中本模块对应节标注 "✅ 无冲突"。

7. 上报：输出材料清单、意图缺陷结论、同步检查结果摘要，进入步骤 2。

---

步骤 2：生成设计文档

目标：基于技术预研报告（由独立的 spec-researcher 产出），生成设计文档（瘦身版）。

1. 读取上游产物：

   • 读取《技术决策完整报告》（位于 .tmp/tech-decision-report-<module_id>.md）。
   • 检查用户在上轮循环中的裁决反馈（如通过 continue 上下文注入）。

2. 增量感知：检查目标路径下设计文档是否已存在：

   • 若不存在 → 全新生成 v1.0。
   • 若已存在 → 基于已有文档增量更新，产出 v2.x，变更章节以 [UPDATED] 标签标注。

3. 检查业务矛盾：

   • 提取报告中的业务矛盾标记清单。
   • 若清单非空 → 基于报告推荐方案和用户历史裁决（如有）做出最佳推断，标注矛盾及处理方式。
   • 若用户历史裁决与报告推荐冲突 → 以用户裁决为准。

4. 项目级一致性复查：

   • 再次扫描已有规格文档，核对本模块设计决策是否与已有模块产生新增冲突。
   • 将新增冲突追加到 docs/功能设计/_sync-issues.md。

5. 生成/更新设计文档：

   • 以技术决策报告为核心依据，用户历史裁决为修正项。
   • 输出路径：docs/功能设计/[序号]-[分组]/[编号]-[名称]/[编号]-[名称]-设计文档.md（格式严格遵守 directory-convention.md）
   • 模板：references/human-design-template.md
   • 必须包含章节：1.1 技术实现思路 → 1.2 已有设计兼容性分析 → 1.3 依赖关系概述 → 1.4 状态机设计（如适用）→ 1.5 设计原则兑现清单 → 1.6 架构权衡与备选方案 → 1.7 注意事项与禁止行为 → 1.8 引用：配套意图文档
   • 增量更新时：在版本记录中追加新版本行，变更章节标题后标注 [UPDATED]。

6. 确认：发起 AskUserQuestion 将设计文档内容呈现给用户审阅，选项为："通过"（确认设计文档，进入契约协调）、"继续完善"（修正或补充设计内容）、"放弃模块"（放弃本模块设计）。用户确认后进入步骤 3。

---

步骤 3：最终规格与契约输出

目标：基于设计文档和契约协调报告，生成落地规范、写入契约文件、更新索引。

1. 读取输入：

   • 读取《契约协调报告》（位于 .tmp/contract-harmonize-report.json）。
   • 扫描 docs/功能设计/ 定位本模块的设计文档。
   • 检查用户在上轮循环中的裁决反馈（如通过 continue 上下文注入）。

2. 增量感知：检查目标路径下落地规范是否已存在：

   • 若不存在 → 全新生成 v1.0。
   • 若已存在 → 基于已有规范增量更新，产出 v2.x，变更章节以 [UPDATED] 标签标注。

3. 处理契约冲突：

   • 提取报告中的 findings.conflicts 和 findings.reusables。
   • 若有冲突 → 基于协调报告的推荐方案和用户历史裁决做出最佳推断，标注冲突及处理方式。
   • 若有可复用项 → 默认复用已有契约（用户历史裁决优先）。
   • 若用户历史裁决与协调报告推荐冲突 → 以用户裁决为准。

4. 生成落地规范对外接口章节（【已锁定】）：

   • 1.3 输入定义（契约引用格式）
   • 1.4 输出定义（契约引用格式）
   • 1.6 接口契约（完整函数签名、docstring、异常、副作用）
   • 1.7 依赖与集成接口
   • 对外接口类型使用契约引用，不写完整字段定义。

5. 生成落地规范内部实现章节（【对内实现】）：

   • 1.1 技术栈绑定 → 1.2 文件归属
   • 1.5 核心逻辑步骤（原子操作，含操作对象、输入来源、输出去向、失败行为）
   • 1.8 状态机（表格形式，如适用）
   • 1.9 异常与边界条件（≥3 种，含精确触发阈值、处理策略、重试参数）
   • 1.10 验收测试场景（≥2 正 + 2 异常，Given-When-Then + 完整 JSON）
   • 1.11 注意事项与禁止行为（编码层面）
   • 1.12 文档详细度自检清单
   • 1.15 意图一致性声明
   • 1.14 外部接口契约清单
   • 模板：references/agent-spec-template.md

6. 写入契约文件：

   • 将对外类型写入 docs/contracts/{module_id}/。
   • 格式必须符合 references/contract.schema.json。
   • x-defined-by 填写本模块编号，x-maturity 初始为 draft。
   • 复用已有契约的类型 → 不新建文件，在 _module-index.json 中记录 reference_only: true。
   • 目录结构参考 references/contract-directory-guide.md。

7. 更新索引：

   • 更新 docs/contracts/_index.json：追加本模块契约条目，更新 x-consumers。
   • 更新 docs/功能设计/_contracts.md：按模块编号插入/更新条目。
   • 格式参考 references/contract-index-template.md。
   • 时间戳通过工作流级共享脚本 .claude/workflows/project-design-pipeline/scripts/get_timestamp.py 获取。

8. 输出落地规范：

   • 合并对外接口章节和内部实现章节，输出到 docs/功能设计/[序号]-[分组]/[编号]-[名称]/[编号]-[名称]-落地规范.md（格式严格遵守 directory-convention.md）。
   • 对外接口章节标记 【已锁定】，内部章节标记 【对内实现】。
   • 增量更新时：在版本记录中追加新版本行，变更章节标题后标注 [UPDATED]。

9. 确认：发起 AskUserQuestion 将最终规格与契约文件呈现给用户终审，选项为："输出规格"（确认最终产物，完成本模块设计）、"继续完善"（修正或补充规格细节）、"放弃模块"（放弃本模块设计）。

10. 上报：用户确认后，输出落地规范路径、契约文件清单、索引更新状态、冲突处理说明（如有）。上报 DONE。

---

回退机制

硬性约束：发现意图缺陷时，无权自行妥协。

触发条件（满足任一）：

1. 意图文档中的业务约束或验收标准在当前技术架构下不可能实现
2. 意图文档中的要求与项目技术栈设计文档存在不可调和的冲突
3. 意图文档中"留给规范阶段的技术决策"清单不完整，缺少关键技术决策项
4. 意图文档中的业务规则存在逻辑矛盾，无法转化为一致的技术实现

回退流程：

1. 立即停止当前所有工作，不得继续生成设计文档或落地规范。
2. 上报 ERROR，报告必须包含：
   • 标记为 "意图缺陷"
   • 缺陷内容（引用意图文档的具体章节和原文）
   • 技术不可行的依据
   • 回退路径："请回退到意图文档阶段，修正以下缺陷后重新冻结：\n- [缺陷描述]\n修正后重新冻结意图文档，再进入规范阶段。"

禁止行为：

• 禁止发现意图缺陷后自行修改或妥协
• 禁止绕过意图缺陷继续生成文档
• 禁止将意图缺陷隐藏在设计文档的注释中

---

质量检查清单

输出前逐项确认：

通用检查：

• 意图文档已存在且已冻结
• 无未解决的意图缺陷（回退机制未触发或已处理）
• 两份文档的模块编号、名称、版本记录保持一致
• 所有"（待确认）"标注都有合理推断
• 已参考项目技术栈设计文档
• 版本记录每行以 > 开头（引用块内）
• 增量更新时版本号正确递增，[UPDATED] 标签准确标注变更章节

设计文档检查（步骤 2 产出）：

• 聚焦"为什么这样实现"，非罗列步骤
• 架构权衡有具体方案对比和选择理由
• 不包含业务定位、用户旅程、验收标准、业务约束
• 依赖关系概述精确到框架/服务/协议

落地规范检查（步骤 3 产出）：

• 对外接口类型已转为契约引用，不写完整字段定义
• 契约文件已写入 docs/contracts/{module_id}/，格式符合 contract.schema.json
• 异常场景 ≥ 3 种，每种含精确触发阈值、处理策略、重试参数
• 验收测试 ≥ 2 正 + 2 异常，Given-When-Then + 完整 JSON
• 依赖声明具体到函数名/Cypher 查询/类名
• 状态机使用表格形式（如涉及）
• 无偷懒表述（"等等"、"..."、"其他字段"、"参考其他模块"）
• 文档自包含：不了解代码的 Agent 可凭此文档独立完成编码
• 包含"意图一致性声明"和"外部接口契约清单"章节

契约文件检查（步骤 3 产出）：

• x-defined-by 已正确填写为本模块编号
• x-contract-type 已正确标注
• 与已有契约的冲突已解决（以用户裁决为准）
• docs/contracts/_index.json 已更新
• docs/功能设计/_contracts.md 已更新

---

参考文件索引

文件	归属	用途	加载时机
references/human-design-template.md	Skill 独有	设计文档输出模板	步骤 2 生成设计文档
references/agent-spec-template.md	Skill 独有	落地规范输出模板	步骤 3 生成落地规范
references/contract-directory-guide.md	Skill 独有	契约目录组织指南	步骤 3 写入契约文件
references/contract-index-template.md	Skill 独有	契约索引模板	步骤 3 更新 _contracts.md
references/contract.schema.json	Skill 独有	契约文件 JSON Schema 标准	步骤 3 写入契约文件