CLAUDE.md 完整配置指南

# CLAUDE.md 完整指南

一个文件。在每次对话开始前加载。如果你正在使用 Claude Code，这里就是你前期配置投入回报最大的地方。

CLAUDE.md 是一个 Markdown 文件，Claude 会在每个会话开始时自动读取它。它存储了你原本需要在每个提示中重复说明的项目专属指令——代码结构、规范、工作流、风格偏好，一应俱全。

我已经对自己的 CLAUDE.md 配置迭代了一段时间。本指南涵盖了我在创建、组织、维护和演进这些文件方面积累的全部经验。如果你在使用其他 AI 编程工具，类似的概念同样适用于 AGENTS.md（这是 Cursor、Builder.io、Zed、OpenCode 等工具的等效文件）。

# 为什么你需要 CLAUDE.md 文件

Claude 每次会话开始时都没有上一次的任何记忆。它不知道你的代码风格偏好，不知道如何运行你的测试，不知道你的团队使用哪种分支命名规范，也不知道你的认证模块里有个奇特的变通方案。

结果就是你不断重复自己的说明。更糟糕的是，你忘记提及某些重要内容，然后花时间去修复那些没有遵循你规范的代码。

CLAUDE.md 解决了这个问题。Claude 会自动读取它，所以你的偏好可以跨会话持久保存。

# 如何创建 CLAUDE.md 文件

最快的入门方式是使用 `/init` 命令。在你的项目目录中运行它，Claude 会根据你的项目结构和检测到的技术栈生成一个 CLAUDE.md 起始文件。

有些人建议从头开始编写，但我会以 `/init` 生成的内容为起点，然后删除不需要的部分。删除比从零创建更容易。生成的文件往往包含一些显而易见、无需明确说明的内容，或者一些没有实际价值的填充文字。

你可能会想，为什么不直接保留生成器生成的所有内容？因为上下文空间是宝贵的。CLAUDE.md 中的每一行都在与你真正要求 Claude 完成的实际任务争夺注意力。

你可以将 CLAUDE.md 放在以下几个位置：

- 项目根目录：最常见的位置。将其提交到版本控制，让团队共享相同的上下文。

- `.claude/CLAUDE.md`：如果你偏好将配置文件放在子目录中，这是一个替代选项。

- `~/.claude/CLAUDE.md`：用户级默认配置，适用于你所有的项目。

对于不应纳入版本控制的个人偏好（你的编辑器习惯、你偏好的详细程度），请改用 `CLAUDE.local.md`。将其添加到 `.gitignore` 以使其不受版本控制。

文件名区分大小写。必须严格写作 `CLAUDE.md`（CLAUDE 大写，.md 小写）。Claude Code 在加载记忆文件时会查找这个特定的文件名。文档中没有明确说明这一点，但当我询问官方文档 AI 助手时，它确认记忆文件与技能文件一样适用大小写敏感规则。

# 如何组织 CLAUDE.md 文件的结构

这才是核心所在。文件里究竟应该包含哪些内容？

## 基本要素

**项目上下文**：这个项目是什么？用一句话为 Claude 定位。"这是一个集成了 Stripe 的 Next.js 电商应用"所传达的信息比你想象的要多。

**代码风格**：你的格式化和模式偏好。使用 ES modules 还是 CommonJS？偏好具名导出？要具体。"正确格式化代码"过于模糊。

**命令**：如何运行测试、构建、代码检查、部署。当你要求 Claude 运行这些操作时，它会使用这些确切的命令。

陷阱：项目特定警告。那个带有奇怪重试逻辑的身份验证模块。需要特定标头格式的 API 端点。那个永远不应该直接修改的文件。

## 完整示例

以下是 Next.js 项目的 CLAUDE.md 可能呈现的样子：

Claude 能高效处理这些内容，因为它使用了清晰的标题组织结构、便于快速浏览的项目符号，以及具体命令而非模糊指令。

## 应该有多长？

一般建议是 300 行以内。越短越好。上下文令牌是宝贵资源。

但我见过一些项目，更长的文件反而更合理。如果你的代码库有复杂的规范或不寻常的模式，预先加载这些上下文可以防止 Claude 做出错误假设，避免在纠正上浪费时间。

我的做法是只包含 Claude 在开始工作之前需要了解的内容。如果某些内容只在特定情况下才重要，我会将其保存在单独的文件中并加以引用。

## @imports 系统

CLAUDE.md 支持使用 `@path/to/file` 语法导入其他文件：

这对于保持主文件精简非常有用。将详细说明放在单独的 Markdown 文件中，然后引用它们。Claude 会在相关时拉取这些内容。

你可以从任何位置引用文件：

- 相对路径：@docs/style-guide.md

- 绝对路径同样有效

- 甚至可以是用户级文件：@~/.claude/my-preferences.md

导入支持递归，因此被引用的文件可以继续引用其他文件。请谨慎使用此功能，以避免创建错综复杂的引用迷宫。

我最终采用的模式是将核心内容保留在 CLAUDE.md 中，将详细的专题指导移至单独文件，通过 @imports 引用。

## 使用 .claude/rules/ 实现模块化规则

对于较大的项目，还有另一个选择：.claude/rules/ 目录。你可以将说明拆分成专注的规则文件，而不是用一个大文件包含所有内容。

