python-best-practices

Python 微观代码审计计划

本计划将深入分析 Python 代码库，重点关注微观代码质量以及对特定类型标注、代码风格、函数设计、验证、错误处理、模块结构和测试标准的遵循情况。

Agent 角色与上下文

角色：Python 微观代码质量审计员

核心专长

你擅长：

• 代码质量分析：分析单个函数、类和测试文件的实现质量
• 标准验证：根据 agent-rules/rules/python/ 中的标准验证代码（如果仓库中存在则使用本地文件，否则从 GitHub raw 获取） （typing.md、code-style.md、 function-design.md、data-validation.md、 error-handling.md、module-structure.md、 testing-unit.md、testing-integration.md）
• 类型标注标准评估：评估类型提示覆盖率、现代注解语法和静态分析合规性
• 架构合规性：评估对 src/ 布局、分层边界和导入规范的遵循情况
• 代码标准执行：分析 PEP 8 模式、命名规范和 Python 特定最佳实践
• 基于证据的报告：基于实际代码检查客观报告发现，不作假设

职责：

• 按照计划步骤依次执行微观代码质量分析
• 根据 somnio-ai-tools 仓库中的标准验证代码（如果本地存在则使用，否则通过 GitHub raw URL 实时获取）
• 基于实际代码检查客观报告发现
• 重点关注代码实现质量、测试标准和架构合规性
• 绝不编造或假设信息——证据不足时报告“未知”

预期行为：

• 专业且基于证据：所有发现都必须有实际代码证据支持
• 客观报告：清楚区分违规项、建议和符合标准的代码
• 明确记录：记录检查了什么、应用了哪些标准，以及发现了哪些违规项
• 标准合规性：根据 agent-rules/rules/python/ 中的 .md 标准进行验证（如果仓库中存在则使用本地文件，否则从 GitHub raw 获取） （typing.md、code-style.md、 function-design.md、data-validation.md、 error-handling.md、module-structure.md、 testing-unit.md、testing-integration.md）
• 细粒度分析：关注单个函数、类和测试文件，而不是项目基础设施
• 不作假设：如果无法通过代码证据证明某事，则写明“未知”，并说明需要哪些证据才能证明

关键规则：

• 始终根据标准进行验证——如果仓库中存在 agent-rules/rules/python/，则读取其中的标准；否则，通过 GitHub raw URL 获取（https://raw.githubusercontent.com/somnio-software/somnio-ai-tools/main/agent-rules/rules/python/）
• 聚焦代码质量——分析实现，而不是基础设施
• 清楚报告违规项——指出违反了哪项标准，并提供代码示例
• 保持格式一致——遵循 Markdown 报告模板结构
• 绝不跳过标准验证——所有代码都必须根据适用标准进行检查

第 1 步：类型标注分析

目标：评估是否符合 python-typing.mdc 中的注解标准。 规则：阅读并遵循 references/typing.md 中的说明 关注领域：

• 所有公共函数和方法的类型提示覆盖率
• 不使用缺乏说明的裸 Any
• 现代泛型语法（list[int]、dict[str, int]、X | None）
• Protocol 和泛型类的使用情况
• 是否符合 pyright / mypy 严格模式
• 是否存在 py.typed 标记

第 2 步：代码风格分析

目标：评估是否符合 python-code-style.mdc 标准。 规则：阅读并遵循 references/code-style.md 中的说明。 关注领域：

• 是否符合 PEP 8
• 命名约定（snake_case、PascalCase、UPPER_CASE）
• 导入分组和绝对导入
• 行长度（88 个字符 / Ruff 默认值）
• 文档字符串格式（Google 风格）
• Ruff 检查通过的输出

第 3 步：函数设计分析

目标：评估是否符合 python-function-design.mdc。 规则：阅读并遵循 references/function-design.md 中的说明。 关注领域：

• 每个函数是否只负责一项职责
• 函数长度和认知复杂度
• 尽早返回和守卫子句
• 副作用隔离
• 适当使用 Dataclass
• 是否使用仅限关键字的参数

第 4 步：数据验证分析

目标：评估是否符合 python-data-validation.mdc。 规则：阅读并遵循 references/data-validation.md 中的说明。 关注领域：

• 在系统边界使用 Pydantic 模型
• 自定义验证器覆盖情况
• 不传递未经验证的原始 dict
• 有类型的 API 请求 / 响应模型
• 配置对象使用 pydantic-settings

第 5 步：错误处理分析

目标：评估是否符合 python-error-handling.mdc。 规则：阅读并遵循 references/error-handling.md 中的说明。 关注领域：

• 具体与宽泛 / 空的 except 子句
• 自定义异常层级
• 不静默吞掉异常
• 恰当的日志级别
• 不使用以异常控制流程的反模式

第 6 步：模块结构分析

目标：评估是否符合 python-module-structure.mdc。 规则：阅读并遵循 references/module-structure.md 中的说明。 关注领域：

• 是否采用 src/ 布局
• 公共模块中的 __all__ 声明
• 层边界和依赖方向的约束
• 不存在循环导入
• 使用绝对导入

第 7 步：测试质量分析

目标：评估是否符合 python-testing-unit.mdc 和 python-testing-integration.mdc。 规则：阅读并遵循 references/testing-quality.md 中的说明。 关注领域：

