Claude Code CLI 設定 2026：5 分鐘快速上手

如何設定 Claude Code？ 透過 npm install -g @anthropic-ai/claude-code 全域安裝 CLI，經由瀏覽器完成身分驗證，然後在專案根目錄建立 CLAUDE.md 檔案，內含技術堆疊資訊與程式碼撰寫慣例。於 .claude/settings.json 設定權限，並加入格式化 hook，讓每次編輯後自動修正樣式。整個設定過程不到五分鐘即可完成。 {.answer-block}

目前 ServiceNow 已有超過 29,000 名開發者每天使用 Claude Code¹，Allianz 也於 2026 年初在全公司推行²。此工具的採用曲線反映出一種模式：開發者一旦在自己的終端機中嘗試過代理式程式設計，就不會再回頭複製貼上聊天視窗的內容。本快速上手指南隸屬於我的 AI 工程系列——為使用 Claude 進行開發的工程師所準備的實用指引。以下教學將帶您在約五分鐘內從零建立一個可運作的 Claude Code 工作階段,並附上可持續沿用的實際設定。

TL;DR： 透過 npm install -g @anthropic-ai/claude-code 安裝 Claude Code,經由瀏覽器進行身分驗證,建立包含專案背景的 CLAUDE.md 檔案,並在 .claude/settings.json 中設定權限。加入 Prettier hook,讓每次寫入檔案後自動格式化。整套設定不到五分鐘即可完成,且設定會跨工作階段持續保留。

重點摘要

獨立開發者： CLAUDE.md 搭配格式化 hook 已涵蓋 80% 的需求。建議從預設權限開始,隨著建立信任再逐步預先核准工具。
團隊負責人： 將 .claude/settings.json 納入版本控制,讓整個團隊共用相同的權限允許清單與 hook。
資安工程師： 三層式權限模型⁴(詢問、允許清單、--dangerously-skip-permissions)直接對應信任等級。詢問模式要求每次寫入與每條命令都須明確核准。

前置需求

安裝 Claude Code 前需要準備三樣東西:

Node.js 18 或更新版本。 Claude Code 以 npm 套件形式發布³。請檢查版本:

node --version
# v18.0.0 or higher

若需安裝或升級 Node.js,可使用 nvm 或直接從 nodejs.org 下載。

具備 API 存取權限的 Anthropic 帳號。 請至 console.anthropic.com 的 Settings > API Keys 建立 API 金鑰。Claude Code 依 token 用量從您的 API 餘額扣款,或可訂閱 Max 方案(截至 2026 年 3 月,個人方案每月 100 美元,團隊方案每月 200 美元)⁶。請將金鑰保留備用,稍後身分驗證時會用到。

一個終端機。 Claude Code 可在任何終端機模擬器中執行:Terminal.app、iTerm2、Windows Terminal、Alacritty,或 VS Code 內建的終端機皆可。建議使用寬度至少 120 欄的終端機,因為 Claude Code 會顯示檔案差異與工具輸出,橫向空間越充裕越好。

安裝

透過 npm 全域安裝 Claude Code:

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

驗證安裝是否成功:

claude --version

終端機應會輸出版本號碼。若出現「command not found」錯誤,代表 npm 全域 bin 目錄未納入您的 PATH。請執行 npm config get prefix,並將其 /bin 子目錄加入 shell 的 PATH。在使用 Homebrew 安裝 Node 的 macOS 上,prefix 通常是 /usr/local,因此若尚未納入,請將 /usr/local/bin 加入 PATH。

常見安裝問題: 若執行 npm install -g 時遇到 EACCES 權限錯誤,請勿使用 sudo。建議改為設定 npm 使用使用者可寫入的目錄⁷:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# Add to your shell profile (~/.zshrc or ~/.bashrc):
export PATH="$HOME/.npm-global/bin:$PATH"

