如何設計 .claude 文件夾？一篇文搞懂 agents、commands、hooks 到 rules

小宙的Prompt Labs研究室

大家好,我是AI小宙!

如果你有在使用 Claude Code 來開發程序或工具，那你一定要知道如何妥善安排 Claude Code 文件夾。我是小宙，這裏我想直接告訴你：如果你從來沒了解過 .claude 文件夾，那你只用了 Claude Code 10% 的能力而已。

我們可以通過一個結構化的 .claude/ 文件夾，讓你把規則、習慣、工作流程“記錄下來”，讓 Claude 每次都能精準按照你的方式工作。這篇文章，我將帶你逐一瞭解 .claude/ 文件夾底下每個目錄的用途，並附上實際範例，讓你馬上可以套用。

agents - 你的 AI 專屬團隊

一般人使用 Claude Code，就是一個 AI 幫你做所有事。Agents 是你自定義的 AI 助理，每一個都有自己的角色設定、可用的工具和行為規則等等。

當 Claude 遇到符合的任務，它會自動把工作交給對應的 Agent 來處理，這就像一個主管把任務分配給不同的組員。雖然 Claude Code 本身就內置一些子代理，像是 Explore、Plan、general-purpose，Claude 會視任務情況自動委派。但這些內置子代理，職責在於幫 Claude 做比較通用型的工作。

而我們自己放在 .claude/agents/ 裏的，則是自定義子代理。和內置的子代理差別為，自定義的子代理更像是根據工作流程打造的專職同事。所以如果你希望不同任務有不同的“專家”來處理，這時候就需要自定義 Agents（子代理）。

Agents 怎麼使用？

在 .claude/agents/ 文件夾下，建立一個 .md 文件，並在最上方用 frontmatter 定義這個 Agent 的設定。例如，你可以做一個“註解整理專家”，專門把零散 feedback 改寫成可直接交付的內容：

子代理常見有這幾種觸發方式：

• 自動觸發：
  Claude 根據 description 的描述，判斷什麼時候應該交給這個 Agent
• 直接指定：
  在對話中說“請用 feedback-editor 幫我整理這份修改意見”
• @提及：
  手動輸入 @"feedback-editor (agent)"

commands - 你的自定義快捷指令

Commands 可以讓你把常用的工作流程包裝成一個指令，只要輸入 /指令名稱，Claude 就會按照你設定的步驟執行。這樣我們就不用每次都重新說明一長串流程，也不用擔心忘記步驟，一個指令搞定所有事。

commands 怎麼使用？

在 .claude/commands/ 文件夾下，建立一個 .md 文件，檔名就是指令名稱（例如：.claude/commands/explain-change.md）：

新增好之後，在對話框輸入 /explain-change src/cart.ts 即可使用。

hooks - 自動化你的工作流程

Hooks 是 Claude Code 的自動觸發機制，讓你在特定事件發生時，自動執行某些動作，不需要每次手動提醒 Claude。舉例來說，你可以設定：Claude 在準備提交 commit 前，自動先跑 lint 和 format；或是在 Claude 要執行某些關鍵指令前，先做額外檢查。

hooks 怎麼使用？

先來看一個實際的 hook 腳本。假設你希望 Claude 在準備提交 commit 前，先自動跑 lint 和 format，那你可以先建立 .claude/hooks/before-commit-check.sh：

這種寫法的好處是，真正的邏輯都放在 .sh 裏，之後要改檢查流程也很直觀。寫好腳本之後，再回到 .claude/settings.json 把它掛上去：

這段設定的意思是：當 Claude 準備執行 git commit 這類 Bash 指令前，先觸發 .claude/hooks/before-commit-check.sh，把 lint 和 format 跑完再繼續。

Hooks 的類型

Claude Code 的 Hook 類型其實很多，小宙為你整理了最常用、最容易上手的一批：

• PreToolUse:
   Claude 執行工具之前
• PostToolUse:
   Claude 執行工具之後
• SubagentStart:
   Claude 啓動子代理時
• SubagentStop:
   Claude 結束子代理時
• Stop:
   Claude 完成回覆時
• SessionStart:
   對話開始時
• Notification:
   Claude 需要你輸入時
• FileChanged:
   被監控的文件發生變化時

rules - 給 Claude 的行為準則

Rules 是你寫給 Claude 的“規定清單”，告訴它在這個項目裏應該怎麼寫代碼、什麼事情不能做、要遵守哪些規範。

小宙要提醒你注意一個細節：不是所有 rules 都是無腦全讀。

• 沒有 paths frontmatter 的 rules，會在一開始就載入
• 有 paths frontmatter 的 rules，只有在 Claude 真的處理到符合的文件時才載入

這也是 rules 很適合大型項目的原因，因為可以把上下文切得很精準，不會每次都把整包規範塞進來。

rules 怎麼使用？

