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