.claude/rules/ 中的所有 Markdown 文件都会自动加载，优先级与主 CLAUDE.md 相同。无需导入，只需将文件放入其中即可生效。

当不同团队成员负责不同的规则集时，这种方式非常有效。前端团队维护 code-style.md，安全团队维护 security.md。没有人需要在一个庞大的文件中处理合并冲突。

我目前还不需要这个功能。我的项目规模还不足以将规则拆分到多个文件中。但如果你所在的团队规模较大且职责领域各异，这种结构就很有意义了。

## 子目录 CLAUDE.md 文件

层级体系还有最后一层：项目子目录中的 CLAUDE.md 文件。

当 Claude 读取子目录中的文件时，它会自动识别该子目录树中的任何 CLAUDE.md。这些文件不会在启动时加载，只有当 Claude 正在处理代码库的该部分时才会被加载。

这对单体仓库或具有独立模块的项目非常有用。你的 /api 文件夹可以有自己的 CLAUDE.md，包含 API 特定规范。你的 /packages/ui 文件夹可以有不同的组件开发规则。Claude 根据其工作位置加载相关上下文。

# 如何维护你的 CLAUDE.md 文件

CLAUDE.md 不是一次性设置完就可以置之不理的产物。你的项目在演进，你的偏好在变化，这个文件也应该随之更新。

## 在工作过程中添加说明

当Claude做出你想纠正的假设时，不要只是在当下修正它。告诉Claude把它添加到你的CLAUDE.md中。

我经常这样做。Claude建议用console.log调试，但我想用logger。与其只纠正一次，我会说"添加到我的CLAUDE.md：始终使用logger而不是console.log。"这条指令会在未来的会话中持续生效。

这让你的CLAUDE.md有机地成长。不必试图预先想到所有事情，而是在事情发生时捕捉经验教训。这就像在会议中做笔记，只不过这些笔记真的会被用到。

注意：早期版本的Claude Code有一个 `#` 键盘快捷键用于添加指令。该功能在2.0.70版本中被移除。目前的做法是直接让Claude编辑你的CLAUDE.md。（https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md）

## 定期审查

每隔几周，我会让Claude审查并优化我的CLAUDE.md。随着时间推移，指令会不断积累。有些会变得冗余，有些会与新添加的指令相冲突。

一句简单的"审查这份CLAUDE.md并提出改进建议"就能暴露这些问题。删除过时的内容，合并冗余的内容，澄清模糊的内容。

这听起来像是维护负担。确实如此。但比起在每次会话中重复自己，或修复无视你的规范所产生的代码，这点负担要小得多。

## 为关键指令添加强调

对于必须严格遵守的规则，强调词有助于引起注意。比如"重要：切勿直接修改migrations文件夹"或"你必须在提交前运行测试"。

不要指望这是万无一失的。Claude仍然可能越过这些界限，尤其是在对话变得越来越长、上下文越来越拥挤的时候。根据我的经验，这样做能提高Claude注意到这些指令的概率，但并不是绝对保证。

要谨慎使用。如果所有东西都被标记为"重要"，那就什么都不重要了。

# 如何随时间改进你的CLAUDE.md

最有价值的更新往往来自代码审查。

当PR揭示出某个未被记录的规范，或审查者发现了违反模式的情况时，这就是一个信号。把它添加到CLAUDE.md中。同样的错误就不会再发生。

如果你正在使用Claude Code的GitHub Action（通过/install-github-action进行设置），你可以在PR评论中直接@claude来进行这些更新。比如"@claude添加到CLAUDE.md：永远不要使用枚举，始终优先使用字符串字面量联合类型。"Claude会更新文件并将变更作为PR的一部分提交。Boris Cherny分享了这个工作流，它已经成为我思考CLAUDE.md维护方式的一部分。（https://x.com/bcherny/status/2007179842928947333）

这创造了一个反馈循环：真实世界中的问题指导你的指令，而指令又能预防未来的问题。你的CLAUDE.md成为一份活文档，记录着你的团队积累的知识。

我把它看作一个代码库本身。你不会第一次就写出完美的代码（也许你会）。你会重构，你会改进。你的CLAUDE.md值得同样的对待。

# CLAUDE.md最佳实践

- 以一句话开头，说明项目是什么

- 让代码风格偏好具体且可操作

- 包含关键命令（测试、构建、lint、部署）

- 充分描述注意事项，以真正预防错误

- 保持在300行以内，或确保每一行都有其存在的价值

- 将详细指导移至@导入文件

- 删除任何过时的或与新指令冲突的内容

- 用强调标记关键规则，但只标记真正关键的内容

- 在工作过程中添加指令，而不仅仅是在开始时

- 在 PR 审查时发现约定时进行更新

- 定期检查过时或冲突的规则

对于较大的项目：

- 具有不同约定的子目录可能需要自己的 CLAUDE.md

- 将规则拆分到 `.claude/rules/` 文件中可以让团队之间的所有权更加清晰

# 入门指南

如果你还没有 CLAUDE.md，现在就运行 /init。检查它生成的内容。删除不适用的部分。添加你的代码风格偏好。

如果你已经有了一个，下次 Claude 做出你想纠正的假设时，告诉它更新文件。看着你的文件从实际使用中有机地成长。

一个文件。几分钟的配置。日积月累，节省大量时间。