NEAT

NEAT

エージェントは調査も推論も得意ではありません。適切なコンテキストがあれば、コードの作成は非常に得意です。NEAT が調査と推論を行うことで、エージェントはコーディングに専念できます。

その最もわかりやすい例が、インシデントカードです。システムで何かが失敗すると、NEAT はそれに対する作業指示書をまとめます。障害が発生した場所（ランタイムが記録していれば、ファイルと行番号まで）、原因の連鎖、修正が影響するすべての範囲、そのコードに適用されるアーキテクチャルール、コードと本番環境の食い違いを示します。各主張には、NEAT がその情報をどのように把握したか（ソースから読み取った、ランタイムで確認した、または推論した）が付記されます。推測は一切ありません。NEAT がたどれない原因は、空欄のままにし、埋めることはありません。エージェントはファイルを grep して原因を推測するのではなく、カードを読んで修正を作成します。

NEAT は、稼働中のシステムのライブグラフを維持することで調査を行います。グラフ内の実体はノードです。ファイルとその中のシンボル、サービス、データベース、ルート、設定、インフラストラクチャがノードとなり、それぞれのエッジには NEAT がその情報をどのように把握したかが記録されます。ソースからEXTRACTED（抽出）、OpenTelemetry からOBSERVED（観測）、ギャップをつなぐステッチャーによるINFERRED（推論）、ランタイムによるエッジの確認が止まったときのSTALE（古い状態）、ステージングされた提案を示すFRONTIER（フロンティア）です。フュージョンは、コードで宣言された内容と本番環境での動作を、同じ粒度（ファイルと行、シンボル、ホスト、データベーステーブル）で結び付けます。答えはその結び付きから得られます。グラフは決定論的で、製品内のどこでも LLM を呼び出しません。モデルではなく、メソッドです。

NEAT のすべての機能は、上に重ねたレイヤーではなく、単一のグラフを読み取るものです。根本原因、影響範囲、依存関係、コードと本番環境の差異、ポリシーチェック、インシデント、評価が含まれます。自分のタスクに取り組むときは、grep の前にまずグラフに問い合わせてください。インシデント、差異、根本原因、影響範囲、依存関係を確認できます。上記のインシデントカードは、NEAT が対応に値する障害を検出したときに渡すもので、自分で取得するものではありません。

NEAT は現在も活発に開発中です。機能はnpx neat.isのインターフェイスでパッチリリースとして提供されます。今後の予定については未解決の課題をご覧ください。

1つのコマンド

npx neat.is

プロジェクト内で実行してください（またはnpx neat.is <path>）。サービスを検出し、静的グラフを構築し、ソースを編集することなく OpenTelemetry を接続して、プロジェクト用のバックグラウンドデーモンを起動します。設定は不要です。続いて、NEAT を接続した状態でアプリを起動します。Node の場合は、生成された.env.neatを読み込んでから（set -a; . ./.env.neat; set +aを実行し、その後いつもの起動コマンドを実行します）、Python の場合は、opentelemetry-instrumentの下で起動コマンドを実行します。アプリの実行に伴い、グラフのランタイム側の情報が補完されます。

リクエストに失敗した場合、エージェントは MCP 経由で作業指示書を要求します。

get_incident_card { "nodeId": "service:checkout" }

すると、そのインシデントの発生箇所、ホップごとの来歴を含む原因の連鎖、影響範囲、適用されるポリシー、差異をまとめて取得できます。neat monitorは、新しいインシデントが発生するたびに1行を出力します。

Windows では、npx neat.isではなくneatコマンドを使用してください。 npm がneat.isという名前の shim を生成しますが、Windows は.isファイルを実行せず、代わりにファイルの関連付けに渡します。一度インストールして、ドットなしのバイナリを実行してください。npm i -g neat.isを実行してから、neat（またはneat <path>）を実行します。グローバルインストールを行わない場合は、npx -p neat.is neatを使用してください。以下のすべてのnpx neat.is <verb>は、この方法ではneat <verb>になります。

より詳しい説明：

NEAT の中核にあるのは、システム全体を表す1つのライブグラフです。2つのストリームを統合して、さまざまな方法でクエリできる単一のモデルを作ります。

