# 代码质量（Code Quality）

本文件定义代理对代码质量的最低要求与审查清单（Python）。

## 1. 总体要求

- 改动聚焦目标；避免“顺手重构”。
- API/行为变更要显式说明影响与迁移方式（尤其是脚本/CLI 输出与配置项）。
- 保持仓库现有约定：优先复用既有结构、命名与工具配置（见 `docs/python/`）。

## 2. 可读性

- 复杂逻辑拆分为具名函数/模块；避免超长函数。
- 尽量使用显式类型与数据结构表达意图（必要时补类型标注）。
- 注释解释“为什么”，避免注释重复代码表述。

## 3. 错误处理

- 失败必须可观测：返回码/异常/日志至少一种要明确。
- CLI/自动化脚本：遇到不可恢复错误应非零退出码。

## 4. Review 清单

- 是否引入了不必要的新依赖？
- 是否遵循 `pyproject.toml` 与 lint 配置？
- 是否对 I/O（文件/网络/数据库）失败路径做了处理？
- 是否需要补测试或示例？