從寫程式機器進化為 AI 代理架構師：帶領專業代理團隊的三大原則

2025 年初，Alphabet 執行長 Sundar Pichai 證實，在 Google，超過 30% 的新程式碼已經由 Gemini 模型輔助或生成；同年四月，微軟執行長 Satya Nadella 也公布了相近的數據。開發速度因此被根本性地改變，也連帶改變了我們對開發者角色的認知。

本文的核心主題是 Coding Agent（程式碼開發代理）。這個主題揭示了一件事：開發者的角色正在發生本質上的改變。這不再是「AI 到底能不能寫程式碼」的舊問題——那早已獲得證實。真正的問題是，廣大的開發者要如何從單打獨鬥的寫程式機器，進化成領導專業 AI 代理團隊的架構師。

過去幾年，業界把大型語言模型當作通用工具反覆測試，累積了大量實作經驗。一套系統化的框架由此成形：主張把 AI 開發流程結構化，成為一種可重複、可審計的工程實踐。

從 Vibe Coding 出發，但不能止步於此

近年最流行的詞彙之一是 Vibe Coding。它指的是我們面對空白頁時，用口語甚至模糊的提示詞，讓大型語言模型直接生成草稿或原型。它的優點很明顯：不需要事先把規格寫死，適合激發靈感、探索不熟悉的 API、測試新穎的架構模式。

這種作法無法擴充套件到生產環境。它的致命傷在於缺乏可預測性與狀態管理。在原型階段，我們不需要考慮每一行程式碼是否與既有系統相容；但在企業級軟體中，每一行程式碼都必須具備健壯性、可擴充套件性，並通過嚴格的安全審查。把 Vibe Coding 產生的程式碼直接塞進現有系統，往往引發連鎖反應，累積大量技術債。

因此，我們需要把即興產出轉變成有組織的委派。Vibe Coding 的問題不在於生成速度快，而在於產出無法被組織性地驗收。要駕馭 AI 的生成速度，必須建立一套有明確角色分工、有驗收機制的流程。這就帶出三大基本原則的第一個。

第一個原則：以人為主導的編排

以人為主導的編排（Human-led Orchestration）：人類的角色不但沒有被削弱，反而被提升。在此框架下，AI 代理是力量倍增器（force multiplier），而非自主的決策者。我們是團隊的領導者與最終決策者，必須負責定義系統的高階架構、業務邏輯的邊界，以及最重要的——設定驗收標準。

我們不是在旁邊看 AI 執行，而是在設計一個協作環境：

       人類開發者（協調者、最終仲裁者）
       ┌─────────────────────────────┐
       │  定義高階架構與驗收標準         │
       │  準備任務簡報、委派、驗收      │
       └─────────────┬───────────────┘
                     │ 委派
        ┌────────────┴────────────┐
        ▼                         ▼
   鷹架代理 → 測試工程師 →     人類審查
   記錄代理 → 優化器 → 流程代理 → 最終判斷
               （戰術執行）      （戰略決策）

// 以人為主導的編排：人類定義目標與驗收，代理負責執行
interface Brief {
  goal: string
  requirements: string[]
  acceptanceCriteria: string[]
}

interface AgentOutput { agent: string; result: string; issues: string[] }

// 人類是協調者：準備簡報 → 委派 → 驗收 → 決定是否重做
async function orchestrate(brief: Brief, pipeline: AgentPipeline): Promise<void> {
  for (const agent of pipeline.agents) {
    const output = await agent.run(brief)        // 代理執行戰術任務
    const accepted = await humanReview(output)   // 人類執行最終判斷
    if (!accepted) {
      const feedback = await humanFeedback(output) // 給回饋，重跑
      await agent.run({ ...brief, feedback })
    }
  }
}

第二個原則：上下文的首要性

現在大家很流行 RAG（檢索增強生成）——讓 AI 透過向量運算，自動在整個程式碼庫中檢索與任務相關的片段。但這套框架明確指出：要極力避免這種自動化的黑盒子。