• 静的解析 — ソースコード、package.json、yaml / env の設定を tree-sitter で解析します。11の言語をシンボル単位で解析できます。対象は JavaScript、TypeScript、Python、Go、Ruby、PHP、C#、Java、Kotlin、Rust、C++ です。そのほとんどでルートとデータベース呼び出しを認識します。ランタイムとコードの統合に対応するのは JavaScript、TypeScript、Python です。サービス間のアウトバウンド HTTP 呼び出しを読み取るのは JavaScript と TypeScript のみのため、その他の言語ではサービス間のエッジにランタイムテレメトリーを利用します。各ソースファイルがノードになり、ファイル間のインポートがエッジになります。また、各ファイルからデータベース、キュー、外部ホストへの呼び出しをコードから抽出します。
• ランタイムテレメトリー — OpenTelemetry のスパンを、呼び出し元の正確なファイルと行に関連付けます。NEAT が計装を設定するため、ランタイムのエッジは静的エッジと同じファイルノードに追加されます。

2つのストリームは同じノードに追加されるため、グラフにはコードが宣言する内容と、システムが実行する内容が並んで保持されます。そこから、役立つ問いを1つのモデルで答えられます。このノードが停止したら何が壊れるのか（影響範囲）、最初に何が壊れたのか（根本原因）、変更によってどのアーキテクチャルールに違反するのか（ポリシー）、宣言された意図と観測された実態がどこで食い違うのか（乖離）。同じグラフを、異なる方法でたどります。

ファイルが基本単位です。 グラフの関係は、曖昧なサービスの塊ではなく、ファイルから始まります。たとえば src/services/billing.ts ──CALLS──▶ api.stripe.com のようになります。関係をファイルと行に結び付けることで、すべての回答を明確にできます。調査結果には「このファイルがこのターゲットを呼び出している」と示されるため、「サービスらしきものが関係している」といった曖昧な回答にはなりません。

各エッジには provenance タグが付いており、利用側は主張の信頼度を正確に把握できます。

• ソースからの EXTRACTED。時間経過による減衰はありません。
• スパンからの OBSERVED。lastObserved と callCount を保持します。
• OTel のカバレッジにギャップがある場合に、トレース接続処理によって INFERRED されます。信頼度には上限があります。
• ランタイムからの情報が途絶えたため STALE になったもの。元の lastObserved を保持します。

グラフは24個の MCP ツールを通じて AI エージェントに公開されます。14個のツール（ask、get_root_cause、get_blast_radius、get_dependencies、get_observed_dependencies、get_incident_history、get_incident_card、get_divergences、get_graph_diff、get_recent_stale_edges、check_policies、semantic_search、expand、relate）でグラフを読み取れます。6個のツール（neat extend）では、バンドルされた OTel セットでカバーされないライブラリの計装ギャップを、バージョン管理された計装レジストリに基づいてエージェントが解消できます。残る4個のツールは、ホスト型プロジェクトをプロバイダーに接続します。

CLI

同じ neat バイナリですべての動詞を処理します。グローバルインストール（npm i -g neat.is）後、または npx neat.is を使って実行します。

neat <path>              orchestrator: extract, instrument, spawn daemon, open dashboard
neat init <path>         extract only; patch-by-default, --apply to write
neat watch <path>        keep the graph live as files change
neat deploy              emit deployment artifacts for a hosted target
neat sync --to <url>     push the local EXTRACTED snapshot to a remote daemon (v0.3.9)
neat divergences         where your code and your production traffic disagree
neat root-cause <id>     walk inbound edges to find what broke first
neat blast-radius <id>   BFS outbound; what would break if this node dies
neat dependencies <id>   transitive outbound dependencies
neat incidents           recent error events
neat policies            current policy violations
neat search <query>      semantic match on node names and ids

すべてのクエリ動詞で --json と --project <name> が使用できます。終了コードは、成功（0）、サーバーエラー（1）、誤用（2）、デーモンに到達できない場合（3）に分かれています。

例：乖離の例

乖離とは、グラフが答える問いの1つであり、ほかの方法では答えるのが最も難しいものです。2つのストリームを同時に必要とします。アプリを実行すると、neat divergences によって、宣言された意図と観測された動作が食い違う箇所が報告されます。

[missing-extracted] src/services/prices.ts ──CALLS──▶ folio-api.example.com   confidence 0.87
  Production observed this call, but static analysis never surfaced the edge.
  → dynamic dispatch or a coverage gap. The code reaches a host it doesn't visibly name.

[missing-observed]  src/db/client.ts ──CONNECTS_TO──▶ postgres:primary        confidence 0.85
  Code declares this connection, but no production traffic has exercised it.
  → dead path, feature flag, or an unshipped branch. The declared dependency is idle.

2つの調査結果は、それぞれ異なるバグを示しています。1つ目は、コードが明示せずに行う呼び出しです。予期せぬ事態が起きる前に把握しておく価値があります。2つ目は、コードが依存しているのに一度も使っていない依存関係です。不要な負荷である可能性も、稼働中だと思っていた経路が実際には使われていない可能性もあります。どちらも同じファイルを比較して得られます。つまり、ファイルが何を述べているかと、何を実行したかの比較です。