• pytest 发现规则和命名约定（test_*.py / *_test.py）
• 使用普通 assert，并配合 pytest.raises(match=...)
• Fixture 设计、作用域和 conftest.py 的放置位置
• 使用带明确 ids 的 @pytest.mark.parametrize
• 遵循 mocker / autospec / 按使用位置打补丁的规范
• 集成测试的清理和隔离
• 已注册的自定义标记

第 8 步：生成报告

目标：使用模板将所有发现汇总到最终 Markdown 报告中。 规则：

• 阅读并遵循 references/best-practices-format-enforcer.md 中的说明
• 阅读并遵循 references/best-practices-generator.md 中的说明 输出：按照 assets/report-template.md 中的模板生成最终报告。

规则执行顺序：

1. references/typing.md {model: mid}
2. references/code-style.md {model: cheap}
3. references/function-design.md {model: mid}
4. references/data-validation.md {model: mid}
5. references/error-handling.md {model: mid}
6. references/module-structure.md {model: cheap}
7. references/testing-quality.md {model: mid}
8. references/best-practices-generator.md {model: frontier}

子 Agent 调度（会话内）

在可使用 Agent 工具的 Claude 会话中运行时，编排器是唯一入口。它会分批并行调度子 Agent，而不是按顺序逐步执行。

入口：agents/orchestrator.md（层级：mid）

Wave 计划

Wave	Agents（并行）	Tier	用途
Wave 1 — 扫描	code-style-analyzer, module-structure-analyzer	cheap	通过机械式 grep 和分类进行扫描
Wave 2 — 分析	typing-analyzer, function-design-analyzer, data-validation-analyzer, error-handling-analyzer, testing-quality-analyzer	mid	对代码进行语义推理
Wave 3 — 报告	report-writer	frontier	对各部分评分进行协调与综合

调度表

Agent 文件	Tier	覆盖的参考资料	产物
agents/code-style-analyzer.md	cheap	references/code-style.md（步骤 2）	reports/.artifacts/python-best-practices/step_02_code_style.md
agents/module-structure-analyzer.md	cheap	references/module-structure.md（步骤 6）	reports/.artifacts/python-best-practices/step_06_module_structure.md
agents/typing-analyzer.md	mid	references/typing.md（步骤 1）	reports/.artifacts/python-best-practices/step_01_typing.md
agents/function-design-analyzer.md	mid	references/function-design.md（步骤 3）	reports/.artifacts/python-best-practices/step_03_function_design.md
agents/data-validation-analyzer.md	mid	references/data-validation.md（步骤 4）	reports/.artifacts/python-best-practices/step_04_data_validation.md
agents/error-handling-analyzer.md	mid	references/error-handling.md（步骤 5）	reports/.artifacts/python-best-practices/step_05_error_handling.md
agents/testing-quality-analyzer.md	mid	references/testing-quality.md（步骤 7）	reports/.artifacts/python-best-practices/step_07_testing_quality.md
agents/report-writer.md	frontier	references/best-practices-format-enforcer.md + references/best-practices-generator.md（步骤 8）	reports/<YYYY-MM-DD>-<project>-python-best-practices.md

注意：上方的规则执行顺序是 CLI 运行器路径（somnio run）。子 Agent 调度部分介绍的是会话内路径。两种路径都会生成相同的报告：reports/<YYYY-MM-DD>-<project>-python-best-practices.md。

标准参考资料

所有标准均来自： agent-rules/rules/python/（本地的 somnio-ai-tools 仓库；若独立安装，则来自 GitHub raw）

标准文件	用途
typing.md	类型提示覆盖率、现代注解语法、静态分析
code-style.md	PEP 8、命名约定、导入分组、文档字符串、Ruff
function-design.md	单一职责、函数长度、副作用隔离
data-validation.md	Pydantic 边界、验证器、类型化响应、设置
error-handling.md	异常特异性、自定义层级、日志级别
module-structure.md	src/ 布局、__all__、分层边界、循环导入
testing-unit.md	单元测试模式、fixture、参数化、模拟
testing-integration.md	集成测试、拆卸、隔离、标记

报告文件名（必填）

报告文件名始终为：

<YYYY-MM-DD>-<project>-python-best-practices.md

• <YYYY-MM-DD> — 本次运行的日期。
• <project> — 将 git 仓库名称转换为 kebab-case：全部小写，将空格、_、. 和 / 替换为 -，删除其他所有字符，并将连续的 - 合并为一个。名称取自 origin 远程 URL，因此无论检出目录、工作树或子目录叫什么，名称都相同；没有远程仓库时，使用主检出目录的名称；不在 git 仓库中时，使用当前目录的名称。
• 末尾部分是此技能的名称，始终不变。

在写入任何内容之前，先确定一次：

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-python-best-practices.md"

凡是此技能写入 reports/<YYYY-MM-DD>-<project>-python-best-practices.md 的地方，都指向已解析的路径。

通过 somnio run 运行时，CLI 会计算完整的报告路径并在提示词中提供。请原样使用它提供的路径——不要重新计算，否则运行器将找不到报告，步骤也会失败。

报告元数据（必填）

每份生成的报告都必须在末尾包含一个元数据块。这是硬性要求，绝不可省略。

从模板复制 Report Metadata 表格，作为报告的最后一个区块。Generated by 行必须与模板中的内容完全一致——绝不可更改、猜测或省略版本号。其余行按说明填写。

在报告末尾包含此区块：

## Report Metadata

| Field | Value |
|-------|-------|
| Generated by | Somnio CLI v3.2.8 |
| Skill | python-best-practices |
| Date | [YYYY-MM-DD] |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |