智能代理程式編程正以技術界前所未見的速度演進。網路上現有的教學資源大多僅涵蓋簡單全新情境下的個別功能。
在打造 Bob 的過程中，以及與來自各行各業的無數實踐者互動之後，我們歸納出一套有助於提升使用 Bob 之成效與體驗的概念。
這些概念同樣適用於採用非主流技術的複雜專案。
概念一：循環——探索、規劃、實作、驗證
智能代理程式軟體工程中最常見的失敗模式，是缺乏結構。對話的連貫性容易讓人誤以為這就是結構，從而誘使我們將實作的所有步驟塞進同一個對話中。這樣的工作階段感覺很有效率，但代價要到審查時才會浮現。
手工寫程式本身就帶來一種自然的結構。由於實作的成本高，在實作前先規劃顯得直覺上合理。在打字的過程中，理解會逐漸積累，而錯誤的假設也很可能在這個過程中浮現。 AI 代理程式消除了這種摩擦。程式碼現在很便宜，這同時也抹去了我們對結構的直覺。曾經作為速度緩慢副產品的結構，如今必須刻意為之。
有意識地運用以下循環，可以提供所需的結構：
- 探索產生理解
- 規劃產生決策
- 實作產生程式碼
- 驗證產生證據
遵循此循環有助於你保持專注、維持結構，並更快、更穩定地達成目標。
單次循環可能耗時二十分鐘，也可能長達三天。一次循環可包含子循環，各階段的時間分配也因任務而異。
關於循環的詳細說明，請參閱下方的深度解析：執行循環。
概念二：上下文視窗是稀缺資源
刻意管理上下文視窗，是回報最高的習慣。
什麼是上下文視窗？
模型是無狀態的。一個對話並非持有記憶的執行工作階段：每一輪都會重新傳送所有先前訊息，並將新的回答附加到末尾。上下文視窗是模型在單次輪次中能接受的最大輸入量。在 Bob V2 中，這個上限為 270k token（上下文視窗管理）。
在第一條訊息傳送之前，視窗就已開始填充：
- 預先載入： Bob 的系統提示、目前模式的描述、repo 的
agents.md，以及每個已連接的 Model Context Protocol (MCP) 工具的描述（Bob 中的 MCP）。 - 工作階段中隱式新增： 檔案讀取、工具執行結果、Bob 引入的 skill 檔案、子代理程式的輸出。
當視窗填滿時，Bob 會壓縮對話。Bob 會以摘要取代目前的對話記錄，然後繼續工作。這樣可以讓工作階段持續進行，但這個過程本質上是有損的。Bob 會自動決定哪些細節被保留，而被丟棄的內容不會有任何標記。一個已壓縮兩次的工作階段，是在摘要的摘要上運作的。
單次 MCP 呼叫可能返回數萬個 token，而一連串的檔案讀取會稀釋工作階段早期討論的內容。模式描述、規則檔案和 MCP 伺服器的影響則更緩慢、更不明顯。Bob 會按來源細分視窗用量，隨著設定逐漸增多，值得定期開啟並檢視這份分解報告。
Bobcoin 主要按 token 數計算費用，因此對話的成本隨其長度呈二次方增長。較長的對話消耗的 Bobcoin 遠多於較短的對話！（Bobcoin 說明文件）
順著上下文視窗工作，而非對抗它
- 將工作拆分到不同的對話中。 一個任務，一個工作階段。這與程式碼中的單一職責原則邏輯相同。一個對話應該只有一個存在的理由，例如「為元件 X 繪製架構圖」或「為功能 Y 建立實作計畫」。上下文視窗中的所有內容都會影響後續輸出，包括那些沒有奏效的方案。一個陷入僵局的工作階段往往會持續僵持，因為失敗的嘗試仍在其中，模型會將其視為這個任務本來面貌的依據（上下文污染）。
- 回滾，而非與 Bob 爭論。 當對話漂移至不期望的行為時，回滾到最後一條正確的訊息，修改該訊息，然後從那裡繼續。這也會撤銷 Bob 在本機所做的所有變更，讓上下文視窗保持精簡（回滾）。
- 值得保留的內容存入檔案，而非留在對話中。 計畫、發現和決策都應存入檔案。同事可以審閱一份 Markdown 文件，並將其交給全新的工作階段；對話記錄卻無法做到這兩點。
- 子代理程式讓大量工作不佔用上下文視窗。 Bob 會自行決定何時執行子代理程式，且只有發現結果會被帶回。當一個任務會產生無需閱讀的大量輸出時，也可以直接要求使用子代理程式（子代理程式）。
- 留意哪些內容進入了上下文視窗，以及這些內容是否有價值。定期檢查你的指引與感測器（如下一節所述），並花時間改善它們。
概念三：兩類基礎構件——指引與感測器
在一個長期專案中，程式碼庫是變好還是變差，與其說取決於 Bob，不如說取決於什麼在塑造其工作、檢查其輸出。可用的基礎構件有很多：規則、skill、模式、hook、子代理程式、外部 linter 和審查代理程式。它們幾乎都只做兩件事之一。
- 指引在 Bob 工作前或工作中引導它（前饋）。 規則、skill 和模式都是指引。
- 感測器在 Bob 行動後回報結果（回饋）。 測試、linter、型別檢查器、互動式瀏覽器工作階段和審查代理程式都是感測器。
1. 指引
所有提供給 Bob 以引導工作的內容都是指引。主要有三種基礎構件可以幫助你實現這一點，它們的運作方式是在你輸入的提示之外，將文字額外放入上下文視窗。它們的差異在於文字何時到達以及什麼觸發它。
- 規則始終啟用。
repo 根目錄的
agents.md是主要規則檔案，關於它的主要建議是保持簡短。每一行都在每一個輪次中競爭注意力，因此過長的規則檔案反而會讓 Bob 難以遵守其中任何一條個別規則（規則）。 - 模式由使用者啟用。 內建模式包括：Ask 為唯讀模式。Plan 透過規劃流程產出結果，並將結果交給 Agent 執行。自訂模式也可以輕鬆新增（模式、新增自訂模式）。
- Skill 由 Bob 在判斷相關時啟用。 只有較短的 skill 描述始終保持啟用狀態。skill 的主體內容只在需要時才載入上下文，這使得 skill 非常節省 token（skill）。
規則檔案中的所有內容每一輪都消耗 token，無論此輪是否需要，因此要保持精簡，讓其餘內容等到適用時再載入。
2. 感測器
所有給予 Bob 關於其產出之回饋的內容都是感測器。哪些訊號有用取決於程式碼庫和技術堆疊，因此值得擁有的感測器集合因專案而異，需要花真功夫來組裝。最有價值的感測器是可由機器執行的，並在實作階段由 Bob 自行執行。感測器可分為兩類。
- 計算型感測器是確定性的：測試、linter、型別檢查器、編譯器。結果精確且可重現，成本低廉，Bob 可以頻繁執行。覆蓋範圍受限於團隊建立和維護的系統。
- AI 型感測器是靈活且不確定性的。審查代理程式依意圖閱讀，以及針對 linter 沒有規則的事項進行判斷。其輸出是判斷，而非測量。結果在不同執行間有所差異，成本和時間限制了其使用頻率（程式碼審查）。
整合感測器有幾種選擇，大致按摩擦力由低到高排列：
- Hook 是摩擦力最低的確定性選項。一個檢查在固定時間點執行，每次都執行，無論 Bob 是否認為其相關。請參閱 hook 說明文件。
- Skill 通常作為指引使用，但一個執行審查的 skill 就是感測器，這也是新增非確定性檢查的最低摩擦方式。請參閱 skill 說明文件。
- 持續整合（CI） 將審查代理程式放入 pipeline，在每個 pull request 上執行，服務整個團隊而非單一開發者。請參閱 PR 審查代理程式實際操作影片。
深度解析：執行循環
各階段的邊界同時也是上下文的邊界，這是保持各階段獨立的實際原因：探索時的零散對話，不應出現在寫程式碼的對話中。
1. 探索
探索的內容因角色和手邊任務而差異很大。它可能是融入一個新的程式碼庫，也可能是評估一次重大重構的影響範圍。一些範例：
- 讓 Bob 為現有系統產生架構圖，然後再做任何修改。請參閱產生架構圖教學，或相同內容的影片版本。
- 從兩個角度索取量身定制的入門導覽，一次以使用者的視角瀏覽產品，一次以開發者的視角瀏覽程式碼。提供關於你的專業背景和任務的資訊，有助於讓文件更貼近需求（檢視程式碼庫）。
- 在 IBM Z 和 IBM i 上，使用平台專屬選項。 這些系統上的探索問題截然不同，能從 premium package 提供的專業工具中大幅受益。請參閱 Z 的 Premium Package（說明文件）以及 IBM i 的 Premium Package（說明文件）。
探索也可能包括打造你預計丟棄的東西。實作現在很便宜，因此一個範圍有限的原型，是驗證某種方法能否在程式碼庫中存活的最快方式。Kent Beck 在二十五年前稱之為 spike implementation，其原則至今相同：打造它是為了學到東西，保留學到的，丟掉程式碼。
廉價的實作提升了架構與程式碼品質的價值，而非降低它。現在很容易寫出大量能運行但方向錯誤的程式碼。
2. 規劃
規劃階段是槓桿最大的地方。計畫做對的每一件事都會有雙倍回報：一次在實作中，一次在變更離開作者手中、同事需要審查時。
一份好計畫需要：
- 簡短且精確，兩者兼顧。 計畫需要被閱讀。
- 明確說明預期結果，包括不確定的部分。知道什麼是未知的，佔了工作的大半，而找出答案是剩下的部分。
- 存入檔案。 計畫不應存活在對話工作階段中。
建立計畫的方式有很多，但內建的 Plan 模式是最容易上手的地方（如本教學所示）。
Plan 模式的設計偏向順從，傾向於填補空缺。雖然這在許多情況下能實現快速迭代，但有時需要更嚴謹的態度。它可能會在一個錯誤假設的基礎上建立一份稱職的計畫，而不質疑這個假設。
一個能與計畫對抗的專屬 skill——例如 Matt Pocock 的 grill-me——是在假設變成程式碼之前獲得審查的最低成本方式。
關於規格驅動開發（SDD）。 這個術語涵蓋了廣泛的範疇，目前仍在演進中。人們傾向於將其視為非此即彼的決定，但它更接近於一個光譜：
- 規格優先：計畫先於實作。這幾乎是不可妥協的。
- 規格錨定：規格在實作後仍然存在，作為文件以及實作必須達到的標準。
- 規格即來源：規格就是來源檔案。人類編輯規格；人類不直接編輯程式碼。
適合哪個層級，取決於團隊、程式碼庫的關鍵性與成熟度，以及所屬產業。較高層級的 SDD 帶來的額外負擔，對快速迭代可能造成痛苦。在汽車行業，規格驅動開發比 AI 早了幾十年，SDD 非常符合現有實踐。
3. 實作
實作是最直接的階段，Bob 幾乎能處理全部內容。
在 Bob 工作時觀察並適時打斷以澄清，是可選且通常有益的做法。把打斷的頻率視為一個訊號：頻繁打斷意味著問題出在計畫上，解決方法是回頭修改計畫，而不是持續糾正。
不要猶豫是否要丟棄整個實作並回到 Plan 模式。程式碼才是便宜的那個部分。
4. 驗證
驗證分為兩個截然不同的類別：自動化驗證和手動驗證。
自動化驗證由 Bob 可用的感測器或透過 hook 強制執行的感測器驅動。它們在實作階段頻繁執行，無需人工介入。主要類別及一些常見範例如下：
- 有效性：它能編譯、通過型別檢查、解析嗎？
- 衡量指標：通過/失敗、型別覆蓋率
- 工具：
tsc、mypy、cargo check、javac
- 行為：它做了正確的事嗎？
- 衡量指標：通過率、分支覆蓋率
- 單元測試、整合測試、端對端測試
- 工具：
pytest、Jest、Playwright、Stryker
- 可維護性：這段程式碼值得保留嗎？
- 衡量指標：複雜度、重複性、邊界違規
- 工具：ESLint、Ruff、Lizard、ArchUnit
- 安全性：這段程式碼安全嗎？
- 衡量指標：按嚴重性分類的發現數、CVE
- 工具：Semgrep、CodeQL、gitleaks、
npm audit
它們使 Bob 能夠發現自身的錯誤，並在實作階段提升品質。良好的測試覆蓋率是防止回歸的重要保護：它確保 Bob 沒有破壞任何現有功能。
在此循環中，驗證被列為循環末尾的獨立階段，這主要是指手動驗證。 手動驗證從執行變更並將觀察到的行為與計畫所指定的行為進行比對開始。不符的情況通常可歸因於以下兩種原因之一：
- 實作偏離了計畫。修復在程式碼中。
- 計畫未能反映你實際打算建構的東西。計畫需要精煉。這種情況更為常見。
手動檢查因此同時測試了計畫和實作。
額外的驗證應在 CI/CD pipeline 中進行。這是軟體工程中的成熟實踐，但可以透過使用無介面的 coding agent 來改善。一個範例：在每個 pull request 上透過 Bob Shell 執行的自動審查，是對人工審查者的補充，而非取代。請參閱 PR 審查代理程式實際操作影片以及以非互動模式執行 Bob Shell 的說明文件。
在團隊中工作
前面幾節描述的是單一開發者的內部循環。外部循環從變更進入審查佇列時開始。每個 diff 現在到達得更快，但附帶的推理說明卻更少，而審查者需要閱讀的東西更多，卻擁有更少的上下文。
證據必須隨著工作一起傳遞。相較於如何完成的，為何這樣做變得更加重要，因為如何完成已不再是昂貴的部分。
實際上，這意味著計畫應隨著變更一起傳遞：團隊將其附加到 pull request，或連同審查一起加回原始 issue 中。具體機制取決於所使用的工具。
外部循環對團隊流程的影響是一個獨立的主題，將在後續文章中討論。
關於提示的一些思考
過去幾年，如何正確地提示 LLM 受到大量關注，甚至衍生出「提示工程師」這個職位類別。如今，大量的提示處理已由框架內部完成。專門提示技術的重要性已逐漸讓位於方法論的方式。以下是一些準則：
- 迭代勝過提示。 當 Bob 的行為不符合你的要求時，回滾並重寫引發問題的那條訊息。在原訊息後持續糾正，會把錯誤答案、對其的抱怨以及重試全部留在視窗中。
- 方法論勝過提示。 一個提示的作用範圍只限於一個工作階段。一份規則檔案，或一個 Bob 可以自行執行的檢查，在產生它的那個工作階段之後的每一個工作階段中都持續發揮作用，這是唯一能在此處累積的投資類型。
- 給 Bob 一份資深工程師會收到的摘要。 一位稱職的同事在接到模糊任務時，會詢問完成標準和允許觸碰的範圍；Bob 不會主動詢問，所以把這兩點都寫進訊息裡。
- 說該做什麼，而非不該做什麼。 「不要使用 class component」排除了一個選項，卻讓其餘的空間都開放著，於是 Bob 從剩下的選項中挑選，這又是一個猜測。直接指定目標——使用帶有 hook 的函式元件——一次就能解決問題。
- 任何給了超過兩次的指令，都應存入檔案。 這正是
agents.md和 skill 的用途。 - 更詳細的提示說明可在撰寫有效提示教學中找到。
重點摘要
- 缺乏結構是最大的問題。 遵循「探索 → 規劃 → 實作 → 驗證」循環，有助於你保持專注，並更快、更穩定地達成目標。
- 上下文是稀缺資源，各階段是上下文的邊界。 不要把探索時的零散對話帶入實作。
- 計畫是審查的產物。 審查計畫優於審查 diff，對作者和審查者皆然。
- 值得保留的任何內容都應離開對話。 計畫、決策和發現都應存入檔案。你可以對檔案進行差異比對、審查、版本控制，並將其交給另一個代理程式。
- 驗證應可由機器執行，這意味著你必須在規劃期間設計它，而非事後才發現需要它。
來源與延伸閱讀
- Simon Willison, Agentic engineering patterns
- Birgitta Böckeler, Harness engineering
IBM Bob 說明文件與教學：