Claude Code 完整指南：從安裝、權限到安全使用

一句話說明

Claude Code 是 Anthropic 推出的命令列 AI 程式開發工具，在終端機裡直接讀寫你的專案檔案、執行命令、操作 Git，自主完成開發任務。

Claude Code 是什麼

Claude Code 是一個在終端機中運行的 AI 開發助手。你用自然語言描述目標，它會自己讀取你的 codebase、分析程式碼結構、修改多個檔案、執行測試、看錯誤訊息再修正，直到任務完成。

跟一般的程式碼補全工具不同，Claude Code 是 Agentic 的。Agentic 的意思是：你給一個目標，它自己規劃步驟、決定要讀哪些檔案、改哪些程式碼、跑哪些命令。你說「幫我加一個使用者登入功能」，它會自己找到路由檔、控制器、資料庫模型、前端頁面，把相關的檔案都改好。過程中如果測試失敗，它會讀錯誤訊息、分析原因、修改程式碼再跑一次，不用你每一步都指示。

Claude Code 的運作環境是你的本機。它讀的檔案在你電腦上，跑的命令在你終端機裡，改的程式碼直接寫進你的檔案系統。這代表它跟你的開發環境零距離，能做到很多 Web 介面做不到的事——同時也代表如果設定不當，它對你的系統有很大的操作權限。

它支援多種方式取得 Claude 模型的存取權。可以用 Claude Pro 或 Max 的訂閱帳號，也可以直接用 Anthropic API 金鑰按 Token 計費，或者透過 Amazon Bedrock 和 Google Vertex AI 存取。企業環境通常會選擇後兩者，讓資料留在自己的雲端帳號中處理。

安裝與初始設定

系統需求

Claude Code 需要 Node.js 18 或以上版本。在 macOS 和 Linux 上可以直接使用，Windows 使用者需要透過 WSL2（Windows Subsystem for Linux）來運行。

確認 Node.js 版本：

node --version
# 需要 v18.0.0 或以上

如果版本不夠新，可以用 nvm 安裝：

nvm install 20
nvm use 20

安裝

透過 npm 全域安裝：

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

安裝完成後，在任何目錄中輸入 claude 就能啟動。

認證設定

第一次啟動時，Claude Code 會要求你登入。有兩種方式：

用 claude.ai 帳號登入。如果你有 Claude Pro（$20/月）或 Max（$100-200/月）訂閱，Claude Code 的使用量包含在訂閱裡面。啟動後會打開瀏覽器讓你授權。

用 API 金鑰。適合按用量計費或企業環境。在終端機設定環境變數：

export ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
claude

如果要讓環境變數每次都生效，加到你的 shell 設定檔（~/.bashrc 或 ~/.zshrc）。飛飛建議不要把 API 金鑰直接寫死在 shell 設定檔裡，用密碼管理工具或 direnv 之類的方案管理比較安全。

第一次啟動

在你的專案目錄中啟動 Claude Code：

cd ~/projects/my-app
claude

啟動後它會進入互動模式。你可以直接用中文輸入指令：

claude                           # 互動模式
claude "幫我看這段程式碼有沒有 bug"  # 單次指令模式
claude --model opus              # 指定使用 Opus 模型
claude --resume                  # 繼續上次的對話

建立 CLAUDE.md

在專案根目錄建立 CLAUDE.md 檔案。Claude Code 每次啟動都會讀這個檔案，用來理解你的專案規範。這是提升 Claude Code 產出品質最有效的做法。

# 專案規範

- 使用 TypeScript + Express.js
- 測試框架：Jest
- 程式碼風格：Prettier，不用分號，單引號
- Commit 訊息格式：Conventional Commits（feat: / fix: / docs:）
- 不修改 src/legacy/ 目錄下的檔案
- 所有 API endpoint 需要加入 rate limiting
- 資料庫操作一律使用 parameterized query

CLAUDE.md 不只給你自己用，也是團隊協作的工具。把它 commit 到 repo 裡，讓每個成員的 Claude Code 都遵循同一套規範。

建立 .claudeignore

類似 .gitignore，用來排除 Claude Code 不該讀取的檔案：

.env
.env.*
secrets/
credentials/
*.pem
*.key
*.p12
node_modules/
dist/

