Hunch——你的AI助手遵循的Git原生决策图

Hunch是一款面向开发者的工具，其核心理念是让代码库记住“为什么”。传统AI助手每次会话都从零开始，重读代码、重新猜测意图，甚至可能“修复”你上个月故意设计的内容，因为决策逻辑分散在PR、Slack和开发者的大脑中，而不是代码仓库里。Hunch通过构建一个Git原生的决策图，将每个提交和测试事件转化为结构化的决策、Bug和约束，从而形成持久化的知识图谱。

问题所在

每个AI会话都从零开始，模型重读代码、重新猜测意图，然后愉快地“修复”你上个月故意做的事情——因为推理存在于PR、Slack和人们的头脑中，而不是仓库里。典型助手记忆是当前代码的临时RAG，范围仅限于当前会话，价值保持平坦。代码库只记录最终状态，从不记录被拒绝的替代方案或必须遵守的不变量。没有记忆，代理会重新发现你已经修复的Bug，并撤销防止它的变通方案。

工作原理

Hunch的工作流程分为索引、学习和接地三个步骤。索引阶段使用确定性方法映射代码结构（函数、文件、组件之间的关系），无需LLM参与，快速且完全在本地运行。学习阶段将每个提交转化为决策，将失败的测试标记为Bug并关联可能原因，将重复或严重的Bug提升为约束——即AI必须遵守的规则。接地阶段通过MCP服务器、自动维护的CLAUDE.md文件和钩子命令，将带有来源、置信度和证据的上下文反馈给AI助手。

推理图

一个Bug衍生一个决策，一个决策衍生一个约束。这些链接让AI代理能够用证据回答“为什么”以及“什么不能打破”——每个节点都附加到其组件、符号和提交。例如，Bug 009：重置后可用的泄漏令牌（无状态JWT无法在服务端吊销，被auth.revocation.spec.ts捕获），导致决策017：将会话存储在Redis而非仅JWT（会话移至服务端，JWT仅携带不透明ID，替代方案被拒绝，后果被记录，提交a1b2c3d作为证据），进而产生约束004：吊销必须在服务端进行（绝不单独依赖JWT过期来注销，范围限定在src/auth/**，在该范围内的任何编辑前都进行检查）。

内部功能

Hunch提供了四类能力：记忆、守护、检索和团队共享。

记忆——图所持有的内容

• 来源追踪：每条记录都有来源、置信度和证据。自动捕获的猜测保持建议性，只有你确认的才能用于阻断。
• Git同步：图作为纯文件存在于代码旁，通过推送/拉取同步，合并没有冲突标记。
• 原子性与持久性：中断写入不会损坏图，损坏状态拒绝覆盖好数据。
• 时间旅行：可以查询任意提交时的图，历史永不被删除。
• 私有记忆：开源代码而不开源推理，敏感决策存在于你控制的私有仓库中。
• 决策接地：文档可能漂移，但图不会，助手在编辑前被告知当前决策。
• 组件Wiki与规范台账：从图渲染Wiki，对每个文档进行分级：接地、过时或未验证。过时文档会得到一份由Wiki管理的副本，更新到当前决策。

守护——阻止什么

• 回归守护：阻止重新添加过去决策故意移除的代码。
• 否决（决策）守护：阻止重新引入被拒绝的方法，即使该方法从未存在于代码中。
• 冗余守护：检测已存在的重复代码。
• CI约束守护：每个PR都会收到评论，指出其触及的不变量和决策，并在确认的阻断规则被破坏时失败。
• 因果合并裁决：每个差异一个裁决（BLOCK/WARN/PASS），引用背后的决策和防止的Bug。
• 意图一致性：检查代码是否仍然遵守记录的设计（分层、必经路径、依赖方向）。
• 永远不犯第二次：纠正代理一次，它就成为所有未来会话中每个助手都必须遵守的规则。

检索——如何获取“为什么”

• MCP原生双向：助手询问文件为何如此构建、更改会破坏什么，以及Bug是否以前发生过，并记录新决策。
• 免grep结构：一次调用返回仓库映射、目录内容、文件大纲或符号的定义位置及其调用者。
• 图增强检索：相比纯搜索，召回率提升41.7%（@10），无需嵌入。
• 操作手册记忆：证明的重复任务步骤，按需返回。
• 脆弱性报告：仓库中最危险的代码排名，附有真实Bug历史。
• 深度综合：多次独立阅读变更，调和成一条笔记，仅在一致处可信。

团队——共享与评估

• 离线工作，零SaaS：没有SaaS，没有API密钥，学习计入你已经支付的编码订阅。
• 共享团队记忆：一个存储跨分支、工作区、团队成员和代理共享，新克隆自动连接。
• 多候选裁决：五个代理解决方案按架构适合度排序。

为何不同

典型代理内存是当前代码的临时RAG，时间范围仅限当前会话，索引语法和文件嵌入，无写入路径，价值平坦。而Hunch的核心数据模型是决策、Bug和约束的精选图，时间范围是整个代码库的生命周期，索引的是意图、因果和不变量，具有一流的写入路径（在提交和测试时学习），价值像飞轮一样复合。它消除的不是“AI看不到足够代码”，而是“AI重复过去错误/破坏设计”。

开始使用

安装非常简单：Node 22.13+，运行npm install -g @davesheffer/hunch即可。然后在一个仓库中运行hunch init，它会索引仓库、安装钩子和合并驱动，并为Claude Code、Cursor、VS Code、Windsurf、Codex和Antigravity等编辑器配置MCP和规则。通过hunch backfill --since 90d可以回溯最近90天的历史，快速填充决策图。之后，在任何这些编辑器中，你可以直接问“为什么这个会话模块是这样构建的？”——答案会从记忆中返回，并附上提交作为证据。

Hunch的价值随时间累积：运行时间越长，决策图越丰富，AI助手的表现越智能。它的设计理念是让代码库记住“为什么”，从而避免重复的错误。