Hunch – AIアシスタントが従うGitネイティブな決定グラフ

Hunchは、開発者がAIアシスタントにコードの「なぜ」を理解させるためのツールです。従来のセッションベースのメモリとは異なり、Hunchは各コミットやテストイベントを構造化された決定、バグ、制約に変換し、持続的に進化する知識グラフを構築します。

問題点

すべてのAIセッションはゼロから始まります。モデルはコードを再読み取り、意図を再推測し、先月あなたが意図的に行ったことを喜んで「修正」します——なぜなら、その推論はPR、Slack、人々の頭の中にあり、リポジトリにはないからです。典型的なアシスタントメモリは現在のコードに対する一時的なRAGであり、範囲はこのセッションのみ、価値は平坦です。コードベースは最終状態のみを記録し、却下された代替案や決して破ってはならない不変条件は記録しません。メモリがないため、エージェントはすでに修正したバグを再発見し、それを防ぐ回避策を元に戻します。

動作の仕組み

Hunchのパイプラインには、インデックス、学習、グラウンディングの3つの層があります。インデックスフェーズでは、LLMを使わずに関数、ファイル、コンポーネント間の接続をマッピングし、変更の波及効果を把握します。学習フェーズでは、各コミットを構造化された決定に変換し、失敗したテストをバグとその原因に関連付け、繰り返し発生する重大なバグを制約（AIが尊重すべきルール）に昇格させます。グラウンディングフェーズでは、MCPサーバー、自動管理されるCLAUDE.md、スラッシュコマンドを介して、出典、信頼度、証拠を含む回答を提供します。

推論グラフ

バグが決定を生み、決定が制約を生みます。これらのリンクにより、エージェントは証拠をもって「なぜ」と「何を壊してはいけないか」に答えることができます——各ノードはコンポーネント、シンボル、コミットに接続されています。例：バグ009（リセット後に使用可能な漏洩トークン、サーバーサイドで無効化できないステートレスJWT）→決定017（セッションをRedisに保存、JWTのみではない）→制約004（失効はサーバーサイドで行うこと）。

内部機能

Hunchは次の4つのカテゴリの機能を提供します：メモリ、ガード、検索、チーム。

メモリ——グラフが保持するもの

• 来歴証明：すべてのレコードに出典、信頼度、証拠があります。自動取得された推測は助言的に留まり、確認されたものだけがブロックに使用されます。
• Git同期：グラフはコードの横にあるプレーンファイルとして存在し、プッシュ/プルで同期、マージはクリーン。
• アトミックで永続的：中断された書き込みがグラフを破損することはなく、破損状態は良いデータを上書きしません。
• タイムトラベルメモリ：任意のコミット時点のグラフを照会でき、歴史は閉じており削除されません。
• プライベートメモリ：コードをオープンソースにしても推論はオープンにしません。機密の決定はあなたが管理する別のプライベートリポジトリに存在します。
• 決定グラウンディング：ドキュメントは漂流しますが、グラフは漂流しません。アシスタントは編集前に現在の決定（却下されたものを含む）を知らされます。
• コンポーネントWikiと仕様元帳：グラフからWikiがレンダリングされ、リポジトリのドキュメントは接地済み、古い、未検証のいずれかに分類されます。古いドキュメントはWiki管理のコピーで現在の決定に更新されます。

ガード——何を防ぐか

• 回帰ガード：過去の決定で意図的に削除されたコードの再追加を防ぎます。
• 拒否（決定）ガード：却下されたアプローチの再導入を、たとえコードに存在しなくても、領収書付きで防ぎます。
• 冗長性ガード：すでに存在するヘルパーの重複を検出します。
• CI制約ガード：すべてのPRにコメントで触れる不変条件と決定を命名し、確認されたブロッキングルールが実際に破られた場合にチェックを失敗させます。
• 因果マージ判定：各差分にBLOCK/WARN/PASSの判定を下し、各ルールを背後にある決定と防止するバグに引用します。
• 意図適合性：コードが記録された設計（レイヤリング、到達必須、依存方向）を尊重しているかをチェックします。
• 二度なし：エージェントを一度訂正すると、将来のすべてのセッションですべてのアシスタントに強制されるルールになります。

検索——「なぜ」を取り出す方法

• MCPネイティブ双方向：アシスタントはファイルがなぜそのように構成されているか、変更すると何が壊れるか、バグが以前発生したかを尋ね、新しい決定を記録します。
• grep不要の構造：1回の呼び出しでリポジトリマップ、ディレクトリの内容、ファイルの概要、シンボルの定義場所と呼び出し元を返します。
• グラフ拡張検索：プレーン検索よりも再現率@10で41.7ポイント向上、埋め込み不要。
• ランブックメモリ：繰り返しタスクの実証済み手順をオンデマンドで返します。
• 脆弱性レポート：リポジトリ内の最も危険なコードを、実際のバグ履歴とともにランク付けします。
• 深い合成：変更の複数の独立した読み取りを調和させ、一致する場合のみ信頼される1つのノートにします。

チーム——共有と評価

• オフライン動作、SaaS不要：SaaSもAPIキーも不要、学習はすでに支払っているコーディングサブスクリプションに請求されます。
• 共有チームメモリ：1つのストアがブランチ、ワークツリー、チームメンバー、エージェント間で共有され、新しいクローンは初期化時に自動接続されます。
• 複数候補判定：5つのエージェント生成ソリューションをアーキテクチャ適合性でランク付けします。

なぜ違うのか

典型的なエージェントメモリとHunchの比較：コアデータモデルは一時的なRAG vs 決定・バグ・制約の厳選グラフ、時間軸はセッション vs コードベースの生涯、インデックス対象は構文+ファイルの埋め込み vs 意図・因果・不変条件、書き込みパスはなし vs 第一級（コミット・テスト時に学習）、時間経過による価値は平坦 vs 複合（フライホイール）。Hunchが取り除くのは「AIが十分なコードを見られない」ではなく、「AIが過去のミスを繰り返す/設計を壊す」です。

始め方

インストールは簡単：npm install -g @davesheffer/hunchを実行し、リポジトリでhunch initを実行してインデックス作成、フックとマージドライバのインストール、MCP設定とルールの書き込みを行います。hunch backfill --since 90dで過去90日間の履歴を再生してメモリをシードできます。その後、Claude Code、Cursor、VS Codeなどのエディタで「なぜこのセッションモジュールはこのように構築されているのか？」と尋ねるだけで、コミットを証拠としてメモリから回答が返ってきます。

Hunchの価値は時間とともに蓄積されます。長く使うほどグラフは豊かになり、AIアシスタントはより賢くなります。コードベースに「なぜ」を記憶させ、同じ過ちを繰り返さないようにしましょう。