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只应该放长期稳定、高频复用、和编码过程直接相关的规则类信息。简单说就是那些你每次写代码都要遵守、但不想每次都复述一遍的约定。✅ 适合放入的内容技术栈与目录约定项目用什么框架、核心代码放在哪个目录、哪些目录禁止修改这是最基础也最有价值的信息。环境与启动命令包管理器用 npm 还是 pnpm后端怎么启动、怎么跑测试避免 Claude 每次都去猜测和试错。编码规范与约束代码风格、命名规则、异常处理方式、分层架构要求统一输出代码的质量。核心架构边界比如 RAG 链路的封装规则、第三方代码目录的修改禁令防止 Claude 改动不该碰的文件。通用协作约定代码提交规范、日志输出标准等团队级共识。❌ 绝对不要放的内容过程性文档会议纪要、设计演进历史、需求变更记录这些和写代码本身无直接关系。冗长业务说明完整的业务规则、产品需求文档需要时再让 Claude 单独读取即可。临时性任务背景本次迭代要做什么、某个临时调试方案这些属于单次对话的上下文。大段代码与完整接口文档这些信息散落在源码里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/ - 用户验收测试UATtesting/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 - 可选 typefeat / fix / docs / refactor / test / chore - 常用 scopefrontend / backend / rag / db / docs / test