| 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：输入准备与前置检查
目标：验证输入完备性，检测意图缺陷，执行项目级一致性扫描。
-
检查已有产物：检查目标路径下设计文档是否已存在。若已存在，说明本模块曾在先前运行中完成过本步骤 → 跳过子步骤 2-3（意图文档校验和意图缺陷初筛），仅执行子步骤 4-5（收集材料路径和项目级一致性检查）。
-
读取上游产物：定位并读取已冻结的意图文档（位于模块目录 docs/功能设计/[序号]-[分组]/[编号]-[名称]/[编号]-[名称]-意图文档.md）。
-
意图文档校验：
- 检查文档存在性。缺失 → 上报
ERROR，说明缺失文件路径。
- 检查冻结状态（文档内标注"已冻结"且有冻结时间）。未冻结 → 上报
ERROR。
-
意图缺陷初筛：扫描意图文档中的业务约束和验收标准，判断是否存在明显技术不可行项：
- 性能指标无法达成
- 与项目技术栈根本性冲突
- 业务规则自相矛盾
- 若发现意图缺陷 → 触发回退机制（见下方），不得继续后续步骤。
-
收集材料路径：定位并记录以下路径（仅记录，不读取内容）：
- 技术栈设计文档：
docs/项目名称-技术栈设计.md
- 功能模块全拆解表：
docs/功能设计/功能模块全拆解.md
- 模块依赖关系分析：
docs/功能设计/模块依赖关系分析.md
- 契约索引：
docs/功能设计/_contracts.md
- 已有规格文档：扫描
docs/功能设计/ 下所有 [编号]-[名称]-落地规范.md
- 路径格式严格遵守
directory-convention.md，[序号] 和 [分组] 从 功能模块全拆解.md 章节标题提取并标准化。
-
项目级一致性检查：
- 扫描已有规格文档的模块编号、状态定义、接口命名。
- 检查同名异构类型、状态定义冲突、循环依赖迹象。
- 将发现的问题追加写入
docs/功能设计/_sync-issues.md（按时间戳分节，不覆盖已有内容）。
- 若无问题，确保
_sync-issues.md 中本模块对应节标注 "✅ 无冲突"。
-
上报：输出材料清单、意图缺陷结论、同步检查结果摘要，进入步骤 2。
步骤 2：生成设计文档
目标：基于技术预研报告（由独立的 spec-researcher 产出），生成设计文档（瘦身版）。
-
读取上游产物：
- 读取《技术决策完整报告》（位于
.tmp/tech-decision-report-<module_id>.md）。
- 检查用户在上轮循环中的裁决反馈（如通过 continue 上下文注入）。
-
增量感知：检查目标路径下设计文档是否已存在：
- 若不存在 → 全新生成 v1.0。
- 若已存在 → 基于已有文档增量更新，产出 v2.x，变更章节以
[UPDATED] 标签标注。
-
检查业务矛盾：
- 提取报告中的业务矛盾标记清单。
- 若清单非空 → 基于报告推荐方案和用户历史裁决（如有）做出最佳推断，标注矛盾及处理方式。
- 若用户历史裁决与报告推荐冲突 → 以用户裁决为准。
-
项目级一致性复查：
- 再次扫描已有规格文档，核对本模块设计决策是否与已有模块产生新增冲突。
- 将新增冲突追加到
docs/功能设计/_sync-issues.md。
-
生成/更新设计文档：
- 以技术决策报告为核心依据，用户历史裁决为修正项。
- 输出路径：
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]。
-
确认：发起 AskUserQuestion 将设计文档内容呈现给用户审阅，选项为："通过"（确认设计文档，进入契约协调）、"继续完善"（修正或补充设计内容）、"放弃模块"（放弃本模块设计）。用户确认后进入步骤 3。
步骤 3：最终规格与契约输出
目标：基于设计文档和契约协调报告，生成落地规范、写入契约文件、更新索引。
-
读取输入：
- 读取《契约协调报告》（位于
.tmp/contract-harmonize-report.json）。
- 扫描
docs/功能设计/ 定位本模块的设计文档。
- 检查用户在上轮循环中的裁决反馈（如通过 continue 上下文注入）。
-
增量感知：检查目标路径下落地规范是否已存在：
- 若不存在 → 全新生成 v1.0。
- 若已存在 → 基于已有规范增量更新，产出 v2.x，变更章节以
[UPDATED] 标签标注。
-
处理契约冲突：
- 提取报告中的
findings.conflicts 和 findings.reusables。
- 若有冲突 → 基于协调报告的推荐方案和用户历史裁决做出最佳推断，标注冲突及处理方式。
- 若有可复用项 → 默认复用已有契约（用户历史裁决优先）。
- 若用户历史裁决与协调报告推荐冲突 → 以用户裁决为准。
-
生成落地规范对外接口章节（【已锁定】）：
- 1.3 输入定义（契约引用格式）
- 1.4 输出定义（契约引用格式）
- 1.6 接口契约（完整函数签名、docstring、异常、副作用）
- 1.7 依赖与集成接口
- 对外接口类型使用契约引用，不写完整字段定义。
-
生成落地规范内部实现章节（【对内实现】）：
- 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
-
写入契约文件：
- 将对外类型写入
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。
-
更新索引：
- 更新
docs/contracts/_index.json：追加本模块契约条目，更新 x-consumers。
- 更新
docs/功能设计/_contracts.md：按模块编号插入/更新条目。
- 格式参考
references/contract-index-template.md。
- 时间戳通过工作流级共享脚本
.claude/workflows/project-design-pipeline/scripts/get_timestamp.py 获取。
-
输出落地规范：
- 合并对外接口章节和内部实现章节，输出到
docs/功能设计/[序号]-[分组]/[编号]-[名称]/[编号]-[名称]-落地规范.md（格式严格遵守 directory-convention.md）。
- 对外接口章节标记
【已锁定】，内部章节标记 【对内实现】。
- 增量更新时：在版本记录中追加新版本行，变更章节标题后标注
[UPDATED]。
-
确认：发起 AskUserQuestion 将最终规格与契约文件呈现给用户终审，选项为："输出规格"（确认最终产物，完成本模块设计）、"继续完善"（修正或补充规格细节）、"放弃模块"（放弃本模块设计）。
-
上报：用户确认后，输出落地规范路径、契约文件清单、索引更新状态、冲突处理说明（如有）。上报 DONE。
回退机制
硬性约束：发现意图缺陷时，无权自行妥协。
触发条件（满足任一）：
- 意图文档中的业务约束或验收标准在当前技术架构下不可能实现
- 意图文档中的要求与项目技术栈设计文档存在不可调和的冲突
- 意图文档中"留给规范阶段的技术决策"清单不完整，缺少关键技术决策项
- 意图文档中的业务规则存在逻辑矛盾，无法转化为一致的技术实现
回退流程：
- 立即停止当前所有工作，不得继续生成设计文档或落地规范。
- 上报
ERROR，报告必须包含：
- 标记为 "意图缺陷"
- 缺陷内容（引用意图文档的具体章节和原文）
- 技术不可行的依据
- 回退路径："请回退到意图文档阶段，修正以下缺陷后重新冻结：\n- [缺陷描述]\n修正后重新冻结意图文档，再进入规范阶段。"
禁止行为：
- 禁止发现意图缺陷后自行修改或妥协
- 禁止绕过意图缺陷继续生成文档
- 禁止将意图缺陷隐藏在设计文档的注释中
质量检查清单
输出前逐项确认：
通用检查：
设计文档检查（步骤 2 产出）：
落地规范检查（步骤 3 产出）：
契约文件检查（步骤 3 产出）：
参考文件索引
| 文件 | 归属 | 用途 | 加载时机 |
|---|
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 写入契约文件 |
