精選 claude-code changelog release-roundup permissions ultracode mods agents-md

Claude Code 2.1.227 到 2.1.305：2026 年 8–10 月總整理

整理 Claude Code v2.1.227 到 v2.1.305（2026/8/10–10/20）的重要變更：新模型別名、自動模式預設、ultracode、AGENTS.md、mods、claude purge，以及升級檢查清單。

2026年10月21日 • 15 分鐘閱讀 • 作者：Claude World

2026 年 8 月 10 日到 10 月 20 日之間，Claude Code 從 v2.1.227 走到 v2.1.305，官方 CHANGELOG 中共有 66 個版本。多數條目是修正，但有一小部分改變了你每天都在依賴的預設行為：別名會選哪個模型、工作階段以哪種權限模式啟動、ultracode 代表什麼、有哪些內建工具，以及你的腳本呼叫哪些指令。

這篇總整理按主題整理這些變更。下面每個版本號都對照官方 CHANGELOG 驗證過，每個版本都連到本站該版本的說明頁，每一節最後附上「怎麼做」。文件與 CHANGELOG 對版本號說法不一時，我們會註明。

模型本身的發布（定價、定位、Mythos 5.1 與 Sonnet 4.5 退役），請見〈Claude Fable 5.1 與 Claude 5.5 家族〉。

重點速覽

變更版本怎麼做
在 Anthropic API 上，fable、opus、sonnet、haiku 改指向 Fable 5.1、Opus 5.5、Sonnet 5.5、Haiku 5.52.1.257、2.1.280、2.1.284、2.1.293升級到 2.1.293 以上；檢查你釘選的模型
Pro 與 Team Standard 的預設模型從 Sonnet 改為 Opus2.1.280偏好 Sonnet 的話就釘選 sonnet
effort 依模型儲存；maxEffortLevel 設上限；5.5 系列預設為 medium2.1.251、2.1.267、2.1.280依模型重新選擇 effort
Ultracode 變成獨立開關，與 effort 分開2.1.284用 /effort ultracode 與 /effort ultracode off
互動式工作階段以自動模式啟動2.1.283、2.1.284想用手動模式就設定 permissions.defaultMode
claude -p 與 Agent SDK 以手動模式啟動2.1.302加上允許規則，或傳入 --permission-mode auto
較新模型上不再提供 todo/task 工具；移除 TaskOutput2.1.233、2.1.268、2.1.277更新仰賴它們的提示與 hook
沒有 CLAUDE.md 時會讀取 AGENTS.md2.1.277、2.1.281選定一個主要的指示檔
Claude Mods2.1.287只安裝來源可信的 mod
claude purge 取代 claude project purge2.1.288更新你的腳本
--restricted、--permission-prompts、--system-prompt-snapshot off、--desktop2.1.248 到 2.1.285用在評測框架、CI 與交接
Code Review 正式推出（10 月 15 日）與審查等級2.1.304依儲存庫設定等級

1. 模型別名與預設模型

版本日期變更
v2.1.2572026-09-01新增 Claude Fable 5.1；fable 指向 Fable 5.1（Claude apps gateway 工作階段暫時仍用 Fable 5）
v2.1.2802026-09-22新增 Claude Opus 5.5；在 Anthropic API、Claude Platform on AWS、Amazon Bedrock 與 Google Cloud’s Agent Platform 上，opus 指向 Opus 5.5；Pro 與 Team Standard 的預設模型從 Sonnet 改為 Opus
v2.1.2842026-09-28新增 Claude Sonnet 5.5；在 Anthropic API 上，sonnet 指向 Sonnet 5.5
v2.1.2932026-10-07新增 Claude Haiku 5.5；在 Anthropic API 上，haiku 指向 Haiku 5.5

同一期間，v2.1.236 新增了 ANTHROPIC_DEFAULT_MODEL 環境變數：它設定新工作階段啟動時使用的模型，而用 /model 選擇的模型仍會覆寫它，並在重新啟動後保留（這點與 ANTHROPIC_MODEL 不同）。

