Session 就是 Commit Message

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

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

重點摘要

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

來源記錄的缺口

Git 追蹤每次變更的五項資訊：誰做的、何時做的、哪些檔案改變了、差異內容，以及一條 commit 訊息。對於人類撰寫的程式碼，commit 訊息橋接了差異與意圖之間的鴻溝。一條好的訊息解釋了變更存在的原因。一條糟糕的訊息（「fix stuff」）則讓審查者不得不從程式碼中重建意圖。

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

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

沒有 session 來源記錄，對 agent 撰寫的變更進行程式碼審查就變成了考古學。審查者閱讀差異、逆向推導推理過程，並形成一個關於變更存在原因的理論。這個理論可能是錯的。Agent 的實際推理是可得的，記錄在 session 逐字稿中。業界標準工作流程（commit、push、審查差異）將推理過程拋棄了。

這個問題在 agent 組合使用時成倍增加。我的編排系統為程式碼審查產生專門的子 agent：正確性審查者、安全性審查者、慣例審查者。⁵ 每個子 agent 執行自己的 session，讀取自己的檔案，形成自己的結論。父 agent 彙總裁定。最終的 commit 訊息寫著「3 reviewers: approve。」三個個別的審查 session——每個都包含具體發現、邊界情況分析和核准理由——存在於 commit 從未引用的個別逐字稿中。每增加一層 agent 委派，就多一層不可見的推理。

來源記錄問題與三個既有的失敗模式相關聯。捏造防火牆一文指出了當不存在輸出閘門時，agent 如何發布未經驗證的聲明。⁶ Session 來源記錄本可以更早發現捏造問題：session 逐字稿顯示 agent 發明了一套沒有任何人審查過的 token 計算方法。不可見的 agent 一文記錄了在沒有明確檢測手段的情況下，agent 行動如何不受監控。⁷ Session 來源記錄就是可見性堆疊產生的稽核軌跡。NIST 公開意見書建議對 agent 行動進行標準化稽核記錄。⁹ 以 git notes 儲存 session 逐字稿是該建議的一種實作方式。

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

僅憑 Git 無法區分一個代表 90 分鐘仔細推理的 47 檔案 commit，與一個代表 agent 在無審查情況下不受約束地執行 90 分鐘的 47 檔案 commit。Git 文件將 notes 描述為「可以附加到物件上而不改變物件本身的額外資訊。」⁸ Session 逐字稿完全符合這個定義：關於 commit 來源的額外資訊，不會改變 commit 雜湊值、差異內容或歷史記錄。

Memento 之問

Memento 專案透過一個 git 擴充套件回答了來源記錄的缺口問題。² 該工具擷取 AI 程式碼 session 逐字稿，並以 git notes 的形式附加到 commit 上，儲存在 refs/notes/commits 和 refs/notes/memento-full-audit 中。

工作流程：git memento init 設定儲存庫。git memento commit <session-id> 取代 git commit，自動從設定的 AI 提供者（Codex 或 Claude Code）擷取 session 逐字稿，並將其作為結構化元資料儲存在 commit 上。

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

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

立場二：Session 是雜訊。 一個 90 分鐘的 session 逐字稿是數千行對話。其中大部分與最終變更集無關。附加完整逐字稿會將信號埋沒在雜訊中，使審查更困難而非更容易。

立場三：要摘要，不要逐字稿。 Session 應該被提煉為結構化摘要：任務描述、考慮過的替代方案、決策理由、引用的證據。摘要在不帶雜訊的情況下保留了來源記錄。Memento 產生標記了使用者和助手輪次的 Markdown 摘要。

立場四：隱私與安全疑慮。 Session 逐字稿可能包含 API 金鑰、內部 URL、來自其他檔案的專有程式碼，或開發者不希望留存在永久 git 記錄中的對話內容。Session 在附加前需要進行淨化處理。

四種立場都有道理。Session 的來源價值不可否認。雜訊問題確實存在。隱私疑慮是結構性的。Memento 解決了立場一和三（逐字稿儲存加 Markdown 轉換）以及立場四（將逐字稿視為不受信任的資料進行摘要生成）。立場二仍是一個開放的設計問題：多少 session 脈絡才足夠？

來源記錄的四個層次

Agent session 元資料組織為四個層次，每個層次回答關於變更的不同問題。

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

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

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

LSP 作為來源記錄的橋樑

