世界級代理工程師的修煉指南
來源: @systematicls | 原文連結
日期:
標籤:
AI 代理Claude CodeContext 管理
來源: @systematicls (sysls)
日期: 2026-03-05
標籤:AI工具Claude CodeCodex代理工程開發工作流
引言
你是一名開發者。你正在使用 Claude 和 Codex CLI，每天都在想自己是否已經充分榨取了 Claude 或 Codex 的所有能力。偶爾你會看到它做一些極其愚蠢的事情，而你無法理解為什麼外面有一群人似乎在建造虛擬火箭，而你卻在努力堆疊兩塊石頭。
你認為問題出在你的工具、外掛、終端機或其他什麼東西上。你使用 beads、opencode、zep，你的 CLAUDE.md 有 26000 行長。然而，無論你做什麼——你都不明白為什麼無法更接近天堂，而你看著其他人與天使嬉戲。
這就是你一直在等待的升天指南。
另外，我在這場競賽中沒有任何利益關係，當我說 CLAUDE.md 時，我也指 AGENT.md，當我說 Claude 時，我也指 Codex。我兩者都廣泛使用。
在過去幾個月中，我觀察到的最有趣的現象之一是，沒有人真正知道如何最大化地提取代理能力。
就像是一小群人似乎能夠讓代理成為世界建造者，而其他人則在掙扎，因為外面眾多的工具而陷入分析癱瘓——認為如果他們找到正確的套件、技能或工具組合，就能解鎖 AGI。
今天，我想消除所有這些迷思，並給你們留下一個簡單、誠實的陳述，然後我們從那裡開始。你不需要最新的代理工具，你不需要安裝一百萬個套件，你絕對不需要覺得必須閱讀一百萬個東西才能保持競爭力。事實上，你的熱情可能弊大於利。
我不是一個觀光客——我從代理幾乎無法寫程式碼的時候就開始使用它們了。我嘗試過所有的套件、所有的工具和所有的範式。我建立了代理工廠來寫訊號、基礎設施和資料管線，不是「玩具專案」——而是在生產環境中運行的實際真實世界用例，經過所有這些之後...
今天，我運行的設定幾乎是你能想像的最精簡的，然而我正在做我用基本 CLI（claude code 和 codex）和理解幾個關於代理工程的基本原則所做過的最突破性的工作。
理解世界正在快速前進
首先，我想說明的是，基礎公司正在進行世代性的衝刺，正如你所看到的，他們不會很快放慢速度。每一次「代理智能」的進步都會改變你與它們合作的方式，因為代理通常被設計得越來越願意遵循指令。
就在幾代之前，如果你在 CLAUDE.md 中寫道要在做任何事情之前先閱讀「READ_THIS_BEFORE_DOING_ANYTHING.md」，它基本上會有 50% 的時間說「去你的」，然後做它想做的事。今天，它對大多數指令都很順從，即使是複雜的嵌套指令——例如，你可以說「先讀 A，然後讀 B，如果是 C，則讀 D」之類的東西，在大多數情況下，它會很樂意遵循。
這一點的重點是，最重要的原則是認識到，每一代新的代理都會迫使你重新思考什麼是最優的，這就是為什麼少即是多。
當你使用許多不同的函式庫和工具時，你將自己鎖定在一個「解決方案」中，用於解決一個在未來幾代代理中可能不存在的問題。此外，你知道誰是最熱情、最大的代理用戶嗎？沒錯——是基礎公司的員工，擁有無限的 token 預算和實際的最新模型。你理解這意味著什麼嗎？
這意味著，如果真的存在一個問題，並且有一個好的解決方案，基礎公司將是該解決方案的最大用戶。你知道他們接下來會做什麼嗎？他們會將該解決方案整合到他們的產品中。想想看，為什麼一家公司會讓另一個產品解決一個真正的痛點並創建外部依賴？你知道我怎麼知道這是真的嗎？看看技能、記憶工具、子代理等。它們都是作為一個「解決方案」開始的，用於解決一個經過實戰測試並被認為實際有用的真實問題。
因此，如果某樣東西真的具有突破性，並以有意義的方式擴展了代理用例，它將在適當的時候被整合到基礎公司的基礎產品中。相信我，基礎公司正在快速前進。所以放輕鬆，你不需要安裝任何東西或使用任何其他依賴來做你最好的工作。
我預測現在評論中會充滿「SysLS，我使用某某工具，它太棒了！我在一天內成功重建了 Google！」；對此我說——恭喜！但你不是目標受眾，你代表的是社群中一個非常非常小的利基市場，這個市場實際上已經弄清楚了代理工程。
上下文就是一切
真的。上下文就是一切。這是使用一千個不同外掛和外部依賴的另一個問題。你會遭受上下文膨脹——這只是說你的代理被太多資訊淹沒的一種花俏說法！
用 Python 幫我建一個猜字遊戲？那很簡單。等等，這個關於「管理記憶體」的筆記是從 26 個 session 前來的是什麼？啊，用戶有一個螢幕在 71 個 session 前我們產生太多子程序時掛起了。總是寫筆記？好的，沒問題...這一切與猜字遊戲有什麼關係？
你懂的。你想要給你的代理完成任務所需的確切資訊量，不多不少！你越能控制這一點，你的代理表現就會越好。一旦你開始引入各種古怪的記憶系統或外掛或太多命名和呼叫不當的技能，你就開始給你的代理關於如何製造炸彈和烘焙蛋糕的食譜的指令，而你只想讓它寫一首關於紅木森林的小詩。
所以，我再次宣揚——剝離你所有的依賴，然後...
做有效的事情
對實作保持精確
記得上下文就是一切嗎？
記得你想要注入給代理完成任務所需的確切資訊量，不多不少嗎？
確保這一點的第一個方法是將研究與實作分開。你想要對你要求代理做什麼非常精確。
當你不精確時會發生什麼：「去建立一個認證系統。」代理必須研究什麼是認證系統？有哪些可用的選項？優缺點是什麼？現在它必須去網路上搜尋它實際上不需要的資訊，它的上下文充滿了大量可能性的實作細節。到了實作的時候，你增加了它會對所選實作感到困惑或產生幻覺的機會，產生不必要或不相關的細節。
另一方面，如果你說「使用 bcrypt-12 密碼雜湊實作 JWT 認證，refresh token 輪換，7 天到期...」那麼它不必研究任何其他替代方案——它確切地知道你想要什麼，因此可以用實作細節填充其上下文。
當然，你不會總是有實作細節。你經常不知道什麼是完全正確的——有時，你甚至可能想要將決定實作細節的工作委託給代理。在那種情況下，你該怎麼辦？簡單——你創建一個關於各種實作可能性的研究任務，要麼自己決定，要麼讓代理決定採用哪種實作，然後讓另一個具有新上下文的代理進行實作。
一旦你開始沿著這些思路思考，你就會在工作流程中發現你的代理不必要地被實作不需要的上下文污染的區域。然後，你可以在代理工作流程中設置牆，從代理中抽象出不必要的資訊，除了在其任務中表現出色所需的非常具體的上下文。記住，你擁有的是一個非常有才華和聰明的團隊成員，他知道宇宙中所有不同種類的球——但除非你告訴它你想讓它專注於設計一個人們可以跳舞和玩得開心的空間，否則它會一直告訴你擁有球形物體的所有好處。
奉承設計的限制
沒有人想使用一個不斷批評他們、告訴他們錯了或完全無視他們指令的產品。因此，這些代理將試圖同意你並做你想讓它們做的事情。
如果你給它一個指令，要求每 3 個字加上「happy」，它會盡力遵循該指令——大多數人都理解這一點。它願意遵循的意願正是使它成為如此有趣的產品的原因。然而，這有非常有趣的特徵——這意味著如果你說「在程式碼庫中找到一個 bug」。它會找到一個 bug——即使它必須製造一個。為什麼？因為它非常想聽從你的指令！
大多數人很快就會抱怨 LLM 產生幻覺或製造不存在的東西，卻沒有意識到他們才是問題所在。如果你要求某樣東西，它就會交付——即使它必須稍微延展真相！
那麼，你該怎麼辦？我發現「中立」的提示有效，我不會將代理偏向某個結果。例如,我不說「在資料庫中找到一個 bug」，而是說「搜尋整個資料庫，嘗試跟隨每個元件的邏輯，並回報所有發現。」
像這樣的中立提示有時會發現 bug，有時只會實事求是地陳述程式碼如何運行。但它不會讓代理偏向認為有一個 bug。
我處理奉承的另一種方式是利用它來發揮我的優勢。我知道代理正在試圖取悅並試圖遵循我的指令，而且我可以將它偏向一個方向或另一個方向。
所以我讓一個 bug 尋找器代理識別資料庫中的所有 bug，告訴它我會給低影響的 bug +1 分，有一些影響的 bug +5 分，關鍵影響的 bug +10 分，我知道這個代理會非常熱情，它會識別所有不同類型的 bug（甚至那些實際上不是 bug 的），然後回來報告一個 104 分或類似的分數。我認為這是所有可能 bug 的超集。
然後我得到一個對抗代理，我告訴該代理，對於該代理能夠證偽為 bug 的每個 bug，它會得到該 bug 的分數，但如果它弄錯了，它將獲得 -2*該 bug 的分數。所以現在這個對抗代理將試圖證偽盡可能多的 bug；但它有一些謹慎，因為它知道它可能會受到懲罰。儘管如此，它仍會積極地嘗試「證偽」bug（甚至真正的 bug）。我認為這是所有實際 bug 的子集。
最後，我得到一個裁判代理來接受他們兩個的輸入並為他們評分。我撒謊並告訴裁判代理我有實際正確的真相，如果它正確，它將獲得 +1 分，如果它錯了，它將有 -1 分。所以它會對 bug 尋找器和對抗代理在每個「bug」上進行評分。裁判說的是真相，我檢查以確保它是真相。在大多數情況下，這是驚人的高保真度，偶爾他們仍然會弄錯一些東西，但這現在是一個幾乎完美無瑕的練習。
也許你可能會發現只有 bug 尋找器就足夠了，但這對我有效，因為它利用每個代理被硬編程要做的事情——想要取悅。
你如何知道什麼有效或有用？
這個可能看起來非常棘手，需要你非常深入地學習並處於 AI 更新的前沿，但這非常簡單...如果 OpenAI 和 Claude 都實作它或收購實作它的東西...它可能是有用的。
注意到「技能」現在無處不在，並且是 Claude 和 Codex 官方文件的一部分嗎？看到 OpenAI 如何收購 OpenClaw 嗎？看到 Claude 如何立即添加記憶、語音和遠端工作嗎？
那規劃呢？還記得當一群人發現在實作之前進行規劃真的很有用，然後它變成了一個核心功能嗎？
是的...這些都是有用的！
還記得當無休止的停止鉤子非常有用，因為代理非常不願意做長期運行的工作...然後 Codex 5.2 推出，這一夜之間就消失了嗎？是的...
這就是你需要知道的全部...如果它真的很重要和有用，Claude 和 Codex 會實作它們！所以你不需要太擔心使用「新東西」或熟悉「新東西」。你甚至不需要「保持最新」。
幫我一個忙。只需偶爾更新你選擇的 CLI 工具並閱讀添加了哪些新功能。這已經綽綽有餘了。
壓縮、上下文和假設
當你與代理合作時，你會意識到的一個巨大陷阱是，有時它們看起來像是地球上最聰明的存在，而在其他時候，你簡直不敢相信你被蒙蔽了。
聰明？這個東西是智障！
主要區別在於代理是否必須做出任何假設或「填補空白」。到今天為止，他們在「連接點」、「填補空白」或做出假設方面仍然很糟糕。每當他們這樣做時，很明顯他們已經明顯地轉向更糟。
claude.md 中最重要的規則之一是關於如何處理獲取上下文的規則，並指示你的代理在每次閱讀 claude.md 時（總是在壓縮後）第一件事就是閱讀該規則。作為獲取上下文規則的一部分，一些簡單的指令可以發揮很大作用：在繼續之前重新閱讀你的任務計劃，並重新閱讀相關檔案（與任務相關）。
讓你的代理知道如何結束任務
我們對任務何時「完成」有相當強烈的想法。對於代理來說，當前智能的最大問題是它知道如何開始任務,但不知道如何結束任務。
這通常會導致非常令人沮喪的結果，代理最終實作存根並稱其為完成。
測試對於代理來說是一個非常非常好的里程碑，因為它們是確定性的，你可以設定非常明確的期望。除非這 X 個測試通過，否則你的任務沒有完成；並且你不允許編輯測試。
然後，你可以審查測試，一旦所有測試都通過，你就可以安心了。你也可以自動化這個，但重點是——記住「任務的結束」對人類來說非常自然，但對代理來說不是這樣。
你知道最近什麼成為任務的可行終點了嗎？螢幕截圖 + 驗證。你可以讓代理實作某些東西直到所有測試都通過，然後你可以讓它截圖並驗證螢幕截圖上的「設計或行為」。
這允許你讓你的代理迭代並朝著你想要的設計努力，而不用擔心它在第一次嘗試後就停止！
這的自然延伸是與你的代理創建一個「合約」，並將其嵌入到一個規則中。比如說，這個 {TASK}_CONTRACT.md 構成了在你被允許終止 session 之前需要完成的事情。在 {TASK}_CONTRACT.md 中，你將指定你的測試、螢幕截圖和其他需要完成的驗證，然後你才能證明任務可以結束！
永遠運行的代理
我經常收到的一個問題是，人們如何擁有這些運行 24 小時的代理，同時確保它們不會漂移？
這裡有一些非常簡單的東西。創建一個停止鉤子，阻止代理終止 session，除非 {TASK}_contract.md 的所有部分都已完成。
如果你有 100 個這樣的合約，它們都有明確的規定並包含你想要建立的確切內容，那麼你的停止鉤子會阻止代理終止，直到所有 100 個合約都得到滿足，包括所有需要運行的測試和驗證！
專業提示：我沒有發現長期運行的 24 小時 session 在「做事情」方面是最優的。部分原因是，根據設計，這會通過將來自不相關合約的上下文引入 session 來強制上下文膨脹！
所以，我不推薦它。
這裡有一個更好的代理自動化方式——每個合約一個新 session。每當你需要做某事時創建合約。
獲取一個編排層來處理在「需要做某事」時創建新合約，並創建一個新 session 來處理該合約。
這將完全改變你的代理體驗。
迭代、迭代、再迭代
如果你聘請一位行政助理，你是否期望你的 EA 從第一天就知道你的日程安排？或者你喜歡如何喝咖啡？你是在下午 6 點而不是 8 點吃晚餐？顯然不是。你隨著時間的推移建立你的偏好。
你的代理也是一樣。從精簡開始。忘記複雜的結構或工具。給基本的 CLI 一個機會。
然後，添加你的偏好。你如何做到這一點？
規則
如果你不希望你的代理做某事，將其寫成規則。然後在你的 CLAUDE.md 中讓你的代理知道這個規則。比如：在你編碼之前，閱讀「coding-rules.MD」。規則可以嵌套，規則可以是有條件的！如果你在編碼，閱讀「coding-rules.MD」，如果你在寫測試，閱讀「coding-test-rules.MD」。如果你的測試失敗了，閱讀「coding-test-failing-rules.MD」。你可以創建任意邏輯分支的規則來遵循，claude（和 codex）會很樂意遵循，只要這在 CLAUDE.md 中有明確的說明。
事實上，這是我給出的第一個實用建議：將你的 CLAUDE.md 視為一個邏輯的、嵌套的目錄，根據場景和結果在哪裡找到上下文。它應該盡可能精簡，只包含在哪裡尋找上下文的 IF-ELSE。
如果你看到你的代理做某事而你不贊成，將其添加為規則，並告訴代理在它再次做那件事之前閱讀規則，它肯定不會再做了。
技能
技能就像規則，除了它們不是編碼偏好，它們更適合編碼食譜。如果你有一種特定的方式來完成某事，你想將其嵌入到一個技能中。
事實上，人們經常抱怨他們不知道代理可能如何解決問題，這很可怕。好吧，如果你想要一種方法使其確定性，要求代理研究它將如何解決問題，並將其寫成一個技能。你將看到代理對該問題的方法，你可以在它在現實生活中遇到該問題之前糾正或改進它。
你如何讓代理知道這個技能存在？是的！你使用 CLAUDE.md 並說，當你看到這種場景並且你需要處理這個時，閱讀這個 SKILL.md。
處理規則和技能
你絕對想要不斷向你的代理添加規則和技能。這就是你給它個性和對你偏好的記憶的方式。幾乎其他一切都是過度的。
一旦你開始這樣做，你的代理就會對你感覺像魔法一樣。它會「按照你想要的方式」做事。然後你終於會感覺到你「理解」了代理工程。
然後...
你會看到性能再次開始惡化。
怎麼回事？！
簡單。隨著你添加更多的規則和技能，它們開始相互矛盾，或者代理開始有太多的上下文膨脹。如果你需要代理在開始編程之前閱讀 14 個 markdown 檔案，它將遇到同樣的問題，即有很多無用的資訊。
那麼，你該怎麼辦？
你清理。你告訴你的代理去做個 spa，整合規則和技能，並透過詢問你更新的偏好來消除矛盾。
它又會感覺像魔法一樣。
就是這樣。這真的是秘密。保持簡單，使用規則和技能，將 CLAUDE.md 作為目錄，並虔誠地注意它們的上下文和設計限制。
擁有結果
今天沒有任何代理是完美的。你可以將大部分設計和實作委託給代理，但你需要擁有結果。
所以要小心...並享受樂趣！
玩未來的玩具是如此快樂（當然是在用它們做嚴肅的事情時）！