dgv

30秒

git clone https://github.com/ShAInyXYZ/Dia-GramV.git && cd Dia-GramV
npm install && npm run build
node packages/mcp/bin/dgv.mjs doctor                        # checks Node + the build, prints the lines below with your path
claude mcp add dgv -s user -- node "$PWD/packages/mcp/bin/dgv.mjs" mcp
ln -s "$PWD/skill" ~/.claude/skills/dgv                     # optional: teaches the agent the workflow

そして、どのプロジェクトでも、エージェントにこう伝えます：

始める前に、このシステムをDGVでマッピングして。

カタログを読み、dgv/<name>.dgv.json を書き、書き込みのたびにlintレポートを受け取り、壊した箇所を修復し、図をレイアウトして http://127.0.0.1:7710 で開きます。以降、そのファイルが地図になります。以後のセッションはすべて、コードを読む前にそのファイルを読みます。

必要なのは Node 20.19+ または 22.12+ です。npm install ですべてを取得します（約100 MB、グローバルには何も入れません）。npm run build でビューアを一度コンパイルします。MCPツールだけが必要ならビルドは不要です — dgv_open 以外はすべてビルドなしで動作します。

Related MCP server: mermaid-mcp-server

これは何か

1つのファイル。 dgv/<name>.dgv.json には、フレーム（境界）、ノード（コンポーネント）、エッジ（接続）が入ります。すべてのノードは固定カタログに含まれるkindを持ち — ui、service、api、db、queue、bridge、external… — そしてportsを宣言できます。すべてのエッジは、接続先のポートと、そこで使うprotocolを指定します。プレーンなJSONで、リポジトリ内の、説明対象のコードの隣に置きます。

2つの入り口。 MCPサーバーはエージェント用です。ファイルの作成・変更・読み取りを行い、書き込みのたびにlintレポート（安定したコード、要素、具体的な修正方法）を受け取ります。ビューアはあなた用です。kindごとに形状があり、ワイヤーがプロトコルを運ぶSvelte Flowキャンバスで、すべてのフィールドを検査するインスペクタと、同じlintがサイドパネルに表示されます。エージェントがファイルを変更すると、ページがリロードされます。

AIがコードを書くときにこれが重要な理由

図は最も重要ではない部分です。重要なのは、システムのモデルが、プログラムが読み取り・検証・変更できるファイルであることです。

雰囲気でコードを書いているなら、システムは頭で追いつけない速さで成長し、あなたがこうだと思っている形と、実際の形は乖離していきます。DGVは、その形に居場所を与え、意味を成さなくなったときに異議を唱えるリンターを与えます。

AIをそばに置いて開発しているなら、図は、コードがまだ表現できない意図を表明する場所です — ワーカーはキューを消費する。APIはバケットに直接書き込まない — それを一度、以降のすべてのセッションが引き継ぐ形で記します。

あなたがエージェントなら、これは、grepで探すことと、知っていることの違いです。見慣れないリポジトリでは、ファイルを開いて全体像を再構築します。dgv_read はその全体像をあなたに渡します。以下は、そのノートアプリに対する完全な出力をそのまま示したものです：

# Notes app
frames 3 · nodes 6 · edges 5 · updated 2026-08-27

## frame browser: Browser
- web [ui] Notes UI — SvelteKit
## frame server: Server · one process
- api [api] HTTP API — /api/notes ports: rest:http/in
- jobs [worker] Job runner — thumbnails, exports
## frame data: Data
- pg [db] Postgres — notes, users ports: sql:sql/in
- redis [queue] Job queue — Redis lists ports: jobs:redis/in
- s3 [storage] Object store — uploads ports: put:s3/in

## edges
- web-api: web → api [sync http] fetch ports ·→rest
- api-pg: api → pg [data sql] ports ·→sql
- api-redis: api → redis [async redis] enqueue ports ·→jobs
- jobs-redis: jobs → redis [async redis] consume ports ·→jobs
- jobs-s3: jobs → s3 [data s3] ports ·→put

api → pg [data sql] ·→sql を読めるエージェントは、データベースにRESTエンドポイントをでっち上げたりしません。200トークンで、ツリーをひと巡りする代わりになります。

できること — 4つのケース

1 · 作る前に計画し、計画が成立しないときは指摘される

エージェントは、1回の dgv_apply で小さなノートアプリを記述します。そこにはありがちな間違いが2つあります：オブジェクトストアのポートが、ノードでは put と呼ばれ、エッジでは upload と呼ばれていること、そして、データベースがAPIにコールバックしていることです。

dgv_apply({ name: "notes-app",
  nodes: [ { id: "s3", kind: "storage", label: "Object store", frame: "data",
             ports: [ { id: "put", protocol: "s3", dir: "in" } ] }, … ],
  edges: [ { id: "jobs-s3", source: "jobs", target: "s3", kind: "data", protocol: "s3", targetPort: "upload" },
           { id: "pg-api",  source: "pg",   target: "api", kind: "sync", protocol: "http", label: "notify on change" }, … ] })