首次啟動時,Claude Code 會開啟瀏覽器前往 Anthropic 控制台進行 OAuth 身分驗證。您登入、授權後,Claude Code 會將 token 存放於本機的 ~/.claude/。或者,您也可以在啟動前設定 ANTHROPIC_API_KEY 環境變數。無論採用哪種方式,憑證都會保存在您的機器上,且僅用於 API 請求的身分驗證。

首次工作階段

切換至任一專案目錄並執行:

cd ~/Projects/my-app
claude

Claude Code 會啟動互動式 REPL 工作階段。首次在新專案中啟動時,Claude 會自動進行數項作業:

掃描目錄結構,以了解專案配置
讀取設定檔,例如 package.json、pyproject.toml 或 Cargo.toml,辨識技術堆疊
尋找專案根目錄的 CLAUDE.md 檔案,以取得專案專屬指示

不妨輸入一個簡單的提示來確認一切運作正常:

> Explain the structure of this project

Claude 會讀取您的檔案、綜合整體架構,並在終端機中回覆。您會即時看到工具呼叫(每次檔案讀取、每條指令執行),且在任何寫入作業前都會徵求核准。

首次工作階段應觀察的重點。 請特別留意兩件事:工具呼叫(在每個動作前即時顯示)與權限提示。工具呼叫顯示了 Claude 如何瀏覽您的程式碼庫。您會發現它會讀取您原本想不到要檢查的檔案,這往往能帶出有用的背景資訊。權限提示則在任何變更實際寫入磁碟前,清楚顯示 Claude 打算做什麼。若提議的編輯看起來不正確,請拒絕並提供進一步說明。Claude 會根據您在工作階段中的回饋調整其作法⁸。

設定 CLAUDE.md

CLAUDE.md 是有效使用 Claude Code 最重要的單一檔案。沒有它,Claude 會從檔案內容推斷您的技術堆疊,並做出合理的猜測。有了它,Claude 從第一個提示起就會遵循您明確的慣例。這個差異至關重要,因為基於推斷的行為會產生漂移:Claude 可能在 ESM 專案中使用 CommonJS、選用錯誤的測試執行器,或忽略您的資料庫遷移流程。CLAUDE.md 可消除這種漂移。

在您的專案根目錄建立該檔案:

touch CLAUDE.md

以下是適用於 Python 專案的實用起始範本:

# My App

## Project Context
FastAPI backend with HTMX frontend. PostgreSQL database.

## Stack
- Backend: Python 3.11, FastAPI, SQLAlchemy 2.0 (async)
- Frontend: HTMX + Alpine.js, Jinja2 templates
- Database: PostgreSQL 16, Alembic migrations
- Testing: pytest with pytest-asyncio

## Code Standards
- Type hints on all function signatures
- Pydantic v2 models for request/response validation
- Async database operations only (no sync SQLAlchemy)

## Commands
- `source venv/bin/activate` before any Python command
- `uvicorn app.main:app --reload` starts the dev server
- `python -m pytest -v` runs the test suite
- `alembic upgrade head` applies database migrations

對於 JavaScript/TypeScript 專案,結構類似:

# My App

## Stack
- Backend: Node.js 20, Express 4, TypeScript
- Frontend: React 18, Vite
- Database: PostgreSQL 16, Prisma ORM
- Testing: Vitest for unit, Playwright for e2e

## Code Standards
- ESM imports only (no require())
- All API endpoints need input validation with Zod
- Tests required for new endpoints before merging

## Commands
- `npm run dev` starts the dev server on port 3000
- `npm test` runs the test suite
- `npx prisma migrate dev` runs database migrations

CLAUDE.md 最有價值的段落,是能預防重複錯誤的那些。若 Claude 一直用 require() 而非 import 進行匯入,請在 Code Standards 加上「ESM imports only」。若您的測試指令需要先啟動 virtualenv,請記錄這段步驟。Claude 在每個工作階段開始時都會讀取 CLAUDE.md,因此每一行都會成為持續生效的指示,並在數百次互動中持續累積效果。我在 AGENTS.md 模式中深入探討了讓 CLAUDE.md 檔案有效運作的模式,以及脈絡即架構這項更廣泛的原則。AGENTS.md 開放規格⁹ 採用類似模式服務其他代理式工具,但 CLAUDE.md 支援更豐富的功能,例如 skills 與 rules 目錄。

