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을 작성하고, 매번 쓰기 때마다 린트 보고서를 받고, 깨뜨린 것을 수리하고, 다이어그램을 배치한 다음 http://127.0.0.1:7710에서 엽니다. 그때부터 그 파일이 지도입니다: 이후의 모든 세션은 코드를 읽기 전에 그 파일을 읽습니다.

Node 20.19+ 또는 22.12+가 필요합니다. npm install이 모든 것을 가져옵니다(~100MB, 전역 설치 없음). npm run build는 뷰어를 한 번 컴파일합니다. MCP 도구만 원한다면 빌드를 건너뛰어도 됩니다 — dgv_open을 제외한 모든 것이 빌드 없이 작동합니다.

Related MCP server: mermaid-mcp-server

무엇인가

단일 파일. dgv/<name>.dgv.json은 프레임(경계), 노드(구성 요소), 엣지(연결)를 담습니다. 모든 노드는 고정된 카탈로그의 **종류(kind)**를 가집니다 — ui, service, api, db, queue, bridge, external… — 그리고 **포트(port)**를 선언할 수 있습니다. 모든 엣지는 연결되는 포트와 사용하는 **프로토콜(protocol)**을 명명합니다. 저장소 안에, 설명하는 코드 옆에 있는 평범한 JSON입니다.

두 가지 진입점. MCP 서버는 에이전트의 것입니다: 파일을 생성, 변경, 읽고, 매번 쓰기 때마다 린트 보고서를 받습니다 — 안정적인 코드, 요소, 구체적인 수정 사항. 뷰어는 당신의 것입니다: 종류마다 모양이 있고 와이어가 프로토콜을 나르는 Svelte Flow 캔버스로, 모든 필드에 대한 인스펙터와 동일한 린트가 사이드 패널에 실시간으로 표시됩니다. 에이전트가 파일을 변경하면 페이지가 다시 로드됩니다.

AI가 코드를 작성할 때 왜 중요한가

그림은 가장 중요하지 않은 부분입니다. 중요한 것은 시스템의 모델이 프로그램이 읽고, 검사하고, 변경할 수 있는 파일이라는 점입니다.

vibecode한다면, 시스템은 머릿속에 담을 수 있는 것보다 빠르게 성장하고, 생각하는 모양은 실제 모양에서 어긋납니다. 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 엔드포인트를 지어내지 않습니다. 이백 개의 토큰이 트리 탐색을 대신합니다.

하는 일 — 네 가지 사례

1 · 구축 전에 계획하고, 계획이 성립할 수 없을 때 알림을 받기

에이전트가 한 번의 dgv_apply로 작은 메모 앱을 설명합니다. 여기에는 두 가지 흔한 실수가 있습니다: 객체 스토어의 포트가 노드에서는 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" ] }, … ] }

뷰어에서의 같은 보고서 — 실패한 와이어는 빨간색이고, 모든 항목은 해당 요소로 이동합니다:

첫 번째 실수는 버그가 되었을 오타입니다. 두 번째는 에이전트가 망설임 없이 구현했을 아키텍처입니다. 둘 다 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 하네스는 네 개의 경계에 걸친 13개 구성 요소입니다: Go 코어를 구동하는 패널과 폰, llama.cpp 서버, 메모리용 Typesense, Python 임베딩 사이드카.

전체 크기에서 — Cerveau 자체, 7개 경계에 걸친 35개 구성 요소, 모든 호출이 선언된 포트에 바인딩됨:

S를 누르면 모든 프레임이 하나의 노드로 접히고, 프레임을 가로지르던 와이어는 하나의 라벨이 붙은 링크로 병합됩니다. 같은 파일입니다. 첫 번째와 보조를 맞출 두 번째 개요 다이어그램은 없습니다:

3 · 같은 다이어그램에서 빌드 추적하기

노드는 status를 가질 수 있습니다 — todo wip done blocked failed update. 2를 누르면 캔버스가 종류 대신 상태로 색칠됩니다. 이제 파일은 빌드 보드입니다. 에이전트는 아직 todo인 것을 읽어 마지막 세션이 멈춘 지점에서 이어가고, blocked 노드의 note는 이유를 말합니다:

4 · 더 이상 사실이 아닐 때 알기

린트는 계획이 일관적이라고 말합니다. 계획이 사실이라고는 말할 수 없습니다 — 디스크의 코드가 여전히 다이어그램이 설명하는 코드라는 것. 노드에 path(파일, 디렉터리, glob, 목록)를 주면 dgv_drift가 프로젝트를 탐색합니다 — git ls-files를 사용하므로 .gitignore가 존중됩니다 — 그리고 아무것도 일치하지 않는 path(drift/missing), 어떤 노드에도 속하지 않는 코드 디렉터리(drift/unclaimed), 같은 파일을 주장하는 두 노드(drift/shared)를 보고합니다.

이 저장소는 그 방식으로 자신의 아키텍처를 유지합니다. 모든 노드에 path가 있습니다:

드리프트가 처음 실행되었을 때, 무언가를 발견했습니다:

$ 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가 파일 하나였기 때문입니다. 넓혔고, 깨끗합니다.

두 개의 선택적 Claude Code 훅이 루프를 닫습니다 (hooks/; doctor는 당신의 경로가 포함된 설정 블록을 출력합니다):

• SessionStart는 ./dgv 안의 모든 다이어그램의 개요를 드리프트 요약과 함께 컨텍스트로 출력합니다 — 에이전트가 가장 먼저 알게 되는 것은 시스템의 모양과 지도가 낡았는지 여부입니다.

• Stop은 각 턴 후에 드리프트를 실행하고, 말할 것이 있을 때만 한 줄을 남깁니다: 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>"을 받습니다. 그러면 사유가 첨부된 정보가 되고, 그 사유는 파일과 함께 이동합니다. 오류에는 ack를 사용할 수 없습니다.

{ "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입니다. 위치는 저장되므로 직접 만든 배치가 유지됩니다. 전체 카탈로그 — 모든 종류, 프로토콜 및 린트 코드 — 는 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 — core: 스키마, 린트 규칙, 패치 의미론, 레이아웃 포함 관계, 폴딩, 내보내기, SVG, drift.

제한 사항

DGV는 소스 코드를 파싱하지 않습니다. 린트는 계획이 일관적인지 알려줄 수 있고, drift는 모든 노드가 여전히 존재하는 코드를 가리키는지, 모든 코드 디렉터리에 노드가 있는지 알려줄 수 있습니다. 그러나 다이어그램이 그린 호출이 코드가 실제로 수행하는 호출인지는 둘 다 알려줄 수 없습니다. 그것은 여전히 사람이나 에이전트가 읽어야 하며, 파일이 저장소에 있기 때문에 그 읽기를 검토할 수 있습니다.

여기에는 없음: 협업 또는 호스팅, 시퀀스 및 라이프사이클 다이어그램, 저장소 구조 탐색. 형식은 버전이 지정되어 있으므로(dgv: 1) 기존 파일을 깨지 않고 추가할 수 있습니다.

유래

Cerveau는 로컬 우선(local-first) 에이전틱 코딩 하네스입니다. docs 폴더에는 arch-viewer라는 비공개 초안이 있었습니다. 아키텍처의 Diagram.json을 읽는 Svelte Flow 캔버스로, 노드 99개, 엣지 127개, 종류가 있는 노드, 레이블이 있는 엣지로 구성되어 있었습니다. 브라우저로만 읽을 수 있었기 때문에 빌드를 수행하는 에이전트는 그것을 볼 수 없었습니다. DGV는 캔버스, 프레임, 레이아웃을 유지하고 그 아래에 계약을 둡니다: 카탈로그, 포트와 프로토콜, 선언된 멤버십, 린터, 그리고 에이전트가 동일한 파일을 읽고 쓰게 하는 MCP입니다. archify는 수리 가능한 진단을 가진 타입이 있는 중간 표현이라는 아이디어를 제공했습니다.

MIT © Mounir Belahbib