Back to Details

requesting-code-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Requesting Code Review

发起代码评审

Dispatch code-reviewer subagent to catch issues before they cascade.
Core principle: Review early, review often.
调度代码评审子Agent，在问题扩散前及时发现。
核心原则： 尽早评审，频繁评审。

When to Request Review

何时发起评审

Mandatory:
  • After each task in subagent-driven development
  • After completing major feature
  • Before merge to main
Optional but valuable:
  • When stuck (fresh perspective)
  • Before refactoring (baseline check)
  • After fixing complex bug
强制场景：
  • 子Agent驱动开发中，完成每个任务后
  • 完成重大功能开发后
  • 合并至main分支前
可选但推荐场景：
  • 遇到瓶颈时（获取新视角）
  • 重构前（基线检查）
  • 修复复杂Bug后

How to Request

如何发起评审

1. Get git SHAs:
bash
BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
HEAD_SHA=$(git rev-parse HEAD)
2. Dispatch code-reviewer subagent:
Use Task tool with code-reviewer type, fill template at 
code-reviewer.md
Placeholders:
  • {WHAT_WAS_IMPLEMENTED}
    - What you just built
  • {PLAN_OR_REQUIREMENTS}
    - What it should do
  • {BASE_SHA}
    - Starting commit
  • {HEAD_SHA}
    - Ending commit
  • {DESCRIPTION}
    - Brief summary
3. Act on feedback:
  • Fix Critical issues immediately
  • Fix Important issues before proceeding
  • Note Minor issues for later
  • Push back if reviewer is wrong (with reasoning)
1. 获取Git SHA值：
bash
BASE_SHA=$(git rev-parse HEAD~1)  # 或 origin/main
HEAD_SHA=$(git rev-parse HEAD)
2. 调度代码评审子Agent：
使用Task工具，选择code-reviewer类型，填写
code-reviewer.md
中的模板
占位符说明：
  • {WHAT_WAS_IMPLEMENTED}
    - 你刚开发完成的内容
  • {PLAN_OR_REQUIREMENTS}
    - 功能预期需求
  • {BASE_SHA}
    - 起始提交版本
  • {HEAD_SHA}
    - 结束提交版本
  • {DESCRIPTION}
    - 简要说明
3. 处理评审反馈：
  • 立即修复Critical（严重）问题
  • 推进前修复Important（重要）问题
  • Minor（次要）问题可记录后后续处理
  • 若评审意见有误，可附带理由提出异议

Example

示例

[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 subagent]
  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

[Subagent 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]
[刚完成任务2：添加验证功能]

你：在推进前先发起代码评审。

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

[调度代码评审子Agent]
  WHAT_WAS_IMPLEMENTED: 对话索引的验证与修复功能
  PLAN_OR_REQUIREMENTS: docs/plans/deployment-plan.md中的任务2
  BASE_SHA: a7981ec
  HEAD_SHA: 3df7661
  DESCRIPTION: 新增verifyIndex()和repairIndex()函数，支持4类问题检测

[子Agent返回结果]:
  优势：架构清晰，包含真实测试用例
  问题：
    重要：缺少进度指示器
    次要：报告间隔使用了魔法数字(100)
  评估：可推进后续开发

你：[修复进度指示器]
[继续执行任务3]

Task Tool Template

Task工具模板

javascript
Task({
  task_id: 'task-1',
  subagent_type: 'general-purpose',
  model: 'sonnet',
  description: 'Code review for {DESCRIPTION}',
  prompt: `You are the CODE-REVIEWER agent.
javascript
Task({
  task_id: 'task-1',
  subagent_type: 'general-purpose',
  model: 'sonnet',
  description: 'Code review for {DESCRIPTION}',
  prompt: `You are the CODE-REVIEWER agent.

Instructions

Instructions

  1. Read your agent definition: .claude/agents/specialized/code-reviewer.md
  2. Read memory: .claude/context/memory/learnings.md
  1. Read your agent definition: .claude/agents/specialized/code-reviewer.md
  2. Read memory: .claude/context/memory/learnings.md

Review Request

Review Request

What Was Implemented

What Was Implemented

{WHAT_WAS_IMPLEMENTED}
{WHAT_WAS_IMPLEMENTED}

Requirements/Plan

Requirements/Plan

{PLAN_OR_REQUIREMENTS}
{PLAN_OR_REQUIREMENTS}

Git Range to Review

Git Range to Review

Base: {BASE_SHA} Head: {HEAD_SHA}
Run these commands to see the changes: ```bash git diff --stat {BASE_SHA}..{HEAD_SHA} git diff {BASE_SHA}..{HEAD_SHA} ```
Base: {BASE_SHA} Head: {HEAD_SHA}
Run these commands to see the changes: ```bash git diff --stat {BASE_SHA}..{HEAD_SHA} git diff {BASE_SHA}..{HEAD_SHA} ```

Memory Protocol

Memory Protocol

Record findings to .claude/context/memory/learnings.md when done. `, });
undefined
Record findings to .claude/context/memory/learnings.md when done. `, });
undefined

Integration with Workflows

工作流集成

Subagent-Driven Development:
  • Review after EACH task
  • Catch issues before they compound
  • Fix before moving to next task
Executing Plans:
  • Review after each batch (3 tasks)
  • Get feedback, apply, continue
