review

Review

管理 PR 的完整审查迭代生命周期：轮询反馈、基于证据评估每条建议、实施修复、解决讨论串，并推动 CI/CD 全部通过。

你是一名同行工程师，负责评估建议，而不是照单全收的下属。审查者的评论是关于你代码的假设。你的职责是用证据判断哪些建议正确，并据此采取行动。

---

输入

输入	必填	默认值	说明
PR 编号	否	通过 gh pr view 从当前分支推断	要管理的拉取请求。如果未提供，则从当前分支检测。如果该分支没有 PR，则会报错并清楚说明。
仓库	否	通过 gh repo view / git remote 推断	owner/repo 格式。
测试命令	否	pnpm test --run && pnpm typecheck && pnpm lint	实施更改后要运行的命令。如果项目使用了不同的工具，可覆盖此项。
SPEC.md 路径	否	无	如果提供，则启用基于规范的审查评估（将建议与设计意图交叉核对）。

---

工作流

此技能分为两个阶段。完成阶段 1 后再进入阶段 2。

阶段 1：审查反馈循环

审查者反馈是主要信号。此阶段的 CI/CD 属于次要信号，按情况处理。

1. 确定 PR 并评估初始状态

确认 gh CLI 可用且已完成身份验证：

gh auth status

如果失败，请停止并告知用户 — 此技能需要 GitHub CLI。

如果未提供 PR 编号，则从当前分支检测：

# Infer PR number from current branch
gh pr view --json number -q '.number'

如果当前分支没有 PR，请停止并告知用户 — 此技能需要现有 PR 才能继续迭代。

然后，在采取行动前，确定当前已有的进展：

脚本路径解析： 以下所有 scripts/ 路径都相对于此技能的基础目录（加载时显示在技能标题中），而不是当前工作目录。调用前请解析完整路径。例如，如果技能基础目录为 ~/.claude/plugins/cache/.../skills/review，那么 scripts/fetch-pr-feedback.sh 表示 ~/.claude/plugins/cache/.../skills/review/scripts/fetch-pr-feedback.sh。如果找不到脚本，请改用 references/review-protocol.md 中等效的 gh api 命令。

# Check for unpushed local changes
git status
git log origin/HEAD..HEAD --oneline

# Check for existing review feedback (use full path to skill's scripts/ dir)
<skill-base>/scripts/fetch-pr-feedback.sh <pr-number>

初始状态	操作
本地更改尚未推送	推送更改；如有需要，更新 PR 描述，然后继续第 2 步。
已推送，正在等待审查反馈	跳过推送。直接进入第 3 步（评估反馈）。
已推送，尚无反馈	进入第 2 步（轮询）。

推送时： 如果实现发生了实质性变化，请更新 PR 正文。加载 /pr 技能来重写 PR 正文 — 它是相对于 origin/main 的 PR 范围的无状态快照，并非演变历史。并非每项小修复都需要编辑 PR 正文。

加载： references/review-protocol.md（章节：“PR 正文”）

2. 轮询评审反馈

等待约 6 分钟，然后查看评审者的反馈。同时顺便检查 CI/CD。

轮询时务必使用该技能的脚本——不要直接调用 gh pr checks 或 gh api。 这些脚本会处理退出代码、解析输出，并对结果分类（已通过／失败／待处理）。原始 gh pr checks 在检查待处理时会返回退出代码 8，看起来像是出错，但这是正常情况——脚本会处理这一点。

# Primary: fetch all review feedback (reviews, inline comments, discussion)
<skill-base>/scripts/fetch-pr-feedback.sh <pr-number> --reviews-only

# Secondary (opportunistic): check CI/CD status
<skill-base>/scripts/fetch-pr-feedback.sh <pr-number> --checks-only

# Or fetch everything at once:
<skill-base>/scripts/fetch-pr-feedback.sh <pr-number>

仅当脚本不可用（文件未找到）时，才回退到原始 gh pr checks。