怎麼做： 執行 claude --version，升級到 v2.1.293 以上。在 Claude Platform on AWS、Amazon Bedrock、Google Cloud’s Agent Platform 與 Microsoft Foundry 上，有些別名仍指向較舊的模型；供應商對照表請見〈Claude 5.5 家族指南〉。

2. Effort：依模型儲存、medium 預設值與上限

  • v2.1.251：/effort 改為依模型儲存預設 effort 等級，切換模型時各自保留設定。這些等級存放在使用者設定的 modelSettings 鍵底下。
  • v2.1.257：在 /effort 中按 s，只變更目前工作階段的 effort，與 /model 的操作一致。
  • v2.1.267：新增 maxEffortLevel 設定（可設在最上層，或在 modelSettings 中依模型設定），在所有供應商上限制 effort 等級，包括 Bedrock、Vertex 與 Foundry；使用者仍可選擇更低的等級。
  • v2.1.280：在 /effort 改為依模型儲存之前存下的 effort 等級，不再套用到 Opus 5.5 等新發布的模型，它們會從自己的預設值開始。在 Claude Code 中，Opus 5.5、Sonnet 5.5 與 Haiku 5.5 預設為 medium。
  • v2.1.292：Agent 工具新增 effort 參數，Claude 會用你要求的 effort 等級執行子代理。

下面這個設定檔把所有模型的上限設為 high，並讓 Opus 5.5 維持在 high，而不是它預設的 medium：

{
  "maxEffortLevel": "high",
  "modelSettings": {
    "claude-opus-5-5": { "effortLevel": "high" }
  }
}

怎麼做： 用 /effort status 檢查你使用的每個模型目前的等級。使用者設定中最上層的 effortLevel 如果是在依模型儲存之前存下的，就不再套用到 Opus 5.5 或更新的模型；請用 /effort 為它們選擇等級（或執行 /effort auto 清除已儲存的等級）。需要上限的團隊，請在受管設定（managed settings）中設定 maxEffortLevel。

3. Ultracode 是開關，不是 effort 等級

v2.1.284：Ultracode 改為 /effort 中的獨立開關（按 Tab，或用 /effort ultracode [on|off]），不再強制使用 xhigh effort，在任何 effort 等級下都能保持開啟。

模型設定文件現在是這樣描述的：“Ultracode is a Claude Code setting rather than a model effort level: with it on, Claude orchestrates dynamic workflows for substantive tasks, at whichever effort level the session runs at.”（Ultracode 是 Claude Code 的設定，而不是模型的 effort 等級：開啟後，Claude 會針對實質性的任務編排動態 workflow，並沿用工作階段當下的 effort 等級。）有兩個細節要注意：

  • claude --effort ultracode 與 Agent SDK 的 effortLevel: "ultracode"，仍會開啟 ultracode 並且設為 xhigh。用 /effort 或 ultracode 設定開啟時，則不會改變 effort 等級。
  • 持久化的 effortLevel 設定與 CLAUDE_CODE_EFFORT_LEVEL 不接受 ultracode；請改在設定中使用 "ultracode": true。當 workflow 被關閉，或模型不支援 xhigh 時，無法使用 ultracode。
/effort ultracode       # turn ultracode on for this session
/effort ultracode off   # turn it off again (v2.1.284+)

怎麼做： 別再把 ultracode 當成比 xhigh 更高的一級。effort 等級與 ultracode 分開選擇；只有同時想要兩者時，才用 claude --effort ultracode 啟動。workflow 的部分請見我們的 ultracode 指南。

