你的 AI 队友每天都在"失忆"

你有没有这种经历：用 Claude 或者 ChatGPT 写代码，每次新开一个对话，你都得把项目背景从头到尾解释一遍——"我用的是 Next.js + TypeScript，后端是 NestJS，数据库是 MongoDB，代码风格用 Prettier，Tab 缩进，变量命名用 camelCase..."

然后你解释完了，AI 给你生成了一段代码，结果它用了 npm 而不是你项目里的 bun，用了 MUI 组件而不是你的 styled-components，甚至还给你装了一个 antd。你崩溃了。

更崩溃的是，你在上一条消息里刚说过"我们禁止使用 MUI"，下一条消息 AI 又给你 import 了一个 @mui/material。

这就是为什么你需要 CLAUDE.md。

一句话解释

CLAUDE.md 是你写给 Claude Code 看的"项目说明书"。它放在项目根目录，Claude Code 每次打开你的项目时会自动读取这个文件。你不用每次都重新解释，AI 打开项目的第一秒就知道：这个项目是什么、用什么技术、有什么规矩、哪些东西不能碰。

你可以把它想象成公司给新员工入职第一天发的那本《员工手册》。有了这本手册，新员工不用挨个去问"公司用什么邮箱？报销流程是什么？代码提交规范是什么？"——手册里全写了。没有这本手册？那每个新员工入职都要问同样的问题，每个老员工都要重复回答。CLAUDE.md 就是这本手册，只不过你的"新员工"是 AI，而且它每次打开项目都像是"第一天入职"。

来看一个真实的例子

说再多理论不如看一个活的。JR Academy 是一个真实的教育平台项目——就是你现在正在用的这个平台。它的 CLAUDE.md 有几百行，我们来看看它到底写了什么。

先看项目使命和定位部分：

## Platform Mission
**JR Academy** is a global AI-driven educational platform
with the mission: "全球华人学习 AI 第一站"

### Brand Positioning
| Dimension | Chinese Site | English Site |
|-----------|-------------|-------------|
| Target Users | Global Chinese-speaking learners | Local job seekers |
| Core Value | AI era learning gateway | IT career training |

你可能会想：这种"使命愿景"有必要写进 CLAUDE.md 吗？AI 又不需要知道公司文化。

答案是：非常有必要。 因为当 AI 帮你写用户面向的文案、设计页面标题、或者决定一个功能的优先级时，它需要知道这个平台是面向谁的。如果 AI 不知道"中文站面向全球华人"，它可能会写出一堆只有本地人才看得懂的俚语；如果 AI 不知道"英文站侧重求职"，它可能在英文站上花大量篇幅写 AI 学习内容。

再看技术栈和项目结构：

### Core Applications
- jr-academy/ — Backend API server (NestJS + TypeScript + MongoDB)
- jr-academy-web-zh/ — Frontend (Next.js + React + TypeScript)
- jr-academy-admin/ — Super Admin dashboard (React + Vite)
- survey/ — SigmaQ mock test platform (Express + React + MongoDB)

### Common Commands
cd jr-academy && bun run start:dev    # localhost:3010
cd jr-academy-web-zh && bun run dev   # localhost:8000

这部分是 CLAUDE.md 的骨架。没有这些信息，AI 写代码就是在黑暗中摸索——它不知道后端在哪个目录、用什么端口、怎么启动。有了这些信息，你说"帮我在后端加一个 API"，AI 就知道该去 jr-academy/ 目录，用 NestJS 的 Controller-Service 模式来写。

接下来是最有价值的部分——编码规范和绝对禁止：

### Naming Conventions
- Interfaces: Prefix with I (e.g., IUser, ICourseData)
- Enums: Prefix with E (e.g., EUserRole)
- Constants: UPPER_SNAKE_CASE
- Files: kebab-case (e.g., user-service.ts)

### UI Design System
✅ Use styled-components for custom styling
❌ DO NOT use Material-UI (MUI) — All MUI imports are forbidden
❌ DO NOT use Ant Design (antd) — All antd imports are forbidden

你看到了吗？它不只是说"请用好的命名规范"这种废话，它具体到了前缀用什么字母、文件名用什么格式。而且"禁止"部分用了非常强烈的语气——DO NOT、forbidden。这不是客气话，这是血泪教训：JR Academy 的团队曾经因为 AI 偷偷引入了 MUI 组件，导致打包体积暴增、样式冲突，花了两天时间才清理干净。

CLAUDE.md 的层级系统

说实话，一个项目只有一个 CLAUDE.md 在很多时候是不够的。Claude Code 实际上支持一个分层系统：

JR Academy 的项目就是一个 monorepo——前端、后端、Admin、各种微服务全在一个仓库里。根目录的 CLAUDE.md 写全局规则（命名规范、ID 原则、Git 规范），然后每个子模块可以有自己的规则。

话说回来，如果你的项目不是 monorepo，一个根目录的 CLAUDE.md 就完全够用了。不要为了"看起来专业"而过度拆分——简单的项目搞一堆规则文件，AI 反而会被信息淹没。

和 Prompt Engineering 是什么关系？

这个问题我经常被问到。简单粗暴地说：

• Prompt Engineering 是你每次跟 AI 对话时的技巧——"帮我写一个登录页面，要求用 TypeScript，包含表单验证"
• Context Engineering 是你在项目层面的配置——CLAUDE.md 写好了，AI 打开项目就自动知道该怎么做

打个比方：Prompt 像是每次打车跟司机说"前面路口左转"，Context 像是在导航 App 里输好了目的地。有了导航，你不用每个路口都指路；有了 CLAUDE.md，你不用每次对话都重复项目背景。

但两者不是替代关系。CLAUDE.md 解决的是"AI 知道项目的基本规矩"，Prompt 解决的是"AI 知道这次具体要做什么"。你需要两个都会。

为什么不能用 README 代替？

你可能想：我项目已经有 README.md 了，里面也有技术栈、安装方法、项目结构，为什么还要再写一个 CLAUDE.md？

原因有三个：

第一，受众不同。 README 是写给人看的，CLAUDE.md 是写给 AI 看的。README 里会有一大段"项目背景"、"贡献指南"、"License"——这些对 AI 写代码完全没用。而 CLAUDE.md 里会有"禁止使用 any 类型"、"所有 API 都需要测试"——这些对人来说太啰嗦但对 AI 至关重要。

第二，格式不同。 CLAUDE.md 的信息密度要高得多。AI 不需要你用华丽的排版和示意图来"说服"它，它需要的是精确、可执行的指令。

第三，Claude Code 会优先读取 CLAUDE.md。 这是它的机制——项目根目录如果有这个文件，它会在每次对话开始前自动注入上下文。README 不会自动注入。