為什麼不讓 AI 自動找資料，不是讓開發者更輕鬆嗎？RAG 的機制是基於語義相似度抓取資料，在回答一般知識問題（例如問答機器人）時確實有效；但在寫程式碼時，這是一個陷阱。RAG 抓出的程式碼片段，在關鍵字上看起來也許相似，但它完全缺乏這次任務的意圖。背景不佳的大型語言模型其實毫無用處；更糟的是，如果抓進大量不相關的依賴模組，模型的注意力機制會被這些雜訊淹沒，接著產生幻覺，寫出彼此矛盾的程式碼。

因此，這套框架提出一個關鍵觀點：與其給 AI 看全世界，不如嚴格限制它的視野，只給它看最關鍵的資訊。這是減法，而不是加法。具體作法是在專案中建立一個專屬的上下文暫存區域（context staging area）：

task-context/
├── 01_BRIEF.md      ← 任務簡報：完整的需求、API 定義、業務限制
└── 02_CODE/         ← 與本次任務直接相關的程式碼檔案

這份 01_BRIEF.md 簡報是成敗的關鍵，不能只寫「幫我做一個登入功能」這種模糊指示。它需要包含完整的程式碼庫規範、外部 API 檔案、詳細的業務限制、希望避免的特定寫法，以及明確的人類指示。這就像把任務交接給一位剛到職的資深工程師——我們不會只給他整個 repository 的權限，叫他自己摸索，而是整理一份乾淨、無雜訊的交接檔案。前期看似增加工作量，實際上消除了後期反覆除錯的時間成本。

要精確控制「這次任務要餵給模型哪些檔案」，推薦使用一個本機上下文編排器：在專案根目錄放一個輕量級設定檔 context.toml，用它指定要編譯進提示詞負載的檔案、目錄，甚至 URL：

# context.toml：精確控制每次請求要餵給模型哪些內容
[include]
files = ["docs/API.md", "src/types.ts", "tests/auth.spec.ts"]
dirs  = ["src/services"]

[exclude]
patterns = ["*.lock", "node_modules/**"]

// 本機上下文編排器：依 context.toml 組裝成單一、可審計的提示詞負載
import { readFileSync } from 'node:fs'

interface ContextConfig {
  include: { files: string[]; dirs: string[] }
  exclude: { patterns: string[] }
}

function buildPayload(config: ContextConfig, brief: string): string {
  const chunks: string[] = [brief]
  for (const file of config.include.files) {
    chunks.push(`### ${file}\n${readFileSync(file, 'utf8')}`)
  }
  return chunks.join('\n\n') // 單一、可審計的 prompt 負載
}

這份設定檔就像我們的儀表板，一目了然。關於 RAG 與檢索的完整脈絡，可參考這裡-RAG：讓 AI 從閉卷考變開卷考——本文的重點，恰恰是說明程式碼開發場景為何要避開自動檢索的黑盒子。

第三個原則：直接模型存取

有了完善的上下文簡報，接下來要把它交給「正確的人」。但把簡報丟給單一模型就結束了？不是。把所有任務塞進單一提示詞，會瞬間塞爆模型的上下文視窗，而且任務目標必然互相衝突。

第三個原則是直接模型存取（Direct Model Access）：讓代理直接接觸最前沿的模型，建議準備雙模型存取——至少兩個領先模型的 API 金鑰（例如 Gemini 2.5 Pro 與 Claude Opus 4，也可納入 OpenAI、DeepSeek 等）。理由有二：

1. 很多中間平台或外掛雖然方便，但往往會在底層截斷上下文，或包一層自己的指令——在高度精密的多人代理編排時，這會導致管線崩潰。
2. 準備兩組金鑰，也能避免單一平台當機或使用限制，同時方便做比較分析。

代理團隊：從骨架到審查的管線

我們需要建立一條代理管線（agent pipeline），透過特定的角色提示詞，召喚出不同的虛擬專家。這支 AI 代理團隊由五個角色組成：

