review-forge

Review Forge

Review Forge 会运行一个保守且限定功能范围的代码审查工作流：

1. 检查目标差异和项目上下文。
2. 在当前功能文件夹中，为每个模型或 Agent 创建一个审查文件。
3. 将多个模型审查文件综合为一份由人工控制的检查清单。
4. 只修复已勾选并确认的问题。
5. 每批修复后运行针对性测试和回归测试。
6. 尽可能独立验证修复。
7. 更新机器可读状态和本地化报告标签。
8. 将所有工作流产物与产品代码隔离。

命令

• review：创建一个特定于模型的审查文件。不要修改产品代码。
• synthesize：将一个功能文件夹中的模型审查文件合并为一份摘要检查清单。不要修改产品代码。
• fix：读取摘要中已勾选的条目，确认选定范围，仅实施这些条目，运行测试并更新状态。
• verify：从独立视角验证已修复的条目，重新运行或检查测试，并更新验证状态。

支持旧版模式别名：

• review-only 表示 review；如果用户要求合并现有审查文件，则表示 synthesize。
• review-and-fix 表示 fix。
• review-verify 表示 verify。

如果用户未指定命令，请根据请求推断最稳妥的命令。如有歧义，默认使用 review。

输入

开始工作前，解析或询问以下输入：

• target：分支、提交范围、拉取请求或当前工作树。
• base：用于比较的分支或引用。如果省略，则根据下方的默认差异规则推断。
• artifact_root：默认值为 code_review/。
• feature：用作产物子文件夹的功能名称。如果省略，则从分支名称、PR 标题、变更的包或差异的简短净化摘要中推断。
• feature_dir：默认值为 code_review/<feature>/。
• command：review、synthesize、fix 或 verify。
• model：审查文件对应的模型或 Agent 名称，例如 codex、opencode、cursor、claude 或 gemini。
• report_language：默认值为 auto，即遵循用户提示的语言。也可指定 en、zh-CN 或 ja 等值。
• auto_fix_allowed：默认值为 false，除非用户明确要求修复。
• perspective：可选的审查重点，例如正确性、安全性、可维护性、测试或用户体验。
• test_command：可选的验证命令覆盖项。

默认差异规则

如果用户未指定目标或基准，则按以下顺序推断审查范围：

1. 如果工作树或暂存区有未提交的更改，则审查未提交的差异。
   • 检查未暂存和已暂存的更改。
   • 将其视为 target: working tree。
   • 除非需要额外上下文，否则无需指定基准分支。
2. 如果没有未提交的更改，则审查当前 HEAD 相对于 main 的差异。
   • 在支持的情况下，优先使用 main...HEAD 这样的合并基准比较。
   • 如果不存在 main，则尝试 master...HEAD。
3. 如果 main 和 master 都不存在，则在可用时检查分支跟踪元数据或 PR 元数据。
4. 只有在无法推断出合理的比较引用时，才询问用户 base。

用户明确提供的 PR、分支、提交范围或基准引用始终优先于这些默认规则。

必需的初始检查

在生成产物或修改代码之前，检查：

• 仓库状态和未提交的更改；
• 相对于所选基准的目标差异；
• 现有的 code_review/ 功能文件夹和审查产物；
• code_review/ 是否列于 .gitignore；
• 包、构建和测试配置；
• 项目中针对测试、lint、类型检查或 CI 的具体说明。

切勿还原与任务无关的用户更改。如果 code_review/ 未被忽略，建议将其添加到 .gitignore，但除非用户提出要求，否则不要编辑 .gitignore。

工件布局

按功能对每个工作流分组：

code_review/<feature>/
  <model>.md
  <model>-<perspective>.md
  summary.md
  fix-plan.md
  verify.md
  status.md

规则：

• 一次模型审查应恰好生成一个审查文件。
• 审查文件名应以模型或 Agent 名称开头，例如 codex.md、opencode.md、cursor.md、claude.md。
• 如果同一模型采用多个视角运行，请追加简短的视角后缀，例如 codex-security.md。
• 默认不包含时间戳。使用稳定的名称，便于快速浏览文件夹。
• 只有在明确要求保留多个历史运行结果时才使用时间戳。

命令输出边界：