决策逻辑：

当前情况	操作
已收到评审反馈，CI/CD 尚未完成	立即开始评估评审反馈。不要等待 CI/CD。
已收到评审反馈，CI/CD 也已完成	两者都进行评估。先处理评审反馈，再处理 CI/CD 失败。
尚无评审反馈，CI/CD 有失败项	等待评审反馈期间，评估并修复 CI/CD 失败项。
两者都尚未就绪	再等 3 分钟，然后重新检查。连续检查 3 次仍无结果后，继续处理其他工作，稍后再回来检查。

3. 评估评审者的反馈

加载： references/review-protocol.md（章节：“评估流程”）

完整的评估流程见参考文件。简要步骤如下：

1. 先调查再做决定——调查深度应与风险相称（针对 Bug 深入调查，针对风格问题可简要调查）。继续之前，先说明自己的信心水平。
2. 从多个维度评估：有效性、正确性、适用性、相关性、权衡、副作用和恰当性。
3. 做出决定——接受、拒绝或部分接受，并给出有证据支持的理由。
4. 回复并提供具体证据。回复后，解决行内评审讨论串——使用 fetch-pr-feedback.sh 输出中的 thread_id 调用 resolveReviewThread GraphQL mutation（参见 references/review-protocol.md）。
5. 通过适当的 GitHub 机制处理每种反馈，完成闭环（行内讨论串 → 回复后通过 GraphQL 解决；评审正文 → 顶层评论；讨论 → 回复）。

不要默认接受。 走最省事的路（直接采纳每条建议）会让代码质量变差，远不如经过审慎评估。同样，也不要默认拒绝——那会浪费有价值的见解。绝不要以“留待未来迭代”为由解决讨论串——你无权承诺未来的工作。对每条建议都要得出实质性结论：接受并实施，或基于证据拒绝。

4. 实施更改并测试

对于小型更改（少于 20 行、单个文件、修复明确）：

• 直接进行更改。

对于中型更改（20–100 行、2–3 个文件）：

• 直接进行更改，但推送前要运行完整测试。

对于大型／复杂更改（超过 100 行、涉及架构，或涉及许多文件）：

• 启动一个子 Agent，并提供清晰、具体的说明和完整上下文（参见 references/review-protocol.md 中的 "Subagent delegation template"）。
• 提交前审查子 Agent 的输出。你仍然是负责人。

推送前，请评估自己的更改：

• 正确性：更改是否确实修复了问题，或正确实现了建议？
• 清晰度：其他工程师能否不需要解释就理解这些更改？
• 代码库一致性：是否遵循现有模式和惯例？
• 适度性：修复是否与问题范围相匹配？是否做得过多或不足？

如果你不确定修复是否充分、正确地解决了审查者的顾虑，请在回复中说明，而不要声称已彻底解决。“我已通过执行 X 来处理这个问题——请确认这符合你的预期”比暗示问题已尘埃落定更有帮助。

任何更改后，至少要运行测试：

# Default — override via --test-cmd if your project uses different tooling
pnpm test --run
pnpm typecheck
pnpm lint

如果更改影响面向用户的行为，还应根据需要手动验证体验（API 调用、浏览器测试等）。修复审查者指出的 UI 问题，且 /browser 可用时，请加载它来验证修复：导航到受影响的页面，确认视觉变化，并检查是否有控制台错误（startConsoleCapture / getConsoleErrors）。截取屏幕截图作为证据——这有助于你在解决审查线程时提供有力佐证。

如果更改影响已记录的行为——无论是面向产品的文档（用户文档、API 参考、指南），还是内部文档（架构文档、README、运行手册）——都要在修复代码的同时更新相关文档文件（.md、.mdx 等）。文档应在整个审查过程中保持准确，而不是留待以后更新。

5. 推送并重复

推送更改，然后返回步骤 2。继续循环。

6. 当反馈超出修复并推送的范围时

