私たちは、なぜそのコードベースがそうなっているのかを覚えるAIを作った

Dev.to / 2026/4/12

💬 オピニオンDeveloper Stack & InfrastructureIdeas & Deep AnalysisTools & Practical Usage

共有:

要点

この記事では、GitHub の PR ワークフローに組み込まれた「Shadow Architect（シャドー・アーキテクト）」というAIエージェントが、チームの過去のインシデントと未文書化の「トライバル・ナレッジ（暗黙知）」を参照して、リスクの高いコード変更に警告を出す仕組みを説明している。
PR が開かれると Shadow Architect は GitHub の Webhook と REST API を使って PR の差分（diff）を取得し、変更されたパス／関数を抽出し、永続的なメモリシステム（Vectorize の「Hindsight」）に問い合わせたうえで、Groq 搭載の LLM により対象を絞った自然言語の PR レビューコメントを生成する。
単純な RAG 手法とは異なり、状況（disposition）に基づく振る舞い（例：認証／決済に対しては懐疑的に見る）や、LLM が応答する前に評価される実行可能な「ハード指令」、さらに各警告を特定のインシデント／指令に結び付ける明示的な “Based_On” 引用を用いる点が特徴。
システムには段階的な低下（graceful degradation）が組み込まれており、Hindsight API が利用できない場合は、CI/CD パイプラインを止めないためにローカルの関連度スコアリング・アルゴリズムへフォールバックする。
デモでは、JWT の変更（`expiresIn` パラメータの削除）を CRITICAL としてフラグ付けし、実際の過去のインシデントを引用したうえで、より安全な refresh-token 実装を推奨する例が示される。
全体の目的は、静的リンタや汎用的なコードレビューでは検出しにくい、過去の本番障害を新人が繰り返さないようにすることにある。

どのエンジニアリングチームにも部族的な知識（tribal knowledge）があります。つまり、シニアエンジニアだけが知っている、書かれていないルールです。
"その関数には触るな。"
"このリトライ制限には理由がある。"
"2023年にまったく同じリファクタを試したら、本番が4時間止まった。"
そうした知識が文書化されていないと、ジュニア開発者は、すでに爆発してしまった地雷の真っ直中に突っ込んでしまいます。標準的なリンターでは、過去に起きたようなミスは検知できません。コードレビューは助けになりますが、レビュー担当者がその歴史を覚えている場合に限ります。
私たちは、この問題を解決するためにShadow Architectを作りました。これは、デジタル部族史（Digital Tribal Historian）として振る舞うAIエージェントです。GitHubのワークフロー内に常駐し、PRが危険なコードに触れた瞬間に、チームの実際のインシデント履歴に基づいて警告を発します。
仕組み
開発者がPull Requestを開いた瞬間：

GitHubがShadow ArchitectサーバーにWebhookを送信
サーバーがGitHub REST APIを使ってPRの差分（diff）全体を取得
変更されたファイルパスと関数名が差分から抽出される
これらは、Hindsight（Vectorizeによる永続メモリシステム）にセマンティッククエリとして送られる
Hindsightは、メモリから最も関連性の高いインシデント、アーキテクチャ上の意思決定、ホットフィックスを思い出す
Groq搭載のLLMが、具体的な過去の文脈を引用して自然言語の警告を生成する
その警告は、GitHubのPR Review Commentとして直接投稿される

基本的なRAGラッパーと何が違うのか
多くのAIコードレビューツールは単純な検索（retrieval）です。同様のテキストを見つけてプロンプトに注入するだけ。Shadow Architectは、Hindsightのエージェント的な推論を使ってそれをさらに進めます。
ディスポジション（気質）に基づくレビュー。エージェントには定義されたパーソナリティがあります――認証や決済のようなクリティカルな経路では、懐疑的でかつ逐語的です。見た目が無害に見える変数名のリネームに流されません。
強制可能な指示。例えば「認証メカニズムを決して削除したり弱めたりするな」といった厳格なルールは、LLMが何かを見る前に、Hindsightによって評価される指示として注入されます。これはソフトなプロンプト指示ではなく、強制される制約です。
メモリの引用。すべての警告には、発火した原因となった「正確なインシデントと指示」を結び付けるBased_Onの引用が含まれます。これは説明可能なAIであってブラックボックスではありません。
自然なフォールバック。Hindsight APIが利用できない場合、スコア付きのローカルな関連性アルゴリズムに切り替えます。CI/CDパイプラインがブロックされることはありません。
それを現実のものにする瞬間
デモでは、ジュニア開発者がPRを開き、jwt.sign()呼び出しからexpiresInパラメータを削除します。ログインタイムアウトの不具合を直すための、何の変哲もない変更に見えます。
Shadow Architectは15秒以内に応答します：

リスクレベル：CRITICAL
2024年2月に、このまったく同じ変更によってJWTセッションがRedisキャッシュに2GB/時のペースで蓄積しました。本番は4時間停止しました（Incident #41）。ログインタイムアウトは、期限（expiry）ではなく、壊れたリフレッシュトークンのフローが原因です。有効期限の削除は、はるかに深刻な問題を引き起こします。
より安全な手順：PR #88からリフレッシュトークンのパターンを実装すること。

Shadow Architectがなければ、これはそのままコードレビューを通過していたでしょう。修正案は妥当に見えました。今日のチームの誰も、2024年のその場にいません。
テックスタック
VectorizeによるHindsight Cloudが、すべての永続メモリを扱います――retainを使ってインシデントを保存し、recallを使って意味的に思い出し、reflectを使ってエージェント的な推論を実行します。Groqはopenai/gpt-oss-120bによる高速なLLM推論を提供します。GitHubのWebhookがすべてのPRでエージェントを起動します。Node.jsとExpressがサーバーを処理します。単純なHTMLダッシュボードにより、エージェントの推論がチームに見えるようになります。

自分で試してみる
GitHub： https://github.com/Rishikanth-S007/Hindsight-Prj
READMEにはセットアップの詳細手順があります。合成インシデント12件をあなた自身のHindsightメモリバンクに投入し、20分以内にライブのGitHubリポジトリに対してテストできます。
「同じやり方で本番を再び壊さないでください。」