整理你的 .claude/ 工作區

為什麼結構很重要

專案小的時候，一個 CLAUDE.md 加幾個設定檔就夠了。但隨著專案成長，指令會變得難以維護、工作流散落在錯的地方、資料夾慢慢變成有用設定和難以解釋的混亂混合物。

一個組織良好的 .claude/ 資料夾，讓 Claude 更容易被引導、被信任，也更容易在真實專案中擴展。

.claude/ 目錄全景

project-root/
├── CLAUDE.md                    # 專案級指引（每次 session 都會讀）
├── CLAUDE.local.md              # 個人覆蓋（不進 git）
└── .claude/
    ├── settings.json            # 權限、hooks、專案行為
    ├── settings.local.json      # 個人設定覆蓋（不進 git）
    ├── rules/                   # 專項規則（特定領域）
    │   ├── api-conventions.md
    │   └── testing-standards.md
    ├── commands/                 # 可複用的 prompt 工作流
    │   ├── review-pr.md
    │   └── write-tests.md
    ├── skills/                  # 打包的完整工作流
    │   └── deploy/
    │       └── SKILL.md
    └── agents/                  # 專用子 agent 設定

每一層負責什麼

CLAUDE.md — 專案的工作憲法

放每次 session 都需要的東西：

主要技術棧
高層架構
最重要的開發指令
廣泛適用的程式碼慣例
專案級警告或約束

不該放的：每個 bug 的細節、每次實驗的記錄、特定領域的深入規範。這些會把 CLAUDE.md 變成一坨低密度噪音。

rules/ — 專項規則

當 CLAUDE.md 開始顯得擁擠，就該拆：

不同模組需要不同指引（前端 vs 後端）
不同人有不同標準
團隊經常更新慣例
想按路徑限定規則作用域

commands/ vs skills/ — 輕量 vs 完整

	commands/	skills/
複雜度	一個檔案就夠	多步驟 + 配套文件
用途	輕量可複用任務	完整工作流程
範例	`review-pr.md`	`deploy/SKILL.md` + 腳本

判斷標準：如果一個 prompt 模板就能搞定 → command。如果需要多步驟流程、有前置條件、有驗收標準 → skill。

hooks/ — 自動執行的安全網

hooks 跟 commands 的差別：hooks 自動跑，commands 手動觸發。

hooks 適合：

攔截危險操作（如阻止 rm -rf）
清理或驗證輸出（如自動跑 linter）
強制執行工作流要求（如 commit 前跑測試）

漸進式成長路徑

不要一開始就填滿所有資料夾。 按需增加：

階段	你遇到的問題	該加什麼
起步	剛開始用 Claude Code	`CLAUDE.md` + `settings.json`
指令膨脹	CLAUDE.md 太長了	加 `rules/` 拆分專項規則
需要自動化	每次都忘記跑測試	加 hooks
prompt 重複	每次都重新解釋同一件事	加 `commands/`
工作流變深	任務有多步驟 + 驗收條件	加 `skills/`
需要專精角色	某些任務需要不同的 agent 設定	加 `agents/`

常見錯誤

1. 把所有東西都塞進 CLAUDE.md

CLAUDE.md 每次 session 都會被讀取，內容越多 → token 越貴 → 重點越容易被稀釋。只放「每次都需要」的東西，其他拆進 rules/ 或 skills/。

2. skill 裝太多

能力不是堆出來的。skill 太多反而讓 Claude 注意力分散，不知道該觸發哪個。關鍵是高頻、穩定、邊界清晰。

3. 團隊設定和個人設定混在一起

判斷標準：如果設定幫整個團隊更一致地工作 → 放專案級（進 git）。如果主要反映一個人的偏好 → 放 .local 檔案（不進 git）。

4. 沒有命名規範

format-edits.sh 好過 script1.sh。名稱要能一眼看出用途。

5. 忘記漸進式成長

一開始就建好所有資料夾，裡面卻空空的。等真的需要時再加，每一層都有明確用途。

AI 協作：學了這個，跟 AI 怎麼配合？

組織好 .claude/ 目錄，本質上是在「教 AI 怎麼跟你合作」。結構越清晰，AI 越不容易迷路。

你的人類優勢：

判斷哪些規則需要「每次都讀」，哪些只需要「被搜尋到時才讀」
決定團隊共享 vs 個人偏好的邊界

可以這樣跟 AI 說：

「我的 CLAUDE.md 已經超過 200 行了。請幫我分析哪些內容適合留在 CLAUDE.md，哪些應該拆到 rules/ 裡。列出建議的拆分方案。」