并非所有审查反馈都只是小修复。如果审查者提出的问题需要大量新工作，请先分类再采取行动：

反馈范围	操作
现有代码中的错误修复或正确性问题	在审查循环中直接修复。
不在范围内的新功能（范围扩展）	暂停。咨询用户——这是产品／范围决策。
对现有实现进行架构性重做	评估适度性：证据是否足以证明这种复杂性合理？如果是，直接实施或通过子 Agent 实施；如果不是，说明理由并拒绝。
验收标准明确的大量新增工作	如果工作流编排器（例如 /ship）正在推动这次审查，就将任务交回编排器，进行正式的实施阶段；否则，咨询用户如何继续。

不要强行把大量返工塞进审查循环的修复并推送流程中。更大的更改需要先单独实施并测试，再并入审查流程。

7. 结束阶段 1

在解决所有审查反馈之前，不要结束。 解决审查线程后，再次轮询以确认没有出现新反馈：

<skill-base>/scripts/fetch-pr-feedback.sh <pr-number> --reviews-only

只有在以下条件全部满足时才能结束：

• 每个审查者反馈线程都已解决（通过代码更改采纳，或基于证据说明理由后拒绝）
• 你已推送最新更改
• 最后一次推送后，你已再次轮询并确认没有出现新的审查评论
• 没有通过推迟到“未来迭代”来解决的线程——每个线程都必须有实质性结论

如果推送后出现新反馈，请返回步骤 3 并进行评估。继续循环，直到满足上述条件。

如果相同反馈在 3 次迭代后仍反复出现，请暂停并咨询用户。

阶段 1 完成后，继续阶段 2。

---

阶段 2：CI/CD 处理

审查循环结束后，将重点转向监控和处理 CI/CD 流水线结果。

1. 监控流水线

<skill-base>/scripts/fetch-pr-feedback.sh <pr-number> --checks-only

2. 出现失败时立即处理

不要等到整个流水线结束。只要某次运行中的任何检查报告失败或已取消，就立即调查：

# Always use --compare-main — classification without main branch evidence is guesswork
<skill-base>/scripts/investigate-ci-failures.sh <pr-number> --compare-main

已取消的运行不算“通过”。 如果运行因 Runner 关闭、超时或资源耗尽而取消，结果就是未知——你无法确定代码是否通过。请重新触发并等待结果。

分类必须有证据。 只有在高度确信失败并非由此 PR 导致时，才能将其归类为预先存在的问题或基础设施问题。“看起来像基础设施问题”并不足够——必须通过证据核实（与主分支对比、重试结果、日志分析）。

对于每项失败或已取消的检查，先调查，再分类：

分类	所需证据	操作
由此 PR 的更改导致	失败发生在此 PR 修改的代码路径中；主分支通过了同一项检查	修复。
预先存在的问题（主分支也失败）	--compare-main 显示主分支上的同一工作流也因相同错误而失败	在 PR 评论中附上证据（主分支运行 ID、相同的错误）。除非修复很简单，否则不要修复。
不稳定测试（重试后通过）	同一项检查在未更改代码的情况下重新运行后通过	重新触发：gh run rerun <run-id> --repo <owner/repo>。等待重新运行完成。如果通过，在 PR 评论中说明。如果再次失败，则深入调查——连续失败两次不算“偶发”。
基础设施问题（超时、Runner 关闭、OIDC、资源问题）	日志显示基础设施层面的错误（而非测试／构建失败）；主分支也出现类似问题，或错误显然与代码无关	重新触发：gh run rerun <run-id> --repo <owner/repo>。等待重新运行完成。在 PR 评论中附上证据。
已取消（任何原因）	运行在完成前被取消	重新触发：gh run rerun <run-id> --repo <owner/repo>。等待结果。不要将已取消的运行归类为“通过”或“与 PR 无关”。

重新触发，不要只做记录。 对于不稳定、基础设施问题和已取消的失败，务必重新触发运行并等待结果。只记录失败而不重试，会留下未知结果——流水线并未通过，而且你没有证据证明它能够通过。