這一步跟 CLAUDE.md 一樣重要。沒有 .claudeignore 的話，Claude Code 在分析問題時可能會讀到包含 API 金鑰或資料庫密碼的 .env 檔案。這些內容會透過 API 傳送到 Anthropic 的伺服器處理。

核心功能

檔案讀寫與 codebase 理解

Claude Code 可以讀取你專案中的任何檔案，理解整個 codebase 的結構。當你要求它修改一個功能，它會先搜尋相關檔案（路由定義、控制器、資料模型、前端元件、測試），分析它們之間的依賴關係，再決定要改哪些地方。

這跟只看你正在編輯的檔案的工具差異很大。舉例來說，如果你說「把使用者的 email 欄位改成可選的」，它會找到 schema 定義、驗證邏輯、API 端點、前端表單、測試案例，一次把所有相關的地方都改完。

終端機命令執行

Claude Code 可以在你的終端機裡直接跑 shell 命令：

• npm install / pip install 安裝套件
• npm test / pytest 跑測試
• npm run build 建構專案
• git status / git diff 檢查狀態
• curl 測試 API 端點
• docker compose up 啟動服務

這代表它可以自己驗證修改有沒有問題。改完程式碼後跑測試、看到失敗、讀錯誤訊息、再修改，這個循環它可以自動跑到測試通過為止。

但這也是風險所在。它可以執行任何 shell 命令，包含刪除檔案、安裝不明套件、修改系統設定。這就是為什麼權限控制很重要——後面會詳細說。

Git 整合

Claude Code 原生整合 Git，包含：

• 自動建立 commit 訊息。它會讀你的 commit history 學習風格，然後用同樣的格式產生新的 commit message。
• 建立和切換 branch。你可以讓它在開始新任務前自動建 feature branch。
• 開 Pull Request。透過 gh CLI 直接從終端機開 PR，帶上標題和描述。
• 解 merge conflict。讓它看衝突的檔案，理解兩邊的修改意圖，產出合併後的版本。

在 CLAUDE.md 中寫清楚你的 Git 規範：

- 開始新任務前先建立 feature branch
- Branch 命名格式：feature/xxx 或 fix/xxx
- 不可以使用 git push --force
- 不可以直接 push 到 main 分支
- Commit 前先跑 npm test

多檔案同步編輯

Claude Code 擅長跨多個檔案的修改。典型的場景：

• 加一個新的 API 端點（路由 + 控制器 + 驗證 + 測試 + 文件）
• 重新命名一個廣泛使用的函式或變數
• 把某個功能從一個模組搬到另一個模組
• 升級框架版本並修改所有不相容的 API 呼叫

每次修改它都會顯示差異（diff），讓你確認再寫入。在 Auto-accept 模式下會直接寫入，所以搭配 Git 使用很重要——改壞了可以 revert。

專案理解與上下文

Claude Code 啟動時會建立對你專案的理解。它會看 package.json、tsconfig.json、目錄結構、README、CLAUDE.md 這些檔案，來搞清楚你用什麼框架、什麼語言、什麼慣例。

你可以進一步用 Slash Command 幫助它理解：

• /init — 初始化 CLAUDE.md，Claude Code 會分析你的專案並自動產生初始版本
• /plan — 進入計畫模式，只規劃不執行，你看完計畫確認後再讓它動手

權限模型與安全邊界

Claude Code 的權限模型是安全使用的核心。它決定了 Claude Code 在你的系統上可以做什麼、不可以做什麼。

三種權限模式

Ask 模式（預設）。每個有風險的操作都會先問你——寫入檔案、執行 shell 命令、Git 操作。你看清楚它要做什麼再決定允許或拒絕。這是最安全的模式，代價是互動比較多，每個步驟都要手動確認。

Auto-accept 模式。讀取和寫入檔案自動允許，但 shell 命令仍然需要確認。適合你信任 Claude Code 的檔案操作，只想控制它執行什麼命令的情況。可以在互動介面裡按 Tab 切換。

Headless 模式。所有操作自動執行，不需要人類確認。專門用於 CI/CD pipeline 和自動化流程，例如在 GitHub Actions 中自動 review PR 或自動修復 lint 錯誤。這個模式不適合日常開發使用。

