工作階段就是提交訊息

一位開發者接手了一個程式碼庫。git blame 顯示一次提交中有47個檔案被更動。提交訊息寫著：「refactor auth module。」提交作者列為一位人類開發者。實際的作者是一個運行了90分鐘的編碼 agent，它讀取了200個檔案，評估了三種替代方案，因為具體原因否決了其中兩種，最終產生了一組觸及每個驗證端點的變更集。那90分鐘的設計決策、被否決的替代方案和討論過的邊界情況全部消失了。Git 保存了什麼改變了。但沒有任何東西保存為什麼改變。

我的認知負債文章將 agent 輸出速度與開發者理解速度之間的差距命名為「認知負債」——一種隨著每次未審查的提交而不斷累積的負債。¹ Memento 專案在 HN 上獲得了100點和124則留言，它提出了下一個問題：如果工作階段包含了推理過程，那麼工作階段是否應該成為提交的一部分？²

重點摘要

Git 記錄了什麼改變了。Agent 工作階段記錄了為什麼改變。當 agent 撰寫程式碼時，工作階段記錄才是真正的設計文件，而每個丟棄記錄的工作流程都丟棄了來源追溯。Memento（一個開源 git 擴充套件）將 AI 工作階段記錄作為 git notes 附加到提交上，建立從提交到推理過程的來源追溯鏈。Claude Code 新的 LSP 整合增加了結構化的程式碼理解能力，使工作階段記錄更加精確：go-to-definition 取代了 grep，型別簽名取代了猜測。以下內容包括：來源追溯的缺口、工作階段中繼資料的四個層次、Memento 的建構方式、LSP 如何改變工作階段資料的品質，以及您今天就能實施的最低來源追溯實踐。

來源追溯的缺口

Git 追蹤每次變更的五件事：誰做的、何時做的、哪些檔案改變了、差異內容，以及提交訊息。對於人類撰寫的程式碼，提交訊息彌合了差異與意圖之間的鴻溝。好的訊息解釋了為什麼這個變更存在。壞的訊息（「fix stuff」）讓審查者只能從程式碼中重建意圖。

Agent 撰寫的程式碼有著不同的來源追溯結構。意圖不存在於開發者的腦海中。意圖存在於工作階段中：啟動任務的提示詞、agent 讀取的檔案、它評估的替代方案、它呼叫的工具，以及它在報告完成時引用的證據。一行提交訊息來概括90分鐘的 agent 推理，丟棄了99.9%的決策脈絡。

這種損失不是理論性的。我的編排系統會產生工作階段狀態檔案（jiro.state.json、jiro.progress.json），記錄每個故事的完成狀態、審查者的裁決和證據閘門的結果。³ 當審查者問「為什麼 agent 使用指數退避而不是熔斷器？」時，工作階段狀態檔案包含答案：agent 評估了兩種模式，發現上游服務回傳帶有 Retry-After 標頭的可重試 503 錯誤，因此選擇了指數退避來遵循標頭值。提交訊息寫著「refactor: standardize retry patterns。」工作階段狀態說明了為什麼。

沒有工作階段來源追溯，對 agent 撰寫的變更進行程式碼審查就變成了考古學。審查者閱讀差異、逆向推導推理過程，然後形成關於為什麼這個變更存在的理論。這個理論可能是錯的。Agent 的實際推理過程是可用的，記錄在工作階段記錄中。業界標準工作流程（提交、推送、審查差異）把推理過程丟掉了。

這個問題在 agent 組合時會倍增。我的編排系統會衍生專門的子 agent 進行程式碼審查：正確性審查者、安全性審查者、慣例審查者。⁵ 每個子 agent 運行自己的工作階段，讀取自己的檔案，形成自己的結論。父 agent 彙總裁決。最終的提交訊息寫著「3 reviewers: approve。」三個各自包含具體發現、邊界情況分析和批准理由的審查工作階段——存在於提交從未引用的獨立記錄中。每一層 agent 委派都增加了另一層不可見的推理。

