編程代理架構：上下文工程與規模化最佳實踐
來源: @juliandeangeIis | 原文連結
日期: Sat Feb 28 23:28:10 +0000 2026
標籤:
AI 編程助手上下文工程代理架構
來源: @juliandeangeIis日期: 2026-03-05 標籤:
AICoding-AgentContext-EngineeringAgent-HarnessMCPSpec-Driven-Development
Coding Agent Harness：如何讓 AI 編程代理在規模化下真正發揮作用
每個人都在使用 AI 編程代理（AI coding agents）進行開發。但很少人能獲得一致的結果。
差異不在於模型、IDE 或提供商。而在於 agent harness（代理架構）：圍繞代理建構的結構化系統，包含上下文、工具和防護機制，讓它能可靠地執行，每一次都如此。
其底層原理是 context engineering（上下文工程）：設計和控制 LLM 在生成任何 token 之前所看到的一切。
agent harness 是上下文工程的實踐應用：將理論轉化為可重複結果的具體實作。
在 MercadoLibre，我們正在向近 20,000 名開發者和數千個程式碼庫推廣這套系統。以下是我們學到的經驗、有效的方法，以及大多數團隊常犯的錯誤。
為什麼需要 Context Engineering？
這個心智模型改變了我對 AI 代理的思考方式：
你的 AI 編程代理就像一個第一天上班的優秀新人。速度快、積極主動，但對你的程式碼庫、慣例或架構完全沒有概念。
你不會只是說「修這個 bug」或「做這個功能」然後就不管了。
你會讓他們入職：文件、技術堆疊、風格指南、發布流程、必要工具的存取權限，以及一位導師來審查他們的工作。
這就是上下文工程：建立一個圍繞模型的系統，讓它能持續做出最好的工作。
Agent 迴圈與其瓶頸
流行的 AI 編程代理如 Claude Code、Cursor 和 Codex，都共享相同的基本迴圈：
讀取 → 規劃 → 編碼 → 驗證 → 迭代
代理讀取你的檔案、規劃方法、撰寫程式碼、執行測試，如果失敗就回到迴圈。這個迴圈很強大，但每次迭代都會消耗同一個有限資源：context window（上下文視窗）。
上下文視窗是代理當前任務的即時工作空間。代理在任何時刻能參考的所有內容都必須放進去。而在迴圈的每個階段，它都在增長：
該圖表顯示 token 如何在有限的上下文視窗內分配。系統規則固定在頂部，而工具結果和對話歷史隨著每輪增長。
這就是我們正在工程化處理的限制。
系統提示和自訂規則：在每輪開始時注入。如果規則對當前任務無用，它們就是在浪費空間。
工具定義：你配置的每個 MCP server 都會增加其 schema。更多工具 = 更少空間留給其他內容。
對話歷史：每條先前的訊息線性累積。
工具結果：檔案內容、終端輸出、API 回應。單次讀取一個大檔案可能一次消耗數千個 token。
代理自己的輸出：它撰寫的程式碼也存在於上下文視窗內。
每個花在冗長工具結果或過長規則檔案上的 token，都是無法用於代理實際工作程式碼的 token。而隨著上下文填滿，準確性和記憶力會下降，通常稱為 context rot（上下文腐化）。
超過某個點（一些研究顯示約在上下文視窗容量的 ~60%），更多的上下文實際上會讓代理變得更糟。
想了解更多關於 context rot 的見解，我推薦這篇近期文章：https://www.morphllm.com/context-rot
即使上下文視窗達到 100 萬或更多 token，基本挑戰依然存在。
最好的 agent harness 設計都以這個現實為核心：在正確的時刻注入正確的上下文，避免用無關資訊污染視窗，並建構長期執行的任務以保持精簡。
Agent Harness：你需要掌握的四個控制桿
agent harness 是一組結構化的控制機制，塑造代理知道什麼、能做什麼，以及其工作如何被驗證。有四個關鍵控制桿：
1. Custom Rules（自訂規則）（cursor/rules, AGENTS.md, CLAUDE.md 等）
這是最容易使用的控制桿，也是大多數團隊應該開始的地方。自訂規則是在每次互動開始時自動注入代理上下文的檔案。
自訂規則應該包含什麼：
- 你專案的技術堆疊和架構模式
- 命名慣例和程式碼風格偏好
- 測試哲學（「總是撰寫帶有表格驅動輸入的單元測試」）
- 你程式碼庫特定的常見陷阱
- 不該做什麼（你多次看到代理產生的反模式）
不屬於自訂規則的內容：
- 完整的 API 文件（太長，浪費上下文）
- 顯而易見的指示（「撰寫乾淨的程式碼」）
- 相互矛盾的規則
關鍵見解：自訂規則是活文件。每次代理犯錯時，你可以詢問代理如何改進其架構。幾週後，你的規則檔案就會成為極其有效的行為指南。
撰寫有效自訂規則的技巧：
- 保持在 500 行以內。指示要精確。
- 模組化。將規則按關注點分成專注的檔案：架構、測試、程式碼、安全性。這樣代理只載入任務必要的內容。
- 使用 few-shot 範例。模型從範例學習遠勝於抽象指示，但不要過度使用冗長範例。
- 不要讓所有內容永遠啟用。很少有規則需要在每個 session 注入。當你的工具支援時使用條件載入。這就是 skills 補充自訂規則的地方：將詳細、重上下文的指示移到按需啟動的 skills。
2. MCP Servers（Model Context Protocol）
MCP 是你給代理的工具，超越讀寫檔案。把它們想成擴展代理能力的外掛。
開箱即用，編程代理可以讀檔案、寫程式碼和執行終端指令。但有了 MCP，它可以：
- 查詢你的資料庫以了解 schema 和資料
- 搜尋你的內部文件或 wiki
- 查找內部 API 合約
- 與你的 CI/CD pipeline 互動
- 從 Figma 存取設計規格
- 測試其實際實作
MCP 的威力在於彌合代理與你組織知識之間的鴻溝。沒有它們，代理僅限於程式碼庫內的內容。有了它們，它可以存取人類開發者會使用的相同資源。
它們對於驗證實際代理輸出也很強大，我稍後會談到回饋迴圈。
3. Skills
Skills 可以給代理新能力和領域專業知識。它們是架構中最強大的控制桿，因為它們結合了上下文注入和可執行邏輯。
一個 skill 是一個包含 SKILL.md 入口點的目錄，可以打包模板、範例輸出、參考文件和可執行腳本。
只有簡短描述保留在上下文中，讓代理知道有什麼可用。完整內容只在 skill 被調用時注入，無論是使用者（/skill-name）還是代理在檢測到相關性時自動調用。
這種按需載入意味著 skills 可以盡可能詳細，而不會永久消耗你的上下文預算。
它們有兩種形式：注入知識的參考 skills（慣例、模式、領域上下文）和為特定動作提供逐步指示的任務 skills。
但真正的威力在於 skills 可以打包和執行腳本，使可擴展性基本上無限：從生成互動式視覺化到擷取即時 CI 資料。它們也可以在具有自己乾淨上下文視窗的隔離 subagent 中執行，防止繁重任務污染你的主 session。
Skills 是可程式化、上下文感知、可組合的代理行為單元。
4. Spec Driven Development（規格驅動開發）（終極架構）
這個值得特別關注，因為它完全重構了你與代理互動的方式。
當前 Coding Agent 的主要瓶頸之一在於椅子和螢幕之間：你。這是因為溝通問題。
當人們開始使用編程代理時，普通使用者沒有指定足夠的細節，所以代理必須「預測」正確的實作。
例如：「製作一個從後台新增項目的新功能」。
看起來簡單，但沒有指定任何內容：技術堆疊、後台在哪裡、API 合約、在哪裡儲存新項目。
在這種情況下，代理會讀取當前程式碼庫、規劃實作，可能達到一個可行的 MVP。你從後台新增一個項目，它有效，也將項目儲存在現有的 MySQL 中。
但當你再次點擊「新增」按鈕時，它會插入該項目兩次。
代理應該透過 ID 管理冪等性「很明顯」。在我們的業務中，只有一個角色可以插入項目「很明顯」。
問題不在於代理：而在於最初的輸入太簡陋。
這就是 Spec Driven Development 要解決的主要問題之一。那麼，它是什麼？
Spec Driven Development (SDD) 是在代理撰寫任何一行程式碼之前撰寫詳細規格的實踐。這些規格包含：功能做什麼、如何與現有程式碼整合、邊緣情況是什麼、驗收標準是什麼樣子，以及測試計劃是什麼。
為什麼 SDD 是最純粹形式的上下文工程？ 因為規格本身就成為了架構。
當你交給代理一份寫得好的規格時，你不只是告訴它要建構什麼。你一次性工程化了它的整個上下文視窗。規格整合了自訂規則（架構決策）、逐步指導和驗收標準（像審查代理），全部在單一或多個 artifact 中。
最棒的部分：你也可以使用代理來撰寫規格。
我會在另一篇文章中擴展 Spec Driven Development、框架、優缺點以及我們如何在規模化下實施它。
回饋迴圈
上述四個控制桿定義了代理知道什麼和能做什麼。但有一個部分位於上下文工程之外，讓整個系統運作：回饋迴圈。測試、linter、型別檢查器、建置腳本：每個產生通過/失敗訊號的工具都成為代理用於自我修正的回饋機制。
可用的結構化回饋越多，所需的「人在迴圈中」就越少。
強制執行此機制最強大的方法之一是 agent hooks：在代理生命週期的特定點自動執行的使用者定義指令。將你的驗證連接到 Stop hook，代理就無法完成，直到檢查通過。這不是它可能忽略的建議。這是強制閘門。
我也會在專門的文章中深入介紹回饋迴圈：hooks、審查代理、Stop hook 模式，以及如何讓整個代理生命週期可程式化。
我們在 MercadoLibre 如何規模化實施
理論很好，但現實會敲門。
真正的規模化需要將這些控制桿編排成一個在整個組織中運作的系統。
有很多規模化問題要解決：不同的技術和版本、數千個（遺留）程式碼庫、多個知識領域，當然還有錯誤使用的成本。
我們目前正在實施 Spec Driven Development，仍在獲得內部採用（已有 4000 名開發者），因為改變開發者的日常工作流程很困難，但我會在另一篇文章中介紹它。
以下是我們做的一些其他實踐：
每種技術的標準化規則
我們在組織層級維護一組精心策劃的自訂規則，針對我們所有的技術（9+）堆疊、內部函式庫和程式碼審查標準進行調整。團隊繼承這個基礎，然後疊加程式碼庫特定的規則。
這些規則的品質至關重要。過於具體可能會破壞遺留專案。使用外部、未批准的函式庫可能導致安全漏洞。
內部開發平台的內部 MCP
我們建構了內部 MCP server，具有內部雲端平台功能和上下文。其中一個主要 MCP 擁有完整的工具包上下文，用於使用對齊的服務和內部 SDK。
提供來自 RAG 結果或更新應用程式文件的業務上下文的內部 MCP。
自訂程式碼審查代理
我們建構了作為 CI pipeline 一部分執行的獨立審查代理。每個 PR，無論是由人類撰寫還是由 AI 編程代理生成，在人類審查者檢視之前都會自動分析。
它們回傳優先順序的發現，因此工程師首先看到最關鍵的問題，而不是平面的評論列表。人類審查者可以專注於高層次的設計決策，而不是捕捉風格違規或遺漏的慣例。在生產之前發現 bug。
結果：更快的審查週期、更一致的程式碼品質，以及一個隨 PR 數量擴展而非審查者數量擴展的安全網。
更大的藍圖
上下文工程不只是一組技術。它是一個新興的工程學科。而 agent harness 是其具體產出：你實際建構、維護和迭代的東西。
隨著 AI 編程代理變得更強大，獲勝的團隊不會是使用最花俏模型的團隊。而是擁有最佳工程架構的團隊：自訂規則、MCP、skills 和規格驅動工作流程作為一個系統協同工作，並具有緊密的回饋迴圈使其持續收斂。
機會是巨大的。但它需要將 AI 代理不是視為魔法盒子，而是視為需要適當入職、工具和監督的優秀團隊成員。
我可以從哪裡開始？ 我的建議是從最簡單的技術開始：關於最佳編程實踐的自訂規則或 skills。祝工程順利！