權限設定檔

在專案的 .claude/settings.json 中設定細粒度的權限：

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)",
      "Bash(curl *)"
    ]
  }
}

allow 清單裡的操作會自動通過，不用手動確認。deny 清單裡的操作會被直接拒絕。沒在任何清單裡的操作會照預設的模式處理（Ask 模式下會問你）。

.claude 目錄

.claude 目錄是 Claude Code 的設定目錄，放在專案根目錄下。裡面可以包含：

• settings.json — 專案層級的設定（權限、Hooks 等）
• 其他 Claude Code 產生的設定檔

這個目錄應該 commit 到版本控制中，讓團隊共用同一套設定。

CLAUDE.md 作為專案指令

CLAUDE.md 的功能不只是說明文件，它是 Claude Code 的行為指令。你在裡面寫的規則，Claude Code 會把它當作約束來遵守。

例如寫「不可以直接修改 production 資料庫」「所有 SQL query 必須使用 parameterized query」「不要安裝未經批准的 npm 套件」，Claude Code 在執行任務時會盡量遵守這些指令。

但要注意：CLAUDE.md 是指導，不是硬性限制。Claude Code 可能在某些情況下偏離這些指令，特別是指令之間有衝突的時候。它不能取代權限模型的設定——真正的安全邊界要靠 settings.json 的 deny 清單來實現。

實際使用場景

Code Review

讓 Claude Code 審查目前分支的修改：

claude
> /code-review

或指定審查某個 PR：

claude "review PR #42 的修改，特別注意安全問題"

它會讀取 diff、分析每個修改、指出潛在問題。飛飛的經驗是，它對語法錯誤、型別問題、明顯的安全漏洞（SQL injection、XSS、硬編碼密碼）的偵測率很高，但對商業邏輯正確性和架構決策的判斷能力有限。AI Code Review 是額外的防線，不能取代人類 reviewer。

Debug

把錯誤訊息貼給它：

claude "這個錯誤怎麼修：TypeError: Cannot read properties of undefined (reading 'map')"

它會在你的 codebase 中搜尋相關的程式碼、分析錯誤原因、提出修改方案。如果你允許它修改檔案和跑測試，它可以自己改完再驗證。

重構

claude "把 src/utils/helpers.js 裡的 formatDate 函式重構成 TypeScript，並更新所有使用到這個函式的檔案"

重構是 Claude Code 最能發揮的場景之一。它可以追蹤一個函式在整個 codebase 中被使用的地方，一次改完所有檔案，確保型別和介面的一致性。

寫測試

claude "幫 src/services/auth.ts 寫單元測試，涵蓋正常登入、密碼錯誤、帳號被鎖定三種情境"

它會看你現有的測試怎麼寫（用什麼測試框架、什麼斷言風格），然後用同樣的模式產生新的測試。比起從頭寫測試，這能省下很多時間，但你要自己檢查它有沒有涵蓋到所有 edge case。

文件產生

claude "幫這個專案的 API 端點產生 OpenAPI 文件"

它可以讀所有的 route 定義和 controller，產出結構化的 API 文件。也可以幫你寫 README、更新 CHANGELOG、產生 JSDoc 註解。

Migration 輔助

claude "把這個專案從 Express.js 4 升級到 5，處理所有 breaking changes"

框架升級是費時的苦工。Claude Code 可以讀 migration guide、找到受影響的程式碼、逐一修改。但大型 migration 建議用 /plan 先看計畫、分批處理，不要一次讓它改整個專案。

Claude Code vs 其他 AI 開發工具

選擇的判斷方式：

如果你習慣在終端機工作、做的是跨多個檔案的修改（重構、migration、功能開發），Claude Code 最適合。如果你想要視覺化的編輯體驗和即時的 inline 編輯，Cursor 比較直覺。如果你主要需要寫程式碼時的即時補全建議，GitHub Copilot 就夠用。如果你只是想問 AI 一段程式碼怎麼寫、不需要它直接改你的檔案，ChatGPT 的網頁介面就可以。

三個本機工具可以搭配使用。在 VS Code 裡用 Copilot 做即時補全，遇到跨多個檔案的複雜任務切到 Claude Code 處理。

