同样一个 Claude Code有人用着像捡到宝有人用着天天想砸键盘。差距八成不在工具在你有没有给它一份像样的CLAUDE.md。这篇是《Claude Code 从入门到精通》专栏的进阶篇。装好、跑通第一个项目之后真正决定它懂不懂你代码的就是项目根目录那份CLAUDE.md。我把自己维护了大半年、踩过坑改了十几版的写法完整交出来含一份可直接复制改用的模板照着写一遍你会明显感觉它从猜你想干嘛变成知道你想干嘛。一、为什么 CLAUDE.md 决定上限Claude Code 每次启动一个项目会自动读取项目根目录的CLAUDE.md把里面的内容当成这个项目的最高指令注入上下文。它不是普通文档是你和 AI 之间的契约。没有它会怎样真实场景你的项目用pnpm它默认上来就npm install把 lock 文件搞乱。你的代码全是函数式风格它给你塞了一堆 class。你明明有现成的request封装它自己fetch重新写一遍。你让它加个接口它顺手把隔壁不相关的文件也优化了。这些都不是模型笨是它不知道你的规矩。CLAUDE.md就是把规矩一次性讲清楚让它每次都按你的来。一句话没有 CLAUDE.md 的 Claude Code只发挥了三成功力。二、放在哪、怎么生成第一版位置项目根目录的CLAUDE.md—— 整个项目生效最常用。子目录也可以放CLAUDE.md—— 只在该目录下的工作生效大型 monorepo 用。用户级~/.claude/CLAUDE.md—— 跨所有项目的你个人偏好比如回答用中文。三层会叠加越具体的优先级越高。生成第一版别手搓让它自己扫进项目后直接敲/initClaude Code 会扫描你的项目结构、依赖、技术栈自动生成一份CLAUDE.md初稿。这是起点不是终点——自动生成的偏描述项目长啥样而真正值钱的是下面这些你必须知道的规矩得你自己补。三、一份好 CLAUDE.md 该写什么六个必备模块我把有用的内容归成六块按重要性排序。核心原则写约束和陷阱不写正确的废话。1. 项目是什么 技术栈一句话级别让它三秒钟知道这是个什么项目、用什么写的。别写小作文。## 项目 一个面向 B 端的订单管理后台。前端 Vue3 TS Pinia后端 FastAPI PostgreSQL。2. 命令清单这是回报最高的一块把怎么装、怎么跑、怎么测、怎么 build明确写死。它最容易在这翻车——用错包管理器、跑错测试命令。## 命令 - 包管理器只用 pnpm禁止 npm/yarn - 装依赖pnpm install - 起开发pnpm dev - 跑测试pnpm test改完代码必须跑 - 类型检查pnpm typecheck - 构建pnpm build3. 代码规范与风格写约束不写教程不是教它怎么写代码是告诉它你的项目跟别人不一样的地方。## 代码规范 - 组件用 script setup 语法不用 Options API - 状态管理一律走 Pinia store禁止在组件里直接调 axios - 网络请求统一用 src/utils/request.ts 的封装不要裸用 fetch/axios - 命名组件 PascalCase工具函数 camelCase常量 UPPER_SNAKE - 注释和 commit 用英文文档用中文4. 项目结构地图让它别乱放文件告诉它每类东西该放哪它就不会把一个 util 塞进 components。## 目录约定 - src/views/ 页面级组件 - src/components/ 可复用组件 - src/api/ 接口定义每个模块一个文件 - src/stores/ Pinia store - src/utils/ 纯工具函数无副作用5. 雷区与禁忌最能防事故的一块把绝对不能干的事列出来。这块每救你一次都是省下一场返工。## 雷区务必遵守 - 禁止修改 src/legacy/ 下任何文件老系统改了会崩 - 禁止改动数据库 migration 历史文件只能新增 - 改完任何代码必须跑 pnpm test红了自己修别留给我 - 不确定的设计决策先问我不要自作主张大改 - 一次只做我让你做的事不要顺手优化无关代码6. 上下文锚点让它知道去哪找答案告诉它哪些文件是真源它就会先去读再动手。## 关键文件 - 接口约定看 docs/api.md - 业务术语表看 docs/glossary.md - 环境变量说明看 .env.example四、可直接复制的模板把下面这份存成项目根目录的CLAUDE.md替换尖括号内容即可# 项目名 这是给 Claude Code 看的项目契约。务必遵守下面的约束。 ## 项目 一句话说清项目是什么 技术栈 ## 命令 - 包管理器pnpm / npm / poetry / ...禁止用其它 - 装依赖命令 - 开发命令 - 测试命令改完代码必须跑红了自己修 - 构建命令 ## 代码规范 - 风格约束 1例如函数式优先避免 class - 统一封装例如请求走 utils/request不裸用 fetch - 命名约定 - 注释/commit 用英文文档用中文 ## 目录约定 - dir/ 放什么 - dir/ 放什么 ## 雷区务必遵守 - 禁止修改 某目录/某文件 - 改完代码必须跑测试不要留红 - 一次只做被要求的事不要顺手改无关代码 - 不确定先问不要擅自大改 ## 关键文件 - 约定/术语/配置 的真源路径五、五个让效果翻倍的实战技巧踩坑总结1. 越短越好别写成手册。CLAUDE.md越长关键约束越容易被淹没。我的经验是控制在 100 行以内每条都是不写它就会犯的错。写满 500 行的文档它读了等于没读。2. 用禁止/务必这种硬词。“建议用 pnpm和禁止用 npm”效果天差地别。约束要写成命令式别写成商量。3. 让它自己维护。发现它又犯了同一个错直接说把这条规矩补进 CLAUDE.md。它会帮你加。CLAUDE.md是越用越准的活文档。4. 用#快捷记忆实测好用。对话里你随口说一句让它记住的规矩开头加#比如# 以后所有时间字段都用 UTCClaude Code 会问你要不要写进CLAUDE.md一键沉淀。5. 别把密钥/敏感信息写进去。CLAUDE.md会被完整读进上下文也常会进 git。API Key、密码这类东西放.env在CLAUDE.md里只写密钥看 .env.example。六、常见踩坑全解Q我写了 CLAUDE.md它好像没读确认文件名是CLAUDE.md全大写、在项目根目录。改完后重启claude会话或新会话才会重新加载。聊到一半改的当前会话不一定生效。Q内容太多它记不住精简。把不影响它干活的项目背景介绍删掉只留命令、规范、雷区。它的注意力是有限的别浪费在废话上。Q多人协作每个人偏好不一样项目级CLAUDE.md放团队共识命令、规范、雷区个人偏好放各自的~/.claude/CLAUDE.md。两层不冲突。Q子目录的 CLAUDE.md 和根目录冲突怎么办就近原则子目录的优先。monorepo 里给每个子包写一份小的根目录写公共的。七、小结与下一步CLAUDE.md是你能给 Claude Code 的回报最高的一次性投入——花 20 分钟写好之后每次对话都在帮你省事、防错。记住一句话写约束和雷区不写正确的废话控制在 100 行以内。下一篇专栏我会讲用 Claude Code 做大型重构而不翻车——上千行的老代码怎么让它分批改、怎么用 git 兜底、怎么验证它没改坏。那篇会用到这篇的CLAUDE.md建议先把这篇的模板用起来。建议收藏本篇下次新建项目直接照模板抄。本专栏会持续更新 Claude Code 的进阶实战从 MCP 扩展、成本控制到子 Agent 编排每篇都能直接用到你的项目里。有自己的CLAUDE.md写法心得欢迎评论区交流我会挑好的补进文章。
别再让 Claude Code 瞎改了：一份 CLAUDE.md 让 AI 真正读懂你项目（含模板·避坑·2026）
同样一个 Claude Code有人用着像捡到宝有人用着天天想砸键盘。差距八成不在工具在你有没有给它一份像样的CLAUDE.md。这篇是《Claude Code 从入门到精通》专栏的进阶篇。装好、跑通第一个项目之后真正决定它懂不懂你代码的就是项目根目录那份CLAUDE.md。我把自己维护了大半年、踩过坑改了十几版的写法完整交出来含一份可直接复制改用的模板照着写一遍你会明显感觉它从猜你想干嘛变成知道你想干嘛。一、为什么 CLAUDE.md 决定上限Claude Code 每次启动一个项目会自动读取项目根目录的CLAUDE.md把里面的内容当成这个项目的最高指令注入上下文。它不是普通文档是你和 AI 之间的契约。没有它会怎样真实场景你的项目用pnpm它默认上来就npm install把 lock 文件搞乱。你的代码全是函数式风格它给你塞了一堆 class。你明明有现成的request封装它自己fetch重新写一遍。你让它加个接口它顺手把隔壁不相关的文件也优化了。这些都不是模型笨是它不知道你的规矩。CLAUDE.md就是把规矩一次性讲清楚让它每次都按你的来。一句话没有 CLAUDE.md 的 Claude Code只发挥了三成功力。二、放在哪、怎么生成第一版位置项目根目录的CLAUDE.md—— 整个项目生效最常用。子目录也可以放CLAUDE.md—— 只在该目录下的工作生效大型 monorepo 用。用户级~/.claude/CLAUDE.md—— 跨所有项目的你个人偏好比如回答用中文。三层会叠加越具体的优先级越高。生成第一版别手搓让它自己扫进项目后直接敲/initClaude Code 会扫描你的项目结构、依赖、技术栈自动生成一份CLAUDE.md初稿。这是起点不是终点——自动生成的偏描述项目长啥样而真正值钱的是下面这些你必须知道的规矩得你自己补。三、一份好 CLAUDE.md 该写什么六个必备模块我把有用的内容归成六块按重要性排序。核心原则写约束和陷阱不写正确的废话。1. 项目是什么 技术栈一句话级别让它三秒钟知道这是个什么项目、用什么写的。别写小作文。## 项目 一个面向 B 端的订单管理后台。前端 Vue3 TS Pinia后端 FastAPI PostgreSQL。2. 命令清单这是回报最高的一块把怎么装、怎么跑、怎么测、怎么 build明确写死。它最容易在这翻车——用错包管理器、跑错测试命令。## 命令 - 包管理器只用 pnpm禁止 npm/yarn - 装依赖pnpm install - 起开发pnpm dev - 跑测试pnpm test改完代码必须跑 - 类型检查pnpm typecheck - 构建pnpm build3. 代码规范与风格写约束不写教程不是教它怎么写代码是告诉它你的项目跟别人不一样的地方。## 代码规范 - 组件用 script setup 语法不用 Options API - 状态管理一律走 Pinia store禁止在组件里直接调 axios - 网络请求统一用 src/utils/request.ts 的封装不要裸用 fetch/axios - 命名组件 PascalCase工具函数 camelCase常量 UPPER_SNAKE - 注释和 commit 用英文文档用中文4. 项目结构地图让它别乱放文件告诉它每类东西该放哪它就不会把一个 util 塞进 components。## 目录约定 - src/views/ 页面级组件 - src/components/ 可复用组件 - src/api/ 接口定义每个模块一个文件 - src/stores/ Pinia store - src/utils/ 纯工具函数无副作用5. 雷区与禁忌最能防事故的一块把绝对不能干的事列出来。这块每救你一次都是省下一场返工。## 雷区务必遵守 - 禁止修改 src/legacy/ 下任何文件老系统改了会崩 - 禁止改动数据库 migration 历史文件只能新增 - 改完任何代码必须跑 pnpm test红了自己修别留给我 - 不确定的设计决策先问我不要自作主张大改 - 一次只做我让你做的事不要顺手优化无关代码6. 上下文锚点让它知道去哪找答案告诉它哪些文件是真源它就会先去读再动手。## 关键文件 - 接口约定看 docs/api.md - 业务术语表看 docs/glossary.md - 环境变量说明看 .env.example四、可直接复制的模板把下面这份存成项目根目录的CLAUDE.md替换尖括号内容即可# 项目名 这是给 Claude Code 看的项目契约。务必遵守下面的约束。 ## 项目 一句话说清项目是什么 技术栈 ## 命令 - 包管理器pnpm / npm / poetry / ...禁止用其它 - 装依赖命令 - 开发命令 - 测试命令改完代码必须跑红了自己修 - 构建命令 ## 代码规范 - 风格约束 1例如函数式优先避免 class - 统一封装例如请求走 utils/request不裸用 fetch - 命名约定 - 注释/commit 用英文文档用中文 ## 目录约定 - dir/ 放什么 - dir/ 放什么 ## 雷区务必遵守 - 禁止修改 某目录/某文件 - 改完代码必须跑测试不要留红 - 一次只做被要求的事不要顺手改无关代码 - 不确定先问不要擅自大改 ## 关键文件 - 约定/术语/配置 的真源路径五、五个让效果翻倍的实战技巧踩坑总结1. 越短越好别写成手册。CLAUDE.md越长关键约束越容易被淹没。我的经验是控制在 100 行以内每条都是不写它就会犯的错。写满 500 行的文档它读了等于没读。2. 用禁止/务必这种硬词。“建议用 pnpm和禁止用 npm”效果天差地别。约束要写成命令式别写成商量。3. 让它自己维护。发现它又犯了同一个错直接说把这条规矩补进 CLAUDE.md。它会帮你加。CLAUDE.md是越用越准的活文档。4. 用#快捷记忆实测好用。对话里你随口说一句让它记住的规矩开头加#比如# 以后所有时间字段都用 UTCClaude Code 会问你要不要写进CLAUDE.md一键沉淀。5. 别把密钥/敏感信息写进去。CLAUDE.md会被完整读进上下文也常会进 git。API Key、密码这类东西放.env在CLAUDE.md里只写密钥看 .env.example。六、常见踩坑全解Q我写了 CLAUDE.md它好像没读确认文件名是CLAUDE.md全大写、在项目根目录。改完后重启claude会话或新会话才会重新加载。聊到一半改的当前会话不一定生效。Q内容太多它记不住精简。把不影响它干活的项目背景介绍删掉只留命令、规范、雷区。它的注意力是有限的别浪费在废话上。Q多人协作每个人偏好不一样项目级CLAUDE.md放团队共识命令、规范、雷区个人偏好放各自的~/.claude/CLAUDE.md。两层不冲突。Q子目录的 CLAUDE.md 和根目录冲突怎么办就近原则子目录的优先。monorepo 里给每个子包写一份小的根目录写公共的。七、小结与下一步CLAUDE.md是你能给 Claude Code 的回报最高的一次性投入——花 20 分钟写好之后每次对话都在帮你省事、防错。记住一句话写约束和雷区不写正确的废话控制在 100 行以内。下一篇专栏我会讲用 Claude Code 做大型重构而不翻车——上千行的老代码怎么让它分批改、怎么用 git 兜底、怎么验证它没改坏。那篇会用到这篇的CLAUDE.md建议先把这篇的模板用起来。建议收藏本篇下次新建项目直接照模板抄。本专栏会持续更新 Claude Code 的进阶实战从 MCP 扩展、成本控制到子 Agent 编排每篇都能直接用到你的项目里。有自己的CLAUDE.md写法心得欢迎评论区交流我会挑好的补进文章。