來源追溯問題與三個既有的失敗模式相關。捏造防火牆識別了當沒有輸出閘門時，agent 如何發布未經驗證的聲明。⁶ 工作階段來源追溯本可以更早發現捏造問題：工作階段記錄顯示 agent 發明了一種沒有人類審查過的 token 計數方法。隱形 agent 記錄了在沒有明確監測機制的情況下，agent 的行動如何不受監控。⁷ 工作階段來源追溯就是可見性堆疊產生的稽核軌跡。NIST 公開意見建議對 agent 行動進行標準化的稽核日誌記錄。⁹ 以 git notes 儲存工作階段記錄是該建議的一種實作方式。

我的品質系統中的證據閘門要求 agent 為每個品質標準引用具體證據：命名模式、解釋替代方案、列出邊界情況、貼上測試輸出。¹⁰ 證據閘門迫使 agent 產生推理和驗證層的資料，否則這些資料不會存在。沒有閘門，agent 只報告「完成」，工作階段只包含流程資料（工具呼叫）。有了閘門，工作階段包含審查者可以對照程式碼驗證的明確理由。

Git 本身無法區分一個代表90分鐘深思熟慮推理的47檔案提交和一個代表 agent 在沒有審查的情況下不受約束運行90分鐘的47檔案提交。Git 文件將 notes 描述為「可以附加到物件上而不改變物件本身的額外資訊。」⁸ 工作階段記錄完全符合這個定義：關於提交來源追溯的額外資訊，不會改變提交雜湊值、差異或歷史記錄。

Memento 的提問

Memento 專案用一個 git 擴充套件回答了來源追溯的缺口。² 這個工具擷取 AI 編碼工作階段記錄，並將它們作為 git notes 附加到提交上，儲存在 refs/notes/commits 和 refs/notes/memento-full-audit 中。

工作流程：git memento init 設定儲存庫。git memento commit <session-id> 取代 git commit，自動從設定的 AI 供應商（Codex 或 Claude Code）擷取工作階段記錄，並將其作為結構化中繼資料儲存在提交上。

124則 HN 留言的討論浮現了四種立場：

立場一：工作階段是必要的脈絡。 Agent 工作階段包含提交訊息無法承載的推理過程。將工作階段附加到提交上保存了來源追溯鏈。審查者可以追溯任何一行程式碼，通過提交、工作階段，回到原始提示詞。

立場二：工作階段是雜訊。 一個90分鐘的工作階段記錄是數千行對話。大部分與最終變更集無關。附加完整記錄把訊號埋沒在雜訊中，使審查變得更困難而非更容易。

立場三：摘要而非記錄。 工作階段應該被濃縮為結構化摘要：任務描述、考慮的替代方案、決策理由、引用的證據。摘要保留了來源追溯而沒有雜訊。Memento 產生以使用者和助理回合標記的 Markdown 摘要。

立場四：隱私和安全疑慮。 工作階段記錄可能包含 API 金鑰、內部 URL、來自其他檔案的專有程式碼，或開發者不希望出現在永久 git 記錄中的對話內容。工作階段在附加前需要清理。

四種立場都有道理。工作階段的來源追溯價值是不可否認的。雜訊問題是真實的。隱私疑慮是結構性的。Memento 處理了立場一和三（記錄儲存與 Markdown 轉換）以及立場四（將記錄視為不可信資料來產生摘要）。立場二仍是一個開放的設計問題：多少工作階段脈絡才夠？

一個互補的工具對同一問題採取了不同的方法。claude-replay 將 Claude Code 工作階段記錄轉換為類似影片的回放，讓審查者逐步觀看 agent 的工作過程，而非閱讀靜態記錄。¹² Memento 回答的是「我們應該儲存什麼？」，而 claude-replay 回答的是「我們應該如何審查？」這兩個工具處理來源追溯工作流程的不同部分：Memento 保存資料（儲存），claude-replay 使資料可理解（呈現）。兩個專案在同一個月內獨立出現的事實驗證了這個論點：實踐者感受到了來源追溯的缺口，正在建構工具來填補它。

來源追溯的四個層次

