1. 为什么我给 AI 写了份项目说明书之后它才真正开始像自己人先说个真实场景。我用 AI 编程助手写代码已经有一阵子了。工具确实快但有个问题一直很烦它在同一个项目里反复犯同样的错。今天告诉它这个项目的 API 请求统一封装在src/api里不要直接写 fetch它能听话十分钟。明天新开一个会话你还没来得及交代它又自顾自地在组件里裸写 fetch 了。你说它笨吧它能帮你写出整个 CRUD 页面你说它聪明吧它记性是真的差每次都得重新教。后来我想明白了一件事这不是模型的智商问题是我自己的工作方式问题。我没给 AI 一个稳定的项目上下文。就好比一个外包同事今天刚入职你指望他看一眼代码就懂你们组的命名规范、接口约定、目录结构和部署流程这不现实。你得给他一份入职手册。对 AI 来说这份手册就是 CLAUDE.md。CLAUDE.md 是 Claude Code 这类命令行 AI 编程工具读取的项目级指令文件。它用 Markdown 格式记录整个项目的潜规则项目是什么架构、目录怎么划分、代码风格有什么约定、哪些命令必须跑、哪些操作绝对不能做。只要文件放在项目根目录AI 在每次会话里都会自动把它的内容当作上下文的一部分。换句话说你写一遍它每次都用得上再也不用你翻来覆去地重复交代。这篇文章我会老老实实讲清楚CLAUDE.md 到底是怎么工作的、一份合格的 CLAUDE.md 应该写什么、怎么写以及我踩过哪些坑之后才总结出来的维护经验。如果你也在用 AI 编程工具做实际项目尤其是 Vue3、Spring Boot 这类工程量不小、约定不少的技术栈这篇文章应该能让你少折腾好几个晚上。2. 先搞清楚 CLAUDE.md 的加载机制才知道它该写什么很多人第一次接触 CLAUDE.md 容易陷入两个极端要么把它当成万能配置指望写几行字 AI 就能瞬间变成项目专家要么把它当成摆设随便抄个模板就扔进仓库再也不管。这两个极端我都试过效果都不好。搞清楚它的加载机制和生效边界你才知道哪些内容放进这个文件才有意义。2.1 它何时被读取以及为什么放根目录最稳妥CLAUDE.md 的核心机制是自动注入上下文。Claude Code 在启动会话、读取项目文件的时候会自动去项目根目录找这个文件把里面的内容加载进对话上下文。你不需要每次手动指定也不需要输入什么特殊的命令工具本身会处理这件事。这里有个关键细节既然是按路径查找那文件位置就决定了它的作用范围。放在项目根目录的 CLAUDE.md只有在进入这个项目目录工作时才会被加载换到别的项目就不生效。如果你有多个项目共用的规则那应该考虑放在更上层的目录或者使用工具支持的用户级配置文件而不是把全局的东西塞进每个项目的 CLAUDE.md 里。还有一点值得注意CLAUDE.md 是基于文本的指令文件不是某种需要编译配置。它的优先级比 AI 从代码里自己推断出来的结果高但又低于你在会话里直接输入的指令。换句话说如果你在对话里明确说这次先不按 CLAUDE.md 的规则来那 AI 会优先听你当前的指令。这个优先级关系很重要它说明 CLAUDE.md 不是锁死行为的强制约束而是默认遵循的长期约定。2.2 哪些内容值得长期存哪些不能往里面塞明白了加载机制下一个问题就是什么该写什么不该写。我自己的判断标准是这条项目信息是否每次会话都需要值得写项目技术栈页面跳转方式、API 封装风格、状态管理方案、目录结构说明、代码风格约定、必须执行的命令、绝对不能碰的操作。不该写一次性任务的说明、关于某个 bug 的临时讨论结论、需要频繁变动的细节比如某次联调的临时 IP、过于宽泛的废话比如请写出高质量的代码这种等于没写的句子。CLAUDE.md 的容量也有限它占用的上下文越大留给实际代码分析和对话的空间就越小。这个文件就像是 AI 的工作记忆的一部分如果里面全是废话那真正重要的规则反而会被稀释。我见过有人把整个项目的文档链接全塞进 CLAUDE.md结果 AI 处理核心任务时的表现反而不如以前——信息太多干扰就多。这个文件必须保持精炼和高度结构化。2.3 全局配置与项目配置的分工Claude Code 还支持用户级别的配置目录把那些跨项目通用的规则比如你个人偏好的格式化工具、常用的命令习惯放在全局位置。这样项目 CLAUDE.md 只需要专注这个项目独有的信息。我个人的分工习惯是层级放什么内容示例全局配置跨项目的个人偏好、通用工作流统一使用 pnpm 安装依赖、变更文件后运行类型检查项目 CLAUDE.md项目特有架构、目录约定、命名规则页面跳转必须通过 pages.js 注册禁止直接用 window.location这样划分的好处是你不用在每一个项目的 CLAUDE.md 里重复写用 pnpm也不用担心新项目继承了不该继承的旧项目规则。全局管人项目管事两者不冲突。3. 一份靠谱的 CLAUDE.md 长什么样结构模板与逐块拆解看再多理论不如直接拆一份实际能用的。下面这份结构是从我自己在真实项目中打磨出来的经过了好几轮增删是目前比较稳的一个版本。它不一定能直接复用到你所有项目里但每个模块的思考逻辑你可以直接拿走。3.1 五段式项目概述、命令、架构、规范、禁区我习惯把 CLAUDE.md 组织成五个部分每部分解决一类问题项目概述三到五句话讲清这项目是什么、核心业务流程是什么、服务端和前端怎么交互。常用命令安装依赖、启动开发服务器、跑测试、构建、代码检查。AI 需要执行命令时它能从这里快速找到正确姿势。架构与目录约定关键目录的职责说明、数据流向、模块边界。这部分帮助 AI 在动代码之前找到正确的位置。代码规范命名方式、组件拆分粒度、接口调用的封装约束、样式方案。红线与禁区明明白白写清楚哪些操作是绝对不能做的。这五个部分的顺序不是随便定的。项目概述在最前面让 AI 在最短的段落里建立对项目的整体认知接着是命令因为 AI 干活经常需要跑命令放在靠前位置能快速定位再后面才是架构和规范这些信息量最大需要 AI 在生成代码时反复参照红线和禁区放最后起兜底作用。3.2 命令与脚本写清楚什么时候用哪条很多人在写这个模块时只列命令不写使用场景结果 AI 照样用错。比如你写了npm run dev是启动开发服务器但没写联调模式下需要用npm run dev:mock那 AI 在需要 mock 数据的任务里还是会茫然地调用普通模式。我现在的写法是每条命令配一句何时使用的说明。## 常用命令 - 安装依赖pnpm install新克隆项目时必须先执行 - 开发服务器pnpm dev本地调试默认端口 5173 - 联调模式pnpm dev:mock当后端接口未就绪时使用走本地 mock 数据 - 单元测试pnpm test修改公共函数或工具类后必须运行 - 类型检查pnpm typecheck修改接口类型定义后必须运行 - 构建产物pnpm build提交到测试环境前执行需确认无类型错误这套写法的逻辑很清楚命令不是孤立存在的它跟项目的开发流程深度绑定。AI 看得越多越能理解这些命令在什么时机被触发而不是机械地背一串命令行。3.3 架构信息要用地图逻辑而不是论文逻辑架构这个模块最容易写成流水账比如src 目录放源码public 目录放静态资源——这种正确的废话没有任何信息量。真正有用的架构说明应该像一张地图它告诉 AI你要找的东西大概在哪个区域从哪里出发能到途中会经过哪些关键节点。以我手头一个 Vue3 单页面工程为例我写的是## 架构与目录约定 - src/pages 下的每个目录对应一个路由页面页面注册在 src/pages.js - 当前项目为单页面工程不能执行页面跳转 API如 window.location.href - 如果需要进行页面跳转必须先在 src/pages.js 中注册页面路径然后使用项目封装的 navigateTo 方法 - src/api 是唯一的接口请求入口所有 HTTP 请求只能通过这里封装禁止在组件内直接调用 axios 或 fetch - src/components 只放可复用的展示型组件带业务请求逻辑的组件就近放在所属页面目录下的 components/ 子目录注意看这些句子的写法。我没有写逻辑要清晰要保持一致性这种空话而是直接给地图坐标页面跳转去哪找注册文件接口请求走哪个入口。AI 拿到这些信息在具体写代码时就不会瞎猜。4. 实战为一个 Vue3 单页面项目写出第一版 CLAUDE.md光看结构还是有点虚我拿一个真实场景完整的走一遍。有一段时间我接手了一个 Vue3 的移动端单页面应用后端接口用的是 Java Spring Boot。项目老化文档缺失团队成员离职前留下了一大摊约定俗成的规矩。我要让 AI 在这个项目里帮忙改需求但它第一周的表现只能用灾难来形容页面跳转搞得乱七八糟、接口调用到处裸写、新加的组件不按现有目录放。后来我花了一个下午做了三件事把 CLAUDE.md 落地了。整个过程完全可以复刻。4.1 第一步收集散落在代码里的潜规则写 CLAUDE.md 的第一步不是动笔是去代码里考古。我通读了几个有代表性的旧模块重点关注这几个问题入口文件里初始化了什么全局注册了什么路由是怎么声明的页面跳转有没有统一封装接口请求的 baseURL 和拦截器做了什么错误处理是统一的还是各写各的样式用的是原生 CSS、预处理器还是有组件库目录里哪些文件是废弃的、绝对不能参照的考古这步很关键因为 AI 生成代码时主要参照的是现存代码的模式如果你不把这些模式提炼出来它只能自己猜。而自己猜的后果十有八九是不符合你项目习惯的。我最终从那个项目里提炼出了一批高频规则比如页面跳转不能用浏览器原生方式必须走pages.js注册。所有请求走src/api下的模块每个模块对应一个后端 controller。后端返回结构是{ code, data, message }code 0才表示成功。这些潜规则原来的团队成员靠口口相传新来的 AI 根本不知道。但它们恰恰是 AI 写代码时最容易踩坑的地方。4.2 第二步动手落笔写完立刻测试收集完规则我按照上一节的五段式框架把它们组织成文。这里有个技巧不要一口气写太长先把最关键的、最不能出错的红线写进去。我把页面跳转和接口请求封装这两个最痛的规则放在了最显眼的位置确保 AI 读取时第一眼就能看到。落笔之后立刻做了一次实测开一个新会话让 AI 做一个之前翻过车的任务——在某页面上加一个按钮点击后跳转到另一个页面。以前它的做法五花八门有的直接改 URL有的用window.location.href有的甚至尝试调用 Vue Router 里根本不存在的 API。写完 CLAUDE.md 再试它会老老实实地先去查pages.js找不到目标页面就说需要先注册然后问我目标页面的路径是什么。这一步的体验非常直接AI 的行为改了那些反复纠正过的问题终于不用再纠正第二遍。4.3 第三步观察 AI 跑偏的地方持续补规则没有一份 CLAUDE.md 能一次性覆盖所有情况。我在后续两周的使用中只要发现 AI 在某个地方的行为不符合预期就记一笔攒几天统一更新一次文件。这不是什么高级操作但特别有效。CLAUDE.md 用着用着就不止是给 AI 的说明书了它慢慢变成了整个项目实际约定的沉淀——团队成员拿它给新人做培训也很合适。一个让我印象很深的例子是后端返回结构的问题。AI 在对接接口时总默认response.data就是业务数据但那个项目的后端返回结构是多包了一层的正确写法应该是response.data.data。这个事我在 CLAUDE.md 里写了一句话解释之后 AI 就再没犯过这个错。5. 文件本身的维护CLAUDE.md 也需要代码评审CLAUDE.md 写完了不是一劳永逸。项目在演进规则在变化文件如果没人维护很快会从帮手变成绊脚石。5.1 什么情况下必须更新我给自己定了几个强制更新的触发条件依赖或技术栈变更比如从 Vue 3.2 升级到 3.5或者引入了一个新的状态管理库CLAUDE.md 里的命令和架构说明必须同步。目录结构大调整比如把src/api重构成src/services地图都变了AI 需要新的坐标。发现 AI 反复犯同类错误说明现有规则有漏洞要把针对性的约束写进去。团队定了新的约定比如后端返回结构加了新字段或者新增了统一的错误处理方式。5.2 哪些内容要果断删除我维护 CLAUDE.md 时有一条原则凡是暂时有用、长期没用的临时信息一律不写。举几个反例当前后端联调环境地址是 192.168.x.x——这个明后天可能就变了写进去反而会让 AI 在地址变更后继续用旧地址。某个文件里有 bug临时跳过——这应该写进 issue不是写进 CLAUDE.md。张三负责聊天模块李四负责订单模块——项目成员变动频繁这句话的下场就是过期、误导。保留这些临时信息最直接的代价是 CLAUDE.md 变臃肿AI 找关键规则的效率下降。更隐蔽的代价是AI 会把过期信息当成现价信息来用那比没有这个文件更糟。5.3 让规则可验证而不是靠自觉这一点我觉得是最能拉开使用体验差距的。CLAUDE.md 里的描述越容易被验证AI 的遵循效果越好。怎么理解可验证举个例子如果你写组件命名请保持一致性AI 会一头雾水什么算一致怎么验证但如果写页面级组件使用 PascalCase 命名放在src/pages对应目录下公共组件使用 camelCase 命题放在src/components目录下AI 就能在生成代码后自己对照这个规则检查。再比如接口请求规则如果写不要随便发请求同样无法执行。但如果写新建 API 函数时必须使用request.js里的统一封装并在src/api对应模块中注册导出AI 执行时就有明确参照。我的经验是每条规则写完都问自己一句——AI 拿到这句话能直接判断自己做对了没有吗如果不能就重写。这跟给团队写开发规范是一个道理只不过 AI 比人更需要明确、无歧义的指令。5.4 亲自跟着 AI 走一遍流程验证文件生效写完或者大改完 CLAUDE.md一定要花几分钟走一个验证清单新开一个会话随便给它派一个小任务这个任务必须覆盖你写在文件里的核心规则。比如让它在现有项目里新增一个列表页看它会不会正确使用pages.js注册。让它在页面里调用一个不存在的接口看它会不会尝试自己裸用 axios。让它改一个公共组件看它会不会把该组件的全局影响都考虑进去。如果这些测试里有一项结果是AI 还在犯老毛病那大概率不是模型的问题是你文件里的规则还不够精确或者位置不够靠前。调整后重测。这个流程土但特别管用。它确保你的 CLAUDE.md 不是一份看起来很有道理的文档而是一份真正能改变 AI 行为的工程配置。6. 结合其他机制把 AI 的长期记忆再加固一层CLAUDE.md 是让 AI 记住项目潜规则的核心手段但不是唯一手段。实际使用中我还发现几个配合技巧能让整个体验更稳、更可维护。6.1 用import把子文档拆出去Claude Code 支持在 CLAUDE.md 里import其他的 Markdown 文件。当项目特别大规则特别多时把一个文件堆到一两千行不仅维护累加载也费。我现在的做法是拆分成几个主题文件commands.md管命令、architecture.md管架构、coding-style.md管规范。CLAUDE.md 本身只保留最核心的总纲和一个import列表。这样做的好处是AI 依然是统一加载的但你维护时可以精准定位到具体的模块去改不用在一个巨型文件里滚来滚去地找那行字。内容的组织清晰了规则本身的质量也会跟着上来。6.2 关键文件里再埋一版局部说明书CLAUDE.md 是全局项目规则但有些核心文件太复杂值得有自己的局部说明。比如那个pages.js本身我在文件顶部加了一段注释简单说明路径注册规则和参数格式。AI 读取这个文件时这段注释比 CLAUDE.md 里的描述距离更近作用更直接。这种做法相当于分层记忆CLAUDE.md 负责宏观的项目级约定文件顶部注释负责微观的文件级说明。两者配合让 AI 在任何一层读取代码时都能拿到当下最需要的上下文。6.3 维护 CLAUDE.md 本身也是给团队做文档沉淀用 CLAUDE.md 一段时间之后你会发现一件事它其实是把团队里靠嘴传、靠脑记的知识变成了写下来、可执行的资产。新人加入时不用再有人跟在后面解释我们项目跳转页面必须走 pages.js这类的规则AI 开发助手也能更快进入靠谱状态。这个副产物对我帮助很大。以前团队成员问我这个项目有什么约定我能答上来一部分但总担心漏了哪个角落。现在直接看 CLAUDE.md所有人看到的信息是完全一致的不再有信息差。7. 几条最实在的体会权当送你的避坑指南最后聊几条我在实际使用里跌过跟头才总结出来的体会不一定适合所有人但大概率适合正在被 AI 金鱼记忆折磨的你。关于内容量精确比全面重要得多。三句中肯的规则效果胜过大段空泛的描述。宁可让 CLAUDE.md 看起来不够长也别让它充满正确的废话。关于文件位置放在项目根目录、保持命名准确注意大小写.md后缀不能少这是最基本的前提。我见过有人把文件放进了docs/目录结果完全不生效折腾半天还以为是工具出了问题。关于更新频率不要写完就忘。我建议把它纳入技术评审的范围每次有规则调整或架构变化像改代码一样去改它。这个文件跟着项目一起演进它才有长期价值。关于 AI 的配合度新开会话时的首次指令也很关键。我习惯在交代任务前先补一句请先阅读根目录的 CLAUDE.md严格按照里面定义的规范执行。虽然理论上 AI 会自动加载这些内容但明确强调一次相当于把规则在它的注意力里置顶了一遍效果会更稳定。说到底CLAUDE.md 的核心理念就是一句话与其每次重复教 AI不如把项目规则沉淀成一个文件让它变成 AI 的肌肉记忆。如果你还没试过我建议今天就花半小时给现有项目写一个初版然后挑一个之前反复翻车的任务测一遍。那种AI 终于不再犯同一个错误的感觉值得你亲身体验一下。
用CLAUDE.md给AI写项目说明书，根治反复犯错问题
1. 为什么我给 AI 写了份项目说明书之后它才真正开始像自己人先说个真实场景。我用 AI 编程助手写代码已经有一阵子了。工具确实快但有个问题一直很烦它在同一个项目里反复犯同样的错。今天告诉它这个项目的 API 请求统一封装在src/api里不要直接写 fetch它能听话十分钟。明天新开一个会话你还没来得及交代它又自顾自地在组件里裸写 fetch 了。你说它笨吧它能帮你写出整个 CRUD 页面你说它聪明吧它记性是真的差每次都得重新教。后来我想明白了一件事这不是模型的智商问题是我自己的工作方式问题。我没给 AI 一个稳定的项目上下文。就好比一个外包同事今天刚入职你指望他看一眼代码就懂你们组的命名规范、接口约定、目录结构和部署流程这不现实。你得给他一份入职手册。对 AI 来说这份手册就是 CLAUDE.md。CLAUDE.md 是 Claude Code 这类命令行 AI 编程工具读取的项目级指令文件。它用 Markdown 格式记录整个项目的潜规则项目是什么架构、目录怎么划分、代码风格有什么约定、哪些命令必须跑、哪些操作绝对不能做。只要文件放在项目根目录AI 在每次会话里都会自动把它的内容当作上下文的一部分。换句话说你写一遍它每次都用得上再也不用你翻来覆去地重复交代。这篇文章我会老老实实讲清楚CLAUDE.md 到底是怎么工作的、一份合格的 CLAUDE.md 应该写什么、怎么写以及我踩过哪些坑之后才总结出来的维护经验。如果你也在用 AI 编程工具做实际项目尤其是 Vue3、Spring Boot 这类工程量不小、约定不少的技术栈这篇文章应该能让你少折腾好几个晚上。2. 先搞清楚 CLAUDE.md 的加载机制才知道它该写什么很多人第一次接触 CLAUDE.md 容易陷入两个极端要么把它当成万能配置指望写几行字 AI 就能瞬间变成项目专家要么把它当成摆设随便抄个模板就扔进仓库再也不管。这两个极端我都试过效果都不好。搞清楚它的加载机制和生效边界你才知道哪些内容放进这个文件才有意义。2.1 它何时被读取以及为什么放根目录最稳妥CLAUDE.md 的核心机制是自动注入上下文。Claude Code 在启动会话、读取项目文件的时候会自动去项目根目录找这个文件把里面的内容加载进对话上下文。你不需要每次手动指定也不需要输入什么特殊的命令工具本身会处理这件事。这里有个关键细节既然是按路径查找那文件位置就决定了它的作用范围。放在项目根目录的 CLAUDE.md只有在进入这个项目目录工作时才会被加载换到别的项目就不生效。如果你有多个项目共用的规则那应该考虑放在更上层的目录或者使用工具支持的用户级配置文件而不是把全局的东西塞进每个项目的 CLAUDE.md 里。还有一点值得注意CLAUDE.md 是基于文本的指令文件不是某种需要编译配置。它的优先级比 AI 从代码里自己推断出来的结果高但又低于你在会话里直接输入的指令。换句话说如果你在对话里明确说这次先不按 CLAUDE.md 的规则来那 AI 会优先听你当前的指令。这个优先级关系很重要它说明 CLAUDE.md 不是锁死行为的强制约束而是默认遵循的长期约定。2.2 哪些内容值得长期存哪些不能往里面塞明白了加载机制下一个问题就是什么该写什么不该写。我自己的判断标准是这条项目信息是否每次会话都需要值得写项目技术栈页面跳转方式、API 封装风格、状态管理方案、目录结构说明、代码风格约定、必须执行的命令、绝对不能碰的操作。不该写一次性任务的说明、关于某个 bug 的临时讨论结论、需要频繁变动的细节比如某次联调的临时 IP、过于宽泛的废话比如请写出高质量的代码这种等于没写的句子。CLAUDE.md 的容量也有限它占用的上下文越大留给实际代码分析和对话的空间就越小。这个文件就像是 AI 的工作记忆的一部分如果里面全是废话那真正重要的规则反而会被稀释。我见过有人把整个项目的文档链接全塞进 CLAUDE.md结果 AI 处理核心任务时的表现反而不如以前——信息太多干扰就多。这个文件必须保持精炼和高度结构化。2.3 全局配置与项目配置的分工Claude Code 还支持用户级别的配置目录把那些跨项目通用的规则比如你个人偏好的格式化工具、常用的命令习惯放在全局位置。这样项目 CLAUDE.md 只需要专注这个项目独有的信息。我个人的分工习惯是层级放什么内容示例全局配置跨项目的个人偏好、通用工作流统一使用 pnpm 安装依赖、变更文件后运行类型检查项目 CLAUDE.md项目特有架构、目录约定、命名规则页面跳转必须通过 pages.js 注册禁止直接用 window.location这样划分的好处是你不用在每一个项目的 CLAUDE.md 里重复写用 pnpm也不用担心新项目继承了不该继承的旧项目规则。全局管人项目管事两者不冲突。3. 一份靠谱的 CLAUDE.md 长什么样结构模板与逐块拆解看再多理论不如直接拆一份实际能用的。下面这份结构是从我自己在真实项目中打磨出来的经过了好几轮增删是目前比较稳的一个版本。它不一定能直接复用到你所有项目里但每个模块的思考逻辑你可以直接拿走。3.1 五段式项目概述、命令、架构、规范、禁区我习惯把 CLAUDE.md 组织成五个部分每部分解决一类问题项目概述三到五句话讲清这项目是什么、核心业务流程是什么、服务端和前端怎么交互。常用命令安装依赖、启动开发服务器、跑测试、构建、代码检查。AI 需要执行命令时它能从这里快速找到正确姿势。架构与目录约定关键目录的职责说明、数据流向、模块边界。这部分帮助 AI 在动代码之前找到正确的位置。代码规范命名方式、组件拆分粒度、接口调用的封装约束、样式方案。红线与禁区明明白白写清楚哪些操作是绝对不能做的。这五个部分的顺序不是随便定的。项目概述在最前面让 AI 在最短的段落里建立对项目的整体认知接着是命令因为 AI 干活经常需要跑命令放在靠前位置能快速定位再后面才是架构和规范这些信息量最大需要 AI 在生成代码时反复参照红线和禁区放最后起兜底作用。3.2 命令与脚本写清楚什么时候用哪条很多人在写这个模块时只列命令不写使用场景结果 AI 照样用错。比如你写了npm run dev是启动开发服务器但没写联调模式下需要用npm run dev:mock那 AI 在需要 mock 数据的任务里还是会茫然地调用普通模式。我现在的写法是每条命令配一句何时使用的说明。## 常用命令 - 安装依赖pnpm install新克隆项目时必须先执行 - 开发服务器pnpm dev本地调试默认端口 5173 - 联调模式pnpm dev:mock当后端接口未就绪时使用走本地 mock 数据 - 单元测试pnpm test修改公共函数或工具类后必须运行 - 类型检查pnpm typecheck修改接口类型定义后必须运行 - 构建产物pnpm build提交到测试环境前执行需确认无类型错误这套写法的逻辑很清楚命令不是孤立存在的它跟项目的开发流程深度绑定。AI 看得越多越能理解这些命令在什么时机被触发而不是机械地背一串命令行。3.3 架构信息要用地图逻辑而不是论文逻辑架构这个模块最容易写成流水账比如src 目录放源码public 目录放静态资源——这种正确的废话没有任何信息量。真正有用的架构说明应该像一张地图它告诉 AI你要找的东西大概在哪个区域从哪里出发能到途中会经过哪些关键节点。以我手头一个 Vue3 单页面工程为例我写的是## 架构与目录约定 - src/pages 下的每个目录对应一个路由页面页面注册在 src/pages.js - 当前项目为单页面工程不能执行页面跳转 API如 window.location.href - 如果需要进行页面跳转必须先在 src/pages.js 中注册页面路径然后使用项目封装的 navigateTo 方法 - src/api 是唯一的接口请求入口所有 HTTP 请求只能通过这里封装禁止在组件内直接调用 axios 或 fetch - src/components 只放可复用的展示型组件带业务请求逻辑的组件就近放在所属页面目录下的 components/ 子目录注意看这些句子的写法。我没有写逻辑要清晰要保持一致性这种空话而是直接给地图坐标页面跳转去哪找注册文件接口请求走哪个入口。AI 拿到这些信息在具体写代码时就不会瞎猜。4. 实战为一个 Vue3 单页面项目写出第一版 CLAUDE.md光看结构还是有点虚我拿一个真实场景完整的走一遍。有一段时间我接手了一个 Vue3 的移动端单页面应用后端接口用的是 Java Spring Boot。项目老化文档缺失团队成员离职前留下了一大摊约定俗成的规矩。我要让 AI 在这个项目里帮忙改需求但它第一周的表现只能用灾难来形容页面跳转搞得乱七八糟、接口调用到处裸写、新加的组件不按现有目录放。后来我花了一个下午做了三件事把 CLAUDE.md 落地了。整个过程完全可以复刻。4.1 第一步收集散落在代码里的潜规则写 CLAUDE.md 的第一步不是动笔是去代码里考古。我通读了几个有代表性的旧模块重点关注这几个问题入口文件里初始化了什么全局注册了什么路由是怎么声明的页面跳转有没有统一封装接口请求的 baseURL 和拦截器做了什么错误处理是统一的还是各写各的样式用的是原生 CSS、预处理器还是有组件库目录里哪些文件是废弃的、绝对不能参照的考古这步很关键因为 AI 生成代码时主要参照的是现存代码的模式如果你不把这些模式提炼出来它只能自己猜。而自己猜的后果十有八九是不符合你项目习惯的。我最终从那个项目里提炼出了一批高频规则比如页面跳转不能用浏览器原生方式必须走pages.js注册。所有请求走src/api下的模块每个模块对应一个后端 controller。后端返回结构是{ code, data, message }code 0才表示成功。这些潜规则原来的团队成员靠口口相传新来的 AI 根本不知道。但它们恰恰是 AI 写代码时最容易踩坑的地方。4.2 第二步动手落笔写完立刻测试收集完规则我按照上一节的五段式框架把它们组织成文。这里有个技巧不要一口气写太长先把最关键的、最不能出错的红线写进去。我把页面跳转和接口请求封装这两个最痛的规则放在了最显眼的位置确保 AI 读取时第一眼就能看到。落笔之后立刻做了一次实测开一个新会话让 AI 做一个之前翻过车的任务——在某页面上加一个按钮点击后跳转到另一个页面。以前它的做法五花八门有的直接改 URL有的用window.location.href有的甚至尝试调用 Vue Router 里根本不存在的 API。写完 CLAUDE.md 再试它会老老实实地先去查pages.js找不到目标页面就说需要先注册然后问我目标页面的路径是什么。这一步的体验非常直接AI 的行为改了那些反复纠正过的问题终于不用再纠正第二遍。4.3 第三步观察 AI 跑偏的地方持续补规则没有一份 CLAUDE.md 能一次性覆盖所有情况。我在后续两周的使用中只要发现 AI 在某个地方的行为不符合预期就记一笔攒几天统一更新一次文件。这不是什么高级操作但特别有效。CLAUDE.md 用着用着就不止是给 AI 的说明书了它慢慢变成了整个项目实际约定的沉淀——团队成员拿它给新人做培训也很合适。一个让我印象很深的例子是后端返回结构的问题。AI 在对接接口时总默认response.data就是业务数据但那个项目的后端返回结构是多包了一层的正确写法应该是response.data.data。这个事我在 CLAUDE.md 里写了一句话解释之后 AI 就再没犯过这个错。5. 文件本身的维护CLAUDE.md 也需要代码评审CLAUDE.md 写完了不是一劳永逸。项目在演进规则在变化文件如果没人维护很快会从帮手变成绊脚石。5.1 什么情况下必须更新我给自己定了几个强制更新的触发条件依赖或技术栈变更比如从 Vue 3.2 升级到 3.5或者引入了一个新的状态管理库CLAUDE.md 里的命令和架构说明必须同步。目录结构大调整比如把src/api重构成src/services地图都变了AI 需要新的坐标。发现 AI 反复犯同类错误说明现有规则有漏洞要把针对性的约束写进去。团队定了新的约定比如后端返回结构加了新字段或者新增了统一的错误处理方式。5.2 哪些内容要果断删除我维护 CLAUDE.md 时有一条原则凡是暂时有用、长期没用的临时信息一律不写。举几个反例当前后端联调环境地址是 192.168.x.x——这个明后天可能就变了写进去反而会让 AI 在地址变更后继续用旧地址。某个文件里有 bug临时跳过——这应该写进 issue不是写进 CLAUDE.md。张三负责聊天模块李四负责订单模块——项目成员变动频繁这句话的下场就是过期、误导。保留这些临时信息最直接的代价是 CLAUDE.md 变臃肿AI 找关键规则的效率下降。更隐蔽的代价是AI 会把过期信息当成现价信息来用那比没有这个文件更糟。5.3 让规则可验证而不是靠自觉这一点我觉得是最能拉开使用体验差距的。CLAUDE.md 里的描述越容易被验证AI 的遵循效果越好。怎么理解可验证举个例子如果你写组件命名请保持一致性AI 会一头雾水什么算一致怎么验证但如果写页面级组件使用 PascalCase 命名放在src/pages对应目录下公共组件使用 camelCase 命题放在src/components目录下AI 就能在生成代码后自己对照这个规则检查。再比如接口请求规则如果写不要随便发请求同样无法执行。但如果写新建 API 函数时必须使用request.js里的统一封装并在src/api对应模块中注册导出AI 执行时就有明确参照。我的经验是每条规则写完都问自己一句——AI 拿到这句话能直接判断自己做对了没有吗如果不能就重写。这跟给团队写开发规范是一个道理只不过 AI 比人更需要明确、无歧义的指令。5.4 亲自跟着 AI 走一遍流程验证文件生效写完或者大改完 CLAUDE.md一定要花几分钟走一个验证清单新开一个会话随便给它派一个小任务这个任务必须覆盖你写在文件里的核心规则。比如让它在现有项目里新增一个列表页看它会不会正确使用pages.js注册。让它在页面里调用一个不存在的接口看它会不会尝试自己裸用 axios。让它改一个公共组件看它会不会把该组件的全局影响都考虑进去。如果这些测试里有一项结果是AI 还在犯老毛病那大概率不是模型的问题是你文件里的规则还不够精确或者位置不够靠前。调整后重测。这个流程土但特别管用。它确保你的 CLAUDE.md 不是一份看起来很有道理的文档而是一份真正能改变 AI 行为的工程配置。6. 结合其他机制把 AI 的长期记忆再加固一层CLAUDE.md 是让 AI 记住项目潜规则的核心手段但不是唯一手段。实际使用中我还发现几个配合技巧能让整个体验更稳、更可维护。6.1 用import把子文档拆出去Claude Code 支持在 CLAUDE.md 里import其他的 Markdown 文件。当项目特别大规则特别多时把一个文件堆到一两千行不仅维护累加载也费。我现在的做法是拆分成几个主题文件commands.md管命令、architecture.md管架构、coding-style.md管规范。CLAUDE.md 本身只保留最核心的总纲和一个import列表。这样做的好处是AI 依然是统一加载的但你维护时可以精准定位到具体的模块去改不用在一个巨型文件里滚来滚去地找那行字。内容的组织清晰了规则本身的质量也会跟着上来。6.2 关键文件里再埋一版局部说明书CLAUDE.md 是全局项目规则但有些核心文件太复杂值得有自己的局部说明。比如那个pages.js本身我在文件顶部加了一段注释简单说明路径注册规则和参数格式。AI 读取这个文件时这段注释比 CLAUDE.md 里的描述距离更近作用更直接。这种做法相当于分层记忆CLAUDE.md 负责宏观的项目级约定文件顶部注释负责微观的文件级说明。两者配合让 AI 在任何一层读取代码时都能拿到当下最需要的上下文。6.3 维护 CLAUDE.md 本身也是给团队做文档沉淀用 CLAUDE.md 一段时间之后你会发现一件事它其实是把团队里靠嘴传、靠脑记的知识变成了写下来、可执行的资产。新人加入时不用再有人跟在后面解释我们项目跳转页面必须走 pages.js这类的规则AI 开发助手也能更快进入靠谱状态。这个副产物对我帮助很大。以前团队成员问我这个项目有什么约定我能答上来一部分但总担心漏了哪个角落。现在直接看 CLAUDE.md所有人看到的信息是完全一致的不再有信息差。7. 几条最实在的体会权当送你的避坑指南最后聊几条我在实际使用里跌过跟头才总结出来的体会不一定适合所有人但大概率适合正在被 AI 金鱼记忆折磨的你。关于内容量精确比全面重要得多。三句中肯的规则效果胜过大段空泛的描述。宁可让 CLAUDE.md 看起来不够长也别让它充满正确的废话。关于文件位置放在项目根目录、保持命名准确注意大小写.md后缀不能少这是最基本的前提。我见过有人把文件放进了docs/目录结果完全不生效折腾半天还以为是工具出了问题。关于更新频率不要写完就忘。我建议把它纳入技术评审的范围每次有规则调整或架构变化像改代码一样去改它。这个文件跟着项目一起演进它才有长期价值。关于 AI 的配合度新开会话时的首次指令也很关键。我习惯在交代任务前先补一句请先阅读根目录的 CLAUDE.md严格按照里面定义的规范执行。虽然理论上 AI 会自动加载这些内容但明确强调一次相当于把规则在它的注意力里置顶了一遍效果会更稳定。说到底CLAUDE.md 的核心理念就是一句话与其每次重复教 AI不如把项目规则沉淀成一个文件让它变成 AI 的肌肉记忆。如果你还没试过我建议今天就花半小时给现有项目写一个初版然后挑一个之前反复翻车的任务测一遍。那种AI 终于不再犯同一个错误的感觉值得你亲身体验一下。