• review：创建或覆盖且仅创建或覆盖一个模型审查文件，例如 codex.md。不要创建 summary.md、fix-plan.md、verify.md 或 status.md。
• synthesize：读取模型审查文件并创建或覆盖 summary.md。不要创建 status.md。
• fix：读取 summary.md 中已勾选的条目，创建或更新 fix-plan.md，并在代码更改和测试后创建或更新 status.md。
• verify：创建或更新 verify.md，并使用验证证据更新 status.md。

除非用户明确要求保留带日期的历史运行结果，否则不要创建 STATUS_20260529.md、REVIEW_SUMMARY_20260529.md 或 CODE_REVIEW_codex_20260529.md 等旧式带时间戳的文件名。

除非仓库已有更适用的本地规范，否则请使用 assets/templates/ 中的模板。

审查收集

在 review 命令中，为当前模型或 Agent 创建单个文件。如果用户未提供 model，且主机信息足以明确推断模型，则据此推断；否则使用清晰的名称，例如 codex。

对于多模型工作流，每个模型都应单独运行 review，并写入同一个 feature_dir。适用时可采用不同视角：

• 正确性和边缘情况；
• 安全性和数据安全；
• 测试和回归风险；
• 可维护性和架构；
• 相关时的产品或用户体验行为。

每项发现都必须包含严重程度、证据、受影响的文件、风险以及具体的建议修复方案。除非模糊的风格偏好会影响可维护性或面向用户的行为，否则应避免提出此类偏好。

Synthesize 命令

在 synthesize 命令中，从一个 feature_dir 读取审查文件并生成 summary.md：

• 默认选择文件夹中的所有模型审查文件；
• 排除 summary.md、fix-plan.md、verify.md 和 status.md；
• 合并重复发现；
• 保留有意义的分歧；
• 记录审查者达成一致的人数；
• 包含建议的测试；
• 使用复选框供人工批准修复。

复选框语义固定：

• 未勾选：未批准修复；
• 已勾选：已批准修复。

不要趁机修复未勾选的问题。

Fix 规则

在 fix 命令中：

1. 从所选 feature_dir 读取 summary.md。
2. 仅选择状态允许修复且已勾选的条目。
3. 确认修复范围，除非用户已明确批准。
4. 创建或更新 fix-plan.md。
5. 仅修改所选条目所需的文件。
6. 运行测试。
7. 更新 status.md，并在适当时更新摘要中的状态字段。

如果已勾选的条目暴露出更大的问题，应停止并在扩大范围前询问。

测试规则

修复后必须进行测试，除非无法执行。

按以下顺序进行验证：

1. 如果能找到与修改行为最相关的测试，先运行范围最小的测试。
2. 运行与修改文件相关的类型检查、lint 或构建检查。
3. 如果能找到且范围合理，运行更广泛的项目回归命令。

如果无法运行测试，请记录：

• 状态枚举值 test_blocked；
• 本应运行的命令；
• 阻塞原因；
• 残余风险。

如果测试失败，不要声称该条目已修复或已验证。将受影响条目标记为 verification_failed 或 partially_fixed，记录失败的命令，并概述失败情况。

验证规则

在 verify 命令中：

• 尽可能从独立于修复者的视角进行验证；
• 检查每个选定的问题是否确实已解决；
• 重新运行测试或检查测试证据；
• 查找修复导致的回归；
• 只有证据支持时才更新状态。

验证需要提供通过测试的证据，或清晰说明 test_blocked 的原因。

语言策略

技能说明、模板字段名称和机器可读状态枚举均使用英语。

生成的报告文本应使用 report_language：

• auto：遵循用户提示所用的语言；
• 明确指定语言值：使用该语言撰写文本；
• 即使在本地化报告中，状态枚举仍使用英语。

状态显示标签可以本地化。

状态枚举

使用以下确切的机器可读状态值：

• open
• approved_for_fix
• fixed
• partially_fixed
• wont_fix
• risk_accepted
• verified
• verification_failed
• test_blocked

每个状态条目都应包含：

• status：上述枚举之一；
• status_label：本地化的人类可读标签，例如 Fixed ✅ 或 已修复 ✅。

完成标准

仅当满足以下条件时，Review Forge 工作流才算完成：

• 审查产物位于 feature_dir 下；
• 只有已检查的项目才标记为已修复；
• 修复后已记录测试证据或 test_blocked 原因；
• 验证状态没有夸大；
• 流程产物与产品代码保持隔离。