CLAUDE.md 文件完全指南

一、概述

CLAUDE.md 是放置在项目根目录下的 Markdown 格式文件，它的作用是作为 Claude Code 的项目级指令文档。你可以把它理解成给 AI 助手看的一份"项目手册"——就像新员工入职第一天收到的那本手册一样，它告诉 Claude 这个项目的所有重要信息，包括技术栈、代码规范、目录结构以及各种开发约定。

这份文件有着极高的优先级。每次你启动一个新的 Claude Code 对话时，系统都会自动读取项目根目录下的 CLAUDE.md 文件，将其内容注入到系统提示（System Prompt）中。这意味着 Claude 从一开始就了解你的项目背景，无需你在每次对话中重复说明项目信息。

CLAUDE.md 与项目中的 README.md 有着本质的区别。README.md 是写给人类开发者看的，它侧重于项目的用途、安装方式和基本使用方法。而 CLAUDE.md 是写给 AI 助手看的，它侧重于AI在协助开发时所需遵循的规则、约定和上下文信息。简单来说：README 告诉人如何用这个项目，CLAUDE.md 告诉 AI 如何帮你开发这个项目。

通过合理编写 CLAUDE.md，你可以让 Claude Code 更准确地理解项目上下文，遵循团队约定，从而大幅提升 AI 编程助手的实际工作效率。

二、文件作用与价值

CLAUDE.md 文件在 Claude Code 的使用体验中扮演着至关重要的角色。它不仅仅是一份文档，更是连接 AI 助手与项目实际需求的桥梁。充分理解它的价值，有助于你更有动力去维护这份文件。

• 提供项目上下文：CLAUDE.md 可以完整描述项目的技术栈、架构设计、目录结构以及数据流关系。当 Claude 在生成代码或分析问题时，这些上下文信息帮助它做出更符合项目实际情况的判断和决策。
• 定义行为规范：你可以在文件中明确代码风格（如缩进方式、命名约定）、测试要求（如单元测试覆盖率标准）、提交信息格式等。这确保了 AI 助手生成的所有内容都符合团队既定的开发标准。
• 减少重复说明：没有 CLAUDE.md 时，你需要在每次对话中都向 Claude 解释项目的技术栈和基本规则。有了这份文件，这些信息会自动加载，你不再需要重复交代同样的背景信息。
• 保证一致性：当团队中的多个开发者都使用 Claude Code 时，统一的 CLAUDE.md 能确保所有成员获得一致的 AI 辅助体验。无论谁在何时使用，Claude 的行为标准都是相同的。
• 加速上手：新成员加入项目时，Claude Code 会自动读取 CLAUDE.md 建立上下文。新人不需要额外花费时间向 AI 解释项目背景，上手速度显著提升。

三、存放位置与加载机制

了解 CLAUDE.md 的存放位置和加载机制是正确使用它的前提。文件必须放置在正确的位置才能被 Claude Code 自动识别和加载，否则你将无法享受到自动化配置带来的便利。

配置优先级（从高到低）：

版本控制建议：CLAUDE.md 应当提交到 Git 仓库中。这样做有三大好处：第一，团队所有成员都能共享同一份 AI 行为配置，确保协作一致性；第二，文件的变更历史会被 Git 完整记录，方便追踪谁在何时修改了哪些 AI 指令；第三，新成员克隆仓库后自动获得配置，无需额外设置。

四、核心内容模块

一个高质量的 CLAUDE.md 应当覆盖以下几个核心内容模块。这些模块共同构成了 AI 助手理解和参与项目开发的完整上下文框架。不同类型的项目可以根据自身特点对这些模块进行增删调整。

4.1 项目概述

项目概述是 CLAUDE.md 的第一部分，它应当用 2-4 句话简要说明项目的名称、核心功能、目标用户和使用场景。这部分信息帮助 Claude 快速建立对项目的整体认知。此外，还应当标明项目的当前状态，例如"开发中"、"维护中"或"已上线"，以便 Claude 根据项目阶段调整辅助策略。

4.2 技术栈

技术栈信息是 CLAUDE.md 中最重要的内容之一。你需要详细列出项目所使用的编程语言及版本号、框架和库的具体版本、构建工具和包管理器、数据库和中间件方案，以及部署平台和环境信息。版本号尤其重要——如果项目使用的是 Python 3.12 而非 3.10，Claude 在生成依赖配置和语法代码时会据此做出正确的选择。

4.3 代码规范

在代码规范部分，你需要明确定义项目使用的编码风格约定。这包括命名约定（使用 camelCase 还是 snake_case）、缩进和格式化规则（例如使用 4 个空格还是 2 个空格）、文件和目录的组织方式、注释规范的要求，以及 Linting 和格式化工具的配置。明确的代码规范是保证 Claude 生成的代码与项目现有代码风格一致的关键。

