大家好，我是程序員魚皮。

　　最近我發(fā)現(xiàn)一個現(xiàn)象，很多同學(xué)開始用 Claude Code、Cursor 這些 AI 編程工具了，但用了一陣子之后就開始抱怨：AI 怎么總是不聽話？讓它改個 Bug 反而引入三個新 Bug，讓它加個功能結(jié)果技術(shù)棧都給換了。

　　這些問題的根源，往往不是 AI 笨，而是你沒有給它足夠的上下文。

　　AI 每次開始新會話，都是一張白紙。它不知道你的項(xiàng)目用的是什么技術(shù)棧，不知道你們團(tuán)隊(duì)的代碼規(guī)范，不知道你之前做了什么決策。

　　你不說，它就猜。猜對了算你運(yùn)氣好，猜錯了你就得返工，把你的 tokens 全拿走，把回憶化成空~

　　那有沒有一種方法，讓 AI 每次開始工作前就自動了解你的項(xiàng)目？

　　必須有啊！就是今天要聊的CLAUDE.md。

　　??本文會收錄到我免費(fèi)開源的

　　一、CLAUDE.md 是什么？

　　CLAUDE.md 是 Claude Code 里的一個 Markdown 文件，放在項(xiàng)目根目錄下。

　　Claude Code 每次啟動會話時，都會自動讀取這個文件，把里面的內(nèi)容當(dāng)作項(xiàng)目的背景知識。

　　你可以把它理解為給 AI 寫的「入職手冊」。就像新員工入職第一天，你會給他一份文檔，介紹公司用什么技術(shù)、代碼怎么寫、測試怎么跑、有什么坑要注意。CLAUDE.md 干的就是這個事。

　　比如一個最簡單的 CLAUDE.md 長這樣：

　　# 我的博客系統(tǒng)

Next.js 16 + TypeScript + Tailwind CSS + Supabase
## 常用命令
-npm run dev # 啟動開發(fā)服務(wù)器
-npm run test # 跑測試
-npm run build # 生產(chǎn)構(gòu)建

## 代碼規(guī)范
-使用函數(shù)式組件，不用 class 組件
-樣式只用 Tailwind CSS，不寫自定義 CSS
-所有組件必須有 TypeScript 類型定義


　　AI 每次開始工作前都會先讀一遍，然后所有生成的代碼都會自動遵循這些規(guī)范，不用你每次都重復(fù)交代。

　　不過有一點(diǎn)需要注意，CLAUDE.md 對 AI 來說是建議而不是強(qiáng)制執(zhí)行的配置。它的效果取決于你寫得有多具體、多簡潔。越精確的指令 AI 遵循得越好，寫了一大堆模糊的要求反而可能被選擇性忽略。

　　二、更通用的 AGENTS.md

　　你可能會想，這是 Claude Code 的專屬功能嗎？我用 Cursor 怎么辦？

　　其實(shí)幾乎所有主流 AI 編程工具都有類似的機(jī)制。比如 Cursor 也支持.cursor/rules/和 AGENTS.md 來做同樣的事。

　　必須要知道的是 AGENTS.md，它是一個跨工具的開放標(biāo)準(zhǔn)，由 OpenAI、Google、Cursor 等多家公司聯(lián)合推出，目前已經(jīng)有好萬個開源項(xiàng)目在用，支持 30 多種 AI 編程工具。

　　Claude Code 雖然默認(rèn)只讀 CLAUDE.md，但你可以在 CLAUDE.md 里用一行@AGENTS.md把它導(dǎo)入進(jìn)來，兩邊就打通了。

　　這些 Markdown 文件本質(zhì)上都是一回事，就是給 AI 寫一份項(xiàng)目說明書。你學(xué)會寫好這份說明書，換任何 AI 編程工具都能用。

　　而且 AGENTS.md 的用途不只是項(xiàng)目開發(fā)指導(dǎo)，它同樣可以作為指導(dǎo) AI 做事的工作流文檔。比如我自己就用 AGENTS.md 來定義各種工作流，像圖文創(chuàng)作、產(chǎn)品客服、數(shù)據(jù)分析這些場景，都可以用一份 Markdown 文件把 AI 的工作方式固定下來，每次啟動自動加載，省得重復(fù)交代。

　　后面我會統(tǒng)一用 CLAUDE.md 來講解，但里面的技巧對所有工具都適用。

　　三、為什么一定要寫好這個文件？

　　你可能覺得，不就是個配置文件嗎，隨便寫寫不就行了？

