---
schemaVersion: 1
slug: gp-124-20260323-akshay-claude-folder-anatomy
ticketId: GP-124
lang: zh-tw
title: .claude/ 資料夾完全解剖 — 你的 AI 助手的大腦在哪裡
summary: 你知道 Claude 為什麼在這個 repo 表現好、換個 repo 就變笨嗎？秘密就在 .claude/ 資料夾裡。Akshay 拆解了整個結構：CLAUDE.md 三層架構、自訂指令、agent、permissions、還有那個你可能不知道存在的全域 ~/.claude/。
originalDate: 2026-03-22
translatedDate: 2026-03-23
source: "@akshay_pachaar on X"
sourceUrl: https://x.com/akshay_pachaar/status/2035341800739877091
author: null
authorshipNote: null
canonicalUrl: https://gu-log.vercel.app/posts/gp-124-20260323-akshay-claude-folder-anatomy
status: published
replacementTicketId: null
replacementUrl: null
---

# .claude/ 資料夾完全解剖 — 你的 AI 助手的大腦在哪裡

> **來源:** [@akshay\_pachaar on X](https://x.com/akshay_pachaar/status/2035341800739877091)

Claude 有失憶症。

不是比喻——是字面上的意思。每次開一個新的 terminal session，Claude 會把上一次學到的所有東西全部忘光。專案架構、coding style、deploy 流程、上次踩過的雷、已經達成的共識，全部歸零。

同一隻 Claude，在 repo A 表現得像資深同事，在 repo B 突然變成第一天來上班的菜鳥。

這不是 bug。這是 LLM 的本質——沒有持久記憶，每次對話都從零開始。問題是：有人解決了這個問題，而且解法藏在一個大多數人沒注意過的資料夾裡。

---

## 一個資料夾治好了失憶症

@akshay\_pachaar 拆解了 [Claude Code](https://gu-log.vercel.app/posts/gp-120-20260320-nyk-builderz-claude-code-codex-ai-agent-cli/) 的 `.claude/` 資料夾結構，但真正有意思的不是資料夾本身——是這套設計背後的哲學。

先講一個反直覺的事實：`.claude/` 不是一個，是兩個。

**專案層**（`repo/.claude/`）住在 repo 根目錄，設定只對這個專案有效。**全域層**（`~/.claude/`）住在家目錄，設定對所有 Claude 使用有效。兩層的關係跟 git 一模一樣——`.git/` vs `~/.gitconfig`。

> **Mogu murmur：**
>
> 這個「兩層」設計看起來理所當然，但 Akshay 沒提到的關鍵是：**大多數人只知道專案層，根本沒碰過全域層**。gu-log 這個 repo 就有 `.claude/` 資料夾，裡面有 tribunal scorer agent 和自訂指令——這篇文章本身就是在那套設定下寫出來的。但 gu-log 同時也有 `~/.claude/CLAUDE.md` 幫 ShroomDog 的所有 repo 統一偏好。少了任何一層，體驗都差一截。這不是 nice-to-have，是基本功。(⌐■\_■)

---

## CLAUDE.md 不只是 readme，是每次對話的第零句話

`.claude/` 裡面最重要的檔案是 `CLAUDE.md`。

但叫它「設定檔」不太精準。更準確的說法是：**每次 Claude 開始對話前，它會默默先讀完這份文件**。開發者在裡面寫什麼，Claude 就帶著那些知識開始工作。Tech stack、naming convention、哪些資料夾不能亂動、commit message 要用什麼語言——全部可以寫進去。

而且它有三層覆蓋機制：

```plaintext
~/.claude/CLAUDE.md          ← 全域（所有專案適用）
  └── repo/.claude/CLAUDE.md  ← 專案（這個 repo 適用）
         └── subdir/CLAUDE.md ← 子目錄（只對這個目錄有效）
```

下層覆蓋上層。全域 CLAUDE.md 說用 tabs，但某個 repo 說用 2 spaces？那個 repo 裡 Claude 就用 2 spaces。

> **Mogu 插嘴：**
>
> 三層覆蓋聽起來很工整，但 Akshay 忽略了一個實戰問題：**大多數人把 CLAUDE.md 當 README 在寫，塞了一堆 Claude 根本不需要知道的背景故事**。結果 context window 被無關資訊吃掉，真正重要的指令反而被沖到底部。CLAUDE.md 不是給人類讀的文件——是給 AI 的操作手冊。短、精準、可行動，比一篇好看的介紹文有用一百倍。(ง •̀\_•́)ง

那全域的 `~/.claude/CLAUDE.md` 該放什麼？放的是跟「人」有關的偏好，不是跟特定 repo 有關的東西：

```markdown
# 偏好
- 使用 zsh，不用 bash
- commit message 用繁體中文
- 不要過度工程化，最簡單能動的就好
- 不要在回覆最後加「希望有幫助」之類的客套話

# 工作環境
- SSH key 在 ~/.ssh/id_ed25519
- staging server 是 staging.myapp.com
```

設定一次，每個 repo 都生效。不用重複交代。

---

## 但 CLAUDE.md 只解決了一半的問題

到這裡為止，解決的是「Claude 不認識這個專案」的問題。但還有另一半：**Claude 每次都用同一種方式做事，沒辦法針對特定任務用特定流程**。

這就是 `.claude/commands/` 的價值——自訂 slash 指令。

在 `.claude/commands/` 裡放 Markdown 檔案，檔名就是指令名。`deploy.md` 變成 `/deploy`，`review-pr.md` 變成 `/review-pr`。每個檔案裡寫的是「執行這個指令時，Claude 該做什麼」的完整說明，可以帶參數（用 `$ARGUMENTS` 占位符）。

```plaintext
.claude/
└── commands/
    ├── deploy.md       → /deploy
    ├── review-pr.md    → /review-pr
    └── ralph-score.md  → /ralph-score
```

> **Mogu 碎碎念：**
>
> Akshay 把 commands 介紹得像一個 nice feature，但**這東西被嚴重低估了**。gu-log 的 `/ralph-score` 就是最好的例子：`.claude/commands/ralph-score.md` 裡面定義了評分標準、輸出格式、校準錨點。每次跑 `/ralph-score gp-124-xxx.mdx`，出來的是一致的、可比較的分數，不是看 Claude 今天心情給的隨機數字。
>
> 重點不是「可以自訂指令」這件事本身——重點是**把隱性知識變成可重複執行的流程**。沒有 command 檔，每次都要重新口頭解釋要怎麼做、標準是什麼。有了它，流程就固化了。這是從「跟 AI 聊天」到「管理 AI 工作流」的分界線。(๑•̀ㅂ•́)و✧

---

## 從指令到分身：[Agent](https://gu-log.vercel.app/glossary#agent) 才是真正的轉折

Commands 解決了「Claude 該怎麼做」，但一個更刺激的問題是：**如果一個 Claude 不夠用呢？**

`.claude/agents/` 讓開發者定義 sub-agent——每個都有自己的人格、工具權限、甚至指定不同的 model。格式是帶 frontmatter 的 Markdown：

```markdown
---
description: 這個 agent 的用途（讓主 agent 知道什麼時候叫它）
model: claude-opus-4-6
tools:
  - Read
  - Bash(grep:*)
---

這裡寫 agent 的系統提示和工作說明...
```

主 Claude 執行任務時，如果判斷需要專家，就 spawn 出對應的 sub-agent。關鍵在那個 `tools` 欄位——不是所有工具都開放，而是只給這個 agent 需要的最小權限。

> **Mogu 偷偷說：**
>
> 這裡是 Akshay 整個 thread 裡我唯一有不同意見的地方。他把 agent 跟 commands 放在同一個層級介紹，但**兩者的本質完全不同**。Command 是一個 prompt template，Claude 還是用同一個 identity 執行。Agent 是一個獨立的 identity——有自己的系統提示、自己的工具限制、甚至自己的 model。
>
> gu-log 的 `.claude/agents/ralph-scorer.md` 就是用 Opus 4.6（因為評分需要更強的判斷力），工具只有 Read 和 Bash 的 grep/cat——**沒有寫入權限**。它可以把文章批得體無完膚，但改不了一個字。這不是信不信任 AI 的問題，是爆炸半徑的問題。一個能讀不能寫的 agent，最壞的情況就是給了錯的分數；一個能讀能寫的 agent，最壞的情況是把 production 文章改爛了。ヽ(°〇°)ﾉ

---

## 安全閥：因為口頭叮嚀靠不住

到這裡出現了一個隱藏的問題：Claude 可以讀檔案、可以執行指令、可以 spawn agent——**權限管控在哪裡？**

答案是 `.claude/settings.json`：

```json
{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)",
      "Read",
      "Write"
    ],
    "deny": [
      "Bash(rm:*)",
      "Bash(curl:*)"
    ]
  }
}
```

同樣有全域版（`~/.claude/settings.json`）控制所有專案的預設行為。

> **Mogu 插嘴：**
>
> settings.json 是整個 `.claude/` 設計裡最不性感但最重要的檔案。Akshay 介紹了 allow/deny 的語法，但沒有點出核心洞見：**用 prompt 說「不要做 X」跟用 settings.json deny「X」是完全不同等級的可靠度**。
>
> [Prompt](https://gu-log.vercel.app/glossary#prompt) 指令是 soft constraint——Claude 「理解」了規則，但在複雜推理鏈裡可能遺忘或誤判。Settings.json 的 deny list 是 hard constraint——系統層面阻擋，不經過 model 判斷。這兩者的差別就像「跟員工說不要碰伺服器」vs「直接收回伺服器權限」。前者靠信任，後者靠架構。在 AI 自動化的場景裡，架構永遠勝過信任。┐(￣ヘ￣)┌

---

## 全域層的最後一片拼圖：Auto-Memory

`~/.claude/` 除了放 CLAUDE.md 和 settings.json，還有一個容易被忽略的功能：**auto-memory**。

[Claude Code](https://gu-log.vercel.app/glossary#claude-code) 會自動把它認為重要的資訊寫入 `~/.claude/` 的記憶檔案。下次開新對話時，這些記憶自動載入。記憶分四類：

- `user`——技術背景、工作習慣
- `project`——正在進行的專案狀態
- `feedback`——開發者給過的修正（「不要這樣做」「用那種方式」）
- `reference`——外部資源位置（[Linear](https://gu-log.vercel.app/glossary#linear) project、Grafana dashboard）

對話歷史也存在 `~/.claude/projects/`，用 `--resume` 旗標可以繼續之前的 context。

> **Mogu 插嘴：**
>
> Auto-memory 是個聰明但有陷阱的設計。聰明在：不需要手動維護 context 文件，Claude 自己做筆記。陷阱在：**Claude 決定什麼值得記、什麼不值得記**——而它的判斷力不見得比一個認真寫日誌的工程師好。
>
> 實戰經驗是：auto-memory 記住的東西大約七成有用、三成要清理。過時的專案狀態、記偏的技術偏好、不再正確的 API 端點——這些殘留記憶不會自己消失，堆久了反而會讓 Claude 做出基於過時資訊的判斷。**記憶不是寫了就好，定期清理才是真正的維護功夫。** (¬‿¬)

---

## 自動販賣機 vs 拿著手冊的同事

把所有東西拼起來，一個完整的 `.claude/` 長這樣：

```plaintext
repo/
├── .claude/
│   ├── CLAUDE.md           ← 專案操作手冊
│   ├── settings.json       ← 權限管控
│   ├── commands/
│   │   ├── deploy.md       ← /deploy 自訂指令
│   │   └── test-run.md     ← /test-run 自訂指令
│   └── agents/
│       └── code-reviewer.md ← 專屬 code review sub-agent
└── ...

~/
└── .claude/
    ├── CLAUDE.md           ← 個人跨 repo 設定
    ├── settings.json       ← 全域預設權限
    └── projects/           ← 對話歷史 + auto-memory
```

原作者 Akshay 用了一句話總結：

> “Most people use Claude like a vending machine. Power users use it like a coworker with a handbook.”

這句話精準到位。但值得再推一步——**handbook 不是寫一次就好的文件，而是一個持續演化的系統**。好的 CLAUDE.md 會隨著專案成長更新，commands 會隨著團隊流程固化，agents 會隨著任務複雜度增加。

`.claude/` 不是一個設定資料夾。它是開發者跟 AI 之間的介面合約——寫得越精確，AI 表現越穩定。失憶症沒有被「治好」，而是被 work around 了：既然每次都從零開始，那就確保每次的「零」已經站在很高的起點上。

> **Mogu OS：**
>
> 最後講一件 Akshay 完全沒提、但對於真正把 Claude Code 用到極致的人最重要的事：**`.claude/` 是可以 commit 進 repo 的**。這代表團隊裡每個人都能共享同一份 Claude 設定——新人 clone repo 之後，Claude 立刻知道這個專案的所有規矩。
>
> gu-log 的 `.claude/` 就在 git 裡，任何人 clone 這個 repo 都會拿到同一套 tribunal agents、同一組 commands、同一份 CLAUDE.md。這不只是個人效率工具——當整個團隊的 AI 助手都讀同一本手冊，「AI 生成的品質不一致」這個問題就從根源被解決了。這才是 `.claude/` 真正最大的價值。╰(°▽°)╯

## 延伸閱讀

- [GP-120: Claude Code vs Codex — AI agent CLI 工具大亂鬥](https://gu-log.vercel.app/posts/gp-120-20260320-nyk-builderz-claude-code-codex-ai-agent-cli/)
- [GP-121: Heynavtoor 說 AI dispatch 改變了他的工作流程](https://gu-log.vercel.app/posts/gp-121-20260320-heynavtoor-ai-claude-dispatch/)