4.4 开发流程

开发流程部分指导 Claude 在参与项目开发时遵循团队的工作流。内容包括分支策略（如 Git Flow 或 GitHub Flow）、提交信息的格式要求（如 Conventional Commits）、Code Review 的流程和标准、测试要求（单元测试框架、集成测试覆盖标准），以及 CI/CD 流程的说明。当 Claude 需要创建提交信息、编写测试或发起 Pull Request 时，这些规范会直接影响其输出。

4.5 重要约定

重要约定涵盖项目中各种非功能性的开发约定。这包括环境变量的命名和使用方式、日志输出的格式和级别规范、错误处理的标准模式、API 设计的接口约定（如 RESTful 风格或 GraphQL 规范），以及数据库迁移的策略。这些约定虽然不直接体现在代码功能中，但对项目的可维护性和团队协作至关重要。

4.6 常用命令

常用命令部分列出项目开发过程中最频繁使用的终端命令。这包括如何安装依赖、启动本地开发服务器、运行不同类别的测试、执行构建和部署操作，以及各种常用脚本的调用方式。将这些命令写入 CLAUDE.md 后，Claude 可以直接执行它们，无需你每次手动输入或回忆命令格式。

五、编写示例

下面是一个完整的 CLAUDE.md 示例文件。你可以基于这个模板进行修改和扩展，以适配自己项目的实际需求。注意观察每个部分的内容深度和信息组织方式。

六、最佳实践

编写一份高质量的 CLAUDE.md 不仅仅是罗列信息，更需要遵循一系列经过实践验证的最佳原则。以下最佳实践来自大量 Claude Code 用户的真实经验总结。

• 简洁但完整：CLAUDE.md 应当只包含 AI 助手在开发中真正需要的信息。避免填充无意义的背景故事或与编程无关的内容。每一行都应当是"可执行的指令"或"有用的上下文"。一个合理的 CLAUDE.md 通常在 100-300 行之间。
• 定期更新：项目随着时间推移会不断演进——技术栈升级、架构调整、流程优化，这些变化都应当同步反映到 CLAUDE.md 中。建议将 CLAUDE.md 的更新纳入项目的常规维护任务，在每次重大变更后及时更新文件内容。
• 可执行的指令：CLAUDE.md 中的指令应当是 Claude 能够直接理解和执行的命令或规则。例如，与其写"请使用良好的编码风格"，不如写"使用 Black 格式化代码，行宽 88 字符，所有函数必须包含类型注解"。明确的指令产生明确的行为。
• 明确的规则：避免使用模糊和主观的表述。像"代码应当易于阅读"或"尝试编写高质量的测试"这样的描述缺乏可操作性。应当代之以具体的规则，如"每个 public 函数必须有 docstring"或"测试覆盖率不低于 80%"。
• 用示例说话：在定义代码规范时，提供一个符合规范的代码示例往往比单纯描述规范更有效。Claude 能够通过示例快速理解预期的模式，并在生成代码时模仿这些示例的风格。
• 先通用后具体：在组织 CLAUDE.md 的内容时，将最通用、最稳定的信息放在前面（如项目概述和技术栈），将较具体、可能变化的信息放在后面（如常用命令和操作细节）。这种排列方式符合阅读习惯，也有利于 Claude 优先处理最重要的指令。
• 定期审查：使用内置的 revise-claude-md 技能定期审查和更新 CLAUDE.md 文件。这个技能会分析当前对话的内容，识别出有用的新信息，并建议将它们补充到文件中。
• 团队共识：CLAUDE.md 反映的是团队的开发约定，而非个人的偏好。在编写或修改 CLAUDE.md 之前，应当与团队成员达成一致。如果团队使用统一的 CLAUDE.md，所有成员就能获得一致的 AI 辅助体验。

七、使用 init 命令初始化

对于新项目或不熟悉 CLAUDE.md 格式的开发者，Claude Code 提供了一个非常实用的 init 命令。通过这个命令，你可以无需手动编写任何内容就能获得一份初始的 CLAUDE.md 文件。

init 命令的工作原理

当你在项目根目录下运行 claude init 命令时，Claude Code 会自动执行以下步骤：首先扫描项目的目录结构，了解文件组织方式；然后分析关键配置文件（如 package.json、pyproject.toml、Dockerfile 等），识别项目的技术栈和框架；接着检测项目的代码风格和常用模式；最后，综合所有这些信息，生成一份结构完整、内容准确的初始 CLAUDE.md 文件。

生成后的手动优化建议

