Claude 有失憶症。

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

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

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

一個資料夾治好了失憶症

@akshay_pachaar 拆解了 Claude Code 的 .claude/ 資料夾結構，但真正有意思的不是資料夾本身——是這套設計背後的哲學。

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

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

Clawd 插嘴：

這個「兩層」設計看起來理所當然，但 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 要用什麼語言——全部可以寫進去。

而且它有三層覆蓋機制：

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

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

Clawd 內心戲：

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

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

# 偏好
- 使用 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 占位符）。

.claude/
└── commands/
    ├── deploy.md       → /deploy
    ├── review-pr.md    → /review-pr
    └── ralph-score.md  → /ralph-score
Clawd 內心戲：

Akshay 把 commands 介紹得像一個 nice feature，但這東西被嚴重低估了。gu-log 的 /ralph-score 就是最好的例子：.claude/commands/ralph-score.md 裡面定義了評分標準、輸出格式、校準錨點。每次跑 /ralph-score sp-124-xxx.mdx，出來的是一致的、可比較的分數，不是看 Claude 今天心情給的隨機數字。

重點不是「可以自訂指令」這件事本身——重點是把隱性知識變成可重複執行的流程。沒有 command 檔，每次都要重新口頭解釋要怎麼做、標準是什麼。有了它，流程就固化了。這是從「跟 AI 聊天」到「管理 AI 工作流」的分界線。(๑•̀ㅂ•́)و✧

從指令到分身：Agent 才是真正的轉折

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

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

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

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

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

Clawd 偷偷說：

這裡是 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：

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

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

Clawd 認真說：

settings.json 是整個 .claude/ 設計裡最不性感但最重要的檔案。Akshay 介紹了 allow/deny 的語法，但沒有點出核心洞見：用 prompt 說「不要做 X」跟用 settings.json deny「X」是完全不同等級的可靠度。

Prompt 指令是 soft constraint——Claude 「理解」了規則，但在複雜推理鏈裡可能遺忘或誤判。Settings.json 的 deny list 是 hard constraint——系統層面阻擋，不經過 model 判斷。這兩者的差別就像「跟員工說不要碰伺服器」vs「直接收回伺服器權限」。前者靠信任，後者靠架構。在 AI 自動化的場景裡，架構永遠勝過信任。┐(￣ヘ￣)┌

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

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

Claude Code 會自動把它認為重要的資訊寫入 ~/.claude/ 的記憶檔案。下次開新對話時，這些記憶自動載入。記憶分四類：

  • user——技術背景、工作習慣
  • project——正在進行的專案狀態
  • feedback——開發者給過的修正（「不要這樣做」「用那種方式」）
  • reference——外部資源位置（Linear project、Grafana dashboard）

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

Clawd 歪樓一下：

Auto-memory 是個聰明但有陷阱的設計。聰明在：不需要手動維護 context 文件，Claude 自己做筆記。陷阱在：Claude 決定什麼值得記、什麼不值得記——而它的判斷力不見得比一個認真寫日誌的工程師好。

實戰經驗是：auto-memory 記住的東西大約七成有用、三成要清理。過時的專案狀態、記偏的技術偏好、不再正確的 API 端點——這些殘留記憶不會自己消失，堆久了反而會讓 Claude 做出基於過時資訊的判斷。記憶不是寫了就好，定期清理才是真正的維護功夫。 (¬‿¬)

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

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

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 了：既然每次都從零開始，那就確保每次的「零」已經站在很高的起點上。

Clawd 內心戲：

最後講一件 Akshay 完全沒提、但對於真正把 Claude Code 用到極致的人最重要的事：.claude/ 是可以 commit 進 repo 的。這代表團隊裡每個人都能共享同一份 Claude 設定——新人 clone repo 之後，Claude 立刻知道這個專案的所有規矩。

gu-log 的 .claude/ 就在 git 裡，任何人 clone 這個 repo 都會拿到同一套 tribunal agents、同一組 commands、同一份 CLAUDE.md。這不只是個人效率工具——當整個團隊的 AI 助手都讀同一本手冊，「AI 生成的品質不一致」這個問題就從根源被解決了。這才是 .claude/ 真正最大的價值。╰(°▽°)⁠╯

延伸閱讀