Back to Details

code-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- ultrathink: Enable extended thinking for deep code analysis -->
<!-- ultrathink: Enable extended thinking for deep code analysis -->

Code Review

代码审查

YOUR ARGUMENTS: 
$ARGUMENTS
DO NOT ask the user for arguments. They are provided above. Parse them NOW and proceed with the review.
The argument is the path to the phase file to review (e.g., 
plans/voice-assistant/phase-01-database-schema.md
).
你的参数：
$ARGUMENTS
请勿向用户索要参数，参数已提供在上方。请立即解析并开始审查。
参数为待审查的阶段文件路径（例如：
plans/voice-assistant/phase-01-database-schema.md
）。

Recent Git Activity

近期Git活动

Recent commits (helps identify which files were modified for this phase):
!
git log --oneline -10 2>/dev/null || echo "(not a git repository)"
Recently changed files:
!
git diff --name-only HEAD~5 2>/dev/null || echo "(no recent changes)"
最近的提交记录（帮助确定此阶段修改的文件）：
!
git log --oneline -10 2>/dev/null || echo "(not a git repository)"
近期修改的文件：
!
git diff --name-only HEAD~5 2>/dev/null || echo "(no recent changes)"

Why This Review Exists

本次审查的目的

The user depends on this review to catch issues before they reach production. Self-review misses problems because the implementer has blind spots about their own code.
What skipping or rushing this review costs the user:
Missed CheckConsequence
Step verificationFeatures incomplete, user discovers gaps in production
Security issues (RLS, credentials)Data leakage between accounts, security incidents
Project pattern complianceInconsistent codebase, harder to maintain
Codebase pattern deviationCode works differently from every other feature, confusing to maintain
Persistent review recordNo audit trail, same mistakes repeated across future phases
This review creates accountability. Specific file:line references and concrete fixes give the user actionable feedback — not vague "looks good" responses that hide problems.
用户依赖本次审查在代码上线前发现问题。自我审查容易遗漏问题，因为开发者对自己的代码存在认知盲区。
跳过或仓促完成本次审查对用户的影响：
未检查项后果
步骤验证功能不完整，用户在生产环境中发现漏洞
安全问题（RLS、凭证）账户间数据泄露，引发安全事件
项目模式合规性代码库不一致，维护难度增加
代码库模式偏离代码行为与其他功能不一致，维护时易混淆
持久化审查记录无审计追踪，未来阶段重复出现相同错误
本次审查可明确责任。具体的文件:行号引用和具体修复方案为用户提供可执行的反馈——而非模糊的“看起来不错”这类无法解决问题的回复。

Codebase-Grounded Review

基于代码库的审查

This review is grounded in the actual codebase, not just a static checklist. Before flagging pattern violations, you read a reference implementation to confirm what the correct pattern looks like. This prevents:
  • Flagging things that are actually correct in this codebase
  • Missing violations because the checklist is stale
  • Giving generic advice instead of specific "line X should match how it's done in file Y"
本次审查完全基于实际代码库，而非静态检查清单。在标记模式违规前，你需要先阅读参考实现以确认正确的模式。这可以避免：
  • 将代码库中实际正确的代码标记为违规
  • 因检查清单过时而遗漏违规项
  • 给出通用建议而非具体的“第X行应与Y文件中的实现方式一致”

Output Location

输出位置

Code/implementation reviews go in the 
reviews/code/
subfolder:
  • Phase file: 
    plans/feature-name/phase-01-slug.md
  • Review file: 
    plans/feature-name/reviews/code/phase-01.md
Examples:
  • plans/250202-voice-assistant/reviews/code/phase-01.md
  • plans/250202-voice-assistant/reviews/code/phase-12.md
Create the 
reviews/code/
directory if it doesn't exist.
Note: Planning/template reviews go in 
reviews/planning/
instead — see 
/review-plan
skill.
代码/实现审查文件需放在
reviews/code/
子文件夹中：
  • 阶段文件：
    plans/feature-name/phase-01-slug.md
  • 审查文件：
    plans/feature-name/reviews/code/phase-01.md
示例：
  • plans/250202-voice-assistant/reviews/code/phase-01.md
  • plans/250202-voice-assistant/reviews/code/phase-12.md
