Skip to main content
這頁是 Part IV 的地圖Part IV（04-0 到 04-11）涵蓋 Claude Code 的整個客製化層。這一頁的任務是先給你全局：.claude 目錄下每個檔案與資料夾各是什麼、何時載入、要不要提交版控。有了這張地圖，後面 04-1 到 04-11 逐機制深入時才不會迷路。與 02-6 的分界：本頁是 Claude 自家 .claude/ 目錄的完整參考；02-6 是跨工具對照（Claude vs Codex vs Antigravity vs Copilot）。想知道「Codex 的同等設定在哪」去 02-6，想知道「這個 .claude/ 裡的檔案是什麼」查本頁。補充五個無專篇主題：output-styles、keybindings、themes、workflows、agent-memory 在 Part IV 沒有獨立單元，本頁第 5 節補到可操作。

​
學習目標

  • 能說出 .claude/ 目錄下每個檔案與資料夾的用途、載入時機，以及該提交還是該 gitignore。
  • 能分辨哪些檔案在專案根（CLAUDE.md、.mcp.json、.worktreeinclude）而非 .claude/ 內。
  • 能設定 output-styles、keybindings、themes 這三個個人化面，並說出 workflows 與 agent-memory 的存放位置。
  • 能把任一檔案對應到它的深讀單元，知道要查細節時去哪一篇。
時效聲明目錄結構與檔名查證截至 2026-06，來源為官方互動式目錄頁 code.claude.com/docs/zh-TW/claude-directory [1] 與各對應主題頁。Claude Code 改版頻繁，動手前以官方當前頁為準。

​
互動式目錄全覽

點選左側任一項目，右側顯示該檔案的用途、載入時機與操作提示。切換上方的 Project 與 Global 標籤分別查看專案層與使用者層。

​
1. 先分清三個位置家族

.claude 相關的檔案散在三個地方，先釘住這個分界，後面逐項才不會錯位： 最常踩的錯是把 CLAUDE.md、.mcp.json 當成 .claude/ 裡的檔案。它們在專案根，不在 .claude/ 內 [1]。

​
2. 五個目前沒有專門單元的主題

Part IV 的 04-1 到 04-11 各有深寫單元，以下五個例外，這裡補到可操作。

​
2.1 output-styles：改寫系統提示的工作模式

output style 是附加到系統提示的一段文字，預設會替換掉內建的軟體工程任務指令，用來把 Claude Code 調成寫程式以外的用途（教學、審查模式）[2]。
  • 內建四種：Default、Proactive、Explanatory、Learning。
  • 自訂：放 ~/.claude/output-styles/<name>.md（個人）或 .claude/output-styles/（專案共享）。frontmatter 欄位：name、description、keep-coding-instructions（預設 false；設 true 保留內建任務指令）、force-for-plugin（plugin 專用）。
  • 選用：/config 選 Output style，或在 settings.json 設 outputStyle key。系統提示在 session 起始固定（為了快取），改後要 /clear 或開新 session 才生效。

​
2.2 keybindings：自訂快捷鍵

~/.claude/keybindings.json 重綁互動式 CLI 的鍵（需 v2.1.18+）[3]。
  • 格式：{ "bindings": [{ "context": "Chat", "bindings": { "ctrl+e": "chat:externalEditor", "ctrl+u": null } }] }。設 null 解除綁定，支援 chord（空格分隔的連按）。
  • context 分多種（Global、Chat、Autocomplete、Settings 等），綁定限定在特定介面區域。
  • 保留鍵不可重綁：Ctrl+C、Ctrl+D、Ctrl+M、Caps Lock。
  • 用 /keybindings 建立或開檔（附 schema），/doctor 會顯示綁定衝突警告。改動自動偵測、熱重載。

​
2.3 themes：自訂配色

~/.claude/themes/<name>.json 定義主題，內容是一個內建 base preset 加一組 overrides 色票 [1]。用 /theme 互動建立或手寫 JSON；選了自訂主題後偏好存成 custom:<slug>。讀取於 session 起始並熱重載。

​
2.4 workflows：動態多代理腳本

