我維護一個叫claude-code-templates的模板庫已經(jīng)有一段時間了。最開始只是自己寫的幾個零散 prompt 文件后來發(fā)現(xiàn)團隊里好幾個朋友也在用 Claude Code 干活一個個都在重復(fù)造輪子干脆把這些年踩過的坑、沉淀下來的協(xié)作模式整理成了一套可復(fù)用的模板體系。Claude Code 本質(zhì)上是跑在命令行里的編程助手它可以直接讀你倉庫里的代碼、改文件、執(zhí)行測試命令甚至能拿著終端輸出繼續(xù)幫你排查問題。聽起來很強大但實際用起來你會發(fā)現(xiàn)一個問題每次新開一個會話它對你的項目背景、代碼規(guī)范、輸出要求一無所知你又要從“我們是做什么的、代碼在哪個目錄、命名習(xí)慣是什么”開始解釋一遍。這就像每次來一個新實習(xí)生你都得把部門規(guī)章制度從頭講一遍講完還得盯著他干活。模板要解決的就是把這套“入職培訓(xùn)”固化成標(biāo)準(zhǔn)文件讓 AI 開箱即用。這套模板庫適合誰正在用或者準(zhǔn)備用 Claude Code 做日常開發(fā)的工程師尤其是那些覺得“AI 寫出來的代碼總差口氣還得自己反復(fù)改提示詞”的人。它會告訴你差的不是模型是你沒有把協(xié)作規(guī)范講清楚。這篇文章我會把這套模板體系的目錄設(shè)計、核心模板的寫法、以及實際接入工作流的方法全部拆開講內(nèi)容偏實操你可以直接抄走。1. 為什么需要 Claude Code 模板從“每次調(diào)教”到“開箱即用”1.1 Claude Code 的協(xié)作邏輯與模板的切入點要理解模板的價值得先理解 Claude Code 的工作方式。它跟你平時在網(wǎng)頁端問 ChatGPT 不太一樣——它在你的終端里運行有文件讀寫權(quán)限能執(zhí)行終端命令這意味著它更像一個“坐在你旁邊的結(jié)對編程伙伴”而不是一個只負(fù)責(zé)回答問題的對話框。既然是結(jié)對編程伙伴就涉及協(xié)作習(xí)慣的問題。真人伙伴跟你配合久了知道你寫 Python 喜歡用 type hint知道你的測試用 pytest 而不是 unittest知道你提交代碼要走 conventional commits。這些“默契”不是天生的是長期磨合出來的。AI 也一樣你以為它聰明到能自己從代碼里推測出你的偏好其實它每次會話都是“失憶”的只能依賴你在對話里給的有限信息加猜測。模板就是把這些“默契”外化成文件。我在模板庫里定義了一套分層結(jié)構(gòu)全局配置管角色和通用規(guī)范項目配置管當(dāng)前倉庫的上下文任務(wù)模板管具體活兒的執(zhí)行流程。這樣每次調(diào)用 Claude Code它讀一遍這些文件就等于瞬間完成了“入職培訓(xùn)”直接進入干活狀態(tài)。1.2 模板化要解決的三個核心痛點第一個痛點是重復(fù)解釋。很多團隊用 Claude Code 干的第一件正事是“幫我看下這幾個文件的代碼問題”結(jié)果 AI 上來先問“請問您的項目是什么語言主要功能是什么代碼在哪個目錄”你明明已經(jīng)給了它整個倉庫的訪問權(quán)它卻像個沒做過功課的新人。有了項目級 CLAUDE.md 模板這些問題都不需要你回答AI 自己讀完模板就能把項目背景、技術(shù)棧、關(guān)鍵目錄全部搞清楚。第二個痛點是輸出不可控。同一個項目你讓 AI 寫一段業(yè)務(wù)代碼它可能這次給你一坨大函數(shù)下次給你拆成五個小函數(shù)。不是它飄了是你沒跟它說清楚你的代碼風(fēng)格偏好。我在模板里會寫“業(yè)務(wù)代碼優(yōu)先拆小函數(shù)單個函數(shù)不超過 40 行”“所有公共函數(shù)必須帶 docstring”“變量命名使用 snake_case”AI 的輸出立刻穩(wěn)定下來了。第三個痛點是經(jīng)驗無法沉淀。今天你費了半天功夫調(diào)出了一套完美的代碼審查提示詞明天換臺電腦就丟了。模板庫天然就是沉淀經(jīng)驗的載體——把一次性的優(yōu)秀口頭提示詞整理成 markdown 文件存進 git 倉庫團隊所有人都能復(fù)用。1.3 模板設(shè)計的頂層原則在設(shè)計模板庫結(jié)構(gòu)之前我給自己定了幾條規(guī)矩這里也分享給你。第一分層管理。全局模板管“你是個什么樣的 AI 助手”項目模板管“你面對的是一個什么樣的項目”任務(wù)模板管“這次活兒具體怎么干”。三層職責(zé)不重疊全局模板不能寫項目相關(guān)的東西任務(wù)模板不寫全局職責(zé)。第二原子化。一個模板文件只干一件事。你不要搞一個超級大模板里面既有代碼規(guī)范又有部署流程。我見過有人把上百行提示詞塞進一個文件結(jié)果 AI 一讀上下文就是幾千 token還沒干活呢預(yù)算燒了一半。拆開的好處是你可以按需組合比如“代碼審查”任務(wù)只需要加載審查模板 項目上下文不需要加載“新功能開發(fā)”模板。第三模板必須參數(shù)化。模板里留好變量占位符比如{{language}}、{{test_framework}}用腳本或者 Claude Code 自己的變量替換能力填值。這樣一份模板可以適用于 Java 項目、Python 項目、Go 項目不用每個項目重新寫一份。2. 模板庫的目錄結(jié)構(gòu)與核心模板拆解2.1 目錄結(jié)構(gòu)設(shè)計我的claude-code-templates倉庫目錄長這樣claude-code-templates/ ├── CLAUDE.md # 全局入口AI 啟動時自動讀取 ├── global/ │ ├── system-prompt.md # 角色定義與核心工作原則 │ ├── code-style.md # 代碼風(fēng)格通用約定 │ ├── output-format.md # 輸出格式與匯報規(guī)范 │ └── workflows.md # 常用工作流TDD、重構(gòu)、調(diào)試 ├── tasks/ │ ├── review.md # 代碼審查任務(wù)模板 │ ├── refactor.md # 重構(gòu)任務(wù)模板 │ ├── feature.md # 新功能開發(fā)模板 │ ├── bugfix.md # Bug 修復(fù)模板 │ └── docs.md # 文檔生成模板 └── projects/ ├── python-service/ │ └── CLAUDE.md # 具體項目上下文 └── web-frontend/ └── CLAUDE.md這個結(jié)構(gòu)你可以直接抄。全局模板放在global/下所有項目共享具體某類活在tasks/下按任務(wù)類型拆分不同項目的差異化上下文放在projects/項目名/CLAUDE.md里。2.2 CLAUDE.md 全局配置模板CLAUDE.md是 Claude Code 的入口文件它之所以叫這個名字是因為 Claude Code 啟動時會在工作目錄里自動尋找這個文件并讀取。所以你只要把模板庫 clone 到機器上然后在項目里軟鏈或復(fù)制一份CLAUDE.mdAI 啟動時就會自動加載配置。我寫的全局CLAUDE.md簡化版長這樣# 角色定位 你是一名資深的全棧軟件開發(fā)工程師擅長代碼審查、架構(gòu)設(shè)計、重構(gòu)、調(diào)試和文檔編寫。 你習(xí)慣用工程化思維解決問題優(yōu)先考慮可維護性和可測試性。 # 工作基本原則 1. 動手改代碼之前先輸出簡要的方案和影響面分析等確認(rèn)后再執(zhí)行。 2. 保持代碼改動最小化不要順手重構(gòu)無關(guān)代碼。 3. 涉及刪除操作文件刪除、數(shù)據(jù)刪除必須二次確認(rèn)。 4. 不確定的需求先列出假設(shè)不要猜。 # 默認(rèn)輸出規(guī)范 - 技術(shù)方案描述使用簡潔的要點式說明不要寫大段散文。 - 給出代碼示例時必須標(biāo)注語言類型。 - 提出修改建議時同時說明理由和潛在風(fēng)險。 # 引入任務(wù)模板的方式 如果用戶要求執(zhí)行代碼審查、重構(gòu)、修復(fù) Bug 等特定任務(wù)先讀取 tasks/ 下對應(yīng)模板文件再開始工作。這個模板的作用是把“角色”和“底線”立住。注意我寫的是“動手改代碼之前先輸出方案”——這一條特別關(guān)鍵它防止 AI 拿到權(quán)限后自作主張把你不希望碰的文件也改了。2.3 任務(wù)模板以“代碼審查”為例任務(wù)模板是復(fù)用價值最高的部分。我把tasks/review.md寫給你看它的結(jié)構(gòu)值得逐段拆解。# 任務(wù)代碼審查 ## 審查范圍 - 待審查文件{{files}} - 審查目標(biāo){{goal}} ## 審查維度按優(yōu)先級排列 1. 正確性邏輯錯誤、邊界條件遺漏、并發(fā)問題 2. 安全性注入風(fēng)險、敏感信息硬編碼、越權(quán)訪問 3. 性能不必要的重復(fù)計算、N1 查詢、內(nèi)存泄漏隱患 4. 可維護性命名是否表意、函數(shù)是否過長、是否存在重復(fù)代碼 5. 可測試性是否有單測覆蓋、依賴是否容易 mock ## 輸出格式 按以下 Markdown 結(jié)構(gòu)輸出審查報告 ### 問題清單 | 嚴(yán)重度 | 文件位置 | 問題描述 | 修改建議 | |--------|----------|----------|----------| ### 總體評價 對本次審查范圍給出 2-3 句總體判斷說明是否需要優(yōu)先處理某些問題。 ## 注意事項 - 只審查列出范圍內(nèi)的文件不要擴大到整個倉庫。 - 每個問題必須給出具體的行號和可操作的修改建議禁止空泛評價。 - 如果發(fā)現(xiàn)審查目標(biāo)之外的嚴(yán)重問題單獨列出不要混入主報告。這個模板的關(guān)鍵在于約束了審查范圍和輸出格式。不寫模板的時候AI 審查代碼經(jīng)常出現(xiàn)兩種極端要么只給一句“看起來不錯”要么把整個文件重寫一遍。模板里的“審查維度”讓它的檢查有章法“輸出格式”讓它的結(jié)果可以直接貼在 PR 評論里你不需要再二次整理。3. 實戰(zhàn)從零搭建一套可復(fù)用的模板體系3.1 初始化與目錄搭建先在你常用的目錄下建一個模板倉庫mkdir claude-code-templates cd claude-code-templates git init mkdir -p global tasks projects然后創(chuàng)建上節(jié)提到的CLAUDE.md和各個目錄下的文件。如果你是團隊使用建好之后直接推到私有 Git 倉庫成員各自 clone 一份即可。接下來讓你自己的項目能使用這套模板。有兩種方案我推薦第二種。方案一把模板庫 clone 到本地后在項目目錄里創(chuàng)建軟鏈ln -s /path/to/claude-code-templates/CLAUDE.md /path/to/your-project/CLAUDE.md方案二直接復(fù)制。復(fù)制的好處是你可以按項目微調(diào)但后續(xù)模板更新不會自動同步。cp /path/to/claude-code-templates/CLAUDE.md /path/to/your-project/CLAUDE.md如果項目里已經(jīng)有自己的CLAUDE.md你需要手動合并內(nèi)容不要直接覆蓋。Claude Code 只讀取當(dāng)前目錄下的這一個CLAUDE.md文件所以合并時要保留項目特有的信息把通用規(guī)范和角色定義替換成模板里的版本。3.2 編寫系統(tǒng)提示詞模板系統(tǒng)提示詞是模板體系里最核心的部分。它定義了 AI 面對任務(wù)時的底層行為方式。網(wǎng)上很多教程會讓你寫“你現(xiàn)在是一個專家”之類的套話說實話效果一般因為模型本身已經(jīng)知道自己是 AI你要做的是給它設(shè)定協(xié)作規(guī)則而不是給它戴高帽。我的global/system-prompt.md內(nèi)容如下你可以參考# 協(xié)作模式 - 每次接手任務(wù)先復(fù)述你對任務(wù)的理解再開始行動。 - 遇到任務(wù)描述含糊的地方列出你的假設(shè)并給一個默認(rèn)處理方案。 - 修改代碼前若涉及多個文件先畫一個簡單的改動清單。 # 問題解決思路 - 先定位問題根因再討論解決方案。禁止繞開根因打補丁。 - 排查問題時輸出你的推理鏈包括你嘗試過的方案和排除掉的原因。 # 對話風(fēng)格 - 回復(fù)使用中文技術(shù)名詞保留英文。 - 要點式輸出優(yōu)先用表格、列表呈現(xiàn)結(jié)構(gòu)化信息。 - 不要輸出與任務(wù)無關(guān)的客套話不要頻繁重復(fù)確認(rèn)。這里面“先復(fù)述任務(wù)理解”是最實用的。AI 經(jīng)常理解偏需求你讓它改 A 它理解成改 B復(fù)述這一條能讓偏差點提前暴露省去返工成本。3.3 變量替換與參數(shù)化實現(xiàn)任務(wù)模板里我用了{{files}}、{{goal}}這樣的占位符。實際使用的時候最簡單的方案是復(fù)制模板文件然后手動把變量替換成真實值。不過次數(shù)多了你會發(fā)現(xiàn)還是麻煩尤其是變量多的時候。我建議寫一個幾十行的 Python 小腳本自動完成變量替換#!/usr/bin/env python3 從模板渲染任務(wù)文件。用法python render.py templates/review.md --var filessrc/main.py --var goal檢查登錄模塊 import argparse from pathlib import Path def render(template_path: str, variables: dict) - str: content Path(template_path).read_text(encodingutf-8) for key, value in variables.items(): placeholder {{ key }} if placeholder not in content: print(f警告模板中不存在占位符 {placeholder}) content content.replace(placeholder, value) return content def main(): parser argparse.ArgumentParser() parser.add_argument(template, help模板文件路徑) parser.add_argument(--var, actionappend, default[], helpkeyvalue 格式) args parser.parse_args() variables {} for item in args.var: key, _, value item.partition() variables[key.strip()] value.strip() rendered render(args.template, variables) print(rendered) if __name__ __main__: main()用法很簡單python render.py tasks/review.md --var filessrc/auth.py --var goal檢查登錄鑒權(quán)邏輯腳本會把渲染好的內(nèi)容輸出到終端你直接復(fù)制給 Claude Code或者把它重定向追加到某個prompt.md文件然后用cat prompt.md | claude-code喂給 AI。3.4 把模板接入日常工作流模板不接入工作流就是一堆死文件。我的日常用法有三個場景。場景一每次 Claude Code 啟動前先讓它讀模板。在項目根目錄啟動 Claude Code 的時候它會自動讀CLAUDE.md。如果你的CLAUDE.md里有“遇到代碼審查任務(wù)先讀取 tasks/review.md”這樣的指令那你只需要在對話里說一句“做一次代碼審查范圍是 src/auth.py”AI 就會自己去讀任務(wù)模板按模板執(zhí)行。場景二手動拼裝組合。如果項目里的CLAUDE.md沒配置“自動讀取任務(wù)模板”你可以在對話里手動指定請先閱讀 /path/to/claude-code-templates/tasks/review.md 中的任務(wù)要求然后按該要求審查 src/auth.py一次指定本次會話內(nèi) AI 都會記住這個模板的內(nèi)容。場景三寫一個 shell 別名一條命令拉起帶模板的會話。在.zshrc或.bashrc里加alias crcd /path/to/your/project claude-code (cat /path/to/claude-code-templates/tasks/review.md)啟動后直接把模板內(nèi)容作為首輪對話發(fā)給 AI省去手工復(fù)制。4. 常見問題與排查技巧實錄4.1 模板內(nèi)容被截斷我在做代碼審查模板的時候一開始寫得特別長恨不得把所有審查規(guī)則全塞進去。結(jié)果發(fā)現(xiàn) Claude Code 上下文有限讀到一半就把模板截斷了后半段的質(zhì)量規(guī)則完全沒生效。這里有個典型的誤區(qū)你以為模板寫得越細 AI 效果越好實際是“過猶不及”。后來我控制每個模板文件在 100 到 200 行以內(nèi)只保留高優(yōu)先級的內(nèi)容。同時把審查維度按優(yōu)先級排列即使上下文被截斷保留下來的也總是最重要的規(guī)則。另外注意CLAUDE.md 里不要放重復(fù)指令。全局模板、項目模板、任務(wù)模板三層加起來總 token 數(shù)越少越好越精簡 AI 越能抓住重點。4.2 模板之間內(nèi)容沖突最常見的情況是全局模板里寫了“使用 camelCase 命名”項目模板里寫了“本倉庫使用 snake_case”AI 讀到?jīng)_突內(nèi)容時會懵掉表現(xiàn)為代碼風(fēng)格隨機切換。排查思路很簡單把項目目錄下的CLAUDE.md、global/目錄文件、以及任務(wù)模板里可能涉及同一主題的段落全部列出來逐一檢查關(guān)鍵詞。我維護了一個簡單的沖突檢查腳本掃描所有 md 文件里的“代碼風(fēng)格”“命名規(guī)范”“縮進”等關(guān)鍵詞列出重復(fù)或沖突的內(nèi)容位置。寫完模板后跑一遍能省不少后面調(diào)試的精力。4.3 換行和 Markdown 格式錯亂Claude Code 讀取模板文件時對空行和縮進的敏感度比你想的高。我踩過一個坑模板里用四個空行分隔段落結(jié)果 AI 把這些空行也當(dāng)作內(nèi)容的一部分輸出報告時格式變得非常松散。解決辦法模板文件統(tǒng)一用標(biāo)準(zhǔn) Markdown 格式段落之間一個空行列表縮進保證一致。不要用制表符不要用四個空格縮進列表項統(tǒng)一用兩空格或直接頂格加-。這些細節(jié)看著不起眼直接決定 AI 生成報告時是否能保持格式穩(wěn)定。4.4 模板不生效明明把CLAUDE.md放到了項目根目錄啟動 Claude Code 之后它卻不按模板行事。排查步驟按順序來確認(rèn)文件名和位置。必須叫CLAUDE.md必須放在啟動命令所在目錄。我之前犯過一個錯把它放到了docs/子目錄下AI 根本讀不到。確認(rèn)模板里沒有語法錯誤。有的模板可能殘留未替換的{{}}占位符AI 讀到未定義變量會跳過相關(guān)指令。確認(rèn)模板編碼是 UTF-8不要用帶 BOM 的 UTF-8 文件否則第一行可能亂碼AI 讀不懂。如果以上都排除了直接在對話里問 AI“請復(fù)述你剛讀到的 CLAUDE.md 內(nèi)容。”它能完整復(fù)述說明加載成功了復(fù)述不出來說明文件路徑或權(quán)限有問題。我把這些高頻問題整理成了速查表問題可能原因處理方案模板內(nèi)容被截斷單文件過長或總上下文過大精簡模板按優(yōu)先級排列控制行數(shù)輸出風(fēng)格不穩(wěn)定多層模板沖突掃描關(guān)鍵詞合并沖突指令格式錯亂換行和縮進不規(guī)范統(tǒng)一 Markdown 格式避免制表符模板不生效文件名、路徑、編碼不對檢查位置、名稱、BOM讓 AI 復(fù)述驗證AI 擅自擴大改動范圍缺少“最小改動”約束在全局模板里強加改動邊界規(guī)則5. 模板體系的進階擴展5.1 跨項目共享模板把模板庫放到 Git 倉庫多個項目共享聽起來簡單實際操作中有個細節(jié)不同項目的技術(shù)棧差異太大全局模板里寫死了編碼規(guī)范Java 項目和 Python 項目用同一套就不合適。我的做法是在項目級CLAUDE.md里做“覆蓋”。全局模板寫的是通用底線項目模板用更具體的規(guī)則覆蓋全局。比如全局寫“變量命名使用 snake_case”項目模板里寫“本倉庫使用 camelCase覆蓋全局 snake_case 規(guī)范”。要保證“覆蓋”生效項目模板的表述必須明確指出是對哪條規(guī)則的覆蓋算是對 AI 的明確暗示。5.2 為不同編程語言定制風(fēng)格模板模板庫到后期一定會往這個方向演化。同一個“代碼審查”任務(wù)審查 Python 項目和審查 Go 項目運行的重點完全不同。Python 要看類型標(biāo)注、異常處理Go 要看錯誤處理是否規(guī)范、是否有 goroutine 泄漏。我把tasks/review.md做成了基礎(chǔ)版然后為常用語言維護了幾個變體tasks/ ├── review.md # 通用 ├── review-python.md # Python 專用 ├── review-go.md # Go 專用 └── review-java.md # Java 專用語言專用模板里不再寫“審查維度”這種通用部分而是直接寫該語言最容易出問題的點。比如review-go.md里我會寫“檢查每個錯誤是否都被正確處理禁止使用 _ 忽略錯誤”。這個文件是從真實項目的代碼評審記錄里提煉的比通用模板針對性高很多。5.3 與自動化流程結(jié)合模板庫積累多了之后每次手動執(zhí)行變得繁瑣。我可以把渲染腳本和模板路徑配置進Makefile一條命令生成指定任務(wù)的完整提示詞review: python render.py tasks/review.md --var files$(FILES) /tmp/prompt.md cat /tmp/prompt.md refactor: python render.py tasks/refactor.md --var module$(MODULE) /tmp/prompt.md cat /tmp/prompt.md你也可以更進一步把生成好的提示詞通過管道直接傳給 Claude Code 的非交互模式實現(xiàn)半自動化的代碼審查流水線。這個方向我還在完善暫時不在這里展開太多但值得關(guān)注。我個人的體會是模板庫不是一次性建設(shè)完就萬事大吉的東西它需要跟著團隊的實際使用情況持續(xù)迭代。我是每個月月底翻一次“近期哪些 prompt 我重復(fù)寫了”“哪些模板生成的代碼質(zhì)量明顯更好”把經(jīng)驗回流進模板里。經(jīng)過幾輪迭代之后你會明顯感覺到AI 寫代碼的綜合表現(xiàn)不再是擲骰子而是穩(wěn)定在一個可以預(yù)期的水準(zhǔn)上。最后分享一個我一直在用的小技巧給模板文件里所有“禁止類”條款加上明確后果例如“如果修改了審查范圍外的文件本次工作將被判定為不合格”。AI 對明確后果的感知比對道理的感知更敏銳這個細節(jié)比你在提示詞里加多少感嘆號都管用。