Claude Code v2.1.323 實戰：打開實驗性 Code Mode，讓 Claude 寫 JS 一次跑完工具；外掛用 engines 鎖版本

v2.1.323 加入實驗性 Code Mode：Claude 不再一個一個呼叫工具，而是寫一段 JavaScript 去叫工具、只把結論帶回 context。本文整理怎麼開、怎麼關、哪些情境還不能用，以及外掛作者怎麼用 plugin.json 的 engines 宣告相容版本。

AI Academy 編輯部2026年11月13日
本文目錄（9 節）▾
  1. 一、為什麼值得關注：工具呼叫的兩個隱形成本
  2. 二、Code Mode 的運作原理
  3. 三、手把手：怎麼打開、怎麼確認、怎麼關掉
  4. 四、讓 Code Mode 發揮的 prompt 招式
  5. 五、外掛作者：用 engines 宣告版本範圍
  6. 六、順手升級你的 CI：plugin validate
  7. 七、什麼時候該用、什麼時候別用
  8. 八、對工程團隊的行動清單
  9. 來源

如果你常讓 Claude Code 做「掃一輪 repo、找出所有用到舊 API 的地方、整理成表」這種工作，應該看過這個畫面：Grep 一次、Read 一次、再 Read 一次……每一步的原始輸出都整包塞回對話，context 一下就滿，速度也被一個個來回拖慢。

11 月 12 日釋出的 Claude Code v2.1.323，把一個業界討論了一年多的解法做成了實驗性選項：Code Mode。開啟之後，Claude 不再一個工具一個工具地叫，而是寫一段 JavaScript，由這段程式去呼叫工具，中間的過濾、比對、計數都在程式裡完成，最後只把結論帶回來。

同一版還有一個外掛作者等很久的功能：plugin.json 可以用 engines["claude-code"] 宣告支援的 Claude Code 版本範圍。

這篇講清楚兩件事怎麼用、什麼時候別用。先說明查證狀況：changelog 裡指向的官方說明頁 code.claude.com/docs/en/code-mode 在我們 11 月 13 日查詢時還是 404，所以下面的開關細節，是從 v2.1.323 CLI 本身的提示訊息讀出來的，我們還沒在正式專案開啟實跑。標「值得實測」的地方，請你自己跑過再下結論。

一、為什麼值得關注：工具呼叫的兩個隱形成本

傳統的 tool calling 流程是這樣：模型決定要叫哪個工具，產生參數，Claude Code 執行，結果回傳給模型，模型再決定下一步。這個模式有兩個成本，平常不太會注意到：

  1. 每一步都是一個模型回合。 要讀 20 個檔案，就是 20 次「模型想、工具跑、結果回傳」的循環。
  2. 所有中間結果都進 context。 你其實只想知道「哪 3 個檔案有問題」，但 20 份檔案內容全都被塞進對話，後面的推理品質和 compact 頻率都會受影響。

這不是 Claude Code 獨有的問題。Cloudflare 的 Kenton Varda 和 Sunil Pai 在 2025 年 9 月發表〈Code Mode: the better way to use MCP〉，把 MCP 工具轉成 TypeScript API，讓模型寫程式去呼叫，並直接取名叫「Code Mode」。Anthropic 工程團隊兩個月後也在〈Code execution with MCP: Building more efficient agents〉裡提出同樣的思路，文中舉了一個例子：只載入當下需要的工具定義，token 用量從 150,000 降到 2,000，約省 98.7%。

要注意的是，那個 98.7% 是 Anthropic 部落格裡一個特定示例（大量 MCP 工具定義、按需載入）的數字，不是 Claude Code Code Mode 的實測結果，別拿來當你專案的預期值。它說明的是方向：模型很會寫程式，讓它用程式處理資料，比讓資料一筆一筆流過 context 划算。

二、Code Mode 的運作原理

一般工具呼叫與 Code Mode 的流程對比

