CLAUDE.md 到底怎么写：Claude Code 的项目记忆与团队规范

一句话主线：你告诉过 Claude Code 的规则，不该每次都靠嘴说。CLAUDE.md 就是写给 Agent 的"项目交接文档"——短一点、准一点、硬一点，它就能少猜一点。

引言：为什么你总是在重复教育 Claude Code

用 Claude Code 的人基本都经历过这个循环：

第一轮你告诉它：“这个项目用 pnpm，不要用 npm。“过一会儿它开始建议 npm install。你告诉它"不要直接改数据库表结构”，修着修着它又想动 schema。你说"改完要跑单测”，它改完代码就准备收工了。

这时候很多人会怀疑：是不是模型不听话？

不完全是。

真正的问题是：你把项目长期规则，当成了临时聊天内容。

聊天内容会随着任务变长被文件内容、命令输出、错误日志淹没；一旦上下文压缩、裁剪、切换任务，它就可能忘。你以为 Claude Code “记得"这些规则，其实它只是"当前上下文里还能看到”。

所以项目规则需要一个更稳定的入口——这就是 CLAUDE.md。在《Claude Code 高效使用指南》里我讲过它是六种扩展能力的第一层，这篇专门把它拆开讲透。

1. CLAUDE.md 到底是什么

CLAUDE.md 就是一个普通的 Markdown 文件，Claude Code 进项目时会自动读取，把内容作为项目上下文的一部分。注意三个关键词：

第一，它是普通 Markdown。 不是配置文件，不是 JSON/YAML，不需要复杂语法。就像给新同事写的说明文档一样写就行。

第二，它是给 Claude Code 看的。 README 主要给人看，CLAUDE.md 主要给 AI 编程 Agent 看。所以不用写项目愿景、业务背景长文、团队文化，要写的是能直接影响 Agent 行动的信息。

第三，它会进入上下文。 这一点最容易被忽略：规则参与后续推理，所以它能让 Claude Code 更稳定——但也会占上下文窗口。这直接决定了一条写作原则：

CLAUDE.md 要短、准、可执行。不是越长越好。

2. 和 README、Prompt、Memory 有什么区别

很多人的第一个疑问是：我都有 README 了，还要 CLAUDE.md 干嘛？

这俩读者不一样。README 的读者是人，写项目介绍、安装方式、使用文档；而 Claude Code 真正需要的是行动约束——从哪个目录入手、改代码前先看哪些文件、用哪个命令验证、哪些文件不要碰、遇到某类错误先查哪里。

Prompt 是当前任务的临时要求，只对这次任务生效；CLAUDE.md 放跨任务都稳定的规则。

Memory 要分清层级：Claude Code 的 memory 有用户级、项目级、企业级。CLAUDE.md 本身就是一种项目记忆；个人习惯（“我喜欢先看计划再改代码”）适合放用户级记忆，团队共享规则才适合放项目里的 CLAUDE.md。

载体	回答的问题	典型内容
README	人怎么理解项目	项目介绍、安装方式、使用文档
Prompt	这次要做什么	“修登录失败，但别改后端接口”（临时）
CLAUDE.md	在这个项目里怎么干活	架构、命令、规范、禁区（跨任务稳定）
Memory	个人/团队经验	用户级放个人习惯，项目级放团队规则

一句话区分：

README 告诉人怎么理解项目，Prompt 告诉模型这次要做什么，CLAUDE.md 告诉 Claude Code 在这个项目里怎么干活。

3. CLAUDE.md 应该放在哪里

这是最容易乱的地方——memory 不是只有一个位置。

位置	作用范围	适合放什么
`~/.claude/CLAUDE.md`	你本机所有项目	个人偏好、通用工作习惯（不提交 Git）
`./CLAUDE.md` 或 `./.claude/CLAUDE.md`	当前项目，团队共享	架构、命令、代码风格、测试方式、禁区（进 Git）
`子目录/CLAUDE.md`	进入该模块时按需加载	模块命令、局部架构和禁区
`@path` import	个人文件 / 项目文档引用	`@~/.claude/my-project-preferences.md`

几个要点：

项目级文件要进 Git，团队所有人用 Claude Code 都能获得同一套规则。
个人偏好不要污染团队文件。以前常用 CLAUDE.local.md，现在更推荐在项目记忆里用 @path import 引入个人文件——个人规则不用进仓库，也更适合多 worktree 场景。
大仓库一定要拆：根目录管全局，前端、后端、文档各自放自己的 CLAUDE.md。Claude Code 会从当前工作目录往上查找记忆，处理某个子树时再加载对应的深层文件。
@path import 也能引用项目文档（如 请参考 @README.md），但要克制——把一堆长文档全 import 进来，上下文就成垃圾桶了。

不要让前端任务背着后端所有细节跑，也不要让文档任务背着数据库规则跑。

4. 什么内容值得写进去

判断标准很简单：它是否会反复影响 Claude Code 的行动？ 会 → 写；只对当前任务有效 → 放 prompt；只是给人看的背景 → 放 README。

值得写的六类内容：