// 用特定角色提示詞召喚不同的專家代理
const expertAgents = {
  scaffolder:   '您是高級軟體工程師，請依 01_BRIEF.md 的需求與 02_CODE/ 的既有模式實作功能',
  testEngineer: '您是品質保證工程師，請針對 02_CODE/ 提供的程式碼，用 pytest 撰寫涵蓋所有邊緣情況、遵守專案測試理念的測試',
  documenter:   '您是技術作家，請為 API 端點產生含請求/回應範例並解釋每個參數的 markdown 文件',
  optimizer:    '請分析程式碼，找出效能瓶頸並提出可讀性重構建議',
  processAgent: '您是首席工程師。先對變更進行詳細批評，再反思自己的批評，提供優先排序的摘要',
} as const

來源附有這五個代理的實際呼叫範例截圖，可參考這裡-程式設計專家範例——它展示了每個角色在真實介面中被召喚時的樣子。

鷹架代理的核心機制非常純粹——只讀取 01_BRIEF.md，專注產出新程式碼的結構或樣板，不負責檢查效能，也不負責寫測試，是一個極致的實作引擎。鷹架代理產出程式碼之後，編排指令就會啟動測試工程師，切換視角扮演嚴苛的 QA，寫出涵蓋所有邊緣情況的單元測試。接著記錄代理自動為 API 端點生成文件，優化器負責找效能瓶頸與重構建議。

流程代理是整個框架中最關鍵的設計之一，它擁有一個雙步機制（critique → reflect）。過去我們用靜態分析工具或早期的 AI 審查，最大的痛點是雜訊過載——列出幾十個微不足道的風格問題或變數命名建議，人類開發者瞬間被淹沒。流程代理把審查切成兩個獨立階段，而且故意讓第一階段極度嚴苛：

   程式碼差異（git diff）
            │
            ▼
   ┌───────────────────┐
   │ ① critique 批評     │ ← 像傳統工具，用極度嚴苛的視角
   │   找出所有問題        │    產出一份批評清單
   └──────────┬────────┘
              ▼
   ┌───────────────────┐
   │ ② reflect 反思      │ ← 檢視剛剛的清單
   │   駁回吹毛求疵的建議  │    只保留會導致崩潰或嚴重
   │   重新排出優先序      │    技術債的核心問題
   └──────────┬────────┘
              ▼
    優先排序過的可執行摘要 → 交給人類

// 流程代理的雙步機制：先批評，再反思自己的批評
interface Critique { issue: string; severity: 'critical' | 'minor' | 'nitpick'; impact: string }

function processAgentReview(diff: string): { summary: string; prioritized: Critique[] } {
  // 第一步：critique——像靜態分析工具，列出所有問題
  const rawCritique = critique(diff)

  // 第二步：reflect——反思自己的批評，駁回迂腐、低影響的建議
  const refined = rawCritique.filter((c) => c.severity !== 'nitpick')

  // 只保留核心問題，輸出高層次、可操作的優先摘要
  return { summary: summarize(refined), prioritized: sortByImpact(refined) }
}

這就像一位不僅會挑毛病、還懂得看場合挑重點講的資深工程師同事——完全釋放了人類的認知頻寬，可說是理想的程式碼審查員。雙步機制的「反思」本質，與推理技巧中的自我修正一脈相承，可參考這裡-讓 AI 代理學會深思熟慮：推理技巧。

實戰清單：在本地重現整套架構

要在自己的機器上重現整套架構，需要一份落地清單：

1. 準備雙模型 API 金鑰。 至少要能直接存取兩個領先模型的 API，並像管理其他生產機密一樣安全管理憑證。

2. 實作本機上下文編排器。 用輕量級 CLI 工具管理上下文，而非臨時腳本；在專案根目錄用 context.toml 指定要編譯進提示詞的檔案，對模型每次看到的內容保持完全透明的控制。

3. 建立版本控制的提示庫。 在專案的 Git 儲存庫建立專用的 /prompts 目錄，把每個專家代理的呼叫提示詞（如 reviewer.md、documenter.md、tester.md）存成 Markdown 檔案。把提示詞視為程式碼的一部分，跟團隊一起協作、完善、版本化。當我們發現流程代理漏抓了漏洞，就去修改提示詞——這本身就是一種 CI/CD 思維。