如果
reviews/code/
目录不存在，请创建该目录。
注意： 规划/模板审查文件需放在
reviews/planning/
中——请查看
/review-plan
技能。

Delegation & Batching

任务委派与批量处理

For instructions on spawning multiple code review agents in batches, see delegation.md.
如需了解如何批量生成多个代码审查Agent，请查看delegation.md。

Task Tracking

任务跟踪

Tasks survive context compacts — skipping this check causes lost progress and repeated work.
Before starting work, run 
TaskList
to check if tasks already exist from a previous session or before a compact. If tasks exist:
  1. Read existing tasks with 
    TaskGet
    for each task ID
  2. Find the first task with status 
    pending
    or 
    in_progress
  3. Resume from that task — do NOT recreate the task list
If no tasks exist, create them after Step 2 (identifying files to review):
Example task list:
Task 1: Read phase document and extract requirements
Task 2: Identify files to review
Task 3: Find reference implementations
Task 4: Run completeness check
Task 5: Run code quality & codebase compliance check
Task 6: Write review file using template
Task 7: Auto-fix Critical and High issues
Task 8: Return summary with next steps
Mark each task 
in_progress
when starting and 
completed
when done.
任务会在上下文压缩后保留——跳过此检查会导致进度丢失和重复工作。
开始工作前，运行
TaskList
检查是否存在来自之前会话或压缩前的任务。如果存在任务：
  1. 使用
    TaskGet
    读取每个任务ID对应的现有任务
  2. 找到第一个状态为
    pending
    或
    in_progress
    的任务
  3. 从该任务继续——请勿重新创建任务列表
如果没有任务，请在步骤2（确定待审查文件）后创建任务：
任务列表示例：
任务1：阅读阶段文档并提取需求
任务2：确定待审查文件
任务3：查找参考实现
任务4：执行完整性检查
任务5：执行代码质量与代码库合规性检查
任务6：使用模板编写审查文件
任务7：自动修复严重和高优先级问题
任务8：返回包含后续步骤的总结
开始任务时标记为
in_progress
，完成后标记为
completed
。

Workflow

工作流程

Step 1: Read the Phase Document

步骤1：阅读阶段文档

Read the phase file at the path provided in the arguments above. Extract:
  • All Implementation Steps (Step 0 through Step N)
  • All Verifiable Acceptance Criteria
  • All Functional and Technical Requirements
读取参数中提供的阶段文件。提取：
  • 所有实现步骤（步骤0至步骤N）
  • 所有可验证的验收标准
  • 所有功能和技术需求

Step 2: Identify Files to Review

步骤2：确定待审查文件

The user should have provided a file list when invoking. If not, ask which files were modified in this phase. You cannot use git commands.
用户在调用时应已提供文件列表。如果未提供，请询问此阶段修改了哪些文件。你不能使用Git命令。

Step 3: Find Reference Implementations

步骤3：查找参考实现

Before reviewing code quality, read at least one reference file from the codebase. This grounds your review in actual patterns, not memory. Without this step, you risk flagging correct code as violations or missing actual deviations.
Classify the files under review and find a reference for each type:
File TypeHow to Find Reference
Server actionsGlob: 
app/home/[account]/**/*server-actions*.ts
— read one
Service filesGlob: 
app/home/[account]/**/*service*.ts
— read one
Zod schemasGlob: 
app/home/[account]/**/*.schema.ts
— read one
SQL migrationsGlob: 
supabase/migrations/*.sql
— read a recent one
React componentsGlob: 
app/home/[account]/**/_components/*.tsx
— read one
Page filesGlob: 
app/home/[account]/**/page.tsx
— read one
Test filesGlob: 
__tests__/**/*.test.ts
— read one
Read the reference file. This is your ground truth for:
  • Function signatures (e.g., Server Action auth pattern)
  • Import paths and sources
  • Naming conventions
  • File organization
  • Error handling patterns
