解決 AI 程式代理人的失憶症：將程式碼儲存庫轉化為其記憶體

AI 程式代理人擅長撰寫程式碼，但卻不擅長記住上週所做的決定。在真實產品上使用 Cursor 和 Claude Code 數月後，我發現最大的成本並非糟糕的程式碼，而是重複解釋相同的架構、重複捕捉相同的錯誤，以及從差異中重建某項變更的原因。

唯一能在每個工作階段中倖存的上下文就是程式碼儲存庫，所以我開始將其視為代理人的記憶體。這就誕生了 Agent Runway，一個開源層，能將規格、決策、檢查點和執行日誌與您的程式碼並列存放。以下將說明其運作方式，以及如何在不到一分鐘內試用它。聲明：我是 Agent Runway 的作者，它採用 MIT 授權且免費。

現在，生成程式碼已不再是難事，真正的挑戰在於維護真實程式碼庫的連續性。如果您曾將程式碼代理人用於任何存活時間超過一個週末的專案，您可能遇到過以下問題：工作階段之間上下文遺失、架構決策被遺忘、相同錯誤在不同功能中重複出現、自主執行缺乏可追溯性，以及實作逐漸偏離需求。

這些問題並非模型「笨拙」，而是模型每次都從零開始，且沒有人（無論是人類或代理人）將重要事項記錄在下一個工作階段會實際讀取的地方。

通常，第一個解決方案是建立一個 CLAUDE.md、.cursor/rules 資料夾或 .github/copilot-instructions.md 檔案。這些檔案很有用，Agent Runway 也會生成它們。但規則檔案只回答一個問題：程式碼在這裡應該是什麼樣子？

它無法回答：我們正在建構什麼，以及「完成」意味著什麼？(規格) 工作應該以什麼順序進行，以及在進入下一步之前必須通過什麼？(工作流程與關卡) 我們上次學到了什麼，以及我們做了什麼決定？(記憶體) 我們停在哪裡，還有什麼未完成？(檢查點與執行日誌)

將所有這些塞進一個不斷增長的指令檔案，只會導致文件混亂。Agent Runway 使用生成的指令檔案 (AGENTS.md、CLAUDE.md、Copilot instructions) 作為輕量級的入口點，並將持久性知識存放在儲存庫中的專用資料夾內。

Agent Runway 是由產物驅動的。工作流程分為四個層次：規格 (Spec) 定義意圖和行為、工作流程 (Workflow) 透過品質關卡協調執行、規則 (Rules) 在每個步驟強制執行標準，以及記憶體 (Memory) 捕捉決策和經驗教訓供未來工作階段使用。所有這些都存在於您的儲存庫中的 .agent-runway/ 資料夾內。

以下是 Lite 初始化後（tree -a -L 2 .agent-runway）的實際目錄結構：.agent-runway、.agent-runway/config、.agent-runway/docs、.agent-runway/docs/architecture、.agent-runway/docs/business、.agent-runway/docs/contracts、.agent-runway/docs/examples、.agent-runway/docs/testing、.agent-runway/docs/tickets、.agent-runway/logs、.agent-runway/memory、.agent-runway/memory/common-failures.md、.agent-runway/memory/execution-memory.md、.agent-runway/memory/project-decisions.md、.agent-runway/memory/reasoning-memory.md、.agent-runway/memory/recurring-patterns.md、.agent-runway/memory/review-findings.md、.agent-runway/memory/testing-notes.md、.agent-runway/memory/ticket-quality-notes.md、.agent-runway/rules、.agent-runway/rules/engineering-principles.mdc、.agent-runway/rules/engineering-security.mdc、.agent-runway/rules/testing.mdc、.agent-runway/skills、.agent-runway/skills/checkpoint、.agent-runway/skills/code-review、.agent-runway/skills/council、.agent-runway/skills/express、.agent-runway/skills/learning、.agent-runway/skills/safety-check、.agent-runway/skills/start、.agent-runway/specs、.agent-runway/workflows。

這些並非被動文件。規格、票證、記憶體檔案、檢查點和執行日誌會影響代理人在不同工作階段中的推理、規劃和執行方式。由於它們只是儲存庫中的檔案，這個產物層可以在 Cursor、Claude Code 和 VS Code Copilot 之間移植，您可以提交並與團隊共享。它不會取代您的技術棧、架構或流程，而是將它們包裝起來。

您無需從第一天就採用完整的流程。Vibe/Lite 預設是一個快速、以技能為主的設定，適用於原型開發、個人工作和低儀式感的程式設計。您需要 Node.js 22 或更新版本：npx @adonai-labs/agent-runway init --preset vibe-lite --target all。

Lite 安裝了一些技能以及一套用於工程原則、安全和測試的小型規則集。沒有斜線指令、沒有代理人、沒有繁重的工作流程。

以下是 Lite 預設中的技能及其用途：@start 將模糊的工作導向正確的技能、@express 進行範圍小、儀式感最少的變更、@code-review 無需斜線指令或代理人即可審查程式碼、@checkpoint 儲存當前狀態以供暫停、恢復或交接、@learning 將持久性經驗教訓儲存到專案記憶體中、@safety-check 快速的執行/謹慎執行/停止風險檢查、@council 預覽針對想法、假設或實作的委員會審查。這些技能之間沒有固定的順序。

