CLAUDE.md是Claude Code的项目级指令文件，放置于项目根目录或~/.claude/目录中。当开发者在项目目录中启动Claude Code时，Claude Code会自动读取该文件，从中获取项目的上下文信息、编码规范、约束条件和自定义Skill定义。CLAUDE.md采用标准的Markdown格式，同时支持一套特殊的语法扩展——主要是YAML格式的Skills定义块——使得Claude Code能通过斜杠命令快速调用项目特定的功能。
本质上，CLAUDE.md充当了"项目大脑"的角色，它告诉Claude Code这个项目是什么、代码怎么写、有哪些规则必须遵守，以及可以通过哪些快捷命令来执行常见任务。一个结构良好的CLAUDE.md能显著提升Claude Code在项目中的工作质量和效率。
一个标准的CLAUDE.md文件包含以下几个主要部分：
位于文件的开头部分，用自然语言描述项目的名称、定位、主要功能和技术栈。Claude Code通过这部分快速了解"这是一个什么项目"。例如可以说明项目是前端应用还是后端服务，使用什么框架和语言，主要的架构模式是什么。
定义代码风格、命名约定、架构规则和团队约定。例如变量命名采用camelCase还是snake_case，React组件使用函数式还是类组件，测试框架和覆盖率要求等。这部分可以引用项目中的.eslintrc、.prettierrc等配置文件。
这部分定义了Claude Code在执行操作时必须遵守的硬性规则。常见的约束包括：build command（构建命令，Claude Code在需要重新构建项目时会自动调用）、test command（测试命令，用于运行测试验证代码正确性）、lint command（代码检查命令）、format command（代码格式化命令）。这些约束确保AI生成的代码符合项目的质量要求。
Skills是CLAUDE.md最强大的特性之一。它允许开发者定义自定义的斜杠命令，通过简单的命令触发复杂的提示词模板。例如定义一个/test命令来运行测试并分析结果，或者定义一个/review命令来进行代码审查。Skills定义使用YAML格式，位于文件末尾的## skills节点下。
总结：CLAUDE.md的四大结构模块——项目概述（What）、编码规范（How）、约束条件（Rules）、Skills定义（Shortcuts）——共同构成了Claude Code高效工作的基础。
Skills定义是CLAUDE.md中最体现灵活性的部分。它采用YAML格式的数组结构，每个Skill包含以下几个字段：
| 字段名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| name | 字符串 | 是 | Skill的显示名称，在斜杠命令列表中会展示给用户 |
| command | 字符串 | 是 | 触发Skill的斜杠命令名称（不带斜杠前缀） |
| prompt | 字符串 | 是 | Skill执行时发送给Claude的提示词模板，支持多行文本 |
| description | 字符串 | 否 | 可选描述文本，帮助用户理解该Skill的用途 |
以下是一个完整的CLAUDE.md Skills定义示例：
在这个示例中，定义了两个Skill：运行测试（对应/test命令）和代码审查（对应/code-review命令）。每个Skill都包含一个多行的prompt模板，当用户在Claude Code中输入对应的斜杠命令时，对应的prompt会被发送给Claude，指导它以特定的方式完成任务。
CLAUDE.md支持多层级配置，在不同的位置放置CLAUDE.md文件可以控制不同的作用范围：
这种多层级设计非常灵活：团队可以在项目级CLAUDE.md中定义与项目紧密相关的Skill（如"部署到测试环境"、"运行项目特定测试"），而开发者可以在用户级CLAUDE.md中定义个人常用的通用Skill（如"创建React组件"、"编写API文档"）。两级合并后，开发者既能使用项目提供的标准化工具，又能保留个人工作流习惯。
实践建议：项目级CLAUDE.md应该只包含项目相关的内容，不要放入个人偏好。个人通用的Skills放在~/.claude/CLAUDE.md中，实现关注点分离。
编写高质量的CLAUDE.md需要遵循一些重要的原则，以下是经过实践检验的最佳实践：
CLAUDE.md不是文档手册，不需要面面俱到。聚焦于Claude Code实际需要的信息：项目的核心上下文、必须遵守的规则、和常用的操作命令。避免将整个项目的README内容复制进来，Claude Code会自动读取项目中的关键配置文件。
Skill的命令名称应该简洁、直观、符合直觉。使用连字符（-）分隔多个单词，保持团队内部统一的命名风格。例如run-tests比execute-all-unit-tests-and-integration-tests更合适。
建议为每个Skill添加description字段，哪怕只有一句话。当用户在Claude Code中输入斜杠时，description会作为命令的说明文字显示，帮助用户快速理解每个命令的用途。
Skill的prompt应该清晰明了，但不必事无巨细。过长的prompt反而会稀释关键信息。建议将prompt控制在合理长度，聚焦于任务的目标和输出格式要求。如果确实需要很长的指令，可以考虑拆分为多个Skill。
随着项目演进，一些Skill可能变得过时或不准确。建议定期审查CLAUDE.md中的Skills列表，删除不再需要的Skill，更新prompt中的项目特定信息（如文件路径、API地址等），确保每个Skill都能正常工作。
对于团队项目，建议创建一份标准的CLAUDE.md模板，包含项目通用的章节结构、编码规范和约束条件。每个开发者可以在此基础之上添加个人级别的Skills。这能确保所有团队成员使用一致的AI辅助工作流。
核心总结：优秀的CLAUDE.md = 简明扼要的项目概述 + 可执行的约束条件 + 精心设计的Skills命令集。它不是写一次就完事的文档，而是伴随项目持续进化的"AI协作手册"。