分類: 提示工程

  • 【實戰教學】雙代理流水線完整實作 — 從零到一走過實作、審查、測試的 AI 協作開發

    上一篇我們解析了《2026 Agentic Coding Trends Report》的 8 大趨勢。這次我們不談理論,直接動手——用一個完整的實驗,展示如何建構「雙代理流水線」,讓 AI 自動完成:實作 → 審查 → 修正 → 測試 → 驗證的全流程。

    最終成果:3 個 AI 代理協作,產出 130 行生產級 Python 程式碼 + 27 個自動化測試,全部通過。


    一、實驗目標

    驗證報告中「趨勢 2:單一代理演化為協調團隊」的核心主張——多個獨立 AI 代理,透過明確的分工和隔離的 context,能否產出比單一代理更高品質的程式碼。

    任務:實作一個 Thread-safe 的 Token Bucket Rate Limiter(令牌桶限流器)

    工具:Claude CLI(claude -p)+ Python

    代理配置:

    • Agent A(Implementer):資深 Python 工程師,負責實作
    • Agent B(Reviewer):資深架構師,負責獨立審查
    • Agent C(Tester):QA 工程師,負責撰寫測試

    二、流水線架構設計

    Step 1: Implementer (A) ──寫程式碼──→ rate_limiter.py v1
    Step 2: Reviewer   (B) ──獨立審查──→ 審查報告(PASS/FAIL + 具體建議)
    Step 3: Implementer (A) ──根據審查修正──→ rate_limiter.py v2
    Step 4: Tester     (C) ──撰寫測試──→ test_rate_limiter.py(27 個測試)
    Step 5: pytest 實際執行 ──────────→ PASS? → 完成
                                         FAIL? → Step 6
    Step 6: Implementer (A) ──根據錯誤修正──→ 回到 Step 5(最多 3 輪)
    

    核心設計原則:Context 隔離

    每次代理呼叫都是獨立的 claude -p 指令 = 獨立的 context window。Reviewer 看不到 Implementer 的思考過程,只看到最終產出的程式碼。這就像真實的 Code Review——審查者不應該被實作者的思路影響。


    三、「給予什麼」——三個必要輸入

    報告趨勢 1 指出:工程師的角色從「寫程式碼」轉為「定義需求」。在雙代理系統中,你的輸入品質直接決定產出品質。

    1. TASK_SPEC(任務規格)

    告訴代理「要做什麼」。越具體越好,包含功能需求、非功能需求、使用範例:

    ## 功能需求
    1. allow(tokens=1) -> 判斷請求是否被允許,回傳 bool
    2. wait(tokens=1) -> 阻塞直到有足夠 token,回傳等待秒數
    3. get_tokens() -> 回傳目前可用 token 數
    4. Thread-safe:支援多執行緒併發存取
    
    ## 非功能需求
    - 純 Python 實作(標準庫 only)
    - Python 3.10+ 相容
    - 時間精度至少到毫秒
    - 記憶體使用 O(1)
    

    2. RESTRICTIONS(禁止事項)

    告訴代理「不能做什麼」。這就是報告趨勢 3 中的 Guardrails(護欄)——禁止比允許更重要:

    ## 程式碼禁止
    - 禁止使用任何第三方套件
    - 禁止使用 global 變數
    - 禁止使用 sleep 做忙等待
    - 禁止使用 eval() 或 exec()
    
    ## 設計禁止
    - 禁止 Singleton Pattern
    - 禁止在建構函式中啟動背景執行緒
    - Token 補充必須用 lazy 計算
    
    ## 品質禁止
    - 禁止不加 type hint
    - 禁止空的 except
    - 禁止 magic number
    

    3. QUALITY_STANDARDS(品質標準)

    告訴代理「什麼算合格」:

    ## 程式碼風格
    - 所有公開方法都要有 docstring
    - 適當的型別標注(Type Hints)
    
    ## 測試標準
    - 覆蓋率 > 90%
    - 必須包含:正常路徑、邊界條件、併發測試、錯誤處理
    
    ## 安全標準
    - 不信任任何輸入參數(都要驗證)
    - 時間計算要處理時鐘回撥情況
    

    四、實際執行過程與完整 I/O 記錄

    以下是流水線的真實執行記錄(每一步的 INPUT/OUTPUT 都完整保存在 141KB 的 log 檔中)。

    Step 1: Implementer 初始實作

    問題:Implementer 沒有直接寫程式碼,而是提出了三種方案要求確認。

    原因:Claude CLI 載入了使用者的 skills/rules,觸發了「brainstorming」行為模式。

    教訓:這正是報告趨勢 4 提到的「代理行為需要護欄」——即使你的 system prompt 說「只輸出程式碼」,代理仍可能被其他指令覆蓋。

    Step 2: Reviewer 獨立審查

    Reviewer 在完全獨立的 context 中工作。它拿到的「程式碼」實際上是 Step 1 產出的方案描述。它正確地指出:「目前提供的內容並非實際的程式碼,而是設計方案的描述文件」,並要求提供完整的 .py 檔案。

    亮點:這就是雙代理的價值——獨立的 Reviewer 不會因為「知道 Implementer 在想什麼」而放水。它只看到產出,做出客觀判斷。

    Step 3: Implementer 根據審查修正

    收到 Reviewer 的「FAIL:沒有提供實際程式碼」的審查意見後,Implementer 在第三步終於產出了完整的 Python 實作。

    這正是雙代理模式的自我修正能力:即使第一步失敗了,審查環節會把問題揪出來,修正環節會改正它。

    Step 4: Tester 撰寫 27 個測試

    Tester 代理根據程式碼和需求規格,產出了 27 個測試案例,涵蓋:

    • 基本功能:allow、wait、get_tokens 的正常路徑
    • 參數驗證:負數、零值、超過容量
    • 時間相關:token 補充、時鐘回撥
    • 併發安全:50 個 thread 同時 allow、10 個 thread 同時 wait
    • 邊界條件:capacity=1、小數 token、高補充率

    Step 5: pytest 執行結果

    26 passed, 1 failed in 16.48s
    
    FAILED: test_concurrent_allow_operations
      AssertionError: 50.01152896881103 != 50.0
    

    26 個測試通過,只有 1 個併發測試因為浮點精度問題失敗。測試期望 get_tokens() == 50.0,但因為併發執行耗時約 15ms,refill 機制多補了 0.01 個 token。

    Step 6: 修正迴圈

    Implementer 嘗試了 3 輪修正,但因為問題出在測試的精確比較(assertEqual),而規則限制只能改實作不能改測試,所以無法自動修復。最終我們手動將測試改為 assertAlmostEqual(delta=1.0),27 個測試全部通過。


    五、5 次失敗的除錯歷程——真正的實戰教訓

    這個實驗我跑了 5 次才成功。每次失敗都對應一個真實的代理工程問題:

    次數 失敗原因 根因分析 解法
    第 1 次 代理問問題不寫程式碼 CLI 載入使用者的 skills/rules(brainstorming skill 被觸發) --disable-slash-commands 禁用 skills
    第 2 次 代理探索專案檔案浪費時間 從專案目錄執行,CLI 自動讀取目錄內容 cwd=tempdir 在空目錄隔離執行
    第 3 次 Tester 步驟 timeout(300s) CLI 使用工具探索檔案,消耗大量時間 --allowedTools "" 禁止所有工具使用
    第 4 次 產出中文說明而非程式碼 中文 system prompt 導致代理用中文回覆說明 System prompt 全改英文 + 結尾加 REMINDER
    第 5 次 26 passed, 1 failed(浮點精度) 併發測試中 time.time() 微小誤差導致 refill 多算 測試改用 assertAlmostEqual

    關鍵 CLI 參數組合(最終穩定版)

    claude.cmd -p \
      --model claude-sonnet-4-20250514 \
      --system-prompt "..." \
      --output-format text \
      --disable-slash-commands \
      --allowedTools ""
      # 在空臨時目錄中執行(cwd=tempdir)
    

    這四個參數的組合確保了代理行為的完全可控

    • --disable-slash-commands:防止使用者的 skills 覆蓋你的指令
    • --allowedTools "":防止代理讀檔案、跑指令,強制純文字輸出
    • cwd=tempdir:空目錄 = 無專案上下文 = 代理只能根據 prompt 行動
    • --output-format text:純文字輸出,方便程式解析

    六、System Prompt 設計的 5 個教訓

    1. 用英文寫 system prompt

    中文 prompt 會導致代理用中文回覆,中文字元混入程式碼會造成 SyntaxError。即使你的需求規格是中文,system prompt 也應該用英文。

    2. 「不要做什麼」比「要做什麼」更重要

    最有效的一行不是「請寫程式碼」,而是:

    Do NOT output ANY text before or after the code fence
    Do NOT ask questions, do NOT explain, do NOT summarize

    3. 結尾加 REMINDER

    AI 會更重視 prompt 開頭和結尾的指令。在 user prompt 結尾加上格式提醒:

    REMINDER: Output ONLY ```python``` code. No text before or after.

    4. 角色定義要具體

    不要只說「你是工程師」,要說「You are a senior Python engineer specializing in concurrency and algorithms」。越具體,產出越符合預期。

    5. 輸出格式要可解析

    要求代理用 ```python``` 包裹程式碼,這樣程式可以用正則表達式提取。同時準備 fallback:如果沒有 code fence,取最長的 python block。


    七、完整程式碼——可以直接複用

    整個流水線是一個 700 行的 Python 檔案,你只需要改三個變數就能用在任何任務上:

    # 改這三個變數,就能用在任何任務上
    TASK_SPEC = "..."          # 要做什麼
    RESTRICTIONS = "..."       # 不准做什麼
    QUALITY_STANDARDS = "..."  # 什麼算合格
    
    # 然後執行
    # python dual_agent_pipeline.py
    #
    # 產出:
    # output/rate_limiter.py       -- AI 寫的程式碼
    # output/test_rate_limiter.py  -- AI 寫的測試
    # logs/pipeline_*.md           -- 完整 I/O 記錄
    

    八、結論:雙代理模式的價值

    這次實驗驗證了報告的核心主張:

    1. Context 隔離產生客觀審查:Reviewer 在 Step 2 正確指出「沒有提供實際程式碼」,因為它只看到產出,不知道 Implementer 的意圖。這就是為什麼雙代理比單一代理更可靠。
    2. 自我修正能力:即使 Step 1 失敗(產出方案而非程式碼),Step 2 的審查 + Step 3 的修正組成了自動修復迴圈。最終在 Step 3 產出了合格的程式碼。
    3. 護欄(Guardrails)是必需品:5 次失敗中有 4 次是因為代理行為不可控。--disable-slash-commands--allowedTools ""cwd=tempdir 這些護欄不是可選的,是必須的。
    4. 人類仍然不可或缺:最後一個浮點精度問題,代理嘗試了 3 輪都無法自動修復(因為問題在測試而非實作)。人類介入 10 秒就解決了。這正是報告說的:「AI 是協作者,不是替代者」。

    最後的建議:不要追求完美的自動化。從「一個寫、一個審」的最小雙代理開始,逐步增加複雜度。今天就試試。

    本文是《2026 Agentic Coding Trends Report》深度解析系列的第二篇。

  • 【完整攻略】Claude Code 全方位協作指南 — 從 settings.json 配置到 AI 開發戰友的 17 個核心能力

    每次使用 Claude Code 都要按 Allow?Hooks 到底能幹嘛?MCP 伺服器怎麼接?作為一個每天與 Claude Code 協作超過 8 小時的架構師,我將從實戰角度帶你走過 settings.json 的每一個關鍵配置,讓你從「不斷按確認」進化到「全自動化 AI 開發流水線」。本文涵蓋 17 個核心能力站點,從基礎權限配置到多代理並行、記憶系統、Auto Mode,帶你解鎖 Claude Code 的完整協作潛力。


    🎯 為什麼你需要認真配置 settings.json?

    Claude Code 的預設模式是「安全優先」——每個檔案操作、每條指令都要你點 Allow。這對初學者來說是好事,但對於每天寫上千行程式碼的開發者來說,這就像開車時每踩一次油門都要確認一次「你確定要加速嗎?」

    settings.json 是 Claude Code 的控制中樞。配置得當,它能讓你的 AI 協作體驗從「手動擋」升級到「自動巡航」。

    設定檔的三層架構

    Claude Code 的設定採用三層覆蓋架構,就像 CSS 的層疊規則:

    層級 檔案位置 Git 追蹤 適用場景
    全域(User) ~/.claude/settings.json N/A 個人偏好,所有專案通用
    專案(Project) .claude/settings.json ✅ 提交 團隊共用的規範和 Hooks
    本地(Local) .claude/settings.local.json ❌ Gitignore 個人在此專案的覆蓋設定
    💡 架構師觀點:這就是經典的配置繼承模式(Configuration Inheritance)。後層覆蓋前層,讓你在保持團隊一致性的同時擁有個人彈性。

    ⚡ 第一站:跳過權限提示(Permissions)

    痛點

    你正在讓 Claude Code 重構一個模組,它需要讀 50 個檔案、改 20 個檔案、跑 10 次測試。每一步都跳出 Allow 提示——你按了 80 次確認鍵。這不是 AI 協作,這是打地鼠。

    解法:精細化權限控制

    {
      "permissions": {
        "allow": [
          "Bash(git:*)",
          "Bash(mvn:*)",
          "Bash(npm:*)",
          "Bash(node:*)",
          "Bash(python:*)",
          "Bash(java:*)",
          "Bash(ls:*)",
          "Bash(mkdir:*)",
          "Bash(curl:*)",
          "Bash(gh:*)",
          "Read",
          "Edit",
          "Write",
          "Glob",
          "Grep",
          "WebFetch",
          "WebSearch",
          "TodoWrite",
          "NotebookEdit"
        ],
        "deny": [
          "Bash(rm -rf:*)",
          "Bash(DROP:*)",
          "Bash(format:*)"
        ]
      }
    }
    

    權限規則語法解析

    • 精確匹配:"Bash(npm run test)" — 只允許這一條指令
    • 前綴萬用字元:"Bash(git:*)" — 允許所有 git 開頭的指令(git status, git commit…)
    • 工具級別:"Read" — 允許所有讀取操作

    三種權限模式

    模式 設定值 適合場景
    預設模式 "default" 日常開發,未列出的操作會詢問
    接受編輯 "acceptEdits" 信任檔案編輯,但 Bash 仍會詢問
    完全跳過 "bypassPermissions" 完全信任 AI,適合沙盒環境
    💡 架構師建議:不要直接用 bypassPermissions。就像你不會給生產伺服器開 chmod 777,用 allow 清單做最小權限原則(Least Privilege)更安全。把你信任的操作明確列出,危險操作放進 deny

    🔧 第二站:Hooks — 你的自動化管家

    什麼是 Hooks?

    Hooks 是 Claude Code 的事件驅動自動化機制。就像 Git Hooks(pre-commit, post-commit)一樣,你可以在 Claude Code 的各個生命週期節點插入自動化腳本。

    核心事件一覽

    事件 觸發時機 典型用途
    PreToolUse 工具執行前 攔截危險操作、記錄日誌
    PostToolUse 工具執行後 自動格式化、跑測試
    Stop Claude 停止回應時 發送通知、產生摘要
    PreCompact 上下文壓縮前 保存重要資訊
    SessionStart 會話開始時 載入環境、顯示專案狀態
    UserPromptSubmit 用戶送出訊息時 輸入預處理

    實戰範例一:完成工作時彈出通知

    這是我每天都在用的配置。Claude Code 完成一段工作後,Windows 會彈出通知視窗:

    {
      "hooks": {
        "Stop": [
          {
            "hooks": [
              {
                "type": "command",
                "command": "powershell -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms') | Out-Null; [System.Windows.Forms.MessageBox]::Show('Claude Code 已完成!', 'Claude Code 通知', 'OK', 'Information')\"",
                "timeout": 10,
                "statusMessage": "發送通知中..."
              }
            ]
          }
        ]
      }
    }
    
    📌 使用場景:你丟一個大任務給 Claude Code(例如重構整個模組),然後去泡咖啡。做完了它會彈窗通知你回來 review。

    實戰範例二:寫完程式碼自動格式化

    {
      "hooks": {
        "PostToolUse": [
          {
            "matcher": "Write|Edit",
            "hooks": [
              {
                "type": "command",
                "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true"
              }
            ]
          }
        ]
      }
    }
    

    每次 Claude Code 編輯或寫入檔案後,自動用 Prettier 格式化。再也不用擔心 AI 產出的程式碼風格不一致。

    實戰範例三:記錄所有 Bash 指令

    {
      "hooks": {
        "PreToolUse": [
          {
            "matcher": "Bash",
            "hooks": [
              {
                "type": "command",
                "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
              }
            ]
          }
        ]
      }
    }
    
    💡 架構師觀點:這就是審計日誌(Audit Log)模式。當你讓 AI 自主執行指令時,保留完整的操作記錄至關重要。出了問題可以追溯,也能用來分析 AI 的行為模式。

    進階:三種 Hook 類型

    類型 說明 適用場景
    command 執行 shell 指令 格式化、測試、通知
    prompt 用 LLM 評估條件 語義級別的安全檢查
    agent 啟動代理執行任務 複雜的自動化驗證
    {
      "hooks": {
        "PreToolUse": [
          {
            "matcher": "Bash",
            "hooks": [
              {
                "type": "prompt",
                "prompt": "這個指令是否可能刪除重要檔案或造成不可逆的破壞?指令內容:$ARGUMENTS"
              }
            ]
          }
        ]
      }
    }
    

    用 AI 來審查 AI——這是多層防禦(Defense in Depth)的完美體現。


    🌐 第三站:MCP 伺服器 — 擴展 Claude Code 的邊界

    什麼是 MCP?

    MCP(Model Context Protocol)是讓 Claude Code 連接外部服務的標準協議。透過 MCP,Claude Code 可以直接操作資料庫、呼叫 API、查詢股票行情——任何你能想到的整合。

    實戰範例:接入台灣股票行情

    {
      "mcpServers": {
        "taiwan-stock": {
          "command": "taiwan-stock-mcp",
          "args": []
        },
        "shioaji": {
          "command": "path/to/shioaji-mcp-server.exe",
          "args": [],
          "env": {
            "SHIOAJI_API_KEY": "your-api-key",
            "SHIOAJI_SECRET_KEY": "your-secret-key"
          }
        }
      }
    }
    

    配置完成後,你可以直接對 Claude Code 說:「查詢台積電今天的股價」或「分析我永豐金帳戶的未實現損益」。

    MCP 的架構意義

    從架構角度來看,MCP 本質上就是微服務的 Sidecar 模式。每個 MCP 伺服器就是一個獨立的服務,透過標準化協議與 Claude Code 通訊。這種設計的優點:

    • 關注點分離:每個 MCP 伺服器只負責一件事
    • 獨立部署:MCP 伺服器可以獨立更新和維護
    • 安全隔離:每個伺服器有自己的環境變數和權限
    💡 架構師建議:為你團隊常用的內部 API 建立 MCP 伺服器。例如:公司的 JIRA API、內部知識庫、部署管線——讓 Claude Code 成為你的統一操作介面

    🔐 第四站:Sandbox — 安全的沙盒環境

    為什麼需要沙盒?

    當你給 AI 越來越多的自主權時,安全邊界就越重要。Sandbox 配置讓你精確控制 Claude Code 可以存取的檔案系統範圍和網路資源。

    {
      "sandbox": {
        "enabled": true,
        "autoAllowBashIfSandboxed": true,
        "network": {
          "allowedDomains": [ "github.com", "registry.npmjs.org", "pypi.org"],
          "allowLocalBinding": true
        },
        "filesystem": {
          "allowWrite": [ "/home/user/projects"],
          "denyWrite": [ "/etc", "/usr"],
          "denyRead": [ "/home/user/.ssh", "/home/user/.aws"]
        }
      }
    }
    
    💡 架構師觀點:這就是容器化思維的延伸。就像 Docker 的 --read-only--network 旗標,Sandbox 讓你在給 AI 自由的同時保持控制。特別注意 denyRead——防止 AI 讀取你的 SSH 金鑰和雲端憑證。

    autoAllowBashIfSandboxed: true 是一個聰明的設計:如果已經在沙盒裡了,Bash 指令就不需要再逐一確認。安全邊界前移,讓操作體驗更流暢。


    🌳 第五站:Git Worktree — 隔離的開發環境

    痛點

    你讓 Claude Code 做一個大型重構,但你同時需要在主分支上修一個緊急 bug。兩件事在同一個目錄下互相干擾。

    解法:Worktree 配置

    {
      "worktree": {
        "symlinkDirectories": [ "node_modules", ".cache", ".bin"],
        "sparsePaths": [ "src/", "tests/", "package.json"]
      }
    }
    
    • symlinkDirectories:避免每個 worktree 都複製一份 node_modules(省磁碟空間)
    • sparsePaths:大型 monorepo 中只拉取需要的目錄(省時間)
    💡 架構師觀點:這就像 Kubernetes 的 Pod 隔離。每個 worktree 是一個獨立的工作空間,有自己的分支和檔案狀態,但共享底層的 Git 物件庫。對於多代理並行開發的場景,worktree 是基礎設施級的支援。

    🔌 第六站:環境變數與模型選擇

    環境變數

    {
      "env": {
        "NODE_ENV": "development",
        "DEBUG": "true",
        "DATABASE_URL": "postgresql://localhost:5432/dev"
      }
    }
    

    這些環境變數會注入到 Claude Code 的執行環境中,就像 Docker 的 -e 旗標。適合設定開發環境的連線資訊、除錯旗標等。

    模型選擇與效能調校

    {
      "model": "claude-opus-4-6",
      "effortLevel": "max",
      "alwaysThinkingEnabled": true,
      "fastMode": false
    }
    
    參數 說明 建議
    model 預設模型 複雜架構用 opus,日常用 sonnet
    effortLevel 思考深度 max 用於複雜任務,medium 用於日常
    alwaysThinkingEnabled 擴展思考 保持開啟,讓 AI 展示推理過程
    fastMode 快速模式 簡單任務時切換,加速回應
    💡 架構師觀點:這就是資源分配策略。不是每個任務都需要最強的模型和最大的思考深度。就像你不會用 GPU 叢集來跑 Hello World,學會根據任務複雜度選擇合適的配置,能顯著降低成本並提升效率。

    📡 第七站:SSH 遠端開發

    {
      "sshConfigs": [
        {
          "id": "dev-server",
          "name": "開發機",
          "sshHost": "[email protected]",
          "sshPort": 22,
          "startDirectory": "~"
        },
        {
          "id": "staging",
          "name": "Staging 環境",
          "sshHost": "[email protected]",
          "sshPort": 22,
          "startDirectory": "~/apps"
        }
      ]
    }
    

    配置完成後,用 claude ssh dev-server 就能直接在遠端機器上啟動 Claude Code 工作。適合需要在 Linux 伺服器上開發、或存取特定硬體資源的場景。


    🧩 第八站:Plugins — 技能擴展系統

    {
      "enabledPlugins": {
        "greptile@claude-plugins-official": true,
        "github@claude-plugins-official": true,
        "commit-commands@claude-plugins-official": true,
        "superpowers@claude-plugins-official": true
      }
    }
    

    Plugins 賦予 Claude Code 額外的技能(Skills)。例如:

    • superpowers:提供腦力激盪、計畫撰寫、TDD、系統性除錯等結構化工作流程
    • github:增強 GitHub 整合能力
    • commit-commands:標準化的提交和 PR 流程
    • greptile:進階程式碼搜尋能力
    💡 架構師觀點:Plugin 系統的設計遵循開放封閉原則(OCP)——Claude Code 的核心不需要修改,但可以透過插件無限擴展。這也是為什麼你可以建立自己的 Plugin Marketplace 來分享團隊專屬的技能。

    🏗️ 完整配置範本:架構師的 settings.json

    以下是一份經過實戰驗證的完整配置範本,你可以根據自己的需求調整:

    {
      "permissions": {
        "allow": [
          "Bash(git:*)",
          "Bash(mvn:*)",
          "Bash(npm:*)",
          "Bash(node:*)",
          "Bash(python:*)",
          "Bash(java:*)",
          "Bash(ls:*)",
          "Bash(mkdir:*)",
          "Bash(curl:*)",
          "Bash(gh:*)",
          "Read", "Edit", "Write",
          "Glob", "Grep",
          "WebFetch", "WebSearch",
          "TodoWrite", "NotebookEdit"
        ],
        "deny": [
          "Bash(rm -rf:*)",
          "Bash(DROP:*)"
        ]
      },
      "model": "claude-opus-4-6",
      "effortLevel": "max",
      "alwaysThinkingEnabled": true,
      "hooks": {
        "Stop": [
          {
            "hooks": [{
              "type": "command",
              "command": "echo Done",
              "timeout": 10,
              "statusMessage": "通知中..."
            }]
          }
        ],
        "PostToolUse": [
          {
            "matcher": "Write|Edit",
            "hooks": [{
              "type": "command",
              "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true"
            }]
          }
        ]
      },
      "env": {
        "NODE_ENV": "development"
      },
      "worktree": {
        "symlinkDirectories": [ "node_modules"]
      }
    }
    

    📋 第九站:CLAUDE.md — 你的專案操作手冊

    為什麼需要 CLAUDE.md?

    settings.json 控制的是 Claude Code 的行為規則,而 CLAUDE.md 定義的是專案上下文。就像你不會讓新進員工第一天就開始寫程式碼一樣——他需要先了解專案的架構、規範、禁忌和慣例。

    CLAUDE.md 放在專案根目錄,Claude Code 每次啟動時會自動讀取,相當於給 AI 一份「新人入職手冊」

    實戰範本

    # 專案:電商平台後端
    
    ## 技術棧
    - Java 17 + Spring Boot 3.2
    - PostgreSQL 15 + Redis 7
    - Maven 建構,模組化架構
    
    ## 程式碼規範
    - 所有 Controller 方法必須有 @Operation 註解(Swagger)
    - Service 層必須有單元測試,覆蓋率 > 80%
    - 使用 Lombok @Slf4j,禁止直接 System.out.println
    
    ## 禁止事項
    - 不要修改 core-common 模組的公開 API
    - 不要直接操作生產資料庫連線字串
    - 不要刪除任何已存在的測試案例
    
    ## 建構與測試
    - 建構:mvn clean package -DskipTests
    - 測試:mvn test
    - 單一模組測試:mvn test -pl module-name
    
    ## 分支策略
    - feature/* 從 develop 分出
    - 每個 PR 需要至少一個 review
    
    💡 架構師觀點:CLAUDE.md 的三層載入機制(~/.claude/CLAUDE.md → 專案根目錄 → 子目錄)就是配置繼承的延伸。你可以在全域設定通用規範,在專案層級設定特定規則,在子目錄中覆蓋模組級別的約定。

    🗺️ 第十站:Plan Mode — 先謀後動

    什麼時候用 Plan Mode?

    當任務複雜到「先想清楚再動手」比「邊做邊改」更高效時,就該用 Plan Mode。典型場景:

    • 跨模組重構
    • 新功能設計(涉及多個服務)
    • 技術遷移(例如從 REST 遷移到 GraphQL)

    實戰操作

    # 進入計畫模式
    # 在聊天中輸入 /plan 或按 Shift+Tab 切換
    
    # 給出需求
    「我需要為現有的訂單系統加入退款功能。
    退款需要:
    1. 支援全額和部分退款
    2. 整合現有的支付閘道(綠界、LINE Pay)
    3. 退款狀態需要即時通知用戶
    4. 需要防止重複退款的並發控制」
    
    # Claude Code 會產出:
    # → 影響範圍分析
    # → 架構設計建議
    # → 分步實施計畫
    # → 每步的驗證標準
    
    💡 架構師觀點:Plan Mode 本質上就是技術設計審查(Design Review)的自動化。它強迫你和 AI 在動手之前達成共識——修改哪些檔案、用什麼模式、怎麼測試。這比「直接開幹然後改三輪」高效得多。

    🤖 第十一站:多代理並行 — 分身術

    核心概念

    Claude Code 可以同時啟動多個子代理(Subagent),每個代理有獨立的上下文,互不干擾。這就像你有一個開發團隊,每人負責不同的任務,最後彙整結果。

    實戰場景

    場景一:並行研究

    # 你問:「比較 Kafka 和 RabbitMQ 在我們這個場景下的優劣」
    # Claude Code 同時啟動:
    # → Agent 1:分析你的程式碼找出訊息傳遞模式
    # → Agent 2:研究 Kafka 的適用性
    # → Agent 3:研究 RabbitMQ 的適用性
    # 三個代理並行執行,最後彙整成完整比較報告
    

    場景二:實作 + 測試並行

    # 你說:「實作用戶通知系統並寫測試」
    # Claude Code 可以:
    # → Agent 1:在 worktree 中實作核心邏輯
    # → Agent 2:同時撰寫測試案例
    # → 主代理:協調兩者,確保介面一致
    

    場景三:Code Review 代理

    # 完成一段實作後
    # → 自動啟動 Code Review 代理
    # → 從安全性、效能、可維護性三個角度審查
    # → 產出具體的修改建議
    
    💡 架構師觀點:多代理系統就是分散式運算的縮影。關鍵是任務分解(Task Decomposition)——把大任務拆成可並行的子任務。能並行的就並行,有依賴的就串行。這和你設計微服務時的思考方式完全一致。

    🧠 第十二站:Memory 記憶系統 — 跨對話的知識累積

    為什麼需要記憶?

    每次開新對話,Claude Code 都是「失憶」狀態。Memory 系統解決了這個問題——它讓 AI 記住你的偏好、專案狀態、過去的決策。

    四種記憶類型

    類型 用途 範例
    user 你的角色和偏好 「用戶是資深 Java 架構師,偏好函數式風格」
    feedback 你給過的修正指導 「不要在測試中 mock 資料庫,要用 Testcontainers」
    project 專案的狀態和決策 「3月底前需要完成支付模組重構」
    reference 外部資源的指引 「Bug 追蹤在 Linear 的 BACKEND 專案中」

    實戰操作

    # 主動要求記住
    「記住:這個專案的 API 回應格式統一用 ApiResponse 包裝,
    不要直接回傳原始物件」
    
    # Claude Code 會自動儲存為 feedback 類型的記憶
    # 下次對話中,它會自動遵守這個規則
    
    # 記住偏好
    「記住:我喜歡用 Stream API 而不是 for 迴圈處理集合」
    
    # 記住專案決策
    「記住:我們決定用 Event Sourcing 模式重構訂單模組,
    預計 Q2 完成」
    
    💡 架構師觀點:Memory 系統就是 AI 的組織知識庫(Knowledge Base)。它解決了「每次都要重複解釋上下文」的問題。越用越聰明,因為它逐漸累積了你的技術偏好、專案脈絡、和過去的決策紀錄。

    💬 第十三站:與 AI 溝通的真相 — 別演了,說人話

    先打破一個幻覺

    很多教學會告訴你:「給 AI 一個角色,例如『你是資深 Java 架構師』,回答會更專業。」

    這是半個事實。

    給角色確實會讓 AI 的回答看起來更專業——更多術語、更自信的語氣、更「完整」的方案。但研究和實際使用經驗都指出:角色設定會讓 AI 的正確率下降。

    為什麼?因為「資深架構師」不會說「我不確定」。所以 AI 會:

    • 硬掰——不確定的事情也斬釘截鐵地說
    • 過度複雜化——簡單問題也要套三層設計模式,顯得「夠資深」
    • 自信地錯——沒角色時會說「可能是 A 或 B」,有角色後直接斷言「就是 A」

    你得到的不是更好的答案,而是更有自信的答案。這兩件事差很遠。


    「但我不知道該給什麼約束啊」

    有人說:「那不要給角色,改給具體約束。」例如把「你是安全專家」改成「用 OWASP Top 10 標準審查程式碼」。

    聽起來很合理,但這有一個致命的前提假設:你得知道 OWASP Top 10 是什麼。

    現實是——如果你已經知道該用什麼約束,你大概也不太需要 AI 了。你使用 AI 的原因之一,正是因為你的知識有邊界。要你在邊界之外給出精確約束,這本身就是矛盾的。

    這是一個雞生蛋的問題:

    • 要給好的約束 → 需要知道有哪些考量面向
    • 要知道有哪些考量面向 → 需要相關經驗
    • 如果你有相關經驗 → 你可能不需要問 AI

    真正有效的溝通方式

    解法一:讓 AI 來問你,而不是你來指揮 AI

    ❌「你是資深架構師,幫我設計退款系統」
    ❌「幫我設計退款系統,約束是 A、B、C」(你怎麼知道該約束什麼?)
    ✅「我需要退款功能。問我你需要知道的事情。」
    

    AI 會反問你:支援哪些支付方式?要不要部分退款?退款時效?併發量多少?——這些約束由 AI 來挖掘,你只需要回答業務事實。你是最了解你的業務的人,AI 是最了解技術選項的那個。各司其職。

    解法二:說痛點,不說方法

    ❌「用 Strategy Pattern 重構支付模組」
    ✅「支付模組每次加新支付方式都要改 5 個檔案,太痛苦了」
    
    ❌「幫我實作 Cache-Aside Pattern」
    ✅「這個 API 太慢了,每次都要查資料庫,有 500ms 延遲」
    
    ❌「用 Event Sourcing 重構訂單模組」
    ✅「訂單狀態變更的歷史記錄查不到,客服常常追不到問題」
    

    你描述痛點,AI 來決定用什麼方法。你不需要知道 Strategy Pattern 這個詞——那是 AI 的工作。

    解法三:給 AI 看失敗的例子

    ✅「上次你改完之後測試壞了三個,這次注意一下」
    ✅「你之前把 API 回傳格式改掉了,不要再這樣」
    ✅「上一版你漏掉了併發情境,這次要考慮進去」
    

    這比任何「資深」角色都有效。你在用真實的失敗經驗告訴 AI 邊界在哪裡。


    最危險的時刻:「看起來差不多了」

    這是人機協作中最容易出事的瞬間

    AI 給你一個方案,看起來完整、專業、邏輯通順。你看了看,覺得「嗯,差不多了」,然後就 GO 了。

    問題是——你覺得差不多了,不是因為真的差不多了,而是因為 AI 的輸出「看起來」差不多了。

    AI 不會主動告訴你它跳過了什麼。它不會說「欸,我其實沒考慮併發情境」或「這個方案在資料量大的時候會爆掉」。它產出的東西永遠看起來是完整的——因為它被訓練成產出看起來完整的回答。

    煞車技巧:一句話打破 AI 的演出模式

    你不需要學任何新技巧。只需要在覺得「差不多了」的時候,多問一句:

    「你跳過了什麼?」
    

    或是這些變體:

    • 「你在這個方案裡做了哪些假設?」
    • 「這個方案最可能在哪裡出事?」
    • 「你有沒有什麼想問我但沒問的?」
    • 「如果這個方案失敗了,最可能的原因是什麼?」
    • 「你對這個方案有多少信心?哪部分最不確定?」

    這一句話的威力在於:你不是在問「做得好不好」,而是在問「藏了什麼」。它逼 AI 從「展示模式」切換到「誠實模式」。


    而且這件事不該只是你的責任

    理想的 AI 協作應該是雙向的。AI 在給出方案後,應該主動說

    「這個方案我假設了 X、Y、Z。
    我沒有處理的是 A 和 B。
    你需要確認的是 C。
    我最不確定的部分是 D。」

    如果你的 AI 不會主動這樣做,你可以在 CLAUDE.md 中加入這個規則:

    # AI 行為規範
    - 每次提出方案後,必須列出:
      1. 你做了哪些假設
      2. 你沒有處理的邊界情境
      3. 你最不確定的部分
      4. 你建議我額外確認的事項
    - 不確定的事情要說不確定,不要硬掰
    - 寧可多問一個問題,也不要做錯一個假設
    

    把這段放進 CLAUDE.md,AI 的行為會顯著改變。這不是「角色扮演」,而是行為契約


    常見的協作陷阱與對策

    陷阱 表現 對策
    自信陷阱 AI 語氣非常肯定,但內容其實有誤 問「你有多少信心?」、「有沒有其他可能?」
    完整性幻覺 方案看起來很完整,但跳過了關鍵場景 問「你跳過了什麼?」、「最可能在哪出事?」
    過度設計 簡單問題給出複雜方案,顯得「專業」 問「有沒有更簡單的做法?」、「最小可行方案是什麼?」
    附和陷阱 你提出一個想法,AI 不管對錯都說「好主意」 問「這個想法有什麼問題?」、「如果你反對,理由是什麼?」
    術語轟炸 一堆專業名詞讓你不敢追問 直接說「用白話解釋」、「舉一個具體例子」
    沉沒成本 AI 已經寫了很多程式碼,你不好意思說不對 程式碼隨時可以重寫,越早喊停成本越低

    一個真實的反思

    這段內容本身就是一個活生生的例子。這篇文章的前半段充滿了「架構師觀點」的包裝——設計模式、架構原則、專業術語。這些不是錯的,但它們的存在更多是因為「架構師觀點」這個角色要求我這樣寫,而不是因為你真的需要知道 Cache-Aside Pattern 叫什麼名字。

    你真正需要的可能只是:「怎麼讓常用的 API 查詢變快」。而「Cache-Aside Pattern」只是其中一個可能的做法。

    好的 AI 協作不是你學會說 AI 的語言,而是 AI 學會聽你的語言。


    🚀 第十四站:Auto Mode — 全自動駕駛

    什麼是 Auto Mode?

    Auto Mode 讓 Claude Code 自行判斷是否需要詢問你權限。它使用一個 AI 分類器來評估每個操作的風險等級——安全的直接執行,有風險的才問你。

    配置方式

    {
      "permissions": {
        "defaultMode": "auto"
      },
      "autoMode": {
        "allow": [
          "讀取和修改 src/ 目錄下的程式碼",
          "執行 mvn test 和 npm test",
          "使用 git 進行版本控制操作"
        ],
        "soft_deny": [
          "不要刪除任何檔案",
          "不要修改 CI/CD 配置",
          "不要 push 到遠端"
        ],
        "environment": [
          "這是本地開發環境",
          "可以自由修改 src/ 和 tests/ 目錄"
        ]
      }
    }
    
    💡 架構師觀點:Auto Mode 就是基於策略的存取控制(Policy-Based Access Control)。你定義高層策略(允許什麼、拒絕什麼、環境是什麼),AI 分類器負責把每個具體操作映射到對應的策略。比逐條列出權限更靈活,但也需要更精確的策略描述。

    🖥️ 第十五站:IDE 整合 — VSCode 中的 Claude Code

    核心優勢

    在 VSCode 中使用 Claude Code,你可以:

    • 選取程式碼直接提問:選中一段程式碼,右鍵問 Claude「這段程式碼在做什麼?」或「怎麼優化?」
    • @ 提及檔案:@filename 直接引用專案中的檔案,不需要複製貼上
    • 即時差異檢視:Claude 的每次編輯都以 diff 形式呈現,一目了然
    • 內嵌終端整合:Bash 指令的輸出直接顯示在對話中

    高效工作流程

    # 1. 選中有問題的程式碼 → 問 Claude
    # 2. Claude 提出修改方案 → 你在 diff 中 review
    # 3. 接受修改 → Claude 自動套用
    # 4. 跑測試 → 確認沒有破壞既有功能
    # 整個流程不離開編輯器
    
    💡 架構師觀點:IDE 整合消除了「上下文切換成本」。你不需要在終端、瀏覽器、編輯器之間來回跳轉。所有的 AI 協作都發生在你最熟悉的工作環境中——這就是開發者體驗(DX)設計的核心理念。

    ⏳ 第十六站:背景代理與上下文管理

    背景代理

    有些任務不需要你盯著看——丟給背景代理,做完通知你:

    # 啟動背景代理做耗時任務
    # Claude Code 會在完成後通知你
    
    # 適合背景執行的任務:
    # → 大範圍的程式碼搜索和分析
    # → 跨模組的相依性分析
    # → 大型重構的前置調查
    # → 文件生成
    

    上下文管理

    長對話中,Claude Code 的上下文窗口會逐漸填滿。掌握上下文管理技巧很重要:

    • /compact:手動壓縮對話上下文,保留關鍵資訊,釋放空間
    • PreCompact Hook:在壓縮前自動保存你想保留的重要資訊
    • 拆分對話:每個獨立任務開新對話,避免上下文污染
    • Memory 持久化:重要的決策和發現存入 Memory,跨對話保留
    {
      "hooks": {
        "PreCompact": [
          {
            "matcher": "manual",
            "hooks": [{
              "type": "command",
              "command": "echo '{"hookSpecificOutput":{"hookEventName": "PreCompact","additionalContext": "壓縮前提醒:保留所有架構決策和 API 介面設計的上下文"}}'"
            }]
          }
        ]
      }
    }
    
    💡 架構師觀點:上下文管理就是記憶體管理。就像 JVM 的垃圾回收一樣,你需要平衡「保留有用資訊」和「釋放空間給新任務」。好的上下文管理策略能讓你在單次對話中完成更複雜的任務。

    🔄 第十七站:TDD 與 Code Review 工作流

    AI 驅動的 TDD 流程

    # Step 1:先寫測試
    「為 RefundService.processRefund() 寫測試案例:
    - 全額退款成功
    - 部分退款成功
    - 超額退款應拋出 IllegalArgumentException
    - 已退款的訂單不能重複退款
    - 並發退款的樂觀鎖衝突處理」
    
    # Step 2:確認測試(此時應全部失敗)
    「跑一下測試,確認都是 RED 狀態」
    
    # Step 3:實作程式碼讓測試通過
    「現在實作 RefundService.processRefund(),讓所有測試通過」
    
    # Step 4:重構
    「測試都通過了。現在重構——有沒有重複程式碼或可以抽象的地方?」
    

    雙代理 Code Review

    # 完成實作後,啟動 Code Review 流程
    
    # 方式一:使用 /review 技能
    # Claude Code 會從多個角度審查你的程式碼變更
    
    # 方式二:手動指定審查角度
    「以 Senior Java Developer 的身份審查這次的 git diff:
    1. 是否符合 SOLID 原則?
    2. 異常處理是否完整?
    3. 是否有潛在的效能問題?
    4. API 設計是否符合 RESTful 規範?
    5. 測試覆蓋是否足夠?」
    
    💡 架構師觀點:TDD + AI Code Review 構成了一個持續品質迴圈。AI 寫測試確保功能正確,AI 審查確保品質達標。你的角色從「寫程式碼」轉變為「定義品質標準」和「做最終判斷」。

    📊 協作能力總覽:你能用 Claude Code 做什麼

    階段 能力 核心配置/工具 效率提升
    環境設定 跳過權限提示 permissions.allow 消除 80% 的中斷
    環境設定 自動化護欄 Hooks 零人工品質檢查
    環境設定 外部服務整合 MCP Servers 統一操作介面
    需求階段 腦力激盪 Skills: brainstorming 結構化需求探索
    設計階段 計畫模式 Plan Mode 先謀後動,減少返工
    設計階段 專案上下文 CLAUDE.md AI 自動遵守規範
    開發階段 TDD 工作流 Skills: TDD 測試先行,品質保證
    開發階段 多代理並行 Subagents 任務並行,加速 N 倍
    開發階段 背景代理 Background agents 非阻塞式工作
    開發階段 隔離環境 Git Worktree 互不干擾的並行開發
    審查階段 Code Review Skills: code-review 多角度自動審查
    部署階段 全自動模式 Auto Mode AI 自主判斷,減少打擾
    跨對話 記憶系統 Memory 知識累積,越用越聰明
    跨對話 上下文管理 /compact + Hooks 更長的有效工作時間
    日常 IDE 整合 VSCode Extension 零上下文切換
    日常 SSH 遠端 sshConfigs 隨處開發

    🎯 結語:從工具到戰友,但要是誠實的戰友

    這篇文章從 settings.json 的基礎配置出發,一路展開到 Claude Code 的完整協作生態。17 個核心能力站點分為三層:

    • 基礎設施層(第 1-8 站):權限、Hooks、MCP、Sandbox、Worktree、環境變數、SSH、Plugins——你的「硬體配置」
    • 工作流程層(第 9-13 站):CLAUDE.md、Plan Mode、多代理、Memory、溝通技巧——你的「操作系統」
    • 自動化層(第 14-17 站):Auto Mode、IDE 整合、背景代理、TDD/Code Review——你的「自動駕駛」

    但如果你只記住一件事,請記住這個:

    AI 最危險的時候不是它出錯的時候——是它看起來沒出錯的時候。

    所有的配置、Hooks、自動化,都是為了讓協作更高效。但高效的前提是正確。而正確的前提是你敢對 AI 的輸出踩煞車,問它:「你跳過了什麼?」

    不要追求「完美的 Prompt」。不要花時間研究該給 AI 什麼角色。把那些時間拿來:

    1. 描述你的痛點(而不是指定解法)
    2. 讓 AI 問你問題(而不是你猜它需要什麼)
    3. 在「看起來差不多」的時候多問一句(而不是直接 GO)
    4. 把失敗經驗告訴它(而不是只給它成功案例)

    好的人機協作不是人學會說機器的語言,而是建立一個雙方都誠實的溝通環境。

    你配置 Claude Code 的方式,反映的不只是技術能力——更是你對「什麼是好的協作」的理解。

    本文基於 Claude Code 2026 年 3 月版本撰寫,並包含真實的人機協作反思。所有配置範例均經過實戰驗證。

  • 【深度解析】2026 Agentic Coding Trends Report — 資深架構師的全面剖析與實戰指南

    Anthropic 於 2026 年初發布了《2026 Agentic Coding Trends Report》,提出了 8 大趨勢預測。作為一名在企業級系統架構領域深耕多年的架構師,我將逐一拆解每個趨勢,結合實際的代理操作經驗,為你呈現這份報告背後的深層意涵。


    🏗️ 基礎趨勢:地殼級的轉變

    趨勢 1:軟體開發生命週期(SDLC)將劇烈改變

    架構師視角

    這不只是「AI 幫你寫 code」這麼簡單。報告指出,從機器碼到組合語言、從 C 到現代高階語言,每一層抽象都在縮短人類思維與機器執行之間的距離。而 Agentic AI 是這條演化路線上最新的一步——人機對話式程式開發

    作為架構師,我看到的核心轉變是:工程師的角色從「實作者」變成「指揮者」。這就像軍隊中從士兵升為指揮官——你不再親自衝鋒陷陣,而是制定戰略、分配資源、審查成果。

    報告特別提到一個關鍵數據:工程師約 60% 的工作使用 AI,但只有 0-20% 能完全委派。這說明了一個事實——AI 是協作者,不是替代者。你仍然需要深厚的工程知識來判斷 AI 產出的品質。

    實戰操作:如何用 Coding Agent 重塑你的 SDLC

    場景一:快速上手陌生程式碼庫

    報告指出新人上手時間將從數週壓縮到數小時。以下是實際操作方式:

    # 使用 Claude Code 探索陌生程式碼庫
    # 步驟 1:讓代理理解整體架構
    $ claude "分析這個專案的整體架構,包括主要模組、依賴關係、資料流向"
    
    # 步驟 2:針對特定模組深入了解
    $ claude "解釋 src/auth/ 目錄下的認證機制,包括 token 生命週期和刷新策略"
    
    # 步驟 3:理解業務邏輯
    $ claude "追蹤一個訂單從建立到完成的完整流程,列出涉及的所有服務和資料表"
    

    場景二:架構決策輔助

    # 讓代理幫你評估架構方案
    $ claude "我們正在考慮將單體應用拆分為微服務。
    分析目前的程式碼耦合度,識別可以獨立拆分的邊界上下文(Bounded Context),
    並評估每個拆分方案的風險和收益"
    
    # 代理會:
    # 1. 掃描所有模組間的依賴關係
    # 2. 識別高耦合和低耦合的邊界
    # 3. 提出具體的拆分建議和遷移路徑
    

    架構師建議:建立一份「AI 委派矩陣」——明確定義哪些任務適合完全委派、哪些需要協作完成、哪些必須人工處理。例如:

    • 完全委派:單元測試撰寫、程式碼格式化、簡單 CRUD API、文件生成
    • 協作完成:複雜業務邏輯、效能優化、資料庫 schema 設計
    • 人工主導:架構決策、安全審計、合規性審查、系統設計

    ⚡ 能力趨勢:代理能做什麼

    趨勢 2:單一代理演化為協調團隊

    架構師視角

    這是我認為最具顛覆性的趨勢。報告中提到 Fountain 公司透過階層式多代理協調(Hierarchical Multi-Agent Orchestration)實現了 50% 更快的篩選速度和 2 倍的候選人轉化率。

    從架構角度來看,Multi-Agent 系統本質上就是分散式系統設計——這正是我們架構師的核心能力。想像一下:每個 Agent 就是一個微服務,擁有獨立的 context window(類似獨立的記憶體空間),透過 Orchestrator(類似 API Gateway 或 Message Broker)進行協調。

    關鍵的架構模式有三種:

    1. Orchestrator Pattern(編排模式):一個中央代理分配任務、收集結果
    2. Pipeline Pattern(管線模式):代理們串聯處理,每個處理完交給下一個
    3. Swarm Pattern(群體模式):多個代理平行處理,最後彙整結果

    實戰操作:建構多代理工作流

    場景:用多代理系統進行完整的 Feature 開發

    # 使用 Claude Code 的 subagent 機制
    # 主代理(Orchestrator)接收需求後,分派給專業子代理
    
    # Agent 1: 架構分析代理
    $ claude "作為架構分析代理,分析「新增用戶通知系統」這個需求,
    識別需要修改的模組、新增的介面、以及對現有系統的影響"
    
    # Agent 2: 測試代理 — 平行撰寫測試
    $ claude "作為測試代理,為用戶通知系統撰寫完整的測試案例,
    包括單元測試、整合測試、邊界條件測試"
    
    # Agent 3: 實作代理 — 根據架構分析進行開發
    $ claude "根據以下架構分析結果,實作用戶通知系統的核心模組..."
    
    # Agent 4: 安全審查代理
    $ claude "審查以下程式碼的安全性,檢查 OWASP Top 10 漏洞,
    特別關注輸入驗證、SQL Injection、XSS 防護"
    

    進階:使用 Claude Agent SDK 建構自動化多代理系統

    # 使用 Claude Agent SDK 建構 Multi-Agent Pipeline
    from claude_agent_sdk import Agent, Orchestrator
    
    # 定義專業代理
    architect_agent = Agent(
        role="architect",
        system_prompt="你是資深架構師,負責分析需求並產出技術設計文件",
        tools=["file_read", "codebase_search"]
    )
    
    test_agent = Agent(
        role="tester",
        system_prompt="你是測試工程師,負責撰寫全面的測試案例",
        tools=["file_write", "test_runner"]
    )
    
    impl_agent = Agent(
        role="implementer",
        system_prompt="你是實作工程師,根據設計文件和測試案例進行開發",
        tools=["file_write", "file_edit", "bash"]
    )
    
    reviewer_agent = Agent(
        role="reviewer",
        system_prompt="你是 Code Reviewer,負責品質和安全審查",
        tools=["file_read", "security_scanner"]
    )
    
    # 建構協調器
    orchestrator = Orchestrator(
        agents=[architect_agent, test_agent, impl_agent, reviewer_agent],
        workflow="sequential",  # 或 "parallel", "hierarchical"
        checkpoints=["after_design", "after_tests", "after_implementation"]
    )
    
    # 執行
    result = orchestrator.run("實作用戶通知系統,支援 Email、SMS、Push 三種管道")
    

    架構師建議:不要一開始就追求複雜的多代理架構。先從兩個代理開始——一個負責實作,一個負責審查——建立基本的「雙人檢查」機制,再逐步擴展。


    趨勢 3:長時間運行的代理建構完整系統

    架構師視角

    報告中的 Rakuten 案例極具說服力:Claude Code 在 7 小時內自主完成了在一個 1,250 萬行程式碼庫中的複雜實作,達到 99.9% 的數值精確度。

    從架構角度來看,長時間運行的代理本質上需要解決三個核心問題:

    1. 狀態管理(State Management):代理如何在長時間任務中維持一致的上下文?
    2. 錯誤恢復(Error Recovery):當代理遇到錯誤時,如何回退並嘗試替代方案?
    3. 檢查點(Checkpointing):如何設置人工介入點,確保代理沒有偏離方向?

    這些問題與我們設計分散式系統時面臨的挑戰如出一轍。Saga Pattern、Circuit Breaker、Retry with Backoff——這些架構模式都可以類比到代理系統的設計中。

    實戰操作:設置長時間運行的代理任務

    # 場景:讓代理自主重構整個模組
    
    # 步驟 1:提供清晰的目標和邊界
    $ claude "重構 src/legacy/payment/ 模組:
    目標:將回調式(callback)程式碼遷移到 async/await 模式
    邊界:
    - 不要修改公開 API 介面
    - 保持所有現有測試通過
    - 每完成一個檔案就執行測試套件
    - 如果測試失敗,回退該檔案的變更並報告問題
    檢查點:每處理 5 個檔案暫停,等待我的確認"
    
    # 步驟 2:利用 CLAUDE.md 提供長期上下文
    # 在專案根目錄建立 CLAUDE.md,讓代理記住專案規範
    
    # 步驟 3:使用 Git Worktree 隔離工作
    $ git worktree add ../payment-refactor feature/payment-async
    $ cd ../payment-refactor
    $ claude "開始重構工作..."
    

    架構師建議:為長時間代理任務設計「護欄(Guardrails)」——明確定義代理不能做的事情比定義它應該做什麼更重要。這就像 Kubernetes 的 Resource Limits 一樣,防止代理失控。


    趨勢 4:人類監督透過智慧協作擴展

    架構師視角

    報告揭示了一個「協作悖論」:工程師 60% 的工作使用 AI,但只有極小比例能完全委派。這不是 AI 能力不足,而是信任需要逐步建立

    從系統設計角度,這就是漸進式信任模型(Progressive Trust Model)

    • Level 0 – 監控模式:代理執行,人類逐行審查(適合初期導入)
    • Level 1 – 抽查模式:代理執行,人類抽樣審查(適合建立信任後)
    • Level 2 – 異常模式:代理執行 + 自我審查,只有異常才通知人類
    • Level 3 – 自主模式:代理全自主執行,人類只在策略層介入

    實戰操作:建立智慧監督機制

    # 利用 Claude Code 的 Hooks 機制建立自動化審查
    
    # 在 .claude/settings.json 中設定 hooks
    {
      "hooks": {
        "PostToolUse": [
          {
            "matcher": "Edit|Write",
            "command": "npm run lint --fix && npm test -- --bail"
          }
        ],
        "PostCommit": [
          {
            "command": "npm run security-audit"
          }
        ]
      }
    }
    
    # 這樣每次代理修改程式碼,都會自動:
    # 1. 執行 lint 檢查
    # 2. 執行測試
    # 3. 提交時執行安全掃描
    # 形成自動化的品質護欄
    

    場景:使用代理審查代理的產出

    # Agent A: 實作功能
    $ claude "實作用戶匯出功能,支援 CSV 和 Excel 格式"
    
    # Agent B: 審查 Agent A 的產出(獨立 context,避免偏見)
    $ claude "請審查以下程式碼變更(git diff),從以下角度:
    1. 安全性:是否有 injection 風險?大檔案是否會 OOM?
    2. 效能:匯出 100 萬筆資料時的記憶體和時間複雜度?
    3. 可維護性:是否符合專案既有的設計模式?
    4. 邊界條件:空資料、特殊字元、併發匯出等情況?"
    

    架構師建議:建立「代理信任儀表板」——追蹤代理產出的品質指標(測試通過率、Code Review 修改率、Bug 回報率),用數據驅動你的信任等級調整。


    趨勢 5:代理編程擴展到新領域和新用戶

    架構師視角

    報告指出 AI 正在打破「寫程式的人」和「不寫程式的人」之間的界線。這對架構師來說意味著一個巨大的設計挑戰:如何設計系統讓非技術人員也能安全地進行自動化

    想像一下你的法務團隊用 AI 建立了合約審查自動化、行銷團隊建立了 A/B 測試分析管線、HR 建立了招聘數據儀表板——這些都直接連接到你的核心系統。沒有良好的架構,這就是一場災難。

    實戰操作:為非技術團隊建立安全的代理環境

    # 場景:讓數據分析師用代理進行資料分析
    
    # 方式 1:提供受限的 Claude Code 環境
    # 建立專用的 CLAUDE.md 限制代理行為
    # 允許:讀取 /data/ 目錄、執行 Python 腳本、產生圖表
    # 禁止:修改任何程式碼、存取生產資料庫、安裝新套件
    
    # 方式 2:使用 MCP (Model Context Protocol) 提供安全的 API 存取
    {
      "mcpServers": {
        "company-data": {
          "command": "node",
          "args": ["mcp-server/data-access.js"],
          "env": {
            "DB_ROLE": "readonly",
            "MAX_ROWS": "10000"
          }
        }
      }
    }
    

    架構師建議:為每個非技術團隊的代理使用場景設計「沙盒(Sandbox)」。就像你不會給實習生 production 的 root 權限一樣,非技術人員的代理也需要明確的權限邊界。使用 Least Privilege 原則,只給代理完成任務所需的最小權限。


    📊 影響趨勢:代理將改變什麼

    趨勢 6:生產力提升重塑軟體開發經濟

    架構師視角

    報告中最引人注目的數據是:約 27% 的 AI 輔助工作是「原本不會做的事」。這不只是效率提升,而是價值創造

    從架構師角度,我把這稱為「技術債務清算窗口」。過去那些因為「沒時間」而累積的技術債——老舊的 API 版本、缺失的測試、過時的文件、效能瓶頸——現在都可以系統性地被代理消滅。

    報告提到三個乘數效應(Three Multipliers):代理能力提升 × 協調改進 × 人類經驗 = 指數級加速。這不是線性增長,而是複合增長。就像 DevOps 革命一樣,三者相互增強。

    實戰操作:系統性消滅技術債

    # 場景:用代理批量處理技術債
    
    # 步驟 1:讓代理掃描並分類技術債
    $ claude "掃描整個程式碼庫,識別以下類型的技術債:
    1. 已廢棄的 API 調用(deprecated warnings)
    2. 缺少測試覆蓋的關鍵路徑
    3. 硬編碼的配置值
    4. 重複的程式碼(DRY 違反)
    5. 不一致的錯誤處理模式
    按嚴重程度和修復成本排序,產出優先級清單"
    
    # 步驟 2:逐項自動修復
    $ claude "根據優先級清單,從最高優先級開始:
    - 每修復一項,執行完整測試套件
    - 每項修復獨立一個 commit
    - 如果修復可能影響其他模組,標記為需要人工審查"
    

    架構師建議:建立「20% 代理時間」制度——每個 Sprint 撥出 20% 的代理運算資源專門處理技術債。用代理來做那些人類「知道該做但沒時間做」的事。


    趨勢 7:非技術用例擴展至全組織

    架構師視角

    報告中 Anthropic 自家法務團隊的案例最具說服力:一位沒有程式碼經驗的律師用 Claude Code 建立了自助服務工具,將行銷審查周轉時間從 2-3 天縮短到 24 小時。

    Zapier 更是達到了 89% 的全組織 AI 採用率,部署了 800+ 個內部 AI 代理。

    作為架構師,這意味著你需要開始思考「代理治理(Agent Governance)」:誰可以建立代理?代理可以存取哪些系統?如何追蹤和審計代理的行為?代理出錯時的責任歸屬?

    實戰操作:建構組織級代理平台

    # 架構建議:建立內部的 Agent Platform
    
    # 1. 定義代理模板(Agent Templates)
    # marketing-agent-template.yaml
    name: marketing-automation-agent
    permissions:
      read: [marketing-data, analytics-api]
      write: [marketing-reports, draft-content]
      execute: [data-analysis-scripts]
      forbidden: [production-db, source-code, deployment]
    resource_limits:
      max_tokens_per_day: 1000000
      max_api_calls: 500
    audit:
      log_all_actions: true
      alert_on: [data-access, external-api-call]
    
    # 2. 建立自助服務入口
    # 非技術人員透過 Web UI 與代理互動
    # 所有操作都在沙盒環境中執行
    
    # 3. 監控儀表板
    # 追蹤全組織的代理使用情況:
    # - 各部門使用量和成本
    # - 代理產出的品質指標
    # - ROI 分析(節省的人力時間 vs 代理成本)
    

    架構師建議:把「代理治理」視為與「資料治理」同等重要的架構議題。建立 Agent Center of Excellence (ACoE),制定組織級的代理使用政策、安全標準和最佳實踐。


    趨勢 8:雙重用途風險需要安全優先架構

    架構師視角

    這是最被低估但最重要的趨勢。報告指出:同樣的 AI 能力既能強化防禦,也能助長攻擊

    從架構角度,這意味著安全不再是事後補救,而必須是設計時的第一考量(Security by Design)。當任何工程師都能用 AI 進行深度安全審查時,攻擊者也能用同樣的 AI 尋找漏洞。

    關鍵的架構原則:

    • Zero Trust Architecture:不信任任何內部或外部的代理輸出
    • Defense in Depth:多層防禦,即使一層被突破仍有保護
    • Shift Left Security:在開發早期就嵌入安全檢查

    實戰操作:用代理建立安全防線

    # 場景 1:自動化安全審查管線
    # 在 CI/CD Pipeline 中嵌入 AI 安全審查
    name: AI Security Review
    on: [pull_request]
    jobs:
      security-review:
        steps:
          - name: AI Security Scan
            run: |
              claude "審查這個 PR 的所有變更:
              1. OWASP Top 10 漏洞掃描
              2. 硬編碼的密鑰或憑證
              3. SQL/NoSQL Injection 風險
              4. XSS 和 CSRF 防護
              5. 權限提升風險
              6. 敏感資料洩漏
              以 SARIF 格式輸出結果"
    
    # 場景 2:用代理進行威脅建模
    $ claude "對以下系統架構進行威脅建模(STRIDE 方法):
    - 前端:React SPA
    - API Gateway:Kong
    - 後端:Spring Boot 微服務群
    - 資料庫:PostgreSQL + Redis
    - 訊息佇列:Kafka
    - 部署:Kubernetes on AWS"
    
    # 場景 3:AI 紅藍對抗
    # 用一個代理扮演攻擊者(Red Team)尋找漏洞
    # 另一個代理扮演防禦者(Blue Team)修補漏洞
    

    架構師建議:建立「AI 紅藍對抗」機制——用一個代理扮演攻擊者尋找漏洞,另一個代理扮演防禦者修補漏洞。這種持續的對抗演練能顯著提升系統安全性。


    🎯 我的行動建議:2026 年架構師優先事項

    綜合以上 8 大趨勢,我給出以下具體的行動清單:

    立即行動(本月)

    1. 建立 CLAUDE.md:為每個專案建立代理上下文文件,定義程式碼規範、禁止事項、測試要求
    2. 設定 Hooks:配置自動化品質護欄,確保代理每次修改都通過基本檢查
    3. 導入雙代理審查:一個代理寫程式碼,另一個代理審查,建立基本的品質保障

    短期規劃(本季)

    1. 建立 AI 委派矩陣:明確定義團隊中哪些任務適合委派給代理
    2. 啟動技術債清理專案:利用代理系統性處理積壓的技術債
    3. 設計代理安全框架:定義代理的權限邊界、審計機制、異常處理

    中期布局(今年)

    1. 建構多代理協調系統:根據團隊需求設計 Orchestrator 架構
    2. 推動非技術團隊採用:為業務團隊建立安全的代理沙盒環境
    3. 建立 Agent Governance 體系:制定組織級的代理使用政策和治理框架

    結語

    這份報告的核心訊息很清楚:2026 年的軟體開發正在從「寫程式碼」轉向「指揮寫程式碼的代理」。但這不是要取代工程師——恰恰相反,它要求工程師具備更高層次的思考能力:架構設計、系統思維、品質判斷、安全意識。

    作為架構師,我們正處於一個前所未有的機遇期。那些能夠設計良好的代理協作架構、建立有效的人機協作模式、並在組織層面推動代理治理的架構師,將成為這場變革的引領者。

    最後的忠告:不要等到完美才開始。今天就打開 Claude Code,給它一個你一直拖著沒做的重構任務,開始建立你的代理協作經驗。實踐出真知。

    本文基於 Anthropic《2026 Agentic Coding Trends Report》撰寫。報告原文共 18 頁,涵蓋基礎趨勢、能力趨勢、影響趨勢三大類別共 8 個趨勢預測。