# Eo Spec Review > | - **Type:** Skill - **Install:** `agentstack add skill-simpleeve-eo-skills-eo-spec-review` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [SimpleEve](https://agentstack.voostack.com/s/simpleeve) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [SimpleEve](https://github.com/SimpleEve) - **Source:** https://github.com/SimpleEve/eo-skills/tree/main/eo-spec-review ## Install ```sh agentstack add skill-simpleeve-eo-skills-eo-spec-review ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # eo-spec-review — 模块 spec 审查 对模块 spec.md 做系统性质量审查，确保模块基线完整、无歧义、可执行。 > **适用阶段**： > - **强制一次**：模块初始化时（由 /eo-module-init 自动触发） > - **可选复检**：archive 后 spec 被 Delta 大改、或发生结构性 refactor 后，用户主动触发 > > 日常业务变更不需要跑 spec-review（走 /eo-change 写 Delta + /eo-change-review 即可）。 ## 核心原则 1. **对照模板审查**：严格依据 spec 模板检查每个章节的完整性与质量 2. **发现歧义**：识别所有可能导致 plan/implement 阶段产生分歧的模糊描述 3. **不改 spec**：审查只产出报告，修订工作由用户决定后通过 `/eo-spec` 执行 4. **固定产出**：输出到 `eo-doc/dev//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//spec.md` 必须已存在 - 如果 spec 不存在，提示用户先执行 `/eo-module-init `（或独立 `/eo-spec`） ## 工作流程 ### 第一步：阅读上下文 1. 阅读 `eo-doc/dev//spec.md`（需通读全文做完整性审查）——若文件较大、单次 `Read` 超限，先用 `Grep` 取章节地图（`^#{1,3} `）再按 offset/limit 分段读全，不可因超限而漏读章节 2. 阅读项目级背景文档（如果存在），理解整体背景 3. **执行模板发现**（见上方），确定是否启用多层审查维度 4. 扫描 `eo-doc/dev/` 下其他 spec 的 frontmatter，检查跨功能一致性 5. 阅读现有代码结构，理解技术现状 ### 第二步：系统审查 按以下维度逐一审查： #### 维度 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//spec-review.md`。 ### 第四步：更新索引 更新 `eo-doc/dev/INDEX.md`。 ## 固定模板 ```markdown --- title: Spec 审查报告 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 - **可操作**：每个问题的建议必须具体到用户能直接行动 - **区分"存在"与"消费"**：新功能引用的已有基础设施，验证其定义是否存在即可。"当前未被业务消费"不构成问题 - **搜索含定义源头**：验证基础设施是否存在时，必须搜索定义源头（含自动生成目录），不能仅搜业务代码 ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [SimpleEve](https://github.com/SimpleEve) - **Source:** [SimpleEve/eo-skills](https://github.com/SimpleEve/eo-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-simpleeve-eo-skills-eo-spec-review - Seller: https://agentstack.voostack.com/s/simpleeve - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.