Claude Code 詳細實戰手冊

繁體中文版本。本手冊根據 Anthropic 官方 Claude Code 文件及其關聯學習頁面重新編寫，並按真實開發流程整理。內容不是網站逐頁複製，而是包含可直接修改的指令、設定、提示詞、工作流程和排錯範例。

1. Claude Code 是甚麼

Claude Code 是智能體式程式開發工具，可以理解程式碼庫、編輯檔案、執行指令，並連接開發工具。應按資料位置和任務需要選擇介面。

2. 安裝與首次啟動

# macOS、Linux 或 WSL 原生安裝
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew 穩定頻道
brew install --cask claude-code

# Windows WinGet
winget install Anthropic.ClaudeCode

cd ~/projects/example-app
claude

# 檢查安裝及登入
claude doctor
claude auth status --text

應從真正需要處理的程式碼庫或套件目錄啟動。目錄過高會引入雜訊；目錄過深則可能看不到專案級指引。

3. 編寫可以完成的任務

清楚交代目標、相關背景、限制和完成證據。陌生或高風險工作應先探索和規劃，再批准實作。

含糊要求

修正結帳功能。

可執行提示詞

目標：避免客戶重試付款時產生重複訂單。

背景：
- 結帳處理：src/checkout/submit.ts
- 付款用戶端：src/payments/client.ts
- 重現：兩個相同 idempotency key 的要求建立兩張訂單

限制：
- 保留現有 API 回應
- 沿用現有交易輔助函式
- 不修改無關格式

完成條件：
- 加入並行重試的回歸測試
- 相關結帳測試通過
- 說明根本原因及修改檔案

只要求規劃

探索登入及工作階段更新流程，現在不要編輯檔案。
列出請求路徑、競爭情況及保安邊界，再提出包含測試和回退考慮的方案。
等待我確認才開始實作。

4. 有意識地使用智能體循環

1. 收集背景：找出入口、測試、慣例和未提交修改。
2. 選擇方案：含糊、架構性或高風險修改使用規劃模式。
3. 執行：保持修改範圍小而完整。
4. 驗證：執行測試、查看真實輸出並審閱差異。

為我建立這個程式碼庫的導覽圖。指出運行入口、主要資料流、測試策略、
設定層，以及最值得先閱讀的三個檔案。引用路徑，不要修改內容。

修正前先重現逾時問題。追蹤一個失敗要求，檢查附近日誌和測試，
分開已確認事實和假設。只有證據支持根本原因後才作最小修正。

先執行最小範圍測試，通過後再執行完整測試。
介面修改要打開真實流程，檢查畫面、互動、響應式版面及主控台錯誤。
HTTP 200 並不是視覺驗證。

5. 管理內容視窗

內容視窗包含對話、工具結果、檔案、指引、Skills 等資料。一個工作階段應集中處理一個完整目標；目標改變時開新工作階段，內容過長則使用有焦點的壓縮。

/context
/compact 保留已批准方案、修改檔案、失敗測試及下一步。
/clear

以 @path/to/file 或 IDE 選取範圍提供高價值資料，避免在幾個入口和測試已足夠時讀取整個程式碼庫。

6. 使用 CLAUDE.md 保存長期指引

CLAUDE.md 是團隊編寫的指引；自動記憶是 Claude 跨工作階段保存的學習。兩者都會影響行為，但不是硬性保安控制。

# 專案指引

## 指令
- 安裝：npm ci
- 單元測試：npm test
- 端到端測試：npm run test:e2e
- 程式碼檢查：npm run lint

## 架構
- HTTP 處理器位於 src/api/handlers/。
- 商業規則放在 src/domain/，不得匯入介面模組。

## 交付規則
- 保留任務範圍以外的使用者修改。
- 每次錯誤修正加入回歸測試。
- 未獲明確要求不得部署或推送。
- 交付時列出實際執行過的指令。

/init
/memory
/context

只適用於指定路徑的規則

---
paths:
  - "src/api/**/*.ts"
---

# API 規則
- 驗證所有外部輸入。
- 使用共用錯誤回應輔助函式。
- 為授權邊界加入整合測試。

已有 AGENTS.md 的程式碼庫，可以在 CLAUDE.md 以 @AGENTS.md 匯入，再加入 Claude 專用指引。

7. 設定、權限與沙箱

Claude Code 會合併管理、使用者、專案及本機設定。團隊共用設定可以提交至版本控制；個人或機器專用資料則放在本機設定。權限規則可以允許、詢問或拒絕工具及指令模式。

{
  "permissions": {
    "allow": ["Bash(npm test:*)", "Bash(npm run lint:*)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"]
  },
  "sandbox": {"enabled": true}
}