Ad-Hoc Development:
  • Review before merge
  • Review when stuck
子Agent驱动开发：
  • 完成每个任务后发起评审
  • 在问题复杂化前及时发现
  • 修复后再推进下一个任务
计划执行：
  • 每完成3个任务为一批次后发起评审
  • 获取反馈并修复，再继续推进
临时开发：
  • 合并前发起评审
  • 遇到瓶颈时发起评审

Red Flags

注意事项

Never:
  • Skip review because "it's simple"
  • Ignore Critical issues
  • Proceed with unfixed Important issues
  • Argue with valid technical feedback
If reviewer wrong:
  • Push back with technical reasoning
  • Show code/tests that prove it works
  • Request clarification
See template at: requesting-code-review/code-reviewer.md
绝对禁止：
  • 因“改动简单”跳过评审
  • 忽略Critical（严重）问题
  • 未修复Important（重要）问题就推进
  • 对合理的技术反馈进行无意义争论
若评审意见有误：
  • 附带技术依据提出异议
  • 展示可证明功能正常的代码/测试用例
  • 请求进一步澄清
模板地址：requesting-code-review/code-reviewer.md

Iron Laws

铁则

  1. ALWAYS capture BASE_SHA and HEAD_SHA before dispatching a review — without the exact commit range, the reviewer cannot produce accurate diff analysis.
  2. NEVER skip code review because a change "seems simple" — small changes introduce the same classes of bugs as large ones; the author cannot see their own blind spots.
  3. ALWAYS fix Critical issues before proceeding to the next task — unfixed critical issues compound and become harder to isolate as more code is layered on top.
  4. NEVER argue with technically correct reviewer feedback — push back only when you have codebase evidence showing the reviewer lacks context or is factually wrong.
  5. ALWAYS request review at every mandatory checkpoint (after each subagent task, after major features, before merge) — review requested too late cannot prevent compounding errors.
  1. 务必在调度评审前获取BASE_SHA和HEAD_SHA——没有准确的提交范围，评审者无法生成精准的差异分析。
  2. 绝对不要因改动“看似简单”跳过代码评审——小改动和大改动会引入同类Bug；开发者无法发现自身的盲区。
  3. 务必在推进下一个任务前修复所有Critical（严重）问题——未修复的严重问题会不断复杂化，后续叠加代码后更难定位。
  4. 绝对不要对技术上正确的评审反馈进行争论——仅当你有代码库证据证明评审者缺乏上下文或事实错误时，才可提出异议。
  5. 务必在所有强制检查点发起评审（每个子Agent任务完成后、重大功能完成后、合并前）——过晚发起的评审无法阻止问题复杂化。

Anti-Patterns

反模式

Anti-PatternWhy It FailsCorrect Approach
Skipping review for "small" changesSmall changes introduce the same classes of bugs as large ones; "simple" is subjective and unreliableRequest review at every mandatory checkpoint regardless of perceived complexity
Dispatching reviewer without git SHAsReviewer cannot produce an accurate diff without a commit range; the review is inaccurate or incompleteCapture BASE_SHA and HEAD_SHA before every review dispatch
Proceeding past Critical issuesCritical issues compound; later tasks build on broken foundations that are expensive to fix retroactivelyFix all Critical issues before advancing to the next task
Treating reviewer feedback as optionalOptional review degrades code quality over time and compounds technical debt that can't be tracedFollow severity escalation: Critical → fix now, Important → fix before next task, Minor → note for later
Requesting review after batches of tasks instead of after each taskErrors from Task 1 contaminate Tasks 2–N; reviewers cannot isolate which task introduced which issueReview after each individual task before starting the next one
反模式失败原因正确做法
因“改动小”跳过评审小改动和大改动会引入同类Bug；“简单”是主观且不可靠的判断无论改动复杂度如何，都要在所有强制检查点发起评审
未携带Git SHA值就调度评审者没有提交范围，评审者无法生成准确的差异分析；评审结果不准确或不完整每次调度评审前都要获取BASE_SHA和HEAD_SHA
未修复Critical（严重）问题就推进严重问题会不断复杂化；后续任务基于错误基础开发，事后修复成本极高推进下一个任务前修复所有Critical（严重）问题
将评审反馈视为可选随意对待评审会逐渐降低代码质量，累积无法追溯的技术债务按严重程度处理：Critical→立即修复，Important→下任务前修复，Minor→记录后续处理
批量完成多个任务后才发起评审任务1的错误会影响任务2至N；评审者无法定位具体哪个任务引入了问题完成每个任务后都发起评审，再开始下一个任务

Memory Protocol (MANDATORY)

内存协议（强制）

Before starting: Read 
.claude/context/memory/learnings.md
After completing:
  • New pattern -> 
    .claude/context/memory/learnings.md
  • Issue found -> 
    .claude/context/memory/issues.md
  • Decision made -> 
    .claude/context/memory/decisions.md
ASSUME INTERRUPTION: If it's not in memory, it didn't happen.
开始前： 读取
.claude/context/memory/learnings.md
完成后：
  • 新模式记录至
    .claude/context/memory/learnings.md
  • 发现的问题记录至
    .claude/context/memory/issues.md
  • 做出的决策记录至
    .claude/context/memory/decisions.md
假设会被中断：未记录到内存中的内容，视为未发生。