shunk031-python-uv-workflow

说明

阅读此 SKILL.md 后，请说：🐍 I read shunk031-python-uv-workflow.

Python UV 工作流

概述

使用此工作流，确保 Python 实现和重构符合仓库政策。

工作流

1. 将 uv 用作 Python 项目的默认工具链。
2. 使用 uv run <script> 运行脚本。
3. 行为发生变化时编写测试，并验证预期行为。
4. 使用 uv 添加标准开发依赖项。
5. 遵循现有项目的设置和质量门禁。依赖项设置完成后，如果项目或仓库有要求，请安装 pre-commit 钩子。
6. 对于新项目或明确的设置请求，只添加请求或仓库政策所需的项目配置；不要为单独的脚本编辑创建 .pre-commit-config.yaml 或 Makefile。
7. 将影响解析器的 uv 设置（例如 exclude-newer）保留在用户的全局 uv 配置之外：uv lock 会将这些设置记录在锁文件的 [options] 块中，因此任何未设置相同配置的环境都会在每次非冻结的 uv run、uv sync 或 uv-lock 钩子运行时重新解析并改写锁文件。需要此类设置的项目必须在自己的 pyproject.toml 中的 [tool.uv] 下声明；含有未声明 [options] 块的已提交锁文件存在缺陷，必须通过重新生成锁文件来修复。
8. 从非 uv 原始项目重构时，应使依赖项保持一致，并验证输出一致性。达到仓库的覆盖率目标；仅当重构或仓库要求时，才将覆盖率提高到 90% 左右。
9. 从源文件锚点构造 Python 路径，并将每个路径组件分别作为操作数：
   • 禁止：Path("/path/to") / "hoge" 和 REPO_ROOT / "home/dot_codex/hooks/session_start_gateway.py"
   • 必须：Path(__file__).parents[N] / "path" / "to" / "hoge" 传递给 Path 或用作 / 操作数的字符串字面量中，绝不能包含由 / 或 \ 分隔的多个路径组件。将路径锚定到源文件，可确保路径在文件移位后以及不同工作树中仍然有效，而不依赖主机布局。允许通过 CLI 参数或环境变量显式提供根路径；仍然禁止硬编码绝对路径字符串。 完成 Python 更改前，请检查所有已更改的 Path(...) 和 / 表达式，确认其中没有包含路径分隔符的字符串操作数。
10. 根据变量的语义角色命名。当同一概念有多种表示形式时，仅在需要区分时添加 _path、_text 或 _data 等限定词；如果变量角色已明确，不要机械地添加类型后缀。

测试期望

• 行为发生变化时，应在重构前添加测试。
• 可行时优先使用真实数据，而非模拟和 monkeypatch。
• 遵循项目声明的覆盖率目标；不要强制采用统一的百分比。

使用 python-uv-rules.md 查看准确命令和规范钩子配置。