Claude Code 能读取代码，却不一定知道团队使用 uv 还是 Poetry、测试命令是否需要额外参数，也无法凭空判断哪些目录禁止修改。CLAUDE.md 的作用，就是把这些仓库之外的隐性知识变成明确、可执行的协作说明。
一份有效的文件不需要很长。关键是分清全局、项目和本地三类信息，并写下能够直接验证的命令与约束。
三层配置分别解决什么问题
可以把 CLAUDE.md 信息拆成三个作用域：
- 全局配置：记录个人在所有项目中的通用偏好，例如默认使用简体中文解释、优先运行现有格式化工具、修改后报告测试结果。
- 项目配置：记录仓库共享事实，例如 Python 版本、依赖管理器、测试入口、目录职责和提交规范。这部分适合进入版本控制。
- 本地配置：记录只适用于当前机器的命令、端口或环境差异，例如私有镜像、容器名称以及本地数据库地址。它通常不应提交。
具体文件名和加载行为可能随 Claude Code 版本变化，使用前应结合当前版本文档确认。常见实践是使用全局 ~/.claude/CLAUDE.md、仓库根目录的 CLAUDE.md，以及仅供个人使用的 CLAUDE.local.md。
三层内容应当逐渐具体：全局文件表达稳定偏好，项目文件描述团队共识，本地文件只覆盖机器差异。不要把同一段规则复制三遍，否则规则更新后很容易互相矛盾。
项目文件要写成可执行说明
含糊的指令很难验证。例如“保证代码质量”没有说明质量门槛，也没有告诉代理该运行什么。更有效的写法是：
# Project Instructions
## Runtime
- Use Python 3.12.
- Manage dependencies with uv. Do not run pip directly.
- Install dependencies with: uv sync --all-extras
## Verification
Run these commands after changing Python code:
1. uv run ruff check .
2. uv run ruff format --check .
3. uv run pytest -q
For a focused test, run:
uv run pytest tests/test_orders.py -q
## Code conventions
- Add type hints to new public functions.
- Use pathlib instead of os.path in new code.
- Keep HTTP handlers thin; place business logic under src/services/.
- Reuse existing exception types from src/errors.py.
## Change boundaries
- Do not edit files under migrations/ unless the task explicitly requires a migration.
- Do not modify generated files under src/generated/.
- Never commit .env files, credentials, or access tokens.
这段内容同时回答了几个实际问题：使用哪个运行时、如何安装依赖、修改后执行哪些检查、代码应该放在哪里，以及哪些文件不能碰。命令可以直接复制到终端验证，因此规则不会停留在口号层面。
还可以补充仓库结构，但只记录容易误判的部分：
## Repository map
- src/api/: FastAPI routes and request validation
- src/services/: business workflows
- src/repositories/: database access
- tests/unit/: tests without network or database access
- tests/integration/: tests requiring PostgreSQL
不必逐项解释显而易见的目录。CLAUDE.md 是操作手册，不是完整架构文档。
可以这样搭建一套 Python 项目配置
下面的命令会创建一个全局文件和一个项目文件。执行前把示例中的工具、Python 版本和测试命令改成项目实际配置：
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md <<'EOF'
# Personal Defaults
- Explain non-trivial implementation decisions briefly.
- Inspect existing project commands before adding new tooling.
- Keep changes scoped to the requested behavior.
- Report which checks were run and whether they passed.
EOF
cat > CLAUDE.md <<'EOF'
# Project Instructions
## Environment
- Python version: 3.12
- Dependency manager: uv
- Install dependencies: uv sync --all-extras
## Required checks
- Lint: uv run ruff check .
- Format check: uv run ruff format --check .
- Test: uv run pytest -q
## Implementation rules
- Put application code under src/.
- Add tests for behavior changes.
- Preserve public API compatibility unless the task explicitly allows a breaking change.
- Read pyproject.toml before changing dependencies or tool configuration.
## Safety
- Never print or commit secrets.
- Do not edit generated files.
- Ask before deleting data or rewriting migration history.
EOF
如果当前机器必须通过内部镜像安装依赖，可以把差异写入本地文件：
cat > CLAUDE.local.md <<'EOF'
# Local Machine Notes
- Start PostgreSQL with: docker compose up -d postgres
- The local API port is 8010.
- Use the company package mirror configured in the current shell.
- Do not place mirror credentials in tracked files.
EOF
printf '\nCLAUDE.local.md\n' >> .git/info/exclude
这里使用 .git/info/exclude，可以只在当前克隆中忽略文件，不必修改团队共享的 .gitignore。如果团队已经统一忽略 CLAUDE.local.md，则不需要重复设置。
创建完成后，不要只检查文件是否存在，还要验证里面的命令：
uv sync --all-extras
uv run ruff check .
uv run ruff format --check .
uv run pytest -q
命令失败时，应修正文档或项目配置。不要把一条只有部分开发者能够运行的命令写成全员必须遵守的事实。
哪些内容不应该写进去
CLAUDE.md 会影响代理后续的分析和修改，因此错误规则会被稳定地重复执行。常见风险包括：
- 写入令牌、密码、私有镜像凭据或客户数据。
- 要求跳过测试、禁用类型检查，或者默认使用破坏性命令。
- 记录已经废弃的脚本名称和目录结构。
- 塞入整篇设计文档，导致关键命令被大量背景文字淹没。
- 使用“尽量保持整洁”之类无法验证的措辞。
- 把个人编辑器偏好写入团队共享文件。
涉及删除数据库、重写迁移历史、推送分支或发布生产环境时，建议明确要求先获得人工确认。CLAUDE.md 可以减少重复沟通，但不应绕过权限控制、代码审查和 CI。
提交前的检查清单
一份实用的 CLAUDE.md 通常能让新加入项目的工程师也回答以下问题：
- 应该用什么命令安装依赖？
- 单元测试、集成测试、lint 和格式检查分别如何运行？
- 哪些目录承载业务逻辑，哪些文件由工具生成？
- 修改哪些区域需要额外确认？
- 哪些规则属于团队共识，哪些只是本地差异？
- 文档中的每条命令现在还能成功执行吗？
从十几行高频规则开始，比一次写出庞大的说明更可靠。每当 Claude Code 重复犯同一种、且无法从代码本身推断的错误时，再把对应约束加入合适的作用域。这样维护出来的 CLAUDE.md 才会持续反映真实工程流程，而不是逐渐失效的提示词仓库。