Python 数据与后端项目 CLAUDE.md 模板

适用场景

Python 项目里，智能体最容易出事的地方不是语法，而是数据：覆盖了原始数据文件、对生产库跑了迁移、把几百兆的 CSV 整个读进上下文、每次运行结果不一致。这份模板把这些红线集中写出来。

它同时覆盖两类项目：有 API 和数据库的后端服务，以及 notebook 加脚本的数据分析项目。用不到的小节直接删掉。

模板

保存为项目根目录的 CLAUDE.md。示例里的 uv、FastAPI、ruff 都只是举例，请换成你实际使用的工具：

# 【项目名】（Python）

Python 3.12；依赖管理 uv（以 `pyproject.toml` 为准）；Web 框架 FastAPI；ORM SQLAlchemy 2 + Alembic；数据处理 pandas。

## 常用命令
- 安装：`uv sync`
- 启动服务：`uv run fastapi dev app/main.py`
- 全部测试：`uv run pytest -q`
- 单个测试：`uv run pytest tests/test_x.py::test_name -q`
- 格式化与 Lint：`uv run ruff format . && uv run ruff check .`
- 类型检查：`uv run mypy app`

## 目录与分层
- `app/api/`：路由层，只做参数校验和调用 service，不写业务逻辑。
- `app/services/`：业务逻辑，函数要有类型标注。
- `app/models/`：ORM 模型。
- `migrations/`：Alembic 迁移，自动生成后必须人工审读再提交。
- `notebooks/`：探索性分析，结论要沉淀进 `app/` 或 `scripts/`，不要让正式代码依赖 notebook。
- `data/raw/`：原始数据，只读。

## 代码约定
- 公共函数必须有类型标注和一行 docstring。
- 异常使用项目自定义的 `AppError` 子类，不要裸 `except:`。
- 配置只从环境变量读取，统一经过 `app/settings.py`，不要散落的 `os.getenv`。

## 数据处理红线
- 绝不修改或删除 `data/raw/` 下任何文件；清洗结果写到 `data/processed/`。
- 查看大文件先用 `head`、`df.head()`、`df.sample()`，不要整份读入后打印。
- 随机操作必须固定种子，保证重复运行结果一致。
- 数据中可能含个人信息：不要打印、不要写进日志、不要粘贴进提交信息。

## 数据库
- 表结构变更只通过 Alembic 迁移，不直接改库。
- 迁移要写 downgrade，并说明是否可逆、是否锁表。
- 只连开发库；任何指向生产的连接串都不要使用，也不要写进代码。

## 验证
- 改动完成后依次运行 ruff、mypy、pytest，汇报实际结果。
- 修 bug 先写一个会失败的测试，再修复，最后确认它变绿。

怎么用 / 怎么改

• 纯数据分析项目可以删掉「目录与分层」里的 API 相关行，把「数据处理红线」放到最前面。
• 使用 pip、poetry 或 conda 的项目，把命令统一替换，并明确写出「不要使用 pip install 直接安装」之类的限制，避免智能体绕开你的依赖管理。
• 虚拟环境激活方式、需要的本地服务（数据库、Redis）都属于「读代码看不出来」的信息，必须写上启动方法。
• 如果数据库规则很长，拆成 .claude/rules/database.md，并用 paths 限定到 migrations/**/*.py 与 app/models/**/*.py，只在碰这些文件时加载。

常见问题或注意事项

• 红线需要硬保障。 CLAUDE.md 只是建议。想真正禁止读写某些路径，请在 .claude/settings.json 里配置权限规则（比如对 data/raw 设置编辑拒绝），详见本站「settings.json 权限白名单」模板。
• 生产库凭据绝不放进项目。 即使写了「不要连生产」，只要凭据在环境里，风险就在。给智能体用的环境只放只读的开发库账号。
• Claude 找不到测试怎么跑。 通常是命令里少了前缀（比如 uv run）。把能跑通的完整命令原样写进去，再让它试一次。
• 迁移文件自动生成后不要直接信任。 让 Claude 把生成的 SQL 和你的模型改动逐项对照，确认没有多余的删列、删表操作。