python-ultimate

Python Ultimate

Python 综合参考指南，提供标准规范、工具、工作流和最佳实践的快速入口。

快速开始

正在编写代码？ → 从 编码规范 开始 正在检查命名？ → 前往 命名约定 正在构建 CLI？ → 前往 CLI 开发 正在修复代码检查器错误？ → 前往 代码检查器规则 正在编写测试？ → 前往 测试 正在调试错误？ → 前往 调试 正在重构？ → 前往 重构 正在审查代码？ → 前往 代码审查 正在审计代码库？ → 前往 审计 正在编写文档？ → 前往 文档 正在规划功能？ → 前往 规划 正在运行 Python？ → 前往 uv 执行 独立脚本？ → 前往 uv 脚本 项目工作流？ → 前往 uv 项目 批量操作？ → 前往 重构（10 个以上文件）

斜杠命令

/python-ultimate 命令接受可选的 sub-command 参数，用于运行针对性的指南审查。不带子命令调用时（例如，仅运行 /python-ultimate），请使用下方「反模式／禁止风格索引」部分进行常规反模式检查。

路由

将 sub-command 参数与下方某个部分匹配，并遵循相应工作流。如果参数与任何已知子命令都不匹配，请说明可用选项（可以输出 python-ultimate help 中的表格）。

---

python-ultimate help

当子命令为 help（或用户询问可用命令时），请呈现下表，让用户查看所有可用选项：

Sub-Command                    │ What It Reviews                                        │ Reference
───────────────────────────────┼────────────────────────────────────────────────────────┼──────────────────────────────────
python-ultimate naming         │ File/dir variable naming (_file/_dir/_path suffixes)  │ references/naming-conventions.md
python-ultimate type-checking  │ TYPE_CHECKING guards and Optional[T] usage             │ references/type-checking.md
python-ultimate imports        │ Required-vs-optional import patterns                    │ references/imports-optional-dependencies.md
python-ultimate coding-standards│ Type hints, f-strings, pathlib, docstrings, comments, data modeling │ references/coding-standards.md
python-ultimate linter-rules   │ Ruff violations (E402, B007, B008, S108, etc.)         │ references/linter-rules.md
python-ultimate debugging      │ Systematic 4-phase debugging process                   │ references/debugging.md
python-ultimate testing        │ Test organization, fixtures, mocking, TDD, coverage    │ references/testing.md
python-ultimate audit          │ 6-dimension codebase audit                             │ references/auditing.md
python-ultimate verification   │ Evidence-based completion claims                       │ references/verification.md
python-ultimate code-review    │ Code review feedback evaluation                        │ references/code-review.md
python-ultimate uv             │ Always `uv run`, never bare `python`                   │ references/uv.md
python-ultimate uv-scripts     │ PEP 723 standalone scripts via `uv init --script`      │ references/uv-scripts.md
python-ultimate uv-projects    │ Project workflow: init, add, sync, lock, groups        │ references/uv-projects.md

---

python-ultimate naming

审查文件和目录变量的命名约定（_file／_dir／_path 后缀）。

工作流：

1. 打开 references/naming-conventions.md，并载入「1. 文件和目录」部分
2. 扫描代码库，查找用作 Path 变量的无修饰路径名称（path、file、dir、output、source、target）
3. 检查前缀模式（dir_output → 应为 output_dir）
4. 查找缺少后缀的通用路径变量名（results → 含义不明确）
5. 使用标准反模式响应格式报告发现的问题

---

python-ultimate type-checking

扫描 TYPE_CHECKING 保护代码和 Optional[T] 的用法。

工作流：

