如果你和我一樣幾乎每天都在用 Claude Code 寫代碼、改 bug、做重構(gòu)那你一定經(jīng)歷過這種循環(huán)新開一個(gè)項(xiàng)目先花二十分鐘把項(xiàng)目背景、技術(shù)棧、代碼風(fēng)格、常用命令一條條喂給 Claude Code等它終于表現(xiàn)得像個(gè)熟悉項(xiàng)目的同事了項(xiàng)目差不多也要收尾了。換個(gè)新項(xiàng)目再來一遍。這套重復(fù)勞動(dòng)逼我做出一個(gè)習(xí)慣——把整個(gè)調(diào)教過程全部沉淀成一套 claude-code-templates。這個(gè)模板庫裝的不只是幾個(gè) Markdown 文件而是一整套讓 AI 編程助手快速進(jìn)入狀態(tài)的約定、流程和檢查清單。這篇文章會(huì)把我的完整思路、目錄設(shè)計(jì)、踩過的坑全部攤開給正在折騰 Claude Code 工作流的人一個(gè)可以直接抄作業(yè)的參考。1. 反復(fù)搭模板的真實(shí)動(dòng)機(jī)同一套調(diào)教動(dòng)作我做了不下二十遍1.1 每次新項(xiàng)目都要重新教育AI 助手太浪費(fèi)了大概從我開始把 Claude Code 當(dāng)作主力編碼工具開始就陷入了一個(gè)循環(huán)。每接到一個(gè)新項(xiàng)目我先建倉庫、搭目錄結(jié)構(gòu)然后打開終端把項(xiàng)目背景、技術(shù)棧選擇、目錄約定、編譯命令、測(cè)試命令一條條敲進(jìn)去。第一天基本都在做這種信息灌輸?shù)诙?AI 才開始產(chǎn)出稍微靠譜的代碼。后來我意識(shí)到這個(gè)教育成本其實(shí)是完全可以復(fù)用的。于是我開始寫第一個(gè) CLAUDE.md。起初只是簡單記了幾條項(xiàng)目約定后來發(fā)現(xiàn)每個(gè)項(xiàng)目都在重復(fù)寫相似的內(nèi)容我就琢磨著把這些內(nèi)容抽出來做成一套模板。這個(gè)模板不能只是幾個(gè)文件拼在一起而是要區(qū)分哪些是全局通用規(guī)則哪些是項(xiàng)目特有約束哪些是某個(gè)會(huì)話里才需要臨時(shí)說清楚的上下文。分開之后模板的復(fù)用性才真正起來。1.2 模板庫里該裝什么不該裝什么先說清楚一個(gè)邊界claude-code-templates 不是代碼片段收集站更不是提示詞大全。它在我這里只負(fù)責(zé)三件事行為約定、流程腳本、項(xiàng)目骨架。行為約定指的是 Claude Code 在項(xiàng)目里應(yīng)該遵守的規(guī)則比如編碼風(fēng)格、命名習(xí)慣、禁忌操作。流程腳本指的是那些需要按順序執(zhí)行的多步操作比如初始化項(xiàng)目、跑測(cè)試、做 code review。項(xiàng)目骨架是空項(xiàng)目結(jié)構(gòu)方便新項(xiàng)目第一時(shí)間建起來。不該裝的東西我也踩過。以前我試過把一些通用領(lǐng)域知識(shí)寫進(jìn)模板比如 Git 操作規(guī)范、數(shù)據(jù)庫設(shè)計(jì)原則寫了滿滿一堆最后發(fā)現(xiàn) Claude Code 本身掌握這些常識(shí)重復(fù)寫進(jìn)去只會(huì)占用上下文窗口讓真正重要的項(xiàng)目信息反而被稀釋。模板庫的定位應(yīng)該是補(bǔ)充增量不是重復(fù)造輪子。2. 模板庫的地基CLAUDE.md 三層結(jié)構(gòu)怎么設(shè)計(jì)2.1 全局層放通用習(xí)慣項(xiàng)目層放架構(gòu)約束會(huì)話層放臨時(shí)上下文我最終把 CLAUDE.md 的分層定為三層全局層、項(xiàng)目層、會(huì)話層對(duì)應(yīng)三個(gè)不同范圍的上下文文件。全局層放在~/.claude/CLAUDE.md里面裝的是我個(gè)人在所有項(xiàng)目里不變的偏好。比如代碼注釋用中文還是英文、函數(shù)命名傾向、commit message 的格式、禁止在沒有測(cè)試的情況下直接改核心模塊代碼。這一層的內(nèi)容非?？酥浦粚憰?huì)長期生效的規(guī)則不會(huì)隨項(xiàng)目變化。項(xiàng)目層放在每個(gè)倉庫根目錄的CLAUDE.md內(nèi)容圍繞這個(gè)項(xiàng)目本身的架構(gòu)和技術(shù)棧展開。包括項(xiàng)目簡介、目錄結(jié)構(gòu)、啟動(dòng)和構(gòu)建命令、依賴管理方式、模塊邊界、已知的技術(shù)債。這一層是 Claude Code 每次會(huì)話默認(rèn)加載的核心上下文寫得好不好直接決定 AI 產(chǎn)出的質(zhì)量。會(huì)話層是更細(xì)粒度的上下文。Claude Code 支持在子目錄里放局部 CLAUDE.md 文件或者我在會(huì)話里通過/add-dir臨時(shí)指定某份說明文檔。這一層適合放模塊級(jí)說明、接口文檔摘要、某次迭代的任務(wù)清單。三層的作用我用一個(gè)表格概括層級(jí)文件位置典型內(nèi)容更新頻率全局層~/.claude/CLAUDE.md個(gè)人編碼偏好、標(biāo)簽規(guī)范、安全檢查策略幾個(gè)月一次項(xiàng)目層倉庫根目錄 CLAUDE.md技術(shù)棧、架構(gòu)約束、構(gòu)建命令、目錄約定項(xiàng)目關(guān)鍵節(jié)點(diǎn)會(huì)話層子目錄 CLAUDE.md 或臨時(shí)引用當(dāng)前任務(wù)背景、模塊細(xì)節(jié)、迭代目標(biāo)每次會(huì)話都可能變2.2 優(yōu)先級(jí)與覆蓋規(guī)則越近的規(guī)則越優(yōu)先三層文件同時(shí)存在時(shí)Claude Code 會(huì)合并加載這些上下文但規(guī)則之間可能沖突。我在踩過幾個(gè)坑之后給自己定了一條規(guī)定就近優(yōu)先全局兜底。項(xiàng)目層里如果明確寫了這個(gè)項(xiàng)目必須使用面向?qū)ο髮懛侨謱永飳懙暮瘮?shù)式優(yōu)先就自動(dòng)讓位。會(huì)話層如果有臨時(shí)說明這次重構(gòu)暫不改動(dòng)接口簽名它又比項(xiàng)目層的長期約定更優(yōu)先。為了減少?zèng)_突全局層里我不再用強(qiáng)約束語言而是改成如果沒有項(xiàng)目級(jí)規(guī)則默認(rèn)這樣做。這樣既保留了通用習(xí)慣又給項(xiàng)目層留足定制空間。2.3 我給 CLAUDE.md 定的語法規(guī)范實(shí)際寫 CLAUDE.md 的時(shí)候最忌諱的是大段散文。AI 讀得懂自然語言但指令越松散執(zhí)行越飄。我把自己的模板文件定了幾條硬性規(guī)范每條規(guī)則都寫成如果...那么...的形式可執(zhí)行、可檢查每個(gè)章節(jié)用二級(jí)標(biāo)題分開禁止在一個(gè)標(biāo)題下堆五六個(gè)無關(guān)主題能用清單表達(dá)的就不用段落清單項(xiàng)不超過一行明確標(biāo)注禁止項(xiàng)因?yàn)?AI 對(duì)否定指令的執(zhí)行效果往往比肯定指令更可靠所有命令要寫清楚在哪一層目錄執(zhí)行避免路徑歧義舉一個(gè)我全局文件里的例子以前我寫的是代碼風(fēng)格要保持整潔后來改成這樣當(dāng)修改 Python 文件時(shí)如果函數(shù)超過 30 行請(qǐng)主動(dòng)提出拆分方案新增模塊必須包含模塊級(jí) docstring說明該模塊的職責(zé)和邊界。這種寫法執(zhí)行起來明顯更穩(wěn)定。3. 模板庫里真正值得沉淀的四類模板3.1 項(xiàng)目初始化模板從空目錄到可運(yùn)行狀態(tài)的第一步項(xiàng)目初始化是使用頻率最高的模板。我把它做成了一個(gè)自定義 slash command放在.claude/commands/init-project.md里每次新項(xiàng)目直接輸入/init-projectClaude Code 就會(huì)按照模板走一遍流程。模板的內(nèi)容分成幾個(gè)階段第一階段是盤點(diǎn)現(xiàn)狀。AI 先掃描當(dāng)前目錄識(shí)別是不是空倉庫、是否已經(jīng)有部分代碼、有沒有現(xiàn)成的 README 或構(gòu)建文件。第二階段是補(bǔ)齊信息。如果項(xiàng)目背景不明確它會(huì)列出需要我確認(rèn)的幾個(gè)問題比如目標(biāo)技術(shù)棧、包管理器、運(yùn)行環(huán)境版本。第三階段是根據(jù)我的回答生成項(xiàng)目級(jí) CLAUDE.md 和基礎(chǔ)目錄結(jié)構(gòu)并給出第一個(gè)可運(yùn)行命令。這個(gè)模板之所以值得沉淀是因?yàn)樗褟臒o到有的過程標(biāo)準(zhǔn)化了避免每次新項(xiàng)目都靠手動(dòng)敲命令一點(diǎn)一點(diǎn)喂上下文。3.2 代碼審查模板讓 AI 當(dāng)挑剔的同事而不是夸夸機(jī)器很多人讓 Claude Code 做 code review得到的就是代碼看起來不錯(cuò)建議補(bǔ)充測(cè)試這種毫無營養(yǎng)的回復(fù)。問題不在工具而在模板。我在 review 模板里做了三個(gè)強(qiáng)制要求。第一只審查 diff不 review 全文。第二按危險(xiǎn)等級(jí)分類輸出阻塞問題、應(yīng)該改的問題、可選建議。第三每條建議必須給出為什么和怎么改不允許只說現(xiàn)象。review 命令的頭部我會(huì)寫成這樣你現(xiàn)在是一個(gè)有十年經(jīng)驗(yàn)的資深 reviewer。只關(guān)注本次提交的代碼變更忽略不相關(guān)的歷史代碼。輸出格式按阻塞問題/應(yīng)修改/可選建議三類列出。每條問題必須包含影響范圍、復(fù)現(xiàn)條件、修改建議。如果本次提交沒有阻塞問題明確說明不要為了湊數(shù)而挑刺。加上這個(gè)約束之后review 質(zhì)量一下子上來了。有一次它真的在 diff 中發(fā)現(xiàn)了一個(gè)循環(huán)邊界問題原因是模板里要求優(yōu)先檢查數(shù)組索引和循環(huán)條件這個(gè)具體約束比泛泛的請(qǐng)仔細(xì)檢查代碼高效得多。3.3 測(cè)試用例生成模板先立測(cè)試邊界再談覆蓋率我在測(cè)試模板里沉淀的不是生成測(cè)試代碼而是生成測(cè)試計(jì)劃。流程是先讓 AI 根據(jù)需求列出需要覆蓋的功能點(diǎn)每個(gè)功能點(diǎn)拆成正常路徑、邊界路徑、異常路徑三類用例等計(jì)劃確認(rèn)之后再生成代碼。這個(gè)流程寫清楚后生成的測(cè)試用例明顯更有針對(duì)性而不是隨手補(bǔ)一堆斷言。模板里有這么一條是花了很大代價(jià)才總結(jié)出來的在編寫測(cè)試之前先列出被測(cè)函數(shù)的輸入約束和可能的狀態(tài)變更。如果被測(cè)函數(shù)依賴外部服務(wù)明確標(biāo)記 mock 策略。禁止生成只斷言函數(shù)被調(diào)用過的假測(cè)試。這條規(guī)則救過我很多次。以前生成的測(cè)試看著覆蓋率挺高實(shí)際上全是空轉(zhuǎn)斷言的都是無關(guān)緊要的東西。3.4 故障排查模板把猜測(cè)變成結(jié)構(gòu)化假設(shè)驗(yàn)證Debug 是最容易讓人血壓升高的工作。Claude Code 一旦被放任自由發(fā)揮很容易順著錯(cuò)誤線索一路狂奔。我后來給它設(shè)計(jì)了排查模板核心是三步走復(fù)現(xiàn)、定位、驗(yàn)證。復(fù)現(xiàn)階段只允許做信息收集不允許改代碼。要求 AI 先還原報(bào)錯(cuò)現(xiàn)場(chǎng)包括完整錯(cuò)誤堆棧、輸入數(shù)據(jù)、操作步驟。定位階段要求列出至少兩個(gè)候選假設(shè)每個(gè)假設(shè)都要有證據(jù)支撐不能憑直覺。驗(yàn)證階段先做最小改動(dòng)再跑關(guān)聯(lián)測(cè)試。這個(gè)模板讓排查過程變得極其有秩序。我印象最深的一次AI 本來懷疑是數(shù)據(jù)庫連接池耗盡按模板要求先查連接數(shù)曲線結(jié)果發(fā)現(xiàn)是某個(gè) SQL 沒走索引。模板里的證據(jù)先行原則直接省掉了一次無效的代碼改動(dòng)。4. 模板可復(fù)用的關(guān)鍵把意圖寫成約束而不是寫成描述4.1 約束表達(dá)的三要素邊界、優(yōu)先級(jí)、驗(yàn)收標(biāo)準(zhǔn)模板里寫規(guī)則最怕的寫法是請(qǐng)生成高質(zhì)量代碼。這句話沒有任何可執(zhí)行性。我后來把每條規(guī)則都拆成三要素邊界、優(yōu)先級(jí)、驗(yàn)收標(biāo)準(zhǔn)。邊界是什么情況下適用這條規(guī)則什么情況下不適用優(yōu)先級(jí)是這條規(guī)則和其他規(guī)則沖突時(shí)誰說了算驗(yàn)收標(biāo)準(zhǔn)是做完之后怎么判斷做對(duì)了。舉個(gè)例子我在模板里寫代碼規(guī)范時(shí)會(huì)這樣寫在修改已有模塊時(shí)如果新代碼與舊代碼風(fēng)格不一致優(yōu)先沿用舊風(fēng)格保持一致性除非舊風(fēng)格存在可復(fù)現(xiàn)的 bug。驗(yàn)收標(biāo)準(zhǔn)是 diff 中新增代碼與上下文的縮進(jìn)、命名風(fēng)格保持一致。有了驗(yàn)收標(biāo)準(zhǔn)之后AI 輸出就有了自檢依據(jù)不需要我每次一遍遍糾正。4.2 變量化設(shè)計(jì)一套模板怎么服務(wù)多類項(xiàng)目模板要復(fù)用就得處理不同項(xiàng)目之間的差異。我的做法是把差異點(diǎn)集中到模板頭部作為變量區(qū)而不是散落在文件各處。比如初始化模板的變量區(qū)會(huì)要求一次性確認(rèn)技術(shù)棧、包管理器、目錄風(fēng)格、測(cè)試框架。后續(xù)所有步驟都從這些變量里取值不再中途提問。這套設(shè)計(jì)讓我管理了多個(gè)項(xiàng)目之后仍然保持模板穩(wěn)定。變量區(qū)相當(dāng)于接口具體實(shí)現(xiàn)可以各不相同但入口是統(tǒng)一的。如果你手頭有 Node 項(xiàng)目、Python 項(xiàng)目、Go 項(xiàng)目一個(gè)初始化模板配合變量區(qū)就夠用不需要給每種技術(shù)棧各建一個(gè)模板。5. 模板庫的版本管理、多設(shè)備同步與演進(jìn)5.1 用 git 管理模板庫像管代碼一樣嚴(yán)格模板庫本身就是一個(gè)倉庫我建議你像我一樣用 git 管起來。目錄結(jié)構(gòu)大致是這樣claude-code-templates/ ├── commands/ # 自定義 slash command │ ├── init-project.md │ ├── review.md │ ├── test-plan.md │ └── debug-trace.md ├── global/ # 全局層 CLAUDE.md 的源文件 │ └── CLAUDE.md ├── project/ # 項(xiàng)目層模板骨架 │ ├── CLAUDE.md.tpl │ └── README.md.tpl ├── scripts/ # 安裝與同步腳本 │ ├── install.sh │ └── sync.sh └── docs/ # 模板庫自身的說明文檔每次更新模板我不直接改文件而是在倉庫里先改通過腳本同步到全局位置和各個(gè)項(xiàng)目。提交信息會(huì)寫清楚改了什么規(guī)則、為什么改、影響了哪些項(xiàng)目。這套流程后面幫了大忙——我可以回溯某條規(guī)則是什么時(shí)候引入的避免規(guī)則越積越多卻說不清來源。5.2 自定義 slash command 的封裝技巧自定義命令是模板庫最靈活的載體。在.claude/commands/目錄下放一個(gè) Markdown 文件文件名就是命令名。文件內(nèi)容就是指令本身可以引用外層模板文件。這就相當(dāng)于把一組多步操作封裝成一個(gè)入口執(zhí)行時(shí)候只需要/review敲一下。我很推薦在命令里用幾步小設(shè)計(jì)開頭明確角色的工作前提避免自由發(fā)揮中間按步驟拆解任務(wù)每一步有輸入輸出結(jié)尾強(qiáng)制輸出一個(gè)結(jié)果確認(rèn)清單讓用戶快速判斷是否完成比如 review 命令的完整流程是先讀取 diff再核對(duì)項(xiàng)目級(jí)規(guī)則里的禁用項(xiàng)然后分三級(jí)輸出意見最后給出一個(gè)修改優(yōu)先級(jí)排序的總結(jié)。這套流程封裝好之后我只需要敲一句命令它自己會(huì)走完整個(gè)流程。5.3 模板的更新節(jié)奏每次項(xiàng)目收尾做一次復(fù)盤模板庫必須持續(xù)演進(jìn)否則會(huì)僵化。我的節(jié)奏是每個(gè)項(xiàng)目結(jié)束后回顧這次項(xiàng)目中 Claude Code 表現(xiàn)最好和最差的地方。最好的地方固化成新規(guī)則最差的地方查明原因要么調(diào)整指令要么刪掉導(dǎo)致誤判的舊規(guī)則。復(fù)盤的時(shí)候我會(huì)重點(diǎn)審視新出現(xiàn)的重復(fù)勞動(dòng)。如果這次項(xiàng)目里我又手動(dòng)糾正了 AI 的同一個(gè)錯(cuò)誤三次那就說明模板里缺一條規(guī)則。如果某個(gè)模板在整個(gè)項(xiàng)目里一次都沒觸發(fā)過那我會(huì)考慮刪掉它或者重新設(shè)計(jì)。模板庫的增量更新就像代碼重構(gòu)——保持精簡才有價(jià)值。6. 實(shí)測(cè)踩坑模板不是越厚越好寫多了反而翻車6.1 上下文過長會(huì)稀釋關(guān)鍵指令我一度把全局層寫得很長涵蓋編碼習(xí)慣、工具鏈偏好、評(píng)論風(fēng)格、命名規(guī)范、提交格式。結(jié)果發(fā)現(xiàn) Claude Code 在具體項(xiàng)目里的判斷反而變?nèi)趿?。后來想明白上下文窗口是有限的模板文件擠占了太多空間真正處理項(xiàng)目代碼的有效上下文就變少了響應(yīng)速度也變慢。這個(gè)問題的解法是瘦身。全局層只留那些真正跨項(xiàng)目生效且高價(jià)值的規(guī)則項(xiàng)目相關(guān)的東西一律下沉到項(xiàng)目層。瘦身之后Claude Code 的響應(yīng)質(zhì)量明顯回升。這也讓我意識(shí)到模板庫不是文檔庫每一行規(guī)則都有上下文成本。6.2 指令沖突會(huì)讓 AI 陷入選擇困難模板多了之后另一個(gè)常見問題是不同模板間的指令沖突。比如全局模板規(guī)定新代碼使用函數(shù)式風(fēng)格項(xiàng)目模板規(guī)定延續(xù)現(xiàn)有類的寫法AI 就會(huì)來回?fù)u擺甚至在一個(gè)文件里混用兩種風(fēng)格。這個(gè)問題光靠就近優(yōu)先還不夠還需要在寫規(guī)則時(shí)就盡量避免寫入相同維度的對(duì)立指令。我更推薦的做法是把規(guī)則拆到不同維度。全局層管安全底線和紅線項(xiàng)目層管架構(gòu)走向和代碼風(fēng)格會(huì)話層管當(dāng)前任務(wù)細(xì)節(jié)。如果真出現(xiàn)沖突模板里必須寫明沖突時(shí)以哪個(gè)為準(zhǔn)否則 AI 只會(huì)隨機(jī)挑一個(gè)。6.3 模板維護(hù)中最值錢的一步回填結(jié)論最后分享一個(gè)很多人都會(huì)忽略的動(dòng)作每次排查完一個(gè)復(fù)雜問題或者做完一次大重構(gòu)我會(huì)把收獲和教訓(xùn)回填到模板庫里?；靥畹臅r(shí)候不是復(fù)制總結(jié)而是提煉成一條如果...那么...規(guī)則。這個(gè)動(dòng)作讓模板庫越來越貼合自己的使用習(xí)慣而不是停留在剛創(chuàng)建時(shí)的樣子。真正好用的 claude-code-templates 不是一次性寫出來的是每個(gè)項(xiàng)目一塊磚一塊磚壘出來的。