python-foundational

Python 基础编码规范技能

概述

每个差异都必须满足的 Python 基础要求。任何 .py 更改都会首先加载此技能。所有更高阶技能都以此为基础。

此内容采用技能而非指令文件的形式，原因有三：技能通过 CLI 插件和 VS Code 扩展分发，无需使用者将文件复制到自己的代码库中；添加新的语言技能无需修改审查 Agent 本身；技能按需加载，当差异中不包含 Python 代码时，可保持上下文窗口较小。

核心检查清单

1. 可读性与风格

• 使用 Python 命名规范：类采用 PascalCase，函数/变量采用 snake_case，常量采用 UPPER_SNAKE_CASE，私有成员采用 _。
• 对导入进行分组：标准库 → 第三方库 → 本地模块（组间空一行，不留尾随空白）。

2. Pythonic 惯用法

• 简单转换优先使用推导式；复杂逻辑/副作用则使用显式循环。
• 对文件、锁、数据库连接始终使用 with。
• 数据持有对象优先使用 dataclass / NamedTuple / Enum。
• 优先使用 pathlib 而非 os.path；适用时使用带时区的 datetime。
• 对包含多个可选参数的函数，使用 * 声明仅限关键字的参数。
• 除非确有必要，否则绝不使用可变默认值或 global/nonlocal。

3. 函数与类设计

• 保持函数简短且职责单一。
• 为所有公共 API 添加文档字符串（遵循代码库风格）。
• 记录不可避免的副作用。
• 遵循代码库定义的类成员顺序（如有）。

4. 类型安全基础

• 为所有公共 API、模块变量和类属性添加类型提示。
• 泛型使用 PEP 695（3.12+）或 TypeVar。
• 除薄封装外，避免使用 Any。

5. 错误处理

• 抛出具体异常；绝不使用裸 except:（仅在应用边界处记录日志并使用宽泛的 except Exception:）。
• 不得静默失败或使用笼统的错误消息。
• 每个异常都应提供上下文、预期状态和指导信息。

6. 应避免的反模式

• 绝不对不可信数据使用 eval、exec 或 pickle。
• 绝不硬编码密钥。

7. 可维护性

• 优先编写自解释代码；注释只说明“为什么”。
• 使用结构化日志，而不是 print。
• 标记难以测试的过长/过于复杂的函数。

8. 架构契合度

• 与现有模式保持一致；不要重新实现共享功能，也不要绕过既定层。
• 将代码放在正确的模块/包中。

9. 设计原则

• 消除重复：将重复逻辑提取到共享辅助函数中，以便修复自动同步生效。
• 优先选择满足当前需求的最简单实现。只有出现第二个具体用例时，才引入抽象。
• 限制更改范围：每个修改的行都应与更改的既定目的相关。
• 在指出看似未使用的代码之前，先确认它不是协议实现、框架钩子、公共 API 或由外部调用的入口点。
• 让解决方案的复杂度与问题复杂度相匹配。重复的函数需要共享辅助函数，而不是事件驱动架构。

参考资料

文件	涵盖内容	用途
design-principles.md	第 9 节	设计原则的依据和示例
code-style-patterns.md	第 1–5 节	风格、惯用法、类型安全、类设计和错误处理的具体代码示例

严重程度准则

严重程度	定义
高	在运行时导致行为错误、数据丢失或安全风险
中	降低可维护性或可读性，或违反项目约定，但不会立即影响运行时
低	外观、风格方面的问题，或轻微的改进机会

故障排查

症状	检查
未加载技能	确认差异中包含 .py 文件。Agent 会将已更改文件的类型与技能描述进行匹配，以此选择技能。
未生成任何发现	检查审查输出中的 Skills Loaded 页脚是否列出了 python-foundational。如果已列出但没有发现，差异可能已经符合检查清单。
严重程度似乎校准不当	对照上方的严重程度准则。高严重程度需要产生运行时影响；中严重程度仅影响可维护性。

贡献

扩展此技能时，请遵循以下约定：

• 检查清单条目应放在 SKILL.md 中。每个项目符号应是一项可由 Agent 或审查者针对差异执行的检查。保持简洁：用一个句子，不包含代码。
• 参考文件位于 references/ 中，用于提供相关检查清单条目的示例或理由。每个参考文件应涵盖连续的章节范围。添加新文件时，请更新 References 表格。
• 添加新检查清单条目前，请确认它没有与任何章节中的现有项目符号重复。将其放在与主要关注点相符的章节中。如果涉及多个关注点，优先放在更具体的章节中。
• 新参考文件应根据其涵盖的主题命名（例如 async-patterns.md）。添加 description 前置内容，说明该文件支持哪些章节。将新行添加到 SKILL.md 中的 References 表格。
• 检查清单条目和示例必须适用于不同代码库。使用通用模块名称，并根据反模式的行为进行描述，而非使用特定目录或文件名。