AIがコード構造を解説！Cursor用プラグイン「how」

「とりあえず、ソース読んでおいて」

新しいプロジェクトにアサインされた初日、我々はこの呪文のような言葉を何度聞いてきただろうか。ドキュメントは3年前から更新が止まり、当時のアーキテクトはとうに退職している。残されたのは、複雑に絡み合った数十のマイクロサービスと、謎の命名規則に支配された巨大なコードベースだけだ。

CursorのようなAIエディタの登場で、個々の関数やクラスの挙動を読み解く苦労は激減した。しかし「メッセージ送信のフロー全体はどう動いているのか？」「認証ミドルウェアはどこで権限をチェックしているのか？」といったマクロなアーキテクチャの質問に対しては、AIは時に迷子になる。局所的なコードの断片を拾い集め、ピントのずれた要約を返してくることも少なくない。

AIに欠けているのは、コードを読む力ではなく「システム全体を探索し、構造として理解する」アプローチそのものなのだ。

この課題に対して、非常にエレガントな解を提示しているのが、Cursor向けのプラグインとして公開された「poteto/how」である。

読むべきは行ではなく「意図」である

このリポジトリは、Cursorに /how というカスタムスキルを追加する。使い方はシンプルで、チャットに「/how 認証サービスはどう構成されている？」と打ち込むだけだ。

特筆すべきは、その出力の質にある。単なるファイルの羅列や関数の要約ではない。「Overview（概要）」「Key Concepts（核となる概念）」「How It Works（仕組み）」「Where Things Live（ファイルの場所）」「Gotchas（ハマりどころ・注意点）」という、シニアエンジニアが新メンバーをオンボーディングする際に語るような、極めて実用的で構造化された解説を出力する。

なぜこのような高品質な回答が可能なのか。その秘密は、背後で動くエージェントのオーケストレーションにある。

探索と統合のエージェント設計

poteto/how は、ユーザーの質問を受け取ると、その複雑さを自動的に判定する。単一のファイルで完結するような単純な質問であれば、そのまま1つのAIエージェントに処理させる。しかし、複数のファイルやサービスにまたがる複雑な質問だと判断した瞬間、動きが変わるのだ。

質問を2〜4つの「探索アングル」に分解し、並列でサブエージェント（Explorer）を走らせる。彼らはコードベースのあちこちを並行して飛び回り、それぞれの視点で調査を行う。そして最後に、合成エージェント（Synthesis）がそれらの調査結果を統合し、一つの首尾一貫したアーキテクチャ解説として出力する。

これは、昨今のLLMアプリケーション設計において「Fan-out / Fan-in（分散と集約）」と呼ばれる強力なパターンだ。コンテキストウィンドウの限界や、単一モデルの注意力低下（Lost in the middle）を防ぐための最適解の一つであり、それをCursorのプラグインという形でシームレスに実装している点が素晴らしい。

批評家たちをコードベースに放つ

もう一つ、我々のようなベテランの関心を惹きつけるのが「Critique（批評）」モードの存在だ。

質問からこのモードがトリガーされると、アーキテクチャの解説を行った後、複数の異なるモデルを用いた「批評家（Critic）」が独立してスポーンする。彼らは、あらかじめ用意された評価基準（Rubric）に基づき、解説された設計に対して「ここはスケールしない」「この依存関係は危険だ」といった容赦ないレビューを行う。

設計の妥当性を検証するには、多角的な視点が不可欠だ。人間同士でホワイトボードを囲んで行う「設計の壁打ち」を、エディタの中で複数のAIモデルを相手に行える体験は、一度味わうと手放せなくなる。

Cursorの「スキル」機能は、特定のフォーマットにプロンプトやルーティングのルールを記述することで、エディタの振る舞いを拡張できる仕組みだ。poteto/how の中身を覗いてみると、エージェントに役割を与えるための緻密なプロンプト設計が SKILL.md や references/ 配下のマークダウンファイル群として美しく整理されており、LLMを活用したツール開発の生きた教材としても非常に価値が高い。

AIはついに、単にコードを書くアシスタントから、複雑なシステムを読み解き、議論を交わす「アーキテクトの相棒」へと進化しつつある。巨大なレガシーコードに立ち向かう前に、ぜひこのスキルをインストールしておきたい。

参考リポジトリ: poteto/how

Photo by Daniil Komov on Unsplash