.claude/workflows/<name>.js（專案）或 ~/.claude/workflows/（個人）是 runtime 在背景執行的 JavaScript 腳本，用來生成並協調數十到數百個 subagent，需 Claude Code v2.1.154+ [1, 4]。不是手寫的，而是從 /workflows 跑一輪後按 s 存檔產生。每個 .js 成為一個 /<name> 命令；專案層同名覆寫個人層。要關閉：/config 切 Dynamic workflows、settings.json 設 disableWorkflows: true、或環境變數 CLAUDE_CODE_DISABLE_WORKFLOWS=1 [4]。

​
2.5 agent-memory：subagent 的持久記憶

subagent 在 frontmatter 設 memory: 才會有專屬記憶目錄，存放位置依範圍而定 [1]： 運作方式同主 session 自動記憶：subagent 自己讀寫，起手載入前 200 行（上限 25 KB），你不手寫。

​
3. 動手做：盤點你的 .claude/

1

列出現有項目

在你常用專案跑 ls -la .claude/ 與 ls -la ~/.claude/，對照上方互動式目錄，列出你已有與還沒用到的項目。
2

檢查 gitignore

對每個已有檔案問一句：它該不該提交？settings.local.json、CLAUDE.local.md、agent-memory-local/ 必須在 .gitignore；漏掉就會把個人設定推給團隊。
3

試裝一個個人化面

挑一個還沒用的個人化面試裝：用 /theme 建一個主題，或 /keybindings 綁一個常用鍵，確認熱重載生效。
4

檢查 output style 現值

跑 /config 看 output style 現值，若你常做非寫程式的任務（審查、教學），試切一個內建 style。

​
4. 常見誤區

反模式清單
  • 把 CLAUDE.md / .mcp.json 當成 .claude/ 內的檔案：它們在專案根。放錯位置 Claude 讀不到。
  • 漏 gitignore 個人層：settings.local.json、CLAUDE.local.md、.claude/agent-memory-local/ 一旦提交，就把你的個人覆寫與本機記憶推給全隊。
  • 以為改 output style / 主題立刻生效：output style 與系統提示在 session 起始固定，改完要 /clear 或開新 session。
  • 把 subagent 記憶與主 session 記憶混為一談：兩者目錄不同、範圍不同，memory: frontmatter 沒設就根本沒有 subagent 記憶。
  • 跨工具照抄路徑：.claude/ 的結構不會原樣搬到 Codex / Antigravity，逐格對位見 02-6。

​
自我檢核

通過本單元的標準
  1. 給你 .claude/ 下任一檔名，你能說出它的用途、何時載入、該不該提交，以及去哪一篇查細節嗎？
  2. 你能說出哪三個檔在專案根而非 .claude/ 內嗎？
  3. 你知道 output style、keybindings、themes 各自的設定檔位置與生效時機嗎？
  4. subagent 的三種 memory: 範圍分別寫到哪裡、哪個會進版控？

​
來源與延伸閱讀

事實主張依官方文件，快變動項標註截至 2026-06。
  • [1] Anthropic, “探索 .claude 目錄”（互動式檔案參考，逐檔列出位置、載入時機、提交與否與範例），Claude Code Docs. Accessed: 2026-06. [Online]. Available: https://code.claude.com/docs/zh-TW/claude-directory （截至 2026-06）
  • [2] Anthropic, “Output styles”（內建四種、自訂 frontmatter、outputStyle 設定與生效時機），Claude Code Docs. Accessed: 2026-06. [Online]. Available: https://code.claude.com/docs/en/output-styles （截至 2026-06）
  • [3] Anthropic, “Keybindings”（~/.claude/keybindings.json、context 與 action、chord、保留鍵），Claude Code Docs. Accessed: 2026-06. [Online]. Available: https://code.claude.com/docs/en/keybindings （截至 2026-06）
  • [4] Anthropic, “Orchestrate subagents at scale with dynamic workflows”（.claude/workflows/*.js runtime 背景執行、生成並協調數十至數百個 subagent，從 /workflows 按 s 存檔、每檔成 /<name>、專案覆寫個人、需 v2.1.154+、disableWorkflows 或 CLAUDE_CODE_DISABLE_WORKFLOWS=1 關閉），Claude Code Docs. Accessed: 2026-06. [Online]. Available: https://code.claude.com/docs/en/workflows （截至 2026-06）