Claude Code 從安裝到生產級工作流的完整手冊

網路上關於 Claude Code 的零碎教學很多：有人只講 npm install，有人只曬一張 diff 截圖，有人把 MCP 和權限混在一起講。真正要上線時，你缺的不是「又一個快捷鍵」，而是一條從裝 CLI 到 CI 綠燈的完整路徑。

本篇是 Cloud Mac AI Stack · L6 支柱手冊（L6-Q01）：把 Claude Code 當作端到端編碼 Agent，從安裝、第一天試跑、日常委託、MCP 接入，一直寫到和 GitHub Runner 聯動的生產級工作流。決策與權限門檻見 L3 決策首講；MCP 逐步安裝見 MCP 教程——本篇只管主線串聯。

本篇知識骨架

下面不是 Claude Code 官方能力全集，而是本篇 L6-Q01 手冊的主線樹——每一枝對應正文一節，括號內是錨點。正文各節標題下方有知識骨架標注，與下表一一對應。沒畫進樹的能力（Hooks、子代理、企業託管等）留給後續專題或官方文件。

從安裝到生產級工作流 · 2026 年 6 月版

本篇主線（Claude Code 完整手冊）
├── 環境選型（#prereq）
│   ├── macOS / Linux 官方支援邊界
│   ├── 本機 Mac mini / MacBook vs Cloud Mac
│   └── Node 18+ · 網路 · Anthropic 帳號 / API Key
├── 安裝驗收（#install）
│   ├── npm install -g @anthropic-ai/claude-code
│   ├── claude doctor · claude login
│   └── 5 步驗收（進倉庫根 · /help · 無 401）
├── 第一天試跑（#first-day）
│   ├── 小範圍委託 + 全綠測試
│   ├── git diff 審查改動範圍
│   └── 建立審查習慣（越界 → 回 L3 決策）
├── 專案邊界（#claude-md）
│   ├── CLAUDE.md 最小模板（安裝 / 測試 / 禁止改動）
│   └── 可執行命令優先於 prose 說明
├── 日常節奏（#daily）
│   ├── 三檔委託（高 / 協作 / 低）
│   └── 四步循環（委託 → 觀察 → 審查 → 合併）
├── 連接層（#mcp）
│   ├── ~/.claude.json · mcpServers
│   ├── GitHub / CodeGraph / Fetch 常見組合
│   └── /mcp 驗收（細節 → MCP 安裝教程）
├── CI 事實鏈（#ci）
│   ├── Diff（Claude Code）vs Fact（Runner）
│   ├── feature 分支 → self-hosted Runner → PR 綠燈
│   └── secrets 與 Agent 環境隔離
├── 生產清單（#production）
│   ├── CLAUDE.md / 權限 / MCP / 密鑰 / CI / 審查 / 成本
│   └── 試跑 vs 生產級對照表
└── Stack 定位（#stack-map）
    ├── L0–L5 在 Cloud Mac AI Stack 中的位置
    └── 外鏈：L3 決策 · MCP 教程 · Runner 執行引擎

環境準備：Mac 還是 Cloud Mac？

知識骨架 · #prereq · 環境選型

Claude Code 官方支援 macOS 和 Linux。如果你只做 Web / 後端，Linux 雲主機也能跑；但只要涉及 xcodebuild、iOS 模擬器或 macOS 專屬工具鏈，就必須有 macOS 環境。

• 本機 Mac mini / MacBook — 24GB 記憶體更穩（Chrome + Docker + Claude Code 並行時 16GB 容易 Swap），參考 M4/M5 選型
• Cloud Mac — 不想先買硬體、或需要與主力機隔離的開發 / CI 環境，見 買還是租
• 不建議 — 在主力筆電上同時跑生產 secrets、無隔離的 Agent 與 CI Runner（見 Runner 隔離）

軟體前置：Node.js 18+、可存取 Anthropic 的網路、Anthropic 帳號（Claude Pro / Max / Team）或 API Key。

安裝與登入（5 步驗收）

知識骨架 · #install · 安裝驗收

以下命令在 macOS 終端機執行（Cloud Mac 上同樣適用）：

# 1. 全域安裝 CLI
npm install -g @anthropic-ai/claude-code

# 2. 環境自檢（Node 版本、PATH 等）
claude doctor

# 3. 登入（瀏覽器 OAuth 或 API Key）
claude login

第一天：跑通第一個委託任務

知識骨架 · #first-day · 第一天試跑

安裝成功不等於「會用」。第一天只做一件事：讓小範圍改動 + 全綠測試，建立你對 Agent 行為的直覺。

1. 在倉庫根建立或完善 CLAUDE.md（下一節詳解）
2. 啟動 claude，委託詞示例：「給 README 增加一節『本地開發』，只改 README，不要動其他檔案」
3. 觀察 Agent 是否先讀檔案、再改、再執行你指定的驗證命令
4. 用 git diff 審查改動範圍，確認沒有越界
5. 合併前自己再跑一遍測試命令（不要盲信「Agent 說通過了」）

第一天目標不是速度，而是建立審查習慣。如果你發現 Agent 頻繁改錯目錄、亂執行危險命令，先回到 權限決策，不要急著上生產倉庫。

CLAUDE.md：專案邊界說明書