4. 權限模式：互動式用自動模式，-p 用手動模式

  • 互動式工作階段以自動模式啟動。 權限模式文件：“With Claude Code v2.1.283 or later, auto mode is the built-in starting permission mode for interactive terminal and VS Code sessions.”（在 Claude Code v2.1.283 以上版本，自動模式是互動式終端機與 VS Code 工作階段的內建起始權限模式。）CHANGELOG 則顯示分兩步完成：v2.1.283 先改變第三方供應商或關閉遙測時的互動式工作階段，v2.1.284 再擴大到所有方案與供應商。permissions.defaultMode 仍可覆寫它。
  • 無介面（headless）執行以手動模式啟動。 同一份文件寫道：“In Claude Code v2.1.302 or later, claude -p and Agent SDK runs with no permission mode set start in Manual mode.”（在 Claude Code v2.1.302 以上版本，沒有設定權限模式的 claude -p 與 Agent SDK 執行，會以手動模式啟動。）需要核准的呼叫會被拒絕，除非有允許規則、hook、canUseTool 回呼或 --permission-prompt-tool 核准。詳見 v2.1.302 說明。
  • 無人值守的主機。 v2.1.259 新增 --permission-prompts none，供無人值守的 headless 主機使用：任何會跳出提示的操作都會自動被拒絕，而目前的權限模式（包括自動模式）照常判斷。
  • 讓自動模式認識你的環境。 v2.1.304 列出 /auto-mode-setup：這是會讀取你的專案與近期工作階段、讓自動模式了解你的環境的引導式設定，現在也能在 Bedrock、Vertex、Foundry、Claude apps gateway 與關閉遙測的工作階段中使用。

有一條規則要記住：在專案的 .claude/settings.json 或 .claude/settings.local.json 中設定的 auto 與 bypassPermissions 不會生效。想繼續親自審查每個動作，就在 ~/.claude/settings.json 中設定手動模式（設定值為 default）：

{
  "permissions": {
    "defaultMode": "default"
  }
}

在 CI 中，請明確給 headless 執行授權：

claude -p "Run the test suite and fix any failures" --permission-mode auto
claude -p "Run the unit tests" --allowedTools "Bash(npm test)"
claude -p --permission-prompts none "Summarize this repository"

怎麼做： 刻意選擇你的起始模式，而不是直接沿用新的預設值。檢查每個 claude -p 工作與 SDK 整合：給它允許規則或 --permission-mode auto，在沒人能回應提示的地方加上 --permission-prompts none。規則系統請見 Session 18：權限模型與安全性。

5. 內建工具：todo 工具、TaskOutput 與分叉子代理

  • v2.1.233：todo/task 追蹤工具（TaskCreate/Get/Update/List、TodoWrite）在 Opus 4.8、Sonnet 5、Fable 5、Mythos 5 與更新的模型上不再提供；設定 CLAUDE_CODE_ENABLE_TODO_TOOLS=1 即可恢復。
  • v2.1.268 把它改成允許清單：這些工具只在 Claude 3.x、Opus 4.0–4.7、Sonnet 4.0–4.6 與 Haiku 4.5 上提供。
  • v2.1.277：移除已棄用的 TaskOutput 工具；Claude 改用 Read 讀取背景任務的輸出檔，taskOutputMaxChars 設定與 TASK_MAX_OUTPUT_LENGTH 也不再有任何作用。
  • v2.1.232：子代理分叉（fork）預設開啟。subagent_type: "fork" 的子代理會繼承完整對話與提示快取，而互動式工作階段中非 teammate 的 agent 預設在背景執行。v2.1.302 讓 claude -p、Agent SDK、桌面應用程式與 VS Code 也預設開啟分叉；設定 CLAUDE_CODE_FORK_SUBAGENT=0 可關閉。

怎麼做： 如果有提示、skill、hook 或 SDK 整合預期會用到 TodoWrite、Task 工具或 TaskOutput，就更新它們；只有在 workflow 真的需要時，才用 CLAUDE_CODE_ENABLE_TODO_TOOLS=1 啟動 Claude Code。從設定中移除 taskOutputMaxChars 與 TASK_MAX_OUTPUT_LENGTH。

6. 專案指示：AGENTS.md 與提示稽核

  • v2.1.277：新增 AGENTS.md 支援。專案中沒有 CLAUDE.md 時，Claude Code 會改讀 AGENTS.md；可在 /config 的「Project instructions」中變更。
  • v2.1.281：AGENTS.md 支援擴大到 Amazon Bedrock、Google Vertex AI、Microsoft Foundry、LLM gateway，以及關閉遙測的工作階段。
  • v2.1.283：新增 /doctor prompt-audit（也可用 /checkup prompt-audit），稽核你的 CLAUDE.md、skill、agent 與指令中是否有為舊模型寫的提示寫法。

