Claude在Grepathy项目中做出无人认可的决定

背景

在AI辅助编程日益普及的今天，编码智能体（coding agent）被广泛用于自动生成代码、实现功能。然而，这些智能体在开发过程中会自主做出许多小决策——例如选择某个库、采用某种实现方式——但开发者通常并未明确批准这些决策。当后续代码审查（PR）时，有人问“为什么这样做？”往往无人能答。答案可能埋藏在本地聊天记录中，而像 Claude Code 这样的工具默认30天后就删除这些记录。这就导致一个关键问题：代理的决策痕迹丢失，团队无法追溯“为什么”。

核心内容

Grepathy 是一个开源 CLI 工具（MIT 协议），专门解决上述问题。它从 Claude Code 的本地会话记录中读取代理在编码过程中做出的决策，提取成结构化的 markdown 文件，并与代码一同提交到仓库中。这样，代码仓库自身就能回答“为什么”，供审查者、队友以及未来的智能体查阅。

工作流程

1. 初始化：npx grepathy init 安装钩子，并可选回填尚存的会话记录。
2. 正常使用 Claude Code 开发，让代理按需提交代码。
3. 当执行 git push 时，Grepathy 自动触发，读取最新会话记录，提取决策，生成 .ai/why/<branch>.md 文件，并展示给开发者审查。
4. 开发者可以编辑或删除条目，Grepathy 会永久尊重这些修改。
5. 未来代理在编辑代码前，会自动通过两种方式接触这些“为什么”信息：
   • CLAUDE.md 指针：每次会话自动加载，指引代理读取 .ai/why/ 目录。
   • PreToolUse 钩子：在代理编辑文件前，如果该文件匹配某个条目的 Touches: 全局模式，则自动将相关条目注入到代理的上下文中。

真实案例

在一个合同项目中，代理自行决定在 Clerk 中预创建访客用户。该决策不在任何计划中，CTO 在 PR 中看到后询问原因，开发者完全不知。如果使用了 Grepathy，仓库中会记录：

### 访客身份在 Clerk 中预创建
状态: agent-initiated — 未在计划或提示中请求
涉及文件: `lib/clerk/*`, `db/schema/guests.ts`
代理推断此方法是为了简化下游身份验证检查。
未讨论明确理由。
风险: 访客用户偏离正常注册路径。
审阅者注意: 确认是否应将访客建模为普通用户。

运行 grep -rn "agent-initiated" .ai/why/ 即可列出所有代理未经任何人批准就做出的决策。

隐私与安全

• 会话记录永远留在本地，不会离开机器。
• 共享的唯一内容是 markdown 摘要，且摘要生成器遵循严格规则：从不引用用户消息、不描述用户的困惑或来回对话、不包含业务或金钱细节、剥离密钥。
• 在提示词之后有两个确定性检查：秘密/财务扫描器，以及“每个条目必须指向真实代码”的规则。
• 开发者可在推送前审查文件，编辑或删除后 Grepathy 永久尊重。

评估

团队进行了盲法、预注册的评估，与诚实基线对比，并发布了完整报告（包括工具失败的部分）。测试表明：

• 有 why 文件的代理能正确回答代码中未显式表达的知识（如“考虑过 CDN 但拒绝了”或“代理自行决策无人批准”）。
• 没有 why 文件的代理则会编造看似合理但错误的答案。
• 但 Grepathy 无法阻止代理重构掉重要代码，也不能普遍提升智能体的能力。如果答案可从代码本身读出，代理不需要 Grepathy。

技术细节

• 零运行时依赖，纯 TypeScript，测试套件封闭（无需 Claude 或 API 密钥，Git 在临时仓库中运行），需 Node >=20 和 Git。
• 每个分支一个文件：.ai/why/<branch>.md。
• 多个代理和工作树均可兼容。
• 目前仅支持从 Claude Code 写入，但任何工具都可读取 why 文件。计划下一步适配 Codex。

关键要点

• 自动捕获决策：Grepathy 从会话记录中事后提取决策，不要求代理在任务中主动记录（因为测试发现代理不会这么做）。
• 仓库内持久化：决策作为 markdown 文件提交到 Git，随代码永久留存，不依赖本地聊天记录（默认30天删除）。
• 双向触发：未来代理通过 CLAUDE.md 指针和 PreToolUse 钩子自动获取相关决策，无需手动查阅。
• 隐私优先：仅共享无敏感信息的摘要，本地会话从不出站。
• 可审查可编辑：每次推送前都会展示生成的 why 文件，允许开发者修改或删除，改动被永久尊重。
• 评估透明：公开了盲法评估报告，包括失败案例。
• 不替代任务跟踪：与 Beads 等任务跟踪工具互补——那些工具记录“接下来做什么”，Grepathy 记录“为什么已经做了”。
• 目前仅写端适配 Claude Code，但读端兼容任何工具；未来将适配 Codex。

意义与影响

Grepathy 解决了AI辅助编程中一个关键但常被忽视的问题：决策可追溯性。随着编码智能体越来越多地介入代码生成，它们做出的“隐式决策”会导致代码库中出现无法解释的遗留问题。传统版本控制只记录“改了哪些代码”，而不记录“为什么这样改”。Grepathy 通过将推理记录纳入版本控制，补上了这一缺失的环节。

• 对团队协作：审查者、维护者、甚至未来的智能体都能直接理解代码背后的理由，减少沟通成本和误解。
• 对AI治理：提供了一种轻量级、无侵入的方式，使代理的行为可审计、可回溯。这有助于建立对AI编码的信任，尤其是在企业环境中。
• 对开源生态：作为 MIT 协议工具，任何人都可以集成或扩展。其设计理念（事后提取、隐私安全、仓库内持久化）可能成为AI辅助编程工作流的标准实践。
• 局限性明确：作者坦诚指出工具不提升智能体能力，也不阻止不合理重构，但恰恰在“记录不在代码中的知识”这一点上价值显著。

Grepathy 不是让代理更聪明，而是让代理的“为什么”永远留在仓库里。它代表了一种将AI决策痕迹基础设施化的思路，可能在未来成为每个AI增强开发工作流的标配组件。