跳轉到主要內容
這個單元解決什麼問題前面各單元把 CLAUDE.md、rules、skills、subagents、hooks、plugins 分開深寫，但你需要一張「整個 .claude 目錄裡每個檔案與資料夾各是什麼、何時載入、要不要提交版控」的完整對照，缺一不可。這個單元就是那張表：逐項列出專案層 .claude/ 與使用者層 ~/.claude/，把散落的深寫單元串成一張可掃描的索引，並補上目前沒有專門單元的五個主題（output-styles、keybindings、themes、workflows、agent-memory）。權威來源是官方互動式目錄頁 [1]。

​
學習目標

  • 能說出 .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 改版頻繁，動手前以官方當前頁為準。

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

.claude 相關的檔案散在三個地方，先釘住這個分界，後面逐項才不會錯位：
家族位置提交版控誰看得到
專案根repo 根目錄（CLAUDE.md、.mcp.json、.worktreeinclude）多數提交團隊
專案 .claude/repo 內 .claude/ 目錄多數提交，*.local.* gitignore團隊（個人覆寫除外）
使用者層~/.claude/（Windows %USERPROFILE%\.claude\）與 ~/.claude.json不提交（機器本地）只有你
最常踩的錯是把 CLAUDE.md、.mcp.json 當成 .claude/ 裡的檔案。它們在專案根，不在 .claude/ 內 [1]。

​
2. 專案根（不在 .claude/ 內）

（repo 根目錄）
CLAUDE.md · 每 session 起手全量載入，專案指令主檔
CLAUDE.local.md · gitignored，個人私有設定（沙盒 URL、本機測試資料）
.mcp.json · session 起始連線，專案級 MCP 伺服器，團隊共享
.worktreeinclude · 建立 git worktree 時，列出要從主 repo 複製的 gitignored 檔
檔案提交何時載入用途深讀
CLAUDE.mdcommitted每 session 起手全量專案指令（慣例、常用指令、架構脈絡）；也可放 .claude/CLAUDE.md04-1
CLAUDE.local.mdgitignored每 session 起手個人在本專案的私有設定04-1
.mcp.jsoncommittedsession 起始連線，工具 schema 預設延遲載入專案級 MCP 伺服器，團隊共享；個人專屬 MCP 放 ~/.claude.json04-9
.worktreeincludecommitted建立 git worktree 時列出要從主 repo 複製進新 worktree 的 gitignored 檔案（如 .env），用 .gitignore 語法官方 worktrees 頁 [1]

​
3. 專案層 .claude/

