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