Claude Code 能读取代码，却不会天然知道团队习惯用 uv 还是 pip、测试入口是 pytest 还是包装脚本，也无法猜出哪些生成目录不能修改。CLAUDE.md 的作用，就是把这些需要反复说明的命令、约束和约定放进持久上下文。真正需要设计的不是“写多少”，而是“哪条规则应该放在哪一层”。
三层文件解决三类问题
可以把 CLAUDE.md 的内容分成全局、项目和本地三层：
| 层级 | 适合保存 | 不适合保存 |
|---|---|---|
| 全局 | 个人通用偏好、默认工具、沟通方式 | 某个仓库独有的命令 |
| 项目 | 团队共享的构建、测试、格式化和架构约束 | 个人路径、密钥、本机端口 |
| 本地 | 当前机器的环境差异、个人临时说明 | 应由整个团队遵守的规则 |
例如，全局层可以声明“修改 Python 文件后运行格式检查”，项目层再明确检查命令是 uv run ruff check .。本地层则可以说明某项集成测试依赖开发者机器上的服务。
这种拆分能避免两个常见问题：一份巨大文件混合所有上下文，以及把个人环境细节提交到仓库。具体文件位置和加载规则可能随 Claude Code 版本变化，落地前应以当前版本文档和团队约定为准。
好规则必须能直接执行
“确保代码质量”几乎没有操作价值。Claude Code 仍然需要判断该运行什么、成功标准是什么。更有效的写法应该给出准确命令、适用范围和禁止事项。
一份项目级 CLAUDE.md 可以这样实践：
# Project Instructions
## Environment
- Python version: 3.12.
- Use `uv` for dependency management.
- Install dependencies with `uv sync --all-groups`.
- Run Python commands through `uv run`; do not call the system Python directly.
## Validation
After changing Python code, run:
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/path/to/test_file.py -q`.
## Conventions
- Add type hints to public functions.
- Put application code under `src/` and tests under `tests/`.
- Do not edit files under `generated/`; regenerate them with `make generate`.
- Do not add a dependency until the standard library and existing dependencies have been considered.
## Change Boundaries
- Keep changes scoped to the requested behavior.
- Update tests when observable behavior changes.
- Never commit `.env`, credentials, or local database files.
这里每条指令都能回答一个工程问题：使用哪个解释器、如何安装依赖、修改后执行哪些检查、哪些目录不能手工编辑。相比堆叠编码哲学，这类信息更能减少错误操作。
建立一个可演练的三层示例
下面的命令会在临时目录中创建三份示例文件，不会修改真实配置。复制运行后，可以检查内容，再按当前 Claude Code 版本支持的路径迁移到实际环境。
set -eu
DEMO_DIR="$(mktemp -d)"
mkdir -p "$DEMO_DIR/global" "$DEMO_DIR/project"
cat > "$DEMO_DIR/global/CLAUDE.md" <<'EOF'
# Personal Defaults
- Prefer small, reviewable changes.
- Explain failed validation commands clearly.
- For Python projects, inspect `pyproject.toml` before choosing tools.
EOF
cat > "$DEMO_DIR/project/CLAUDE.md" <<'EOF'
# Project Instructions
- Use Python 3.12 and `uv`.
- Install dependencies with `uv sync --all-groups`.
- Run tests with `uv run pytest -q`.
- Run linting with `uv run ruff check .`.
- Keep source code in `src/` and tests in `tests/`.
EOF
cat > "$DEMO_DIR/project/CLAUDE.local.md" <<'EOF'
# Local Notes
- The integration API is available at `http://127.0.0.1:8081` on this machine.
- Skip network-dependent tests when the local API is not running.
- Do not commit this file.
EOF
find "$DEMO_DIR" -type f -name 'CLAUDE*.md' -print -exec sed -n '1,120p' {} \;
printf '\nDemo created at: %s\n' "$DEMO_DIR"
示例中的本地地址只是实践假设，需要替换为自己的环境。团队还应把本地文件名加入 .gitignore，前提是该文件确实不需要共享：
printf '\n# Claude Code local instructions\nCLAUDE.local.md\n' >> .gitignore
git diff -- .gitignore
追加前先检查现有 .gitignore，避免重复条目。任何令牌、密码或私钥都不应写入这些文件；“只在本地使用”也不能替代密钥管理。
写完后用任务验证，而不是只读一遍
CLAUDE.md 是否有效，要看 Claude Code 能否据此完成真实任务。可以选择三个小场景进行演练：
- 要求它定位并运行单个 Python 测试，观察是否使用项目指定的命令。
- 要求它修改一个函数，检查是否同时执行格式化、静态检查和测试。
- 要求它调整生成代码，确认它是否遵守“运行生成器、不要直接编辑”的边界。
如果指令没有生效，先检查规则是否含糊、互相冲突或藏在过长段落中。不要立刻增加更多文字；通常应把抽象句子改成命令，删除重复内容，并把规则移动到正确层级。
采用时的检查清单
一份可靠的 CLAUDE.md 应该简短但可操作：命令能复制执行，目录和工具名称准确，禁止事项说明原因，项目规则可以由团队审查。全局层保持通用，项目层进入版本控制，本地层只描述机器差异且不包含秘密。
还要把它当作代码维护。升级 Python、替换包管理器或修改 CI 后，应同步更新命令。过期指令比缺少指令更危险，因为它会稳定地把自动化引向错误路径。