生產環境模式
掌握可觀測性、監控和部署模式以用於生產環境。
你將學到什麼
到目前為止，你一直將 Claude Code 作為個人工具使用 — 一個開發者在終端機中操作。但 Claude Code 也可以在 CI/CD 流水線中以無頭模式運行、服務整個團隊，並作為自動化工作流的一部分。從開發環境遷移到生產環境，需要你對任何生產系統都會應用的同等嚴謹：監控、測試、錯誤處理和成本控制。
完成後，你將了解：
- 如何以無頭（非互動）模式運行 Claude Code
- 搭配 GitHub Actions 的 CI/CD 整合模式
- 可觀測性：日誌、追蹤和監控代理行為
- 成本追蹤和預算策略
- 在進入生產環境前測試代理工作流
- 擴展 AI 輔助開發的成熟度模型
問題是什麼
一個在你筆電上運行的工具和一個在生產環境可靠運行的工具是不同的。差距在於：
開發環境： 生產環境：
───────────── ────────────
一個使用者 多個使用者/觸發器
互動式終端 無頭模式，無 UI
錯誤 → 你能看到 錯誤 → 靜默失敗
成本 → 你的 API 帳單 成本 → 團隊/組織預算
測試 → 「在我這裡可以」 測試 → 自動化驗證
監控 → 你在看著 監控 → 儀表板 + 告警每個差距都是潛在的失敗模式。本堂課涵蓋如何彌合每一個差距。
如何運作
無頭模式
Claude Code 可以在沒有終端 UI 的情況下運行，使其適合自動化：
# 管道輸入提示，取得結構化輸出
echo "Review this PR for security issues" | claude --output-format json
# 一次性模式搭配特定提示
claude -p "Summarize the changes in the last 3 commits" --output-format json
# 從 stdin 讀取並指定允許的工具
cat requirements.txt | claude -p "Check for outdated dependencies"--output-format json 旗標對自動化至關重要。不是人類可讀的終端輸出，而是結構化的 JSON：
{
"result": "Found 2 security issues:\n1. SQL injection in user_query.py:45\n2. Missing auth check in api/admin.py:12",
"cost_usd": 0.023,
"duration_ms": 4500,
"model": "claude-sonnet-4-20250514",
"session_id": "sess_abc123"
}這個輸出可以被下游工具解析、儲存在資料庫中，或發送到儀表板。
CI/CD 整合
最常見的生產模式：Claude Code 在 GitHub Actions 中運行。
# .github/workflows/ai-review.yml
name: AI Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: Run AI Review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
# Get the diff
DIFF=$(git diff origin/main...HEAD)
# Run Claude Code in headless mode
REVIEW=$(echo "$DIFF" | claude -p \
"Review this diff for bugs, security issues, and style problems.
Output as JSON with fields: summary, findings (array),
recommendation (approve/request_changes)." \
--output-format json)
echo "$REVIEW" > review-output.json
- name: Post Review Comment
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const review = JSON.parse(fs.readFileSync('review-output.json', 'utf8'));
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: `## AI Code Review\n\n${review.result}`
});這會在每個 PR 上運行。AI 審查 diff 並將發現作為評論發布。無需人類觸發 — 完全自動化。
可觀測性
生產環境的 AI 代理需要與任何生產服務相同的可觀測性：
┌──────────────────────────────────────────────────────┐
│ 可觀測性堆疊 │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ 第 1 層：日誌 │ │
│ │ • 發送了什麼提示 │ │
│ │ • 呼叫了什麼工具（及結果） │ │
│ │ • 最終輸出是什麼 │ │
│ │ • 遇到了什麼錯誤 │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ 第 2 層：指標 │ │
│ │ • 每個會話使用的 token 數 │ │
│ │ • 每個會話/每個專案的成本 │ │
│ │ • 每個會話的持續時間 │ │
│ │ • 工具呼叫次數 │ │
│ │ • 錯誤率 │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ 第 3 層：告警 │ │
│ │ • 會話成本超過閾值 │ │
│ │ • 錯誤率飆升 │ │
│ │ • 代理陷入迴圈（持續時間異常） │ │
│ │ • 偵測到非預期的工具呼叫 │ │
│ └─────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────┘成本監控
在生產環境中，API 成本需要追蹤和預算：
┌──────────────────────────────────────────────────┐
│ 成本控制層 │
│ │
│ 第 1 層：每個會話的限制 │
│ ┌──────────────────────────────────────────┐ │
│ │ claude --max-tokens 50000 │ │
│ │ 為單個會話設定 token 上限 │ │
│ └──────────────────────────────────────────┘ │
│ │
│ 第 2 層：模型選擇 │
│ ┌──────────────────────────────────────────┐ │
│ │ Haiku 用於簡單任務 ~$0.001/呼叫 │ │
│ │ Sonnet 用於程式碼任務 ~$0.01/呼叫 │ │
│ │ Opus 用於關鍵任務 ~$0.05/呼叫 │ │
│ └──────────────────────────────────────────┘ │
│ │
│ 第 3 層：預算儀表板 │
│ ┌──────────────────────────────────────────┐ │
│ │ 追蹤：每個專案、每個開發者、 │ │
│ │ 每種工作流類型的成本，隨時間變化 │ │
│ └──────────────────────────────────────────┘ │
│ │
│ 第 4 層：告警 │
│ ┌──────────────────────────────────────────┐ │
│ │ 「專案 X 今天花了 $50（限制：$20）」 │ │
│ │ → Slack 告警通知團隊負責人 │ │
│ └──────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────┘一個簡單的成本追蹤包裝器：
#!/bin/bash
# track-cost.sh - Wrapper that logs Claude Code costs
PROJECT="$1"
PROMPT="$2"
# Run Claude Code and capture JSON output
OUTPUT=$(claude -p "$PROMPT" --output-format json 2>/dev/null)
# Extract cost
COST=$(echo "$OUTPUT" | jq -r '.cost_usd // 0')
MODEL=$(echo "$OUTPUT" | jq -r '.model // "unknown"')
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
# Log to CSV
echo "$TIMESTAMP,$PROJECT,$MODEL,$COST" >> ~/.claude/cost-log.csv
# Return the result
echo "$OUTPUT" | jq -r '.result'測試代理工作流
代理工作流需要像程式碼一樣進行測試。三個層級：
┌──────────────────────────────────────────────────────┐
│ 代理測試金字塔 │
│ │
│ /\ │
│ / \ │
│ / E2E \ 完整工作流測試 │
│ / test \ 「/deploy 能運作嗎？」 │
│ /──────────\ │
│ / \ │
│ / Integration \ Skill + 工具測試 │
│ / tests \ 「這個 skill │
│ / \ 是否觸發了正確 │
│ /────────────────────\ 的工具？」 │
│ / \ │
│ / Unit tests \ 個別規則 │
│ / (CLAUDE.md rules, \ 「這個規則 │
│ / skill files) \ 解析正確嗎？」 │
│ /──────────────────────────────\ │
│ │
└──────────────────────────────────────────────────────┘單元測試：驗證你的 CLAUDE.md 和 skill 檔案格式正確，包含預期的指令。
# Test that skill files exist and are non-empty
for skill_dir in .claude/skills/*/; do
if [ ! -f "$skill_dir/SKILL.md" ]; then
echo "FAIL: Missing SKILL.md in $skill_dir"
exit 1
fi
if [ ! -s "$skill_dir/SKILL.md" ]; then
echo "FAIL: Empty SKILL.md in $skill_dir"
exit 1
fi
done
echo "PASS: All skill files present and non-empty"整合測試：用已知的提示運行 Claude Code，並驗證它使用了預期的工具。
# Test that the review skill reads the right files
OUTPUT=$(claude -p "/review" --output-format json 2>/dev/null)
if echo "$OUTPUT" | jq -r '.result' | grep -q "Security Review"; then
echo "PASS: Review skill produced security section"
else
echo "FAIL: Review skill missing security section"
fi端對端測試：在測試環境中運行完整的工作流，並驗證結果。
成熟度模型
團隊分階段採用 Claude Code。每個階段解鎖更多價值：
┌──────────────────────────────────────────────────────┐
│ AI 輔助開發成熟度 │
│ │
│ 階段 1：臨時使用 │
│ ├── 個別開發者使用 Claude Code │
│ ├── 沒有共享的設定 │
│ ├── 每個人有自己的工作流 │
│ └── 價值：個人生產力提升 │
│ │
│ 階段 2：個人自動化 │
│ ├── 帶有專案規則的自定義 CLAUDE.md │
│ ├── 用於重複任務的個人 skills │
│ ├── 常見操作的允許清單 │
│ └── 價值：一致的個人工作流 │
│ │
│ 階段 3：團隊標準化 │
│ ├── 共享的 CLAUDE.md 已簽入版本庫 │
│ ├── 團隊的 skills 和 agents 在 .claude/ 中 │
│ ├── CI/CD 整合用於審查和檢查 │
│ ├── 每個專案的成本監控 │
│ └── 價值：團隊級的一致性和品質 │
│ │
│ 階段 4：平台整合 │
│ ├── Claude Code 在所有 CI/CD 流水線中 │
│ ├── 為內部工具建立自定義 MCP 伺服器 │
│ ├── 可觀測性儀表板 │
│ ├── 跨團隊的 skill 共享 │
│ ├── 預算管理和治理 │
│ └── 價值：組織級能力 │
│ │
└──────────────────────────────────────────────────────┘大多數團隊在階段 1 或 2。階段 3 是乘數效應開始的地方 — 共享的知識意味著每個團隊成員都能從最佳工作流中受益。
關鍵洞見
生產環境的 Claude Code 關乎可靠性和可預測性。 讓軟體具備生產就緒性的相同原則 — 監控、測試、錯誤處理、成本管理 — 直接適用於 AI 代理系統。
一個在你筆電上 95% 時間都能運作的代理不算是生產就緒。生產就緒意味著：
- 你知道它何時失敗（監控）
- 你知道它為什麼失敗（日誌）
- 你知道它花了多少錢（預算）
- 你知道它會表現一致（測試）
- 你知道它不會做出非預期的事（權限）
這些工具並不特殊。它們是軟體工程師幾十年來一直在使用的相同工具：日誌、指標、告警、測試和 CI/CD。唯一的區別是被監控的「服務」是一個 AI 代理，而不是一個網頁伺服器。
實作範例
以下是一個完整的 GitHub Actions 工作流，它將 Claude Code 作為自動化程式碼審查者運行，具備成本追蹤和錯誤處理：
# .github/workflows/claude-review.yml
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
permissions:
contents: read
pull-requests: write
jobs:
ai-review:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: Run Review
id: review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
# Get changed files
FILES=$(git diff --name-only origin/main...HEAD)
# Run review with timeout and cost cap
claude -p "Review these changed files for bugs and
security issues: $FILES. Be concise." \
--output-format json \
--max-turns 20 \
> review.json 2>&1 || true
# Check if output is valid JSON
if ! jq empty review.json 2>/dev/null; then
echo '{"result": "Review failed to produce output"}' > review.json
fi
- name: Post Results
if: always()
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
let review;
try {
review = JSON.parse(fs.readFileSync('review.json', 'utf8'));
} catch (e) {
review = { result: 'Review failed: ' + e.message };
}
const body = [
'## AI Code Review',
'',
review.result || 'No output',
'',
'---',
`Model: \`${review.model || 'unknown'}\` | ` +
`Cost: \`$${review.cost_usd || '?'}\` | ` +
`Duration: \`${review.duration_ms || '?'}ms\``
].join('\n');
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body
});此工作流中的關鍵生產細節：
timeout-minutes: 10— 防止失控的會話--max-turns 20— 限制代理迴圈的迭代次數|| true— 防止該步驟導致整個工作流失敗- JSON 驗證 — 處理輸出格式錯誤的情況
- 評論中的成本 — 每次審查都顯示其成本以增加透明度
if: always()— 即使審查步驟出錯也會發布結果
前後對比
| 開發環境使用 | 生產環境使用 |
|---|---|
| 互動式終端 | 無頭模式，JSON 輸出 |
| 一個開發者 | 整個團隊，CI/CD 觸發 |
| 手動監控 | 儀表板和告警 |
| 成本是個人的 | 成本被追蹤和預算化 |
| 「在我這裡可以」的測試 | 自動化驗證 |
| 臨時工作流 | 標準化的、受版本控制的 skills |
| 單一會話 | 大規模的並行會話 |
課程總結
你已經完成了 Claude Code 架構精通課程 — 橫跨四個模組的 24 堂課。
你學到了什麼
模組 1：核心代理（第 1-6 堂課）
你從基礎開始。Agent Loop — 在 end_turn 和 tool_use 之間路由的非同步訊息迴圈。帶有權限閘門的工具系統。使用 TodoWrite 進行規劃。子代理和上下文隔離。Skills 和知識載入。上下文壓縮和記憶體管理。
這六堂課給了你心智模型：Claude Code 不是一個聊天機器人。它是一個帶有工具、權限和上下文管理的代理迴圈。
模組 2：多代理（第 7-12 堂課） 你開始擴展。帶有依賴邊的任務圖。平行運行的背景任務。透過共享上下文通訊的代理團隊。協調用的團隊協議。帶有工作/閒置階段的自主代理。用於安全平行開發的 Worktree 隔離。
這些課程向你展示，複雜的工作需要多個代理，每個都有自己的上下文，透過定義良好的協議進行協調。
模組 3：真實架構（第 13-18 堂課） 你深入了解了機制。用於引導代理行為的控制協議。用於連接外部服務的 MCP 整合。事件驅動可擴展性的 Hooks 系統。會話儲存和狀態持久化。用於塑造代理行為的 CLAUDE.md 設計。權限模型和安全架構。
這些課程給了你實際知識，讓你能為真實世界的使用設定、擴展和保護 Claude Code。
模組 4：精通（第 19-24 堂課） 你達到了生產就緒。用於平行開發的多 CLI 工作流。帶有重試邏輯和備用策略的錯誤恢復。跨模型選擇和 token 管理的成本優化。人機協作設計以平衡自主性和監督。用於編碼團隊知識的自定義 agents 和 skills。最後，大規模可靠性的生產模式。
核心原則
在全部 24 堂課中，幾個原則一再出現：
-
Agent Loop 是基礎。 所有東西 — 工具、子代理、skills、團隊 — 都建構在簡單的迴圈之上：呼叫 API、檢查停止原因、執行工具、重複。
-
上下文是最珍貴的資源。 上下文視窗是有限的。每個設計決策 — 子代理、壓縮、skills、worktrees — 最終都是關於有效管理上下文。
-
權限是安全網。 「AI 可以做任何事」和「AI 是有用的」之間的差距，由權限系統來彌合。信任隨時間逐步建立，從嚴格到自主。
-
Markdown 是擴展語言。 CLAUDE.md、skills、agents — 全是 Markdown。無需編譯、無需部署、無需框架。放入一個檔案，獲得一個能力。
-
生產環境需要生產紀律。 監控、測試、錯誤處理、成本管理。工具是熟悉的。應用場景是新的。
接下來去哪裡
本課程教了你架構 — Claude Code 如何運作以及如何擴展它。以下是前進的方向：
-
建構你自己的 skills 庫。 從你的團隊最常做的三個工作流開始。將它們編碼為 skills。根據實際使用進行迭代。
-
設定 CI/CD 整合。 從 PR 上的自動化程式碼審查開始。衡量建議的品質。根據結果調整你的 CLAUDE.md 和提示。
-
貢獻社群。 分享你的 skills、agents 和模式。Claude Code 生態系統透過共享知識而成長。
-
突破邊界。 多代理架構、自定義 MCP 伺服器、新穎的代理協調模式 — 這個領域還很年輕，設計空間廣闊。
你現在擁有在 Claude Code 之上建構的架構知識，而不只是使用它。這就是使用者和建構者之間的區別。
開始建構吧。