会话即提交信息

一位开发者接手了一个代码库。git blame显示一次提交修改了47个文件。提交信息写着：”refactor auth module。”提交作者显示为一位人类开发者。而实际作者是一个运行了90分钟的编码Agent，它读取了200个文件，评估了三种替代方案，因特定原因否决了其中两种，最终生成了一组涉及所有认证端点的变更集。那90分钟的设计决策、被否决的替代方案以及讨论过的边界情况全部消失了。Git保留了什么发生了变化。没有任何东西保留了为什么。

我的认知债务文章将Agent输出速度与开发者理解速度之间的差距命名为”认知债务”——一种随着每次未审查的提交而不断累积的负债。¹ Memento项目（获得了100个HN积分和124条评论）提出了下一个问题：如果会话包含推理过程，那么会话是否应该成为提交的一部分？²

概要

Git记录了什么发生了变化。Agent会话记录了为什么。当Agent编写代码时，会话记录才是真正的设计文档，而每个丢弃记录的工作流都丢弃了溯源信息。Memento（一个开源Git扩展）将AI会话记录作为git notes附加到提交上，创建了从提交到推理过程的溯源链。Claude Code的新LSP集成增加了结构化的代码理解能力，使会话记录更加精确：跳转到定义取代了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分钟的会话会生成数兆字节的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。”十四个英文单词。会话元数据包含2300个单词的结构化溯源信息。提交信息与会话上下文之间的差距是两个数量级。

溯源的成本

会话溯源并非免费的。三项成本制约着采用。

存储。 一个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上周二为什么做了这个选择？”两个系统相辅相成：可观测性实时发现问题，溯源在事后解释问题。

来源