## 常用命令          ← 最应该写，命令写完整，尤其 monorepo
- 安装依赖：pnpm install
- 本地开发：pnpm dev
- 单元测试：pnpm test
- 构建检查：pnpm build
- 所有命令都在 docs/ 目录下执行

## 目录结构          ← 写目录职责，不要贴完整文件树
- `src/components/`：通用 UI 组件
- `src/api/`：接口封装，组件不要直接调用 fetch
- `src/hooks/`：可复用业务逻辑

## 编码规范          ← 写具体规则，不写空话
- 新组件使用函数组件
- 样式优先使用已有 token，不新增散乱颜色
- API 错误统一通过 handleApiError() 处理

## 禁止事项          ← AI 编程最怕乱动不该动的地方
- 不要修改数据库 schema，除非用户明确要求
- 不要升级核心依赖版本
- 不要提交 .env、token、密钥

## 验证要求
- 修改业务逻辑后，必须运行相关测试；无法运行则在最终回复说明原因

## 常见坑
- 支付模块的金额单位是分，不是元
- 本项目使用 pnpm，不要使用 npm 或 yarn

命令一定要写完整——尤其是 monorepo 或需要特定目录执行的项目，cd docs && npm run build 比你每次口头提醒强太多。常见坑的价值最高：人踩过一次就记住的坑，AI 不知道，写在聊天里容易丢，写进 CLAUDE.md 就是长期资产。

5. 什么内容不要写进去

CLAUDE.md 最大的问题不是没人写，而是越写越长，最后变成项目垃圾场：

❌ 完整接口文档——几十个接口全贴进去，最多写"API 文档见 docs/api.md"
❌ 历史流水账——“2025-01-03 修了登录问题"对当前行动没帮助；如果历史决策很重要，要写成规则结论（“登录态统一由 authStore 管理”），别写流水账
❌ 空泛口号——“写高质量代码"“注意性能"看着正确，但不能指导行动；改成可执行规则（“列表页超过 100 条数据时使用分页”）
❌ 过期规则——过期规则比没有规则更危险：项目从 npm 换成 pnpm，旧规则还写 npm，Claude Code 会很听话地继续错
❌ 太细的临时任务——“今天先修用户 A 的导出 bug"属于当前对话，任务结束后还留在文件里只会污染后续任务

6. 怎么写才真的有效：短、准、硬

三个词：短、准、硬。短是不要长篇大论；准是每条都和行动有关；硬是写成明确约束，而不是温柔建议。

太软 ❌	改成 ✅
尽量注意测试	修改业务逻辑后必须运行相关测试，无法运行则在最终回复说明原因
代码要符合项目风格	新增 API 请求必须放在 `src/api/`，页面组件只能调用封装后的 API 方法
保持代码优雅	公共逻辑超过两个页面复用时，抽到 `src/hooks/`

把好写法归成六类：项目是什么、命令怎么跑、目录怎么分、代码怎么写、什么不能做、改完怎么验。其他内容能不放就不放。

写 CLAUDE.md，不是为了显得你很懂 AI，而是为了让 AI 少猜。

7. 大项目怎么拆 CLAUDE.md

小项目一个根文件够用；大项目（尤其 monorepo）一定要拆。如果把 Web 前端、Node 后端、移动端、文档站、组件库的规则全写进根文件，最后一定变成十几屏——Claude 每次做很小的任务，都要背着一堆无关规则。

repo/
  CLAUDE.md            ← 全局：包管理器、Git 流程、安全要求、全局禁止事项、通用验证方式
  apps/web/CLAUDE.md   ← 模块：目录职责、启动/测试命令、模块常见坑
  apps/admin/CLAUDE.md
  packages/ui/CLAUDE.md
  docs/CLAUDE.md

这和我之前讲 Agent 上下文管理是同一个逻辑：

不是让模型看见更多，而是让它看见更有价值的信息。

8. CLAUDE.md 和上下文窗口有什么关系

CLAUDE.md 不是免费空间，它会进入上下文。上下文窗口就像一张工作台：规则放上去，模型就能看到；但放太多，工具输出、文件内容、用户要求就会被挤。

官方会对 CLAUDE.md 使用 prompt caching 降低重复读取的成本。但注意：缓存降低的是计费压力，不代表它不占上下文空间，也不代表信息越多越好。 一份 300 行的 CLAUDE.md，即使缓存了，模型每次也要在大量规则里找重点——重要规则被淹没，无关规则干扰当前任务。

所以我的建议是：

根 CLAUDE.md 控制在几屏内
每条规则尽量一行说明
长文档用链接或 @path import 引用
低频规则放到对应子目录
定期删除过期内容

9. 给你一个可以直接抄的模板

# 项目工作说明

## 项目概述

- 本项目是一个 XXX 应用，主要技术栈是 XXX。
- 主要代码在 `src/`，测试在 `tests/`。
- 优先遵循现有代码风格，不要引入新的架构风格。

## 常用命令

- 安装依赖：`pnpm install`
- 本地开发：`pnpm dev`
- 单元测试：`pnpm test`
- 构建检查：`pnpm build`