Agent 工作階段中繼資料組織為四個層次，每個層次回答關於變更的不同問題。

每個層次都有成本。儲存完整的意圖層（原始提示詞）很便宜：一個文字欄位。儲存完整的流程層（每個工具呼叫）對於90分鐘的工作階段會產生數 MB 的 JSON。儲存推理層要求 agent 明確敘述其決策過程，而大多數 agent 預設不會這樣做。儲存驗證層需要與測試執行器和審查系統整合。

我的編排系統透過不同機制擷取所有四個層次。³ 使擷取成為可能的 hook 基礎設施跨越15種事件類型共84個 hook。⁵ 意圖：UserPromptSubmit hook 記錄原始提示詞。流程：PostToolUse hook 記錄每個工具呼叫和結果。推理：證據閘門要求 agent 為每個品質標準引用具體理由。驗證：jiro.state.json 檔案記錄測試輸出和審查者裁決。

Hook 還追蹤 agent 調用了哪些技能以及調用順序。¹¹ 由 /review 技能後接 /test 技能產生的提交，與單一非結構化工作階段產生的提交有著不同的來源追溯特徵。技能序列揭示了工作流程模式：先審查再測試，還是先測試再審查？順序對理解品質保證的覆蓋範圍很重要。資料分散在多個狀態檔案中。問題在於這些資料都沒有附加到 git 提交上。

LSP 作為來源追溯的橋樑

Claude Code 新的 LSP（Language Server Protocol）整合改變了工作階段來源追溯資料的品質。⁴

在 LSP 之前，Claude Code 透過 grep 和檔案讀取來瀏覽程式碼庫。當 agent 需要找到一個函式的定義時，它會在所有檔案中搜尋函式名稱。搜尋回傳模糊的結果：多個匹配、部分匹配、在註解中包含函式名稱的測試檔案。Agent 選擇最可能的匹配。工作階段記錄記載：「搜尋 authenticate_user，在 auth.py、test_auth.py 和 middleware.py 中找到。」來源追溯資料包含搜尋過程、歧義性，以及 agent 的最佳猜測。

有了 LSP，agent 呼叫 goToDefinition 並在約50毫秒內收到確切的檔案和行號。⁴ 工作階段記錄記載：「authenticate_user 定義在 auth.py:47。」來源追溯資料是精確的、無歧義的、且可由機器驗證的。閱讀工作階段的審查者可以確信 agent 找到了正確的定義，而非不同模組中名稱相似的函式。

這種改善在整個工作階段中會不斷累積。一個使用 grep 讀取200個檔案的 agent 會產生充滿「搜尋 X，找到潛在匹配 A、B、C，選擇了 A」的工作階段資料。一個使用 LSP 讀取200個檔案的 agent 會產生「X 定義在 file:line，引用在 file:line、file:line、file:line」的工作階段資料。基於 LSP 的工作階段是 agent 程式碼理解的精確地圖。基於 grep 的工作階段是模糊的近似值。

LSP 增加了六種改善來源追溯品質的能力：

來源追溯的意涵：來自啟用 LSP 的 agent 的工作階段記錄作為設計文件更有價值，因為每個程式碼導航步驟都是可驗證的。審查者可以確認 agent 對程式碼庫的理解是正確的，而不僅僅是看似合理的。

code-review-graph 專案將結構化理解推進了一步：一個跨工作階段持續存在的程式碼圖譜，降低了每次調用時重新理解程式碼庫的 token 成本。¹³ LSP 在工作階段內提供結構化查詢，而持久化圖譜在工作階段之間提供結構化記憶。對於來源追溯，這意味著未來的 agent 將攜帶的不僅是工作階段記錄，還有產生決策的結構化理解。圖譜成為另一層來源追溯資料：不僅是「agent 在 auth.py:47 找到了 authenticate_user」，而是「agent 的程式碼圖譜已經包含了呼叫階層，所以它跳過了導航直接進入實作。」Agent 的先驗知識影響其決策，而這些先驗知識屬於來源追溯鏈的一部分。

工作階段中繼資料的實際樣貌