書き込みは成功し、同じターンでレポートが返ってきます：

{ "ok": false, "lint": { "error": 1, "warning": 2, "info": 0 },
  "diagnostics": [
    { "code": "port/undeclared", "severity": "error",
      "message": "edge \"jobs-s3\" uses target port \"upload\" but node \"s3\" does not declare it",
      "subject": { "type": "edge", "id": "jobs-s3", "field": "targetPort" },
      "fixes": [ "add port {id:\"upload\"} to node \"s3\"", "point the edge at one of: put" ] },
    { "code": "kind/store-initiates", "severity": "warning",
      "message": "\"pg\" is a db; stores do not initiate sync calls to \"api\"",
      "subject": { "type": "edge", "id": "pg-api" },
      "fixes": [ "reverse the edge and mark it kind:\"data\"",
                 "if it is a trigger/CDC stream, add a worker or queue between them" ] }, … ] }

同じレポートをビューアで見ると、失敗したワイヤーは赤くなり、各エントリはその要素にジャンプします：

1つ目の間違いは、そのままバグになっていたであろうタイプミスです。2つ目は、エージェントならためらわずに実装していたであろうアーキテクチャです。どちらもid、コード、修正方法として返ってくるので、コードが存在する前に計画が修復されます：

dgv_apply({ name: "notes-app",
            edges: [ { id: "jobs-s3", targetPort: "put" } ],       // partial: id + the field that changes
            remove: { edges: [ "pg-api" ] } })
→ { "ok": true, "lint": { "error": 0, "warning": 0, "info": 0 } }

2 · すでにあるシステムをマッピングする

エージェントをリポジトリに向けます — コードからCerveauのアーキテクチャをDGVでマッピングして — すると、エージェントはエントリポイント、リスナー、クライアント、設定を読み、見つけたものを書き出します。下のローカルAIハーネスは、4つの境界にまたがる13のコンポーネントです：Goコアを駆動するパネルと電話、llama.cppサーバー、メモリ用のTypesense、Pythonの埋め込みサイドカーです。

フルサイズでは — Cerveau自身、7つの境界にまたがる35のコンポーネント、すべての呼び出しが宣言済みのポートにバインドされています：

S を押すと、すべてのフレームが1つのノードに折りたたまれ、フレームをまたいでいたワイヤーは1本のラベル付きリンクに統合されます。同じファイルです。最初の図と歩調を合わせるべき2つ目の概要図はありません：

3 · 同じ図で開発の進捗を追う

ノードは status を持つことができます — todo wip done blocked failed update。2 を押すと、キャンバスはkindの代わりにステータスで色分けされます。ファイルはビルドボードになります。エージェントは、まだ todo のものを読むことで前回のセッションの続きから始められ、ブロックされたノードの note にはその理由が書かれます：

4 · それが真実でなくなったときを知る

lintは計画が整合的であることを示します。しかし、計画が真実であるとは言えません — つまり、ディスク上のコードが、図が記述しているコードのままであるとは言えないのです。ノードに path（ファイル、ディレクトリ、glob、リスト）を与えると、dgv_drift がプロジェクトを走査します — git ls-files を使うので .gitignore が尊重されます — そして、何にも一致しない path（drift/missing）、どのノードにも属さないコードのディレクトリ（drift/unclaimed）、同じファイルを主張する2つのノード（drift/shared）を報告します。

このリポジトリも、すべてのノードに path を持たせて、同じ方法で自身のアーキテクチャを管理しています：

driftを初めて実行したとき、何かが見つかりました：

$ node packages/mcp/bin/dgv.mjs drift dia-gramv
warning drift/unclaimed  packages/mcp/ — 1 of 5 files belong to no node
        fix: add a node with this path | widen an existing node's path to cover it | add it to meta.driftIgnore if it is not part of the system

packages/mcp/package.json が誰にも主張されていませんでした。MCPノードの path が1つのファイルだったからです。範囲を広げたら、クリーンになりました。

2つのオプションのClaude Codeフックでループが閉じます（hooks/；doctor はあなたのパスを含む設定ブロックを表示します）：

• SessionStart は、./dgv 内のすべての図の概要を、driftサマリーとともにコンテキストに出力します — エージェントが最初に知るのは、システムの形と、地図が古くなっていないかどうかです。

• Stop は毎ターン後にdriftを実行し、何か言うべきことがあるときだけ、1行残します：DGV · app: 1 node path no longer exists (old)。ブロックすることはありません。

ビューア

node packages/mcp/bin/dgv.mjs serve → http://127.0.0.1:7710 — またはエージェントから dgv_open。

