Claude Code 教學：如何在 VS Code 中設定 Hooks 與 Subagents 實戰

讀完這篇教學，你會知道如何在 VS Code 中設定 claude code vscode extension，並透過實戰操作學會 claude code hooks 怎麼用 與 claude code subagents 設定，把 AI 從單純的程式碼生成工具，變成能自主執行複雜任務的開發副手。

多數開發者卡關的地方，不是裝好擴充功能，而是不知道怎麼設定 claude code subagents 設定 跟 claude code hooks 怎麼用。這篇文章會帶你走完整個流程，從安裝到建立自動化開發流程。

查看相關日報

什麼是 Claude Code？核心概念與價值

Claude Code 不是聊天機器人，而是 Anthropic 為軟體開發者設計的代理程式（Agent）介面。它能執行命令、讀取檔案系統，並與開發環境深度互動。開發者用自然語言描述專案需求，AI 會自動規劃執行步驟，甚至主動呼叫終端機指令完成任務。

學習 claude code vscode extension 的重點在於「自主性」。過去你得手動複製貼上程式碼、手動跑測試、手動修錯誤；現在你可以授權 AI 在特定範圍內自己動手做。核心概念是把開發者的意圖轉成可執行的行動序列，而不只是給文字建議。

但自主性一旦擴大，控制就變得重要。這正是 claude code hooks 怎麼用 與 claude code subagents 設定 存在的理由：透過 Subagents（子代理），你可以把大型專案拆成多個專精角色，例如一個顧前端、一個顧後端、一個顧測試，各自帶著自己的提示詞與工具權限分工合作。Hooks 則是掛在 Claude Code 生命週期事件上的 shell 指令——工具執行前後、送出提示時、session 開始或結束時自動跑你指定的腳本。兩者的差別是：subagent 由 Claude 決定什麼時候委派，hook 則不管 Claude 怎麼想，時間到就一定會執行。這套架構讓你能精準畫出 AI 的行為邊界。

事前準備：環境配置與工具安裝

這一步直接影響後續 claude code vscode extension 的穩定性與功能完整性，別跳過。

VS Code 系統需求與相容性檢查

官方文件列的先決條件只有兩項：VS Code 1.94.0 或更新版本，以及一個 Anthropic 帳號——任一付費 Claude 訂閱（Pro、Max、Team、Enterprise）或 Claude Console 帳號都可以，不需要 API Key。

擴充功能本身內建了一份 Claude Code CLI 供聊天面板使用，所以只裝擴充功能不必另外處理 Node.js。但如果你想在 VS Code 的整合式終端機直接打 claude 指令，就要另外安裝獨立版 CLI。

官方沒有公布 RAM 或 CPU 的建議值，這部分請依自己的專案規模斟酌。

安裝 Claude Code 擴充功能與建立 Anthropic 帳號

開啟 VS Code 的「擴充功能」視窗（Extensions View，Cmd+Shift+X / Ctrl+Shift+X），搜尋「Claude Code」。務必確認發布者是 Anthropic 官方（擴充功能識別碼為 anthropic.claude-code），避免裝到來路不明的第三方套件。

Cursor、Devin Desktop、Kiro 這類 VS Code 分支也裝得起來，在編輯器內搜尋「Claude Code」，或從 Open VSX registry 安裝。

若還沒有帳號，先辦一個付費 Claude 訂閱或 Claude Console 帳號。第一次打開面板時會出現登入畫面，點「Sign in」在瀏覽器完成授權即可，整個流程不需要 API Key。

小提醒：如果你的 shell 裡設了 ANTHROPIC_API_KEY 卻還是看到登入畫面，通常是 VS Code 沒繼承到 shell 環境變數。從終端機用 code . 啟動 VS Code，或直接用 Claude 帳號登入就好。

Step 1：安裝與基本設定流程

擴充功能裝好後，進入核心設定階段，這是掌握 claude code vscode extension 的關鍵，也是後續設定 Hooks 的基礎。

首次登入與面板操作

1. 點擊側邊欄的 Claude Code 圖示打開面板（也可以用 Command Palette 搜「Claude Code」）。
2. 第一次會看到登入畫面，點「Sign in」，瀏覽器會開起來讓你完成授權。
3. 授權完成回到 VS Code，面板會出現「Learn Claude Code」的上手清單，可以逐項點「Show me」跟著做，或直接用 X 關掉。

