Claude Code Dev Container 導入

將 Claude Code 的執行環境隔離在 Docker 容器內，以 filesystem 與 network isolation 縮小 autonomous execution 的爆破半徑。

概述

Claude Code 是 agentic coding 工具，會自行決定要執行什麼指令、讀什麼檔案、發什麼網路請求。在主機 OS 上直接執行時，一旦遭遇 prompt injection 攻擊或指令誤判，Claude 能碰到的東西包括 SSH key、瀏覽器 cookie、其他 repo、雲端憑證。Dev Container 的核心目的是縮小這個「爆破半徑（blast radius）」：容器內只看得到這個 repo 與其 dependencies，其餘全部隔離在外。

Anthropic 官方 reference 配置提供三層保護：Network isolation（default-deny，只開 allowlist 網域）、Filesystem isolation（看不到宿主機家目錄）、完整開發工具鏈。這個設計呼應 Gartner 採用篇的建議：「本機做 planning、容器裡做 autonomous execution」。正因為有容器邊界，才敢開 autonomous mode；沒有容器邊界而開 autonomous mode，是把工作站當賭注。

核心內容

三層保護說明

層	內容
Network isolation with default-deny	容器預設只能連到 allowlist 上的網域（npm registry、GitHub、Anthropic API 等），其餘全擋
Filesystem isolation	容器內看不到宿主機的家目錄、SSH key、其他專案；Claude Code 能改的只有這個 repo
完整開發工具鏈	預裝 Claude Code CLI、Node.js、git、常見 language runtime

Windows 環境的三種後端選擇

後端	可行性	備註
Docker Desktop for Windows	多數公司被擋	250 員工以上 / 營收 $10M 以上要付費授權
WSL2 + Docker Engine（apt 裝 docker-ce）	多數公司能走的路徑	不需要 Docker Desktop
Podman / Rancher Desktop / colima	替代品	Dev Containers extension 對 Podman 支援偶爾踩雷

WSL2 + Docker Engine 的基本流程：

在 WSL2 Ubuntu 裡用 apt install docker-ce 安裝 Docker Engine
VS Code 從 Windows 端打開 repo
Dev Containers extension 自動偵測 Windows VS Code → WSL → Docker 鏈路

效能注意事項： Repo 放置位置決定 I/O 性能：

❌ 放在 /mnt/c/...（Windows 檔案系統 mount）→ npm install 可能慢 5–10 倍
✅ 放在 ~/projects/...（WSL 原生檔案系統）→ 從 VS Code 用「Open Folder in WSL」進去

資安確認： 先確認公司是否同時擋掉 WSL 裡跑 Docker daemon——有些公司只擋 Docker Desktop 授權問題，有些是連 container runtime 整個禁，先問 IT。

套件隔離觀念轉換

Dev Container 本質上是一台全新的 Linux 機器，Windows 上或 WSL 主環境的全域套件容器完全看不到：

類別	容器裡怎麼處理
Node 全域套件	推薦順序：專案 devDependency > `npx` > devcontainer `postCreateCommand`
Python 版本	用 `ghcr.io/devcontainers/features/python:1` 明確指定版本
uv	用 `ghcr.io/va-h/devcontainers-features/uv:1` feature；`uv.lock` 帶進容器 `uv sync` 建 .venv
dotfiles / shell config	VS Code Dev Containers extension 有 dotfiles repo 設定可同步
VS Code extensions	在 `devcontainer.json` 的 `customizations.vscode.extensions` 指定

第一次設定套件問題會花半天到一天，但這個「痛苦」是有價值的：你被迫把所有依賴明確列出。三個月後團隊新人加入，他不需要問「你電腦上裝了什麼我才能 reproduce」——devcontainer.json 就是答案。

Base Image 選擇原則

用乾淨的 devcontainers/base:ubuntu-24.04 + language features，而不是 Python/Node image 當底：

Python/Node base image 都「預裝了一個版本」，再用 feature 裝另一個語言容易撞版本
乾淨 base + 明確宣告的 language features = 沒有隱藏條款的環境憲法

關鍵要點

Dev Container 的核心價值是縮小 autonomous execution 的爆破半徑，不是把整個開發體驗塞進容器
Windows 環境優先走 WSL2 + Docker Engine，不需要 Docker Desktop
Repo 務必放在 WSL 原生檔案系統，避免 /mnt/c/ 路徑的 I/O 性能懲罰
devcontainer.json 是 repo 的環境憲法，第一版先不要加 network isolation，基本環境穩定後再加
第一次設定的套件痛苦是收益：強迫把「在我電腦上能跑」這個黑盒攤開

部署設定參考

Python 3.13 + Node 22 + uv + OpenSpec 的完整 devcontainer.json 範例。

完整 `devcontainer.json`

json

{
  "name": "Python 3.13 + Node 22 + OpenSpec",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",

  "features": {
    "ghcr.io/devcontainers/features/python:1": {
      "version": "3.13",
      "installTools": false
    },
    "ghcr.io/devcontainers/features/node:1": {
      "version": "22"
    },
    "ghcr.io/va-h/devcontainers-features/uv:1": {}
  },

  "postCreateCommand": "npm install -g @fission-codes/openspec",

  "remoteUser": "vscode",

  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "charliermarsh.ruff",
        "anthropic.claude-code"
      ]
    }
  }
}

設計決策說明：

項目	選擇	原因
Base image	`devcontainers/base:ubuntu-24.04`	乾淨底層，language features 各自獨立，無隱藏預裝版本
Python `"installTools": false`	關掉	不需要 pylint/flake8/mypy，改用 uv + ruff，容器 build 更快
uv 安裝方式	community feature（非 curl）	處理好 PATH/completion/cache，build 階段就裝好
`remoteUser: vscode`	非 root 開發	base image 預建 UID 1000 非 root user，基本資安要求

Build 後驗證指令

bash

python --version    # Python 3.13.x
node --version      # v22.x.x
uv --version        # uv 0.5.x

# 測試 repo 真實 workflow
uv sync             # pyproject.toml 能解出來嗎
uv run pytest       # 測試跑得起來嗎
npm install         # 如果 repo 也有 package.json

CLAUDE.md 建議加入的說明

本 repo 的 Claude Code session 請從 dev container 啟動。
理由：(1) 環境版本由 .devcontainer/devcontainer.json 明確宣告，避免「在我電腦上能跑」；
      (2) 容器邊界提供 filesystem 與 network 的 default-deny 起點，是後續開 autonomous mode 的前提。

導入順序建議

階段	內容	說明
1	基本環境 + 工具鏈	跑順 workflow，解完套件問題
2	團隊習慣容器開發	觀察痛點與邊緣情況
3	加 network isolation	分一個獨立 PR 加 firewall script + allowlist
4（可選）	Managed settings	等 platform team 成形，強制全公司套用 dev container

來源

Gartner G00850617 — How to Adopt Anthropic's Claude Code at Scale（2026/03/17）
Gartner G00850426 — How to Govern Anthropic's Claude Code at Scale（2026/03/16）
原始素材：2026-05-13 Claude Code Dev Container 導入指南

Claude Code Dev Container 導入 ​

概述 ​

核心內容 ​

三層保護說明 ​

Windows 環境的三種後端選擇 ​

套件隔離觀念轉換 ​

Base Image 選擇原則 ​

關鍵要點 ​

部署設定參考 ​

完整 devcontainer.json ​

Build 後驗證指令 ​

CLAUDE.md 建議加入的說明 ​

導入順序建議 ​

相關概念 ​

來源 ​