impl-peer-review

实现同行评审

独立评审运行时会对实现差异进行压力测试。此技能仅在实现完成后，收到用户明确请求时才运行跨大模型评审；评审范围仅包括差异，以及用户指定的任何 --context 文件，与任何任务跟踪系统解耦。Compozy 是评审引擎：每一轮都是针对可配置运行时执行一次 compozy exec。评审者写入的发现文件是唯一事实来源——compozy exec 的标准输出／标准错误和事件日志仅视为运行证据。

随附文件

所有 scripts/<name> 或 references/<name> 路径均相对于此 SKILL.md 所在目录（<skill-dir>）解析。所有随附文件均为只读——可读取或运行，但切勿在评审过程中编辑。

询问用户

当某个步骤要求询问用户（要纳入哪些发现、是否再运行一轮）时，请使用运行时的交互式提问工具——即提出问题并暂停，直到用户回答的工具（例如 AskUserQuestion）。如果运行时没有此类工具，请将问题作为完整的助手消息发送并停止；仅在用户回复后再自行回答。

输入

所有输入均为可选项。默认值使常见用法为不带参数的 impl-peer-review。

• --files <p1,p2,...> — 将评审范围限定为指定路径，而非整个分支差异。
• --context <p1,p2,...> — 提供给评审者的额外上下文文件（规范、ADR、设计文档、RFC、README）。此技能不会假定这些文件存在。
• --base <git-ref> — 差异的基准引用。默认为 main。使用 --base HEAD~N 可缩小范围。
• --staged — 仅评审暂存的更改（git diff --staged），而非分支差异。
• --out <dir> — 各轮产物的输出目录。参见“输出目录”。
• --verify <cmd> — 验证命令（构建／测试），同时用作就绪门槛和修复后的门槛。若未提供，则根据 references/readiness-checks.md 自动检测；若无法确定，则询问用户。
• --ide <ide>（默认 claude）：评审运行时，传递给 compozy exec --ide。可接受的值与 compozy exec 一致：codex、claude、cursor-agent、droid、opencode、pi、gemini、copilot。若值无效，请列出可接受的值并询问用户选择——不要回退到 claude。
• --model <name>（默认 opus）：传递给 compozy exec --model。不要预先验证；让 compozy 报告不兼容问题（关于过时模型的响应，参见步骤 3）。
• --reasoning <effort>（默认 xhigh）：传递给 compozy exec --reasoning-effort。可接受的值：low、medium、high、xhigh。

输出目录

按以下顺序确定 <out>：

1. 若提供了 --out，则使用该值。
2. 否则，若仓库中存在与当前工作明确对应的 .compozy/tasks/<slug>/ 布局，则使用该任务的 qa/ 目录：.compozy/tasks/<slug>/qa/。
3. 否则，默认使用仓库根目录下的 .peer-reviews/<UTC-timestamp-YYYYMMDDTHHMMSSZ>/。

若目录不存在，则创建它。每件产物都使用 -roundN 进行版本标记；绝不覆盖之前的轮次，而是递增到下一轮。

发现产物

每轮仅有一个权威发现文件：<out>/impl-review-findings-roundN.md。评审者只写入该文件，不写入其他文件。若目标路径不存在、含义不明确、不可写或位于 <out> 之外，评审者应拒绝并停止——不得回退到标准输出。

发现文件格式——包括 frontmatter、章节标题和每项字段——由 references/impl-review-prompt.md 定义，并由 scripts/validate-findings.sh 强制执行。

流程

步骤 0：确认 Compozy 可用 确认 compozy 二进制文件位于 PATH 中（例如 command -v compozy）。如果缺失，则中止并用一行消息告知用户安装 Compozy；跨 LLM 独立性正是重点，因此必须要求安装，而不能回退到工具原生的子 Agent。本技能会直接调用 compozy exec，无需安装 --agent。

步骤 1：验证输入并确定范围

