Code Review

代码评审

Philosophy

评审理念

Code review maintains a healthy codebase while helping contributors succeed. The burden of proof is on the PR to demonstrate it adds value. Your job is to help it get there through actionable feedback.

Critical: A perfectly written PR that adds unwanted functionality must still be rejected. The code must advance the codebase in the intended direction. When rejecting, provide clear guidance on how to align with project goals.

Be friendly and welcoming while maintaining high standards. Call out what works well. When code needs improvement, be specific about why and how to fix it.

代码评审既能维护代码库的健康状态，也能帮助贡献者取得成功。PR需自行证明其能为代码库带来价值。你的职责是通过可落地的反馈，帮助PR达到要求。

关键原则：即便PR的代码编写完美，但如果添加了不必要的功能，仍需予以拒绝。代码必须符合代码库的既定发展方向。拒绝时，需清晰说明如何调整才能契合项目目标。

保持友好热情的态度，同时坚守高标准。要肯定PR中的可取之处。当代码需要改进时，需具体说明问题原因及修复方案。

What to Focus On

评审重点

Does this advance the codebase correctly?

代码变更是否符合代码库的发展方向？

Even perfect code for unwanted features should be rejected.

即便功能代码完美，但如果是不必要的功能，仍需拒绝。

API design and naming

API设计与命名

Identify confusing patterns or non-idiomatic code:

Parameter values that contradict defaults
Mutable default arguments
Unclear naming that will confuse future readers
Inconsistent patterns with the rest of the codebase

识别易混淆的模式或不符合惯例的代码：

与默认值矛盾的参数取值
可变默认参数
命名模糊，易误导后续维护者
与代码库其他部分的模式不一致

Specific improvements

具体改进建议

Provide actionable feedback, not generic observations.

提供可落地的反馈，而非泛泛而谈。

User ergonomics

用户易用性

Think about the API from a user's perspective. Is it intuitive? What's the learning curve?

从用户视角审视API：是否直观？学习成本如何？

For Agent Reviewers

针对Agent评审者的指南

Read the full context: Examine related files, tests, and documentation before reviewing
Check against established patterns: Look for consistency with codebase conventions
Verify functionality claims: Understand what the code actually does, not just what it claims
Consider edge cases: Think through error conditions and boundary scenarios

通读上下文：评审前需查看相关文件、测试用例及文档
对照既定模式：检查是否符合代码库的约定规范
验证功能声明：明确代码实际实现的功能，而非仅看PR描述
考虑边缘场景：思考错误情况与边界场景

What to Avoid

评审禁忌

Generic feedback without specifics
Hypothetical problems unlikely to occur
Nitpicking organizational choices without strong reason
Summarizing what the PR already describes
Star ratings or excessive emojis
Bikeshedding style preferences when functionality is correct
Requesting changes without suggesting solutions
Focusing on personal coding style over project conventions

无具体内容的泛泛反馈
提及不太可能出现的假设性问题
无充分理由的情况下对代码组织方式吹毛求疵
重复PR已描述的内容
星级评分或过度使用表情符号
当功能无误时，纠结于风格偏好
要求修改却不给出解决方案
优先关注个人编码风格而非项目约定

Tone

沟通语气

Acknowledge good decisions: "This API design is clean"
Be direct but respectful
Explain impact: "This will confuse users because..."
Remember: Someone else maintains this code forever

认可合理决策：「这个API设计很简洁」
直接但保持尊重
说明影响：「这会让用户产生困惑，因为……」
牢记：代码会由其他人长期维护

Decision Framework

决策框架

Before approving, ask:

Does this PR achieve its stated purpose?
Is that purpose aligned with where the codebase should go?
Would I be comfortable maintaining this code?
Have I actually understood what it does, not just what it claims?
Does this change introduce technical debt?

If something needs work, your review should help it get there through specific, actionable feedback. If it's solving the wrong problem, say so clearly.

批准PR前，需自问：

该PR是否达成了其宣称的目标？
该目标是否与代码库的发展方向一致？
我是否愿意长期维护这段代码？
我是否真正理解了代码的实际功能，而非仅看PR描述？
该变更是否会引入技术债务？

若PR需要改进，你的评审反馈应通过具体、可落地的建议帮助其完善。若PR解决的是错误的问题，需明确指出。

Comment Examples

评论示例

Good comments:

Instead of	Write
"Add more tests"	"The `handle_timeout` method needs tests for the edge case where timeout=0"
"This API is confusing"	"The parameter name `data` is ambiguous - consider `message_content` to match the MCP specification"
"This could be better"	"This approach works but creates a circular dependency. Consider moving the validation to `utils/validators.py` "

优质评论：

反面示例	正面示例
"添加更多测试"	" `handle_timeout` 方法需要针对timeout=0的边缘场景补充测试"
"这个API很混乱"	"参数名 `data` 表意模糊——建议改为 `message_content` 以匹配MCP规范"
"这可以做得更好"	"当前方案可行，但会产生循环依赖。建议将验证逻辑移至 `utils/validators.py` "

Checklist

检查清单

Before approving, verify:

All required development workflow steps completed (uv sync, prek, pytest)
Changes align with repository patterns and conventions
API changes are documented and backwards-compatible where possible
Error handling follows project patterns (specific exception types)
Tests cover new functionality and edge cases
The change advances the codebase in the intended direction

批准前，需验证：

已完成所有必要的开发流程步骤（uv sync, prek, pytest）
变更符合代码库的模式与约定
API变更已文档化，且尽可能保持向后兼容
错误处理遵循项目模式（使用特定异常类型）
测试覆盖了新功能及边缘场景
变更符合代码库的既定发展方向

reviewing-code

Original

Translation