junior-engineer-review

初级工程师代码审查

使用此技能，审查生成的代码是否便于一位能力较强的新团队成员理解、修改、调试和解释。

将总体认知负担作为主要衡量标准。好的代码在当前文件中应一目了然，在更大的包结构中也合乎逻辑，并且不依赖作者未明说的意图。

审查原则

• 优先考虑可读性、可追溯性和安全修改，而不是巧妙的写法。
• 审查代码时，假设下一位维护者了解仓库背景，但不了解 Agent 的私有推理过程。
• 优先指出与具体代码位置相关的问题，而不是泛泛而谈风格。
• 除非主观偏好会实质影响理解、调试或修改安全性，否则不要因此阻止变更。
• 保留有益的简洁优雅，但应拒绝那些让代码更难解释的小众语言特性、压缩表达和巧妙流程。

审查流程

代码变更后，始终执行此审查，即使用户没有单独要求审查。进行代码变更时，将此审查作为解决问题的循环：

1. 使用下方检查清单审查变更的代码。
2. 如果发现问题，修复所有可执行且属于范围内的问题。
3. 修复后重新审查。
4. 持续进行，直至审查未发现未解决的问题，或总共完成 10 轮审查。
5. 如果进行到第 10 轮时仍有问题，停止修改代码，并报告尚未解决的问题、无法解决的原因，以及后续所需工作。

每轮审查都要：

1. 确认生成或变更的代码，以及它要支持的行为。
2. 从入口点到副作用，追踪主要执行路径。
3. 检查新团队成员是否无需先阅读无关目录，就能解释每个步骤。
4. 查找编排、验证、持久化、格式化或错误处理是否混杂在一起。
5. 根据实际问题的规模，评估所选抽象和依赖是否合适。
6. 审查测试能否说明行为并提升变更信心。
7. 仅报告会实质影响可读性、可维护性、调试或安全修改的问题。

注意事项

• 命名：优先使用无需注释即可说明意图的名称。指出含糊不清的名称、隐含领域假设的名称，或仅描述实现机制的名称。
• 函数：优先保持单一职责。指出混合编排、验证、持久化、格式化和呈现的函数，除非文件规模较小时这样更简单。
• 抽象：除非至少存在两种真实实现、明确的测试边界，或项目已有惯例，否则避免使用接口、工厂、策略、注册表或通用包装器。
• 文件：按领域或概念拆分，而不是按任意的技术形式拆分。指出那些增加跳转成本却未降低复杂度的小文件。
• 目录：优先采用直观的导航和面向包的分组。读者不应需要了解完整的目录树才能找到相关代码。
• 控制流：优先采用直白、易读的流程。指出那些会遮蔽执行路径或增加测试难度的巧妙链式调用、过度使用的三元表达式、嵌套回调和深层分支。
• 错误处理：在错误发生的操作附近处理错误。指出远离错误来源、过于笼统、被吞掉或缺少上下文的错误。
• 执行可追溯性：优先采用显式流程，而不是隐式魔法。指出那些会模糊执行过程的隐藏回调、动态分发、反射、全局注册或生命周期钩子。
• 测试：测试应说明行为并覆盖有价值的边界情况，而不应只验证实现机制。指出那些照搬私有结构、却遗漏关键路径的脆弱测试。
• 注释：注释应解释某件事为何必要，而不是复述代码内容。指出为弥补代码不清晰而添加的注释。
• 依赖：小问题应避免引入库。如果本地代码更简单、更清晰且风险更低，则指出新增依赖的问题。

输出

按严重程度排序列出发现的问题。对于每项发现，请包含：

• 位置：文件及行号（如有）。
• 问题：认知负担或可维护性方面的问题。
• 影响：这会如何影响新团队成员理解、修改、调试或解释代码。
• 建议的改进：更简单的改进方向；除非确有必要，否则不要大规模重写。

如果代码通过了合理性检查，请明确说明，并指出任何残留风险或测试缺口。

如果此技能在代码更改后运行，请注明最终循环次数，以及循环是因为所有问题都已解决而结束，还是因为达到 10 次循环的上限而结束。

保持务实、友善的语气。目的是让人更容易维护生成的代码，而不是批评无伤大雅的风格差异。