8. 以 Skills 封裝重複流程

.claude/skills/release-check/
└── SKILL.md

---
name: release-check
description: 部署前驗證網站版本。
---

# 版本檢查
1. 執行單元及整合測試。
2.建立正式版本。
3. 用瀏覽器檢查主要流程。
4. 總結風險和阻礙。
5. 未獲明確要求不得部署。

多步工作流程使用 Skill；長期專案事實使用 CLAUDE.md；必須機械執行的動作使用 Hook。

9. 使用子智能體分工

子智能體擁有獨立內容，亦可限制工具。適合獨立研究、審閱、測試或專業分析。每項工作應有清楚而有限的輸出。

---
name: security-reviewer
description: 審閱修改中可被利用的保安問題。
tools: Read, Grep, Glob, Bash
model: inherit
---

只審閱已修改程式碼及可達資料流。
按嚴重程度列出檔案、行數、利用情境、證據及最小修正。
不要編輯檔案。

讓 security-reviewer 子智能體審閱目前差異；你同時執行相關測試。
報告前將審閱發現與測試證據互相核對。

10. 使用 Hooks 自動執行守則

Hooks 可在 Claude Code 事件前後執行格式化、阻擋危險指令、驗證檔案、記錄事件或發送完成通知。正式使用前要獨立測試 Hook 指令。

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }]
    }]
  }
}

11. MCP 與插件

MCP 連接外部工具及資料；插件把 Skills、子智能體、Hooks 和 MCP 設定組合成可安裝套件。私人系統應使用已授權連接，並只給予所需能力。

claude mcp add --transport http project-docs https://mcp.example.com
claude mcp list

# 工作階段內
/mcp

/plugin marketplace add example-org/claude-plugins
/plugin install code-review@example-marketplace

安裝前檢查插件來源、工具權限、Hook 指令及 MCP 目的地。

12. 工作階段與平行工作

claude --continue
claude --resume
claude --resume auth-refactor

/rename auth-refactor
/branch try-streaming-approach

多項平行任務應命名工作階段。分支對話可嘗試另一方案而不影響原對話；不要在兩個終端機同時恢復同一工作階段。

claude --worktree dependency-upgrade

# 一個工作階段升級依賴，另一個審閱介面修改；
# 最後在主要目錄整合並執行端到端測試。

13. 無介面執行與 CI

claude -p "審閱目前差異的正確性和保安風險，不要編輯檔案。"

claude -p --output-format json \
  "執行相關測試並回傳簡短失敗摘要。" \
  > claude-result.json

git diff main --name-only | claude -p \
  "指出需要保安審閱的修改檔案並解釋原因。"

# 在程式碼庫工作階段內設定 GitHub Actions
/install-github-app

無人值守工作必須限制工具、成本或輪次、輸出格式及失敗行為；CI 不應取得超出任務需要的程式碼庫或秘密資料權限。

14. 瀏覽器、桌面端、網頁及遠端

在 Chrome 開啟本機應用程式，重現結帳失敗，檢查畫面和主控台，
再於桌面及流動裝置寬度驗證修正。不要提交真實付款或修改正式資料。

本機工作階段可存取本機檔案和工具；雲端工作使用隔離環境和已連接的程式碼庫。選擇介面前先確認資料在哪裡，以及任務需要甚麼權限。

15. 排錯清單

1. 執行 claude doctor 檢查安裝及設定。
2. 以 claude auth status --text 分開登入和專案問題。
3. 用 /context 確認 CLAUDE.md、規則及 Skills 已載入。
4. 使用 /permissions、/hooks 或 /mcp 檢查相應系統。
5. 檢查專案及本機設定有否無效 JSON 或衝突。
6. 診斷啟動問題時暫停插件和 MCP。
7. 內容累積過多時使用新的聚焦工作階段。
8. 修改全域設定前記錄精確指令、錯誤、版本、作業系統及最小重現。

只進行診斷，不要修改檔案或設定。重現問題、記錄確實失敗步驟，
檢查有效設定及最近日誌，並按證據排列可能原因。
清楚標示已確認事實和假設。

16. 官方資料來源

本手冊逐頁整理 Anthropic 官方的完整文件索引、快速開始、常用流程、最佳實務、CLAUDE.md 與記憶、權限、沙箱、Skills、子智能體、Hooks、MCP、工作階段、Worktree、程式化使用、GitHub Actions及排錯等頁面。

編輯日期：2026 年 8 月 11 日。版本敏感的指令、方案供應、模型行為或政策，使用前應再次核對官方頁面。