知識骨架 · #claude-md · 專案邊界

CLAUDE.md 是 Claude Code 的「專案 README for Agent」——比給人看的 README 更強調可執行命令與禁止事項。生產級倉庫幾乎必備。

# 專案：my-saas

## 安裝
pnpm install

## 測試（改程式後必須全跑）
pnpm test
pnpm lint

## 禁止改動
- 不要修改 .env、secrets/
- 不要升級 major 依賴除非明確要求
- 計費相關改動必須同時更新對應測試

## 目錄約定
- src/app — Next.js 頁面
- packages/api — 後端邏輯

寫好 CLAUDE.md 後，同樣任務的檔案誤改率和測試循環輪數通常會明顯下降——我們在 工作站實測裡，完整 CLAUDE.md 與空白模板相差約 20% 耗時。

日常開發工作流

知識骨架 · #daily · 日常節奏

試跑通過後，進入日常節奏。建議把任務分成三檔，而不是「什麼都丟給 Agent」：

日常循環建議固定為四步：

1. 委託 — 說清範圍、驗收標準、禁止碰的目錄
2. 觀察 — 看 Agent 讀了哪些檔案、執行了哪些 shell
3. 審查 — git diff + 自己跑測試（與 CLAUDE.md 一致）
4. 合併 — PR + code review；不要直接在 main 上讓 Agent 連續提交

與 Cursor 的分工：Cursor 適合編輯器內補全與小範圍改寫；Claude Code 適合跨檔案 + shell + 測試循環的 Agent 任務。兩者可以並存，但別指望一個工具覆蓋所有場景。

接入 MCP（連接層）

知識骨架 · #mcp · 連接層

當 Agent 需要讀 GitHub Issue、查程式碼圖譜、拉 API 文件時，光靠倉庫內 grep 不夠——這時接 MCP（Model Context Protocol），相當於給 Claude Code 插上「標準 USB 介面」。

• 配置入口 — ~/.claude.json 的 mcpServers 段
• 常見組合 — GitHub MCP（Issue / PR）、CodeGraph MCP（影響面分析）、Fetch MCP（文件）
• 驗收 — 在 Claude Code 裡輸入 /mcp，應看到 mcp__github__* 等工具

逐步安裝與排錯，跟 MCP 安裝教程（15 分鐘）；權限模型見 MCP 最小權限。MCP 是生產級工作流的必要元件，但不是第一天就必須全配——建議先跑通無 MCP 的基礎流，再加 GitHub MCP。

接上 CI：Claude Code + Runner

知識骨架 · #ci · CI 事實鏈

本機 Agent 改完程式、測試綠了，還不算「生產級」——你還需要一條與開發機隔離的 CI 事實鏈。Stack 裡的分工口訣：

Claude Code 生產 Diff，GitHub Runner 生產 Fact。

建議工作流：

1. 開發者在 Cloud Mac / 本機 Mac 上用 Claude Code 完成改動，推送到 feature 分支
2. Self-hosted Runner（與 Agent 環境隔離）觸發 xcodebuild test / pnpm test 等
3. PR 必須 CI 綠燈 + 人工 review 才能合併
4. 生產 secrets 只存在於 Runner 或密鑰管理服務，不進 Agent 日常 shell 環境

Runner 註冊與隔離配置：執行引擎 · 排隊與 TCO · 一 job 一 workspace。

若本機同時跑 Ollama + Claude Code + Runner，注意記憶體排班，避免 Swap 拖慢 CI——見 並行排班。

生產級清單（上線前必查）

知識骨架 · #production · 生產清單

從「能跑」到「能上線」，過一遍這張表：

Stack 全鏈路地圖

知識骨架 · #stack-map · Stack 定位

把本篇放進 Cloud Mac AI Stack，你在整條鏈上的位置如下：

• L0 底座 — 為什麼用 Cloud Mac
• L1 執行 — GitHub Runner（Fact 層）
• L2 推理 — Ollama 私有推理（可選，本機 embedding / 小模型）
• L3 編碼 — 本篇 · Claude Code 完整手冊（Diff 層主線）
• L4 連接 — MCP 三連通
• L5 自動化 — OpenHands Agent 平台

Stack 總架構圖 + 五模組接入順序見支柱地圖 L6-Q02 · Claude Code 核心架構與 Stack 總圖——本篇是其中「編碼 Agent」段的落地手冊。

常見問題

知識骨架 · #faq · 補充答疑

Claude Code 一定要買 Mac 才能用嗎？ 官方支援 macOS 和 Linux。涉及 iOS / macOS 建置時必須用 Mac，可本機或 Cloud Mac。

訂閱和 API Key 怎麼選？ 個人試跑 Pro / Max 訂閱最省事；團隊或 CI 整合往往用 API Key + 用量管控。成本對比見 模型計費。

生產級是不是一定要 MCP？ 小倉庫可以沒有；一旦要讀 GitHub Issue、跨服務查文件，MCP 幾乎是標配。

Agent 改壞了怎麼辦？ git checkout -- . 或 git stash；養成小步提交、頻繁分支，別在髒工作區上堆多個委託。

• L3 決策：什麼時候該讓 Agent 正式接入
• Claude Code MCP 安裝教程
• Mac mini 工作站實測
• GitHub Runner 執行引擎