ノードをフレームにドラッグすると、そのフレームに加わります。フレームは収まるように拡大します。Ctrl+Z で元に戻せます。Ctrl+S で保存できます — 未保存の編集がある間にエージェントがファイルを変更した場合は、ページがその旨を表示し、選択させてくれます。L でワイヤーのスタイルを切り替えます：浮遊ベジェ、カードの周りを迂回、直線。Shift+S は画面に表示されているものを自己完結型のSVGとして保存します。このREADMEのすべての図はこの方法で作られました。

折りたたみビューの配置は、ブラウザ内でダイアグラムごとに保持され、ファイルには保存されません。

リファレンス

ダイアグラムはエージェントが起動されたディレクトリ配下の./dgvに保存されます。DGV_DIRで別の場所に保存できます。

最初に形状（schema/invalid）、次に参照（ref/missing-node、ref/missing-frame、ref/duplicate-id）、その後に以下のルールをチェックします。エラーはokをブロックします。警告と情報はアドバイスです。

エラー — 先に進む前に修正してください。

警告 — プランに穴がある可能性があります。

情報 — 確認する価値あり。件数にはカウントされません: kind/store-access、kind/module-loose、kind/external-inside、graph/shared-store、layout/unplaced。

意図的な警告には、その要素にack: "<reason>"を付けます。理由が添付された情報になり、その理由はファイルとともに保持されます。エラーはacknowledgeできません。

{ "dgv": 1,
  "meta":   { "title": "Notes app", "description": "…", "colorBy": "kind", "edgeStyle": "routed" },
  "frames": [ { "id": "server", "label": "Server · one process", "tone": "amber",
                "position": { "x": 480, "y": 60 }, "size": { "width": 380, "height": 300 } } ],
  "nodes":  [ { "id": "api", "kind": "api", "label": "HTTP API", "sublabel": "/api/notes",
                "frame": "server", "status": "done", "path": "src/api", "position": { "x": 520, "y": 120 },
                "ports": [ { "id": "rest", "protocol": "http", "dir": "in" } ] } ],
  "edges":  [ { "id": "web-api", "source": "web", "target": "api",
                "kind": "sync", "protocol": "http", "targetPort": "rest", "label": "fetch" } ] }

kindはノードに必須です。エッジでは省略時はプロトコルから推論されます — sql redis s3 fs smbの場合はdata、kafka nats amqp mqtt sse wsの場合はasync、それ以外はsyncです。位置は保存されるため、作成した配置は維持されます。完全なカタログ — すべての種類、プロトコル、lintコード — はskill/references/format.mdにあります。

node packages/mcp/bin/dgv.mjs serve  [--dir d] [--port p] [--no-open]      # viewer, default http://127.0.0.1:7710
node packages/mcp/bin/dgv.mjs lint   <name|file> [--json]
node packages/mcp/bin/dgv.mjs layout <name|file> [--direction TB|LR]
node packages/mcp/bin/dgv.mjs export <name|file> [--format markdown|mermaid|summary|svg]
node packages/mcp/bin/dgv.mjs drift  <name|file> [--root dir] [--json]
node packages/mcp/bin/dgv.mjs list | catalog | doctor | open <name>

npm test — コア: スキーマ、lintルール、パッチのセマンティクス、レイアウトの包含、折りたたみ、エクスポート、SVG、ドリフト。

制限事項

DGVはソースコードを解析しません。lintはプランが一貫していることを教えてくれます。ドリフトは、すべてのノードが存在するコードを指していることと、すべてのコードディレクトリにノードがあることを教えてくれます。どちらも、ダイアグラムが描く呼び出しがコードが行う呼び出しであることは教えてくれません — それは依然として人間またはエージェントが読み取るものであり、リポジトリ内にあるファイルがその読み取りをレビュー可能にしています。

対象外: コラボレーションやホスティング、シーケンス図やライフサイクル図、リポジトリ構造の自動検出。フォーマットはバージョン管理されているため（dgv: 1）、既存ファイルを壊さずにこれらを追加できます。

成り立ち

Cerveauはローカルファーストのエージェンティックコーディングハーネスです。そのdocsフォルダにはarch-viewerという非公開のドラフトがありました。アーキテクチャのDiagram.jsonを読み込むSvelte Flowキャンバスで、99ノード、127エッジ、種類を持つノード、ラベルを持つエッジで構成されていました。ブラウザでしか読めないため、構築中のエージェントはそれを見ることができませんでした。DGVはキャンバス、フレーム、レイアウトを維持し、その下に契約を置きます: カタログ、ポートとプロトコル、宣言されたメンバーシップ、リンター、そしてエージェントが同じファイルを読み書きするためのMCPです。archifyは、修復可能な診断情報を持つ型付き中間表現のアイデアを提供しました。

MIT © Mounir Belahbib