Claude Code 教學：安裝、CLAUDE.md 與權限設定指南

Claude Code 教學完整版：安裝、第一天該學的四個指令、CLAUDE.md 怎麼寫才有效、權限允許清單怎麼設，以及如何用環境變數把模型端換成其他相容服務。

Claude Code 是跑在終端機裡的編碼代理。它不是聊天視窗——你把它開在專案目錄，它會自己讀專案結構、改多支檔案、跑測試、開 PR。學會用它的門檻不在英文好不好，而在於：你願不願意先花二十分鐘設定好 CLAUDE.md 與權限，換之後每天省下的重複交代。

這篇是給第一次用的人的完整教學：安裝、第一天的正確用法、四個一定要學的指令、CLAUDE.md 怎麼寫、權限模式怎麼選、以及怎麼把模型端換成自己的供應商。本文指令在 claude 2.1 上實跑過，開始前先 claude --version 對一下版本。

安裝與第一次啟動

需要 Node.js 22 以上（撰稿時的官方要求，版本會往上調，裝不起來先看 node -v）：

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

cd 到你的專案，然後：

claude

第一次啟動會要你完成登入（訂閱方案或 API 金鑰擇一）。登入完成後，第一件事不要叫它寫功能，先叫它讀懂專案：

先看一下這個 repo 的結構，告訴我主要的模組怎麼切、資料流從哪裡進來

理由很實際：它答得準不準，直接告訴你這個專案的脈絡它抓不抓得到。抓不到，代表你需要補 CLAUDE.md；抓得到，你才知道可以放心交付多大的任務。

第一天就該學的四個指令

/clear 是新手最常忽略、老手用最兇的一個。脈絡裡塞著三十分鐘前那個已經放棄的方案，只會讓它一直繞回去。一個任務 = 一段乾淨的脈絡。

另外兩個值得早點知道：

• Plan mode：讓它先講計畫、不動手。大改動前先進 plan mode，確認方向對了再放行，比事後 review diff 省事。
• claude -p "<任務>"：非互動模式，輸出直接進 stdout，可以塞進腳本或 CI。

claude -p "把 CHANGELOG.md 未發布區塊整理成一段發版說明" > release-notes.txt

CLAUDE.md：投報率最高的二十分鐘

CLAUDE.md 放在專案根目錄，每次開工自動載入。它不是文件，是指令——寫進去的東西會被當成規則遵守。

先跑 /init 產生初版，然後手動把真正重要的東西補上。好的 CLAUDE.md 長這樣：

# 專案規範

## 指令
- 開發：`pnpm dev`（不要用 npm）
- 測試：`pnpm test -- --run`
- 型別檢查：`pnpm typecheck`

## 規矩
- 所有 API 回應型別集中在 `src/types/api.ts`
- 不要新增第三方套件，先問
- 樣式用 CSS Modules，專案裡沒有 Tailwind
- commit message 用繁體中文

## 坑
- `src/legacy/` 底下的東西不要重構，有外部系統依賴
- 本地測試需要先跑 `docker compose up -d db`

三個實務原則：

1. 寫「不要做什麼」比寫「要做什麼」有效。 它預設會做的事很多，你真正需要的是圍籬。
2. 每次你在對話裡重複交代第二次的事，就該寫進 CLAUDE.md。 這是最好的判準。
3. 可以分層。 家目錄的 ~/.claude/CLAUDE.md 放個人偏好（例如「回答用繁體中文」），專案根目錄放團隊規範，子目錄再放模組專屬規則。

權限：讓它跑得動，又不會亂跑

預設每個會改檔案或執行指令的動作都會問你。全部按同意很煩，全部放行很危險，正解是把重複出現的安全動作加進允許清單——同意提示裡選「不要再問」，或直接編輯專案的 .claude/settings.json：