我使用它們的一種方式是：@express 用於實際的變更，範圍小，儀式感少。當您一天結束或交接時使用 @checkpoint。當前狀態會進入日誌，因此下一個工作階段（您的或代理人的）會從那裡恢復，而不是從猜測開始。當您發現值得記住的事情時使用 @learning：一個重複的錯誤、一個決定、一個慣例。

它會進入 .agent-runway/memory/，供未來的工作階段參考。這只是我的習慣，並非必需的順序。我最鼓勵使用 @learning 步驟。修正一次錯誤很容易，重點是下一個工作階段不會重複它。

當工作量超出 Lite 的範圍時，可以原地升級：npx agent-runway upgrade --to structured。這會保留您的記憶體、日誌、檢查點和文件，並添加完整的結構化工作流程集。或者直接從那裡開始，例如：npx @adonai-labs/agent-runway init --preset node-typescript --target all。

結構化模式增加了斜線指令、代理人、規格、票證、主導/自主工作流程、架構/反對關卡、完整規則和可選的治理檢查。

核心路徑是：/spec-creator 定義實作前的意圖和行為、/ticket-creator 將其轉化為可供開發的票證、/lead 帶有品質關卡的完整實作工作流程、/review 結構化審查：工程、安全、效能。當您需要時，還有更多入口點：/architect 用於設計決策、權衡和 ADRs、/contrarian 用於對所選方法進行對抗性審查、/validate 和 /po-eval 用於票證和產品準備度、/refactor 用於保留行為的變更，以及 /iac 用於基礎設施即程式碼。

貫穿所有這些工作流程的兩個理念是：測試驅動交付 (Test-Driven Delivery)。對於行為變更，工作流程從理解問題、定義預期行為和選擇證明變更的證據開始，然後才進行實作。當嚴格的測試優先不切實際時，它會記錄原因並使用最小可信的替代方案。

敘事交付 (Narrative Delivery)。票證、提交、PR 描述、檢查點和記憶體條目講述一個簡短的技術故事：為什麼這項工作存在、改變了什麼、什麼證據表明它是安全的，以及什麼仍然未完成。這不是冗長的文件，而是無需逆向工程差異即可恢復的意圖。

技術棧是單獨添加的，沒有自己的斜線指令。它們安裝規則、程式碼審查整合和技術棧技能（.NET、TypeScript、Node.js、React、Python、Go、Rust）：agent-runway add <stack>。

對於無人值守或低監督的執行，有 /autonomous-lead。它與 /lead 保持相同的品質標準，此外還有我不想跳過的三件事：強制執行日誌、ADR 關卡、破壞性操作前的人工批准。目標不是「讓代理人自由發揮」，而是能夠在之後回來，確切地看到它做了什麼以及為什麼。需要明確的是，Agent Runway 並非一個完全自主的 AI 工程師，它也無法取代工程判斷的必要性。

@code-review 和 /review 會產生一份整合式的 PR 風格報告：一個結論、去重複的嚴重性計數、附帶影響的發現、可直接貼上的 PR 評論、優點、技術債務說明和建議的合併關卡。您可以明確選擇模式：/review Files changed: [檔案列表] Lens: all Mode: compact。

Compact 是普通 PR 的預設模式。它會審查差異一次，並按來源標記發現：CR (標準審查)、SEC (安全)、SNR (資深架構/營運)。

/review Files changed: [檔案列表] Lens: all Mode: isolated。Isolated 模式適用於高風險 PR：身份驗證、個人身份資訊 (PII)、合規性、公共合約、資料遷移、基礎設施即程式碼 (IaC)、併發、大型跨層變更。

它會對相同的差異執行獨立、專注的 CR、SEC 和 SNR 檢查，然後進行整合和去重複。對於高影響的變更，還有一個可選的反對視角 (CTR)，這不是預設關卡。兩種模式都只審查引入的變更，並將廣泛的技術債務與行級發現分開。

如果您需要數據，agent-runway metrics 會從關卡結論和執行日誌中為您提供交付記分卡，而 agent-runway ci-check (預覽，選擇加入) 則會在 CI 中驗證治理產物，預設為諮詢模式，或者在團隊準備好後使用 --profile strict。

一些誠實的注意事項：它不是應用程式框架、SDK 抽象層，也不是架構和文件實踐的替代品。@council 和 ci-check 是預覽功能。它們可以運作，但其行為和 ci-check 的 JSON 輸出可能仍會改變。結構化是有成本的。這就是 Lite 存在的原因，也是路線圖明確指出並非每個小任務都應使用重量級治理的原因。

接下來 (v1.7)：CLI 內部模組化、更多產物層級和安裝/更新回歸測試、更好的本地測試和發布文件，以及透過真實範例穩定 @council。之後，我想嘗試「共享工作區」模型（意圖、假設、上下文、約束、信心、計畫）以提高交接和恢復品質，但這只有在真實的多工作階段任務上測試後才會進行。完整列表請參閱 ROADMAP.md。

試用它：npx @adonai-labs/agent-runway init --preset vibe-lite --target all。從小處著手。保留有效的部分。當工作需要時再升級。儲存庫：https://github.com/adonai-labs/agent-runway。

npm：https://www.npmjs.com/package/@adonai-labs/agent-runway。如果您試用它，請告訴我它在哪裡阻礙了您：哪個技能感覺儀式感太重，或者您的代理人在工作階段之間仍然忘記了哪個上下文。問題、想法和批判性回饋都非常歡迎，一個星號有助於其他人找到這個專案。