1. 打开 references/type-checking.md，并载入「规则：绝不使用 TYPE_CHECKING 保护代码」部分
2. 搜索 TYPE_CHECKING 导入：rg "TYPE_CHECKING" src/
3. 搜索 Optional[ 的用法：rg "Optional\[" src/
4. 对每项发现，确定根本原因（循环导入、仅用于类型检查的导入）
5. 建议合适的替代方案（共享类型模块、协议、前向引用、局部导入）
6. 使用标准反模式响应格式报告发现的问题

---

python-ultimate imports

审查导入模式——区分必需依赖与可选依赖。

工作流：

1. 打开 references/imports-optional-dependencies.md 并加载硬性规则
2. 检查 pyproject.toml，确定哪些包是必需依赖，哪些是可选依赖
3. 搜索保护必需依赖的 try/except ImportError 模式： rg "except ImportError" src/
4. 对每个匹配项进行分类：必需依赖 → 常规顶层导入；可选依赖 → 局部处理
5. 使用标准的反模式响应格式报告发现

---

python-ultimate coding-standards

审查是否符合编码标准：类型提示、f-string、pathlib、文档字符串、注释、禁止的模式，以及含糊的输入/输出类型。

工作流：

1. 打开 references/coding-standards.md 并加载相关章节
2. 针对每种禁止的模式，使用有针对性的 grep 模式进行搜索：
   • Optional\[ → 必须改为 T | None
   • \.format\( 或 % 格式化 → 必须使用 f-string
   • os\.path\. → 必须使用 pathlib.Path
   • # noqa → 修复根本问题
3. 检查是否存在通过多个 isinstance 检查处理的含糊输入/输出类型
4. 扫描含糊的类型注解：
   • rg ": object$" 或 rg "-> object" → 将裸 object 用作类型
   • rg "\bAny\b" src/ --include "*.py" → 使用了 typing.Any（标记每处以供审查）
5. 扫描数据类字段和函数签名中对 None 的误用：
   • rg "= None$" → 可能存在哨兵值/缺失值模式
   • 检查值为 list | None = None、dict | None = None 的数据类字段 → 应使用 field(default_factory=...)
   • 检查将 T | None 作为错误信号的函数返回值 → 应改为抛出异常
6. 使用标准的反模式响应格式报告发现

---

python-ultimate linter-rules

使用感知上下文的模式审查并修复特定的 Ruff 检查器违规。

工作流：

1. 打开 references/linter-rules.md 并加载相关规则章节
2. 运行 ruff check src/ 以识别违规项
3. 对于每条违规规则，按照参考文档中的上下文相关修复模式进行处理：
   • E402 → 将导入移至模块顶部
   • B007 → 在未使用的循环变量前加上 _
   • B008 → 使用 None 哨兵值（Typer Annotated 参数除外）
   • S108 → 使用 tempfile 或 tmp_path fixture
   • PLC0415 → 将导入移至模块级别
   • NPY002 → 使用 default_rng()
   • S311 → 在安全相关场景中使用 secrets
4. 重新运行 ruff check src/ 以确认修复
5. 使用标准的反模式响应格式报告发现

---

python-ultimate debugging

启动系统化的 4 阶段调试流程。

工作流：

1. 打开 references/debugging.md 并加载完整的 4 阶段流程
2. 阶段 1 — 根本原因： 重现问题，阅读错误消息，沿数据流从症状追溯到问题源头
3. 阶段 2 — 模式： 查找可正常工作的示例，与有问题的代码进行对比，列出所有差异
4. 阶段 3 — 假设： 提出一个可测试的假设，进行尽可能小的改动来验证
5. 阶段 4 — 实现： 先编写一个失败的测试，再实现修复，并验证所有测试均通过
6. 牢记铁律：未先调查根本原因，不得进行修复。
7. 如果已有 3 次或更多修复失败，请停止并重新评估架构，而不是继续猜测

---

python-ultimate 测试

检查测试组织、覆盖率、夹具、模拟和 TDD 合规性。

工作流：

1. 打开 references/testing.md，了解模式和标准
2. 检查测试文件命名：遵循 test_<module>.py 约定
3. 检查测试类命名：使用 PascalCase 格式的 Test<Name>
4. 检查测试方法命名：使用 snake_case 格式的 test_<description>
5. 运行覆盖率检查：uv run pytest --cov=src --cov-report=term-missing
6. 检查夹具质量（名称清晰、作用域合适、完成拆解）
7. 使用标准的反模式响应格式报告发现

---

python-ultimate 审计

对代码库进行六个维度的审计。

工作流：

1. 打开 references/auditing.md 并加载全部六个维度
2. 针对每个维度（架构、质量、安全、性能、测试、可维护性）：
   • 使用 grep/glob 扫描相关危险信号
   • 按严重程度对发现分级（严重、高、中、低）
3. 按照 references/auditing.md 中的格式汇总并撰写审计报告
4. 提供包含健康评分和首要建议的执行摘要
5. 制定行动计划，列出紧急、短期、中期和待办事项

---

python-ultimate 验证

验证完成声明是否有最新证据支持。

工作流：

1. 打开 references/verification.md，并加载铁律和门禁函数
2. 针对每项声明，确定可用于证明它的命令
3. 运行完整命令、阅读输出并检查退出代码
4. 只有完成上述步骤后，才能陈述结果——必须有证据，而非假设
5. 禁用词：should、probably、might、likely
6. 使用标准的反模式响应格式报告结果

---

python-ultimate 代码审查

评估代码审查反馈，并以严谨的技术方式作出回应。

工作流：

1. 打开 references/code-review.md 并加载完整工作流
2. 遵循 READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT 流程
3. 针对每条反馈：对照代码库现状进行验证，并评估其技术合理性
4. 不要敷衍认同——应基于技术理由回应，或提供证据予以反驳
5. 在以下情况下予以反驳：建议会破坏现有功能、违反 YAGNI 原则或缺乏完整上下文

---

python-ultimate uv

严格执行运行规范：每次调用 Python 都必须通过 uv。

工作流：

1. 打开 references/uv.md，并加载铁律和执行模式
2. 将直接调用 python / python3 视为违规——改用 uv run ...
3. 在沙盒环境中，确认 UV_CACHE_DIR 已设置为可写目录
4. 使用标准的反模式响应格式报告发现

---

python-ultimate uv-scripts

检查 PEP 723 独立脚本是否遵守“绝不手动编辑元数据”规则和 Agent 式脚本设计规则。

工作流：

1. 打开 references/uv-scripts.md，并加载铁律和核心工作流
2. 搜索 PEP 723 块，并检查其是否通过 uv init --script / uv add --script / uv remove --script 创建或维护
3. 搜索手动编辑的元数据标记：rg "# /// script"、rg "# dependencies =" — 每处都必须有 uv 管理工作流的依据
4. 对照 Agent 式脚本设计规则，检查交互式提示（input(）、缺少 --help、自由格式的 stdout，以及无界输出
5. 使用标准的反模式响应格式报告发现

---

python-ultimate uv-projects

审查由 uv 管理的项目：锁定、同步、分组和常见错误。

工作流：

1. 打开 references/uv-projects.md 并加载「常见错误」表
2. 检查包含 pyproject.toml + uv.lock 的项目中是否使用了 pip install
3. 检查 uv sync 的用法——需要保证可复现性时，是否遗漏了 --locked
4. 检查 .venv/ 是否已加入 Git 忽略，以及 uv.lock 是否已提交
5. 检查工作区和依赖组是否一致
6. 使用标准的 反模式响应格式 报告发现

---

预期的 /python-ultimate 响应格式

为确保各 Agent 的响应一致，所有子命令的响应均按以下格式编写：

1. 摘要 — 按严重性和类别统计发现总数
2. 发现 — 每项发现单独列出：file:line、匹配的模式类别、简短理由
3. 修复指南 — 首选替代模式，并提供一个具体的修复前/后示例
4. 参考资料 — 指向 references/*.md 中相关部分的直接链接
5. 验证 — 运行的确切命令及观察到的结果

使用简洁、技术性的语言。避免刻意表示赞同，也避免推测性措辞。

反模式 / 禁用风格索引

常见错误或禁用模式的权威速查表。详细理由和示例保留在参考文件中。

类别	禁止模式	推荐模式	来源
类型检查	TYPE_CHECKING 导入保护	重构模块边界，使用前向引用／协议	references/type-checking.md
类型提示	Optional[T]	T | None	references/coding-standards.md
字符串格式化	.format() 和 % 格式化	f-string	references/coding-standards.md
路径	使用 os.path	pathlib.Path	references/coding-standards.md
Lint 抑制	用 # noqa 隐藏问题	修复根本问题	references/coding-standards.md
导入策略	对必需依赖使用防御性的 try/except ImportError	对必需依赖使用常规的顶层导入	references/imports-optional-dependencies.md
路径变量命名	使用 path、file、output 等不带限定的名称表示路径	使用 _file／_dir 后缀	references/naming-conventions.md
路径变量命名	dir_x、file_x 等前缀形式	x_dir、x_file 等后缀形式	references/naming-conventions.md
注释	重述显而易见的代码意图	仅说明原因／限制	references/coding-standards.md
调试工作流	在根因分析前采用猜测并检查式修复	遵循 4 阶段流程	references/debugging.md
调试行为	多次失败后仍反复“再试一次”	停下来重新评估架构	references/debugging.md
代码审查行为	敷衍式赞同用语	给出技术性回应和证据	references/code-review.md
数据建模	对轻量级内部结构使用 pydantic，或在信任边界使用 dataclass	内部 DTO 使用 dataclass；验证／API 边界使用 pydantic	references/coding-standards.md
Python 执行	直接调用 python／python3	uv run ...（uv 选择解释器、同步环境并解析依赖）	references/uv.md
脚本元数据	手写或手动编辑 PEP 723 # /// script 块	uv init --script／uv add --script／uv remove --script	references/uv-scripts.md
项目依赖	在由 uv 管理的项目中运行 pip install	uv add（由 pyproject.toml 管理）	references/uv-projects.md
锁文件	在需要可复现性的场景中不带 --locked 使用 uv sync	uv sync --locked（或在信任锁文件时使用 --frozen）	references/uv-projects.md
版本控制卫生	提交 .venv/；不提交 uv.lock	将 .venv/ 加入 Git 忽略规则；提交 uv.lock	references/uv-projects.md
架构	假设 uv python install 能提供 32 位 Python	将系统 32 位解释器路径传给 uv run --python <path>	references/uv-python-versions.md
类型提示	未作说明就使用 object 或 typing.Any 作为类型注解	使用精确的联合类型（str | int），结构类型使用 typing.Protocol	references/coding-standards.md
默认值	将 None 用作集合的默认值或无提示的错误信号	可变默认值使用 field(default_factory=...)，错误状态使用异常	references/coding-standards.md

---

编码规范

Python 核心编码规则。完整详情请参阅 references/coding-standards.md。

类型提示

所有地方都必须使用。使用管道语法（T | None），绝不使用 Optional[T]。需要 Python 3.10+。

def process(data: str, limit: int | None = None) -> list[str]: ...

绝不使用 TYPE_CHECKING 守卫。 替代方案请参阅 references/type-checking.md。

字符串格式化

只使用 f-string。不使用 .format() 或 % 格式化。

代码长度限制

目标	限制
模块	< 250 行
函数	< 75 行
类	< 200 行

文档字符串

使用 Google 风格。公共函数和类必须编写文档字符串。

禁止的模式

• TYPE_CHECKING 守卫
• os.path（使用 pathlib.Path）
• Optional[T]（使用 T | None）
• # noqa 注释
• 修改 sys.path
• 对必需依赖项使用防御性的 try/except ImportError（参阅 references/imports-optional-dependencies.md）
• 使用含糊或过宽的参数／返回类型，并在其中隐藏 isinstance／hasattr 检查，以及将 None 作为错误返回值（参阅 references/coding-standards.md）
• 使用 pydantic 定义轻量级内部结构，或使用 dataclass 处理不受信任的／API 数据（参阅 references/coding-standards.md）
• 未经说明就将 object 或 typing.Any 用作类型注解（使用精确的联合类型、typing.Protocol 或尽可能具体的类型；参阅 references/coding-standards.md）
• 将 None 用作可变集合的默认值（在 dataclass 中使用 field(default_factory=...)；参阅 references/coding-standards.md）
• 将 None 作为不显式提示的错误返回值——优先使用异常或结果类型（参阅 references/coding-standards.md）

---

命名约定

确保清晰一致的变量命名规范。完整详情请参阅 references/naming-conventions.md。

文件和目录

模式	后缀	示例
文件	_file	output_file、config_file
目录	_dir	cache_dir、output_dir
未知类型	_path	data_path（仅限特殊情况）

反模式（路径变量一律禁止）：

• 通用名称前不带限定词：path、file、folder、dir、directory、output、input、source、target、dest
• 使用前缀而非后缀：dir_output、file_config
• 缺少后缀：results、data、config（含义不明确）

完整反模式列表请参阅 references/naming-conventions.md。

测试命名

• 文件：test_<module>.py
• 类：Test<DataProcessor>（PascalCase，前缀为 Test）
• 方法：test_<description>（snake_case，前缀为 test_）

自动化验证

# Check a variable name
uv run assets/check_path_naming.py output_file
# Output: is_file

# Scan for violations
uv run assets/check_path_naming.py --check-files src/

# Scan for core forbidden patterns
uv run assets/check_path_naming.py --check-forbidden src/

# Repro fixture scan (see assets/examples)
uv run assets/check_path_naming.py --check-forbidden assets/examples/

参考 fixture 文件和预期输出：assets/examples/forbidden-scan-expected.md

---

CLI 开发

使用 Typer 或 Click 构建 Python CLI。参阅 references/cli-development.md。

框架选择

新项目使用 Typer（由类型提示驱动，样板代码更少）。复杂参数处理使用 Click。

关键模式

• 使用类型提示验证参数
• 使用 Rich 格式化输出
• 集成环境变量
• 为错误状态设置退出代码

---

代码检查器规则

针对 Ruff 代码检查器规则进行上下文感知修复。参阅 references/linter-rules.md。

涵盖的规则

规则	描述	快速修复
E402	模块级导入不在文件顶部	将导入移至顶部
B007	未使用的循环变量	在变量名前加上 _
B008	默认参数中调用函数	使用 None 哨兵值
S108	硬编码的临时文件路径	使用 tempfile
PLC0415	导入不在顶层	将导入移至模块级
NPY002	使用旧版 numpy 随机数功能	使用 numpy.random
S311	使用标准随机数功能	在安全场景下使用 secrets

Typer 例外

Typer Annotated 参数允许使用 B008。请参阅 references/linter-rules.md。

---

测试

测试组织、夹具、模拟和 TDD。请参阅 references/testing.md。

快速命令

uv run pytest -v --tb=short
uv run pytest --cov=src --cov-report=term-missing

核心实践

• 测试与代码并置：<module>_test.py 与实现文件放在一起
• 覆盖率目标为 90% 以上
• 在 conftest.py 中定义夹具
• 使用参数化测试处理多个输入
• 使用 unittest.mock 模拟外部依赖

TDD 循环

红 → 绿 → 重构。没有先编写失败测试，就不编写生产代码。请参阅 references/testing.md。

---

调试

系统化的 4 阶段调试流程。请参阅 references/debugging.md。

铁律

未先调查根本原因，不得修复。

4 阶段流程

1. 根本原因 — 重现问题、隔离问题、追踪数据流
2. 模式分析 — 确定状态变化和时序问题
3. 假设 — 提出可测试的预测
4. 实现 — 进行最小修复，并通过测试验证

危险信号

• “让我试着改一下 X”
• 不理解原因就修复症状
• 多次尝试修复均失败

---

重构

查找 → 替换 → 验证工作流。请参阅 references/refactoring.md。

工作流

1. 查找 — 使用 Grep 搜索目标模式
2. 替换 — 批量更改时使用 replace_all 编辑
3. 验证 — 运行测试并检查是否引入回归问题

代码迁移

在文件之间按行移动代码。请参阅 references/refactoring.md。

---

代码审查

接收并评估代码审查反馈。请参阅 references/code-review.md。

工作流

阅读 → 理解 → 验证 → 评估 → 回复 → 实施

核心原则

• 不要只做表面上的赞同
• 以技术理由提出异议
• 实施前先验证反馈
• 评估建议是否正确

---

审计

从 6 个维度分析代码库。请参阅 references/auditing.md。

维度

1. 架构 — 结构、模块化、依赖关系
2. 质量 — 可读性、复杂度、重复
3. 安全性 — 输入验证、密钥、注入
4. 性能 — 瓶颈、内存、I/O
5. 测试 — 覆盖率、质量、边界情况
6. 可维护性 — 文档、技术债务

严重程度评级

严重 → 高 → 中 → 低

---

文档

包含 10 个部分的文档结构。请参阅 references/documentation.md。

工作流

探索 → 映射 → 阅读 → 综合

部分

项目概述、架构、关键组件、数据流、API 参考、配置、设置指南、开发指南、测试、部署

Mermaid 图表

用于展示架构、时序和流程图。

---

规划

用于功能实现的持续更新文档 PLAN.md。请参阅 references/planning.md。

适用场景

适用于跨越 3–15 个提示词的功能。可在全新会话中独立使用。

结构

目标 → 上下文 → 阶段 → 验证 → 进度 → 决策 → 备注

---

项目设置

项目结构、依赖项和导入。参见 references/project-setup.md 和 references/uv-projects.md。

主要工具

• uv 用于依赖管理
• src 布局 用于包
• pyproject.toml 用于配置

导入顺序

1. 标准库
2. 第三方库
3. 本地库（绝对导入）

---

uv 工作流

通过 uv 运行程序、编写脚本和管理项目。参见 references/uv.md、references/uv-scripts.md、 references/uv-projects.md 和 references/uv-python-versions.md。

铁律

始终使用 uv run。绝不直接使用 python / python3。

# BAD
python script.py

# GOOD
uv run script.py

独立脚本（PEP 723）

仅通过 uv 管理元数据，绝不手动编辑 # /// script 块。

uv init --script path/to/script.py
uv add --script path/to/script.py "requests>=2.32,<3"
uv run path/to/script.py

项目

uv init my-project
uv add requests --dev pytest
uv sync --locked
uv run pytest

Python 版本与架构

uv python install 3.12
uv python pin 3.12
uv run --python 3.12 script.py

uv 仅提供 x86_64 解释器——若要使用 32 位 Python，请将 --python 指向系统已安装的解释器。参见 references/uv-python-versions.md。

范围边界

安装 uv 本身以及使用 uvx 运行 MCP 服务属于独立的 uv 技能，不属于此技能。

---

文件分析

以非破坏性方式分析文件和代码库。参见 references/file-analysis.md。

工具

• stat 用于获取元数据
• wc 用于统计行数
• Grep 用于搜索模式
• Glob 用于查找文件

---

类型检查替代方案

绝不使用 TYPE_CHECKING 守卫。参见 references/type-checking.md。

替代方案

1. 将共享类型提取到专用模块中
2. 使用协议进行结构化类型检查
3. 使用前向引用（字符串字面量）
4. 使用局部导入（最后的手段）

---

批量操作

针对 10 个以上文件操作的高效 Python 执行方式。与迭代式方法相比，可节省 90%–99% 的令牌。

适用场景：

• 批量操作（10 个以上文件）
• 复杂的多步骤工作流
• 对多个文件进行迭代处理
• 用户提及效率或性能

工作流模式：

1. 本地分析 — 使用元数据操作（文件计数、grep 模式）
2. 本地处理 — 在 Python 中执行所有转换
3. 返回摘要 — 报告数量，而非完整数据

示例模式：

# Bulk refactor across 50 files
from pathlib import Path
import re

files = list(Path(".").glob("**/*.py"))
modified = 0

for f in files:
    content = f.read_text()
    new_content = re.sub(r"old_pattern", "new_pattern", content)
    if new_content != content:
        f.write_text(new_content)
        modified += 1

result = {"files_scanned": len(files), "files_modified": modified}

# Code audit metadata extraction
from pathlib import Path
import ast

files = list(Path("src").glob("**/*.py"))
complexity_issues = []

for f in files:
    tree = ast.parse(f.read_text())
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef):
            # Calculate simple complexity metric
            nested = sum(
                1 for n in ast.walk(node) if isinstance(n, (ast.If, ast.For, ast.While))
            )
            if nested > 10:
                complexity_issues.append(
                    {"file": str(f), "function": node.name, "complexity": nested}
                )

result = {"files_audited": len(files), "high_complexity": len(complexity_issues)}

最佳实践：

• ✅ 返回摘要，而非完整数据
• ✅ 尽可能批量执行操作
• ✅ 使用 pathlib.Path 进行文件操作
• ✅ 妥善处理错误，并返回错误数量
• ❌ 元数据已足够时，不要将完整源代码读入上下文
• ❌ 不要以交互方式逐个处理文件

令牌节省随文件数量增加：

文件数	交互式	批量操作	节省比例
10	~5K 个令牌	~500 个令牌	90%
50	~25K 个令牌	~600 个令牌	97.6%
100	~150K 个令牌	~1K 个令牌	99.3%

---

参考文件

所有详细内容都在 references/ 中。只加载所需内容：

文件	内容
coding-standards.md	类型提示、格式、大小限制、文档字符串、注释、数据建模
cli-development.md	Typer/Click、参数、Rich 输出、环境变量
linter-rules.md	Ruff 规则 E402、B007、B008、S108、PLC0415、NPY002、S311
testing.md	固件、参数化、模拟、TDD、覆盖率
type-checking.md	TYPE_CHECKING 替代方案、协议、前向引用
debugging.md	4 阶段流程、危险信号、合理化
refactoring.md	批量操作、代码迁移、安全检查
code-review.md	接收反馈、提出异议、评估
auditing.md	6 维度分析、严重性评级
documentation.md	10 部分结构、Mermaid 图表
planning.md	PLAN.md 模板和示例
file-analysis.md	元数据、行数统计、模式搜索
project-setup.md	项目结构、uv、导入
verification.md	提交前钩子、tox、Makefile 目标
imports-optional-dependencies.md	必需与可选依赖项的导入模式
uv.md	执行规范：始终使用 uv run，不要直接使用 python，以及 UV_CACHE_DIR
uv-scripts.md	PEP 723 独立脚本、uv init --script、Agentic 设计
uv-projects.md	项目工作流、锁定/同步、--locked 与 --frozen、组、工作区
uv-python-versions.md	版本固定、--python 标志、32 位 / 自由线程构建