企業使用的安全考量

程式碼傳輸與儲存

Claude Code 透過 Anthropic 的 API 傳輸你的程式碼來處理。Anthropic 在 API 使用條款中承諾：透過 API 傳送的資料不會用於模型訓練，也不會被 Anthropic 的員工查看，除非使用者回報問題或偵測到違規行為。API 資料在傳輸過程中和靜態儲存時都有加密，並且在一定期限後刪除。

但這仍然代表你的程式碼會經過 Anthropic 的伺服器。如果企業的資安政策不允許程式碼離開內部環境，有兩個替代方案：

透過 Amazon Bedrock 使用。Claude 模型部署在你的 AWS 帳號中，程式碼不會離開你的 VPC。

透過 Google Vertex AI 使用。類似 Bedrock，在你的 GCP 帳號中處理。

這兩種方式的好處是程式碼只在你自己的雲端環境中處理，缺點是設定比較複雜，而且可能有額外的費用。

API 金鑰管理

企業環境中管理 API 金鑰的建議做法：

• 每個開發者用獨立的 API 金鑰，不共用。這樣可以追蹤誰用了多少 Token、做了什麼操作。
• CI/CD 用專門的 API 金鑰，跟個人帳號分開。
• 設定每個金鑰的用量上限（Spending Limit），避免某個自動化任務跑飛導致高額帳單。
• 金鑰存放在 Secret Manager（AWS Secrets Manager、GCP Secret Manager、HashiCorp Vault）中，不要寫在設定檔裡。
• 定期輪換金鑰，至少每 90 天一次。

團隊權限政策

統一團隊使用 Claude Code 的方式：

把 CLAUDE.md、.claudeignore、.claude/settings.json 都 commit 到 repo 中。這確保每個成員的 Claude Code 遵循同樣的規範——哪些檔案不能讀、哪些命令不能跑、程式碼風格要怎麼寫。

制定一份 Claude Code 使用政策，釐清哪些專案可以用、哪些不行。例如：前端 UI 和工具腳本可以用，核心的加密模組和支付邏輯不用。

稽核與記錄

Claude Code 的每次對話都有記錄，可以透過 claude --resume 查看歷史。在企業環境中，搭配 API 的使用記錄（哪個金鑰、什麼時間、消耗多少 Token），可以追蹤 AI 工具的使用狀況。

如果用 Bedrock 或 Vertex 部署，還可以透過 CloudTrail 或 Cloud Audit Logs 取得更詳細的稽核記錄。

合規性考量

在決定導入 Claude Code 之前，需要評估的合規面向：

• 資料處理合約（DPA）。如果你的程式碼包含個人資料（使用者名稱、email 在測試資料中），確認 Anthropic 的 DPA 符合你的 GDPR 或個資法要求。
• 產業法規。金融業、醫療業等受監管產業，程式碼中可能包含受保護的商業邏輯或資料處理流程，確認外部 AI 處理是否合規。
• 智慧財產權。AI 產出的程式碼的著作權歸屬，目前各國法律仍在發展中，企業需要有自己的立場。
• 供應鏈安全。Claude Code 可能建議安裝第三方套件，每個新套件都是供應鏈攻擊的潛在入口。

使用技巧與最佳實踐

給清楚的指令

跟 Claude Code 溝通時，指令越具體效果越好。

模糊的指令：「改善這個程式碼」

具體的指令：「把 src/services/auth.ts 裡的 login 函式重構。目前它同時做驗證、查資料庫、產 token 三件事，拆成三個獨立函式。保持現有的測試都能通過。」

告訴它你要什麼、改哪裡、有什麼限制。Claude Code 不是通靈的，它讀得到你的程式碼但讀不到你的意圖。

善用 CLAUDE.md

CLAUDE.md 的內容可以包含：

• 技術棧和框架版本
• 程式碼風格和命名慣例
• 目錄結構說明
• 禁止的操作（不要改某些檔案、不要用某些套件）
• Commit 訊息格式
• 測試規範
• 部署流程

越詳細的 CLAUDE.md，Claude Code 的產出品質越好。飛飛建議花 30 分鐘把你的專案規範寫進 CLAUDE.md，這能省下大量事後修正的時間。