怎麼做： 在與其他程式開發代理共用的儲存庫中，決定以哪個檔案為準；只有在沒有 CLAUDE.md 時才會讀取 AGENTS.md。換到 5.5 系列模型後，執行 /doctor prompt-audit。請參考 Session 17：CLAUDE.md 設計。

7. 外掛與 Claude Mods

  • v2.1.269：新增 claude plugin eval，針對 Claude Code 執行外掛的評估套件，產出有分數、可重現的結果（JSON 與 HTML 報告）。
  • v2.1.285：claude plugin configure <plugin> 會顯示外掛的選項與尚未設定的項目，或用 --values-stdin 從標準輸入讀取並儲存新值。
  • v2.1.287：新增 Claude Mods，外掛現在可以修改更深層的行為。同一版還加入內建 mod「You should know」，由一個旁支 agent 幫你注意你或 Claude 可能忽略的事；用 /plugin enable cc-plugin-you-should-know@builtin 開啟（限開啟遙測的第一方工作階段）。Anthropic 的發布文章寫道：“Today we’re introducing mods, small TypeScript functions that change how Claude Code works.”（今天我們推出 mods：改變 Claude Code 運作方式的小型 TypeScript 函式。）以及 “Mods ship inside plugins, so you install and share them like any plugin.”（Mods 包在外掛中發布，所以安裝與分享方式和一般外掛相同。）
  • claude plugin test [dir] 會在 mod hook 環境中執行 mod 的 *.test.ts 與 *.test.tsx 檔案。它存在於 v2.1.305 的 CLI 中，但在 CHANGELOG 中第一次出現是 v2.1.288 的一項修正，因此引入它的確切版本並沒有記載。

怎麼做： 把 mod 當成任何你會執行的程式碼看待。Anthropic 的文章說得很直接：“They aren’t sandboxed, and you should only install mods from sources you trust”（它們沒有沙箱隔離，請只安裝來源可信的 mod）。如果你寫 mod，請在 CI 中執行 claude plugin test；如果你發布外掛，請加上 claude plugin eval 評估套件。

8. 在自己的基礎設施上執行雲端工作階段

自架環境在本期間前夕、8 月 7 日的 v2.1.224 推出：claude self-hosted-runner 能把你自己的機器或容器，變成 Claude Code 網頁版、行動版與桌面版工作階段的執行場所，適用於 Team 與 Enterprise 方案。搭配的 --environment <environment-id> 旗標會在自架環境上建立雲端工作階段（ID 以 ccpool_ 開頭）。在本期間，runner 陸續加入營運所需的控制項：

  • v2.1.238：--defer-shutdown-max-min <minutes> 在收到 SIGTERM 後繼續服務已連線的工作階段，時間到再把剩下的暫存起來並結束。
  • v2.1.248：--client-label <label>（或 SELF_HOSTED_RUNNER_CLIENT_LABEL）覆寫 runner 註冊時使用的標籤。
  • v2.1.271：在組織允許的情況下，fast mode 可用於 Claude Code Remote 工作階段（雲端與自架 runner）。
  • v2.1.290：claude --environment <id> 改透過目前的 Sessions API 建立工作階段。
  • v2.1.299：claude self-hosted-runner orchestrator 新增 --shutdown-drain-sec，收到 SIGTERM 時讓進行中的工作有時間完成。
claude self-hosted-runner setup     # guided operator walkthrough
claude self-hosted-runner doctor    # diagnose a deployed runner
claude -p "Run the smoke test" --environment ccpool_abc123 --ref main

怎麼做： 如果你在營運 runner，請設定 --defer-shutdown-max-min（orchestrator 則設定 --shutdown-drain-sec），避免部署時中斷進行中的工作階段，並用 --client-label 區分不同主機。