　　大錯特錯！CLAUDE.md 的質(zhì)量直接決定了 AI 幫你干活的效率和準(zhǔn)確度。

　　以我自己天天用 AI 編程的體驗(yàn)來看，一個好的 CLAUDE.md 至少能解決 3 個問題：

　　第一，減少重復(fù)溝通。

　　沒有 CLAUDE.md 的時候，每次新會話我都得重復(fù)交代一遍技術(shù)棧、代碼規(guī)范、項(xiàng)目結(jié)構(gòu)。有了它，這些信息 AI 自動就知道了。

　　第二，提升代碼一致性。

　　之前 AI 有時候用 React 函數(shù)組件，有時候給我整個 class 組件出來；有時候用 CSS Modules，有時候給我寫內(nèi)聯(lián)樣式。規(guī)范寫進(jìn) CLAUDE.md 后，這種問題基本消失了。

　　第三，降低出錯率。

　　比如我的項(xiàng)目里有個特殊的 API 響應(yīng)格式{ success, data, error }，不寫進(jìn)規(guī)則的話，AI 每次都按自己的習(xí)慣來。寫進(jìn)去之后，Claude 就會自動遵循，不用我每次糾正。

　　之前我在另一篇文章里提到過，規(guī)則文件在 50 行左右時遵循率可以達(dá)到 94%，但如果一股腦堆到 400 行，遵循率就掉到了 71%。

　　所以 CLAUDE.md 不是越多越好，而是要精準(zhǔn)。

　　這就引出了最核心的問題，也是本文的重點(diǎn)，怎么寫好 CLAUDE.md 文檔？

　　四、怎么寫好 CLAUDE.md？

　　下面這些技巧，很多是經(jīng)過社區(qū)大量實(shí)踐和我個人驗(yàn)證的經(jīng)驗(yàn)，建議仔細(xì)閱讀，細(xì)細(xì)品味。

　　1、控制在 200 行以內(nèi)

　　這是 Claude Code 官方文檔給出的建議。

　　CLAUDE.md 的內(nèi)容會在每次會話開始時加載到 AI 的上下文窗口中。這個窗口是有限的，你的規(guī)則文件越長，留給實(shí)際工作內(nèi)容的空間就越少。

　　而且 AI 對指令的遵循能力跟指令數(shù)量負(fù)相關(guān)。社區(qū)有人引用過一項(xiàng)研究，AI 大概能合理遵循 150 到 200 條指令，超過這個數(shù)之后，遵循質(zhì)量會均勻下降，不僅僅是忽略新加的，而且全部都開始變差。

　　所以寫 CLAUDE.md 要像寫簡歷一樣，精煉再精煉。

　　對于每一行，問自己一個問題：刪掉它 AI 會犯錯嗎？

　　如果答案是不會，就果斷刪掉。

　　2、只寫 AI 猜不到的東西

　　官方文檔專門列了一個 CLAUDE.md 中應(yīng)該寫和不該寫的清單，非常值得參考。

　　應(yīng)該寫進(jìn)去的：

　　 AI 不可能猜到的構(gòu)建命令和測試命令

　　 跟默認(rèn)不同的代碼風(fēng)格規(guī)則

　　 團(tuán)隊(duì)的 Git 規(guī)范（分支命名、PR 格式）

　　 項(xiàng)目特有的架構(gòu)決策

　　 開發(fā)環(huán)境的特殊要求（必需的環(huán)境變量之類）

　　 容易踩坑的地方

　　不該寫進(jìn)去的：

　　 AI 讀代碼就能知道的東西

　　 通用的語言規(guī)范（AI 本來就會）

　　 詳細(xì)的 API 文檔（放別的地方，CLAUDE.md 里放鏈接就行）

　　 寫干凈的代碼、注意性能這種廢話

　　像我做編程導(dǎo)航項(xiàng)目時，就把一些即使讀代碼也容易忽略的約定寫進(jìn)了 CLAUDE.md，比如 API 響應(yīng)統(tǒng)一使用BaseResponse包裝類、異常統(tǒng)一用BusinessException拋出。雖然 AI 深入分析代碼也能發(fā)現(xiàn)這些模式，但寫進(jìn)規(guī)則之后能省掉它每次重新推斷的過程，效率高很多。

　　3、用正面指令代替否定指令

　　這個技巧其實(shí)有點(diǎn)兒反直覺。。