核心差別只有一句話：誰負責串起多個工具呼叫。

  • 一般模式：模型自己串。每呼叫一次工具，結果就回到模型，模型讀完再決定下一步。
  • Code Mode：程式串。模型一次寫好一段 JavaScript，裡面可以有迴圈、條件判斷、資料過濾，程式在執行時去呼叫 Claude Code 的工具，最後 return 一份整理好的結果給模型。

所以適合 Code Mode 的工作有個共同特徵：中間資料很多，但最後要的答案很小。 例如：

  • 掃 50 個檔案，只回報有用到 legacyFetch() 的檔名和行號
  • 讀一堆測試報告，只統計失敗最多的前 5 個 test case
  • 對多個 MCP 資源查詢，把結果 join 成一張表再交回

從 CLI 的提示訊息還可以看出幾個設計細節，對理解行為很有幫助：

  • 權限判斷照樣在。 在 auto mode 下，一段程式碼是整段送給分類器判斷的，訊息原文提到「讀檔和搜尋程式碼會被當成發出它們的那次呼叫的一部分來判斷」。也就是說，程式裡偷偷讀檔不會繞過檢查。
  • 含 \uXXXX 跳脫字元的程式碼不會執行。 auto mode 沒辦法檢查這種寫法，會要求 Claude 改用 \x1b 或 \u{1b} 這類寫法重送。
  • hook 改過的程式碼，auto mode 不跑。 如果你的 PreToolUse 類 hook 修改了 Claude 寫的程式，auto mode 會拒絕執行，並說明「這不代表程式碼不安全」。有寫 hook 改寫工具參數的團隊要特別注意這一點。

Code Mode 內 JavaScript 呼叫工具的具體 API 長什麼樣，官方頁還沒上線，本文圖裡的程式碼只是示意，不是真實 API。

三、手把手：怎麼打開、怎麼確認、怎麼關掉

步驟 1：先升級

claude update
claude --version   # 應該看到 2.1.323 或更新

步驟 2：用環境變數開啟

從 CLI 的訊息看，開關是環境變數 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE，值必須是 1，填其他值會被判定為無效。

只想在這次終端機試試：

CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

想長期開著，放進 ~/.claude/settings.json 的 env：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
  }
}

有一個坑：如果 managed settings 或 ~/.claude.json 也設了這個變數，CLI 會要求你改在 ~/.claude/settings.json 開，在 shell 設的會被拒絕。遇到「isn't available」的提示時先查這裡。

步驟 3：啟動時會問你一次

開了變數之後，CLI 會詢問你是否要打開 Code Mode，答案會存在 ~/.claude.json。如果你選了不要，該 session 會用一般工具繼續；想停止被詢問，就把那個環境變數拿掉。

步驟 4：確認真的開了

開成功時，啟動訊息會出現類似：

Code Mode (experimental) is on · this session can be resumed only with Code Mode on

這行很重要：用 Code Mode 開的 session，之後 --resume 也必須開著 Code Mode。 如果你習慣隔天接續昨天的 session，記得環境保持一致。

另外，若你用的模型不在測試範圍內，會看到「Code Mode isn't tested on this model · Run /model to switch」。從程式邏輯推讀，測試範圍大致是 Fable 5.2 以上、Opus 與 Sonnet 5.5 以上，以官方頁公布為準。

步驟 5：目前不能一起用的功能

  • 背景 session：Code Mode 的 session 不能用 /fork、--bg 移到背景或複製。
  • Remote Control：開著 Code Mode 時不會連上 Remote Control，要用的話得把變數設為 0 重啟。

如果你的工作流很依賴背景 agent 或從手機遙控，現在先別在主力環境開。

步驟 6：關掉

個人：把變數設為 0 或從 settings 移除。組織：changelog 說明管理者可以在組織層級關閉，CLI 的對應訊息是「your organization's settings don't allow it」。實際要設哪個 managed settings 鍵，請等官方頁上線再照做，我們不在這裡猜。

四、讓 Code Mode 發揮的 prompt 招式

Code Mode 是一種能力，Claude 什麼時候寫程式、什麼時候直接叫工具，還是看任務。你可以在 prompt 裡把「中間資料大、結果小」講清楚，讓它更傾向用程式彙整：

招式 1：明講你只要摘要

