Claude Code写Python总乱套？试试这套工程规范Skill

你用 Claude Code 写 Python，AI 生成的代码能跑，但总觉得哪里不对？类型提示东一块西一块，import 顺序乱糟糟，pytest 跑起来一堆 warning？问题不是 AI 不够强——是你的 AI 缺一套 Python 工程标准。

smith-python 就是来解决这个问题的。这是一个来自独立 NLP 研究者 Mike Tian-Jian Jiang（tianjianjiang）的 Python 开发规范 Skill，配套在他的 smith 框架里——一个 47 个 Skill 的全家桶。

核心规范：这些规则 AI 很容易忽略，但必须强制执行

这个 Skill 的核心逻辑很直接——在 Primacy Zone（最高优先级）里写清楚哪些绝对不能做，然后用 Ruff + pytest 落地：

• 禁止相对导入（from .module import）——必须用绝对路径
• 禁止在函数内做 inline import——这是性能陷阱
• 测试必须用函数风格，不能用 pytest class（class TestFoo:）
• 所有函数必须有类型提示，包括返回值
• 必须用虚拟环境执行 pytest，直接跑 python -m pytest 会漏 .env

这些规则看起来像 eslint 配置，但它是给 AI 看的——所以每一条都附带了「为什么」，不只是规则本身。

测试规范：TDD 是方法论，不是口号

smith-python 依赖 smith-tests 做测试质量门控。组合起来的工作流是：

• 写测试函数：def test_should_parse_pdf_when_valid_file_provided()
• 测试文件位置必须镜像源代码：foo/bar/xyz.py → tests/unit/foo/bar/test_xyz.py
• 用 poetry run pytest 或 uv run pytest 执行
• 提交前跑 ruff check --fix && ruff format && pytest

关键细节：用 Ruff 做格式化和 linting 合一，比 black + flake8 组合更现代，也更符合 AI 生成代码的特点。

环境变量处理：AI 的盲区

AI 写代码经常忽略环境变量的正确加载方式。smith-python 的推荐模式：

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    api_key: str
    timeout: int = 30

    class Config:
        env_file = ".env"

# 必须在 import 库之前设置
os.environ["LIBRARY_CONFIG"] = "value"
import library  # 现在能看到配置了

还有一点很关键：必须用 extra= 参数做结构化日志，不能用 %-style 格式化——这对可观测性至关重要。

安装使用

smith 框架所有 Skill 都遵循 agentskills.io 标准，跨平台兼容，支持 Claude Code、Cursor、Windsurf 等工具：

git clone https://github.com/tianjianjiang/smith.git $HOME/.smith
ln -sf $HOME/.smith $HOME/.claude/skills

之后 Claude Code 会自动发现并激活 smith-python——当你处理任何 Python 文件时，Skill 自动触发，给你对应的规范和检查。

47 个 Skill 打底，从 Python 开发（smith-python）到测试（TDD、pytest 模式）到调试（smith-validation 用的科学方法论）到计划追踪——整套体系是少数个人开发者维护、但质量极高的框架。

如果你用 Claude Code 写 Python，这个 Skill 值得直接装上。

GitHub：https://github.com/tianjianjiang/smith

GitHub: https://github.com/tianjianjiang/smith