ポリシー：グラフに対するルール

Divergence は「現状」を示します。ポリシーを使うと、「あるべき姿」を表明できます。プロジェクト内の policy.json で、同じグラフに対するアサーションとしてアーキテクチャ上のルールを宣言します。たとえば、「service:billing と service:orders だけが postgres:primary に接続できる」や、「どのファイルも legacy-api.internal を呼び出してはならない」といったルールです。ルールはライブグラフに対して実行されるため、コードで宣言されている内容と、本番環境で実際に行われていることの両方を評価します。

NEAT はグラフの変化に合わせて、すべてのポリシーを継続的に評価します。エッジがルールに違反すると、その違反が表面化します。一度きりの lint 実行に埋もれることはありません。違反は次の 2 つの方法で確認できます。

• neat policies は、現在違反している内容を一覧表示します。--node でノードを指定したり、--hypothetical-action で変更をドライランしたりできます。
• check_policies は、同じ内容を MCP 経由で AI エージェントに提供します。新機能を実装するエージェントは、どのルールに抵触するか、またどのアサーションの範囲内で作業しているかを確認できます。対象となるのは、以前の機能、ほかのエージェント、またはエンジニアがすでに設定したルールです。

block アクションは、FrontierNode（グラフが新たに検知した外部ホスト）の昇格を制御するため、許可されていない外部依存関係がひそかにモデルへ定着することを防ぎます。一貫しているのは、グラフがすでにアーキテクチャを把握しているため、重視するルールをそのグラフに対するアサーションとして表現でき、システムの変化に合わせてその状態を保てるという点です。

サーバーで NEAT を実行する

ghcr.io/neat-technologies/neat:latest のコンテナイメージは neatd start を起動し、REST を :8080、OTLP を :4318、ウェブ UI を :6328 で公開します。トークンを生成してイメージを実行し、OTel SDK の接続先を指定します。

NEAT_AUTH_TOKEN=$(openssl rand -hex 32)
docker run -d --name neat \
  -e NEAT_AUTH_TOKEN="$NEAT_AUTH_TOKEN" \
  -p 8080:8080 -p 4318:4318 -p 6328:6328 \
  -v /var/lib/neat:/neat-out \
  ghcr.io/neat-technologies/neat:latest

すべての公開インターフェースで NEAT_AUTH_TOKEN が必須です。デーモンは、トークンが設定されていない状態でループバック以外のアドレスにバインドすることを拒否します。REST と SSE の呼び出し元は Authorization: Bearer <token> でトークンを送信し、OTel エクスポーターも同じヘッダーを送信します。NEAT_OTEL_TOKEN を使うと、OTLP トークンを個別にローテーションできます。

より簡単な方法として、neat deploy を実行するとトークンが生成され、docker-compose.neat.yml が書き出されます。また、アプリケーションのデプロイプラットフォームで必要となる環境変数ブロックが表示されます。

OTEL_EXPORTER_OTLP_ENDPOINT=https://<your-host>:4318
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20<generated-token>

リバースプロキシの背後で実行する

TLS 終端と認証を上流のプロキシですでに処理している場合は、NEAT_AUTH_PROXY=true を設定すると、デーモンがリクエスト側の Bearer チェックをスキップします。ただし、バインド権限のチェックでは、NEAT_AUTH_TOKEN が設定されていない状態での公開バインドが引き続き拒否されます。そのため、両方を設定してください。

neat.example.com {
  reverse_proxy localhost:8080 {
    header_up Authorization "Bearer {env.NEAT_AUTH_TOKEN}"
  }
  reverse_proxy /events localhost:8080
  @otlp path /v1/traces
  reverse_proxy @otlp localhost:4318 {
    header_up Authorization "Bearer {env.NEAT_AUTH_TOKEN}"
  }
}

次に docker run … -e NEAT_AUTH_TOKEN=… -e NEAT_AUTH_PROXY=true … を実行し、Caddy に公開インターフェースを保護させます。

NEAT をエージェントに接続する

NEAT の MCP サーバーは、公式の MCP Registry に io.github.neat-technologies/neat として登録されているため、レジストリに対応したエディターならワンクリックでインストールできます。

各ボタンは npx -y @neat.is/mcp を使って @neat.is/mcp サーバーを接続し、ローカルデーモンを参照するよう設定します。デフォルト以外のデーモンを対象にするには、NEAT_CORE_URL を設定してください。Claude Code の場合：

claude mcp add neat -- neat-mcp