9. 自動化用的新旗標與指令

旗標或指令版本適用情境
--restricted（或 CLAUDE_CODE_RESTRICTED=1）v2.1.248評測框架在共用機器上驅動 claude。它會移除能執行指令或程式碼的內建工具與 WebFetch（除非在 --tools 中指名），讓檔案工具只能在工作目錄內操作，拒絕 bypassPermissions，並忽略使用者、專案與本機設定
--permission-prompts nonev2.1.259在 -p 執行中沒人能回應提示；提示會被拒絕，權限模式照常判斷
--system-prompt-snapshot offv2.1.267你在多次 --continue 執行之間反覆調整系統提示文字（例如 --append-system-prompt），希望每次請求都重新建構系統提示
claude --desktopv2.1.285你想在 Claude 桌面應用程式中，接續目前目錄的工作，或用 --continue、--resume <id> 開啟某個工作階段
claude purge [path]v2.1.288你想刪除某個專案在本機的所有 Claude Code 狀態；它取代 claude project purge，舊名稱仍可使用，但會顯示提醒
不帶 --sandbox 的 claude remote-controlv2.1.300原本沒有作用的 --sandbox 與 --no-sandbox 旗標現在會報錯結束；請改在設定中使用 sandbox.enabled

CLI 參考文件把 --system-prompt-snapshot 的最低版本列為 v2.1.257，而 CHANGELOG 是在 v2.1.267 加入 --system-prompt-snapshot off；使用 v2.1.267 以上版本，兩種說法都沒問題。

claude purge ~/work/repo --dry-run          # preview what would be deleted
claude --restricted -p "Grade this patch"   # harness-safe run
claude --desktop --continue                 # open this directory's latest conversation in the desktop app

怎麼做： 在腳本中搜尋 claude project purge，以及 claude remote-control 上的 --sandbox；評測框架請改用 --restricted。

10. Artifacts、/design 與 /slides

  • /design [brief] 會把 UI 模型稿、畫面流程、登陸頁或海報畫成 Claude Design artifact；/slides [brief] 則會製作 Claude Slides 簡報。兩者在 CHANGELOG 中都沒有引入條目；指令參考文件列出兩者都需要 Claude Code v2.1.265 以上版本，且工作階段必須能使用 artifacts。
  • Artifacts 需要 Pro、Max、Team 或 Enterprise 方案，以及 Anthropic API；在 Amazon Bedrock、Google Cloud’s Agent Platform、Microsoft Foundry 與 Claude Platform on AWS 上無法使用。
  • v2.1.281 修正了 claude remote-control 替你啟動的 Remote Control 工作階段中缺少 Artifact 工具的問題。
  • v2.1.302 在 /design-sync 與 /design-login 加上提醒：獨立版 Claude Design（claude.ai/design）將於 2026 年 12 月 14 日前關閉。
/slides a quarterly review of the platform team's reliability work, for the engineering all-hands
/design a settings screen for a mobile banking app
/artifacts

怎麼做： 如果你的團隊用 /design-sync 把設計系統同步到獨立版 claude.ai/design，請在 2026 年 12 月 14 日前規劃遷移，參考 Anthropic 的遷移說明。

11. 程式碼審查：/code-review 等級、ultra 與 Code Review 正式推出

自本期間前夕、8 月 6 日的 v2.1.223 起，/review 成為 /code-review 的別名；/code-review 會以指定的 effort 等級審查目前的 diff 或某個 PR，而 /code-review ultra 會在雲端執行深入的多代理審查（/ultrareview 是它的別名）。在本期間：

  • v2.1.232：high、xhigh 與 max 等級的 /code-review 也和其他等級一樣在背景代理中執行。
  • v2.1.257：--comment 透過 glab mr note 把審查結果貼到 GitLab merge request。
  • v2.1.269：/ultrareview --post 會在結果出來時直接貼出 PR 留言。
  • v2.1.288：/code-review 新增 --max-findings <n>|all，可回報比平常上限更多或更少的發現。
  • v2.1.290：在 medium effort 下，對於沒有專屬審查調校的模型（包括 Opus 5.5 與 Sonnet 5.5），/code-review 也會回報程式碼清理與 CLAUDE.md 慣例方面的發現。