來自我的編排系統的真實範例。故事：「為驗證端點新增速率限制。」

意圖層（來自 UserPromptSubmit hook）：

Prompt: "Implement rate limiting on POST /auth/login.
  Use sliding window, 5 attempts per minute per IP.
  Return 429 with Retry-After header."

流程層（來自 PostToolUse hook）：

Files read: 14 (auth/, middleware/, tests/)
Files written: 3 (rate_limiter.py, auth.py, test_rate_limit.py)
Bash commands: 7 (pytest x3, pip install x1, curl x3)
Duration: 23 minutes
Token usage: 87K input, 24K output

推理層（來自證據閘門）：

Pattern: Sliding window (token bucket rejected
  because per-IP granularity requires separate
  counters, sliding window handles this natively)
Edge cases: IPv6 normalization, proxy headers
  (X-Forwarded-For validated against trusted proxy list)

驗證層（來自 jiro.state.json）：

Tests: 12 passed, 0 failed, 0 skipped
Reviewers: correctness (approve), security (approve),
  conventions (approve with note: add docstring to
  rate_limiter.py:RateLimiter class)
Evidence gate: 6/6 criteria met

同一變更的提交訊息：「feat: add rate limiting to auth endpoint。」十四個字。工作階段中繼資料包含2,300字的結構化來源追溯。提交訊息與工作階段脈絡之間的差距是兩個數量級。

來源追溯的成本

工作階段來源追溯不是免費的。三項成本制約了採用。

儲存空間。 一個90分鐘的 agent 工作階段產生500KB至2MB的原始記錄。以每天10次提交計算，完整記錄每天為 git 儲存庫增加5至20MB。Git notes 將資料儲存在主要歷史記錄之外（預設不影響 git clone 的大小），但 refs/notes/memento-full-audit 中的稽核軌跡會持續累積。Memento 的 Markdown 轉換將原始大小縮減約60%。²

隱私。 工作階段記錄包含 agent 所見的一切：檔案內容、環境變數、API 回應、帶有堆疊追蹤的錯誤訊息。附加到公開儲存庫的記錄會暴露內部實作細節。Memento 將記錄視為不可信資料，並指示摘要模型忽略嵌入的指令，但完整稽核軌跡中的原始記錄需要存取控制。²

訊雜比。 一個90分鐘的工作階段中，agent 讀取200個檔案但只修改12個，包含188個檔案的無關流程資料。挑戰在於區分導航（雜訊）和決策點（訊號）。四層模型有所幫助：意圖和推理是高訊號，流程是混合的，驗證是高訊號。一個預設儲存意圖和推理、按需儲存流程的來源追溯系統，在不失去關鍵決策脈絡的情況下降低了雜訊。

您今天就能實施的做法

四項不需要新工具的最低來源追溯實踐：

1. 結構化提交訊息。 將「refactor auth module」替換為結構化格式：

feat: add rate limiting to auth endpoint

Task: sliding window rate limiter, 5/min per IP
Alternatives: token bucket (rejected: per-IP overhead)
Evidence: 12 tests pass, 3 reviewers approve
Session: 23 min, 87K tokens, 14 files read

這種格式是四個來源追溯層的手動版本。訊息回答了意圖（任務）、推理（替代方案）和驗證（證據），只用了四行。不需要任何工具。

2. 將工作階段記錄與提交一起保存。 在 agent 工作階段結束後，將記錄匯出為儲存庫中的檔案（例如 .sessions/2026-03-02-auth-rate-limit.md）。對於公開儲存庫，將該檔案加入 .gitignore；對於內部儲存庫則直接提交。記錄無需 git notes 基礎設施即可供審查使用。

3. 標記 agent 撰寫的提交。 使用 git trailer 標記 agent 產生的提交：

Agent: Claude Code (Opus)
Session-Duration: 23m
Files-Read: 14
Files-Written: 3

Trailer 建立了一個機器可解析的 agent 參與記錄。git log --grep="Agent: Claude Code" 列出所有 agent 撰寫的提交。這些中繼資料使未來的工具能夠重建來源追溯鏈，而無需回溯標註。

