AI 编码 Agent 悄悄在 PR 里加了你没批准的代码？Grepathy 把每个决策都写进 Git 历史

CTO 在 PR 里发现了一行自己从未批准过的逻辑。开发者说「我不知道——Claude 自己决定的」。这不是个例，而是 AI 编码 Agent 时代最隐蔽的风险之一。

问题：你的 Agent 做了你没同意的决定

想象一下这个场景：你让 Claude Code 实现一个功能，它认真地写了代码、提交了 PR。CTO 审查时突然问——「为什么这里要预创建 Guest 用户？谁批准的？」

你愣住了。你根本没有要求过这个功能。Claude 在开发过程中自己推断出这个方案，觉得「这样更合理」，就直接写进去了。而代码审查时，几百行的 diff 里，这个「合理的小改动」就这样滑了过去。

这就是 Grepathy 要解决的问题——让 Agent 写的代码变得可审查。

为什么传统代码审查不够了？

在 AI 编码 Agent 的工作流中，Agent 每走一步都会做大量微小决策：

• 「这个 API 参数用默认值还是显式传值？」
• 「用户验证放在前端还是后端？」
• 「用枚举还是字符串常量？」

这些决策 Agent 自己就做了，开发者可能在旁边刷手机等结果。等到 PR 提交时，Agent 已经累积了几十个「你没批准」的决策。更糟的是——Claude Code 默认 30 天后就会删除会话记录。到那时想查当初为什么这么做，已经无处可查了。

Grepathy：把 Agent 的「为什么」写进代码仓库

Grepathy 是一个 MIT 开源的 TypeScript CLI 工具，它的思路很直接：读取 Agent 的本地会话记录，提取其中的关键决策，以 Markdown 文件的形式提交到代码仓库中。

npx grepathy init

运行这个命令后，Grepathy 会在你的项目中安装 Git hooks。之后你正常使用 Claude Code 开发，当你 git push 时，Grepathy 自动：

1. 读取当前分支的 Claude Code 会话记录
2. 提取其中的决策点（Agent 独立做出的选择、非计划内的改动、有风险的设计取舍）
3. 生成 .ai/why/.md 文件，提交到仓库

一个真实案例

Grepathy 的作者在自己的外包项目上亲身经历过这个问题。Agent 自作主张在 Clerk 中预创建了 Guest 用户，CTO 在 PR 中发现了这个改动并质问作者。作者自己也不知道——因为这不是他要求的功能。

如果有 Grepathy，仓库里就会有这样的记录：

### Guest identities are pre-created in Clerk
Status: agent-initiated — not requested in plan or prompts
Touches: `lib/clerk/*`, `db/schema/guests.ts`

The agent inferred this approach to simplify downstream auth checks.
No explicit rationale was discussed.

Risk: guest users diverge from the normal signup path.
Reviewer attention: confirm whether guests should be modeled as normal users.

CTO 看到这条记录就会知道：这不是开发者的主观决定，而是 Agent 的自主行为——需要额外关注。

搜索所有未批准的 Agent 决策

grep -rn "agent-initiated" .ai/why/

这条命令会列出仓库中所有 Agent 自行做出的、未经人类批准的决策。对于安全审计和代码审查来说，这相当于一个 「Agent 行为日志」，让审查者知道哪些代码需要特别关注。

Grepathy 的核心设计

基于 Git Hook 的被动式工作流

作者团队尝试过让 Agent 在运行过程中主动记录决策——结果发现 Agent 根本不会认真执行。于是他们换了个思路：事后从会话记录中提取。

claude        # 正常工作，让 Agent 边开发边提交
git push      # Grepathy 在 push 时提取决策并生成 why 文件

这种设计的好处：

• 零侵入：Agent 不需要改变行为，正常开发即可
• 不阻塞工作流：Grepathy 从不阻止 push，从不影响暂存区
• 多 Agent 友好：多个分支的决策文件互不干扰

双层触发机制

Grepathy 不仅把决策写在文件里，还确保未来的 Agent 在修改相关代码时能看到这些历史决策：

1. CLAUDE.md 指针：Grepathy 在项目中添加一个 CLAUDE.md 文件，指向 .ai/why/ 目录。Claude Code 每次启动时自动加载这个文件，知道去哪里查找历史决策。

1. PreToolUse Hook：当 Agent 即将修改某个文件时，如果该文件有相关的历史决策记录，Grepathy 会自动将匹配的条目注入到 Agent 的上下文中。Agent 会在修改代码前「看到」当初为什么这样做。

这意味着：即使原来的开发者离职了，新的 Agent 也能知道当初设计的来龙去脉。

隐私优先

Grepathy 的会话记录提取全在本地完成，你的会话记录永远不会离开你的机器。上传到仓库的唯一内容是 Markdown 格式的决策摘要，并且自动经过两道安全检查：

• 敏感信息扫描仪：自动检测并剔除密钥、财务信息
• 代码引用验证：确保每个条目都指向真实的代码文件

你还可以在 push 前手动编辑或删除任意条目，Grepathy 会永久尊重你的修改。

实操：在你的项目中使用 Grepathy

npx grepathy init

npx grepathy status

npx grepathy context src/auth/login.ts

npx grepathy sync

所有命令列表：

与同类工具的对比

Grepathy 并非市场上唯一的 Agent 决策记录工具，但它的定位很独特：

这两类工具完全可以互补使用——一个规划未来，一个记录过去。

局限性（作者坦诚列出的）

Grepathy 的作者在公开发布的测评报告中诚实地列出了工具的局限性：

• 不会阻止 Agent 重构掉重要代码：Grepathy 是记录工具，不是安全护栏
• 不提升 Agent 的通用能力：如果答案可以从代码中直接读取，Agent 不需要 Grepathy
• 目前仅支持 Claude Code：读取决策需要 Claude Code 的会话记录格式，Codex 适配器正在开发中

但任何人都可以读取 .ai/why/ 中的 Markdown 文件，因为格式是纯文本。

总结

在 AI 编码 Agent 越来越自主的今天，Grepathy 解决了「代码审查」和「决策透明度」之间的鸿沟。它不像安全工具那样阻止 Agent 做什么，而是提供了一个简单但有效的机制：让每一个 Agent 做出的决策，都在代码仓库中留下可追溯的记录。

对于团队来说，这意味着：

• 审查者可以快速定位「Agent 自主决定」的代码段
• 未来的开发者能理解当初为什么这样设计
• 安全审计有了 Agent 行为的完整日志

在 CTO 问「这是谁批准的」之前，让 Grepathy 帮你回答。

相关链接

• Grepathy GitHub 仓库
• Grepathy 决策文件格式文档
• 架构与 Git 行为详解
• 公开发布的盲测评估报告