または、~/.claude/settings.json を手動で編集します。

{
  "mcpServers": {
    "neat": {
      "command": "neat-mcp",
      "env": { "NEAT_CORE_URL": "http://localhost:8080" }
    }
  }
}

上記の neat-mcp バイナリは、グローバルインストールされていることを前提としています。グローバルインストールされていない場合は、代わりに neat skill --apply を実行してください。グローバルバイナリがなくてもサーバーを解決できるよう、npx -y @neat.is/mcp を使った同じ mcpServers.neat エントリが書き込まれます。どちらの形式でも、デーモンの URL には NEAT_CORE_URL が使われます。エージェントにデフォルト以外のデーモンを参照させるには、これを設定してください。

Claude Code のセッションで、「checkout-svc が失敗する理由は？」 と尋ねてください。NEAT はグラフをたどり、トラバーサルパス、エッジの出典、信頼度スコア、推奨される修正方法を示して回答します。

grep より先にグラフを使う

neat hooks --apply

これにより、エージェントが生のテキスト検索に切り替える前にグラフを照会するよう促す仕組みが 2 つインストールされます。

• Claude Code の検索促進フック — エージェントが Grep／Glob、または Bash の grep／rg／find を使おうとしたときに、まず semantic_search、get_dependencies、get_divergences を使うよう案内するメモを挿入する PreToolUse フックです。検索は引き続き実行される、穏やかで処理を妨げない促しです。他のフックには触れずに ~/.claude/settings.json にマージされ、再実行しても安全です。
• エージェントを問わないグラフ優先のガイダンス — CLAUDE.md／AGENTS.md／.cursorrules に貼り付ける Markdown ブロック（GRAPH_FIRST.md。~/.neat/neat-graph-first.md にも書き込まれます）です。どのハーネスを使うエージェントにも、同じ指針を示せます。

フックは Claude Code 専用です。他のハーネス（Codex、Gemini、Cursor）では、代わりにガイダンスブロックを利用します。インストールせずに各項目を確認するには、neat hooks --print-hook、--print-guide、--print-settings を実行してください。

Claude Code プラグイン — まとめてインストールする方法

上記の neat skill と neat hooks コマンドは、必要なものを個別に選んで NEAT を接続する方法です。Claude Code では、MCP グラフツール、グラフ優先の検索促進フック、スキルをプラグインとして一度にインストールできます。

claude plugin marketplace add NEAT-Technologies/Neat
claude plugin install neat@neat

プラグインはこのリポジトリの plugin/ にあり、GitHub から直接インストールできます。別途公開するものはありません。プラグインには、個別に実行するコマンドが書き込むものとまったく同じ MCP サーバー設定と検索促進フックが含まれるため、どちらの方法でも同じように動作します。好みの方法を選んでください。バンドルされた MCP サーバーにデフォルト以外のデーモンを参照させるには、NEAT_CORE_URL（デフォルトは http://localhost:8080）を設定してください。

リポジトリの構成

packages/
  types/          shared Zod schemas: node, edge, event, result types
  core/           graph engine, tree-sitter extraction, OTel ingest, REST API, neat CLI
  mcp/            stdio MCP server exposing the twenty-four tools to AI agents
  web/            Next.js dashboard
  claude-skill/   Claude Code skill metadata
  neat.is/        umbrella package
plugin/           Claude Code plugin — bundles the MCP server, hook, and skill (repo-hosted)

ドキュメント

• docs/guide/：ユーザーガイドです。使い始めるための手順、基本概念、クエリの実行、AI エージェント、トラブルシューティングを説明しています。まずはこちらをご覧ください。
• PROVENANCE.md：4 つのエッジ状態と、パスに沿って信頼度がどのように引き継がれるかを説明しています。
• CLAUDE.md：このリポジトリで作業するエージェントおよびコントリビューター向けのガイドです。
• docs/architecture.md：パッケージの境界とデータフローを説明しています。
• docs/api-reference.md：REST エンドポイントと MCP ツールのシグネチャを説明しています。
• docs/runbook.md：日常的に使うコマンドと復旧手順を説明しています。
• docs/contracts.md：すべての PR が遵守すべき拘束力のあるルールを説明しています。
• CONTRIBUTING.md：ブランチの規約、PR の形式、開発環境のセットアップについて説明しています。
• SECURITY.md：脆弱性の報告方法を説明しています。

コントリビューション

PR を歓迎します。ブランチの規約、PR の形式、すべての変更を審査する契約フレームワークについては、まず CONTRIBUTING.md をお読みください。

ライセンス

Apache 2.0 です。詳細は LICENSE をご覧ください。