1. 确认用户刚刚完成（或暂停）实现阶段，并明确要求审查当前状态。不要在主动编辑期间进行审查。
2. 确定 diff 范围：
   • 如果提供了 --files，验证每个路径均存在，并将 diff 限定在这些路径内。
   • 如果提供了 --staged，则使用 git diff --staged。
   • 否则，运行 git diff <base>...HEAD --name-only（<base> 默认为 main）来计算变更文件集。如果 diff 为空，则中止并告知用户没有内容需要审查。
3. 确定 <out>（参见 Output Directory），如有需要则创建该目录。
4. 确定验证命令（使用 --verify，否则自动检测，否则询问用户）。
5. 停止。在运行审查前，完整阅读 references/readiness-checks.md。 验证所有 readiness 标记均通过；标记及其自动检测顺序见该文件。如果任何标记未通过，则报告未通过的标记并中止——对有问题或未完成的变更进行外部审查会浪费额度并产生干扰信息。
6. 列出已有的 <out>/impl-review-findings-round*.md 和 <out>/impl-review-summary-round*.md 文件，以确定下一个审查轮次编号。如果没有文件，则从 round1 开始。

步骤 2：编写审查提示词

1. 停止。撰写提示词前，请完整阅读 references/impl-review-prompt.md。 这是规范的可执行审查者提示词模板；请逐字替换其中的占位符，不要改写。组装后的提示词必须以审查者说明开头，而不是以介绍模板的 Markdown 包装内容开头。
2. 捕获差异内容：
   • 运行 git diff <base>...HEAD -- <changed-files>（如果使用 --staged，则运行 git diff --staged -- <changed-files>），并将原始补丁写入 <out>/impl-review-diff-roundN.patch。
   • 运行 git log --oneline <base>...HEAD -- <changed-files> 并捕获提交列表（如果使用 --staged，则为空字符串）。
