claude-code-templates 這個項目說白了就是一套給 Claude Code 用的“工作手冊”倉庫。先說一個場景我自己剛用 Claude Code 那段時間每次開新會話都得在 prompt 里反復交代同樣的背景——“先讀一下 README 再動手”“別碰 lock 文件”“測試用 pnpm 跑”“代碼風格不要亂改”。稍微復雜點的任務光前情提要就能打滿半個屏幕而且只要哪回少說一句對話質(zhì)量就立刻掉檔。后來我把這些重復指令整理成了一個模板庫讓 Claude Code 在每次開始任務前自動加載發(fā)現(xiàn)整個使用體驗完全不一樣了。這個項目就是我整理出來的那套模板集合包含按場景拆分的 CLAUDE.md、自定義斜杠命令、以及配套的使用文檔。它解決的核心問題是讓 AI 在項目里像一個真正“知道上下文”的老成員而不是每次都重新認識一遍這個倉庫。適合所有在用 Claude Code 做日常開發(fā)的人也適合想在團隊里統(tǒng)一 AI 工作流的同學參考。1. claude-code-templates 到底在解決什么問題1.1 模板化不是因為懶而是因為對話是“一次性”的Claude Code 的工作方式跟普通聊天窗口不太一樣你給它一個任務它基于當前會話的上下文去理解、規(guī)劃、執(zhí)行。但每次新開會話它對這個項目的認知基本等于零。它不知道你的項目是干嘛的、代碼風格是什么、測試怎么跑、哪些文件絕對不能改。這些信息你每次都得重新喂一遍這就是“一次性對話”的弊端。一個很直觀的類比是開會。如果你請來一個顧問每次開會都從“我們這個公司是做什么的”講起那這個會的前十分鐘就廢了。如果你提前給他一份公司簡介、一份會議議程、一份決策邊界說明他進來就能直接聊正事。claude-code-templates 里的模板就是這份資料包它把你希望 AI 默認知道的項目背景、行為規(guī)范、工作流約定全部固化成文件讓 AI 在對話開始時就自動“讀過”一遍。我最初是被這個痛點逼著才去搞模板的。當時有個小項目我連續(xù)三四個會話都在跟 Claude Code 重復同一批指令最后實在煩了把常見的七八條約束寫進 CLAUDE.md結(jié)果下一輪對話它就主動說“根據(jù)項目約定我先跑一遍現(xiàn)有測試再定位問題”。那一刻我是服氣的——它不是變聰明了而是終于有了一份靠譜的入職手冊。1.2 模板的邊界不是越詳細越好很多人在了解模板機制后容易走向另一個極端把模板寫成一本幾百行的“百科全書”。這反而是我見過最多人踩的坑。模板的核心價值是“固定高質(zhì)量默認行為”不是替代需求文檔。它應該寫清楚的是AI 在這個項目里扮演什么角色、在開始任務前必須做什么、代碼和流程上有哪些約定、哪些操作絕對不能碰。至于某個具體功能怎么做、某個模塊怎么優(yōu)化這是你每次在 prompt 里該給的信息不該塞進模板。否則模板會變得又長又雜AI 在長上下文里反而會丟失關(guān)鍵約束。我自己對模板的取舍有個標準如果這條規(guī)則適用于這個項目的絕大多數(shù)任務它就值得進模板如果它只適用于某個特定場景那就應該放進按需加載的場景模板或斜杠命令里而不是堆在全局模板里。這也是 claude-code-templates 這個項目把模板按任務類型拆成多個文件的原因——不是為了好看是為了讓 AI 在什么場景只讀什么該讀的內(nèi)容上下文更干凈指令更不容易被稀釋。2. 模板里的核心技術(shù)點CLAUDE.md 的加載機制與字段設(shè)計2.1 CLAUDE.md 的加載機制與分層記憶要玩轉(zhuǎn)模板庫必須先理解 CLAUDE.md 是“怎么被 AI 讀到的”。Claude Code 有一套內(nèi)置的記憶加載約定項目根目錄的 CLAUDE.md 會在會話開始時被自動加載作為項目級長期記憶用戶主目錄下的全局配置也可以放一份那是跨項目的用戶級偏好。除此之外項目里還可以用.claude/commands/目錄放自定義斜杠命令需要的時候輸入/命令名才會臨時加載對應的模板內(nèi)容。理解這一層很重要因為很多人的模板“不生效”根本不是內(nèi)容寫得不好而是文件放錯了位置或者沒理解加載時機。我見過有人把項目專用規(guī)則寫進了全局模板結(jié)果打開任何項目 AI 都在執(zhí)行那套規(guī)則沖突不斷也有人以為改完 CLAUDE.md 當前會話馬上生效實際必須重開會話才會重新加載。在我的項目里模板是分層設(shè)計的最底層是全局模板只寫放之四海皆準的原則比如“不要在沒有確認的情況下執(zhí)行批量刪除”“遇到模糊需求先提問”往上一層是項目級 CLAUDE.md寫這個倉庫的具體玩法比如技術(shù)棧、啟動命令、文件組織約定再往上是按場景拆分的命令模板比如代碼評審、寫單測、提交信息這些只在特定時候才需要被加載的內(nèi)容。三層各管各的互不污染。2.2 六個關(guān)鍵字段構(gòu)成一份靠譜的模板骨架我拆過很多模板包括自己反復迭代的版本最后發(fā)現(xiàn)一份能穩(wěn)定起作用的模板其實就六個關(guān)鍵模塊。不用每次全寫但至少要有三到四個否則這個模板很難“立住”。第一是身份與目標。告訴 AI 它在這個項目里應該以什么視角工作。比如“你是一名重視可維護性的后端工程師”和“你是一個快速出原型的腳本選手”這兩種身份下的行為偏好完全不同。第二是環(huán)境與背景。項目用什么語言、什么包管理器、測試跑什么命令、構(gòu)建流程是什么。這部分是最能減少無效追問的因為 AI 不用再猜也不用靠讀文件去推斷。第三是啟動流程。約定任務開始前的固定動作。比如“接到任務后先看 README 和 docs/ 目錄”“先列出你對任務的理解再動手”。這招對防止 AI 拿著半懂不懂的需求直接開碼非常管用。第四是工作約定。包括代碼風格、提交信息格式、命名習慣、單測要求等。這里我特別建議寫得像“checklist”而不是散文AI 對這種格式化要求的執(zhí)行明顯更穩(wěn)定。第五是邊界與禁忌。比如“不要修改 lock 文件”“不要做全文件格式化”“批量替換前必須逐一確認”。這是我自己最看重的一塊因為 AI 闖禍通常不是因為它不會做事而是它太會做事——你讓它優(yōu)化三行代碼它順手給你格式化了整個目錄。第六是輸出偏好。方案對比用表格、代碼塊必須標注語言、解釋問題要給出前提假設(shè)。這能讓對話效率上一個臺階。我挑一段自己模板庫里的骨架給你看你現(xiàn)在寫 CLAUDE.md 完全可以照這個結(jié)構(gòu)起步# 身份與目標 你是這個倉庫的核心維護者優(yōu)先保證現(xiàn)有功能不被破壞再考慮代碼組織優(yōu)化。 # 環(huán)境與背景 - 技術(shù)棧Node.js TypeScript - 包管理器pnpm - 測試命令pnpm test - 代碼規(guī)范ESLint Prettier不要自動格式化整個文件 # 啟動流程 1. 接到任務后先簡述你對需求和改動范圍的理解。 2. 改動前先確認當前分支必要時建議新建分支。 3. 完成后跑一次 pnpm test再提交改動說明。 # 邊界與禁忌 - 不修改 package-lock.json / pnpm-lock.yaml。 - 不做大范圍格式化或全局替換。 - 遇到不確定的接口調(diào)用先查調(diào)用方的實際用法。2.3 場景化命令把長模板拆成隨用隨取的“技能包”如果說 CLAUDE.md 是默認加載的“常駐記憶”那斜杠命令就是按需取用的“技能包”。這是 claude-code-templates 里做得比較順手的一部分。例如我倉庫里有個/code-review命令它對應的模板文件里只寫了“按以下維度評審本次改動邏輯正確性、邊界遺漏、可測試性、命名與可讀性、性能隱患。輸出格式按嚴重程度排序并給出修改建議”。平時這個模板完全不會加載但你一旦輸入/code-reviewAI 就立刻進入代碼評審專家模式。這個設(shè)計思路非常像工具包常駐記憶只放最常用的幾把“基礎(chǔ)工具”各種專業(yè)用途的“專用工具”都收納在柜子里用的時候再拿。好處是會話上下文不會被大量無關(guān)指令占滿AI 對關(guān)鍵規(guī)則的注意力明顯更強。我自己實測過一個場景同一批代碼用不加載任何命令的普通會話去讓它評審和加載/code-review模板后去評審后者給出的結(jié)果深了不止一個級別因為它有明確的評審維度不會天馬行空亂說。3. 從零搭建自己的模板庫路徑、結(jié)構(gòu)與迭代流程3.1 先做一周“高重復輸入”記錄別急著寫如果你也想搭一套自己的 claude-code-templates我先勸你一句不要憑借大腦里的模糊印象上來就寫。我第一版模板就是憑印象寫的結(jié)果里面一半規(guī)則是我自己想當然的另一半是重復兩三次才發(fā)現(xiàn)的真問題寫完后 AI 的行為并沒有顯著改善。后來我換了個笨辦法連續(xù)一周每次跟 Claude Code 交互時把那些“你又輸了第二遍”的內(nèi)容記錄下來。不一定是長篇大論可能就是“先跑測試”“別改配置”“用中文回復提交信息”“保持小步提交”這類的短句。一周下來你會發(fā)現(xiàn)真正高頻率出現(xiàn)的其實就是那么十來條而它們大多數(shù)可以歸納成“啟動動作”“輸出偏好”“邊界禁忌”三類。這一步的核心價值是讓你的模板從“感覺可能需要”變成“實際被反復需要”。模板不是寫給 AI 看的規(guī)則清單而是你過去工作習慣的真實投影。只寫你真正依賴的規(guī)則AI 才能真正幫到你寫一堆你都不會遵守的規(guī)范AI 執(zhí)行了反而添亂。3.2 從最小可用模板開始別一口氣上全量我強烈建議第一版模板定一個小目標能覆蓋你日常 80% 對話的背景交代就夠。不要試圖把代碼規(guī)范、評審標準、CI 流程、文檔要求全部塞進去那只會讓第一版既難維護又難調(diào)。我自己的第一版 CLAUDE.md 其實非常樸素只有五條先讀 README 再回答任務開始前列出理解保持現(xiàn)有代碼風格不碰 lock 文件提交信息用約定式格式。就這么五條已經(jīng)讓新會話的“寒暄成本”大幅下降。后面每遇到一個新的重復痛點再往模板里加一條持續(xù)迭代滾動。這樣的好處是你知道是哪一條規(guī)則讓 AI 行為變好了哪一條其實是無效甚至有害的。如果一上來就寫二三十條AI 出問題你根本不知道是哪條在搗亂。3.3 文件放哪、優(yōu)先級是什么這部分別搞錯模板文件的放置位置直接決定了它的生效范圍。我的做法是這樣項目級 CLAUDE.md 放在倉庫根目錄跟著項目走只描述這個項目相關(guān)的東西。用戶級全局配置放在個人主目錄的.claude/下寫放之四海皆準的工作習慣。斜杠命令則放在項目級.claude/commands/或用戶級~/.claude/commands/里項目級會覆蓋用戶級同名命令。這個分層如果沒理清很容易出現(xiàn)“AI 在 A 項目里執(zhí)行了你在 B 項目里設(shè)定的規(guī)則”這種低級事故。我自己就翻過車某次在全局模板里寫了“所有交互使用 XX 約定”結(jié)果另一個項目的 AI 也被強制套用造成了不小的混亂?，F(xiàn)在我的原則是——全局模板只寫心態(tài)層面的原則比如“不盲猜需求”“動手前先確認”一切與具體技術(shù)棧、目錄結(jié)構(gòu)、工具鏈相關(guān)的內(nèi)容全部下沉到項目級或按需命令里。給一個目錄結(jié)構(gòu)參考這也是 claude-code-templates 倉庫本身的組織方式claude-code-templates/ ├── templates/ │ ├── CLAUDE.md # 項目級常駐模板 │ ├── code-review.md # 代碼評審場景模板 │ ├── bug-fixing.md # 修 bug 場景模板 │ └── refactoring.md # 重構(gòu)場景模板 ├── commands/ │ ├── code-review.md # 對應 /code-review 命令 │ ├── write-tests.md # 對應 /write-tests 命令 │ └── commit.md # 對應 /commit 命令 ├── docs/ │ ├── design.md # 模板設(shè)計思路 │ └── usage.md # 使用說明 └── README.md # 項目入口這里的關(guān)鍵是把“模板內(nèi)容”和“命令綁定”分開。templates/里的文件是給人讀的素材commands/里的文件才會被 AI 真正按需加載。這樣你不需要改命令體系就能調(diào)整某個場景的模板內(nèi)容維護起來清爽得多。3.4 模板庫本身也要用 Git 管理并且值得開源共享最后給一個很容易被忽視的建議模板庫本身也要納入版本管理。我一開始就是本地建了個文件夾直接改后來發(fā)現(xiàn)改壞了沒法回退也不知道是哪次改動讓 AI 表現(xiàn)變差。把模板倉庫納入 Git 后每次改模板就像改代碼一樣有跡可循出問題可以直接git diff看改動效率一下就上來了。更近一步這類模板其實非常適合開源。因為好的模板經(jīng)驗是高度可復用的——每個團隊在“啟動動作”“邊界禁忌”上的寫法大同小異真正有差異的只是技術(shù)棧和業(yè)務約束。把模板開源出來一方面有人幫你 review 問題、提優(yōu)化意見另一方面你也在給整個 Claude Code 生態(tài)沉淀方法。claude-code-templates 這個項目就是這樣從個人實踐慢慢長成了一套可復用方案的。4. 實測中的常見坑與排查思路4.1 改完模板沒反應多半是會話沒有重新加載這是我被問過最多的問題“我改了 CLAUDE.mdAI 沒有變化啊。”原因很簡單Claude Code 對 CLAUDE.md 的讀取主要發(fā)生在會話啟動階段你在一段已經(jīng)開始的對話里改文件它大概率不會動態(tài)感知。要像改完代碼重啟服務那樣重開一個新會話新模板才會生效。另外還要確認你沒有把小寫打錯。文件名必須嚴格是CLAUDE.md才能被識別claude.md或者claude.MD都不行。這種看一眼很蠢的坑我身邊真有人踩過而且排查了半小時才發(fā)現(xiàn)是大小寫問題。4.2 模板越長AI 反而越“笨”這是我另一個深刻的教訓。有段時間我把各種“經(jīng)驗”都往 CLAUDE.md 里塞什么“遇到性能問題優(yōu)先考慮緩存”“ORM 字段別用前綴”“時間字段統(tǒng)一存時間戳”……寫了兩百多行。結(jié)果發(fā)現(xiàn) AI 在執(zhí)行基礎(chǔ)任務時反應明顯變慢而且經(jīng)常抓不住重點把一些邊緣規(guī)范當成首要約束。原因其實可以理解上下文是有容量的模板越長核心約束在相對位置上就越不顯眼。AI 可能看得到但注意力被分散了?，F(xiàn)在我的策略是嚴格分層全局和項目級 CLAUDE.md 控制在 20 到 30 行以內(nèi)只保留最高頻、最關(guān)鍵、收益最大的規(guī)則那些適用于特定場景的豐富細節(jié)全部挪到斜杠命令的模板文件里。效果很直接——AI 對核心規(guī)則的遵循率明顯回來了。4.3 模板規(guī)則與實際需求沖突了怎么辦模板是默認行為不是鐵律這一點必須在模板里寫清楚。比如我的某個項目里模板寫了“不自動修改 lock 文件”但某次升級依賴確實必須更新 lock 文件這時如果模板沒有任何關(guān)于“例外處理”的說明AI 大概率會卡在規(guī)則上反復詢問或者干脆自作主張繞開。合理的做法是在模板里補一句當任務明確需要違反某條禁忌時先說明理由并爭取確認而不是直接拒絕或硬執(zhí)行。這不僅是給 AI 的指令也是對團隊協(xié)作邊界的定義規(guī)則存在的意義是防止手滑而不是限制決策。有了這一句“例外說明”模板就從一個僵硬的檢查表變成了一個靈活的協(xié)作協(xié)議AI 的行為會合理得多。4.4 快速排查自查表現(xiàn)象可能原因處理方式改模板后行為沒變會話未重新加載記憶重開會話再試模板完全沒生效文件名或路徑不對檢查是否為根目錄的CLAUDE.md注意大小寫規(guī)則偶爾執(zhí)行偶爾不執(zhí)行模板過長核心約束被稀釋精簡常駐模板細節(jié)下放到命令模板項目間規(guī)則串味全局模板里寫入了項目專屬內(nèi)容把具體技術(shù)棧規(guī)則移到項目級模板出現(xiàn)矛盾指令全局與項目級模板內(nèi)容沖突以項目級為準并刪除全局中的冗余描述不清楚 AI 到底讀了哪些規(guī)則模板加載狀態(tài)未知在對話里直接詢問它做了哪些預設(shè)讓它復述最后一條我自己現(xiàn)在經(jīng)常用。遇到 AI 表現(xiàn)奇怪我第一件事不是看日志而是直接問它“你現(xiàn)在記住了哪些項目規(guī)則請逐條列出。”它復述出來的內(nèi)容立刻能暴露問題——是沒加載到還是加載了但理解偏了一目了然。5. 場景選型速查與模板演進5.1 常見場景模板選型對照模板庫最忌諱的就是一刀切因為你的任務類型差異極大。評審代碼和寫測試需要的上下文完全不同維護老項目和新項目的行為約定可能完全相反。我整理了一張自己常用的選型表你可以按需取用使用場景推薦模板核心內(nèi)容建議位置日常小改動項目級 CLAUDE.md角色、啟動動作、輸出偏好、基礎(chǔ)禁忌項目根目錄代碼評審code-review 模板評審維度、嚴重級別排序、修改建議格式.claude/commands/寫測試write-tests 模板測試范圍、用例命名、mock 約定.claude/commands/修 bugbug-fixing 模板先復現(xiàn)、再定位、改后回歸驗證.claude/commands/重構(gòu)refactoring 模板保持行為一致、避免大范圍改動、小步提交.claude/commands/提交代碼commit 模板提交信息格式、前置檢查.claude/commands/這張表不是標準答案而是一個起點。你可以對照自己的實際工作流去增刪。關(guān)鍵點是默認常駐模板要克制斜杠命令要豐富。常駐模板負責“不出錯”命令模板負責“做得好”。5.2 模板是活代碼需要隨項目一起演進模板庫不是寫一次就一勞永逸的東西。項目在變你的工作流在變AI 工具本身也在變模板必須跟著項目一起演進。我自己大概每一到兩周會翻一次模板做一次“清理”刪掉那些 AI 已經(jīng)形成慣性、不再需要提醒的規(guī)則。比如某個項目里早就不需要強調(diào)“先跑測試”因為它每次都跑了這條就可以從模板里拿掉給更重要的新約束騰地方。然后補上最近踩過的新坑。比如我某次發(fā)現(xiàn) AI 在重構(gòu)時差點改了公共接口回來后我就在 refactoring 模板里加了一條“涉及公共 API 變更前必須列出所有受影響調(diào)用方?！边@個“清理—補充”的節(jié)奏比任何一次性的精心設(shè)計都重要。因為模板的價值永遠不在于紙面上的完整性而在于它對當前階段的真實工作是否還有指導意義。一份好久沒動的模板跟一份好久沒維護的代碼一樣會慢慢變成團隊里的“僵尸文檔”。5.3 最后說一點個人體會在做 claude-code-templates 之前我一直覺得讓 AI 干活的核心是“prompt 寫得好”。后來發(fā)現(xiàn)prompt 寫得好不如把高頻的公共上下文沉淀成模板來得穩(wěn)定。前者靠臨場發(fā)揮后者靠體系復用。用 Claude Code 到現(xiàn)在模板庫是我改動頻率最高的“基礎(chǔ)設(shè)施”之一它在不知不覺中提升了每一次對話的下限——就算某一輪我懶得寫太多細節(jié)AI 也不會從零開始而是站在模板給它搭好的肩膀上干活的。如果你剛開始做這件事我只建議你記住一句話模板要越用越“貼手”不用怕改不用怕刪。把模板當代碼寫慢慢迭代它會在你日常開發(fā)里變得比想象中更值得依賴。