重復(fù)勞動)
先把結(jié)論放在前面claude-code-templates 并不是什么新奇的黑科技它是一套圍繞 Claude Code 命令行編碼 Agent 整理出來的模板集合核心目標是解決同一個問題——每次打開終端都要把相同需求重新描述一遍。我用 Claude Code 也有一段時間了最初的體驗是“的確很強”但用久了就會發(fā)現(xiàn)重復(fù)勞動非常多生成一個函數(shù)要寫一段需求補齊測試又要寫一段需求做一次代碼審查還得寫一大段約束。這套模板庫做的事就是把高頻動作拆成可復(fù)用的命令文件、項目記憶文件和初始化腳本敲一個斜杠命令就能啟動一段規(guī)范化流程。下面我從設(shè)計思路、模板寫法、項目落地到排錯經(jīng)驗完整拆一遍。1. 項目拆解claude-code-templates 到底解決什么問題1.1 模板不只是提示詞很多剛接觸 Claude Code 的人會把模板簡單理解成“把提示詞存起來下次復(fù)制粘貼”。這么做當然有效果但它沒有解決真正的痛點。Claude Code 本身提供了一個叫 CLAUDE.md 的項目記憶機制。你可以在項目根目錄放一個 CLAUDE.md里面寫清構(gòu)建命令、測試命令、代碼風格、禁止事項Agent 每次啟動都會自動讀取這份記憶。你可以把最常用的需求說明放進去但更聰明的做法是把它當成“工作準則”而不是“一次性指令”。claude-code-templates 真正想沉淀的是一套可以落地的模板工程用 CLAUDE.md 定義 Agent 的長期行為規(guī)范。用.claude/commands目錄下的命令文件把高頻動作固化成斜杠命令。用 settings.json 控制工具權(quán)限、白名單和模型選擇。用一套可復(fù)用的命令正文配合參數(shù)輸入把“寫一個模塊”“審查代碼”“生成測試”變成標準化流程。我在整理這套模板時給自己定的標準很簡單每一個模板都必須能在真實項目里馬上跑起來而不是躺在倉庫里當擺設(shè)。1.2 這套模板能解決哪些核心痛點我觀察到的 Cluade Code 使用場景里高頻痛點其實就三類第一類是上下文不連貫。今天讓 Agent 寫一個工具函數(shù)明天讓它給同一個函數(shù)補測試每天都要重新交代項目背景、文件路徑、代碼風格。時間長了Agent 的回復(fù)質(zhì)量完全依賴你當天提示詞寫得夠不夠細。第二類是路徑和風格反復(fù)橫跳。Agent 有時候會自作主張把代碼放在不合理的目錄有時候會忽略項目已有的命名規(guī)范。你不盯著它就按照通用最佳實踐來結(jié)果跟項目現(xiàn)有代碼風格不一致。第三類是權(quán)限和安全配置混亂。哪些工具允許自動執(zhí)行哪些需要人工確認如果不通過配置文件固定下來Agent 會在不該自動操作的地方擅自改動文件。模板解決這三類問題的方式分別是用項目記憶穩(wěn)定上下文用命令正文固定工作流程用 settings 約束行為邊界。1.3 什么樣的場景值得模板化不是所有需求都適合做成模板。做模板的成本是客觀存在的你寫一份命令文件至少十分鐘維護它還需要持續(xù)投入。我建議只有滿足下面條件的場景才值得模板化每周至少會用三次以上。操作步驟明確輸出結(jié)果可預(yù)期。每次執(zhí)行都需要重復(fù)交代相同背景。執(zhí)行失敗時依賴固定的排查路徑。符合這幾條的場景最常見的就是新模塊開發(fā)、單元測試生成、代碼審查、重構(gòu)、提交信息整理、項目初始化。我不建議把那種特別發(fā)散的需求做成模板比如“幫我看看這個項目有沒有優(yōu)化空間”——這種需求每次都不一樣模板套上去反而限制 Agent 的發(fā)揮空間。2. 理解模板系統(tǒng)的三個組成部分2.1 CLAUDE.mdAgent 的長期記憶Claude Code 的 CLAUDE.md 本質(zhì)上是一個純文本文檔但它在項目里承擔的角色很像“團隊新人手冊”。Agent 每次啟動任務(wù)前都會讀取它并優(yōu)先遵循里面的要求。我在模板庫里維護的 CLAUDE.md 一般分五塊第一塊是項目的基本信息包括技術(shù)棧、目錄結(jié)構(gòu)、常用命令。這一塊是為了讓 Agent 不至于在簡單問題上反復(fù)詢問。第二塊是代碼風格約定包括縮進、命名、組件劃分、導(dǎo)入順序。比如我經(jīng)常寫函數(shù)命名使用動詞開頭布爾類型變量使用 is/has 前綴CSS 類名遵循 BEM 風格。第三塊是“禁止事項”比如不允許修改鎖定文件、不允許跳過測試直接改代碼、不允許在沒有確認的情況下運行刪除命令。第四塊是工作流偏好比如先讀源碼再提問、改動完成前先跑測試、提交代碼前自動整理格式。第五塊是環(huán)境信息包括 Node 版本、包管理器、本地服務(wù)啟動方式。但是有個使用細節(jié)特別容易踩坑Claude Code 對 CLAUDE.md 的讀取遵循就近原則。根目錄的 CLAUDE.md 和.claude/子目錄里的 CLAUDE.md 權(quán)重不一樣子目錄的會覆蓋根目錄的同名規(guī)則。換句話說你可以為不同子模塊定制不同的行為規(guī)范。2.2 自定義斜杠命令把高頻需求變成快捷鍵.claude/commands/目錄是 Claude Code 最實用的功能之一。每放一個 Markdown 文件進去Claude Code 就會多一個斜杠命令比如放一個review.md就能用/review喚起代碼審查流程。命令文件的開頭有一段 YAML 格式的 front matter用來配置元信息。一個最簡單的例子--- description: 審查當前分支的代碼改動 argument-hint: 可選指定審查范圍 ---說明文字后面就是命令正文。正文怎么寫直接決定了這個命令好不好用。我在實際使用中發(fā)現(xiàn)命令正文應(yīng)該具備三個特點第一命令正文里要有明確的角色設(shè)定。告訴 Agent 它現(xiàn)在扮演什么角色比如“你是一個資深前端工程師關(guān)注代碼的可維護性和性能”。角色設(shè)定能讓輸出風格更穩(wěn)定。第二命令正文里要有結(jié)構(gòu)化的輸出要求。比如“先輸出改動文件的列表再按文件逐個列出問題最后給出修改建議”。沒有結(jié)構(gòu)要求的命令很容易收到一段混亂的分析。第三命令正文要支持參數(shù)。Claude Code 的命令可以使用$ARGUMENTS這樣的占位符用戶在調(diào)用命令時輸入的內(nèi)容會原樣注入到命令正文里。2.3 settings.json行為邊界和權(quán)限控制Claude Code 讀取的配置除了 CLAUDE.md還有一個 settings.json。它在項目里的作用就是權(quán)限閘門。我見過不少用戶Claude Code 用了一段時間以后經(jīng)常抱怨 Agent“擅自改了不該改的文件”——問題就出在權(quán)限配置太寬松。settings.json 可以設(shè)置 allow、deny、requireApproval 等規(guī)則比如只允許自動讀寫 src 目錄下的文件遇到刪除操作必須先征求用戶同意。我維護模板時每套配置都會附一份最小可用的 settings.json{ permissions: { allow: [ Read, Edit, Glob, Bash(npm run test) ], deny: [ Bash(rm -rf .*), Edit(lock.json) ], requireApproval: [ Write, Bash(git push) ] } }這里的寫法只是示意不同版本的 Claude Code 對權(quán)限字段的命名可能有差異但思路是一致的把高風險操作用 deny 攔死把普通寫操作用 requireApproval 卡一道人工確認。3. 實操三個高價值模板的完整寫法這一部分我直接把我模板庫里最有生命力的三個命令文件拿出來拆解。它們的共同特點是結(jié)構(gòu)簡單、適用范圍廣、幾乎每周都會用到。3.1 新模塊腳手架模板寫新模塊是使用頻率最高的場景。沒有模板的時候我每次都要說一遍項目背景、模塊職責、文件放哪里、接口怎么導(dǎo)出。有了模板之后我只需要敲/scaffold然后跟上模塊名稱。命令文件內(nèi)容大概是這樣的--- description: 生成一個新模塊的腳手架 argument-hint: 模塊名稱例如 utils/format --- 你是一個熟悉當前代碼庫的資深開發(fā)者。 請根據(jù)用戶提供的模塊路徑完成以下步驟 1. 在 src 目錄下創(chuàng)建對應(yīng)的文件夾和入口文件入口文件命名為 index.js。 2. 根據(jù)模塊功能生成注釋塊內(nèi)容包括模塊用途、作者、創(chuàng)建日期、依賴關(guān)系。 3. 創(chuàng)建類型定義文件如果項目使用 TypeScript。 4. 在模塊目錄下創(chuàng)建一個 README.md寫清模塊的使用方法。 5. 不修改任何已有文件不需要寫測試除非用戶明確要求。 模塊路徑$ARGUMENTS 注意 - 請先閱讀項目的 CLAUDE.md遵循既有命名規(guī)范。 - 文件路徑必須嚴格基于用戶提供的模塊路徑解析不要自行改變目錄結(jié)構(gòu)。這份模板的精髓在于最后那條“不修改已有文件”。很多 Agent 在生成新模塊時會順手改點別的把已有代碼弄得面目全非。加上這條約束以后執(zhí)行就老實多了。3.2 代碼審查模板代碼審查模板是我個人最喜歡的一個命令。Claude Code 讀完代碼以后如果能按固定的框架輸出審查意見價值會比泛泛而談大得多。--- description: 對當前改動進行代碼審查 argument-hint: 可指定文件路徑默認審查全部改動 --- 你是一名資深代碼審查者請嚴格按以下步驟執(zhí)行 第一列出本次改動的文件清單并用表格展示每個文件的改動行數(shù)。 第二逐文件審查以下維度 - 邏輯正確性是否存在邊界條件遺漏 - 安全性是否存在注入、越權(quán)、敏感信息泄露風險 - 可維護性命名是否清晰職責是否單一 - 性能是否存在無意義循環(huán)、重復(fù)計算、內(nèi)存泄漏 第三對每個問題標注嚴重等級 - P0必須修復(fù)可能導(dǎo)致線上故障 - P1建議修復(fù)長期會有隱患 - P2可選優(yōu)化不影響當前功能 第四輸出總結(jié)說明當前改動是否可以直接合并。 審查范圍$ARGUMENTS用了一段時間以后我把嚴重等級的分類也寫進了模板效果非常直觀。P0 級別的問題 Agent 基本都能抓出來比如空指針、未捕獲的異常、明顯越權(quán)操作反而是一些命名混亂、邏輯繞彎的問題需要人工盯一盯。3.3 測試生成與重構(gòu)模板測試模板我做成自適應(yīng)模式如果用戶給了文件路徑就只針對該文件生成測試如果沒有給路徑就自動掃描最近修改的文件。這樣做的好處是不需要維護多個命令文件一個命令覆蓋了“補測某個函數(shù)”和“補測剛改完的一片代碼”兩種需求。--- description: 為指定文件或最近改動生成單元測試 argument-hint: 可選目標文件路徑 --- 你是一個熟悉開源技術(shù)棧的測試工程師。 請根據(jù)用戶指定文件或最近改動的文件生成一份完整的單元測試文件。 要求 1. 測試文件放在與被測文件相同的目錄下命名為 原文件名.test.js。 2. 覆蓋以下場景正常輸入、邊界輸入、異常輸入。 3. 使用項目已有的測試框架和斷言庫不要引入新依賴。 4. 對 Mock 的使用加注釋說明為什么需要 Mock。 目標文件$ARGUMENTS 生成完成后運行項目的測試命令確認新測試全部通過如果失敗主動修復(fù)測試代碼直到通過。特別注意最后一行要求 Agent 主動跑測試直到通過。如果不寫這一句Agent 經(jīng)常只生成測試代碼卻不驗證等于把問題從編寫階段推到了驗收階段。很多用戶沒注意到這些命令是支持“遞歸復(fù)用”的模板里可以指定先執(zhí)行項目已有的其他命令再執(zhí)行當前邏輯。比如重構(gòu)模板的開頭就可以寫成“先執(zhí)行/review再根據(jù)審查結(jié)果進行重構(gòu)”。4. 從零搭建一個模板倉庫目錄結(jié)構(gòu)、命名規(guī)范與迭代方式4.1 推薦目錄結(jié)構(gòu)和命名規(guī)范我當前維護的 claude-code-templates 目錄結(jié)構(gòu)如下claude-code-templates/ ├── README.md ├── CLAUDE.md ├── .claude/ │ ├── settings.json │ └── commands/ │ ├── scaffold.md │ ├── review.md │ ├── test.md │ ├── refactor.md │ ├── commit.md │ └── init.md ├── project-templates/ │ ├── node-lib/ │ ├── react-component/ │ └── cli-tool/ └── docs/ ├── best-practices.md └── troubleshooting.md命名上我堅持三條規(guī)則命令文件名必須用小寫英文動詞一個命令一個動詞不要出現(xiàn)review_and_fix.md這種復(fù)合詞。原因很簡單斜杠命令本身就是快捷鍵快捷鍵要短復(fù)合詞會拖慢輸入速度。每個命令文件必須有 description。沒有 description 的命令不會出現(xiàn)在斜杠命令菜單里而且還容易把自己繞暈。命令內(nèi)部段落用“第一、第二、第三”或者編號列表不要用含糊的“盡可能”“盡量”這類詞。模板是給 Agent 看的Agent 對模糊指令的理解遠不如對明確步驟的理解。4.2 模板設(shè)計的三條原則第一短小。命令正文不要超過兩百行。Claude Code 每次調(diào)用模板模板內(nèi)容都會算進上下文窗口。模板越長讀完模板以后留給實際代碼分析的令牌就越少回答質(zhì)量會肉眼可見地下降。第二明確。把“做什么”和“不做什么”都寫清楚。我見過太多人寫模板只寫正面要求忘了寫邊界結(jié)果 Agent 總是跑偏。比如你讓它“改進這段代碼”它可能連業(yè)務(wù)邏輯都給你改了但如果你加上“只優(yōu)化性能不改變對外接口”結(jié)果立刻收斂。第三可組合。每一個模板盡量只做一件事但允許調(diào)用其他模板。比如測試模板可以通過$ARGUMENTS指定目標文件也可以從重構(gòu)模板的流程里被調(diào)用腳手架模板生成完文件以后可以提示用戶順手執(zhí)行/test補測試。把大模板拆成小模板再組合維護成本會斷崖式下降。4.3 如何用模板初始化一個真實項目這里我拿 project-templates/node-lib 這個目錄舉個例子。它不是一個單純的命令文件而是整套腳手架一份完整的 package.json、一個精簡的目錄結(jié)構(gòu)、一個可以直接當模板用的 CLAUDE.md。用這個腳手架初始化項目時我執(zhí)行的是/init命令命令正文會讓 Claude Code 先讀取 project-templates/node-lib 下的所有文件然后按以下步驟工作復(fù)制整個模板目錄到用戶指定的新項目路徑。修改 package.json 中的項目名、版本號和描述。根據(jù)用戶對項目用途的說明更新 README.md。刪除模板目錄里無用的示例代碼。在新目錄中生成核心入口文件并跑通一次測試。整個過程大概不到一分鐘。如果沒有這套腳手架光是手工建目錄、寫 package.json、配 eslint 就能耗掉快半小時。把“項目初始化”模板化是我覺得投入產(chǎn)出比最高的決定。5. 高頻問題排查和調(diào)試實錄模板系統(tǒng)用久了一定會碰到各種問題。我把在真實項目里踩過的坑按頻率列出來對照排查思路一起講。5.1 命令沒出現(xiàn)在斜杠命令菜單里這是新手最常遇到的第一道坎。文件放進.claude/commands/以后輸入/卻看不到命令大概率是三個原因一是擴展名不對。Claude Code 的命令文件必須使用.md擴展名如果你放了個.txt或者.markdown它不會被識別。二是 front matter 格式不規(guī)范。description字段必須寫在最頂部而且要在兩個---中間。如果缺少結(jié)束的---整個命令會被當成純文本仍然不會出現(xiàn)在菜單里。三是目錄權(quán)限問題。某些系統(tǒng)上.claude目錄沒有正確創(chuàng)建或者放在 Shopify 這類靜默忽略目錄的位置。檢查路徑是不是在項目真實根目錄下。排查技巧很簡單打開 Claude Code 的調(diào)試輸出輸入/看菜單列表如果列表里沒有你的命令再用命令行的ls -la .claude/commands確認文件確實存在且權(quán)限可讀。5.2 Agent 執(zhí)行時忽略模板約束模板寫得清楚但 Agent 就是不照著做這個問題也很多人問過。實際上模板約束被忽略通常不是 Cluade Code 不聽話而是約束在整套提示詞體系里優(yōu)先級太低。Agent 的指令優(yōu)先級排序大概是這樣的用戶當前輸入 命令文件正文 項目 CLAUDE.md 全局 CLAUDE.md 模型內(nèi)置偏好。如果你的模板里寫著“不要修改已有文件”但項目 CLAUDE.md 里寫著“根據(jù)實際情況靈活調(diào)整”Agent 就會傾向于在沖突時選擇更靈活的那一條。所以排查思路是檢查是不是在 CLAUDE.md 里寫了和模板互斥的規(guī)則把模板里最關(guān)鍵的約束也提煉到 CLAUDE.md 的業(yè)務(wù)規(guī)則部分讓它升到更高優(yōu)先級。我早期吃過幾次虧之后養(yǎng)成了把最重要約束同步寫到兩個文件里的習慣這樣 Agent 無論如何都會讀到。5.3 上下文窗口被撐爆模板是上下文消耗大戶尤其是喜歡把示例、歷史命令、完整項目結(jié)構(gòu)都塞進模板的用戶。一旦出現(xiàn)“代碼分析到一半前面的指令被模型忽略”的情況多半是上下文滿了。解法有幾個第一模板里只保留和當前需求強相關(guān)的信息通用規(guī)范交給 CLAUDE.md。 第二設(shè)置模板的 allowed-tools 字段限制命令只能調(diào)用特定工具避免 Agent 無謂地讀取大量文件。 第三用 README 文檔的引用替代模板內(nèi)嵌長文本讓 Agent 按需閱讀。Claude Code 支持在 CLAUDE.md 中用路徑引用其他文檔模板也可以用同樣的方式鏈接到細節(jié)文檔而不是把全部內(nèi)容塞進命令正文。5.4 權(quán)限配置過于寬松或過于嚴格配置權(quán)限是一個典型的“既要又要”問題。allow 列表開得太寬Agent 容易誤操作開得太窄Agent 連讀文件都要反復(fù)確認效率為零。我的經(jīng)驗是分階段配置。模板初始化階段只允許讀文件和寫模板文件項目運行階段把測試命令加入 allow 列表提交階段把 git 相關(guān)操作設(shè)為 requireApproval。模板維護者應(yīng)該默認“最小權(quán)限”發(fā)現(xiàn)某個操作頻繁需要人工確認再把該操作提升到自動通過。下面這張問題排查表是我整理模板庫時隨手寫下的直接放在 docs/troubleshooting.md 里遇到問題時比搜索引擎快得多癥狀大概率原因處理方式斜杠命令不出現(xiàn)文件擴展名或 front matter 錯誤檢查 .md 后綴和 --- 分隔符命令執(zhí)行到一半就停上下文窗口溢出精簡模板縮短中毒分析范圍Agent 不遵循禁止項模板約束優(yōu)先級低于 CLAUDE.md把關(guān)鍵約束同步到 CLAUDE.md工具權(quán)限頻繁被拒settings.json 權(quán)限列表過窄擴大 allow 列表或設(shè)置 requireApproval輸出結(jié)果格式不統(tǒng)一模板缺少結(jié)構(gòu)化輸出要求在模板里指定輸出步驟和標題層級5.5 “參數(shù)注入”出錯的特殊場景還有一個隱蔽的坑$ARGUMENTS變量在使用中文時會遇到編碼問題尤其是在 Windows 終端下。如果你發(fā)現(xiàn)模板里注入的參數(shù)出現(xiàn)亂碼最直接的辦法是改用交互式確認——在命令正文里要求 Agent 先向用戶確認參數(shù)內(nèi)容再繼續(xù)執(zhí)行。這樣雖然多一步交互但能避開整座編碼兼容性的暗礁。6. 維護模板庫的幾條經(jīng)驗心得6.1 不要一上來就想搞完整體系第一次做模板庫的人很容易犯的一個錯是“力圖全面”。又是代碼審查模板又是架構(gòu)評審模板又是安全審計模板目錄建了十幾個真正用過的不超過兩個。我自己的經(jīng)驗是先挑三個最高頻的動作做成模板用一個月把這三份打磨到“閉著眼睛用都不會翻車”再開始擴充。模板庫是長出來的不是設(shè)計出來的。6.2 模板版本控制和團隊共享模板庫本身是我用 git 維護的每次修改都寫清楚 commit message比如“review 模板增加日志輸出檢查項”。這樣以后某一次改動導(dǎo)致工程質(zhì)量下降可以回溯到具體改動點而不是靠記憶。團隊協(xié)作時我把模板庫和項目倉庫分開管理項目倉庫通過 git submodule 或者直接復(fù)制的方式引用模板。直接復(fù)制的好處是項目模板不會被遠程更新打亂壞處是沒法同步升級submodule 則反過來。我個人的偏好是核心命令模板用 submodule項目腳手架代碼直接復(fù)制因為腳手架每次生成項目后一般不會再改。6.3 定期做一次“模板清理”模板也有保質(zhì)期?？蚣苌?、目錄重構(gòu)、工作流調(diào)整都會讓舊模板的部分內(nèi)容失效。我每個季度會做一次模板體檢把每個命令文件從頭讀一遍問自己三個問題——現(xiàn)在還會用這個命令嗎里面的路徑和命令還能跑通嗎有沒有更好的寫法把回答不出來的模板直接刪掉。寧可只有一個用得精的模板也不要十個躺在倉庫里發(fā)霉的模板。6.4 模板庫的最佳狀態(tài)是“可增減”我用下來的體會是Claude Code 的模板系統(tǒng)真正厲害的地方不在于幫你省打字而在于把“人的經(jīng)驗”沉淀成“Agent 的行為模式”。你可以在不同項目間快速切換風格新人也能靠一套模板很快融入已有項目的開發(fā)節(jié)奏。從效率賬來看我最常用的三個模板scaffold、review、test平均每周使用超過二十次每個模板幫我省下大約三到五分鐘的需求描述時間每周就是兩小時左右。更關(guān)鍵的是輸出質(zhì)量穩(wěn)定了同一個需求不會因為狀態(tài)波動時而生成得好、時而生成得差。6.5 最后分享一個小技巧如果你和我一樣經(jīng)常要同時維護多個項目可以在用戶級配置目錄~/.claude/CLAUDE.md里放一份全局規(guī)范把“讀代碼前先讀 README”“提交信息用中文”“小步提交”這類通用于所有項目的規(guī)則寫進去然后項目級 CLAUDE.md 只放該項目獨有的配置。這樣你的模板庫就可以進一步瘦身凡是通用的行為約束不需要塞進每一個命令文件Agent 會自己從全局規(guī)范里讀取。做模板這事不復(fù)雜但確實需要耐心。我最早一份 command 文件前前后后改了四個版本才把指令精簡到既不啰嗦又能穩(wěn)定輸出預(yù)期結(jié)果。建議拿到模板的你也先以“給項目增加一個每日必用命令”為目標跑通一次完整流程再回來慢慢演進成自己的成套模板體系。 Claude Code模板庫：用CLAUDE.md與斜杠命令終結(jié)重復(fù)勞動
先把結(jié)論放在前面claude-code-templates 并不是什么新奇的黑科技它是一套圍繞 Claude Code 命令行編碼 Agent 整理出來的模板集合核心目標是解決同一個問題——每次打開終端都要把相同需求重新描述一遍。我用 Claude Code 也有一段時間了最初的體驗是“的確很強”但用久了就會發(fā)現(xiàn)重復(fù)勞動非常多生成一個函數(shù)要寫一段需求補齊測試又要寫一段需求做一次代碼審查還得寫一大段約束。這套模板庫做的事就是把高頻動作拆成可復(fù)用的命令文件、項目記憶文件和初始化腳本敲一個斜杠命令就能啟動一段規(guī)范化流程。下面我從設(shè)計思路、模板寫法、項目落地到排錯經(jīng)驗完整拆一遍。1. 項目拆解claude-code-templates 到底解決什么問題1.1 模板不只是提示詞很多剛接觸 Claude Code 的人會把模板簡單理解成“把提示詞存起來下次復(fù)制粘貼”。這么做當然有效果但它沒有解決真正的痛點。Claude Code 本身提供了一個叫 CLAUDE.md 的項目記憶機制。你可以在項目根目錄放一個 CLAUDE.md里面寫清構(gòu)建命令、測試命令、代碼風格、禁止事項Agent 每次啟動都會自動讀取這份記憶。你可以把最常用的需求說明放進去但更聰明的做法是把它當成“工作準則”而不是“一次性指令”。claude-code-templates 真正想沉淀的是一套可以落地的模板工程用 CLAUDE.md 定義 Agent 的長期行為規(guī)范。用.claude/commands目錄下的命令文件把高頻動作固化成斜杠命令。用 settings.json 控制工具權(quán)限、白名單和模型選擇。用一套可復(fù)用的命令正文配合參數(shù)輸入把“寫一個模塊”“審查代碼”“生成測試”變成標準化流程。我在整理這套模板時給自己定的標準很簡單每一個模板都必須能在真實項目里馬上跑起來而不是躺在倉庫里當擺設(shè)。1.2 這套模板能解決哪些核心痛點我觀察到的 Cluade Code 使用場景里高頻痛點其實就三類第一類是上下文不連貫。今天讓 Agent 寫一個工具函數(shù)明天讓它給同一個函數(shù)補測試每天都要重新交代項目背景、文件路徑、代碼風格。時間長了Agent 的回復(fù)質(zhì)量完全依賴你當天提示詞寫得夠不夠細。第二類是路徑和風格反復(fù)橫跳。Agent 有時候會自作主張把代碼放在不合理的目錄有時候會忽略項目已有的命名規(guī)范。你不盯著它就按照通用最佳實踐來結(jié)果跟項目現(xiàn)有代碼風格不一致。第三類是權(quán)限和安全配置混亂。哪些工具允許自動執(zhí)行哪些需要人工確認如果不通過配置文件固定下來Agent 會在不該自動操作的地方擅自改動文件。模板解決這三類問題的方式分別是用項目記憶穩(wěn)定上下文用命令正文固定工作流程用 settings 約束行為邊界。1.3 什么樣的場景值得模板化不是所有需求都適合做成模板。做模板的成本是客觀存在的你寫一份命令文件至少十分鐘維護它還需要持續(xù)投入。我建議只有滿足下面條件的場景才值得模板化每周至少會用三次以上。操作步驟明確輸出結(jié)果可預(yù)期。每次執(zhí)行都需要重復(fù)交代相同背景。執(zhí)行失敗時依賴固定的排查路徑。符合這幾條的場景最常見的就是新模塊開發(fā)、單元測試生成、代碼審查、重構(gòu)、提交信息整理、項目初始化。我不建議把那種特別發(fā)散的需求做成模板比如“幫我看看這個項目有沒有優(yōu)化空間”——這種需求每次都不一樣模板套上去反而限制 Agent 的發(fā)揮空間。2. 理解模板系統(tǒng)的三個組成部分2.1 CLAUDE.mdAgent 的長期記憶Claude Code 的 CLAUDE.md 本質(zhì)上是一個純文本文檔但它在項目里承擔的角色很像“團隊新人手冊”。Agent 每次啟動任務(wù)前都會讀取它并優(yōu)先遵循里面的要求。我在模板庫里維護的 CLAUDE.md 一般分五塊第一塊是項目的基本信息包括技術(shù)棧、目錄結(jié)構(gòu)、常用命令。這一塊是為了讓 Agent 不至于在簡單問題上反復(fù)詢問。第二塊是代碼風格約定包括縮進、命名、組件劃分、導(dǎo)入順序。比如我經(jīng)常寫函數(shù)命名使用動詞開頭布爾類型變量使用 is/has 前綴CSS 類名遵循 BEM 風格。第三塊是“禁止事項”比如不允許修改鎖定文件、不允許跳過測試直接改代碼、不允許在沒有確認的情況下運行刪除命令。第四塊是工作流偏好比如先讀源碼再提問、改動完成前先跑測試、提交代碼前自動整理格式。第五塊是環(huán)境信息包括 Node 版本、包管理器、本地服務(wù)啟動方式。但是有個使用細節(jié)特別容易踩坑Claude Code 對 CLAUDE.md 的讀取遵循就近原則。根目錄的 CLAUDE.md 和.claude/子目錄里的 CLAUDE.md 權(quán)重不一樣子目錄的會覆蓋根目錄的同名規(guī)則。換句話說你可以為不同子模塊定制不同的行為規(guī)范。2.2 自定義斜杠命令把高頻需求變成快捷鍵.claude/commands/目錄是 Claude Code 最實用的功能之一。每放一個 Markdown 文件進去Claude Code 就會多一個斜杠命令比如放一個review.md就能用/review喚起代碼審查流程。命令文件的開頭有一段 YAML 格式的 front matter用來配置元信息。一個最簡單的例子--- description: 審查當前分支的代碼改動 argument-hint: 可選指定審查范圍 ---說明文字后面就是命令正文。正文怎么寫直接決定了這個命令好不好用。我在實際使用中發(fā)現(xiàn)命令正文應(yīng)該具備三個特點第一命令正文里要有明確的角色設(shè)定。告訴 Agent 它現(xiàn)在扮演什么角色比如“你是一個資深前端工程師關(guān)注代碼的可維護性和性能”。角色設(shè)定能讓輸出風格更穩(wěn)定。第二命令正文里要有結(jié)構(gòu)化的輸出要求。比如“先輸出改動文件的列表再按文件逐個列出問題最后給出修改建議”。沒有結(jié)構(gòu)要求的命令很容易收到一段混亂的分析。第三命令正文要支持參數(shù)。Claude Code 的命令可以使用$ARGUMENTS這樣的占位符用戶在調(diào)用命令時輸入的內(nèi)容會原樣注入到命令正文里。2.3 settings.json行為邊界和權(quán)限控制Claude Code 讀取的配置除了 CLAUDE.md還有一個 settings.json。它在項目里的作用就是權(quán)限閘門。我見過不少用戶Claude Code 用了一段時間以后經(jīng)常抱怨 Agent“擅自改了不該改的文件”——問題就出在權(quán)限配置太寬松。settings.json 可以設(shè)置 allow、deny、requireApproval 等規(guī)則比如只允許自動讀寫 src 目錄下的文件遇到刪除操作必須先征求用戶同意。我維護模板時每套配置都會附一份最小可用的 settings.json{ permissions: { allow: [ Read, Edit, Glob, Bash(npm run test) ], deny: [ Bash(rm -rf .*), Edit(lock.json) ], requireApproval: [ Write, Bash(git push) ] } }這里的寫法只是示意不同版本的 Claude Code 對權(quán)限字段的命名可能有差異但思路是一致的把高風險操作用 deny 攔死把普通寫操作用 requireApproval 卡一道人工確認。3. 實操三個高價值模板的完整寫法這一部分我直接把我模板庫里最有生命力的三個命令文件拿出來拆解。它們的共同特點是結(jié)構(gòu)簡單、適用范圍廣、幾乎每周都會用到。3.1 新模塊腳手架模板寫新模塊是使用頻率最高的場景。沒有模板的時候我每次都要說一遍項目背景、模塊職責、文件放哪里、接口怎么導(dǎo)出。有了模板之后我只需要敲/scaffold然后跟上模塊名稱。命令文件內(nèi)容大概是這樣的--- description: 生成一個新模塊的腳手架 argument-hint: 模塊名稱例如 utils/format --- 你是一個熟悉當前代碼庫的資深開發(fā)者。 請根據(jù)用戶提供的模塊路徑完成以下步驟 1. 在 src 目錄下創(chuàng)建對應(yīng)的文件夾和入口文件入口文件命名為 index.js。 2. 根據(jù)模塊功能生成注釋塊內(nèi)容包括模塊用途、作者、創(chuàng)建日期、依賴關(guān)系。 3. 創(chuàng)建類型定義文件如果項目使用 TypeScript。 4. 在模塊目錄下創(chuàng)建一個 README.md寫清模塊的使用方法。 5. 不修改任何已有文件不需要寫測試除非用戶明確要求。 模塊路徑$ARGUMENTS 注意 - 請先閱讀項目的 CLAUDE.md遵循既有命名規(guī)范。 - 文件路徑必須嚴格基于用戶提供的模塊路徑解析不要自行改變目錄結(jié)構(gòu)。這份模板的精髓在于最后那條“不修改已有文件”。很多 Agent 在生成新模塊時會順手改點別的把已有代碼弄得面目全非。加上這條約束以后執(zhí)行就老實多了。3.2 代碼審查模板代碼審查模板是我個人最喜歡的一個命令。Claude Code 讀完代碼以后如果能按固定的框架輸出審查意見價值會比泛泛而談大得多。--- description: 對當前改動進行代碼審查 argument-hint: 可指定文件路徑默認審查全部改動 --- 你是一名資深代碼審查者請嚴格按以下步驟執(zhí)行 第一列出本次改動的文件清單并用表格展示每個文件的改動行數(shù)。 第二逐文件審查以下維度 - 邏輯正確性是否存在邊界條件遺漏 - 安全性是否存在注入、越權(quán)、敏感信息泄露風險 - 可維護性命名是否清晰職責是否單一 - 性能是否存在無意義循環(huán)、重復(fù)計算、內(nèi)存泄漏 第三對每個問題標注嚴重等級 - P0必須修復(fù)可能導(dǎo)致線上故障 - P1建議修復(fù)長期會有隱患 - P2可選優(yōu)化不影響當前功能 第四輸出總結(jié)說明當前改動是否可以直接合并。 審查范圍$ARGUMENTS用了一段時間以后我把嚴重等級的分類也寫進了模板效果非常直觀。P0 級別的問題 Agent 基本都能抓出來比如空指針、未捕獲的異常、明顯越權(quán)操作反而是一些命名混亂、邏輯繞彎的問題需要人工盯一盯。3.3 測試生成與重構(gòu)模板測試模板我做成自適應(yīng)模式如果用戶給了文件路徑就只針對該文件生成測試如果沒有給路徑就自動掃描最近修改的文件。這樣做的好處是不需要維護多個命令文件一個命令覆蓋了“補測某個函數(shù)”和“補測剛改完的一片代碼”兩種需求。--- description: 為指定文件或最近改動生成單元測試 argument-hint: 可選目標文件路徑 --- 你是一個熟悉開源技術(shù)棧的測試工程師。 請根據(jù)用戶指定文件或最近改動的文件生成一份完整的單元測試文件。 要求 1. 測試文件放在與被測文件相同的目錄下命名為 原文件名.test.js。 2. 覆蓋以下場景正常輸入、邊界輸入、異常輸入。 3. 使用項目已有的測試框架和斷言庫不要引入新依賴。 4. 對 Mock 的使用加注釋說明為什么需要 Mock。 目標文件$ARGUMENTS 生成完成后運行項目的測試命令確認新測試全部通過如果失敗主動修復(fù)測試代碼直到通過。特別注意最后一行要求 Agent 主動跑測試直到通過。如果不寫這一句Agent 經(jīng)常只生成測試代碼卻不驗證等于把問題從編寫階段推到了驗收階段。很多用戶沒注意到這些命令是支持“遞歸復(fù)用”的模板里可以指定先執(zhí)行項目已有的其他命令再執(zhí)行當前邏輯。比如重構(gòu)模板的開頭就可以寫成“先執(zhí)行/review再根據(jù)審查結(jié)果進行重構(gòu)”。4. 從零搭建一個模板倉庫目錄結(jié)構(gòu)、命名規(guī)范與迭代方式4.1 推薦目錄結(jié)構(gòu)和命名規(guī)范我當前維護的 claude-code-templates 目錄結(jié)構(gòu)如下claude-code-templates/ ├── README.md ├── CLAUDE.md ├── .claude/ │ ├── settings.json │ └── commands/ │ ├── scaffold.md │ ├── review.md │ ├── test.md │ ├── refactor.md │ ├── commit.md │ └── init.md ├── project-templates/ │ ├── node-lib/ │ ├── react-component/ │ └── cli-tool/ └── docs/ ├── best-practices.md └── troubleshooting.md命名上我堅持三條規(guī)則命令文件名必須用小寫英文動詞一個命令一個動詞不要出現(xiàn)review_and_fix.md這種復(fù)合詞。原因很簡單斜杠命令本身就是快捷鍵快捷鍵要短復(fù)合詞會拖慢輸入速度。每個命令文件必須有 description。沒有 description 的命令不會出現(xiàn)在斜杠命令菜單里而且還容易把自己繞暈。命令內(nèi)部段落用“第一、第二、第三”或者編號列表不要用含糊的“盡可能”“盡量”這類詞。模板是給 Agent 看的Agent 對模糊指令的理解遠不如對明確步驟的理解。4.2 模板設(shè)計的三條原則第一短小。命令正文不要超過兩百行。Claude Code 每次調(diào)用模板模板內(nèi)容都會算進上下文窗口。模板越長讀完模板以后留給實際代碼分析的令牌就越少回答質(zhì)量會肉眼可見地下降。第二明確。把“做什么”和“不做什么”都寫清楚。我見過太多人寫模板只寫正面要求忘了寫邊界結(jié)果 Agent 總是跑偏。比如你讓它“改進這段代碼”它可能連業(yè)務(wù)邏輯都給你改了但如果你加上“只優(yōu)化性能不改變對外接口”結(jié)果立刻收斂。第三可組合。每一個模板盡量只做一件事但允許調(diào)用其他模板。比如測試模板可以通過$ARGUMENTS指定目標文件也可以從重構(gòu)模板的流程里被調(diào)用腳手架模板生成完文件以后可以提示用戶順手執(zhí)行/test補測試。把大模板拆成小模板再組合維護成本會斷崖式下降。4.3 如何用模板初始化一個真實項目這里我拿 project-templates/node-lib 這個目錄舉個例子。它不是一個單純的命令文件而是整套腳手架一份完整的 package.json、一個精簡的目錄結(jié)構(gòu)、一個可以直接當模板用的 CLAUDE.md。用這個腳手架初始化項目時我執(zhí)行的是/init命令命令正文會讓 Claude Code 先讀取 project-templates/node-lib 下的所有文件然后按以下步驟工作復(fù)制整個模板目錄到用戶指定的新項目路徑。修改 package.json 中的項目名、版本號和描述。根據(jù)用戶對項目用途的說明更新 README.md。刪除模板目錄里無用的示例代碼。在新目錄中生成核心入口文件并跑通一次測試。整個過程大概不到一分鐘。如果沒有這套腳手架光是手工建目錄、寫 package.json、配 eslint 就能耗掉快半小時。把“項目初始化”模板化是我覺得投入產(chǎn)出比最高的決定。5. 高頻問題排查和調(diào)試實錄模板系統(tǒng)用久了一定會碰到各種問題。我把在真實項目里踩過的坑按頻率列出來對照排查思路一起講。5.1 命令沒出現(xiàn)在斜杠命令菜單里這是新手最常遇到的第一道坎。文件放進.claude/commands/以后輸入/卻看不到命令大概率是三個原因一是擴展名不對。Claude Code 的命令文件必須使用.md擴展名如果你放了個.txt或者.markdown它不會被識別。二是 front matter 格式不規(guī)范。description字段必須寫在最頂部而且要在兩個---中間。如果缺少結(jié)束的---整個命令會被當成純文本仍然不會出現(xiàn)在菜單里。三是目錄權(quán)限問題。某些系統(tǒng)上.claude目錄沒有正確創(chuàng)建或者放在 Shopify 這類靜默忽略目錄的位置。檢查路徑是不是在項目真實根目錄下。排查技巧很簡單打開 Claude Code 的調(diào)試輸出輸入/看菜單列表如果列表里沒有你的命令再用命令行的ls -la .claude/commands確認文件確實存在且權(quán)限可讀。5.2 Agent 執(zhí)行時忽略模板約束模板寫得清楚但 Agent 就是不照著做這個問題也很多人問過。實際上模板約束被忽略通常不是 Cluade Code 不聽話而是約束在整套提示詞體系里優(yōu)先級太低。Agent 的指令優(yōu)先級排序大概是這樣的用戶當前輸入 命令文件正文 項目 CLAUDE.md 全局 CLAUDE.md 模型內(nèi)置偏好。如果你的模板里寫著“不要修改已有文件”但項目 CLAUDE.md 里寫著“根據(jù)實際情況靈活調(diào)整”Agent 就會傾向于在沖突時選擇更靈活的那一條。所以排查思路是檢查是不是在 CLAUDE.md 里寫了和模板互斥的規(guī)則把模板里最關(guān)鍵的約束也提煉到 CLAUDE.md 的業(yè)務(wù)規(guī)則部分讓它升到更高優(yōu)先級。我早期吃過幾次虧之后養(yǎng)成了把最重要約束同步寫到兩個文件里的習慣這樣 Agent 無論如何都會讀到。5.3 上下文窗口被撐爆模板是上下文消耗大戶尤其是喜歡把示例、歷史命令、完整項目結(jié)構(gòu)都塞進模板的用戶。一旦出現(xiàn)“代碼分析到一半前面的指令被模型忽略”的情況多半是上下文滿了。解法有幾個第一模板里只保留和當前需求強相關(guān)的信息通用規(guī)范交給 CLAUDE.md。 第二設(shè)置模板的 allowed-tools 字段限制命令只能調(diào)用特定工具避免 Agent 無謂地讀取大量文件。 第三用 README 文檔的引用替代模板內(nèi)嵌長文本讓 Agent 按需閱讀。Claude Code 支持在 CLAUDE.md 中用路徑引用其他文檔模板也可以用同樣的方式鏈接到細節(jié)文檔而不是把全部內(nèi)容塞進命令正文。5.4 權(quán)限配置過于寬松或過于嚴格配置權(quán)限是一個典型的“既要又要”問題。allow 列表開得太寬Agent 容易誤操作開得太窄Agent 連讀文件都要反復(fù)確認效率為零。我的經(jīng)驗是分階段配置。模板初始化階段只允許讀文件和寫模板文件項目運行階段把測試命令加入 allow 列表提交階段把 git 相關(guān)操作設(shè)為 requireApproval。模板維護者應(yīng)該默認“最小權(quán)限”發(fā)現(xiàn)某個操作頻繁需要人工確認再把該操作提升到自動通過。下面這張問題排查表是我整理模板庫時隨手寫下的直接放在 docs/troubleshooting.md 里遇到問題時比搜索引擎快得多癥狀大概率原因處理方式斜杠命令不出現(xiàn)文件擴展名或 front matter 錯誤檢查 .md 后綴和 --- 分隔符命令執(zhí)行到一半就停上下文窗口溢出精簡模板縮短中毒分析范圍Agent 不遵循禁止項模板約束優(yōu)先級低于 CLAUDE.md把關(guān)鍵約束同步到 CLAUDE.md工具權(quán)限頻繁被拒settings.json 權(quán)限列表過窄擴大 allow 列表或設(shè)置 requireApproval輸出結(jié)果格式不統(tǒng)一模板缺少結(jié)構(gòu)化輸出要求在模板里指定輸出步驟和標題層級5.5 “參數(shù)注入”出錯的特殊場景還有一個隱蔽的坑$ARGUMENTS變量在使用中文時會遇到編碼問題尤其是在 Windows 終端下。如果你發(fā)現(xiàn)模板里注入的參數(shù)出現(xiàn)亂碼最直接的辦法是改用交互式確認——在命令正文里要求 Agent 先向用戶確認參數(shù)內(nèi)容再繼續(xù)執(zhí)行。這樣雖然多一步交互但能避開整座編碼兼容性的暗礁。6. 維護模板庫的幾條經(jīng)驗心得6.1 不要一上來就想搞完整體系第一次做模板庫的人很容易犯的一個錯是“力圖全面”。又是代碼審查模板又是架構(gòu)評審模板又是安全審計模板目錄建了十幾個真正用過的不超過兩個。我自己的經(jīng)驗是先挑三個最高頻的動作做成模板用一個月把這三份打磨到“閉著眼睛用都不會翻車”再開始擴充。模板庫是長出來的不是設(shè)計出來的。6.2 模板版本控制和團隊共享模板庫本身是我用 git 維護的每次修改都寫清楚 commit message比如“review 模板增加日志輸出檢查項”。這樣以后某一次改動導(dǎo)致工程質(zhì)量下降可以回溯到具體改動點而不是靠記憶。團隊協(xié)作時我把模板庫和項目倉庫分開管理項目倉庫通過 git submodule 或者直接復(fù)制的方式引用模板。直接復(fù)制的好處是項目模板不會被遠程更新打亂壞處是沒法同步升級submodule 則反過來。我個人的偏好是核心命令模板用 submodule項目腳手架代碼直接復(fù)制因為腳手架每次生成項目后一般不會再改。6.3 定期做一次“模板清理”模板也有保質(zhì)期?？蚣苌?、目錄重構(gòu)、工作流調(diào)整都會讓舊模板的部分內(nèi)容失效。我每個季度會做一次模板體檢把每個命令文件從頭讀一遍問自己三個問題——現(xiàn)在還會用這個命令嗎里面的路徑和命令還能跑通嗎有沒有更好的寫法把回答不出來的模板直接刪掉。寧可只有一個用得精的模板也不要十個躺在倉庫里發(fā)霉的模板。6.4 模板庫的最佳狀態(tài)是“可增減”我用下來的體會是Claude Code 的模板系統(tǒng)真正厲害的地方不在于幫你省打字而在于把“人的經(jīng)驗”沉淀成“Agent 的行為模式”。你可以在不同項目間快速切換風格新人也能靠一套模板很快融入已有項目的開發(fā)節(jié)奏。從效率賬來看我最常用的三個模板scaffold、review、test平均每周使用超過二十次每個模板幫我省下大約三到五分鐘的需求描述時間每周就是兩小時左右。更關(guān)鍵的是輸出質(zhì)量穩(wěn)定了同一個需求不會因為狀態(tài)波動時而生成得好、時而生成得差。6.5 最后分享一個小技巧如果你和我一樣經(jīng)常要同時維護多個項目可以在用戶級配置目錄~/.claude/CLAUDE.md里放一份全局規(guī)范把“讀代碼前先讀 README”“提交信息用中文”“小步提交”這類通用于所有項目的規(guī)則寫進去然后項目級 CLAUDE.md 只放該項目獨有的配置。這樣你的模板庫就可以進一步瘦身凡是通用的行為約束不需要塞進每一個命令文件Agent 會自己從全局規(guī)范里讀取。做模板這事不復(fù)雜但確實需要耐心。我最早一份 command 文件前前后后改了四個版本才把指令精簡到既不啰嗦又能穩(wěn)定輸出預(yù)期結(jié)果。建議拿到模板的你也先以“給項目增加一個每日必用命令”為目標跑通一次完整流程再回來慢慢演進成自己的成套模板體系。