3. 在 <out>/ 下定义本轮产物路径：impl-review-findings-roundN.md、 impl-review-events-roundN.jsonl（事件日志）、impl-review-result-roundN.err（标准错误）、 impl-review-status-before-roundN.txt、impl-review-status-after-roundN.txt，以及 impl-review-validation-error-roundN.md（仅在需要时）。
4. 查找现有项目规则文件，以填充 {project_rules}：根目录级别的 CLAUDE.md、 AGENTS.md、.cursor/rules/*、.cursorrules、CONTRIBUTING.md；差异涉及目录中的嵌套 CLAUDE.md/AGENTS.md；以及任何项目记忆/指令文档（例如 docs/_memory/、 常设指令、经验索引）。嵌套规则和记忆规则包含仅搜索根目录会遗漏的关键约束。
5. 替换提示词模板中的占位符：
   • {scope_summary} — 用一段话描述已实现的内容。根据用户的简述、提交消息，或在传入 --context 时根据关联的规范/PRD 提炼。
   • {context_paths} — 来自 --context 的仓库根目录相对路径，每行一个；如果没有则填写 none。如果所审查的差异实现了规范目录中的任务（例如 .compozy/tasks/<slug>/、 specs/<name>/、docs/rfcs/<name>/），即使用户未传入 --context，也要在此处包含该规范中承载契约的同级产物（参见“防护措施：契约一致性”）。
   • {project_rules} — 已发现规则文件的仓库根目录相对路径，每行一个；如果没有则填写 none。
   • {changed_files} — 仓库根目录相对路径，每行一个。
   • {diff_path} — 第 2 步中补丁文件的仓库根目录相对路径。
   • {commit_list} — 捕获的 git log --oneline 输出；如果使用 --staged，则填写 none。
   • {findings_path} — <out>/impl-review-findings-roundN.md 的准确绝对路径。
   • {round} — 数字形式的审查轮次 N。
6. 将组装好的提示词写入 <out>/impl-review-prompt-roundN.md。

步骤 3：执行跨 LLM 审查

1. 捕获运行前的状态快照：

   git status --short > <out>/impl-review-status-before-roundN.txt
   

2. 运行（替换已解析的 --ide/--model/--reasoning，默认值为 claude/opus/xhigh）：

   compozy exec --ide <ide> --model <model> --reasoning-effort <reasoning> --format json --prompt-file <out>/impl-review-prompt-roundN.md > <out>/impl-review-events-roundN.jsonl 2> <out>/impl-review-result-roundN.err
   

3. 捕获运行后的状态快照：

   git status --short > <out>/impl-review-status-after-roundN.txt
   

4. 如果命令以非零状态退出，必须明确报错，不得静默重试。如果标准错误中显示 The model 'X' does not exist，运行时可能设置了过时的名称：告知用户已配置的模型，并在重新运行前向用户确认；不要自行替换模型。

5. 命令退出后，必须确认目标发现文件存在。如果文件缺失，即使 compozy exec 以 0 退出，本轮仍无效——写入 impl-review-validation-error-roundN.md，并询问是否重新运行。

步骤 4：验证并总结发现

1. 运行随附的只读验证器：

   bash <skill-dir>/scripts/validate-findings.sh --kind implementation --round N --path <out>/impl-review-findings-roundN.md
   

2. 手动检查 findings 文件并验证语义契约：

   • 每条 finding 都有真实的文件路径和行号，或明确说明为何不适用；
   • blocker 包含与项目规则或架构约束相关的理由；
   • 不含 TBD、占位文本、虚构路径或仅输出到 stdout 的 finding；
   • 当 {context_paths} 中传入了规范契约产物时，findings 必须逐字段明确评估契约一致性（见 Guardrails：契约一致性）——没有契约一致性评估的 SHIP 判定属于无效轮次；
   • 对比前后状态快照，确认除预期的审查产物/日志路径外没有其他变化。

3. 如果验证失败，将失败的检查项、命令、退出状态和产物路径写入 <out>/impl-review-validation-error-roundN.md。不得将该轮总结为 SHIP。

4. 根据已验证的 findings 文件生成 <out>/impl-review-summary-roundN.md，包含：判定（SHIP / FIX_BEFORE_SHIP / REWORK）；每个 blocker 一行理由；风险列表；小问题列表；最可能受修复影响的文件；以及操作产物路径。

5. 向用户简要总结：判定、blocker/风险/小问题的数量、主要主题，以及本轮生成的产物路径。

6. 在步骤 5 前，不得修改源代码、测试、配置、文档或提交。

步骤 5：由用户决定是否修复

1. 询问用户要纳入哪些 findings：
   • A) 所有 blocker
   • B) 指定的 blocker/风险/小问题
   • C) 不做修改——仅保留审查记录
   • D) 先手动修改，再进行任何修复
2. 仅应用用户选择的 findings。
3. 应用任何代码更改后，重新运行已确定的验证命令。如果失败，应修复新出现的问题，或在宣布修复完成前将其反馈给用户。
4. 将修复决定记录在 <out>/impl-review-remediation-roundN.md 中，列出：已纳入的项目及新的提交/差异范围；延期项目；更改的文件；以及带时间戳的验证命令和结果。
5. 向用户说明已更改的内容和仍延期的事项。只有在用户明确指示时才提交或推送。

步骤 6：可选的后续轮次

1. 询问用户是否希望针对更新后的代码再进行一轮同行评审，还是维持当前状态。
2. 仅在用户明确要求时才运行后续轮次：从步骤 2 开始，针对新的差异重新审查，并在同一 <out> 目录中生成新的 roundN+1 产物集。

防护措施

契约一致性。 对于规范工作流差异，仅凭工程质量永远不能获得 SHIP。当差异实现了规范目录（.compozy/tasks/<slug>/、specs/<name>/、docs/rfcs/<name>/）中的任务时，审查者必须获得该规范中包含契约的配套产物——规范示例文档、输入/架构表、QA 样例、测试契约、一致性映射——并逐字段评估交付内容。{context_paths} 未包含这些产物的轮次无效；对任务文件的转述绝不能作为充分的契约来源。真实事故：由于每轮审查都未收到规范示例文档，某项交付内容与该文档相矛盾，却连续有七轮获得了 SHIP。

每轮只计一次。 compozy exec 是此技能唯一消耗外部审查额度的地方。每轮运行一次；仅当该轮明确无效且用户要求重跑时，才可再次运行。