層級順序很重要。 您可以將 CLAUDE.md 放在三個位置,Claude 會依據具體程度由高至低合併:

~/.claude/CLAUDE.md:適用於所有專案的全域指示(您個人的程式撰寫偏好)
./CLAUDE.md:專案層級指示(納入版本控制,與團隊共用)
./src/CLAUDE.md:目錄層級指示(針對 monorepo 模組或子系統的範圍限定)

專案層級的 CLAUDE.md 就是您要提交到版本控制的那一份。使用 Claude Code 的團隊成員會自動繼承您的慣例。

權限基礎

Claude Code 以三層權限模式⁴運作,用以決定代理程式擁有多少自主權。您所選擇的層級掌控一項根本的取捨:自主權越高,工作階段速度越快,但對變更內容的能見度就越低。

詢問模式(預設)要求在每次檔案寫入、指令執行或破壞性操作前都須核准。您會看到 Claude 確切的意圖,並逐步核准或拒絕。建議從這個模式開始,因為核准提示能教您了解 Claude Code 的運作方式。使用幾次工作階段後,您會培養出直覺,判斷哪些作業可安全預先核准,哪些每次都值得仔細審視。

允許清單權限 讓您預先核准特定工具與模式,使 Claude 不需每次都詢問。請在專案的 .claude/settings.json 中進行設定:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(python -m pytest*)",
      "Bash(alembic upgrade head)"
    ]
  }
}

上述設定允許 Claude 讀取檔案、搜尋程式碼庫,以及執行您的測試與遷移指令,無須詢問。但在寫入檔案或執行其他 bash 指令前,仍會徵求同意。請留意這個模式:讀取作業與已知安全的指令列入允許清單;寫入作業則保留在詢問模式,因為您會想在檔案寫入磁碟前審視 Claude 寫了什麼。

跳過權限確認(--dangerously-skip-permissions)會停用所有確認提示。此旗標僅為 CI/CD 管線與自動化流程設計,適用於無人監管核准的情境。切勿在您重視的程式碼庫上於互動式工作階段中使用。

此權限系統讓 Claude Code 可安全地用於實際專案。其進程設計刻意循序漸進:從詢問模式開始建立理解,將變得重複的作業列入允許清單,並保留寫入作業的控管,讓您在變更實際落地前始終有機會檢視。

您的第一個 Hook

Hook 是在 Claude Code 生命週期特定時點執行的 shell 指令⁵。我撰寫過完整的 hooks 教學,從零開始建構五個正式環境可用的 hook;另一篇打造自訂 skills 則介紹了自動化的下一個層次。Hook 解決了 LLM 型工具的一項根本問題:模型多數情況下會遵循您的格式化規則,但「多數情況下」意味著每十次檔案編輯就會出現一次樣式不一致。Hook 提供確定性保證,填補了模型僅能提供機率性保證的缺口。格式化 hook 會在每次檔案寫入後執行您的格式化工具,次次如此,無論模型當下的決定為何。以下是一個實用的起手 hook:在 Claude 編輯檔案後自動格式化。

在您的專案中建立或編輯 .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

PostToolUse hook⁵ 會在每次 Edit 或 Write 工具呼叫之後觸發。Claude Code 會將 $FILE_PATH 設為被修改檔案的路徑。Prettier 會就地格式化該檔案,而 || true 可確保非零的結束代碼不會阻擋 Claude,以防 Prettier 未安裝或該檔案類型不受支援⁵。

其他建議採用的實用起始 hook:

PreToolUse on Bash:封鎖如 rm -rf / 或 git push --force 等危險指令
SessionStart:將目前日期、作用中的 git 分支或環境變數注入脈絡(SessionStart hook 的 stdout 會輸入到 Claude 的脈絡中)
Stop:在 Claude 完成任務時自動執行您的測試套件