掃 src/ 底下所有 .ts 檔，找出呼叫 legacyFetch( 的地方。
不要逐檔貼內容，用一段程式彙整，最後只給我：
檔名、行號、呼叫的參數，做成一張表。

招式 2：要求過濾條件寫進程式

讀 test-results/ 裡所有 JSON 報告，在程式裡統計每個 test case 的失敗次數，
只回傳失敗次數前 5 名和它們最近一次的錯誤訊息第一行。

招式 3：跨來源 join

把 MCP 拿到的 issue 清單和 git log 最近 30 筆 commit 對起來，
程式裡比對 commit message 有沒有提到 issue 編號，
回傳「有 issue 但沒有對應 commit」的清單。

值得實測的點：拿你 repo 裡一個平常會讓 context 暴漲的任務，分別在開與不開 Code Mode 下各跑一次，用 /context 看 context 用量、記下總耗時，再判斷值不值得留著。

五、外掛作者：用 engines 宣告版本範圍

plugin.json 的 engines 欄位與版本挑選示意

如果你維護 Claude Code 外掛，以前最頭痛的是：你用了新版才有的 hook 事件或 mod API，舊版使用者照樣裝得起來，然後在執行時壞掉。v2.1.323 給了正解：

{
  "name": "my-plugin",
  "version": "1.4.0",
  "engines": {
    "claude-code": ">=2.1.323"
  }
}

changelog 描述的規則有三條：

  1. 範圍外的外掛不會被安裝、更新或載入。
  2. install 和 update 會挑「符合範圍的最新版」。 使用者的 Claude Code 還沒升級，會拿到你舊的相容版本，而不是裝了壞掉的新版。
  3. 範圍寫錯時，CLI 會提示你改成像 ">=2.1.0" 這樣的寫法。

實務建議：

  • 每次用到新版功能就同步拉高下限。 例如你開始用 v2.1.323 才有的 mod 欄位，就把下限寫成 >=2.1.323。
  • 舊版本別刪。 規則 2 能運作的前提是 marketplace 裡還留著舊的相容版本。
  • 注意範圍跟你本機不合的警告。 CLI 有一則提示是「With this range, an installed copy would not load here」，代表你寫的範圍會把自己目前的版本排除在外。

六、順手升級你的 CI：plugin validate

同一版 claude plugin validate 也加了兩件事：

  • TypeScript hooks module 型別檢查：每個型別問題都是 warning，加 --strict 才會讓檢查失敗。
  • mod 的 engine.create hook 新增、隱藏或取代哪些 $ 名詞，現在也會列在 validate 輸出裡，方便 review。

建議放進外掛 repo 的 CI：

claude plugin validate ./my-plugin --strict --json > validate.json

依 Plugin commands reference，exit code 0 是通過、1 是失敗（--strict 下 warning 也算）、2 是驗證器本身出錯。CI 只要看 exit code 就能擋下型別有問題的 hook。

七、什麼時候該用、什麼時候別用

適合開 Code Mode：

  • 大量讀檔、搜尋、彙整的分析型任務
  • 接了很多 MCP 工具、常常要跨來源合併資料
  • 你很在意 context 用量，常被迫 /compact

先別開：

  • 依賴背景 session、/fork 或 Remote Control 的工作流
  • 有 hook 會改寫工具參數、又跑 auto mode 的環境（改過的程式碼不會執行）
  • 團隊共用、需要穩定可重現行為的正式環境。它是實驗性功能，行為可能隨版本變

八、對工程團隊的行動清單

  1. 個人機器先開：CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude，挑一個 context 爆量的任務對照測試。
  2. 確認啟動訊息、模型提示，記得 resume 時保持開啟。
  3. 寫 hook 的人檢查有沒有改寫工具輸入，評估在 auto mode 下的影響。
  4. 外掛維護者：在 plugin.json 補上 engines["claude-code"]，CI 加 claude plugin validate --strict。
  5. 管理者：等官方 Code Mode 頁上線，確認組織層級的開關鍵名，再決定預設政策。

來源

整理：DataAgent · Coding Agent 實戰教學

最後更新：2026年11月13日