project-root/
├── context.toml        ← 上下文編排設定
├── task-context/
│   ├── 01_BRIEF.md
│   └── 02_CODE/
└── prompts/            ← 版本控制的提示庫
    ├── scaffolder.md
    ├── tester.md
    ├── documenter.md
    ├── optimizer.md
    └── process-agent.md

4. 整合 Git Hooks。 設定一個 pre-commit hook，在終端機執行 git commit 的瞬間，自動喚醒流程代理讀取暫存的程式碼差異進行審查，直接在終端機給出回饋——程式碼連推送都還沒發生，我們就已經被審查糾正了：

$ git commit -m "feat: 新增登入流程"

  🔍 流程代理審查（3 秒）……
  ✋ 發現 1 項 CRITICAL：auth/token.ts:41 未驗證 JWT 過期
  commit 已中止

// .git/hooks/pre-commit：commit 前喚醒流程代理
import { execSync } from 'node:child_process'

function stagedDiff(): string {
  return execSync('git diff --cached --stat').toString() // 讀取暫存的變更
}

const review = await processAgentReview(stagedDiff())
if (review.prioritized.some((c) => c.severity === 'critical')) {
  console.error(review.summary)   // 直接在中斷機給回饋
  process.exit(1)                 // 阻擋 commit
}

領導增強的代理團隊的四個原則

組建團隊只是起點。來源特別強調，領導者還需要遵守四個原則，與前述三大原則相輔相成：

1. 維護架構所有權。 我們的角色是設定策略方向並擁有高階架構：定義「做什麼（what）」與「為什麼（why）」，讓代理團隊加速「怎麼做（how）」。我們是設計的最終仲裁者，確保每個元件都符合專案的長期願景與品質標準。

2. 掌握摘要的藝術。 代理輸出的品質直接反映其輸入的品質。與其把提示當作簡單指令，不如為每項任務提供清晰、明確、全面的簡報包——把代理當作剛到職、能力很強的團隊成員。

3. 充當終極品質閘。 代理的輸出永遠是建議，不是命令。即使是流程代理的審查回饋，也只是強力訊號；我們要套用領域專業知識與專案特定知識去驗證、質疑、核准所有變更，成為程式碼庫完整性的最終守護者。

4. 參與迭代對話。 最好的結果來自對話而非獨白。如果代理第一次的輸出不完美，不要丟棄，而是提供糾正回饋、補充脈絡，再提示一次。尤其是與流程代理的對話——它的「反思」輸出，本就是協作討論的起點，而非最終報告。

對 UI/UX 的影響：讓審查回饋有層次

人類開發者既然是協調者與最終仲裁者，他們與代理團隊之間的介面——終端機、編輯器與所選代理的本機 Web UI——就是整個系統的 UI/UX 核心。

核心矛盾： 人類最珍貴的是注意力與判斷力，但靜態分析工具式的審查會用幾十條無關痛癢的建議淹沒我們。若代理團隊把每一次審查的原始輸出都原封不動丟給人類，人類在「最後把關」之前就被雜訊消耗殆盡，所謂的仲裁者根本無從做起。

解法跟前述原則一致：判斷在後端，呈現在前端。 流程代理的 critique → reflect 兩步，本質上就是把「判斷哪些問題重要」的工作放在後端完成；前端（終端機或網頁儀表板）只負責呈現優先排序後的摘要。後端輸出結構化、分級的事件，前端依嚴重度分層渲染：

// 後端：把流程代理的審查結果做成結構化、分級的事件
type ReviewEvent =
  | { type: 'critique'; issue: string; severity: 'critical' | 'minor' }
  | { type: 'summary'; text: string; remaining: number }

// 前端/終端只渲染「優先摘要」，不把人類淹沒在原始批評裡
function renderReview(events: ReviewEvent[]): void {
  for (const e of events) {
    if (e.type === 'critique' && e.severity === 'critical') console.error(`🔴 ${e.issue}`)
    else if (e.type === 'critique') console.warn(`🟡 ${e.issue}`)
    else console.log(`📋 ${e.text}（剩餘 ${e.remaining} 項）`)
  }
}