## 目录结构

- `src/components/`：通用组件
- `src/pages/`：页面入口
- `src/api/`：接口封装，组件不要直接调用 fetch
- `src/hooks/`：可复用业务逻辑
- `tests/`：测试文件

## 编码规范

- 新增 API 请求必须放在 `src/api/`。
- 页面组件不要直接调用 `fetch`。
- 公共逻辑被两个以上模块复用时，抽到 `src/hooks/`。
- 修改已有功能时，优先保持现有接口兼容。

## 禁止事项

- 不要提交 `.env`、token、密钥。
- 不要升级核心依赖版本，除非用户明确要求。
- 不要修改数据库 schema，除非用户明确要求。
- 不要删除用户已有改动。

## 验证要求

- 修改业务逻辑后，运行相关测试。
- 修改公共组件后，运行构建检查。
- 如果测试无法运行，在最终回复里说明原因。

## 常见坑

- 本项目使用 pnpm，不要使用 npm 或 yarn。
- 修改配置文件后，需要重新启动开发服务器。
- 遇到鉴权问题，先检查 `src/api/auth.ts` 和 `src/store/auth.ts`。

模板的价值是结构，不是内容。把每一条改成自己项目里的真实规则——假的规范，比没有规范更坑。

10. 团队里怎么维护 CLAUDE.md

如果团队已经大量使用 AI 编程，建议把 CLAUDE.md 当成工程资产维护，不要让它变成某个人电脑里的私货：

项目根 CLAUDE.md 进仓库——团队共享规则都进 Git
个人偏好放用户级 memory——喜欢中文回复、喜欢先看计划，这些不污染团队文件
规则变更像代码一样审查——禁止事项、测试命令、架构规则直接影响 AI 的行动，写错了就是把错误流程自动化
踩坑之后及时沉淀——Claude 因为某个坑连续犯错，不要只在聊天里骂它，写进 CLAUDE.md 一句话（“支付模块的金额单位是分，不是元”）可能避免很多次错误
定期删——过期命令、已不存在的目录、重复规则、临时任务残留，越短越准越有用

11. 面试和工作中怎么讲这个能力

会用 Claude Code 只是让它写代码；更高级的是把 AI 编程变成稳定流程。如果面试官问"你怎么让 AI 编程工具更稳定？"，可以这样答：

“我不会只靠临时 prompt 管项目规则。对于跨任务稳定的信息——项目架构、常用命令、测试方式、代码风格、禁止改动范围——我会沉淀到 CLAUDE.md，让 Claude Code 每次进入项目都能读取，减少重复解释，也减少上下文压缩后丢约束的问题。但我不会把它写成大杂烩，因为它会进入上下文，太长会稀释注意力。所以我会按全局规则和模块规则拆分，根目录写通用约束、子目录写模块细节；临时任务放 prompt，个人偏好放用户级 memory，团队规则放项目级 CLAUDE.md。核心目标不是让模型看到更多，而是让它看到更稳定、更有行动价值的信息。”

这个回答说明的不只是"我会用工具”，而是你理解 AI Coding 背后的工程化问题——这比背一堆名词值钱得多。

总结

CLAUDE.md 不是魔法，它不会让 Claude Code 瞬间变成懂你公司所有业务的老员工。但它能解决一个非常实际的问题：

别让 AI 每次进项目都从零猜。

项目怎么启动、代码怎么写、哪里不能动、改完怎么验——这些规则越早沉淀，Claude Code 越像一个靠谱队友。不要把它写成百科全书，就写那些会反复影响行动的规则：短一点，准一点，硬一点，这就够了。

关于其他扩展能力（Skills、Subagents、MCP、Hooks、Plugins）怎么和 CLAUDE.md 组合，可以看系列里的高效使用指南和四层扩展能力的工程演进；想了解它和上下文管理的底层关系，推荐底层运行机制。

参考链接

Claude Code 官方文档（CLAUDE.md 与 Memory）：https://code.claude.com/docs/en/memory
Claude Code 官方文档（扩展能力总览）：https://code.claude.com/docs/en/features-overview
Claude Help Center（Give Claude context: CLAUDE.md and better prompts）：https://support.claude.com/en/articles/14553240-give-claude-context-claude-md-and-better-prompts
Claude Help Center（Claude Code cheatsheet）：https://support.claude.com/en/articles/14553413-claude-code-cheatsheet

引言：为什么你总是在重复教育 Claude Code#

1. CLAUDE.md 到底是什么#

2. 和 README、Prompt、Memory 有什么区别#

3. CLAUDE.md 应该放在哪里#

4. 什么内容值得写进去#

5. 什么内容不要写进去#

6. 怎么写才真的有效：短、准、硬#

7. 大项目怎么拆 CLAUDE.md#

8. CLAUDE.md 和上下文窗口有什么关系#

9. 给你一个可以直接抄的模板#

10. 团队里怎么维护 CLAUDE.md#

11. 面试和工作中怎么讲这个能力#

总结#

参考链接#