Hook 讓 Claude Code 從對話式工具轉變為受治理的開發環境。即使只是一兩個精選的 hook,也能消除整類錯誤。

遭遇問題時

在使用 Claude Code 的第一週,有三種情境特別常見。事先了解這些能節省除錯時間。

Claude 忽略您的 CLAUDE.md 指示。 最常見的原因是:Claude 在您編輯該檔案之前就已讀取,並快取了當時的理解。請執行 /clear 重設脈絡,或開啟新工作階段。Claude 僅在工作階段開始時重新讀取 CLAUDE.md,並不會在每個提示時重讀。若開啟全新工作階段後 Claude 仍忽略指示,請檢查是否有優先等級較高的 CLAUDE.md(使用者層級 ~/.claude/CLAUDE.md)與您的專案層級檔案衝突。

Claude 做了您未核准的變更。 若您將模式設得過於寬鬆(例如使用 Bash(*) 而非 Bash(python -m pytest*)),Claude 就能未經詢問即執行指令。請將允許清單的模式收窄。最安全的作法是:僅將讀取作業與特定具名指令列入允許清單。若 Claude 已造成不預期的變更,git diff 會清楚顯示哪些地方有改動,而 git checkout -- <file> 即可還原。

長時間工作階段中脈絡視窗被填滿。 當 200K 的脈絡視窗被填滿時,Claude Code 會壓縮較早的訊息,但壓縮過程可能遺漏對話早期的重要細節。對於超過 30 分鐘的工作階段,建議定期提交可運作的變更,再以 /clear 開啟新工作階段。新的脈絡會重新讀取 CLAUDE.md,從乾淨的狀態開始。我習慣在每個子任務完成後提交一次,這同時提供了回復點與自然的工作階段分界。

Claude 編輯了錯誤的檔案或進行了不必要的變更。 當 Claude 開始「改進」您並未要求它修改的程式碼時,問題通常出在提示不夠明確。與其說「整理一下 auth 模組」,不如說「在 app/auth/handlers.py 中,將 verify_user 重新命名為 verify_user_credentials,並更新所有呼叫端」。明確性可降低非預期的副作用。若 Claude 已造成不想要的編輯,git diff 可清楚顯示變更內容,git checkout -- <file> 則能在不影響其他工作的情況下還原個別檔案。

後續步驟

以上教學涵蓋了核心要素:安裝、首次工作階段、專案設定、權限,以及起始 hook。若想比較 Claude Code 與其他代理式工具,請參閱 Claude Code vs Codex。若想取得涵蓋全部五大核心系統(CLAUDE.md 層級、完整權限模型、hooks 架構、自訂斜線指令與多代理工作流程)的完整參考資料,請閱讀 Claude Code 完整指南。

該指南涵蓋脈絡視窗管理、子代理委派、skill 自動啟用,以及數月每日使用 Claude Code 後浮現的各種模式。若本快速上手對您有幫助,完整指南將是自然的下一步。若想查閱所有指令、旗標與快捷鍵的速查參考,請參閱 Claude Code 速查表。

參考資料

FAQ

安裝 Claude Code 的需求為何？

您需要 Node.js 18 或更新版本(Claude Code 以 npm 套件形式發布)、一個具備 API 存取權限的 Anthropic 帳號或 Max 訂閱方案,以及任一終端機模擬器。Claude Code 可在 macOS、Linux 與 Windows(透過 WSL 或原生方式)上執行。除 Node.js 外,無須額外相依套件、Docker 容器或語言執行環境。安裝指令為 npm install -g @anthropic-ai/claude-code。

CLAUDE.md 是什麼？為什麼需要它？

