CLAUDE.md 配置完全指南：让 Claude Code 记住你的项目

为什么需要 CLAUDE.md 文件

使用 Claude Code 时，如果没有 CLAUDE.md 文件，每次启动新会话都像是从零开始——它需要重新探索代码库、理解依赖关系、了解已实现的功能。更糟糕的是，它不得不做出各种假设，这让我们很难引导 Claude 朝正确方向工作。

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，它直接在终端中运行，能够读取、编写和修改代码文件。与 IDE 插件不同，Claude Code 以 agentic 方式工作——它可以自主执行命令、浏览文件系统、运行测试。但每次新会话启动时，它的上下文窗口是空白的，这意味着它对项目的理解完全依赖于当前会话中获取的信息。CLAUDE.md 的设计正是为了解决这个"冷启动"问题。

CLAUDE.md 文件本质上是一个放在项目根目录的 Markdown 文件，Claude Code 每次启动会话时会自动读取它。你可以把它理解为代码库的入职培训脚本——它为 AI 提供了持久化的项目记忆。

从技术实现角度看，CLAUDE.md 的内容会被追加到你的提示词中，成为每次对话的上下文基础。这里需要理解一个重要的技术细节：Claude 模型的上下文窗口（context window）有固定大小限制，所有输入——包括系统提示、CLAUDE.md 内容、用户指令和代码文件——都需要在这个窗口内。这就是为什么后文会强调保持 CLAUDE.md 精简：过长的记忆文件会压缩留给实际代码和对话的空间，降低模型的有效工作能力。

如何创建和编写 CLAUDE.md

使用 /init 命令快速生成

最简单的方式是运行 /init 命令，Claude 会基于你的代码库自动生成一份 CLAUDE.md 文件。它会分析项目的 package.json、目录结构、配置文件等，推断出技术栈和项目约定。当然，自动生成的内容通常需要手动调整和补充，因为有些架构决策和团队约定是无法从代码中自动推断的。

CLAUDE.md 内容结构示例

以一个 Next.js 15 项目为例，一份典型的 CLAUDE.md 文件包含以下几个部分：

技术栈声明：

• Next.js 15，使用 App Router
• Tailwind CSS
• Drizzle ORM

Next.js 15 的 App Router 是从 Pages Router 演进而来的新路由架构，基于 React Server Components（RSC）构建，默认所有组件在服务端渲染。Drizzle ORM 则是一个轻量级的 TypeScript ORM，以其类型安全和接近原生 SQL 的查询语法著称，与 Prisma 不同的是它不需要代码生成步骤，schema 定义直接用 TypeScript 编写。在 CLAUDE.md 中明确声明这些技术选型，可以让 Claude Code 在生成代码时直接使用对应的 API 风格，而不是猜测项目使用的是哪种方案。

常用命令：

• 开发服务器启动命令
• 测试运行命令
• Lint 检查命令

代码风格规范：

• 使用两空格缩进
• 优先使用命名导出（named exports）
• 所有 API 路由放在 app/api 目录下
• 尽可能使用 Server Actions 替代 API Routes

关于最后一条规范的背景：Server Actions 是 App Router 引入的核心特性，允许开发者直接在组件中定义服务端函数（通过 'use server' 指令标记），客户端可以像调用普通函数一样触发服务端逻辑，无需手动创建 API 端点。这大幅简化了表单提交、数据变更等场景的代码量。如果不在 CLAUDE.md 中明确这一偏好，Claude Code 可能会默认创建传统的 API Route 文件来处理数据操作。

这些信息看似简单，但效果显著。当你让 Claude Code 创建一个 React 组件时，它立刻就知道该用 Tailwind 来写样式，而不需要先花时间探索项目中使用了什么 CSS 方案。

CLAUDE.md 记忆文件的层级体系

CLAUDE.md 并不是只有一个文件，它实际上有一套层级系统，适用于不同的使用场景：

项目级 CLAUDE.md

放在项目根目录，包含项目特定的技术栈、架构约定和开发规范。这个文件应该提交到版本控制系统中，供整个团队共享使用。这类似于 .editorconfig 或 .eslintrc 等配置文件的协作模式——通过 Git 仓库共享开发规范。当团队成员对架构决策达成共识（比如状态管理用 Zustand 而非 Redux），将其写入 CLAUDE.md 可以确保每个人的 AI 助手都遵循相同的技术选型，避免不同成员的 Claude Code 生成风格迥异的代码。

用户级 CLAUDE.md

放在你的个人配置文件夹中（通常是 ~/.claude/ 目录），这个文件只属于你个人，且跨所有项目生效。这个设计借鉴了 Unix 系统中 dotfile 的传统——如 ~/.gitconfig、~/.bashrc 等个人配置文件。适合放置个人编码偏好，比如你习惯的注释风格、变量命名方式、偏好函数式编程还是面向对象、希望注释用中文还是英文等。

这种分层设计意味着团队共识和个人偏好可以优雅地共存，互不干扰。当两个层级的配置同时存在时，它们会叠加生效，为 Claude Code 提供更完整的上下文信息。

三个 CLAUDE.md 实用配置建议

1. 让 Claude 主动记住纠正内容

如果你在使用过程中需要反复纠正 Claude 的某个行为——比如总是提醒它"用 Server Actions 而不是 API Routes"——那就明确要求 Claude 将这条规则保存到记忆中。下次回到项目时，它就会自动遵循这个约定。这种交互式的记忆更新方式，让 CLAUDE.md 成为一个不断学习和积累的知识库，而非静态的配置文件。

2. 使用 @ 符号引用项目文档

如果项目中有需要 Claude 参考的文档，使用 @ 符号加文件路径即可引用。例如 @docs/architecture.md 可以让 Claude 在需要时读取项目的架构文档。这样 Claude 就能基于你的项目文档来工作，而不是依赖通用知识。这对于使用了自定义框架、内部库或特殊业务逻辑的项目尤为重要。

3. 先观察再补充，保持文件精简

一个反直觉但非常实用的建议：新项目开始时不要急着写 CLAUDE.md。先正常使用 Claude Code，观察你在哪些地方需要反复纠正它的行为。然后只把这些真正需要纠正的内容写入 CLAUDE.md。

这种方法的好处是保持文件精简，只包含真正必要的信息。过于冗长的 CLAUDE.md 反而可能稀释重要信息的权重——因为所有内容都会占用有限的上下文窗口空间，当记忆文件过长时，模型对每条指令的关注度会相应降低，关键规则可能被"淹没"在大量次要信息中。

总结

一次令人沮丧的 Claude Code 会话和一次高效的会话之间的差别，归根结底在于上下文。CLAUDE.md 就是你提供上下文的核心手段。

建议的起步策略：

1. 先声明技术栈
2. 再写明编码偏好和规范
3. 列出常用命令
4. 随着使用不断迭代补充

记住，CLAUDE.md 不是一次性写完的文档，而是随项目演进持续更新的活文件。好的 CLAUDE.md 能让 Claude Code 从"需要反复指导的新手"变成"了解项目全貌的老手"。

核心要点

• CLAUDE.md 是 Claude Code 的持久化记忆文件，放在项目根目录自动读取，内容会追加到提示词中
• 记忆文件有层级体系：项目级（团队共享）和用户级（个人偏好，跨项目生效）
• 建议先不写 CLAUDE.md，观察需要反复纠正的行为后再补充，保持文件精简
• 文件内容应包含技术栈声明、常用命令、代码风格规范三大核心部分
• 可通过 /init 命令快速生成初始版本，后续随项目演进持续迭代更新