3. 修复、测试、推送并监控下一次运行

修复失败后：

1. 在本地运行测试，验证修复。
2. 推送。
3. 监控下一次 CI/CD 运行。
4. 重复以上步骤，直到流水线通过，或所有剩余失败都有证据证明是预先存在的问题／与 PR 无关，并已记录。

4. 退出阶段 2

仅当以下条件全部满足时才停止：

• CI/CD 流水线通过（或失败已附有证据地记录为预先存在的问题／与 PR 无关——与主分支对比、相同的错误、重试结果）
• 没有已取消或待处理的运行——每项检查都有明确的通过结果，或有附证据记录的失败
• 你对实现质量感到满意
• 任务列表中没有待处理事项

如果 CI 因同一问题连续失败 3 次，请暂停并咨询用户。

---

第二轮审查（可选）

完成阶段 1 和阶段 2 后，评估此 PR 是否需要进行第二轮完整审查。出现以下任一情况时，启动第二轮审查：

• PR 涉及身份验证、权限、数据修改或安全敏感代码
• 实现涉及重大的架构决策或权衡
• 在不同子系统中修改了多个文件
• 第一轮审查发现了实质性问题（而非小瑕疵）

如需启动第二轮审查，请发表评论请求对 PR 进行完整审查，然后返回阶段 1 第 2 步（轮询反馈）。沿用相同的评估和处理流程。

对于简单的 PR（单文件配置更改、简单的错误修复、外观调整），跳过第二轮审查。

---

完成

两个阶段均完成后（如果触发了第二轮审查，也包括第二轮审查），向用户（或调用此技能的技能）报告：

• 所有审查反馈讨论串均已解决（并总结已采纳／未采纳的意见）
• CI/CD 流水线状态
• 添加到 PR 描述的“Future considerations”部分的任何事项（如有）

重新调用指南（供调用方参考）： 如果此技能报告完成后，PR 又有新提交推送（来源不限，包括调用方修复、用户请求的更改或后续工作流阶段），则应重新启动审查周期。只有最近一次推送经过审查周期且所有讨论串均已解决，审查循环才算完成。

---

反模式

• 盲目接受所有审查者的建议，而不进行评估
• 盲目拒绝审查者的建议，而不进行调查
• 浅尝辄止地调查——不阅读相关代码就接受或拒绝建议
• 未先在本地运行测试就推送代码
• 未经用户确认就强制推送或执行破坏性 git 操作
• 作出最终决定后仍留下未解决的审查讨论串
• 抹平细微差别——明明诚实的评估应为“存在合理的权衡”，却强行二选一地接受或拒绝
• 无证据地断言——回复听起来信心十足，却与实际调查的深度不符
• 推给“未来迭代”——以“我们会在未来迭代中处理”或类似说法解决讨论串。你无权承诺未来的工作。应当接受并实施，或基于证据拒绝。
• 在讨论串未解决时退出——留下未处理的审查反馈讨论串或待办事项就结束审查循环
• 通过修复并推送的循环强行进行大幅返工，而不是升级处理

---

附录：参考资料和脚本索引

路径	使用时机	跳过的影响
references/review-protocol.md	评估审查者反馈（阶段 1，第 3 步）；PR 正文指南；委派给子 Agent	对审查作出机械、不加批判的回应；遗漏反馈中的细微差别
/pr 技能	编写或更新 PR 正文（阶段 1，第 1 步；任何实质性推送后）	PR 正文结构不一致；缺少章节；描述过时
scripts/fetch-pr-feedback.sh	获取审查反馈和 CI/CD 状态	Agent 使用错误或已弃用的 gh 命令，遗漏行内审查评论
scripts/investigate-ci-failures.sh	使用日志调查 CI/CD 故障（阶段 2）	Agent 难以查找运行 ID、获取日志或与 main 进行比较