CLAUDE.md笔记

这篇文章结合一个完整的前后端 RAG 项目实践，讲清楚 CLAUDE.md 到底该怎么写：什么内容必须放，什么内容绝对不能放，最后给一份可直接复用的完整示例。

CLAUDE.md 为什么这么重要？

很多人知道 CLAUDE.md 是给 Claude Code 看的项目说明，但很少有人注意它的加载机制，而这恰恰是决定它怎么写的核心：

• 自动加载，全程驻留：打开项目时 Claude Code 会自动读取根目录的 CLAUDE.md，并且在整个会话周期内一直保留在上下文中，不会轻易被后续内容挤掉。
• 每轮计费，持续消耗：它不是按需加载的。如果你的文件有 5000 Token，那么本次会话的每一轮对话，都要为这 5000 Token 额外付费，和对话轮数成正比。
• 优先级高，影响全局：它会在读取代码之前生效，相当于给 Claude 定下了整个项目的“基本法”，后续所有代码生成、修改、排查操作都会默认遵循这份约定。

这就决定了：CLAUDE.md 绝对不能写成“信息垃圾桶”。它的内容越精炼、复用价值越高，你的投入产出比就越高；反之，冗余内容越多，就是在纯浪费 Token。

核心原则：做“速查手册”，不做“百科全书”

一个合格的 CLAUDE.md，只应该放长期稳定、高频复用、和编码过程直接相关的规则类信息。简单说，就是那些你每次写代码都要遵守、但不想每次都复述一遍的约定。

✅ 适合放入的内容

1. 技术栈与目录约定：项目用什么框架、核心代码放在哪个目录、哪些目录禁止修改，这是最基础也最有价值的信息。
2. 环境与启动命令：包管理器用 npm 还是 pnpm，后端怎么启动、怎么跑测试，避免 Claude 每次都去猜测和试错。
3. 编码规范与约束：代码风格、命名规则、异常处理方式、分层架构要求，统一输出代码的质量。
4. 核心架构边界：比如 RAG 链路的封装规则、第三方代码目录的修改禁令，防止 Claude 改动不该碰的文件。
5. 通用协作约定：代码提交规范、日志输出标准等团队级共识。

❌ 绝对不要放的内容

1. 过程性文档：会议纪要、设计演进历史、需求变更记录，这些和写代码本身无直接关系。
2. 冗长业务说明：完整的业务规则、产品需求文档，需要时再让 Claude 单独读取即可。
3. 临时性任务背景：本次迭代要做什么、某个临时调试方案，这些属于单次对话的上下文。
4. 大段代码与完整接口文档：这些信息散落在源码里，Claude 可以按需读取，没必要常驻上下文。

记住一个简单的判断标准：如果这条规则未来一个月都不会变，而且几乎每次写代码都用得到，就放进去；否则就不要放。

实战示例：前后端分离 RAG 项目的完整 CLAUDE.md

下面是一份我自用的面向 Vue 3 + FastAPI + LangChain + Milvus + SQLite 技术栈的完整 CLAUDE.md，目录结构、启动命令、编码约束都做了明确约定，全程控制在合理长度，没有冗余信息。

# CLAUDE.md - 项目开发契约

## 1. 技术栈总览
本项目为前后端分离的 RAG 智能应用系统，技术栈固定如下：
- 前端：Vue 3 + Vite + Pinia
- 后端：Python 3.11 + FastAPI
- 核心能力：LangChain 1.0 + DeepSeek 大模型 + Milvus 3.0 向量数据库
- 结构化存储：SQLite

## 2. 顶层目录约定
- 前端代码统一存放于 `frontend/` 目录
- 后端代码统一存放于 `backend/` 目录
- 项目文档、设计说明、接口手册统一存放于根目录 `docs/`
- 全项目测试代码统一存放于根目录 `testing/`
  - 单元测试代码：`testing/ut/`
  - 用户验收测试（UAT）：`testing/uat/`