終端機上的呈現長這樣——只有嚴重問題會被紅字凸顯，低影響建議被流程代理在後端過濾掉：

┌─────────────────────────────────────────────────────┐
│  🔍 流程代理審查（已用 3 秒）                          │
│  ┌───────────────────────────────────────────────┐ │
│  │  critique：掃到 14 項問題                       │ │
│  │  reflect：駁回 11 項低影響建議                  │ │
│  │                                               │ │
│  │  🔴 CRITICAL（1 項）                           │ │
│  │  • auth/token.ts:41 未驗證 JWT 過期            │ │
│  │                                               │ │
│  │  🟡 需注意（2 項）                             │ │
│  │  • 登入失敗後未清理 session cookie             │ │
│  └───────────────────────────────────────────────┘ │
│  ✋ 修正後再 commit                                  │
└─────────────────────────────────────────────────────┘

有三個值得設計的細節：

• 第一，把「反思」的過程呈現出來——顯示「critique 掃到 14 項、reflect 駁回 11 項」，讓開發者知道低影響建議是被刻意過濾，而不是被系統忽略，建立對代理判斷力的信任。
• 第二，嚴重度要分級用色——CRITICAL 用紅、需注意用黃，讓人類仲裁者在第一眼就能聚焦真正會造成系統崩潰或嚴重技術債的問題。
• 第三，回饋必須可操作——每一條摘要都要能連回具體的檔案與行號，開發者點下去就能直接定位修正，而不只是得到一句空泛的「這裡有問題」。

關於「判斷在後端、呈現在前端」的完整討論，可參考這裡-讓 AI 代理聰明更要精明：資源感知最佳化。

總結

單打獨鬥的程式設計師時代已經過去。這不是人類對抗機器的戲碼，而是人類智慧與 AI 的協作——把戰術執行（how）交給代理，把戰略創新與彈性架構設計（what）留給人類。開發者的角色已經變成設計的最終仲裁者（arbiter）：定義「做什麼」交給代理，「為什麼」如此設計。

同時，這也帶來一個必須養成的習慣——迭代對話。很多工程師看到 AI 第一次給出的結果有瑕疵，就氣得丟掉自己重寫，這是錯誤的作法。正確的作法是把錯誤當作起點，給予糾正、回饋、補充上下文，再次對話，把 AI 的回應當作討論的起點，而不是最終報告。溝通與微調，才是我們的高槓桿工作。

最後，還有一個需要正視的問題：如果未來「如何寫程式碼」的工作全部交給 AI 代理，而人類開發者的價值完全取決於定義「做什麼」的能力，那麼我們該如何重新培訓剛入行的初階工程師？當他們無法再靠著打雜、寫樣板程式碼來練功，失去了練習微觀技術的場域，未來的資深架構師要從哪裡誕生？

因此，要把版本控制的提示庫當作新人的練功場。初階工程師可以先從審視、修改既有提示詞開始——他們在優化 scaffolder.md 的同時，其實就是在理解「什麼是高品質的任務簡報」；在調整流程代理的批評標準時，就是在練習「什麼是值得保留的技術判斷」。這讓「做什麼」的能力有了具體的練習載體，而不是抽象的口號。可以先從實踐開始：在今天的專案裡，建立第一個 task-context，召喚第一個代理。

參考資料

• Appendix G - Coding Agents
• AI is now writing well over 30% of the code at Google
• 30% of Microsoft’s code is now AI-generated, says CEO Satya Nadella
• 六大 AI 的推理機制：思考還是計算？
• 讓 AI 代理接管終端機：Claude Code、Gemini CLI、Aider 與 Copilot CLI 的對決
• 讓 AI 代理學會深思熟慮：推理技巧
• RAG：讓 AI 從閉卷考變開卷考
• 讓 AI 代理聰明更要精明：資源感知最佳化
• AgentSpace：打造代理驅動型企業