| name | eo-spec-review |
| description | 对模块 spec.md 做系统性质量审查。必需场景:module-init 阶段(由 /eo-module-init 触发一次)。可选场景:archive 后含大量 MODIFIED/REMOVED 时复检。触发:审查 spec / review spec / 检查需求 / /eo-spec-review。
NOT FOR: 审代码(/eo-review)或 change 方案(/eo-change-review)。
|
eo-spec-review — 模块 spec 审查
对模块 spec.md 做系统性质量审查,确保模块基线完整、无歧义、可执行。
适用阶段:
- 强制一次:模块初始化时(由 /eo-module-init 自动触发)
- 可选复检:archive 后 spec 被 Delta 大改、或发生结构性 refactor 后,用户主动触发
日常业务变更不需要跑 spec-review(走 /eo-change 写 Delta + /eo-change-review 即可)。
核心原则
- 对照模板审查:严格依据 spec 模板检查每个章节的完整性与质量
- 发现歧义:识别所有可能导致 plan/implement 阶段产生分歧的模糊描述
- 不改 spec:审查只产出报告,修订工作由用户决定后通过
/eo-spec 执行
- 固定产出:输出到
eo-doc/dev/<module-name>/spec-review.md
模板发现
启动时检查 eo-doc/templates/:
- 若
eo-doc/templates/project-profile.md 存在 → 读取,了解项目类型和层级结构
- 若
eo-doc/templates/spec-layers.md 存在 → 读取,作为维度 7 "多层协作完整性"的审查依据(知道模板要求了什么,才能判断 spec 是否完整)
- 若上述文件不存在 → 跳过维度 7(现有默认行为)
前置条件
- 必须能找到
.eo-project.json。找不到 → 报错退出,提示运行 /eo-project-init。eo-doc/ 路径通过 doc_root 字段解析
- 对应模块的
eo-doc/dev/<module-name>/spec.md 必须已存在
- 如果 spec 不存在,提示用户先执行
/eo-module-init <module-name>(或独立 /eo-spec)
工作流程
第一步:阅读上下文
- 阅读
eo-doc/dev/<module-name>/spec.md(需通读全文做完整性审查)——若文件较大、单次 Read 超限,先用 Grep 取章节地图(^#{1,3} )再按 offset/limit 分段读全,不可因超限而漏读章节
- 阅读项目级背景文档(如果存在),理解整体背景
- 执行模板发现(见上方),确定是否启用多层审查维度
- 扫描
eo-doc/dev/ 下其他 spec 的 frontmatter,检查跨功能一致性
- 阅读现有代码结构,理解技术现状
第二步:系统审查
按以下维度逐一审查:
维度 1:结构完整性
- 模板中每个章节是否都已填写
- 是否有章节被跳过或用"TODO"、"待补充"等占位符敷衍
- 同目录 spec-history.md 是否已生成(含「模块初始化」初始记录行)
维度 2:需求清晰度
- 每条需求描述是否无歧义
- 是否存在"可能"、"大概"、"应该"、"也许"等模糊词
- 输入/输出的格式、类型、约束是否明确
- 核心行为描述是否足够具体
维度 3:边界与范围
- In Scope / Out of Scope 是否明确且合理
- 是否存在需求范围蔓延的风险
- 已知约束是否完整
维度 4:验收标准质量
- 每条 AC 是否使用 Given-When-Then 格式
- AC 是否可测试、可自动化验证
- 正常路径、边界条件、异常场景是否都有对应的 AC
维度 5:一致性检查
- spec 内部各章节之间是否自相矛盾
- 与已有的其他 spec 是否存在冲突或重叠
- 与项目整体架构和技术约束是否兼容
维度 6:可行性预判
- 需求在技术层面是否可实现
- 是否存在明显的技术风险未被提及
- 非功能需求是否合理
基础设施引用验证原则:
- 新功能引用已有基础设施(配置表、协议定义、枚举、类型等)时,只需验证定义是否存在,不判断业务代码是否已消费。"尚未被业务消费"恰恰是新功能要做的事,不构成可行性问题
- 验证存在性时,搜索定义源头(含自动生成目录),不能仅搜业务逻辑代码就判定"不存在"
- 只有定义源头确实找不到时,才标记为可行性风险
维度 7:多层协作完整性(仅多层项目)
条件维度:仅当 eo-doc/templates/spec-layers.md 存在时启用。
审查依据:以 spec-layers.md 模板定义的结构为标准,逐项检查 spec 的"多层协作需求"章节。
- 结构对照:spec-layers.md 模板要求的每个子章节(交互流向、各层职责划分、需要的数据与通信、一致性检查清单)是否都已填写
- 层覆盖度:project-profile.md 中定义的每个层是否都在职责划分表中出现
- 各层职责是否明确划分,无遗漏
- 交互流向是否覆盖所有层间通信
- 数据与通信需求表是否覆盖所有涉及的层
- 一致性检查清单是否可验证(每条约束有明确的验证方式)
- 是否存在层间职责冲突或重叠
- 禁止事项检查:是否违反模板中的禁止事项(如写了接口签名、消息字段、代码结构)
第三步:撰写审查报告
按照下方固定模板撰写,写入 eo-doc/dev/<module-name>/spec-review.md。
第四步:更新索引
更新 eo-doc/dev/INDEX.md。
固定模板
---
title: <功能名称> Spec 审查报告
spec_name: <spec-name>
tags: [标签1, 标签2]
created: YYYY-MM-DD
updated: YYYY-MM-DD
status: active
summary: >
一句话概述审查结论。
---
# <功能名称> Spec 审查报告
> 关联 Spec:[spec.md](spec.md)
> 审查日期:YYYY-MM-DD
> Spec 状态:草稿 | 已确认
## 审查总结
一段话概述 spec 整体质量,是否达到可进入 plan 阶段的标准。
给出明确结论:✅ 模块基线通过 / ⚠️ 需小幅修订后通过 / ❌ 需大幅修订
## P0 - 必须修订(阻塞模块基线确认)
### [P0-1] <问题标题>
- **类型**:歧义 / 遗漏 / 矛盾 / 不可行
- **位置**:spec.md 中的章节
- **描述**:问题的具体描述
- **影响**:如果不解决,plan/implement 阶段会产生什么问题
- **建议**:需要补充或修订的方向
## P1 - 建议修订(不阻塞但影响质量)
### [P1-1] <问题标题>
- **类型**:模糊描述 / 边界不清 / AC 不足 / 一致性问题
- **位置**:spec.md 中的章节
- **描述**:问题的具体描述
- **建议**:改进方向
## P2 - 可选优化(锦上添花)
### [P2-1] <问题标题>
- **类型**:措辞优化 / 场景补充 / 格式调整
- **描述**:建议内容
## 结构完整性检查
| 章节 | 状态 | 备注 |
|------|------|------|
| 1.1 功能简述 | ✅ / ❌ / ⚠️ | ... |
| 1.2 所属模块 | ✅ / ❌ / ⚠️ | ... |
| 1.3 关联文档 | ✅ / ❌ / ⚠️ | ... |
| 2.1 目标用户 | ✅ / ❌ / ⚠️ | ... |
| 2.2 用户故事 | ✅ / ❌ / ⚠️ | ... |
| 2.3 使用场景 | ✅ / ❌ / ⚠️ | ... |
| 3.1 输入 | ✅ / ❌ / ⚠️ | ... |
| 3.2 输出 | ✅ / ❌ / ⚠️ | ... |
| 3.3 核心行为描述 | ✅ / ❌ / ⚠️ | ... |
| 3.4 业务规则与约束 | ✅ / ❌ / ⚠️ | ... |
| 4.1 性能要求 | ✅ / ❌ / ⚠️ | ... |
| 4.2 安全要求 | ✅ / ❌ / ⚠️ | ... |
| 4.3 兼容性要求 | ✅ / ❌ / ⚠️ | ... |
| 5.1 In Scope | ✅ / ❌ / ⚠️ | ... |
| 5.2 Out of Scope | ✅ / ❌ / ⚠️ | ... |
| 5.3 已知约束 | ✅ / ❌ / ⚠️ | ... |
| 6. 验收标准 | ✅ / ❌ / ⚠️ | ... |
| 7. 多层协作需求 | ✅ / ❌ / ⚠️ / N/A | 仅多层项目需要 |
| 8. 开放问题 | ✅ / ❌ / ⚠️ | ... |
| spec-history.md | ✅ / ❌ / ⚠️ | 已生成、含初始记录行 |
## 验收标准覆盖分析
| 功能需求 | 对应 AC | 覆盖情况 |
|----------|---------|----------|
| 需求描述 | AC-N | ✅ 已覆盖 / ❌ 缺失 / ⚠️ 不完整 |
关键约束
- 不改 spec:审查只产出报告,不直接修改 spec.md
- 客观依据:基于模板标准和项目上下文审查,不做主观偏好评判
- P0 必须精准:只有真正阻塞模块基线建立、会导致后续 change 反复澄清的问题才标为 P0
- 可操作:每个问题的建议必须具体到用户能直接行动
- 区分"存在"与"消费":新功能引用的已有基础设施,验证其定义是否存在即可。"当前未被业务消费"不构成问题
- 搜索含定义源头:验证基础设施是否存在时,必须搜索定义源头(含自动生成目录),不能仅搜业务代码