　　有篇論文研究發(fā)現(xiàn)，87.5% 的 AI 規(guī)則違反都來自同一個原因，就是否定句反而把被禁止的概念給激活了。你寫「不要使用分號」，AI 看到分號這兩個字，反而更容易在后續(xù)生成中產(chǎn)出分號。

　　這跟心理學(xué)里的白熊效應(yīng)一模一樣。叫你不要想白熊，你腦子里馬上就全是白熊。

　　所以正確的做法是用正面表述替代：

　　 ? 不要使用 class 組件 → ? 使用函數(shù)式組件和 Hooks

　　 ? 不要用 any 類型 → ? 所有變量必須有明確的 TypeScript 類型定義

　　 ? 不要在主分支直接提交 → ? 所有變更通過 feature 分支提交 PR

　　
4、指令要具體可驗(yàn)證

　　模糊的指令等于沒有指令。AI 很擅長處理具體的規(guī)則，但對抽象的要求就會自行發(fā)揮。

　　舉些例子：

　　 ? 正確格式化代碼 → ? 使用 2 空格縮進(jìn)

　　 ? 測試你的更改 → ? 提交前運(yùn)行 npm test

　　 ? 保持文件有序 → ? API handlers 放在 src/api/handlers/

　　越具體的指令，AI 越容易判斷自己有沒有遵循，違反了也更容易被發(fā)現(xiàn)。

　　5、用 Hooks 來強(qiáng)制執(zhí)行

　　CLAUDE.md 本質(zhì)上只是建議，不是 100% 生效的禁令。

　　像代碼格式化、提交前跑測試、危險命令攔截這些任務(wù)，應(yīng)該用確定性的自動化腳本來執(zhí)行。

　　Claude Code 提供了 Hooks 機(jī)制，可以在 AI 操作的關(guān)鍵節(jié)點(diǎn)自動執(zhí)行你預(yù)設(shè)的腳本。

　　比如你想讓每次文件編輯后自動跑 ESLint，寫一個 Hooks 配置就搞定了，AI 根本不介入，100% 會執(zhí)行。

　　一句話總結(jié)就是，CLAUDE.md 負(fù)責(zé)建議，Hooks 負(fù)責(zé)強(qiáng)制操作。

　　
6、大項(xiàng)目用路徑規(guī)則按需加載

　　如果你的項(xiàng)目比較大，200 行根本裝不下所有規(guī)范。這時候不要硬往 CLAUDE.md 里塞，而是用.claude/rules/目錄來拆分。

　　每個規(guī)則文件可以用 YAML frontmatter 指定只對特定路徑的文件生效：

　　---
paths:
-"src/api/**/*.ts"
---

# API 開發(fā)規(guī)范
-所有API端點(diǎn)必須包含輸入驗(yàn)證
-使用標(biāo)準(zhǔn)的錯誤響應(yīng)格式
-添加OpenAPI文檔注釋


　　這樣只有當(dāng) Claude 操作src/api/下面的 TypeScript 文件時，這些規(guī)則才會加載到上下文中，既省了上下文空間，又不會用不相關(guān)的規(guī)則干擾 AI。

　　7、用 @import 做漸進(jìn)式披露

　　社區(qū)里最受推崇的高級技巧叫漸進(jìn)式披露，核心思想就是不要把所有東西塞進(jìn) CLAUDE.md，而是告訴 AI 去哪里找它需要的信息。

　　做法很簡單。在項(xiàng)目中創(chuàng)建一個docs/目錄，放各類專題文檔，然后在 CLAUDE.md 中用簡短描述加觸發(fā)條件來引用：

　　## 參考文檔

### API 架構(gòu) — @docs/api-architecture.md
何時閱讀：添加或修改 API 端點(diǎn)時

### 數(shù)據(jù)庫設(shè)計(jì) — @docs/database-design.md
何時閱讀：創(chuàng)建或修改數(shù)據(jù)模型時


　　這樣 Claude 只在真正需要的時候才會去讀取對應(yīng)的文檔，平時不占用上下文空間。

　　CLAUDE.md 的@path導(dǎo)入語法支持相對路徑和絕對路徑，最多可以嵌套 4 層。

　　這個思路其實(shí)跟我之前講的上下文工程和 Agent Skills 是類似的。AI 編程工具的上下文窗口是有限的，你不能一股腦把所有信息都塞進(jìn)去。Anthropic 官方把這個策略叫 just-in-time，就是讓 AI 按需獲取信息，而不是全量加載。