claude init 生成的 CLAUDE.md 是一个很好的起点，但它并不能完美覆盖所有项目特有的约定和规范。在生成初始版本后，建议你人工检查并补充以下内容：项目特有的业务规则和逻辑约定、团队内部的工作流和沟通规范、自定义的脚本和工具链使用说明，以及任何你认为重要的但 init 无法自动识别的内容。

后续更新维护

随着项目的持续开发，CLAUDE.md 也需要同步更新。除了手动编辑外，你可以利用 revise-claude-md 技能来完成这一任务。每次完成一个对话后，运行这个技能，它会回顾本次对话中讨论的与项目配置相关的内容，并自动建议对 CLAUDE.md 的修改。这大大降低了维护成本，确保文件始终与项目保持同步。

八、高级技巧

对于已经熟悉 CLAUDE.md 基础用法的进阶用户，以下高级技巧可以帮助你进一步发挥 CLAUDE.md 的潜力，实现更精细化的 AI 行为控制。

多级指令：根目录 CLAUDE.md + 子目录的 .claude.md

除了项目根目录的 CLAUDE.md 外，你还可以在项目的子目录中放置 .claude.md 文件（注意文件名前有一个点号）。当你在子目录中启动对话或涉及该子目录的文件时，Claude 会同时加载根目录的 CLAUDE.md 和对应子目录的 .claude.md。这种方式适用于大型项目中不同模块有各自独立规范的情况，可以实现指令的作用域隔离。

条件指令：针对不同类型的任务

在 CLAUDE.md 中，你可以编写针对特定任务类型的条件指令。例如，当 Claude 被要求编写测试时，你可以指定测试框架和风格；当涉及数据库迁移时，指定迁移工具和命名规范。通过在文件中分类组织规则，Claude 可以根据当前任务的性质自动选择应用哪组规则，实现更加智能化的行为控制。

安全约束：限制 AI 的操作范围

CLAUDE.md 是定义安全边界的最佳场所。你可以在文件中明确声明 Claude 不允许执行的操作，例如"不允许修改 .env 文件"、"不允许删除数据库中的数据"或"不允许向生产环境直接部署代码"。这些安全约束会被系统提示接受，从而在源头上防止 AI 执行越权操作。结合 settings.json 中的权限配置，可以形成多层的安全防护。

模板复用：跨项目共享配置

如果你的团队维护着多个相似类型的项目（如多个微服务），可以考虑创建一个 CLAUDE.md 模板。模板中包含了所有项目通用的规则和规范，每个项目只需要在模板基础上添加自己的特有信息即可。这种方式可以显著降低跨项目的维护成本，同时确保所有项目遵循统一的基础规范。

版本对比：用 Git 追踪变更历史

由于 CLAUDE.md 建议纳入 Git 版本管理，你可以利用 Git 的 diff 和 log 命令来追踪文件的变更历史。当 CLAUDE.md 中的某个指令导致 AI 行为异常时，你可以通过 git diff 快速定位最近的修改，及时回滚或修正问题。这也是为什么建议将 CLAUDE.md 放在 Git 仓库中进行管理的另一个重要原因。

九、常见问题

在实际使用 CLAUDE.md 的过程中，开发者可能会遇到一些典型问题。以下是常见问题的诊断和解决方案。

• CLAUDE.md 不生效：最常见的原因是文件放置位置不正确。请确认 CLAUDE.md 恰好位于项目的根目录下，与 .gitignore 文件同级。如果文件在子目录中或者在项目目录之外，Claude Code 将无法找到它。另一个可能的原因是文件名大小写——在 Linux/macOS 系统中文件名是大小写敏感的，请确保文件名完全为 CLAUDE.md。
• 指令冲突：当多级配置（CLAUDE.md、.claude/settings.json、~/.claude/settings.json）中存在冲突时，理解优先级关系至关重要。记住 CLAUDE.md 的优先级最高，它会覆盖 settings.json 中的同名设置。如果发现 AI 的行为不符合预期，先检查各级配置是否出现了互相矛盾的指令。
• 内容过时：CLAUDE.md 最常见的"病"就是内容过时。项目依赖升级了但文件没更新，目录结构调整了但文件没更新，这些都会导致 AI 给出错误的信息。解决方案是将 CLAUDE.md 的更新纳入开发流程的常规环节，并在每次重大变更后立即更新文件。使用 revise-claude-md 技能可以辅助这一过程。
• 篇幅过长：有些项目的 CLAUDE.md 可能因为包含过多细节而变得非常冗长。过长的文件不仅难以维护，还可能导致 AI 在加载时"淹没"在信息中，抓不住重点。解决方案是对内容进行分层——最核心、最常用的规则放在 CLAUDE.md 中，而专门的、很少变化的细节可以放在项目文档中通过引用方式引入。