• Claude Code hooks（.claude/hooks/）：PostToolUse 对每次编辑的 .py 即时跑 ruff 并回灌错误；PreToolUse 硬拦裸 python、uv run --package、docker compose build --parallel（含引号感知的分段解析）。两个钩子在开发过程中已实战触发、当场抓住真实错误。

在这段关于 Claude Code Hooks（钩子）的配置描述中， “裸 python”（Bare Python） 指的是： 直接在命令行中调用系统全局的 python 或 python3 命令，而没有通过虚拟环境管理工具（如 uv、poetry）或没有激活虚拟环境来运行。

结合你提供的上下文（里面提到了拦截 uv run --package），可以判断该项目使用的是 uv（一个现代、极速的 Python 包和项目管理工具）来管理依赖和虚拟环境。

为什么要“硬拦”（严格拦截）裸 python？

在 AI 辅助编程（如使用 Claude Code）时，AI 为了图省事，经常会习惯性地生成 python main.py 或 pip install xxx 这样的命令。开发者配置 Hook 去“硬拦”这些命令，主要是出于以下工程化考虑：

1. 防止依赖找不到（ModuleNotFoundError）
   • 裸 python：调用的是系统全局的 Python，里面通常没有安装项目所需的第三方库，一跑就报错。
   • 正确做法：应该使用 uv run python main.py，这样 uv 会自动在项目的虚拟环境中执行，确保所有依赖都可用。
2. 保证 Python 版本一致
   • 裸 python：可能调用的是系统自带的 Python 3.8，而项目要求的是 Python 3.11。
   • 正确做法：uv run 会自动识别项目中的 .python-version 文件，使用正确的 Python 版本。
3. 防止污染系统全局环境
   • AI 如果发现缺包，可能会自作聪明地执行 pip install requests（裸 pip），这会把包安装到系统全局环境中，造成环境污染。
   • 正确做法：应该拦截并迫使 AI 使用 uv add requests 将依赖添加到项目的 pyproject.toml 中。
4. 强制 AI 遵守团队规范
   • 通过 PreToolUse（工具使用前）钩子，在 Claude 准备执行 Bash 命令的瞬间进行拦截。如果发现命令是以 python 或 python3 开头的，直接拒绝执行，并迫使 Claude 自己纠正为 uv run ...。

直观对比示例

场景	❌ 会被 Hook 拦截的“裸 python”命令	✅ 符合规范的命令（uv 托管）
运行脚本	python main.py	uv run python main.py
跑测试	python -m pytest	uv run pytest
装依赖	pip install pandas	uv add pandas
跑包管理	python -m pip install -r requirements.txt	uv sync

补充：什么是“含引号感知的分段解析”？

这是指这个 Hook 拦截脚本写得非常严谨。当 Claude 尝试执行类似 python script.py "hello world" 的命令时，Hook 脚本在解析命令字符串时，能够智能识别引号，不会把 "hello world" 错误地拆分成两个参数。它能精准提取出命令的第一个词（即 python），从而准确触发拦截规则，防止误杀或漏网。

总结：“硬拦裸 python”就是开发者给 AI 立下的规矩——“在我的项目里，绝对不允许你直接调用系统的 Python，所有的执行必须通过 uv 走虚拟环境！”