我第一次用 Claude Code 的時候其實不太順利。每開始一個新任務都要在提示詞里重新交代項目背景、技術(shù)棧、代碼風格、驗收標準一套流程下來等我折騰完熱情已經(jīng)消耗一半。更麻煩的是就算交代了它也經(jīng)常在中間環(huán)節(jié)忘記我后面的約束。后來我試著把經(jīng)常用的 prompt 整理成模板統(tǒng)一放進一個倉庫管理這才終于體驗到“一條命令就進入狀態(tài)”的感覺。這篇文章就聊聊我的 claude-code-templates 積累過程包括模板分類、目錄結(jié)構(gòu)、加載方式以及那些真正踩過的坑。1. 為什么需要一套 claude-code-templates1.1 真正的問題不是 AI 不聰明而是你每次都在重新解釋Claude Code 本身能力不弱但是它的“記憶”完全依賴當前會話里的上下文。你給它看了什么、說了什么它才知道什么你沒寫的它只能靠猜。一旦項目變大你不可能每次都把幾十個文件的核心約束重新粘進對話里更不可能要求每個參與的人都記得同樣一套規(guī)則。我印象很深的一次讓 Claude 幫忙重構(gòu)一個訂單服務類。我在對話里寫了“不要動接口簽名保留現(xiàn)有日志不要引入新依賴”結(jié)果幾分鐘后它直接把方法簽名改了還順手加了一個我沒見過的工具庫。問題不是它能力不夠而是我給的指令只對當前輪有效下一輪它開始自由發(fā)揮。后來我把這類約束寫成一個固定模板每次調(diào)用時自動帶出來效果立刻穩(wěn)定很多。1.2 模板解決的是“上下文與狀態(tài)”的確定性模板的本質(zhì)是把一組經(jīng)過驗證的、跨任務復用的指令沉淀成靜態(tài)資產(chǎn)。你可以把它理解成菜譜。菜譜不會替你煎牛排的熟度但它能保證你每次下鍋前都知道要放多少油、用多大火不會因為今天心情不同就亂灑調(diào)料。Claude Code 也是一樣模板化的 prompt 能降低兩件事的不確定性模型的輸出風格和關(guān)注點是否穩(wěn)定你和模型在最開始的若干輪里到底把注意力花在“對齊規(guī)則”還是“解決任務”上。用模板還有一個隱性好處省 token。同樣一句“先給方案不要直接改代碼”寫死在一個文件里你只需要在模板里出現(xiàn)一次如果靠現(xiàn)場手寫大概率每次都要重復最后還寫得不如模板精確。1.3 這套模板適合誰、能覆蓋什么場景我最推薦下面幾類人認真整理自己的 claude-code-templates已經(jīng)在用 Claude Code 寫業(yè)務代碼但覺得每次對話“啟動成本”很高的人團隊有多人共用同一個倉庫希望 AI 的 Review 和提交信息風格保持一致的人希望把個人經(jīng)驗沉淀成資產(chǎn)而不是每次靠臨場發(fā)揮的人。它覆蓋的場景很廣日常任務拆解、代碼審查、重構(gòu)、生成提交信息、補文檔、定位線上問題幾乎每個動作都可以模板化。唯一不太適合模板化的是那種一次性的純知識問答比如“解釋一下什么是 B 樹”這種情況直接問就好套模板反而顯得累贅。2. 模板的核心分類與設計拆解2.1 角色與行為模板先在開頭把“人設”立住很多人使用 Claude Code 時喜歡一上來就甩任務但忘了一個關(guān)鍵步驟告訴模型它現(xiàn)在扮演誰、受什么約束。一個沒有角色邊界的模型回答問題的自由度太高容易跑偏。所以我第一個模板通常是“角色與行為約束”它的作用相當于給模型劃定工作半徑。我常用的基礎(chǔ)模板長這樣你是一名資深后端工程師熟悉 Java/Spring Boot 項目。 當前項目背景 - 技術(shù)棧Java 21 Maven PostgreSQL - 包結(jié)構(gòu)按業(yè)務模塊分包repository 層統(tǒng)一使用 MyBatis-Plus - 代碼風格Google Java Format私有方法放在類底部 工作原則 1. 先理解需求再給出方案不要直接改代碼 2. 所有建議必須說明對現(xiàn)有模塊的影響面 3. 不引入不必要的依賴優(yōu)先復用現(xiàn)有工具類 4. 涉及刪除代碼時先說明刪了會影響哪些調(diào)用方。 輸出要求 - 使用 Markdown 列表簡潔為主 - 代碼塊必須標注語言 - 存在風險點放在“注意”一欄。這個模板的價值不在文采而在把團隊約定固化下來。實際使用中我發(fā)現(xiàn)角色說明越具體越能減少“我本來想讓它在某條業(yè)務線上做縱深它卻在通用能力上泛泛而談”的情況。注意不要寫成一篇幾千字的“人格設定”模型不會和你玩扮演游戲它只需要清晰、可執(zhí)行的邊界。2.2 任務拆解模板從一句話到可執(zhí)行計劃用戶給 Claude Code 最常提的說法是“幫我做一個功能”這其實是反模式。缺少目標、約束和驗收條件的任務模型只能靠猜而且容易一步到位地改代碼。我后來強制自己使用“任務拆解模板”把模糊請求變成結(jié)構(gòu)化指令。模板的設計分成五個部分目標、約束、輸入、輸出、驗收標準。請按以下結(jié)構(gòu)完成開發(fā)任務 目標 {一句話描述你要達成的結(jié)果} 約束 - 不能改動 {受保護的文件/接口} - 保持與現(xiàn)有 {模塊/風格} 一致 - 性能要求{例如單次查詢耗時不超過 200ms} 輸入 - 相關(guān)代碼文件{路徑列表} - 相關(guān)業(yè)務背景{補充說明} 輸出 1. 實現(xiàn)方案簡述 2. 關(guān)鍵代碼 diff 3. 自測步驟 4. 潛在風險。 驗收標準 - {標準 1可執(zhí)行的檢查項} - {標準 2可執(zhí)行的檢查項}這套模板讓我最受益的地方是“驗收標準”一欄。以前 Claude 經(jīng)常告訴我“完成了”但到底怎么算完成雙方理解完全不同?，F(xiàn)在有了驗收項它會在動手前自己先核對一遍極大減少了“做完但沒做對”的返工。2.3 代碼審查模板讓 Review 不停留在“看起來沒問題”把 Claude Code 用于代碼審查其實比寫代碼更穩(wěn)。生成代碼時它會興奮地“創(chuàng)造”但審查時它更容易調(diào)用分析能力。不過如果你只丟一句“幫我 review 一下”它大概率會回你一堆“看起來很好”的空話。我需要的是一個能強制它逐項檢查的 checklist 模板。下面是我一直在用的審查模板請審查當前代碼改動重點檢查以下維度 1. 正確性 - 是否存在空指針、越界、并發(fā)問題 - 邊界條件是否被覆蓋 - 異常路徑是否會導致狀態(tài)不一致。 2. 性能 - 是否有 N1 查詢或不必要的全表掃描 - 是否創(chuàng)建了重復對象 - 大數(shù)據(jù)量下是否存在內(nèi)存隱患。 3. 安全 - 是否存在 SQL 注入 / XSS 等風險 - 是否對用戶輸入做了校驗。 4. 可讀性與維護性 - 命名是否清晰 - 是否有可以抽取的重復邏輯 - 新增代碼是否遵循項目現(xiàn)有模式。 5. 測試 - 關(guān)鍵邏輯是否有對應單測 - 測試是否覆蓋了失敗路徑。 輸出格式 - 按嚴重程度分級阻塞 / 重要 / 建議 - 每個問題必須附上具體文件和行號 - 沒有問題的維度也要明確寫“未發(fā)現(xiàn)問題”不要默認跳過。這個模板執(zhí)行一次后我基本不需要再追問補充意見。它最核心的一點是“沒有問題的維度也要寫未發(fā)現(xiàn)問題”這會倒逼模型真實檢查而不是敷衍地夸一句。對個人項目和團隊 Review 都適用。2.4 文檔與提交信息模板把瑣碎收尾變成固定動作開發(fā)中最容易被忽略的是收尾動作。寫完代碼后提交信息和更新文檔屬于枯燥但必不可少的步驟。模板在這里的價值不是提高生成速度而是保持風格統(tǒng)一讓 Git 歷史看起來像一個“人”提交的。我這里的提交信息模板基于 Conventional Commits 做了簡化請根據(jù)當前改動生成提交信息。 要求 1. 使用 Conventional Commits 格式 2. type 從以下值中選擇 feat, fix, refactor, docs, test, chore, perf, style 3. 主題不超過 50 個字符 4. scope 必須寫對應模塊名例如feat(order-service) 5. 正文按“為什么改”和“改了什么”兩個部分組織 6. 如果涉及破壞性變更在尾部用 BREAKING CHANGE 標注。 當前改動 {可以由模型讀取 git diff 后自動填充}文檔模板則是給“寫完代碼后補一段設計說明”用的一般包含背景、方案選型、調(diào)用方式、注意事項。用模板的好處很明顯Claude 輸出的文檔不會再出現(xiàn)一堆空話而是按照你關(guān)心的維度逐條展開。實踐下來文檔模板和提交信息模板加起來基本能覆蓋項目里 90% 的瑣碎收尾。3. 實操從零搭建你的 claude-code-templates 項目3.1 倉庫結(jié)構(gòu)與模板格式選擇先回答一個常見問題模板用什么格式保存我的答案是純 Markdown不要用 JSON更不要自定義 DSL。原因有三個Markdown 本身就是 Claude 最熟悉的輸入格式它不會理解錯層級Markdown 可以用 Git 做 diff模板改動歷史清清楚楚團隊成員即使不熟悉代碼也能看懂模板內(nèi)容。我的倉庫結(jié)構(gòu)非常簡單claude-code-templates/ ├── CLAUDE.md ├── README.md └── commands/ ├── review.md ├── task.md ├── docs.md └── commit.md其中CLAUDE.md是給 Claude Code 的“項目級長期記憶”commands/目錄放可以一鍵觸發(fā)的命令模板。如果是個人使用這個規(guī)模完全夠了團隊用的話可以按業(yè)務模塊再拆子目錄。為什么不做成一個龐大的“全家桶”因為模板一旦太多加載和檢索成本反而超過手工寫 prompt 的成本。我見過有人收集了幾百個模板結(jié)果一個都不常用那不是效率工具是收藏癖。真正的模板庫應該保持“夠用且精煉”。3.2 利用 CLAUDE.md 承載項目級長期約束Claude Code 有一個很關(guān)鍵的特性如果項目根目錄存在CLAUDE.md它會在一開始就把這個文件作為長期上下文帶入對話。我在模板倉庫的根目錄放了一份CLAUDE.md內(nèi)容不是具體 prompt而是倉庫說明和調(diào)用約定# claude-code-templates 本倉庫用于存儲和 Claude Code 協(xié)作時的高頻模板。 ## 目錄說明 - commands/ 下的 .md 文件對應同名 slash command - 每個命令文件必須包含 description - 命令內(nèi)容應保持可執(zhí)行不要出現(xiàn)空泛描述。 ## 使用約定 - 調(diào)用代碼審查時使用 /review - 發(fā)起任務拆解時使用 /task - 生成提交信息時使用 /commit - 所有模板只寫約束不寫具體實現(xiàn)細節(jié)。如果你只是在普通項目中使用 Claude Code也可以在項目根目錄維護一份類似的文件把技術(shù)棧、包結(jié)構(gòu)、部署命令、特殊約定都寫進去。這樣每一次啟動對話模型天然知道“我在哪里、能做什么、不能做什么”。我個人的體會是項目級CLAUDE.md比任何復雜 prompt 都管用因為它根本不需要你每次粘貼就已經(jīng)在上下文里了。3.3 把模板注冊成 Slash Command 并調(diào)用如果每次用模板都要打開文件、復制、粘貼那使用成本仍然太高。正確的方式是把模板注冊成 Slash Command。在 Claude Code 中項目級命令存放在.claude/commands/目錄下文件名去掉.md就是命令名。比如我在.claude/commands/review.md里寫入--- description: 按團隊規(guī)范執(zhí)行代碼審查 --- 請審查當前改動重點檢查正確性、性能、安全、可讀性和測試覆蓋。 按阻塞/重要/建議三級輸出問題并標注具體文件與行號。保存后在當前項目里啟動 Claude Code直接輸入/review它就會把模板內(nèi)容作為指令帶入當前會話。這個命令文件里的description字段是給命令選擇列表用的寫清楚用途很重要否則時間久了你自己都會分不清。用戶級的命令可以放在~/.claude/commands/下跨項目全局生效。我一般把最通用的task.md放在用戶級把和項目緊密相關(guān)的review.md放進各項目的.claude/commands/里兼顧通用和特定約束。3.4 一個完整模板的執(zhí)行流程以/review為例完整執(zhí)行流程是這樣的在項目根目錄建立.claude/commands/放入review.md啟動 Claude Code輸入/review模型讀取命令模板然后調(diào)用工具查看當前分支的改動模型按模板清單逐項檢查最終輸出分級審查結(jié)果。實際生成的結(jié)果看起來會像這樣【阻塞】文件 src/service/OrderService.java 第 132 行 在循環(huán)中調(diào)用 findById產(chǎn)生 N1 查詢。建議改為批量查詢后內(nèi)存匹配。 【重要】文件 src/service/OrderService.java 第 45 行 異常被吞掉后繼續(xù)執(zhí)行失敗路徑無法感知。建議至少記錄日志。 【建議】文件 src/controller/OrderController.java 第 67 行 入?yún)⑿ｒ炦壿嫼?service 層重復建議提煉公共方法。 未發(fā)現(xiàn)問題安全性檢查、測試覆蓋檢查。這套流程的妙處在于模板只負責提供檢查框架真正讀代碼、跑 diff 的動作還是由模型自己完成。你不用在對話里手動貼一堆文件輸入一條命令就夠了。4. 常見問題與排查技巧實錄4.1 模板調(diào)用后沒反應問題出在哪我遇到過最蠢的情況是模板文件路徑寫錯命令名怎么敲都無效。Slash Command 的搜索路徑必須包含.claude/commands/而且文件擴展名必須是.md。如果你放在項目根目錄而不是.claude下面那它不會被加載。排查步驟很簡單確認路徑項目級是.claude/commands/xxx.md確認文件名命令名由文件名的去擴展名部分組成不要用中文空格或大寫字符重啟 Claude Code 會話命令是啟動時加載的新增文件后需要新開會話如果急著用先手動/read .claude/commands/review.md再告訴它“按這個模板執(zhí)行”。在新會話里加載完畢后調(diào)用/review就能看到模板效果。如果仍然沒反應多半是description字段缺失導致命令列表無法識別補上就好。4.2 上下文窗口被長模板撐爆模板不是越長越好。我第一次寫 review 模板時一口氣把幾十條檢查項塞了進去結(jié)果 Claude 的上下文窗口被占掉一大截真正回答問題時反而變得遲鈍。后來我把模板精簡到 20 行左右只保留最核心的檢查維度效果立刻改善。處理長模板有兩條經(jīng)驗把模板拆成多個小命令比如review-security.md、review-performance.md需要哪一個就調(diào)用哪一個模板只寫“原則和清單”不寫長篇解釋。詳細的原理說明應該放在CLAUDE.md里而不是放在每次都會被加載的命令文件里。如果你發(fā)現(xiàn)某次對話上下文已經(jīng)塞得很滿可以先用/clear清理會話再繼續(xù)。模板的意義是讓你穩(wěn)定起步不是讓你把整個項目文檔都塞進去。4.3 模板太粗或太細怎么找到平衡模板太粗起不到約束作用模板太細會限制模型的合理發(fā)揮。我踩過兩個方向上的坑節(jié)奏感是靠反饋調(diào)整出來的。粗的例子“請認真完成這個任務。”這種話沒有任何可執(zhí)行性Claude 只能自由發(fā)揮。細的例子強迫它每次輸出必須按某個特定格式逐字包含 50 個字段導致大量輸出口水話。我的參考區(qū)間是一份模板 50200 行。對于代碼審查這種需要覆蓋多個維度的場景可以靠近 150 行對于提交信息這種單一場景50 行以內(nèi)就夠了。調(diào)優(yōu)方法也很簡單每次使用后記錄一個“不滿意”的點把它作為一行約束加進模板。比如我發(fā)現(xiàn) Claude 總是不寫“影響面”就在角色模板里加一行“所有建議必須說明影響面”。迭代幾輪模板會越來越貼合你的習慣。4.4 團隊如何共用一套模板模板最容易被忽視的價值是團隊一致性。如果團隊五個人都在用 Claude Code每個人自己維護一套風格完全不同的 prompt結(jié)果就是 review 建議風格五花八門。所以我在團隊里做了一件事單獨建一個claude-code-templates倉庫所有成員通過 Git 同步。同步方式有兩種直接把整個倉庫作為子模塊掛到各項目的.claude下用一個簡單的 shell 腳本把commands/里的文件復制到本地項目目錄。我更傾向腳本同步因為子模塊在頻繁改模板時會產(chǎn)生很多額外 commit。腳本只做一件事拉取遠程模板復制到當前項目的.claude/commands/下。模板變更后每個人執(zhí)行一次就能更新到最新。團隊維護模板還有一個硬性要求必須有description和簡短的 README 說明。否則別人看到一堆不認識的命令根本不知道有什么用。我也在 CI 里加了一個輕量檢查掃描所有.md文件是否包含description字段不通過就不允許合并。這個動作很小但能避免模板庫變成垃圾場。我現(xiàn)在自己維護的 claude-code-templates 里真正高頻使用的其實只有六七個文件。但我最大的體會是模板的價值不在于讓 Claude 更聰明而在于讓我自己重新整理了一遍工作流。每當我踩到一個新坑我就把它寫成一行約束加進對應模板下一次就不再犯同樣的錯。寫模板時我還會特意用否定句而不只是肯定句比如“不要引入新依賴”“不要改動接口簽名”模型對明確的禁止項比泛泛的目標更敏感。慢慢積攢下來這套模板更像是我和 Claude 協(xié)作時沉淀出的第二大腦。