devmap

DevMap

一度分析すれば、どこでもコンテキストを再利用できます。 開発者と AI エージェント向けに、コードベースのエントリーポイント、重要なファイル、機能、ルートをマッピングする CLI です。

ドキュメント · ウェブサイト · GitHub

コードについて新しい AI チャットを始めるたびに、最初から説明し直す必要があります。毎回同じコードベースを説明し直すことになります。DevMap はこの問題を解決します。

DevMap は、静的解析と任意の AI による解釈を組み合わせ、プロジェクトを構造化して再利用可能な形で把握するためのレイヤーを一度だけ構築する CLI です。このレイヤー（.devmap/index.json、機能マップ、DEVMAP.md）は、リポジトリ全体を再スキャンしたり、貼り直したりする代わりに、その後あなたや任意の AI エージェントが読み込むものです。リポジトリ全体のソースコードはローカルに保持され、AI モデルに一括送信されることはありません。

インストール

npm install --global @flaid/devmap

グローバルにインストールせずに実行することもできます。

npx @flaid/devmap --help

必要条件

• Node.js 22.12 以降
• AI プロバイダーの API キー：Groq、OpenRouter、または任意の OpenAI 互換エンドポイント

AI を設定していなくても、静的解析は引き続き利用できます。

クイックスタート

把握したいプロジェクトのルートから、次のコマンドを実行します。

devmap init
devmap analyze
devmap onboarding
devmap doctor

devmap init はプロバイダーを選択し、キーを検証して、設定をローカルに保存し、.devmap/ を準備して、DEVMAP.md を生成し、AGENTS.md に安全に統合します。

AI プロバイダーの設定

次の操作中に、矢印キーで Groq、OpenRouter、またはカスタムの OpenAI 互換エンドポイントを選択します。

devmap init

Groq のキーは https://console.groq.com/keys で取得できます。OpenRouter のキーは https://openrouter.ai/keys で取得できます。

カスタムエンドポイントの場合、DevMap はベース URL（http://localhost:20128/v1 があらかじめ入力されています）を尋ね、サーバーが公開しているモデルの一覧を表示します。そのため、OpenAI 互換のセルフホスト型ゲートウェイなら、すぐに利用できます。

OpenRouter の場合、DevMap は次の内容を表示します。

OpenRouter model [openrouter/free]:

Enter キーを押すと無料ルーターが使われます。または、無料・有料を問わず、任意の OpenRouter モデル ID を入力してください。選択したモデルは保存され、優先モデルとして使用されます。

Groq を非対話形式で設定する場合：

GROQ_API_KEY="your-key" devmap init

PowerShell の場合：

$env:GROQ_API_KEY="your-key"
devmap init
Remove-Item Env:GROQ_API_KEY

OpenRouter を非対話形式で設定する場合：

OPENROUTER_API_KEY="your-key" devmap init

キーはローカルの ~/.devmap/config.json に保存されます。リクエストはお使いのマシンから選択したプロバイダーに直接送信されます。DevMap はキーを DevMap が所有するサーバーに送信しません。

コマンド

devmap init
devmap analyze
devmap analyze --fresh
devmap map                    # full project map
devmap map <feature-or-file>  # scoped to one feature or file
devmap flow                   # curated top flows
devmap flow <feature-or-route>
devmap explain <target>       # file, feature, or function
devmap onboarding --write
devmap onboarding --write --language id
devmap doctor
devmap config model auto
devmap mcp                    # run as an MCP server

Groq と OpenRouter は、初期化時に選択したモデルを使用します。いずれかのプロバイダーのモデルを変更するには、次のコマンドを実行します。

devmap config model <model-id>
devmap config model auto

MCP サーバー

devmap mcp は、stdio 経由で DevMap をModel Context Protocolサーバーとして実行します。AI エージェントはツール呼び出しでプロジェクトマップについて質問し、コンテキストファイル全体を最初に読み込む代わりに、構造化された JSON を受け取ります。

devmap analyze
claude mcp add devmap -- npx -y @flaid/devmap mcp

ほかのクライアントも、同じコマンド（npx -y @flaid/devmap mcp）を stdio サーバーとして起動します。

{
  "mcpServers": {
    "devmap": {
      "command": "npx",
      "args": ["-y", "@flaid/devmap", "mcp"]
    }
  }
}

ツール：devmap_overview、devmap_map、devmap_flow、devmap_routes、devmap_impact、devmap_find、devmap_analyze、および --allow-ai 指定時のみ利用できる devmap_explain。

サーバーはデフォルトで読み取り専用かつ静的に動作します。--allow-ai を指定して起動しない限り、AI プロバイダーに接続しません。また、エージェントが devmap_analyze を呼び出すか、--auto-refresh を指定して起動した場合にのみ、.devmap/ 内に書き込みます。すべての回答には、スナップショットが古くなっているかどうかが示されます。クライアントの設定方法とツールの入力については、MCP ガイドを参照してください。

生成されるコンテキスト

DevMap は以下を生成します。

• 軽量な AI エージェント向けナビゲーション用の .devmap/index.json
• 機能ごとのマップとソースの優先順位を示す .devmap/features/*.json
• プロジェクト分析全体を構造化して保存する .devmap/snapshot.json
• 人間と AI エージェント向けの利用ガイドである DEVMAP.md
• ファイルがすでに存在する場合、確認後にのみ AGENTS.md に追加される小さな DevMap ブロック

既存の AGENTS.md と DEVMAP.md ファイルが上書きされることはありません。

AI エージェント向け

まず .devmap/index.json を読み、関連する機能マップを開いて、その sourcePriority ファイルを確認してください。軽量なナビゲーション層では不十分な場合にのみ、 .devmap/snapshot.json を使用してください。

スクリプト、エディター、CI、AI エージェントでは --json を使用してください。

devmap analyze --json
devmap onboarding --json
devmap doctor --json

JSON モードでは、ANSI カラー、ターミナル装飾、ストリーミングによる部分出力を含まない、 解析可能な JSON ドキュメントが 1 つ標準出力に書き込まれます。

対応スタック

• フロントエンド：Next.js、Astro、SvelteKit、Nuxt、Remix、React Router v7、TanStack Router/Start、Expo Router、SolidStart、Qwik City、Angular、React、Vue、Svelte
• バックエンド：Express、NestJS、Fastify、Hono、Elysia、Koa、AdonisJS

上記のリスト全体が検出対象です。Next.js と Express は最も詳細に分析されます。 マルチパッケージワークスペースはプロジェクトの種類ごとに分類されるため、CLI とウェブアプリを含む モノレポは、両方を含むものとして報告されます。

プライバシー

• プロジェクト分析は AI による解釈の前にローカルで実行されます。
• リポジトリのソース全体が選択したプロバイダーに送信されることはありません。
• .env ファイルと一般的な生成ディレクトリは無視されます。
• API キーはローカルに保存され、コミットしないでください。

リンク

• リポジトリ：https://github.com/itsflaid/devmap
• イシュー：https://github.com/itsflaid/devmap/issues
• 変更履歴：https://github.com/itsflaid/devmap/blob/main/CHANGELOG.md

ライセンス

MIT