Claude Code 全新的 LSP（Language Server Protocol）整合改變了 session 來源資料的品質。⁴

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

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

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

LSP 增加了六項提升來源記錄品質的能力：

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

Session 元資料的實際樣貌

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

意圖層（來自 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

同一變更的 commit 訊息：「feat: add rate limiting to auth endpoint。」十四個字。Session 元資料包含 2,300 字的結構化來源記錄。Commit 訊息與 session 脈絡之間的落差是兩個數量級。

來源記錄的成本

Session 來源記錄並非免費。三項成本制約了採用。

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

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

信噪比。 一個 90 分鐘的 session 中，agent 讀取 200 個檔案但只修改 12 個，包含 188 個檔案的無關流程資料。挑戰在於區分導覽（雜訊）和決策點（信號）。四層模型有所幫助：意圖和推理是高信號，流程是混合的，驗證是高信號。一個預設儲存意圖和推理層、按需儲存流程層的來源記錄系統，可以在不遺失關鍵決策脈絡的情況下減少雜訊。

您今天就能實施的做法

四個不需要新工具的最低來源記錄實踐：

1. 結構化 commit 訊息。 將「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. 將 session 逐字稿與 commit 一起保存。 在 agent session 結束後，將逐字稿匯出為儲存庫中的檔案（例如 .sessions/2026-03-02-auth-rate-limit.md）。對公開儲存庫將該檔案加入 .gitignore，或對內部儲存庫直接 commit。逐字稿無需 git notes 基礎設施即可供審查。

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

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

Trailer 建立了機器可解析的 agent 參與記錄。git log --grep="Agent: Claude Code" 列出所有 agent 撰寫的 commit。元資料使未來的工具能夠在不需要回溯標注的情況下重建來源鏈。

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

證據閘門實踐與更廣泛的來源記錄論述相連。一個在 commit 前必須為其決策提供合理化解釋的 agent，會產生比不受約束的 agent 更高品質的 session 元資料。閘門將來源記錄從被動的副產品（記錄發生了什麼）轉變為主動的品質信號（要求 agent 解釋發生了什麼以及為什麼）。

重點結論

致工程主管： 每一個僅有單行訊息的 agent 撰寫 commit 都丟棄了設計文件。Session 逐字稿包含了推理過程。請判斷該推理對您團隊的程式碼審查、新人上手和事件回應工作流是否有價值。如果答案是肯定的，至少實施結構化 commit 訊息。

致開發者： 當您接手 agent 撰寫的程式碼時，commit 訊息告訴您什麼改變了。Session 逐字稿（若有保留）告訴您為什麼改變。請在您團隊的 agent 工作流中推動 session 來源記錄。Memento 專案提供了一種 git 原生的方法。結構化 commit 訊息提供了零基礎設施的起點。

致工具開發者： LSP 整合透過以精確、可驗證的程式碼引用取代模糊的 grep 導覽，使 session 逐字稿更有價值。Agent 程式碼理解能力的每一項改進都提升了 session 產生的來源資料品質。請構建保留四個來源記錄層次的匯出格式。

常見問題

什麼是 session 來源記錄？ Session 來源記錄是 AI agent 在程式碼 session 期間推理過程的記錄：原始任務、讀取的檔案、評估的替代方案、做出的決策，以及產生的證據。Session 逐字稿捕捉了 commit 訊息和差異無法承載的「為什麼」。

什麼是 Memento？ Memento 是一個開源 git 擴充套件，擷取 AI 程式碼 session 逐字稿並以 git notes 形式附加到 commit 上。該工具支援 Codex 和 Claude Code，產生 Markdown 摘要，並提供 GitHub Action 用於 PR 整合。²

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

Session 逐字稿是否應該提交到 git？ 答案取決於儲存庫的隱私要求。對於內部儲存庫，提交逐字稿可保留來源記錄。對於公開儲存庫，git notes（預設在 clone 時不會傳輸）或帶有 commit 引用的獨立儲存是更安全的做法。²

Session 來源記錄需要多少儲存空間？ 一個典型的 30 分鐘 agent session 產生 200KB-800KB 的原始逐字稿。Git notes 將資料儲存在主物件資料庫之外，預設不影響 git clone 大小。Memento 的 Markdown 轉換可將原始大小減少約 60%。對於每天執行 10-20 個 agent session 的團隊，預計每天產生 2-10MB 的來源資料，相當於每個 session 一張中等解析度的截圖。²

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

參考來源