{
  "permissions": {
    "allow": [
      "Bash(pnpm test:*)",
      "Bash(pnpm typecheck)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ]
  }
}

原則很簡單：唯讀與可還原的動作放行，會動到外部世界的不放行（推送、部署、刪除、發訊息、付款）。這條線畫清楚，你就能安心讓它連續工作十幾分鐘不用盯著。

還有一個習慣比任何設定都重要：動手前先 commit。有乾淨的 git 狀態，任何時候都能 git checkout . 把它做的事整批丟掉。

實戰：一個真的會用到的工作流

假設你要修一個 bug。有效的流程是：

1. 先給它重現路徑，不要先給它猜。

   跑 pnpm test -- --run src/cart/total.test.ts，第 3 個 case 紅的，先重現給我看
   

2. 要它先解釋成因再改。 直接叫它修，你會拿到一個能讓測試變綠但你看不懂的補丁。
3. 改完要它跑測試自證。 CLAUDE.md 裡寫好測試指令，這步它會自己做。
4. 自己看 diff。 這一步沒有捷徑。

寫新功能時把順序反過來：先 plan mode 讓它提計畫、你改計畫、再放行實作。在計畫階段改方向的成本，是在程式碼階段改的十分之一。

換一個模型端

Claude Code 的模型端是可以指向其他相容服務的——三個環境變數而已，不用改任何專案設定。會這樣做的理由通常是：想在同一套工具裡試不同模型、想讓團隊共用一個計費出口、或需要台灣的付款方式與憑證。

BazaarLink 提供相容的端點，設定像這樣：

# macOS / Linux
export ANTHROPIC_BASE_URL=https://api.bazaarlink.ai
export ANTHROPIC_AUTH_TOKEN=sk-bl-你的金鑰
export ANTHROPIC_MODEL=anthropic/claude-opus-4.6

claude

# Windows PowerShell
$env:ANTHROPIC_BASE_URL = "https://api.bazaarlink.ai"
$env:ANTHROPIC_AUTH_TOKEN = "sk-bl-你的金鑰"
$env:ANTHROPIC_MODEL = "anthropic/claude-opus-4.6"

claude

四個實測後才知道的細節：

1. ANTHROPIC_BASE_URL 填到網域為止，不要帶 /v1。 工具自己會接上 /v1/messages；帶了會變成 /v1/v1/messages 然後 404。
2. ANTHROPIC_MODEL 要填完整 id，例如 anthropic/claude-opus-4.6、anthropic/claude-sonnet-4.6、anthropic/claude-opus-5。可用清單看 模型列表。
3. 可能會看到「某某模型已退役」的提示。 那是工具本地用模型字串比對出來的，不是伺服器的回應，不影響執行。
4. 要切回原本的設定，把這三個環境變數拿掉就好。 沒有任何專案檔案被改到，所以切換是零成本的。

金鑰到 bazaarlink.ai/free 開；免費層足夠把整套流程跑通再決定要不要加值，實際的頻率上限以該頁標示為準。企業使用與發票條件見 企業方案。

常見卡關

它一直問我要不要執行指令 — 把重複出現的安全指令加進 .claude/settings.json 的允許清單。

它改了不該改的檔案 — 兩件事：git checkout 還原，然後把「不要動 X」寫進 CLAUDE.md。同一個錯誤發生第二次，代表規則沒寫下來。

回答開始飄、一直繞回舊方案 — 脈絡髒了。/clear 重來，長任務中途用 /compact。

它說找不到某個指令 — 你的專案指令沒寫進 CLAUDE.md，它只能猜。

中文回答時繁簡混雜 — 在 ~/.claude/CLAUDE.md 寫一行「一律使用繁體中文（台灣用語）回答」。

小結

Claude Code 的效率差距不在誰比較會下 prompt，而在三件基礎功：CLAUDE.md 寫得夠不夠具體、脈絡有沒有勤清、權限清單有沒有調到「安全的事不用問」。這三件做好，它從一個要一直盯著的工具，變成可以交付整段任務的同事。

模型端是可換的，工具本身不綁死在單一供應商——三個環境變數就能切，也隨時能切回去。

台幣計費・統一發票・主流 AI 模型・OpenAI 相容 API