用途:这是面向 Python 代码变更的基础编码规范技能,任何 .py 改动都会优先加载,其他更高阶技能均以其为基础。它以技能而非普通说明文件的形式分发,可通过 CLI 插件与 VS Code 扩展使用,无需把文件复制进仓库;新增语言技能也不必改动审查代理本身;按需加载可在 diff 不含 Python 时保持上下文精简。
主要能力:检查清单覆盖九类内容。可读性与风格:类用 PascalCase、函数与变量用 snake_case、常量用 UPPER_SNAKE_CASE、私有成员用下划线;导入按标准库、第三方、本地分组并以空行分隔。Pythonic 惯用法:简单转换优先推导式,复杂逻辑或副作用用显式循环;文件、锁、数据库连接一律用 with;数据载体优先 dataclass、NamedTuple、Enum;用 pathlib 替代 os.path,必要时使用带时区的 datetime;多可选参数函数使用 * 关键字参数;禁止可变默认值,非必要不用 global/nonlocal。函数与类设计:保持函数小而单一职责,公共 API 写 docstring,记录不可避免的副作用,遵循代码库的类成员顺序。类型安全:公共 API、模块变量、类属性加类型提示,泛型用 PEP 695(3.12+)或 TypeVar,除薄封装外避免 Any。错误处理:抛出具体异常,禁止裸 except,应用边界处才可宽泛捕获并记录日志,异常信息需含上下文、预期状态与指引。反模式:禁止对不可信数据使用 eval、exec、pickle,禁止硬编码密钥。可维护性:优先自解释代码,注释只写“为什么”,用结构化日志替代 print,标记过长或难测试的函数。架构契合:沿用既有模式,不重复实现共享功能或绕过既定分层,代码放入正确模块。设计原则:消除重复,把重复逻辑抽成共享辅助函数;优先满足当前需求的最简实现,出现第二个具体用例再引入抽象;限制改动范围,每行修改都应可追溯到变更目的;标记疑似未使用代码前先确认它不是协议实现、框架钩子、公共 API 或外部入口;方案复杂度与问题复杂度匹配。
使用方式:技能由代理按变更文件类型与技能描述匹配自动选择;参考资料放在 references/ 目录,design-principles.md 对应第 9 节,code-style-patterns.md 对应第 1–5 节,提供示例与理由。
适用场景与限制:适用于 Python 代码审查与规范落地。严重度分为高(运行时错误行为、数据丢失或安全暴露)、中(可维护性、可读性或约定违反,无即时运行时影响)、低(外观或风格)。排障:技能未加载时确认 diff 含 .py 文件;无发现时检查审查输出中 Skills Loaded 是否列出本技能;严重度偏差时对照评级标准。扩展技能时,检查项写入 SKILL.md,每条一句话且不含代码,参考资料命名对应主题并更新引用表。资料未提供具体安装命令、收费与平台细节。