如何設計 .claude 文件夾？一篇文搞懂 agents、commands、hooks 到 rules
整理版優先睇
掌握 .claude 文件夾設定，發揮 Claude Code 嘅全部潛力
呢篇文章由 AI 小宙撰寫，佢想話畀大家知 .claude/ 文件夾點樣幫你發揮 Claude Code 嘅真正威力。作者指出，好多人用 Claude Code 只用到一成能力，因為佢哋唔識得設定 agents、commands、hooks、rules 等自訂元件。文章嘅整體結論係：透過結構化嘅 .claude/ 文件夾，你可以將規則、習慣同工作流程「記錄落嚟」，令 Claude 每次都按照你嘅方式精準工作。
小宙逐一拆解每個目錄嘅用途：agents 係自訂 AI 助理，可以分工合作；commands 係快捷指令，將流程打包成一個指令；hooks 係自動觸發機制，例如提交前自動執行檢查；rules 係行為準則，可以按檔案路徑分開載入；skills 係可重用工作腳本，做法比 commands 更現代；settings.json 控制權限同自動化行為；CLAUDE.md 係核心大腦，每次對話優先讀取。
最後佢總結：.claude/ 文件夾係 Claude Code 嘅設定中心，幫你慳返好多重複說明嘅時間。文章仲附有實際範例，讀者可以即時套用。
- 自訂 agents 可以創建專屬 AI 助理，根據 description 自動觸發或手動叫用，提升分工效率。
- commands 用 / 快捷指令包裝常用流程，唔使每次重複說明，例如 /explain-change 可自動解釋程式碼變更。
- hooks 實現自動化，例如喺 commit 前執行 lint/format，透過 settings.json 掛載 .sh 腳本。
- rules 支援 paths frontmatter，按檔案路徑決定載入時機，適合大型項目精簡上下文。
- CLAUDE.md 係項目基礎知識，每次對話優先讀取；建議保持精簡，必要時用 @ 匯入外部檔案。
自訂 AI 助理同快捷指令
一般用 Claude Code，得一個 AI 幫你做曬所有嘢。但 agents 可以讓你自訂唔同角色嘅子代理，每個都有特定工具同行為規則。Claude 會根據 description 判斷邊個 agent 適合處理當前任務，就好似主管派工咁。自訂 agents 放喺 .claude/agents/，用 frontmatter 定義設定，例如可以做個「註解整理專家」專門執拾 feedback。
自訂 agents 有三種觸發方式：自動觸發、直接指定、@提及
commands 就係將常用流程包裝成一個指令，輸入 /指令名稱就搞掂。放喺 .claude/commands/，例如 .claude/commands/explain-change.md，入面寫低步驟，之後打 /explain-change 就可以用。咁就唔使每次都重複講成串流程，仲唔怕漏咗步驟。
自動化工作流程嘅 hooks
Hooks 係自動觸發機制，等你可以喺特定事件發生時自動執行動作。例如你想喺提交 commit 前自動跑 lint 同 format，就寫個 .sh 腳本放喺 .claude/hooks/，然後喺 settings.json 度掛上去。
PreToolUse hook：Claude 執行工具之前觸發，適合做驗證或檢查
小宙整理咗幾款常用 hook 類型：PreToolUse、PostToolUse、SubagentStart、SubagentStop、Stop、SessionStart、Notification、FileChanged。例如用 PreToolUse 配合 matcher，淨係喺執行 git commit 嘅時候先觸發檢查腳本，非常靈活。
行為準則同可重用工作腳本
Rules 係你寫畀 Claude 嘅「規定清單」，話畀佢知喺呢個項目入面應該點寫 code、唔準做咩、要遵守咩規範。其中一個重要細節：有 paths frontmatter 嘅 rules 只會喺 Claude 處理相關檔案時先載入，唔會一開始就塞曬所有規則，好啱大型項目用。
Rules 支援 paths frontmatter，可將前端、後端、數據庫規範拆成獨立檔案，按需載入
Skills 同 commands 類似，但係更現代嘅做法。每個 skill 係一個文件夾，入面有 SKILL.md 做主設定，可以加埋範本、範例等。Claude Code 會喺做相關工作時自動讀取 skill，唔關事嘅時候就唔佔 token。
# SKILL
## description
當用戶要求執行複雜任務時，先確認範圍再開始，避免誤解。
## steps
1. 詢問用戶目標同限制
2. 總結理解並請用戶確認
3. 確認後先執行全局設定與核心大腦
settings.json 控制 Claude 可以做咩、唔可以做咩，仲有自動化行為。可以放喺 ~/.claude/settings.json（個人全域）、.claude/settings.json（項目共享）、.claude/settings.local.json（本機私用）。例如你可以限制 Claude 唔準執行危險指令，或者設定環境變數。
settings.json 可以分別放喺三個層級：個人、項目共享、本機私用，方便團隊協作
CLAUDE.md 係最重要嘅文件，每次對話開始 Claude 會優先讀取。你喺度寫低項目背景、常用指令、開發規範。如果你懶得寫，可以用 /init 指令叫 Claude 自動生成。官方建議 CLAUDE.md 保持精簡，必要時用 @path/to/file 匯入其他說明文件。
小宙嘅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 都係無腦全讀。
沒有 pathsfrontmatter 嘅 rules，會喺一開始就載入有 pathsfrontmatter 嘅 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深度學習資料，等你深入瞭解技術核心，成為技術大神！
小宙的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 都是無腦全讀。
沒有 pathsfrontmatter 的 rules，會在一開始就載入有 pathsfrontmatter 的 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深度學習資料，讓你深入瞭解技術核心，成為技術大神！