負責審查組織 PR 的 Code Review 已於 10 月 15 日正式推出。Anthropic 的正式推出公告寫道：“Code Review is out of research preview and available to Claude Team and Enterprise organizations.”（Code Review 已結束研究預覽，開放給 Claude Team 與 Enterprise 組織使用。）以及 “Most reviews now finish about 3x faster (~20 minutes down to 6-10 minutes) compared to during preview.”（與預覽期間相比，大多數審查的完成速度快了約 3 倍，從約 20 分鐘縮短到 6–10 分鐘。）v2.1.304 加入審查等級：Owner 可為組織選擇 Quick、Standard（預設）或 Deep，也能替個別儲存庫指定自己的等級。

/code-review high 1234            # review pull request 1234 at high effort
/code-review --fix                # review the current diff and apply the findings
/code-review --max-findings all   # report every finding instead of the usual limit
/code-review ultra                # deep multi-agent review in the cloud

怎麼做： 依風險高低選擇等級；不指定等級時，/code-review 會沿用你上次輸入的等級。Team 與 Enterprise 的管理員可以讓關鍵儲存庫使用 Deep，例行的儲存庫使用 Quick。

12. 其他值得知道的變更

變更版本
當背景任務讓 /goal 等待 30 分鐘以上時，Claude 會主動確認狀況（設定 CLAUDE_CODE_GOAL_CHECKIN_MINUTES=0 可關閉）v2.1.234
內建「Concise」輸出風格v2.1.237
PreModelSwitch 與 PostModelSwitch hook 事件v2.1.251
全螢幕的 diff 面板，用 /diff 切換v2.1.260
/skill-doctor 顯示沒用到的 skill 與它們占用的上下文v2.1.261
/output-style [name] 列出並切換輸出風格v2.1.269
onFailure: "block" 讓指令與 HTTP hook 在失敗時阻擋動作（fail closed）v2.1.295
在一小時的提示快取到期前進行閒置壓縮；v2.1.302 在 /config 加入 Idle compaction 選項v2.1.299

升級檢查清單

claude --version   # where you are; v2.1.305 is the newest release covered here
claude update      # update to the latest version
claude doctor      # read-only installation and settings diagnostics

接著檢查意義已經改變的設定：

  1. 起始權限模式。 如果不想用自動模式，就在 ~/.claude/settings.json 中設定 permissions.defaultMode；並給 claude -p 工作允許規則或 --permission-mode auto。
  2. 釘選的模型。 在設定、ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_*_MODEL 變數、子代理的 model: 欄位與 fallbackModel 中搜尋舊的 ID，特別是 claude-sonnet-4-5-20250929，它將於 2026 年 11 月 30 日在 Claude API 上退役。
  3. Effort。 使用者設定中最上層的 effortLevel 不再套用到 Opus 5.5 或更新的模型。用 /effort 依模型儲存等級（存放在 modelSettings），需要上限時加上 maxEffortLevel。
  4. Ultracode。 使用 /effort ultracode、/effort ultracode off 或 ultracode 設定；effortLevel 不接受 ultracode。
  5. 改名與移除。 把 claude project purge 換成 claude purge，移除 taskOutputMaxChars 與 TASK_MAX_OUTPUT_LENGTH，並從 claude remote-control 呼叫中拿掉 --sandbox 與 --no-sandbox。
  6. Todo 工具。 只有在 workflow 真的需要 TodoWrite 或 Task 工具時，才設定 CLAUDE_CODE_ENABLE_TODO_TOOLS=1。
  7. 指示檔。 執行 /doctor prompt-audit，並決定以 CLAUDE.md 還是 AGENTS.md 為準。

資料來源

上面每個版本在本站的版本封存中都有獨立頁面。新別名背後的模型，請見〈Claude Fable 5.1 與 Claude 5.5 家族〉。