Appearance
Claude Code完整指南：CLAUDE.md文件详解
CLAUDE.md 是 Claude Code 在每个会话开始时自动读取的 Markdown 文件。它将 Claude Code 从通用 AI 助手转变为适合您项目的开发工具。
什么是 CLAUDE.md？
CLAUDE.md 是 Claude Code 在每个会话开始时自动读取的 Markdown 文件。在这个文件中，您可以编写说明、规则和偏好，Claude Code 会在整个后续交互过程中遵循它们。
核心价值：将 Claude Code 从通用 AI 助手转变为适合您项目的开发工具。
CLAUDE.md 的加载方式
Claude Code 通过分层加载模型读取内存和指令：
| 层级 | 位置 | 影响范围 |
|---|---|---|
| 用户级 | ~/.claude/CLAUDE.md | 影响所有项目 |
| 项目级 | 项目根目录的 CLAUDE.md | 影响当前仓库 |
| 子目录级 | 特定子目录中的 CLAUDE.md | 仅在该目录内生效 |
加载规则
- 启动时首先读取与当前工作目录相关的 CLAUDE.md 文件
- 用户级 ~/.claude/CLAUDE.md 作为更高级别默认首选项层
- 子目录内的 CLAUDE.md 只有实际从这些目录读取内容时才生效
- 多个 CLAUDE.md 同时活动时，最近范围规则优先级更高
冲突解决
最近范围原则：规则离当前任务越近，适用范围越窄，优先级通常越高。
例：用户级说用 4 空格缩进，项目级说用 2 空格，该项目内遵循 2 空格。
如何编写 CLAUDE.md
快速开始：使用 /init 命令
bash
$ claude > /init/init 会查看技术栈、目录结构和常用命令，生成一个基本起始框架。
第一次写作：从最有用的信息开始
最值得首先添加的信息类别：
| 类别 | 说明 |
|---|---|
| 常用命令 | 构建、测试、lint 和本地开发命令 |
| 项目特定约束和陷阱 | 哪些目录不能编辑、哪些表使用软删除 |
| 基本工作流程 | 分支命名、预提交检查、基准 PR 要求 |
| 基本架构上下文 | 每个目录的职责、模块分层边界 |
随着文件增长，使用 @imports 分割
markdown
# 项目说明
有关项目概述，请参见 @README.md。
有关可用命令和脚本，请参见 @package.json。
有关测试约定，请参见 @docs/testing.md。
有关 API 设计规则，请参见 @docs/api-guidelines.md。CLAUDE.md 的演变
通过协作问题持续改进
CLAUDE.md 后来添加的内容来自日常工作反复发现的具体协作问题：
| 问题 | 添加规则 |
|---|---|
| Claude Code 一直用 npm 而非 pnpm | 添加包管理器规则 |
| 测试文件放错目录 | 记录正确放置规则 |
| 编辑数据库模式文件忘记重建 | 写下依赖关系和构建步骤 |
使用 /reflection 进行定期回顾
每个会话结束时，要求 Claude Code 总结该轮协作中有哪些内容值得添加到 CLAUDE.md 中。
使用 Insights 报告进行优化
Insights 让您查看更长一段时间的使用情况，更容易看到哪些问题持续存在。
最佳实践
保持简洁，优先高价值信息
| 问题 | 说明 |
|---|---|
| 文件过长 | 消耗更多上下文，留给实际任务的空间更少 |
| 文件杂乱 | 模型可能视为低相关性背景材料 |
具体说明，让规则可执行
真正有帮助的是在可直接遵循的层面上写作：
- 测试应该使用哪个命令
- 哪些目录不能编辑
- 提交前是否必须运行 lint
- API 层属于哪个目录
- 在什么情况下必须添加测试
传达意图，而非仅规则列表
例：「不要修改 src/generated/ 下的文件」是规则，但进一步解释「这些文件从 OpenAPI 模式自动生成，真正来源是模式和生成工作流」，Claude Code 就能理解限制存在的原因。
使用渐进式披露
| 主文件保留 | 分割出去 |
|---|---|
| 最常见、稳定、跨任务信息 | 使用 @imports 或多级 CLAUDE.md |
安全提醒
永远不要在 CLAUDE.md 中放置 API 密钥、密码、令牌等机密，因为它通常会进入版本控制。
与其他 AI 编码工具对比
| 工具 | 文件名 | 设计思路 |
|---|---|---|
| Claude Code | CLAUDE.md | 注入模型的持久内存或上下文 |
| Gemini CLI | GEMINI.md | 注入模型的持久内存或上下文 |
| Codex / OpenCode / Droid | AGENTS.md | 向 AGENTS.md 靠拢 |
Claude Code 优势：分层加载和项目上下文管理方面有明显优势。
总结
| 要点 | 说明 |
|---|---|
| 核心价值 | 从通用助手转变为项目开发工具 |
| 加载方式 | 分层加载，最近范围优先 |
| 编写建议 | 从可用版本开始，通过协作不断添加、修剪、收紧 |
| 最佳实践 | 简洁、具体、传达意图、渐进披露 |
CLAUDE.md 值得认真理解：将项目经验转化为长期规则，让 AI 更一致地理解上下文。
关键词：CLAUDE.md, Claude Code配置, 分层加载, /init命令, @imports, /reflection