　　8、讓 AI 幫你維護(hù)

　　CLAUDE.md 不是寫好了就不管了，它應(yīng)該是一份隨著項(xiàng)目成長不斷完善的 “活” 文檔。

　　Claude Code 的創(chuàng)始人推薦了一個習(xí)慣：每次 Claude 犯錯，不要只修正錯誤，還要順手讓它把糾正寫進(jìn) CLAUDE.md。

　　我自己也是這么做的，比如 Claude 用了錯誤的導(dǎo)入路徑，糾正完之后跟它說一句：把這條規(guī)則更新到 CLAUDE.md 里，下次別再犯。

　　Claude 特別擅長給自己寫規(guī)則，時間久了，你的 CLAUDE.md 就變成了一份完整的項(xiàng)目知識庫，出錯率會明顯下降。

　　另外 Claude Code 現(xiàn)在還有一個 Auto Memory 自動記憶功能，Claude 會自動記錄它在工作中發(fā)現(xiàn)的模式和偏好，存到~/.claude/projects/ <項(xiàng)目> /memory/ 目錄下。這些筆記每次會話都會自動加載，相當(dāng)于 AI 給自己做了一份備忘錄。

　　你隨時可以用/memory命令查看和編輯這些記憶。

　　
五、如何快速創(chuàng)建？

　　看到這里你可能會想，這些技巧我都記住了，但從零開始寫一份完整的 CLAUDE.md 還是有點(diǎn)頭疼。

　　別擔(dān)心，有幾個快速起步的方法。

　　用 /init 命令自動生成

　　在 Claude Code 中輸入/init，Claude 會自動分析你的代碼庫，生成一份包含構(gòu)建命令、測試指令和項(xiàng)目規(guī)范的 CLAUDE.md。如果文件已經(jīng)存在，它會建議改進(jìn)而不是覆蓋。

　　不過需要注意，自動生成的內(nèi)容可能不夠精確，畢竟 AI 只能看到你的代碼成果，不理解背后的過程。

　　社區(qū)有人說過，CLAUDE.md 影響你工作流的每個階段和產(chǎn)出的每個文件，一條不好的指令產(chǎn)生的破壞力遠(yuǎn)超一行壞代碼。所以自動生成之后，一定要自己過一遍，該刪的刪、該補(bǔ)的補(bǔ)。

　　讓 AI 從對話中沉淀

　　我自己經(jīng)常用的一種方法是，先不急著寫 CLAUDE.md，正常跟 AI 協(xié)作完成一兩個任務(wù)。做完之后，讓 AI 回顧整個對話過程，幫你總結(jié)出需要記住的項(xiàng)目規(guī)范和注意事項(xiàng)，直接寫成 CLAUDE.md。

　　這樣得到的規(guī)則文件是從實(shí)戰(zhàn)中提煉出來的，比憑空想象要精準(zhǔn)得多。

　　像我自己帶團(tuán)隊(duì)做項(xiàng)目時，每次 Code Review 中發(fā)現(xiàn) AI 犯的錯誤，都會讓 Claude 把修正追加到 CLAUDE.md 里。做了一個月之后，這份文件已經(jīng)沉淀了幾十條非常有針對性的規(guī)則，新同事用 Claude Code 的時候上手也快了很多。

　　
參考優(yōu)秀的開源項(xiàng)目

　　GitHub 上有個 awesome-claude-md 倉庫，收錄了 100 多個真實(shí)項(xiàng)目的 CLAUDE.md 示例，覆蓋各種技術(shù)棧和項(xiàng)目類型，包括 Anthropic 官方的、Cloudflare 的 monorepo 項(xiàng)目等等。

　　另外還有個 awesome-claude-code 倉庫，整理了 Skills、Hooks、斜杠命令等 Claude Code 生態(tài)工具，也值得收藏。

　　有時間的話，可以讓 AI 幫你分析一下這些案例，找個跟你項(xiàng)目技術(shù)棧接近的參考著寫，比從零開始快多了。

　　記住，CLAUDE.md 的內(nèi)容寧缺毋濫。

　　先從最關(guān)鍵的 20 行開始，在實(shí)際使用中再慢慢補(bǔ)充。

　　六、多層級配置和團(tuán)隊(duì)協(xié)作

　　如果你在團(tuán)隊(duì)中使用 Claude Code，或者同時做多個項(xiàng)目，有一些進(jìn)階玩法值得了解。

　　四層作用域

