requesting-code-review

请求代码审查

使用 task 工具调度 code-reviewer 子 Agent，在问题扩散之前发现问题。审查者会获得精心编写的评估上下文，而绝不会看到你会话的历史记录。这样审查者就能专注于工作成果，而不是你的思考过程，同时也能为你继续工作保留上下文。

核心原则： 尽早审查，频繁审查。

何时请求审查

必须：

• 在子 Agent 驱动的开发中完成每项任务后
• 完成重大功能后
• 合并到 main 之前
• 更改涉及安全相关代码时——不可信输入、身份验证/授权、机密、注入点、子进程/插件边界或新增依赖（调度 security-reviewer）

可选但很有价值：

• 遇到瓶颈时（获取全新视角）
• 重构之前（检查基线）
• 修复复杂错误后

如何请求

1. 获取 git SHA：

BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
HEAD_SHA=$(git rev-parse HEAD)

2. 使用 task 工具调度全局 Agent：code-reviewer、code-quality-reviewer 或 security-reviewer：

code-reviewer、code-quality-reviewer 和 security-reviewer Agent 已在全局注册，并配备了相应的审查清单。调用时，请提供已实现内容、计划参考和 git 差异范围等上下文。Agent 将使用 git diff {BASE_SHA}..{HEAD_SHA} 检查更改。

Task 工具提示词中应包含的上下文：

• 你刚完成的工作（简要概述）
• 它应该实现什么（计划或需求参考）
• 起始提交 SHA（BASE_SHA）
• 结束提交 SHA（HEAD_SHA）

3. 根据反馈采取行动：

• 立即修复严重问题
• 继续之前修复重要问题
• 将次要问题记录下来，留待以后处理
• 如果审查者有误，请说明理由并提出异议

示例

[Just completed Task 2: Add verification function]

You: Let me request code review before proceeding.

BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
HEAD_SHA=$(git rev-parse HEAD)

[Dispatch code-reviewer sub-agent using the `task` tool]
  WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
  PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
  BASE_SHA: a7981ec
  HEAD_SHA: 3df7661
  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types

[Sub-agent returns]:
  Strengths: Clean architecture, real tests
  Issues:
    Important: Missing progress indicators
    Minor: Magic number (100) for reporting interval
  Assessment: Ready to proceed

You: [Fix progress indicators]
[Continue to Task 3]

与工作流集成

子 Agent 驱动的开发：

• 每完成一项任务后都进行审查
• 在问题累积之前发现它们
• 修复问题后再继续下一项任务

执行计划：

• 每批任务（3 项）完成后进行审查
• 获取反馈、应用反馈，然后继续

临时开发：

• 合并前审查
• 遇到瓶颈时审查

选择审查者

Agent	适用时机	拒绝做什么
spec-reviewer	实现完成后立即审查——代码是否严格符合规范，不多不少？	评论风格或质量
code-quality-reviewer	在通过规范合规性审查后——分解、命名、错误处理、测试质量	重新争论范围
security-reviewer	更改涉及不可信输入、身份验证/授权、机密、注入点、子进程/插件边界或新增依赖时——通过规范和质量审查后	不报告缺少从输入到影响的可追踪路径的问题
code-reviewer	功能完成或合并前——全面检查更改是否达到生产就绪标准	—
reviewing-interface-quality（skill）	更改包含面向用户的 UI 时	—

顺序很重要。 先检查规范合规性，再检查代码质量，然后进行安全审查，最后进行生产就绪审查。在规范合规性审查之前进行质量审查，会浪费精力去润色可能并非所需的代码；在规范合规性审查之前进行安全审查，则可能会审计本就有意为之的错误行为。请参阅 subagent-driven-development。

编写派发提示词

审查者一开始没有任何上下文。你写下的内容就是他们了解的一切——绝不是你的会话历史。给审查者的提示词如果含糊，得到的审查结果也会含糊。

提示词按以下顺序包含：

1. 构建了什么——两句话
2. 应该实现什么——完整粘贴需求或计划任务文本，而不是引用文件
3. 差异范围——BASE_SHA 和 HEAD_SHA
4. 查看位置——发生变更的文件
5. 你已了解的信息——你做出的偏离及原因
6. 你希望得到什么——报告格式

粘贴需求文本。 让审查者去读 docs/plans/x.md 会多耗费一次工具调用，还可能导致他们读错任务。你已经有了需求文本。

不要告诉他们你的看法。 “我认为错误处理很完善”会让审查者倾向于认同。陈述事实，要求他们指出问题。

Review the implementation of Task 2 from the auth plan.

REQUIREMENT (verbatim from the plan):
  Add verifyIndex() and repairIndex() to src/index/verify.ts. verifyIndex()
  returns a list of issues across 4 types: orphaned, stale, duplicate,
  missing. repairIndex() fixes each type. Report progress every 100 items.

DIFF: git diff a7981ec..3df7661
FILES: src/index/verify.ts, src/index/types.ts, tests/index/verify.test.ts

KNOWN DEVIATION: used a WeakMap rather than the Map the plan specified,
so entries are collected with their request objects. Behavior identical.

Return: PASS or FAIL with file:line references for each finding.

处理反馈

必需的子技能： 在实施任何建议之前，先使用 receiving-code-review。审查者有时会出错，盲目实施错误的建议比不做审查更糟糕。

严重程度	操作
严重	先修复，再做其他事
重要	在下一个任务开始前修复
次要	记录下来；如果修复成本低就修，否则暂缓

然后再次审查。 发现问题的审查者并未批准修复。使用相同的上下文，并补充所做的变更，重新派发审查。跳过复审，就会让“已修复”的问题一直留到合并时。

危险信号

切勿：

• 因为“这很简单”就跳过审查
• 忽略严重问题
• 在重要问题未修复时继续推进
• 反驳合理的技术反馈
• 让审查者阅读计划文件，而不粘贴任务文本
• 在提示词中加入自己的评估（这会影响审查）
• 未经复审就认为修复已完成
• 审查尚未提交的工作——先提交，确保差异范围真实可靠

如果审查者有误：

• 给出技术理由进行反驳
• 提供能证明其有效的代码或测试
• 请求澄清

常见错误

派发时带入会话上下文。 审查者会继承你的假设，审查你的推理，而不是代码。

没有差异范围。 审查者会阅读整个文件，并对不属于此次变更的既有代码提出意见。

提交前审查。 没有稳定的差异范围，审查者看到的内容还可能是只保存了一半的状态。

用一位审查者同时审查规范和质量。 这是两个不同的问题，把它们合在一起，会导致范围问题得不到应有的关注。

把审查当作走形式。 如果每次审查都返回“已批准，没有问题”，要么是提示词影响了审查结果，要么是用错了审查者。