code-review
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseWhen doing a code review, follow these rules.
进行代码审查时,请遵循以下规则。
Determining what to review
确定审查范围
Choose the review scope from the user's request:
- No target: The staged and unstaged diffs, plus untracked files and their contents.
- Commit: The commit metadata and patch.
- Branch or base ref: The merge-base, commits since that base, and the branch diff. If the branch is already merged, its historical base and head from pull-request metadata.
- Pull request URL or number: The pull-request context, base and head commits, commit list, and historical diff. For a merged pull request, include its historical iteration or merge metadata. Treat a bare number as a pull request only when the request or repository provider makes this clear.
If the requested target or provider metadata is unavailable, report that instead of choosing a different review scope.
根据用户请求选择审查范围:
- 无指定目标:已暂存和未暂存的差异(diff),以及未跟踪文件及其内容。
- 提交记录(Commit):提交元数据和补丁。
- 分支或基准引用:合并基准、自该基准以来的提交记录,以及分支差异。如果分支已合并,则使用拉取请求元数据中的历史基准和头部。
- 拉取请求(Pull request)URL或编号:拉取请求上下文、基准和头部提交记录、提交列表以及历史差异。对于已合并的拉取请求,需包含其历史迭代或合并元数据。仅当请求或仓库提供商明确说明时,才将纯数字视为拉取请求编号。
如果请求的目标或提供商元数据不可用,请告知用户,而非选择其他审查范围。
Identifying the spec source
确定需求来源
Look for the intended requirements in this order:
- A path, URL, issue or work-item ID, or requirements text supplied by the user.
- A specification or work item linked from the pull request.
- Issue references in commit messages, using the repository's configured issue-tracker workflow.
- Ask the user.
If a supplied source cannot be accessed, ask the user for its contents. If the user confirms that no specification exists, continue the review and state that no spec was available.
按以下顺序查找预期需求:
- 用户提供的路径、URL、问题或工作项ID,或需求文本。
- 拉取请求中链接的规范或工作项。
- 提交消息中的问题引用,需符合仓库配置的问题跟踪器工作流。
- 询问用户。
如果无法访问提供的来源,请向用户索要其内容。如果用户确认不存在规范,则继续审查并说明无可用规范。
Gathering Context
收集上下文信息
Diffs alone are not enough. After getting the diff, read the entire file(s) being modified to understand the full context. Code that looks wrong in isolation may be correct given surrounding logic—and vice versa.
- Use the diff to identify which files changed
- For worktree reviews, read each relevant untracked file completely
- Read the full file to understand existing patterns, control flow, and error handling
- Check for existing style guide or conventions files (CONVENTIONS.md, AGENTS.md, .editorconfig, etc.)
仅查看差异是不够的。 获取差异后,请阅读被修改的完整文件以理解全部上下文。孤立看似乎有问题的代码,结合周围逻辑可能是正确的——反之亦然。
- 通过差异确定哪些文件被修改
- 对于工作树审查,请完整阅读每个相关的未跟踪文件
- 阅读完整文件以了解现有模式、控制流和错误处理
- 检查是否存在现有的风格指南或约定文件(如CONVENTIONS.md、AGENTS.md、.editorconfig等)
What to Look For
审查要点
Bugs - Your primary focus.
- Logic errors, off-by-one mistakes, incorrect conditionals
- If-else guards: missing guards, incorrect branching, unreachable code paths
- Edge cases: null/empty/undefined inputs, error conditions, race conditions
- Security issues: injection, auth bypass, data exposure
- Broken error handling that swallows failures, throws unexpectedly or returns error types that are not caught.
Structure - Does the code fit the codebase?
- Does it follow existing patterns and conventions?
- Are there established abstractions it should use but doesn't?
- Excessive nesting that could be flattened with early returns or extraction
Performance - Only flag if obviously problematic.
- O(n²) on unbounded data, N+1 queries, blocking I/O on hot paths
Behavior Changes - If a behavioral change is introduced, raise it (especially if it's possibly unintentional).
Spec compliance - When a spec is available, flag missing or incorrectly implemented requirements. Cite the relevant requirement.
漏洞(Bugs) - 你的首要关注点。
- 逻辑错误、差一错误、条件判断错误
- If-else防护:缺失防护、分支错误、不可达代码路径
- 边缘情况:空值/空输入/未定义输入、错误条件、竞争条件
- 安全问题:注入攻击、权限绕过、数据泄露
- 错误处理失效:吞掉错误、意外抛出异常或返回未被捕获的错误类型
结构(Structure) - 代码是否适配代码库?
- 是否遵循现有模式和约定?
- 是否存在应使用但未使用的既定抽象?
- 过度嵌套可通过提前返回或提取代码来简化
性能(Performance) - 仅标记明显有问题的情况。
- 无界数据上的O(n²)算法、N+1查询、热点路径上的阻塞I/O
行为变更(Behavior Changes) - 如果引入了行为变更,需指出(尤其是可能非故意的变更)。
规范合规性(Spec compliance) - 当有规范可用时,标记缺失或错误实现的需求,并引用相关要求。
Before You Flag Something
标记问题前的注意事项
Be certain. If you're going to call something a bug, you need to be confident it actually is one.
- Only review the changes - do not review pre-existing code that wasn't modified
- Don't flag something as a bug if you're unsure - investigate first
- Don't invent hypothetical problems - if an edge case matters, explain the realistic scenario where it breaks
- If you need more context to be sure, use the tools below to get it
Don't be a zealot about style. When checking code against conventions:
- Verify the code is actually in violation. Don't complain about else statements if early returns are already being used correctly.
- Some "violations" are acceptable when they're the simplest option. A statement is fine if the alternative is convoluted.
let - Excessive nesting is a legitimate concern regardless of other style choices.
- Don't flag style preferences as issues unless they clearly violate established project conventions.
确保确定。 如果你要将某内容标记为漏洞,需确信它确实是漏洞。
- 仅审查变更部分 - 不要审查未修改的既有代码
- 若不确定,不要标记为漏洞 - 先调查
- 不要凭空假设问题 - 如果边缘情况重要,请解释其实际会导致故障的场景
- 如果需要更多上下文才能确定,请使用以下工具获取信息
不要对风格过于偏执。 检查代码是否符合约定时:
- 确认代码确实违反了约定。如果已正确使用提前返回,不要抱怨else语句。
- 某些“违反”在是最简单解决方案时是可接受的。如果替代方案很复杂,使用语句是没问题的。
let - 无论其他风格选择如何,过度嵌套都是合理的关注点。
- 除非明确违反既定项目约定,否则不要将风格偏好标记为问题。
Tools
工具
Use these to inform your review:
- Codebase context - Find how existing code handles similar problems. Check patterns, conventions, and prior art before claiming something doesn't fit.
- Library/API context - Use relevant available skills or approved documentation to verify library/API usage before flagging it as wrong.
- Web Search - Research best practices if you're unsure about a pattern.
If you're uncertain about something and can't verify it with these tools, say "I'm not sure about X" rather than flagging it as a definite issue.
使用以下工具辅助审查:
- 代码库上下文 - 了解现有代码如何处理类似问题。在声称某内容不适配前,先检查模式、约定和已有实现。
- 库/API上下文 - 在标记库/API使用错误前,使用相关可用技能或已批准文档进行验证。
- 网络搜索 - 若不确定某模式,研究最佳实践。
如果对某内容不确定且无法通过这些工具验证,请说明“我不确定X的情况”,而非将其标记为明确问题。
Output
输出要求
- If there is a bug, be direct and clear about why it is a bug.
- Clearly communicate severity of issues. Do not overstate severity.
- Critiques should clearly and explicitly communicate the scenarios, environments, or inputs that are necessary for the bug to arise. The comment should immediately indicate that the issue's severity depends on these factors.
- Your tone should be matter-of-fact and not accusatory or overly positive. It should read as a helpful AI assistant suggestion without sounding too much like a human reviewer.
- Write so the reader can quickly understand the issue without reading too closely.
- AVOID flattery, do not give any comments that are not helpful to the reader. Avoid phrasing like "Great job ...", "Thanks for ...".
- Cite the affected file and line for each finding.
- 如果存在漏洞,请直接清晰地说明其为何是漏洞。
- 明确传达问题的严重程度。不要夸大严重程度。
- 批评应清晰明确地说明漏洞出现所需的场景、环境或输入。评论应立即指出问题的严重程度取决于这些因素。
- 语气应客观中立,不要指责或过于积极。应作为有用的AI助手建议,不要过于像人类审查者的语气。
- 撰写内容时应让读者无需仔细阅读即可快速理解问题。
- 避免奉承,不要给出对读者无帮助的评论。避免使用“做得好……”“感谢……”之类的措辞。
- 为每个发现引用受影响的文件和行号。