我們只要在 .claude/rules/ 文件夾下，建立 .md 文件：.claude/rules/api.md 來描述你的規範即可。

這種 paths frontmatter 的好處是，只有當 Claude 真的碰到 API 相關文件時，這份規範才會被載入。也就是說，你可以把前端規範、後端規範、數據庫規範拆成不同文件，各自只在需要時出現，整體上下文會乾淨很多。

skills - 可重複使用的工作腳本

Skills 和 Commands 類似，都是讓你定義可呼叫的工作流程。不同的是，Skills 像是工作手冊，Claude Code 會在做相關工作時，自動讀取相關內容或規範，如果做不相關工作，就不讀取，不佔用 token，這也是 Claude Code 官方推薦的現代寫法。

每個 Skill 是一個文件夾，裏面放着 SKILL.md 作為主要設定檔，還可以附上範本、範例等補充資料。

skills 怎麼使用？

在 .claude/skills/ 下建立一個文件夾，並在裏面新增 SKILL.md。裏面可以放上 description，讓 Claude Code 知道什麼時候要使用這個 skill，比如說這個 .claude/skills/clarify-before-doing/SKILL.md：

settings.json - 項目權限與行為設定

settings.json 是 Claude Code 的設定檔，用來控制 Claude 可以做什麼、不可以做什麼，以及各種自動化行為。例如你可以限制 Claude 不能執行某些危險指令，也可以設定環境變量、調整 UI 主題等。

設定檔的位置

設定檔可以放在多個位置：

• ~/.claude/settings.json
   : 你個人的所有項目
• .claude/settings.json
   : 當前文件夾的項目（可提交到 git 共享）
• .claude/settings.local.json
   : 當前文件夾的項目（本機私用，不提交）

範例設定

比如我們可以允許 Claude Code 去讀取和修改文件，但是拒絕它執行危險操作（出於安全演示，已轉義潛在高危指令），就可以這樣寫：

前面提到的 Hook，也是一樣寫在這個 settings.json 裏，基本上 hooks/ 目錄放的是腳本本體，而 settings.json 裏是描述“什麼時候觸發哪一支腳本”。例如前面提到的提交前檢查，就可以像這樣掛：

{   

"hooks": {    

 "PreToolUse": [       

   {        

      "matcher": "Bash(git commit *)",       

      "hooks": [   

       {            

       "type": "command",             

    "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/before-commit-check.sh"          

       }        

      ]       

     }    

    ]   

   } 

  }

這對於團隊協作特別重要，可以在 .claude/settings.json 設定好規範，提交到 git，讓整個團隊的 Claude 行為一致。

CLAUDE.md - Claude 的核心大腦

CLAUDE.md 是整個 .claude/ 文件夾中最重要的一個文件。每次對話開始，Claude 都會優先讀取這個文件，把裏面的內容當作這個項目的“基礎知識”。

你可以在這裏寫下項目背景、常用指令、開發規範，讓 Claude 一開始就掌握所有必要的上下文。如果你想偷懶的話，也可以直接使用 /init 指令，讓 Claude 自動幫你生成一個 CLAUDE.md 的初始版本。

另外，官方現在也很鼓勵把 CLAUDE.md 維持精簡，必要時用 @path/to/file 的方式匯入其他說明文件。這樣可以保留核心規則在主檔，細節再拆出去，不容易越寫越肥。

以下是一個範例：

CLAUDE.md 可以放哪裏？

CLAUDE.md 和 settings.json 一樣，可以分為全局和項目限定的：

• ~/.claude/CLAUDE.md
   : 你個人的所有項目
• ./CLAUDE.md
   : 這個項目（通常提交到 git）

和 rules/ 的差別

那 CLAUDE.md 和 rules/ 有什麼差別呢？如果是小項目，單純用 CLAUDE.md 就非常夠，但是當項目越來越大，有越來越多相關規範，就可以考慮拆分出 rules/ 來更好地維護。

簡單說的話就是：CLAUDE.md 適合放“整個項目都該知道”的事情，而 rules/ 適合放“特定文件或特定領域才需要”的規則。

總結

.claude/ 文件夾就是你的 Claude Code 設定中心，讓你可以定製化自己的工作方式、流程，不用每次都重新說明。最後小宙為你簡單整理一下：

• agents/
   : 定義專屬的 AI 子代理
• commands/
   : 建立自定義快捷指令
• hooks/
   : 設定自動化工作流程觸發器
• rules/
   : 細分主題的行為規範
• skills/
   : 可複用的進階工作腳本
• settings.json
   : 權限控制與全局設定
• CLAUDE.md
   : 項目說明與開發規範

聯繫小宙 / 獲取完整AI學習手冊

END

❤️點贊、👀在看、➕關注

💠AI提示詞+AI深度學習資料，讓你深入瞭解技術核心，成為技術大神！