| name | spec-review-with-codex |
| description | Claude 与 Codex 双视角 Spec Review（代码驱动）。并行审查需求/设计产出物（proposal、specs、design、tasks 等），各自独立探索项目代码以验证 spec 的可行性和完整性，对比分析后输出综合报告到 `.ai_docs/review/`。适用场景：(1) 用户在 opsx:ff 后要求审查 spec 质量，(2) 用户要求双 agent 协作审查需求或设计文档，(3) 用户手动明确触发该 skill 并传入目标目录。codex 永远不使用本 skill。 |
Spec Review with Codex
Claude 与 Codex 双视角并行审查需求/设计产出物，对比分析后输出综合报告。核心原则：代码驱动审查——两个 agent 各自独立探索项目代码，从不同视角验证 spec 是否切合当前代码实际。
参考资料
references/codex-exec-guide.md — Codex CLI exec 命令参考。codex exec 失败时按需读取。
输入
/spec-review-with-codex 之后的参数是目标目录路径。支持两种形式：
- OpenSpec 变更目录：如
openspec/changes/error-types-preconditions/，自动识别其中的 proposal.md、specs/、design.md、tasks.md
- 任意文档目录：包含需求/设计文档的目录，递归扫描
.md 文件
如未提供参数，使用 AskUserQuestion 询问目标目录。
代码探索原则
审查不能只看文档。Claude 和 Codex 必须各自独立探索项目代码，以代码现状为基准评判 spec。
探索范围（按 spec 涉及的模块按需执行）：
- 项目元信息：AGENTS.md、CLAUDE.md、go.mod/package.json 等，了解项目架构、约定和依赖
- 相关模块代码：spec 涉及的包/模块的现有实现，理解当前架构和模式
- 接口与类型定义：spec 引用或将修改的接口、类型、数据结构
- 测试代码：现有测试的覆盖范围和测试模式，判断 spec 的测试策略是否合理
- 相似功能：项目中已有的类似功能实现，判断 spec 是否复用了现有模式
不要预先汇总代码摘要。让每个 agent 自行决定探索路径和深度，以获得独立视角。
审查检查清单
Claude 和 Codex 共用同一套审查标准。构造 Codex prompt 时，将本节内容完整嵌入。
CRITICAL: 完整性 (Completeness)
- 需求是否覆盖了所有用户场景（正常流程 + 异常流程）？
- 错误处理和边界条件是否有对应需求？
- 是否遗漏了非功能性需求（性能、安全、可观测性）？
- 并发和竞态场景是否被考虑？
HIGH: 一致性 (Consistency)
- 需求之间是否存在矛盾或冲突？
- proposal 的范围与 specs 的需求列表是否对齐？
- design 的技术决策是否满足 specs 中的所有需求？
- tasks 是否覆盖了 specs 和 design 中的所有要求？
- 术语使用是否一致（同一概念是否用了不同名称）？
HIGH: 代码对齐 (Code Alignment)
需要探索项目代码后才能回答的问题：
- spec 提出的架构/模式是否与项目现有架构一致？是否引入了不必要的新模式？
- 项目中是否已有可复用的组件、工具函数或模式？spec 是否充分利用了它们？
- spec 涉及的修改是否会破坏现有功能？影响面是否被完整识别？
- spec 中引用的接口、类型、模块是否真实存在？签名是否匹配？
- 技术方案是否符合项目已有的编码约定和最佳实践（命名、错误处理、日志、测试等）？
- 依赖项（外部库、框架版本）是否与项目当前依赖兼容？
HIGH: 清晰度 (Clarity)
- 每条需求是否可验证（有明确的通过/失败标准）？
- 是否存在模糊用语（"适当的"、"合理的"、"尽可能"）？
- 接口契约（输入/输出/错误）是否明确定义？
- 是否有足够的示例或场景说明？
MEDIUM: 可行性 (Feasibility)
- 技术方案在当前代码基础上是否可行？是否存在未验证的假设？
- 是否考虑了替代方案并记录了取舍？是否有更简单的实现路径被忽略？
- 依赖项（外部库、系统能力）在项目中是否已确认可用或易于引入？
- 复杂度评估是否合理？是否有过度工程化的迹象？
- 是否存在需要大规模重构现有代码才能实现的隐含前提？
MEDIUM: 范围 (Scope)
- 变更边界是否清晰？是否有范围蔓延？
- 是否有需求超出了 proposal 定义的范围？
- 影响分析是否完整（对现有功能的影响）？
LOW: 可维护性 (Maintainability)
- 设计是否过度工程化？
- 是否为未来扩展留了合理的空间（但不过度设计）？
- 文档是否足够支撑后续开发者理解上下文？
问题陈述格式
Claude 和 Codex 的审查报告中，每个发现的问题必须按以下四要素结构化陈述：
- 位置：问题出现在哪个文件/章节/需求项（给出具体引用）
- 问题：问题是什么，属于哪个检查维度（如 Completeness / Code Alignment）
- 影响：如果不修复，会导致什么后果
- 建议：具体的修复或改进建议
构造 Codex prompt 时，将本节内容完整嵌入，要求 Codex 按相同格式输出。
工作流程
1. 识别审查目标
确认目标目录路径存在，扫描目录结构，列出待审查文件。生成摘要标识 summary_id（如 spec-error-types）。
2. 并行启动审查
同时执行以下两件事：
Codex 审查（后台）：
mkdir -p .ai_docs/codex_call .ai_docs/review
codex exec --full-auto -m gpt-5.6-sol -c model_reasoning_effort=xhigh \
-o .ai_docs/codex_call/spec-review-result.md \
-C "<workdir>" \
"<prompt>" \
2>.ai_docs/codex_call/spec-review.log
Codex prompt 构造规则：
- 告知审查目标目录路径，与用户给的路径保持一致
- 要求不调用 OpenSpec 相关 skill，不修改任何文件
- 完整嵌入「代码探索原则」和「审查检查清单」章节内容，要求按相同维度和优先级输出结构化审查结果
- 明确要求 Codex 独立探索项目代码：读取项目元信息（AGENTS.md 等）、探索 spec 涉及的现有模块代码、验证 spec 中引用的接口和类型是否真实存在
- 要求 Codex 使用中文输出审查报告
- 如果是 OpenSpec 变更目录，要求执行跨产出物对齐检查
- 使用 Bash
run_in_background 启动，不限时
Claude 审查（前台）：
Claude 使用中文进行审查并输出结果。
- 读取目标目录下所有产出物文件
- 探索项目代码：按「代码探索原则」独立探索 spec 涉及的项目代码，重点关注现有架构、模式、接口定义和相关模块实现
- 按「审查检查清单」中的优先级逐项审查（包括「代码对齐」维度）
- 如果是 OpenSpec 变更目录，执行跨产出物对齐检查：
- proposal 定义的 capabilities 是否都有对应 specs
- specs 中的需求是否都在 design 中有技术方案
- design 中的决策是否都在 tasks 中有实现步骤
- tasks 是否有"孤立任务"（无法追溯到 specs 中的需求）
3. 对比分析与综合
等待 Codex 完成，读取 .ai_docs/codex_call/spec-review-result.md。
对比两份审查结果，使用中文写入 .ai_docs/review/<summary_id>-spec-review.md。
对比分析规则：
- 将两份报告中的问题按主题归并（同一位置/同一问题的合并为一条）
- 每个问题综合双方的建议，给出最终建议
- 如果某个问题的上下文不足以给出可靠建议（如一方指出了问题但缺少代码层面的验证），回到代码中补充探索，获取足够上下文后再给出建议
- 对 Codex 独有发现，回到代码/文档验证后再给出综合建议
- 不要简单罗列双方原文，要做真正的综合判断
报告结构：
# Spec Review Report: <标题>
## 审查目标
[目标目录、产出物列表、项目上下文]
## 共同发现
[两方都指出的问题——可信度最高，每条含综合建议]
## Claude 独有发现
[仅 Claude 发现的问题]
## Codex 独有发现
[仅 Codex 发现的问题，每条含 Claude 验证结论和综合建议]
## 综合结论
[最终评价、关键改进建议、优先级排序]
每条问题沿用「问题陈述格式」章节定义的四要素结构，按 severity 从高到低排列。无 finding 时对应章节不输出。
向用户展示报告摘要，并告知完整报告路径。