Complete this step before Step 5. Flagging pattern violations without first confirming the correct pattern from a real file leads to false positives that waste the user's time.
在审查代码质量前，请至少阅读代码库中的一个参考文件。 这能让你的审查基于实际模式而非记忆。跳过此步骤可能会将正确的代码标记为违规，或遗漏实际的偏离项。
对待审查文件进行分类，并为每种类型查找参考文件：
文件类型查找参考文件的方式
Server actions通配符：
app/home/[account]/**/*server-actions*.ts
— 读取其中一个
服务文件通配符：
app/home/[account]/**/*service*.ts
— 读取其中一个
Zod schemas通配符：
app/home/[account]/**/*.schema.ts
— 读取其中一个
SQL迁移文件通配符：
supabase/migrations/*.sql
— 读取一个近期的文件
React组件通配符：
app/home/[account]/**/_components/*.tsx
— 读取其中一个
页面文件通配符：
app/home/[account]/**/page.tsx
— 读取其中一个
测试文件通配符：
__tests__/**/*.test.ts
— 读取其中一个
读取参考文件。 这是你的基准，用于确认：
  • 函数签名（例如Server Action的认证模式）
  • 导入路径和来源
  • 命名规范
  • 文件组织结构
  • 错误处理模式
请在步骤5之前完成此步骤。 在未从真实文件确认正确模式的情况下标记模式违规，会导致误报，浪费用户时间。

Step 4: Completeness Check

步骤4：完整性检查

Verify every section in the phase document was implemented. See checklist.md for detailed criteria.
验证阶段文档中的每个部分均已实现。详细标准请查看checklist.md。

Step 5: Code Quality & Codebase Compliance Check

步骤5：代码质量与代码库合规性检查

Review the files against project patterns, security requirements, AND the reference implementations from Step 3. See checklist.md for detailed criteria.
For each file under review:
  1. Compare its patterns against the reference from Step 3
  2. Check against the codebase compliance checklist in checklist.md
  3. Flag deviations with severity and specific file:line references
When flagging an issue, cite the reference: "Line 42 uses 
async (data) =>
but reference file 
claude-ai-server-actions.ts:65
shows 
async (data, user) =>
is required when 
auth: true
."
For React/Next.js Code: Load Performance Guidelines
If reviewing React components, Next.js pages, or frontend code, invoke:
/vercel-react-best-practices
This loads 57 performance rules. Check the code against CRITICAL and HIGH priority rules:
CRITICAL - Eliminating Waterfalls:
  • No sequential awaits for independent operations (use Promise.all)
  • Suspense boundaries for streaming content
  • Early promise initiation in API routes
CRITICAL - Bundle Optimization:
  • No barrel file imports (import directly from source)
  • Heavy components use next/dynamic
  • Third-party scripts deferred after hydration
HIGH - Server-Side Performance:
  • React.cache() for per-request deduplication
  • Minimal data serialization to client components
  • Parallel data fetching in server components
MEDIUM - Re-render Optimization:
  • Derived state computed during render, not useEffect
  • Memoization for expensive computations
  • useTransition for non-urgent updates
Flag violations in the appropriate priority section of the review.
对照项目模式、安全需求以及步骤3中的参考实现审查文件。详细标准请查看checklist.md。
对于每个待审查文件：
  1. 将其模式与步骤3中的参考文件进行比较
  2. 对照checklist.md中的代码库合规性检查清单进行检查
  3. 标记偏离项，并注明严重程度和具体的文件:行号引用
标记问题时，请引用参考文件： “第42行使用
async (data) =>
，但参考文件
claude-ai-server-actions.ts:65
显示，当
auth: true
时，必须使用
async (data, user) =>
。”
对于React/Next.js代码：加载性能指南
如果审查React组件、Next.js页面或前端代码，请调用：
/vercel-react-best-practices
这会加载57条性能规则。对照CRITICAL和HIGH优先级规则检查代码：
CRITICAL - 消除请求瀑布：
  • 独立操作不使用顺序await（使用Promise.all）
  • 流式内容使用Suspense边界
  • API路由中提前初始化Promise
CRITICAL - 包优化：
  • 不使用桶文件导入（直接从源导入）
  • 大型组件使用next/dynamic
  • 第三方脚本在 hydration 后延迟加载
HIGH - 服务端性能：
  • 使用React.cache()进行每请求去重
  • 最小化向客户端组件的数据序列化
  • 服务端组件中并行数据获取