- 部署脚本、Docker 配置存放于根目录 `deploy/`
- 本地开发数据、SQLite 数据库文件存放于 `backend/data/`
- 禁止在根目录散落业务代码与文档文件

## 3. 环境与包管理
- 前端：Node.js ≥ 18，包管理器统一使用 npm，禁止混用 pnpm/yarn
- 后端：Python 版本固定为 3.11，依赖通过 requirements.txt 管理，服务入口为 `backend/main.py`，内置热重载能力
- 所有环境变量通过 `.env` 文件加载，禁止代码中直接硬编码密钥与连接参数

## 4. 常用开发命令
### 前端（frontend/ 目录下执行）
- 本地启动开发服务：`npm run dev`
- 生产环境构建：`npm run build`
- 代码格式化：`npm run format`
- 语法检查：`npm run lint`

### 后端（项目根目录下执行）
- 本地启动服务（自带热重载）：`python backend/main.py`
- 执行后端单元测试：`python -m pytest testing/ut/backend`
- 执行全量单元测试：`python -m pytest testing/ut`
- 执行用户验收测试：`python -m pytest testing/uat`
- 代码格式化：`black backend/ testing/`
- 数据库迁移：`alembic upgrade head`

## 5. 开发工作流约定
- 新增功能模块、调整核心架构、改动公共组件、修改RAG主链路等中大型需求，**必须先输出设计方案，经用户确认后方可开始编码实现**
- 设计方案至少包含：实现思路、涉及的文件列表、核心改动点、对现有逻辑的影响
- 单文件小范围修改、bug修复、格式调整、配置更新等简单任务，可直接执行，无需提前走设计确认
- 设计方案输出阶段，默认不修改任何业务代码文件

## 6. 编码规范约定
### 6.1 前端 Vue3 规范
- 统一使用 `<script setup>` 语法 + Composition API
- 组件命名采用大驼峰（PascalCase），文件名与组件名保持一致
- 全局状态统一使用 Pinia 管理，禁止散落全局变量
- 接口请求统一收敛到 `src/api/` 目录，禁止组件内硬编码请求

### 6.2 后端 FastAPI 规范
- 遵循 PEP 8 规范，强制使用 black 格式化、isort 整理导入顺序
- 路由按模块划分，统一使用 APIRouter 注册到 `app/api/` 下
- 入参与响应结构统一使用 Pydantic 定义校验
- 业务异常统一抛出 `app.common.exceptions.BusinessError`，由全局异常处理器返回标准格式

### 6.3 RAG 链路统一规则
- LangChain 链实现必须使用 LCEL 语法，禁止使用旧版链式调用
- 大模型、Embedding 模型统一从 `app.rag.models` 模块导入，禁止各处重复初始化实例
- 提示词模板统一存放在 `app/rag/prompts/` 目录，以文件或常量形式管理
- Milvus 集合命名格式：`{业务域}_{数据类型}_v{版本号}`，禁止随意创建集合
- 向量检索统一通过 `app.rag.retriever` 层封装调用，禁止业务代码直接操作 Milvus 客户端

## 7. 目录边界与约束
- 所有项目文档、设计方案、接口说明统一放入 `docs/` 目录，禁止散落在业务代码目录中
- 单元测试、UAT 测试代码按分类放入 `testing/` 对应子目录，禁止混入 frontend/backend 的业务源码目录
- 前端业务代码必须放在 `frontend/src/` 对应模块下，公共组件收敛到 `frontend/src/components/`
- 后端第三方适配代码放在 `backend/app/third_party/`，禁止直接修改该目录源码
- 禁止手动修改 SQLite 数据库文件，所有表结构变更必须通过 Alembic 迁移脚本执行
- Milvus、大模型等配置统一由 `backend/app/config/settings.py` 管理

## 8. 代码提交规范
- 提交信息格式：`type(scope): message`
- 可选 type：feat / fix / docs / refactor / test / chore
- 常用 scope：frontend / backend / rag / db / docs / test