CLAUDE.md 是位於專案根目錄的 markdown 檔案,用來告知 Claude Code 您的技術堆疊、程式碼慣例與常用指令。沒有它,Claude 會從檔案內容推斷您的設定並做出合理猜測——但這些猜測會在不同工作階段之間產生漂移。有了 CLAUDE.md,Claude 從第一個提示起、每個工作階段都會遵循您明確的慣例。它支援三層階層式結構:使用者層級(~/.claude/CLAUDE.md)、專案層級(./CLAUDE.md)與目錄層級(./src/CLAUDE.md),依具體程度順序合併。

Claude Code 費用為何？

Claude Code 提供兩種計費模式。API 用量計費模式依 token 用量以 Anthropic 標準 API 費率收費⁶。一般 30 至 60 分鐘的工作階段費用約在 0.50 至 3.00 美元之間,視程式碼庫規模與生成量而定。另一選項是 Anthropic 的 Max 方案⁶(截至 2026 年 3 月,個人方案每月 100 美元,團隊方案每月 200 美元),其中包含 Claude Code 使用額度,並提供較高的速率限制。可於 console.anthropic.com 監控 API 用量。

可以搭配 VS Code 使用 Claude Code 嗎？

可以。Claude Code 可在任何終端機中運作,包括 VS Code 的內建終端機。在 VS Code 中開啟終端機面板,切換至您的專案目錄,並如同在獨立終端機中一樣執行 claude。Claude Code 會直接讀取並編輯磁碟上的檔案,因此變更會立即反映在您的 VS Code 編輯器分頁中。無須額外安裝 VS Code 擴充套件。部分開發者會在編輯器旁保留一個專屬終端機分割視窗供 Claude Code 使用,這樣能在變更發生時即時審視,效果很好。

Claude Code 用於正式環境程式碼庫安全嗎？

Claude Code 的詢問模式要求在每次檔案寫入與每條指令執行前都須明確核准。未經您確認,磁碟上不會有任何變更。此權限系統加上可封鎖強制推送或破壞性 shell 指令等危險操作的 hook,使 Claude Code 能實際用於正式工作。我每天都在服務真實使用者的專案中使用 Claude Code。關鍵在於:從詢問模式開始,在核准每個工具呼叫前先了解其作用,並逐步僅將您信任的作業加入允許清單。版本控制是最後一道安全網:在開始任何重大 Claude Code 工作階段前先行提交,即可隨時還原。

新使用者最常犯的錯誤為何？

在提示中給予 Claude 過多背景資訊,而非將其寫進 CLAUDE.md。新使用者常將整套程式撰寫標準貼進每個提示中,這會浪費脈絡視窗的空間,且不同工作階段之間產生不一致的結果。請將重複性指示一次寫入 CLAUDE.md,並將提示保留給工作階段內的個別請求。第二常見的錯誤是:將 Bash(*) 而非具體指令加入允許清單。萬用字元的 Bash 允許清單讓 Claude 可以未經詢問執行任何 shell 指令,這違背了權限系統的設計初衷。

Anthropic, “ServiceNow Customer Story.” anthropic.com/customers/servicenow ↩
Anthropic, “Allianz Customer Story.” anthropic.com/customers/allianz ↩
Anthropic, “Claude Code Overview.” docs.anthropic.com/en/docs/claude-code/overview. Source: github.com/anthropics/claude-code ↩
Anthropic, “Claude Code Permissions.” docs.anthropic.com/en/docs/claude-code/security ↩↩
Anthropic, “Claude Code Hooks.” docs.anthropic.com/en/docs/claude-code/hooks ↩↩↩
Anthropic, “Pricing.” platform.claude.com/docs/en/about-claude/pricing ↩↩↩
npm Documentation, “Resolving EACCES permissions errors when installing packages globally.” docs.npmjs.com/resolving-eacces-permissions-errors ↩
Anthropic, “Effective usage of Claude Code.” docs.anthropic.com/en/docs/claude-code/best-practices ↩
Linux Foundation Agentic AI Foundation, “AGENTS.md Specification.” github.com/anthropics/agent-instructions ↩