登入後就能直接對話。在編輯器選取一段程式碼，Claude 會自動看到你選的內容；按 Option+K（Mac）/ Alt+K（Windows、Linux）可以把帶行號的檔案引用（例如 @app.ts#5-10）插進提示框。

設定檔是 .claude/settings.json，不是 config.json

這是最多教學文章寫錯的地方，也是最難自己發現的地方——參數名稱寫錯不會報錯，設定只是靜靜地不生效。

Claude Code 的設定檔叫 settings.json。官方列出的位置與優先序（高到低）是：

| 層級 | 檔案 | 影響範圍 |

| --- | --- | --- |

| 受管理設定 | managed-settings.json／MDM | 整個組織 |

| 指令列 | claude --settings | 只有這次 session |

| 專案個人 | .claude/settings.local.json | 只有你、只有這個專案（不進版控） |

| 專案共用 | .claude/settings.json | 專案所有人（要 commit） |

| 使用者 | ~/.claude/settings.json | 你的所有專案 |

在專案根目錄建立 .claude 資料夾（已存在就直接用），新增 settings.json：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

model 可以填模型別名（default、sonnet、opus、haiku、fable、opusplan、best）或完整模型名稱（例如 claude-opus-5）。$schema 那行指向官方發布的 JSON Schema，VS Code、Cursor 這類支援 JSON Schema 的編輯器會給你自動完成與即時驗證。

⚠️ temperature、max_tokens、system_prompt、exclude_paths 這四個鍵在 Claude Code 的設定檔裡都不存在。 寫進去不會報錯，但完全不會生效。對應的正確做法是：

