刻意讓代理慢下來

更快的代理不會打造出更好的軟體——有紀律的代理才會。讓 RakuAI 保持連貫的那個節流閥,正是我們認為每一個認真的代理驅動團隊都需要的紀律。

這個週六的計畫和前幾個週末不一樣。前幾個週末都是產出量週末。八十個 commit、七十個 commit,再之前是兩百八十二個。趨勢一路向上。我把代理佇列全開,看著程式碼行數不斷堆高。

這個週末我刻意把它壓回三十七個 commit。這張圖上的趨勢現在是向下的,而且是刻意向下的,我想寫一寫為什麼,因為我不認為這是大多數用 AI 代理做開發的人會預期的趨勢。

這個工作流程的真實面貌

代理不會累。實作層的產出量,受限於 token 成本和佇列上有多少開放的議題。如果我早上六點開一百個議題,佇列會整天清空又填滿,然後我會收回一百個 PR。當這個工作流程被允許全速運轉時,它就是這樣。

它在全速運轉時做不到的,是產出一個連貫的程式碼庫。每個 PR 各自落地時都很乾淨。一天之內落地的四十個 PR 的交集開始漂移。命名慣例分歧。子系統邊界變得模糊。處理某個議題的代理對執行環境層做了一個假設,而處理平行議題的代理沒有做同樣的假設。到了週六晚上,這兩個假設在第三個 PR 裡撞在一起,那個 PR 必須調和它們,而調和的結果就是爛泥。

這個工作流程的瓶頸不是代理。是那個閱讀代理產出、維持架構連貫的人。

我改了什麼

兩件事,都能在這個週末的 commit 模式裡看見。

我砍掉了佇列深度。不再隨時保持十五個開放的代理佇列議題,我把它降到六個。代理不再全速運轉。它們的節奏,讓我能在下一批落地之前真的讀完它們的輸出。

我把審查提前了。不再讓代理的 PR 堆著等我攢成一批來處理,我改成每一個 PR 一開就審。這聽起來比較慢,而且確實比較慢。但它也能在漂移擴散之前抓住它。一個在週六一早就被糾正的壞假設,不需要在週六晚上橫跨六個 PR 去解開。

這兩個改變加起來的效果,就是一個三十七 commit 的週末,而不是八十 commit 的週末。加起來的效果,也是一個比上週六狀態更好的程式碼庫,而這才是重點。

依然落地了什麼

一套多倉庫紀律在這個週末變得更扎實。執行環境、SDK 和文件倉庫一起移動。執行環境在 README 裡得到了文件目錄總覽。SDK 得到了對應的交叉引用。文件成長了。三個倉庫沒有任何一個跑到其他倉庫前面。

這很重要,因為在代理驅動的工作流程裡,文件不只是文件。文件是代理接手下一個議題時讀取的輸入。如果文件對執行環境支援什麼撒了謊,代理會忠實地為那個撒謊版本的執行環境寫程式碼,而那些程式碼無法對著現實編譯。補救方法是讓三個倉庫隨時保持誠實,即使其中一個才是你自然而然會想動手的那個。

這個週末另一件安靜但重要的事,是 API 表面的清理。有幾個在九月的衝刺中加進來的 API,後來發現不該放在公開表面上。它們被降級為內部使用。代理在一個 PR 裡完成了橫跨整個 SDK 的降級。這種重構,由一個人類單獨做,要花上一整天。在這個工作流程裡,只要一個議題、一個 PR,和一次仔細的審查。

在這個工作流程裡,「最佳實踐」是什麼意思

一份短清單,被這個週末砍節奏的經驗磨得更利。

文件是開發的輸入,不是開發的輸出。如果文件很爛,工作就會很爛。像維護程式碼一樣維護文件。像審查程式碼一樣審查文件。拒絕合併任何跳過文件的功能。

子系統之間的邊界是神聖的。代理不會發明程式碼庫裡本來沒有的邊界。如果你想要一條邊界,你必須自己畫出來、標上名字,並拒絕違反它的 PR。

跨倉庫同步是第一級任務。當執行環境和 SDK 必須一起移動時,PR 描述必須寫明,而且其中一個的合併要以另一個的合併為前提。雙倉庫狀態分歧,是比較容易避免、卻比較痛苦難以復原的失效模式之一。

刻意慢下來。代理不會。你必須。代理出貨一百個 PR 的那個週末,並不等於程式碼庫改善了一百個 PR 價值的那個週末。代理出貨三十七個仔細審查過的 PR 的那個週末,倒有可能是。

合作夥伴可能覺得有用的部分

如果你正在用自主編碼代理打造任何東西,而且正陷入這個工作流程的「代理跑得飛快、程式碼庫一團糟」版本,答案不是更好的代理。答案是更小的佇列、更早的審查,以及讓代理當作輸入來讀的文件。

如果你是一個 AI 實驗室,正在為像這樣的自主 PR 工作流程調校編碼代理,我在實務上覺得最有用的指標,不是每天出貨的程式碼行數。而是一週前段落地的 PR,有多常在同一個週末稍晚就必須重寫,因為程式碼庫在它腳下移動了。那個數字越低,代理在真正的工作上就越出色。

三十七個 commit。一個比上週六更好的程式碼庫。週六下午,我要去散個步。