code-review

Basic Machines 代码审查

在需要遵循 Basic Machines 的代码风格和架构判断标准，对仓库内代码进行常规审查时使用此技能。仅报告问题；除非用户要求修复特定问题，否则不要修改代码。

范围

根据以下内容审查当前差异或指定文件：

• 仓库的 AGENTS.md / CLAUDE.md
• docs/ENGINEERING_STYLE.md
• 已修改的代码路径和测试

仅应用当前仓库的指导。在 basic-memory 中，优先关注本地优先的文件／数据库／MCP 边界。在 basic-memory-cloud 中，优先关注租户／工作区隔离、云端 Worker 行为以及 web-v2 状态／运行时边界。

审查标准

仅报告具体且可证伪的风险：

• 认知负担： 此改动是否比解决问题所需的更难理解？
• 变更传播： 产品的一处改动是否会迫使不相关的多个层进行修改？
• 知识重复： 是否在多个地方编码了相同规则，导致其可能出现偏差？
• 意外复杂性： 此改动是否无必要地增加了抽象、回退方案或状态？
• 依赖方向： API／MCP／CLI、服务、仓库和 UI 存储是否遵循预期边界？
• 领域模型失真： 名称和类型是否仍符合产品概念，还是传输／存储细节泄漏到了领域模型中？
• 测试判定依据质量： 对于此改动声称要防止的 Bug 或回归，测试能否在问题出现时失败？

必须明确检查的项目规则

• 不要针对未知模型形状使用推测性的 getattr(obj, "attr", default)。
• 不要吞掉宽泛的异常，不要仅发出警告却让操作失败，也不要隐藏回退行为。
• 不要使用掩盖不明确类型关系的类型转换或 Any。
• 内部值／结果对象使用数据类；在验证／序列化边界使用 Pydantic。
• 只需要某项能力时，使用范围狭窄的 Protocol。
• 明确异步／资源的所有权、取消和清理。
• 对有风险的改动提供有意义的回归测试或验证。
• 注释应解释原因，而非描述内容。

报告格式

按严重程度排序，并以问题列表开头。每个问题都应包含：

严重程度	用途
high	可能导致正确性、安全性、数据丢失或租户／工作区隔离失败
medium	具体的可维护性或边界风险，可能导致未来出现缺陷
low	轻微的一致性问题、含糊的指导或仅供审查的清理项

severity | file:line | risk category | claim
Why: concrete behavior or code path that proves the risk.
Fix: smallest practical change, or "none obvious" if the risk needs product input.

如果没有发现问题，请明确说明，并指出仍存在哪些验证缺口。