第 3 章 · 项目上下文与 CLAUDE.md
本章目标：理解 CLAUDE.md 的作用与加载层级，学会编写有效的项目指令文件，掌握嵌套优先级规则。
3.1 为什么需要 CLAUDE.md
每次启动 Claude Code 时它对项目一无所知。没有 CLAUDE.md，它会花大量 token 探索目录结构、猜测技术栈、试错构建命令。有了 CLAUDE.md，它直接获得：
- 项目是什么（技术栈、框架版本）
- 怎么构建和测试
- 代码风格约定
- 不能违反的硬约束
ROI 最高的第一步
在仓库根目录放一个 CLAUDE.md 文件是 harness engineering 中投入产出比最高的操作——一个文件可能比升级到更贵的模型更有效。
3.2 加载层级
Claude Code 按以下优先级加载指令文件（就近覆盖远端）：
text
1. 企业策略 /Library/Application Support/ClaudeCode/CLAUDE.md (最高)
2. 用户全局 ~/.claude/CLAUDE.md
3. 项目根目录 ./CLAUDE.md 或 ./.claude/CLAUDE.md
4. 子目录 src/components/CLAUDE.md (仅当读取该目录下的文件时)
5. 本地覆盖 ./.claude/CLAUDE.local.md (不提交到 Git)嵌套优先级示例
text
my-project/
├── CLAUDE.md ← "使用 pnpm 作为包管理器"
├── frontend/
│ └── CLAUDE.md ← "前端测试用 vitest"
└── backend/
└── CLAUDE.md ← "后端测试用 pytest"当前端任务时，两个文件都生效：pnpm + vitest。 当后端任务时：pnpm + pytest。
3.3 编写有效的 CLAUDE.md
官方建议 约 100 行以内——它是"地图"而非"百科全书"。超过的内容拆到 docs/ 目录让 agent 按需读取。
markdown
# CLAUDE.md
## Project Overview
E-commerce API built with FastAPI + PostgreSQL.
## Tech Stack
- Python 3.12, FastAPI 0.141, SQLAlchemy 2.0 (async)
- PostgreSQL 16, Redis 7
## Commands
- Install: pip install -e ".[dev]"
- Test: pytest tests/ -x --tb=short
- Lint: ruff check src/
- Type check: mypy src/ --strict
- Run dev: uvicorn app.main:app --reload
## Code Style
- Use Annotated dependencies for DI
- All API responses use Pydantic response_model
- Error handling via custom exceptions in app/exceptions.py
## Hard Constraints
- Never modify alembic/migrations manually
- Always run tests before marking task complete3.4 与 AGENTS.md 的兼容性
Claude Code 也支持读取 AGENTS.md 文件（开放标准）。如果两者同时存在，两者都会被加载。推荐做法：
| 场景 | 建议 |
|---|---|
| 只用 Claude Code | 用 CLAUDE.md |
| 多工具团队 | 用 AGENTS.md（Codex/Cursor 等也认） |
| 需要差异化指令 | 同时维护，CLAUDE.md 放 Claude 特有配置 |
本章小结
- CLAUDE.md 告诉 agent 项目全貌和约束，ROI 极高；
- 五层加载优先级：企业 > 全局 > 项目 > 子目录 > 本地；
- 约 100 行以内，超出的拆到 docs/ 按需读；
- AGENTS.md 兼容，可共存。
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. 当项目根目录的 CLAUDE.md 说"用 npm"，而子目录 CLAUDE.md 说"用 pnpm"，处理该子目录下文件时会怎样？
2. 官方建议 CLAUDE.md 的理想长度是多少？
3. .claude/CLAUDE.local.md 的用途是什么？
4. 如果项目中同时有 CLAUDE.md 和 AGENTS.md，会发生什么？
🛠️ 动手实践
- 为你的项目编写一份 CLAUDE.md，包含构建命令和技术栈。
- 在子目录中创建嵌套 CLAUDE.md，设置不同的测试命令，验证就近优先。
- 创建
.claude/CLAUDE.local.md写入个人偏好，确认不被 Git 追踪。
完成后进入第 4 章。