4. 對 agent 提交要求證據閘門。 在 agent 提交之前，要求它回答六個問題：程式碼遵循什麼模式？有哪些更簡單的替代方案？處理了哪些邊界情況？測試是否通過？您檢查了哪些檔案是否有迴歸？變更是否解決了實際問題？¹⁰ 答案構成推理和驗證層。沒有閘門，agent 只報告「完成」，工作階段只包含流程資料。有了閘門，每次提交都會產生結構化的來源追溯，作為品質保證的副產品。

證據閘門的實踐與更廣泛的來源追溯論點相連。一個必須在提交前證明其決策合理性的 agent，會比不受約束運行的 agent 產生更高品質的工作階段中繼資料。閘門將來源追溯從被動的副產品（記錄發生了什麼）轉變為主動的品質訊號（要求 agent 解釋發生了什麼以及為什麼）。

關鍵要點

給工程主管： 每個帶有一行訊息的 agent 撰寫提交都丟棄了設計文件。工作階段記錄包含推理過程。請決定這些推理對您團隊的程式碼審查、新人入職和事件回應工作流程是否有價值。如果答案是肯定的，至少實施結構化提交訊息。

給開發者： 當您接手 agent 撰寫的程式碼時，提交訊息告訴您什麼改變了。工作階段記錄（如果保存了的話）告訴您為什麼改變。在您團隊的 agent 工作流程中推動工作階段來源追溯。Memento 專案提供了 git 原生的方法。結構化提交訊息提供了零基礎設施的起點。

給工具建構者： LSP 整合透過將模糊的基於 grep 的導航替換為精確、可驗證的程式碼引用，使工作階段記錄更有價值。對 agent 程式碼理解的每一次改進都提升了工作階段產生的來源追溯資料品質。建構保留四個來源追溯層次的匯出格式。

常見問題

什麼是工作階段來源追溯？ 工作階段來源追溯是 AI agent 在編碼工作階段中推理過程的記錄：原始任務、讀取的檔案、評估的替代方案、做出的決策和產生的證據。工作階段記錄擷取了提交訊息和差異無法承載的「為什麼」。

什麼是 Memento？ Memento 是一個開源 git 擴充套件，擷取 AI 編碼工作階段記錄並將其作為 git notes 附加到提交上。該工具支援 Codex 和 Claude Code，產生 Markdown 摘要，並提供 GitHub Action 以進行 PR 整合。²

LSP 如何改善 agent 工作階段？ Language Server Protocol 為 agent 提供結構化的程式碼理解：確切的定義、帶型別的引用、呼叫階層和即時診斷。來自啟用 LSP 的 agent 的工作階段記錄包含精確、可驗證的程式碼導航資料，而非模糊的 grep 結果。⁴

工作階段記錄是否應該提交到 git？ 答案取決於儲存庫的隱私要求。對於內部儲存庫，提交記錄保存了來源追溯。對於公開儲存庫，git notes（預設在 clone 時不會傳輸）或帶有提交引用的獨立儲存是更安全的方法。²

工作階段來源追溯需要多少儲存空間？ 典型的30分鐘 agent 工作階段產生200KB至800KB的原始記錄。Git notes 將資料儲存在主要物件資料庫之外，預設保持 git clone 大小不變。Memento 的 Markdown 轉換將原始大小縮減約60%。對於每天運行10至20個 agent 工作階段的團隊，預計每天產生2至10MB的來源追溯資料，相當於每個工作階段一張中等解析度的截圖。²

Agent 可觀測性與工作階段來源追溯之間是什麼關係？ Agent 可觀測性即時監控 agent 的行為：資源消耗、政策遵循、執行時期行為。⁷ 工作階段來源追溯記錄 agent 事後決定了什麼以及為什麼。可觀測性回答「agent 現在的行為是否正確？」來源追溯回答「為什麼 agent 上週二做了這個選擇？」這兩個系統互為補充：可觀測性即時捕捉問題，來源追溯在事後解釋問題。

參考資料