MEDIUM - 重渲染优化：
  • 派生状态在渲染时计算，而非useEffect
  • 昂贵计算使用 memoization
  • 非紧急更新使用useTransition
在审查的相应优先级部分标记违规项。

Step 6: Read Output Template and Write Review File

步骤6：读取输出模板并编写审查文件

Read the output template BEFORE writing the review.
Reviews written without reading the template first produce inconsistent formats that the user cannot compare across phases. Read 
references/CODE-REVIEW-TEMPLATE.md
and follow the exact format specified.
The template defines the exact sections, table columns, and verdict format. Inventing custom formats, adding extra sections like "Positive Observations" or "Technical Excellence", or using emoji checkmarks breaks the user's ability to track review status consistently across phases.
Write to: 
{plan-folder}/reviews/code/phase-{NN}.md
在编写审查文件前，请先读取输出模板。
未读取模板就编写的审查文件格式不一致，用户无法在不同阶段间进行比较。请读取
references/CODE-REVIEW-TEMPLATE.md
并严格遵循指定格式。
模板定义了确切的章节、表格列和结论格式。自定义格式、添加额外章节（如“积极观察”或“技术卓越”）或使用表情符号复选框，会破坏用户在不同阶段间统一跟踪审查状态的能力。
写入路径： 
{plan-folder}/reviews/code/phase-{NN}.md

Step 6b: Validate Review Format

步骤6b：验证审查格式