.claude
settings.json · 共享設定，權限 / hooks / model / env / statusLine / outputStyle
settings.local.json · gitignored，個人覆寫，同 schema 陣列合併純量取最近層
rules
*.md · topic 規則；無 paths: 等同 CLAUDE.md 起手載入，有 paths: 限指定 glob
skills
檔案 / 資料夾提交用途深讀
settings.jsoncommitted權限、hooks、model、env、statusLine、outputStyle 等；是 enforced 設定（不像 CLAUDE.md 只是 context）02-3
settings.local.jsongitignored個人覆寫，與 settings.json 同 schema；陣列類設定跨層合併、純量取最近層02-3
rules/*.mdcommittedtopic 規則檔；無 paths: frontmatter 時等同 CLAUDE.md 起手載入，有 paths: 時只在 Claude 讀到符合 glob 的檔案才載入04-2
skills/<name>/SKILL.mdcommitted可由你 /<name> 或 Claude 依 description 自動叫用的 skill，目錄可夾帶 references/、scripts/04-4
commands/<name>.mdcommitted舊式單檔斜線命令；與 skills 已是同一機制，新工作流建議改用 skills/，同名時 skill 優先04-3
output-styles/committed專案共享的輸出風格（見第 5 節）；個人風格多放 ~/.claude/output-styles/本單元第 5 節
agents/*.mdcommittedsubagent 定義（各有獨立 context、工具集、可指定 model）04-5
workflows/*.jscommitted動態 workflow 腳本，由 /workflows 存檔產生，每檔成為一個 /<name>；專案層同名覆寫個人層本單元第 5 節
agent-memory/<agent>/MEMORY.mdcommittedsubagent 的專案層持久記憶（frontmatter memory: project），與主 session 自動記憶分開本單元第 5 節
與主 session 自動記憶不同.claude/agent-memory/ 是 subagent 自己的記憶，跟你主 session 的自動記憶（在 ~/.claude/projects/<repo>/memory/）是兩回事。subagent 用 memory: local 會改寫到 .claude/agent-memory-local/（gitignored）、memory: user 改寫到 ~/.claude/agent-memory/（跨專案）[1]。

​
4. 使用者層 ~/.claude/ 與 ~/.claude.json

~
.claude.json · app 狀態 / UI 偏好 / OAuth session / 個人 MCP；多由 /config 管理，不手編
.claude
CLAUDE.md · 個人跨專案指令，與專案 CLAUDE.md 並存載入；衝突時專案層優先
settings.json · 套用所有專案的預設；被專案層同名 key 覆寫
keybindings.json · 自訂鍵盤快捷鍵（見第 5.2 節，需 v2.1.18+）
檔案 / 資料夾用途深讀
~/.claude.jsonapp 狀態、UI 偏好、OAuth session、per-project 信任決策、個人 MCP 伺服器；多由 /config 管理，不手編。注意 IDE 切換（autoConnectIde 等）與 session 內核准的 permission 存的位置不同（後者進 .claude/settings.local.json）02-4
~/.claude/CLAUDE.md個人跨專案指令，與專案 CLAUDE.md 並存載入；衝突時專案層優先04-1
~/.claude/settings.json套用所有專案的預設；被專案層同名 key 覆寫02-3
~/.claude/keybindings.json自訂鍵盤快捷鍵（見第 5.2 節）本單元第 5.2 節
~/.claude/themes/自訂配色主題（見第 5.3 節）本單元第 5.3 節
~/.claude/rules/ skills/ commands/ output-styles/ agents/ workflows/與專案層對應，但作用於所有專案各對應單元
~/.claude/agent-memory/memory: user 的 subagent 跨專案記憶04-5
~/.claude/projects/<repo>/memory/MEMORY.md主 session 自動記憶（v2.1.59+，起手載入前 200 行或 25KB）04-1

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

前面四節把每項對應到深寫單元，剩下這五個沒有專篇，在此補足到可操作。

​
5.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 才生效。
一個教學模式 output style
---
description: 解釋設計決策，小改動留給你自己實作
keep-coding-instructions: true
---

每完成一個任務，補一段「為什麼這樣設計」說明關鍵取捨。
改動少於 10 行時，用 TODO(human) 標記留給使用者實作，不要自己寫。

​
5.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 會顯示綁定衝突警告。改動自動偵測、熱重載。

​
5.3 themes：自訂配色

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

​
5.4 workflows：動態多代理腳本

.claude/workflows/<name>.js（專案）或 ~/.claude/workflows/（個人）是 runtime 在背景執行的 JavaScript 腳本，用來生成並協調數十到數百個 subagent，需 Claude Code v2.1.154+ [1, 4]。它不是手寫的，而是從 /workflows 跑一輪後按 s 存檔產生（內建 /deep-research 是一個現成範例）。每個 .js 成為一個 /<name> 命令；專案層同名覆寫個人層。要關閉：/config 切 Dynamic workflows、settings.json 設 disableWorkflows: true、或環境變數 CLAUDE_CODE_DISABLE_WORKFLOWS=1 [4]。深入機制見官方專頁 [4]，本單元只標位置與來源。

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

subagent 在 frontmatter 設 memory: 才會有專屬記憶目錄，存放位置依範圍而定 [1]：
frontmatter寫入位置提交範圍
memory: project.claude/agent-memory/<agent>/MEMORY.mdcommitted團隊共享
memory: local.claude/agent-memory-local/gitignored本機本專案
memory: user~/.claude/agent-memory/本機跨專案
運作方式同主 session 自動記憶：subagent 自己讀寫、起手載入前 200 行（上限 25KB），你不手寫。

​
6. 工具對照：其他 agent 的目錄對等

同一套「設定即目錄」在其他工具有對應結構（截至 2026-06，嚴格路徑見 02-6）：
面向Anthropic Claude（主範本）OpenAI CodexGoogle AntigravityGitHub Copilot CLICursor（短提）
設定根.claude/、~/.claude/.codex/、~/.codex/（CODEX_HOME 可搬）工作區 .agents/、全域 ~/.gemini/、~/.gemini/config/.github/、~/.copilot/（COPILOT_HOME）.cursor/
專案指令CLAUDE.mdAGENTS.md（AGENTS.override.md 優先）GEMINI.md / AGENTS.md、.agents/rules/.github/copilot-instructions.md、AGENTS.md.cursor/rules/*.mdc、AGENTS.md
行為設定settings.jsonconfig.tomlGUI + ~/.gemini/antigravity-cli/settings.json~/.copilot/config.jsonGUI（Settings）
skills.claude/skills/<n>/SKILL.md.agents/skills/<n>/SKILL.md工作區 .agents/skills/；全域 IDE ~/.gemini/config/skills/、CLI ~/.gemini/antigravity-cli/skills/~/.copilot/skills/、.github/skills/（無原生 skill）
subagents.claude/agents/*.md~/.codex/agents/*.toml、.codex/agents/*.toml.agents/ 為主~/.copilot/agents/*.agent.md、.github/agents/（無）
hookssettings.json 的 hooks~/.codex/hooks.json、config.toml 的 [hooks]hooks.json（.agents/ 或 ~/.gemini/config/）~/.copilot/hooks/、.github/hooks/（無）
MCP.mcp.json、~/.claude.jsonconfig.toml 的 [mcp_servers.<id>]~/.gemini/config/mcp_config.json~/.copilot/mcp-config.json、.mcp.json.cursor/mcp.json
對等不等於語意相同表裡同一列只代表「概念對得上」，不代表行為一致。Codex 的 skills 在 .agents/skills/（不是 .codex/skills/）、Antigravity 工作區規則用複數 .agents/（不是單數），都是容易照舊心智模型踩錯的點。換工具時逐格查 02-6，別套用 Claude 的路徑。

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

1

列出現有項目

在你常用專案跑 ls -la .claude/ 與 ls -la ~/.claude/，對照第 3、4 節，列出你已有與還沒用到的項目。
2

檢查 gitignore

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

試裝一個個人化面

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

檢查 output style 現值

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

​
8. 常見誤區

反模式清單
  • 把 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，逐格對位見第 6 節與 02-6。

​
自我檢核

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

​
來源與延伸閱讀

事實主張依官方文件，快變動項標註截至 2026-05。
  • [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）