安裝與三層 settings

TL;DR

• 三層 settings：global（~/.claude/settings.json）、project shared（.claude/settings.json）、project local（.claude/settings.local.json）——後者覆蓋前者。
• 個人習慣放 global、團隊共通放 project shared、機密與個人偏好放 project local（並 gitignore 它）。
• CLAUDE.md 是給 Claude 看的「自我介紹」——不是給人讀的 README。

一個情境：把設定複製給同事，但 API key 不能跟著走

你在自家專案把 Claude Code 調得很順手——加了幾個 allow 規則少按一些 permission prompt、設了某個內部 API 的 base URL、塞了一條 hook 在每次 commit 前跑 lint。

新同事 onboard，問你：「這套設定怎麼複製過去？」

你會發現一個尷尬的問題：

• 那條 lint hook 是團隊共通的，應該跟 repo 走
• API base URL 也是團隊共通的
• 但你那把 ANTHROPIC_API_KEY、那個指向你本機 ~/scratch 的路徑、那個只有你會用的 alias——絕對不能跟 repo 走

如果只有一份 settings.json，你只能二選一：要嘛全部 commit（洩 key），要嘛全部 gitignore（同事拿不到）。

三層 settings 就是為了解這件事。

安裝（一行）

跨平台都一樣（macOS、Linux、Windows WSL 都行，原本影片只展示 macOS 但已經不限）：

npm install -g @anthropic-ai/claude-code
claude

第一次跑 claude 會走 OAuth 把帳號接起來，token 存在 ~/.claude/。之後 cd 到任何 repo 開 claude 就能用。

三層 settings：誰覆蓋誰

三個檔案同名同 schema，差在作用域和優先級：

層級	路徑	進 git 嗎	適合放什麼
Global	~/.claude/settings.json	不會（在你 home）	你個人跨專案的偏好、theme、常用 model
Project shared	.claude/settings.json	會	團隊共通的 permission allow list、hooks、env
Project local	.claude/settings.local.json	不要	機密、本機路徑、你個人在這專案的 override

優先級由低到高：global → project shared → project local。同一個 key 出現在多層時，最右邊的贏。

一個具體例子：lint hook 該放哪一層

假設團隊規定每次 Claude 改完檔，要自動跑 pnpm lint --fix。這條 hook：

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "pnpm lint --fix" }] }
    ]
  }
}

這該進哪一層？

• 不是 global——別的 repo 沒有 pnpm lint
• 不是 project local——別人 clone 下來就沒這條 hook 了，規範執行不了
• 應該是 project shared（.claude/settings.json），跟 repo 一起 commit

反過來，如果你個人想多加一條「commit 前先發 macOS 通知提醒我」的 hook——那是你私人習慣，放 project local。

（hook 只是先給你看一個範例，後面 Section 3 會專門講。）

CLAUDE.md：給 Claude 的「自我介紹」

跟 settings 平行的，還有一個檔叫 CLAUDE.md——放在 repo root（或 ~/.claude/CLAUDE.md 當 global）。

它跟 README 不一樣：

	README	CLAUDE.md
讀者	人	Claude
內容	怎麼安裝、怎麼用	這 repo 的慣例、不要碰的檔、常用指令
篇幅	越完整越好	越精煉越好（會吃 context）

舉例：「這個專案用 pnpm 不要用 npm」、「generated/ 底下的檔不要手改」、「跑 test 用 pnpm vitest run 不要互動模式」——這些都是給 Claude 的 hint，會被自動載進每次對話的 context。

寫得好的 CLAUDE.md 能省掉你每次重複交代環境細節。但它吃 context 額度，所以要短、要精準——細節怎麼寫留給後面 lesson 07（Controlling Context）。

接下來

裝好了、設定分層理解了，下一步是真的開始用——但在 Claude 動手前，先讓它把 plan 講出來。

下一篇：Plan mode：先看再動