AI Agent 一次能修改十幾個檔案,但提交後通常只剩下 commit message 和 diff。這些內容可以說明「改了什麼」,卻難以回答:為什麼選擇這個方案?模型在哪裡沒有把握?如果現在重新執行,是否會得到相同結果?
Git 記錄的是程式碼事實,並未保存完整的決策脈絡。ADRs for AI 試圖補上這段空白:把模型的決策依據寫進 Git,並以 ORRCF 要求 Agent 主動揭露疑慮。
真正的缺口不在程式碼,而在決策紀錄
假設要求 Agent 把同步任務改為非同步佇列。
最後的 diff 可能只有幾行:新增 producer、consumer 與 retry policy,再刪除原本的阻塞呼叫。
Code review 可以檢查 race condition、訊息遺失與重複消費等問題,但審查者看不到完整的決策鏈:
- 為什麼不用 Redis Streams,而是 Kafka?
- 為什麼保留現有資料庫作為 source of truth?
- 是否評估過任務延遲與維運複雜度?
- 出現哪些現象,就代表這次選擇有誤?
Agent 參與後,這些問題更容易被壓縮成一句「已依最佳實務優化」。
一般 ADR 原本就是為了處理這類問題而設計。它是一種輕量的決策紀錄。Nygard 的經典形式通常包含背景、選項、決定與後果。團隊藉此留下選擇特定技術路徑的原因。即使後來的人沒有參與討論,也能理解程式碼為何演變成現在的樣貌。
ADRs for AI 做了兩項調整。
第一,將 ADR 擴展至人機協作情境。AI Agent 可以是決策提案的作者,也能讀取後續的決策紀錄。
第二,使用 Git 保存這些 Architectural Deliberation Records。紀錄不再隨著聊天視窗消失,而是進入版本控制,與程式碼一起審查、提交及回滾。
只留在聊天視窗裡的自然語言解釋,至多算是一份日誌。放進 Git 後,它才可能成為可供協作的工程脈絡。
ORRCF:讓模型先交出五份作業
ADRs for AI 使用 ORRCF 組織模型提出的決策提案:
- Options:有哪些可行選項,包括維持現狀。
- Recommendation:模型推薦哪一個選項。
- Rationale:為什麼推薦此選項,以及放棄了哪些方案。
- Confidence:模型對推薦結果的信心程度。
- Falsifier:哪些證據能證明這項推薦並不成立。
這看起來像一套解釋模板,但目的不只是讓輸出更完整。
ORRCF 要求模型揭露疑慮,並將建議交由人類批准或覆寫。模型不能提交程式碼後,只附上一段禮貌性的總結;它必須先提出可供審查的決策提案。
例如,非同步佇列任務可能寫成以下形式:
## Options
1. 保留同步呼叫
2. 使用 Redis Streams
3. 使用 Kafka
## Recommendation
使用 Redis Streams。
## Rationale
目前吞吐量不需要 Kafka 的分區與維運成本。
Redis Streams 已提供 consumer group、確認機制和訊息保留。
## Confidence
中高。主要不確定性是現有重試邏輯遷移後的冪等性。
## Falsifier
如果壓測中 consumer lag 持續增長,或重投導致重複處理,
則目前方案不成立,應重新評估 Kafka。
人類可以批准提案,也可以覆寫推薦結果;覆寫的原因同樣可以寫入 ADR。下一次 Agent 不只讀取程式碼,也能讀取團隊過去做過的取捨。
這能形成一套可持續的 AI 程式開發腳手架。它保存本次建議,也保存團隊對建議作出的修改。後續任務可以將已批准、已拒絕及附帶條件的方案當作脈絡。
這並不等於要求每個 commit 都寫一篇長文。比較適合的做法,是為高風險、高成本,或難以單靠 diff 理解的變更,加上一次決策檢查。
ADR 放進 Git,才能成為協作脈絡
許多 Agent 工具已經擅長檢索程式碼:先找出相關檔案,再讀取 symbol definition、搜尋 caller,接著修改實作。
ADR 補上的是另一層檢索:哪些選擇已經討論過,哪些邊界條件已經踩過坑。
假設第一次遷移資料庫時,團隊因流量偏低而選擇 SQLite。隨著流量變化,團隊又決定改用 PostgregreSQL。ADR 應該保留兩次紀錄:
- 第一次為什麼選擇 SQLite。
- 第二次為什麼遷移至 PostgregreSQL。
- 哪些假設已經失效。
- 哪些限制仍然存在。
如果後續 Agent 只讀取目前程式碼,可能把舊方案誤認為偶然留下的實作。讀取 ADR 後,它至少有机会看到當時面臨的約束。
Git 還帶來三項協作特性。
第一,決策與實作可以一起審查。審查者能對照程式碼,檢查模型是否兑现承諾。
第二,決策可以回滾。程式碼改錯了,可以回滾 diff;架構選擇錯了,也可以透過新的 ADR 明確宣告替代方案,而不是抹除歷史。
第三,責任邊界更加清楚。人類批准或覆寫的是一份明確的提案,而不是在模糊的「模型已經處理完」中承擔結果。
不過,ADR 不應取代測試、code review 或架構討論。它只是讓這些活動多了一個共同參照。
反直覺:更多紀錄未必帶來更多監督
將結構化格式接入 Agent 流程,很容易得到一個漂亮的結果:每次任務都多出 Options、Rationale、Confidence 與 Falsifier。
但這也可能只是形式主義。
Confidence 不可靠。模型寫下「0.8」,不代表結果有 80% 的正確機率。訓練資料中的措辭習慣、prompt 模板,甚至任務難度,都可能改變這個數字。它最多只是一個需要解釋的訊號。
Falsifier 同樣不等於測試。
模型寫下「如果 consumer lag 持續增長,就代表方案失敗」,不代表它已經撰寫壓測,也不代表團隊知道增長門檻為何。一個永遠不會被執行的證偽條件,只是把不確定性改寫成更正式的文字。
因此,ADR 的品質必須回到工程證據:
- Rationale 是否引用真實約束,而不是籠統的最佳實務?
- Recommendation 是否與實際程式碼變更一致?
- Falsifier 是否對應可執行的測試或監控指標?
- 人類覆寫模型後,是否記錄了覆寫理由?
- 後續 Agent 是否確實讀取並使用歷史 ADR?
還有一個更隱蔽的問題:紀錄可能製造監督幻覺。
文件越完整,審查者越容易覺得決策已經妥善處理。但如果 ORRCF 只是任務結束前自動產生的模板,它可能只是在複述程式碼,而不是解釋程式碼。
真正有用的 ADR,應該能讓人察覺不一致之處。
例如,模型推薦 Redis,理由是避免資料庫鎖競爭;實際程式碼卻在 transaction 中更新狀態表。審查者一眼就能看出提案與實作之間出現偏差。
這比「模型很自信地表示已完成任務」更有價值。
因此,ADRs for AI 更適合被視為 audit interface,而非 quality assurance interface。它讓 AI 建議更容易受到檢查,但不會自動讓建議變得更正確。
原始專案說明來自 ADRs for AI 專案網站及其 Hacker News 討論。專案展示了 Architectural Deliberation Records、ORRCF 五項格式、人類批准或覆寫機制,以及以 Git 為基礎的可持續 AI 程式開發腳手架。
編輯觀察
ADRs for AI 的價值不在於「記錄 AI」,而是將模型建議轉換成可稽核的工程物件。程式碼回答系統目前是什麼,ADR 回答它為何變成這樣。當兩者進入同一份 Git 歷史,後來的工程師與 Agent 才有機會繼承決策脈絡。
我的判斷是,ORRCF 的短期價值主要在審查介面,而不在自治能力。它未必讓 Agent 變得更聰明,卻能讓偏差更早暴露:推薦與程式碼不一致、證偽條件沒有對應測試,或人類覆寫後未留下理由。如果團隊只把它視為自動會議紀錄,它很快就會變成文件負擔。
這與過去的 AI 程式開發工具不同。早期工具主要負責補全程式碼與測試;現在 Agent 已開始進行跨檔案修改,決策影響範圍更大。現有素材未提供 production 環境成效、專案規模或錯誤率變化,成熟度仍有待驗證。真正該測的不是 ADR 寫得多漂亮,而是半年後,新 Agent 能否少走一次舊路。