一个文件。在每次对话前加载。如果你在使用 Claude Code，这就是你设置时间投入回报最高的地方。
CLAUDE.md 是一个 markdown 文件，Claude 会在每次会话开始时自动读取。它保存了你原本需要在每个提示中重复的项目特定指令。结构、约定、工作流、风格。
我已经迭代我的 CLAUDE.md 设置有一段时间了。本指南涵盖了我学到的关于创建、结构化、维护和发展这些文件的所有内容。如果你在使用其他 AI 编程工具，同样的概念也适用于 AGENTS.md（Cursor、Zed、OpenCode 和其他 AI 编程工具 的等效文件）。
为什么你需要 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 电商应用”比你想的告诉 Claude 更多。
- 代码风格：你的格式化和模式偏好。使用 ES 模块还是 CommonJS？偏好命名导出？要具体。“正确格式化代码”是模糊的。
- 命令：如何运行测试、构建、lint、部署。当你要求 Claude 运行东西时，它会使用这些确切的命令。
- 注意事项：项目特定的警告。那个有奇怪重试逻辑的认证模块。需要特定头部格式的 API 端点。永远不应该直接修改的文件。
完整示例
以下是一个 Next.js 项目的 CLAUDE.md 可能的样子：
# 项目：ShopFront
Next.js 14 电商应用，使用 App Router、Stripe 支付和 Prisma ORM。
## 代码风格
- TypeScript 严格模式，不使用 `any` 类型
- 使用命名导出，不使用默认导出
- CSS：Tailwind 工具类，不使用自定义 CSS 文件
## 命令
- `npm run dev`：启动开发服务器（端口 3000）
- `npm run test`：运行 Jest 测试
- `npm run test:e2e`：运行 Playwright 端到端测试
- `npm run lint`：ESLint 检查
- `npm run db:migrate`：运行 Prisma 迁移
## 架构
- `/app`：Next.js App Router 页面和布局
- `/components/ui`：可复用 UI 组件
- `/lib`：工具和共享逻辑
- `/prisma`：数据库架构和迁移
- `/app/api`：API 路由
## 重要说明
- 永远不要提交 .env 文件
- /app/api/webhooks/stripe 中的 Stripe webhook 处理程序必须验证签名
- 产品图片存储在 Cloudinary，不是本地
- 查看 @docs/authentication.md 了解认证流程详情Claude 能高效处理这个，因为它有清晰的标题、便于扫描的要点，以及具体的命令而不是模糊的指令。
应该多长？
==一般建议是在 300 行以内。越短越好。上下文 token 是宝贵的。
但我见过一些项目，更长的文件是有意义的。如果你的代码库有复杂的约定或不寻常的模式，预先加载这些上下文可以防止 Claude 做出错误假设并浪费时间在修正上。
对我有效的方法是包含 Claude 在开始工作前需要知道的内容。如果某些内容只在特定情况下重要，我将其保存在单独的文件中并引用它。
@imports 系统
CLAUDE.md 支持使用 @path/to/file 语法导入其他文件：
查看 @README.md 了解项目概述
查看 @docs/api-patterns.md 了解 API 约定
查看 @package.json 了解可用的 npm 脚本这对于保持主文件精简很强大。将详细指令放在单独的 markdown 文件中，然后引用它们。Claude 在相关时拉入内容。
你可以从任何地方引用文件：
- 相对路径：
@docs/style-guide.md - 绝对路径也有效
- 甚至用户级文件：
@~/.claude/my-preferences.md
导入可以是递归的，所以你引用的文件可以引用其他文件。谨慎使用以避免创建引用迷宫。
我采用的模式是将基本内容保留在 CLAUDE.md 中，将详细的主题特定指南移到单独的文件中，用 @imports 引用。
使用 .claude/rules/ 的模块化规则
对于更大的项目，还有另一个选择：.claude/rules/ 目录。你可以将所有内容放在一个大型文件中，而是将指令拆分成专注的规则文件。
your-project/
├── .claude/
│ ├── CLAUDE.md # 主项目指令
│ └── rules/
│ ├── code-style.md # 代码风格指南
│ ├── testing.md # 测试约定
│ └── security.md # 安全要求
.claude/rules/ 中的所有 markdown 文件都会自动加载，与你的主 CLAUDE.md 具有相同的优先级。不需要导入。只需放入文件，它们就会被包含。
当不同的团队成员拥有不同的规则集时，这很有效。前端团队维护 code-style.md。安全团队维护 security.md。没有人需要在一个巨大的文件中合并冲突。
我还没有需要这个。我的项目还没有大到需要在多个文件中拆分规则。但如果你在一个更大的团队，有独立的领域，这种结构是有意义的。
子目录 CLAUDE.md 文件
还有层次结构的另一层：项目子目录中的 CLAUDE.md 文件。
当 Claude 读取子目录中的文件时，它会自动获取该子树中的任何 CLAUDE.md。这些不会在启动时加载。只有当 Claude 正在积极处理代码库的该部分时才会包含。
这对于 monorepo 或有独立模块的项目很有用。你的 /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。
定期审查
每隔几周，我会要求 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：永远不要使用 enums，总是优先使用字符串字面量联合类型。“Claude 会更新文件并将更改作为 PR 的一部分提交。
Boris Cherny 分享了这个工作流，它已经成为我思考 CLAUDE.md 维护的一部分。
这创建了一个反馈循环：现实世界的问题通知你的指令，这防止未来的问题。你的 CLAUDE.md 成为一个活的文档，捕捉你团队积累的知识。
我把它想象成代码库本身。你不会在第一次尝试时就写出完美的代码。你会重构。你会改进。你的 CLAUDE.md 值得同样的对待。
CLAUDE.md 最佳实践
- 用一句话解释项目是什么开头
- 使代码风格偏好具体且可操作
- 包含关键命令（测试、构建、lint、部署）
- 足够详细地说明注意事项以实际防止错误
- 保持在 300 行以内，或者确保每一行都有其价值
- 将详细指南移到 @imported 文件中
- 删除任何过时或与较新指令冲突的内容
- 用强调标记关键规则，但只标记真正关键的
- 在工作时添加指令，不只是预先添加
- 从 PR 审查中更新，当约定浮现时
- 定期审查过时或冲突的规则
对于更大的项目：
- 具有不同约定的子目录可能需要自己的
CLAUDE.md - 将规则拆分到
.claude/rules/文件中可以使跨团队的所有权更清晰
今天就开始
如果你还没有 CLAUDE.md，现在就运行 /init。审查它生成的内容。删除不适用的。添加你的代码风格偏好。
如果你已经有了，下次 Claude 做出你想要纠正的假设时，告诉它更新。看着你的文件从实际使用中有机地增长。
一个文件。几分钟的设置。随着时间节省数小时。