After writing the review file, run the validation script to catch structural issues:
bash
python $CLAUDE_PROJECT_DIR/.claude/skills/code-review/scripts/validate_review.py {review-file-path}
If validation fails, fix the reported issues in the review file before proceeding. The script checks for missing sections, incorrect table formats, and forbidden patterns (like "Positive Observations" sections that aren't in the template).
编写完审查文件后，运行验证脚本以检查结构问题：
bash
python $CLAUDE_PROJECT_DIR/.claude/skills/code-review/scripts/validate_review.py {review-file-path}
如果验证失败，请在继续前修复审查文件中报告的问题。该脚本会检查缺失的章节、不正确的表格格式以及禁止的模式（如模板中没有的“积极观察”章节）。

Step 7: Auto-Fix Critical and High Issues

步骤7：自动修复严重和高优先级问题

If no Critical/High issues were found, skip to Step 8.
Default: FIX IT. Most review issues are straightforward pattern corrections. Auto-fix is the expected outcome, not the exception. A review that identifies problems but fixes nothing is only half the job.
Fix Critical and High issues directly in the source files:
  1. For each Critical/High issue: a. Read the source file at the file:line cited in the review b. Read the reference file that shows the correct pattern c. Apply the fix using Edit (for targeted changes) or Write (for new files)
  2. Examples of fixes to make (never defer these):
    • Wrong function signatures — fix to match the reference
    • Missing 
      'use client'
      or 
      'use server'
      directives
    • Wrong import paths or import ordering
    • Missing error handling where the reference shows a clear pattern
    • Missing 
      server-only
      imports in server-side files
    • Wrong TypeScript types (e.g., 
      any
      where a proper type exists)
    • Security issues: missing RLS checks, exposed credentials, missing auth
    • Naming/convention violations where the reference shows the correct pattern
  3. The ONLY reasons to defer to the main agent (use sparingly):
    • The fix would change the feature's business logic or user-facing behavior
    • The fix contradicts the phase's Decision Log or architectural approach
    • You genuinely cannot determine the correct fix even after reading references
  4. After fixing, re-read the file to verify the fix is correct and doesn't introduce new issues.
  5. Update the review file:
    • Append "(Auto-fixed)" to fixed items in the Issues tables
    • Fill in the "Fixes Applied" section (see template)
    • Update the Verdict to reflect only remaining unfixed issues
如果未发现严重/高优先级问题，请跳至步骤8。
默认操作：修复问题。 大多数审查问题都是简单的模式修正。自动修复是预期结果，而非例外。只发现问题但不修复的审查只完成了一半工作。
直接在源文件中修复严重和高优先级问题：
  1. 对于每个严重/高优先级问题： a. 读取审查中引用的文件:行号对应的源文件 b. 读取显示正确模式的参考文件 c. 使用Edit（针对目标修改）或Write（针对新文件）应用修复
  2. 可修复的问题示例（请勿推迟）：
    • 错误的函数签名——修改为与参考文件一致
    • 缺失
      'use client'
      或
      'use server'
      指令
    • 错误的导入路径或导入顺序
    • 参考文件中明确有模式但缺失错误处理
    • 服务端文件中缺失
      server-only
      导入
    • 错误的TypeScript类型（例如在应有正确类型的地方使用
      any
      ）
    • 安全问题：缺失RLS检查、凭证暴露、缺失认证
    • 参考文件中明确有正确模式但违反命名/规范
  3. 唯一可推迟给主Agent的情况（谨慎使用）：
    • 修复会改变功能的业务逻辑或用户可见行为
    • 修复与阶段的决策日志或架构方法相矛盾
    • 即使阅读参考文件后仍无法确定正确的修复方案
  4. 修复后，重新读取文件以验证修复正确且未引入新问题。
  5. 更新审查文件：
    • 在问题表格中的已修复项后添加“（已自动修复）”
    • 填写“已应用的修复”部分（请查看模板）
    • 更新结论以仅反映未修复的剩余问题

Step 8: Return Summary with Next Steps

步骤8：返回包含后续步骤的总结

After writing the review file, return:
  • Review file location
  • Verdict (Ready/Not Ready) — based on remaining unfixed issues only
  • Count of issues (total, auto-fixed, deferred)
  • Reference files used
  • Auto-fixed (count and brief list of what was fixed)
  • Deferred to main agent (issues not auto-fixed and why)
  • Next Steps for Medium/Low — present as improvement opportunities
Improvement mindset: When listing Medium/Low issues, frame them as concrete improvements worth doing now — not optional niceties. Phases are rarely revisited after completion, so "fix later" effectively means "never." The user prefers investing in quality now over speed.
Action directive for main agent: If there are deferred items or Medium/Low suggestions, end your summary with:
ACTION REQUIRED: [N] deferred items and [M] improvement suggestions need main agent attention.
Please review the items above and fix or discuss with the user before proceeding.
编写完审查文件后，返回：
  • 审查文件位置
  • 结论（通过/未通过）——仅基于未修复的剩余问题
  • 问题数量（总数、已自动修复、已推迟）
  • 使用的参考文件
  • 已自动修复（数量及修复内容的简要列表）
  • 推迟给主Agent（未自动修复的问题及原因）
  • 中/低优先级问题的后续步骤——作为改进机会呈现
改进思维： 列出中/低优先级问题时，应将其描述为当前值得实施的具体改进——而非可选的优化。阶段完成后很少会被重新审视，因此“以后修复”实际上意味着“永远不修复”。用户更倾向于现在投入时间提升质量而非追求速度。
主Agent的操作指令： 如果存在推迟项或中/低优先级建议，请在总结末尾添加：
ACTION REQUIRED: 有[N]个推迟项和[M]个改进建议需要主Agent关注。
请查看上述内容并在继续前修复或与用户讨论。

Troubleshooting

故障排除

Review produces false positives (flagging correct code)

审查产生误报（将正确代码标记为违规）

Cause: The review skipped Step 3 (reading reference implementations) and flagged code based on assumptions rather than actual codebase patterns.
Fix: Always read at least one reference file of each type before flagging issues. If the codebase uses a pattern that differs from generic best practices, the codebase wins.
原因： 审查跳过了步骤3（读取参考实现），基于假设而非实际代码库模式标记代码。
修复： 在标记问题前，务必至少读取每个类型的一个参考文件。如果代码库使用的模式与通用最佳实践不同，以代码库的模式为准。

Review is superficial ("looks good, no issues found")

审查过于表面（“看起来不错，未发现问题”）

Cause: The reviewer didn't read individual files at specific line numbers, relying on a surface-level scan instead of deep inspection.
Fix: For each file under review, read the full file and compare line-by-line against both the phase requirements and the reference implementation. Check every import path, function signature, and error handling pattern.
原因： 审查者未读取具体行号的单个文件，仅进行了表面扫描而非深入检查。
修复： 对于每个待审查文件，完整读取文件并逐行对照阶段需求和参考实现进行比较。检查每个导入路径、函数签名和错误处理模式。

Auto-fix introduces new issues

自动修复引入新问题

Cause: The fix was applied without re-reading the file to verify correctness, or the fix didn't account for surrounding context.
Fix: After every Edit, re-read the modified file to verify the fix is correct. Check that imports still resolve and that the change doesn't break adjacent code.
原因： 应用修复后未重新读取文件验证正确性，或修复未考虑周围上下文。
修复： 每次Edit后，重新读取修改后的文件以验证修复正确。检查导入是否仍能解析，且修改未破坏相邻代码。

Review format is inconsistent across phases

不同阶段的审查格式不一致

Cause: The reviewer didn't read 
references/CODE-REVIEW-TEMPLATE.md
before writing (Step 6). Custom formats break the user's ability to track review status.
Fix: Always read the template first and follow its exact structure. Do not add custom sections or change the table format.
原因： 审查者在编写前未读取
references/CODE-REVIEW-TEMPLATE.md
（步骤6）。自定义格式会破坏用户跟踪审查状态的能力。
修复： 务必先读取模板并严格遵循其确切结构。请勿添加自定义章节或修改表格格式。

Resuming After Context Compact

上下文压缩后恢复工作

If you notice context was compacted or you're unsure of current progress:
  1. Run 
    TaskList
    to see all tasks and their status
  2. Find the 
    in_progress
    task — that's where you were
  3. Run 
    TaskGet {id}
    on that task to read full details
  4. Continue from that task — don't restart from the beginning
Tasks persist across compacts. The task list is your source of truth for progress, not your memory.
Pattern for every work session:
TaskList → find in_progress or first pending → TaskGet → continue work → TaskUpdate (completed) → next task
如果发现上下文已被压缩或不确定当前进度：
  1. 运行
    TaskList
    查看所有任务及其状态
  2. 找到
    in_progress
    的任务——这是你之前的工作位置
  3. 对该任务运行
    TaskGet {id}
    以读取完整详情
  4. 从该任务继续——请勿从头开始
任务会在压缩后保留。任务列表是你进度的唯一真实来源，而非你的记忆。
每个工作会话的模式：
TaskList → 找到in_progress或第一个pending任务 → TaskGet → 继续工作 → TaskUpdate (completed) → 下一个任务

Constraints

约束条件

  • Write review files within the plan folder
  • When auto-fixing, you may also edit source files cited in the review
  • Read the phase file FIRST before reviewing code
  • Read at least one reference implementation before flagging pattern violations
  • Cite references when flagging codebase pattern issues (e.g., "reference: claude-ai-server-actions.ts:65")
  • Be specific with file paths and line numbers
  • Critical and High issues block phase completion (unless auto-fixed)
  • Auto-fix: Default is to fix. Only defer for genuine business logic changes or ADR contradictions
  • Auto-fix: "Needs verification" is not a valid excuse — use Glob/Grep/Read to verify, then fix
The user configured this review to be thorough because vague feedback ("looks good", "some issues") doesn't help fix problems. Specific file:line references, comparison to known-good reference code, and concrete fixes are what the user needs to take action.
  • 审查文件写入计划文件夹内
  • 自动修复时，你可以编辑审查中引用的源文件
  • 审查代码前务必先阅读阶段文件
  • 标记模式违规前，请至少读取一个参考实现
  • 标记代码库模式问题时，请引用参考文件（例如：“参考文件：claude-ai-server-actions.ts:65”）
  • 请提供具体的文件路径和行号
  • 严重和高优先级问题会阻止阶段完成（除非已自动修复）
  • 自动修复： 默认操作是修复。仅在确实需要更改业务逻辑或与ADR矛盾时才推迟
  • 自动修复： “需要验证”不是合理的借口——使用Glob/Grep/Read进行验证，然后修复
用户将本次审查配置为全面审查，因为模糊的反馈（“看起来不错”、“存在一些问题”）无助于解决问题。用户需要的是具体的文件:行号引用、与已知良好参考代码的对比以及具体的修复方案，以便采取行动。