用 Plan Mode 處理複雜任務

面對大型任務（框架升級、架構重構、新功能開發），先用 /plan 讓 Claude Code 規劃再動手：

claude
> /plan 把專案從 React 17 升級到 18，列出所有需要修改的地方

看完計畫確認合理再讓它執行。這比直接讓它動手然後發現改錯方向，效率高很多。

善用模型切換

不同任務用不同模型：

• Opus：複雜的架構設計、大型重構、需要深度思考的問題
• Sonnet：日常 bug 修復、功能開發、Code Review
• Haiku：格式調整、簡單的程式碼產生、快速問答

用 --model 參數或在互動模式中切換。日常任務用 Sonnet 可以省下不少費用。

什麼時候不該用 Claude Code

不是所有任務都適合用 Claude Code：

處理高度機密的程式碼。核心的加密演算法、支付處理邏輯、安全機制的實作，這些程式碼的洩漏風險遠高於生產力的提升。

做最終的安全決策。Claude Code 可以幫你找漏洞，但安全架構的決策、加密方案的選擇、權限模型的設計，這些應該由有經驗的安全工程師或資安團隊負責。

處理你不理解的領域。如果你看不懂它寫的程式碼，就沒辦法判斷正確性和安全性。用 Claude Code 的前提是你有能力 review 它的產出。

安全注意事項

Claude Code 是一個有實際操作能力的工具，而且它的操作在你的本機執行。以下是你需要意識到的具體風險。

檔案系統存取

Claude Code 可以讀取和寫入你啟動它的目錄下的所有檔案。如果你在 home 目錄（~）啟動，它可以讀到 .ssh/ 裡的私鑰、.aws/ 裡的 AWS 憑證、.gnupg/ 裡的加密金鑰、瀏覽器的 profile 目錄中的 cookies 和密碼。

防範做法：永遠在特定的專案目錄中啟動 Claude Code，不要在 home 目錄或根目錄啟動。用 .claudeignore 排除敏感檔案。

命令執行風險

Claude Code 可以在你的終端機裡執行任何 shell 命令。這包含：

• rm -rf 刪除檔案（可能刪到不該刪的東西）
• npm install 安裝套件（可能引入有惡意程式碼的套件）
• curl 下載檔案（可能從不信任的來源下載執行檔）
• docker 操作（可能影響你的容器環境）
• chmod 修改權限（可能讓檔案變成全域可讀）

防範做法：保持 shell 命令的手動確認（不要設成 auto-accept），在 deny 清單中列出危險的命令模式。看清楚每個命令再放行。

API 金鑰外洩

API 金鑰外洩的常見情境：

• 把 API 金鑰寫在 .env 中，Claude Code 讀到後透過 API 傳出去
• Claude Code 在 debug 過程中印出環境變數的值
• Claude Code 在 commit 中包含了含有金鑰的設定檔

防範做法：.claudeignore 排除所有含有金鑰的檔案。在 CLAUDE.md 中寫明「不要讀取或輸出任何 API 金鑰、密碼或 Token」。定期用 git-secrets 或 truffleHog 掃描 repo。

敏感檔案處理

有些檔案不應該經過外部 API 處理：

• 含有客戶個資的測試資料
• 內部的安全稽核報告
• 尚未公開的商業策略文件
• 受 NDA 保護的合約或技術文件

用 .claudeignore 排除這些檔案。如果 Claude Code 需要理解某個設定的結構來 debug，給它一個不含真實值的範本（.env.example），不要讓它讀真實的設定檔。

Prompt Injection

如果你的 codebase 中有使用者可控的內容（例如使用者上傳的檔案、資料庫中的使用者輸入），Claude Code 在讀取這些內容時可能被 Prompt Injection 影響。攻擊者可以在這些內容中嵌入指令，讓 Claude Code 執行非預期的操作。

這是一個進階的風險，但在處理使用者產生的內容（UGC）或外部資料時值得注意。

常見問題

參考資料

• Claude Code 官方文件 — docs.anthropic.com
• Claude Code GitHub — github.com/anthropics/claude-code
• Anthropic API 使用條款 — anthropic.com/policies
• Anthropic 商業條款 — anthropic.com/commercial-terms