　　CLAUDE.md 不只能放在項(xiàng)目根目錄，它支持四個層級，按加載順序從先到后排列：

　　1）組織級，公司 IT 統(tǒng)一部署的規(guī)范，所有人強(qiáng)制生效

　　2）用戶級~/.claude/CLAUDE.md，對你本機(jī)的所有項(xiàng)目生效

　　3）項(xiàng)目級./CLAUDE.md，只對當(dāng)前項(xiàng)目生效，可提交到 Git

　　4）本地級./CLAUDE.local.md，只對當(dāng)前項(xiàng)目生效，不提交到 Git

　　加載越靠后的內(nèi)容，AI 越傾向于優(yōu)先遵循，所以優(yōu)先級是 本地級 > 項(xiàng)目級 > 用戶級。但組織級比較特殊，它雖然加載最早，卻不可被個人或項(xiàng)目設(shè)置排除，屬于公司強(qiáng)制執(zhí)行的底線規(guī)范。

　　建議團(tuán)隊(duì)共享的規(guī)范寫在項(xiàng)目級，個人偏好寫在本地級，兩邊互不干擾。

　　團(tuán)隊(duì)共建 CLAUDE.md

　　Claude Code 的創(chuàng)始人推薦把 CLAUDE.md 用 Git 來管理，讓團(tuán)隊(duì)成員共同維護(hù)。

　　每當(dāng)有人在 Code Review 中發(fā)現(xiàn) AI 犯了什么錯誤，就把修正追加到 CLAUDE.md 里。時間久了，這個文件就沉淀了團(tuán)隊(duì)的開發(fā)經(jīng)驗(yàn)和規(guī)范，變成了整個團(tuán)隊(duì)的 AI 使用手冊。

　　我們自己團(tuán)隊(duì)也是這么做的。像面試鴨后端項(xiàng)目的 AGENTS.md，里面沉淀了技術(shù)棧選型、Spring Boot 分層規(guī)范、統(tǒng)一響應(yīng)格式、異常處理方式、數(shù)據(jù)庫命名規(guī)則等約定。新同事入職直接看這份文件就能上手，Claude 也能自動遵循這些規(guī)范生成代碼，省了大量溝通成本。

　　
重要規(guī)則一定要存文件

　　當(dāng)你在對話中用/compact壓縮上下文時，項(xiàng)目根目錄的 CLAUDE.md 會被重新讀取和注入。但你在對話中口頭說的指令，比如后面的代碼都用 async/await，壓縮后就沒了。

　　所以，凡是重要的規(guī)則，一定要寫進(jìn) CLAUDE.md，不要只在對話里說。這一點(diǎn)跟我之前講的上下文工程也是相通的，持久化的信息要落到文件里，別光靠 AI 的短期記憶。

　　七、排查不生效的問題

　　如果你發(fā)現(xiàn) AI 好像沒在遵守 CLAUDE.md 里的規(guī)則，可以按這個順序排查：

　　1）運(yùn)行/memory命令，看看你的 CLAUDE.md 有沒有被正確加載

　　2）檢查指令是不是太模糊了。比如格式化好代碼這種 AI 沒法執(zhí)行，改成使用 2 空格縮進(jìn)、單行不超過 80 字符

　　3）檢查不同文件之間有沒有矛盾的指令。如果 CLAUDE.md 里說用 MyBatis Plus，某個 rules 文件里又說用 MyBatis Flex，AI 可能隨便選一個

　　4）如果某個操作必須在特定時機(jī)執(zhí)行，比如每次提交前跑 lint，就不要靠 CLAUDE.md 了，改用 Hooks

　　
最后嗶嗶

　　沒想到吧，就這么一個 Markdown 文件，其實(shí)是 AI 編程時代最重要的基礎(chǔ)設(shè)施之一。

　　以前我們寫 README.md 是給人看的，現(xiàn)在寫 CLAUDE.md 是給 AI 看的。但本質(zhì)都一樣，就是把項(xiàng)目的重要信息組織好、傳達(dá)清楚。區(qū)別在于，給 AI 寫的說明書要更精煉、更具體、更可執(zhí)行。

　　如果你還沒有為自己的項(xiàng)目寫一份 CLAUDE.md，馬上就可以試試。從最簡單的 20 行開始，把技術(shù)棧、構(gòu)建命令、和 AI 總是犯錯的幾個規(guī)則寫進(jìn)去，你會立刻感受到它的強(qiáng)大。

　　我是魚皮，持續(xù)分享 AI 編程干貨。