• 想給 AI 專案層級的行為準則（原本以為是 system_prompt 的用途）→ 寫在專案根目錄的 CLAUDE.md 或 .claude/CLAUDE.md。Claude Code 每個 session 開始時會自動載入它，也會載入工作目錄往上每一層的 CLAUDE.md。用 /init 可以請 Claude 掃過 codebase 幫你生一份起手式，用 /context 可以確認到底載入了哪些檔案。
• 想把含密碼、金鑰或個資的檔案排除在 AI 讀取範圍外（原本以為是 exclude_paths）→ 用 permissions.deny 加 Read 規則，例如 Read(./.env)、Read(./secrets/**)。官方文件註明 Read 的 deny 規則同時會擋掉 Edit 與 Write 對同一路徑的操作；規則的評估順序是 deny → ask → allow，先命中先算。
• 取樣參數（temperature、max_tokens）不開放在設定檔調整。

小提醒：Read deny 規則管得住 Claude 的檔案工具，以及它在 Bash 裡跑的 cat、head、tail、sed；但管不住 Python 或 Node 腳本自己開檔案讀。要作業系統層級的隔離，得另外開 sandbox。

Step 2：第一個實作範例 - 建立 Subagents

基本設定完成後，進入最實戰的部分：建立 Subagents（子代理）。這是 claude code subagents 設定 的核心應用，能把單一 AI 的能力擴展成團隊協作模式。

Subagents 是 Markdown 檔，不是 JSON

Claude Code 沒有 subagents.json 這個檔案。 官方格式是「帶 YAML frontmatter 的 Markdown 檔」，一個 subagent 就是一個 .md 檔，放在：

| 位置 | 生效範圍 |

| --- | --- |

| .claude/agents/ | 目前這個專案 |

| ~/.claude/agents/ | 你所有的專案 |

| 受管理設定 | 整個組織 |

| --agents CLI 參數 | 只有這次 session |

| 外掛的 agents/ 目錄 | 啟用該外掛的地方 |

以前端專家為例，建立 .claude/agents/frontend-specialist.md：

---
name: frontend-specialist
description: 前端開發專家，負責 React 元件優化與 CSS 樣式調整
tools: Read, Glob, Grep, Edit
model: sonnet
---

你是前端開發專家，專注於 React 元件優化與 CSS 樣式調整。
遇到複雜的 UI 問題時，先說明你打算怎麼驗證使用者體驗，再動手改。

frontmatter 只有 name 與 description 兩個必填欄位。其餘可選欄位包含 tools（允許的工具）、disallowedTools（禁止的工具）、model、permissionMode、maxTurns、skills、mcpServers、memory、background、effort、isolation、color。

⚠️ role、scope、instructions 這三個欄位不存在。 角色描述寫在 description，行為指示寫在 frontmatter 底下的 Markdown 正文（那就是這個 subagent 的 system prompt）。想限制它能碰哪些檔案，不是寫 scope，而是用 tools / disallowedTools 縮限工具，再搭配 .claude/settings.json 的 permissions 規則限制路徑。

後端與測試的角色同理，各建一個 .claude/agents/backend-specialist.md 與 .claude/agents/qa-engineer.md 即可。

預期執行結果與除錯技巧

設定完成後，有三種叫用方式：

1. 自然語言：直接在對話裡點名，例如「用 frontend-specialist subagent 優化首頁的載入速度」。
2. @-mention：輸入 @ 從跳出的清單選，或手動打 @agent-frontend-specialist。
3. 整個 session 指定：claude --agent frontend-specialist，或在 .claude/settings.json 寫 "agent": "frontend-specialist"。

⚠️ 注意第 2 種寫法的前綴是 @agent-，不是 @frontend-specialist。

預期結果：Claude 把任務交給該 subagent，它在自己的 context 裡讀檔、分析效能瓶頸，提出優化建議或直接改。

除錯技巧：Subagent 沒被叫到或做不了事時，檢查這三點：

1. 檔案位置與副檔名：確認檔案在 .claude/agents/ 底下且是 .md，frontmatter 的 --- 分隔線完整。
2. description 寫得夠不夠具體：Claude 是靠 description 判斷什麼時候該把任務交出去，寫太籠統就不會被選中。
3. 工具被關掉了：檢查 frontmatter 的 tools / disallowedTools，以及 .claude/settings.json 的 permissions.deny——deny 規則優先於 allow。

若 Claude 拒絕執行某些動作，先看是不是命中了 permissions 的 deny 或 ask 規則，而不是去改提示詞。

Step 3：進階技巧 - Hooks 怎麼用與最佳實踐

掌握 Subagents 後，接著是 claude code hooks 怎麼用 的進階應用。Hooks 定義 AI 在特定事件發生時的自動反應機制，把開發流程從「被動回應」變成「主動預防」。

Hooks 寫在 settings.json 裡，不是獨立的 hooks.json

跟 subagents 一樣，你自己的 hooks 沒有專屬檔案（唯一的例外是外掛自帶的 hooks/hooks.json）。它們寫在設定檔的 hooks 鍵底下：~/.claude/settings.json、.claude/settings.json 或 .claude/settings.local.json。

結構是「事件名稱 → matcher → handler 陣列」：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-eslint.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git commit *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/secret-scan.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

有三件事是虛構教學最常寫錯的，而且錯了都不會報錯：

1. 事件名稱是固定字串，不能自己造。 官方目前列出的事件有：SessionStart、Setup、SessionEnd、UserPromptSubmit、UserPromptExpansion、Stop、StopFailure、PreToolUse、PostToolUse、PostToolUseFailure、PostToolBatch、PermissionRequest、PermissionDenied、SubagentStart、SubagentStop、TeammateIdle、TaskCreated、TaskCompleted、FileChanged、CwdChanged、DirectoryAdded、ConfigChange、InstructionsLoaded、WorktreeCreate、WorktreeRemove、PreCompact、PostCompact、Notification、MessageDisplay、Elicitation、ElicitationResult。像 on_file_change、on_test_failure、on_commit 這種寫法不會被辨識——設定檔照樣讀得進去，但 hook 一次都不會觸發。
2. 沒有 action 欄位，也沒有 run_linter、security_scan 這種內建動作。 handler 的 type 可以是 command（跑你自己的腳本或執行檔）、http、mcp_tool、prompt、agent。要跑 ESLint 就自己寫一支 shell script，用 command 指過去。
3. 也沒有 path 欄位。 篩選靠的是 matcher（比對工具名稱，例如 Edit|Write、Bash、mcp__memory__.*、*）與可選的 if（權限規則字串，例如 Bash(rm *)）。要限定檔案路徑，就在自己的腳本裡讀 hook 傳進來的輸入自行判斷。

想一次關掉全部 hooks，在設定檔加 "disableAllHooks": true。

效率提升策略與常見陷阱避免

在 PreToolUse 上掛 if: "Bash(git commit *)" 的安全掃描，等於在每次提交前多一道自動檢查，避免敏感資訊外洩。

效率提升策略：

• 分層設定：把開發時要跑的（PostToolUse 配 Edit|Write）與提交時才跑的（PreToolUse 配 Bash + if）分開，避免寫 code 時被打斷。
• 用個人層設定試新 hook：先寫進 .claude/settings.local.json（不進版控）驗證行為，穩定了再搬到 .claude/settings.json 給團隊共用。

常見陷阱：

• 以為有執行順序可以調：官方文件寫明「所有比對到的 hooks 平行執行」，沒有 priority 這種欄位。有先後依賴關係的檢查，就寫在同一支腳本裡依序跑。
• 腳本自己改檔案又觸發自己：PostToolUse 的腳本若去改檔案，可能繞回來再觸發一次。Claude Code 沒有 max_iterations 這類欄位可以限制，要在自己的腳本裡加防護（例如寫一個 lock 檔，或跳過由 hook 自己產生的變更）。
• 卡住不動：command、http、mcp_tool 的 timeout 預設是 600 秒，但 UserPromptSubmit 事件會把它降到 30 秒、MessageDisplay 降到 10 秒。長工作可以加 "async": true 丟到背景不擋主流程；想讓它結束時叫醒 Claude，用 "asyncRewake": true（結束碼 2 時把 stderr 餵給 Claude）。
• 資源消耗：Hook 跑太頻繁會吃資源。開發環境可以先關掉非必要的，只在 CI/CD 啟用。

常見問題 FAQ

如何解決 API 連線不穩定的問題？

先檢查網路連線，再確認登入狀態是否還有效（在面板重新 Sign in 一次）。⚠️ 網路上常見的 retry_policy 參數在 Claude Code 的設定檔裡不存在，寫進 .claude/settings.json 不會生效。設定檔本身叫 settings.json 而不是 config.json，可以在檔案第一行加 "$schema": "https://json.schemastore.org/claude-code-settings.json"，讓編輯器直接標出打錯或不存在的鍵。另外，如果 shell 有設 ANTHROPIC_API_KEY 卻一直跳登入畫面，改用 code . 從終端機啟動 VS Code。

Hooks 的執行順序可以指定嗎？

官方文件寫明「所有比對到的 hooks 平行執行」，沒有 priority 欄位可以指定順序。同一個 handler 就算寫在多個設定檔裡也只會跑一次（外掛與 skill 帶的副本另計）。有先後依賴的檢查——例如要先掃安全再檢查程式碼風格——就把兩步寫進同一支腳本依序執行，不要指望設定檔幫你排序。至於 subagent，它是被 Claude 主動委派或你點名叫用的，不參與 hook 的觸發排序。

用 Claude Code 需要付費嗎？

Claude Code 沒有獨立的免費方案，它包在 Claude 訂閱裡。依 Anthropic 官方定價頁：Free（$0）不含 Claude Code；Pro 明列「Includes Claude Code」，年繳每月 $17、月繳 $20；Max 5x 與 Max 20x 從每月 $100 起，同樣包含。團隊方案的 Standard 與 Premium 座位也都含 Claude Code。VS Code 擴充功能接受任一付費訂閱（Pro、Max、Team、Enterprise）或 Claude Console 帳號登入，不需要 API Key。定價會調整，設定前建議先看一次官網 Pricing 頁。

下一步：深化你的 AI 開發能力

這篇教學帶你走完 claude code vscode extension 的安裝、設定與實戰應用，也學會了 claude code subagents 設定 與 claude code hooks 怎麼用 的具體操作方式。

接下來，建議把這些設定套用到手上的實際專案，依專案需求微調 Subagents 與 Hooks 的參數。Anthropic 的更新速度快，隔一陣子回來看官方文件，可能會發現新的設定選項或行為變化。

AI 能自主執行任務，不代表它該擁有最終決策權。設定好邊界、盯緊執行結果，才是用好這套工具的關鍵。