Diagram：説明を目に見える形にする
アーキテクチャ、状態機械、データモデルは、人とエージェントが同じ図を見れば議論しやすくなります。 Diagramは、図のソースをファイルに保持し、Canvasに表示します。提案を依頼し、ソースを編集し、結果を見て判断を見直すまで、 作業の文脈を切り替えずに進められます。
図はSpecificationの代わりではありません。曖昧さを明らかにし、判断を説明し、代案を具体化するために使えます。 契約は引き続き、適切な場所に記録します。
図はCodingAgentやSticky Noteと同じ作業グラフに参加します。ソースはファイルに残ります。
Diagramを作成・追加する
インターフェースから作成する
- CanvasのツールバーでDiagramをクリックするか、Specsのすぐ後にあるDiagramsパネルを開き、New diagramを使います。
- 形式を選び、名前を入力します。既定はMermaidです。
- 作成前に表示されたパスと拡張子を確認します。
Enterで確定し、Escapeでキャンセルします。 - Sourceに記述します。Excalidrawの場合は描画から始められます。
ツールバーのDiagramをCanvasの配置したい場所へドラッグすることもできます。パネルにフォームが開き、確定までその位置を保持します。 ツールバーをクリックして作成する場合は、表示領域が使われます。
フォームには独立したフォルダー欄はありません。ツールバーや全体のNew diagram操作では、Workspaceに設定された保存先を使います。 フォルダーの**New Diagram…**メニューでは、そのフォルダーを使います。確定前に表示されたパスを確認してください。 名前の重複や失敗はフォーム内に表示され、ファイルは上書きされません。draw.ioは外部エディターを使うため、作成形式の一覧にありません。
パネルで作成する形式を選びます。draw.ioは既存ファイルから開くため、この作成一覧には表示されません。
新しい図の保存先を選ぶ
Workspace Settings → Documentation rootsを開きます。SpecificationsとDiagramsはこれらのルートを共有し、 Diagrams専用のルート一覧はありません。
Diagrams folderは、最初のDocumentation rootからの相対パスです。既定はdiagramsなので、ルートがdocsなら
docs/diagrams/になります。architecture/diagramsのような入れ子のフォルダーを指定し、保存前に計算された保存先を確認できます。
サブフォルダーを使わず最初のルートに直接作成するには、.を指定します。
この欄の変更やルートの並べ替えは、次回以降の作成先だけを変えます。既存のファイルやNodesは移動しません。 パネルはDocumentation roots内の図を検出します。その外にあるファイルも、明示的なパスでCanvasに開けます。 検出の設定は、新たなファイルシステム権限ではありません。
既存のファイルから追加する
DiagramsパネルのAdd to Canvasを使うか、ファイルをCanvasへドラッグします。
.vl.jsonのような複合拡張子も含め、拡張子で形式が決まります。ソースは元の場所に残り、ディスク上の変更はNodeに反映されます。
SVGは明示的に選びます。 通常、.svgを開いたりドラッグしたりすると、DiagramではなくFileになります。
CodingAgentに追加を依頼する場合は、Diagramが必要だと伝えてください。同じファイルがすでにFileとして表示されていれば、
ファイルを変更せず、識別情報、位置、サイズ、Connectionsを保ったままNodeを変換します。
一つのWorkspaceで同じ参照元を表すNodeは最大一つです。Diagramの名前を変更すると、ソースのファイル名が変わります。 Nodeだけを削除しても、ファイルは削除されません。
CodingAgentと作業する
形式だけでなく、何を伝えたいかを説明してください。「きれいな図を作って」よりも、「このフローの判断と失敗経路を示して」の方が背景を伝えられます。 小さな例を使い、図がシステムに合っているか確認しましょう。
以下のプロンプトは、架空のデータを使った出発点です。担当のCodingAgentに貼り付け、送る前に名前やパスを調整してください。
Nodeの作成にはAllow workspace editingが必要です。既存のリソースは到達可能である必要があり、Guardrailsも引き続き適用されます。
構造変更の許可がなければ、ソースや手順だけを依頼してください。
パスを指定しない場合、CodingAgentはWorkspaceのDocumentation rootsとDiagrams folderを確認し、インターフェースと同じ保存先を使います。
既定の設定ではdocs/diagrams/です。プロンプト内の明示的なパスが優先されます。以下の例はdocs/diagrams/を明示しています。
別の設定済みルート内に保存してパネルから見つけたい場合は、パスを調整してください。
構文だけでなく、図を確認する
CodingAgentはソースを書き、DiagramをCanvasに追加し、現在のレンダリング結果であるrendered、failed、not_renderedを確認できます。
失敗した場合は、エンジンのエラーと、利用可能なら行番号を受け取ります。
見た目が正しいソースでも、レンダリング成功の証拠にはなりません。not_renderedは、現在のファイルについて有効な観察結果がないことを意味します。
Diagramを開くか表示位置へ移動して、表示させてください。別の版のファイルの結果、未保存のプレビュー、再起動前の観察結果は、現在の成功として扱えません。
Diagramに到達できても、直接のConnectionにdiagram_read_onlyがある場合、エージェントはソースを保持し、Nodeの名前変更や削除も行えません。
プロンプトやファイルシステムのツールで、この制限を迂回しないでください。
依頼からCanvas上の図まで
CodingAgentがCRMのエンティティ図をCanvasに作成する様子を見る (新しいタブで開きます)。
この実演は、CodingAgentと背景情報を記したSticky Noteから始まります。ユーザーが基本的なCRMのエンティティ図を依頼すると、 エージェントはExcalidrawを使い、ソースを書き、自身に接続されたDiagramをCanvasに追加します。 以下の例と同様に、Nodeの作成にはWorkspaceの編集許可が必要です。
完成した図には、Account、Contact、Lead、Opportunity、Activityと、架空のフィールドや関係が含まれます。 プロジェクトのモデルに使う前に確認してください。これは提案の例であり、実際のスキーマを分析したものではありません。 実演は作成から表示結果までを扱います。編集、エクスポート、フォルダーの整理は、このガイドの各手順で説明します。
録画は無音で、英語の画面です。入力や待機の一部は早送りされ、最終結果は通常の速度で表示されます。 上の文章だけでも、動画に頼らず実演の内容を把握できます。
説明したい内容で形式を選ぶ
すべての例は、ソースの作成とCanvasでの確認を依頼するもので、アプリのコードは実行しません。 必要なリソースの初回ダウンロードにはネットワークが必要な場合があります。ダウンロードとオフライン利用も参照してください。
異なる形式をCanvasで併用できます。画像は説明用の例です。形式と制限の詳細は以下で説明します。
Mermaid — .mmd、.mermaid
フロー、シーケンス、状態の説明を始めるのに適しています。Kavorに組み込まれたエンジンの対応種類を使うため、 Mermaidに追加されたばかりの構文も使えるとは限りません。小さな架空のフローを作るには、CodingAgentに貼り付けます。
Mermaidでdocs/diagrams/checkout.mmdを作成してください。カート → 支払い → 確認の流れと、支払い拒否の経路を示してください。
私のグラフにDiagramとして追加し、現在のレンダリング結果を確認してください。
報告されたエラーを修正してください。アプリは変更せず、結果を観察する前に成功を宣言しないでください。
期待する結果： 失敗経路が読み取れるフローと、レンダリング結果の報告が得られます。
有効な観察結果がまだなければ、成功を推測せずnot_renderedと報告します。
PlantUML — .puml、.plantuml
UML、シーケンス、Gantt、マインドマップ、ワイヤーフレームに使います。JavaScriptエンジンなので、Javaのインストールは不要です。 C4を含む標準ライブラリは必要時に取得し、C4の初回利用には追加ダウンロードが必要な場合があります。CodingAgentに貼り付けてください。
C4ライブラリでdocs/diagrams/checkout-context.pumlを作成し、顧客、店舗、外部の決済サービスを示してください。
関係を明記し、ファイルをDiagramとして追加して、現在の結果を確認してください。
ライブラリが足りない場合やエラーがある場合は、完成したと言う前に理由を報告してください。
期待する結果： 外部依存を明示した簡潔なC4コンテキスト図が得られます。 ネットワークやライブラリの不足を、図の検証成功と混同してはいけません。
Graphviz — .dot、.gv
頂点の配置によって依存関係を理解しやすくするグラフに使います。レイアウトは組み込みエンジンに含まれるものです。 CodingAgentに貼り付けてください。この例の依存関係は架空で、リポジトリから推測したものではありません。
docs/diagrams/dependencies.dotを作成してください。webはapiに、apiはbillingとcatalogに、両者はstorageに依存します。
グラフを左から右へ配置し、Diagramとして追加して、現在のレンダリングを確認してください。
実際のプロジェクトの依存関係を作り出さないでください。これは指定した内容だけの例です。
期待する結果： ラベル付きの依存関係グラフが得られます。説明用の図を、プロジェクトの診断結果として扱いません。
D2 — .d2
アーキテクチャやコンポーネント間の関係に使います。KavorはDagreとELKのレイアウトに対応し、TALAには対応しません。 CodingAgentに貼り付け、レイアウトが重要な場合は選択を明示してください。
Dagreレイアウトでdocs/diagrams/order-service.d2を作成し、顧客、API、キュー、ワーカーを通る注文の経路を示してください。
Diagramとして追加し、現在のレンダリングを確認してください。DagreかELKに対応する機能だけを使い、TALAは使わないでください。
エラーがあれば報告し、実際のインフラは変更しないでください。
期待する結果： TALAに依存せず、図に示したサービスも作成しない、読みやすいアーキテクチャ図が得られます。
SVG — .svg
図形、ラベル、構成を直接制御したいベクター図に使います。表示機能は組み込みです。 通常のFileとの区別を保つため、CodingAgentには明示的にDiagramとして依頼してください。
docs/diagrams/review-cycle.svgを作成し、Builder、Reviewer、人間の判断という三つの箱を順につないでください。
スクリプトやリモートリソースのない自己完結したSVGを使い、FileではなくDiagramとして明示的に追加してください。
現在のレンダリングを確認し、他のNodesを変更せずに結果を報告してください。
期待する結果： ベクター図がDiagramとして表示されます。拡張子が.svgというだけでFileの種類は変わりません。
Excalidraw — .excalidraw
後から視覚的に操作を続けたい、試行的な図に使います。ファイルにはExcalidrawのシーンが入り、Kavorでビジュアルエディターを使える形式です。 簡単なシーンを準備するには、CodingAgentに貼り付けます。
docs/diagrams/review-workshop.excalidrawを作成し、アイデア、実装、レビューを矢印とラベルで示す有効なシーンを用意してください。
Diagramとして追加し、レンダリングを確認してください。私がEdit drawingで編集を続けられるよう、シンプルな図にしてください。
既存のファイルは置き換えず、私のレビューが済んだとは言わないでください。
期待する結果： Edit drawingで開けるシーンが得られます。
シーンを生成するだけで、表したフローの品質が保証されるわけではありません。判断に使う前にレビューしてください。
draw.io — .drawio
ページやレイヤーを含む、この形式の図の表示に使います。View onlyです。Kavorにはビジュアルエディターがなく、SourceでXMLも編集できません。 作成や編集には外部ツールを使ってください。許可されていれば、CodingAgentがファイルシステム経由で編集することもできます。 自分の文書を上書きせず、新しい例を作るためにエージェントへ貼り付けます。
顧客 → API → データベースの1ページを持つ有効なdraw.ioファイルとして、docs/diagrams/order-overview.drawioを作成してください。
作成済みのファイルをDiagramとして追加し、現在のレンダリングを確認してください。
draw.ioにNew diagramを使わず、Kavor内で視覚的に編集できると約束しないでください。
期待する結果： Node内で閲覧できるページが得られます。後から変更する場合は、外部アプリか、許可されたソース編集を使ってください。 Kavorはファイルの変更を反映します。
Vega-Lite / Vega — .vl.json、.vg.json
データのグラフに使います。.vl.jsonはVega-Lite、.vg.jsonはVegaを選びます。文法が異なるため、拡張子を変えるだけでは切り替えられません。
ネットワークに依存しない例にするには、CodingAgentに貼り付け、データの埋め込みを依頼してください。
Vega-Liteでdocs/diagrams/build-times.vl.jsonを作成し、架空のビルド時間12秒、18秒、9秒を棒グラフで示してください。
データはJSON内に含め、軸に名前を付け、外部のデータセットは取得しないでください。
Diagramとして追加し、現在のレンダリングを確認してください。
期待する結果： 比較しやすく、単位が明確なグラフが得られます。Vegaを使う場合は、その文法と.vg.jsonのパスを明示的に依頼してください。
エンジンがキャッシュ済みでも、リモートのデータセットにはネットワークが必要です。
WaveDrom — .wavedrom
デジタル信号のタイミングに使います。Kavorで使うソースは、有効なJSONであり、JavaScriptのスクリプトではありません。 簡単なハンドシェイクを表示するには、CodingAgentに貼り付けます。
clock、request、acknowledgeの8サイクルを、有効なJSONでdocs/diagrams/handshake.wavedromに作成してください。
acknowledgeがrequestに応答するタイミングを明示し、スクリプトは実行しないでください。
Diagramとして追加し、現在の結果を確認して、エンジンが報告したエラーを修正してください。
期待する結果： 時間軸上でそろった信号が得られます。図は例を説明するもので、ハードウェアの測定を証明しません。
nomnoml — .nomnoml、.noml
簡潔なUMLのスケッチに使います。nomnoml独自の構文で、PlantUMLとは互換ではありません。CodingAgentに貼り付けてください。
docs/diagrams/order-model.nomnomlを作成し、Order、OrderItem、Productの関係と少数の属性を示してください。
nomnomlの構文を使い、Diagramとして追加して、現在のレンダリングを確認してください。
架空のモデルにとどめ、プロジェクトのクラスやスキーマは変更しないでください。
期待する結果： 議論用のエンティティのスケッチが得られます。図を自動的な実装に変えるものではありません。
Pikchr — .pikchr
PICスタイルの描画言語で技術図を構成するために使います。任意のPICプログラムではなく、Pikchrの文法を使います。 小さな処理の図を作るには、CodingAgentに貼り付けます。
docs/diagrams/processing.pikchrを作成し、入力、変換、出力をラベル付きの箱と矢印で示してください。
Pikchrの構文を使い、Diagramとして追加して、現在のレンダリングを確認してください。
エンジンがソースを拒否した場合は、観察したエラーを修正してから結果を報告してください。
期待する結果： シンプルなベクター図が得られます。もっともらしい構文でも、エンジンの結果を観察する代わりにはなりません。
Svgbob — .bob
ASCIIのスケッチをベクター図に変換するために使います。文字の位置合わせもソースの一部です。 CodingAgentに貼り付け、ファイル内の位置合わせを維持してください。
docs/diagrams/request-path.bobをASCIIで作成し、ClientとServerというラベルの二つの箱を矢印でつないでください。
位置合わせを保ち、Diagramとして追加して、現在のレンダリングを確認してください。
画像を貼るだけで済ませず、テキストのスケッチを編集可能なソースとして残してください。
期待する結果： テキストのスケッチから図が得られます。空白の変更によって形が変わる場合があります。
DBML — .dbml
テーブル、列、リレーションについて議論するために使います。ソースはSQLではなくDBMLです。 レンダリングしても、テーブルの作成やマイグレーションの実行は行われません。架空のモデルを使い、CodingAgentに貼り付けます。
docs/diagrams/shop-schema.dbmlを作成し、customers、orders、order_itemsのキーとリレーションを示してください。
Diagramとして追加し、現在のレンダリングを確認してください。
実際のデータベースには接続せず、マイグレーションも生成せず、この例を私のプロジェクトのスキーマとして扱わないでください。
期待する結果： レビュー可能なデータモデルが得られます。後から実際のスキーマを表したい場合は、許可された情報源を提供し、 発見事項、仮説、判断を分けてください。
図とソースを切り替える
- Diagram： 視覚的な結果を中心に表示します。既存のファイルはこのビューで開きます。
- Source： ソースを表示します。編集可能な形式は、Filesと同じエディターと保存の仕組みを使います。
- Split： 左にソース、右にプレビューを表示し、切り替えずに調整・比較できます。
ソース形式の新規ファイルはSourceで開きます。Excalidrawでは、Edit drawingでビジュアルエディターに入り、 Finish editingで図の表示に戻ります。変更は同じファイルと保存の仕組みを使い、図専用の別のSaveはありません。 視覚的な編集とソース編集は、同時には有効になりません。
draw.ioのSourceは読み取り専用です。外部エディターで作業するにはOpen with default appを使います。
Diagramビューでは、右ボタンでドラッグすると図の内部表示を移動できます。ピンチ、またはCtrl/⌘ + ホイールで、Canvasを動かさずズームできます。
ズーム操作とFitを使って表示範囲を調整してください。Node自体を移動する場所は引き続きヘッダーです。
Excalidrawのエディターには独自の操作があります。
ソース形式では、Splitでコードと結果を並べて確認できます。Excalidrawでは図そのものを視覚的に編集することもできます。
プレビューが古くなった場合
編集後のレンダリングに失敗すると、Preview out of dateとエンジンのエラーとともに、最後に成功した結果が表示され続ける場合があります。 これは以前のソースの結果であり、新しいソースの成功を証明しません。実際の行番号が報告されていれば、Sourceでその行を開けます。 一度もレンダリングに成功していないファイルでは、ソースと失敗内容が表示されます。
構文を修正し、保存して、現在の結果を確認してください。保存の問題や競合は、レンダリング失敗とは異なります。 画面に図が残っているという理由で、ローカル編集を破棄しないでください。
共有用にエクスポートする
Exportでは、Node内に収まる範囲の切り抜きではなく、図全体のSVGとPNGを出力できます。 draw.ioでは、アクティブなページとそのレイヤーを出力します。プレビューが古い場合は、最後に成功したレンダリングを使い、そのことを通知します。 レンダリング済みの結果が一つもなければ、エクスポートは利用できません。
Canvasに追加せずDiagramsパネルを使う
パネルはDocumentation roots内を再帰的に調べて図のファイルを検出し、.gitignoreを尊重します。
名前やパスで検索し、All formatsで形式を絞り込めます。Workspace内の全ファイルを検索するものではありません。
一覧は、ディスク上の実際のフォルダー階層を反映します。検索や形式フィルターを使わない場合は、空のフォルダーも含みます。 ディレクトリを展開・折りたたんで移動してください。ルートが複数あれば、ツリーはルートごとにまとめられます。
SpecsとDiagramsは、同じDocumentation rootsを表示します。一方のパネルで作成したフォルダーは、もう一方にも現れます。 コピーではなく、ディスク上の同じフォルダーだからです。Specificationが図になったり、そのライフサイクルが変わったりすることはありません。
- Preview： Nodeを追加せず、読み取り専用の表示を開きます。行へのホバーや選択だけでは開きません。
一度に開けるプレビューは一つです。
Escapeで閉じると、操作にフォーカスが戻ります。 - Add to Canvas： 参照元を追加します。Nodeがすでにあれば、既存のものを表示します。
- New diagram： 形式と名前を指定し、インラインフォームから作成します。
- Show in File Manager： ファイルやフォルダーの場所を、システムのファイルマネージャーで表示します。
プレビューでは、その形式のエンジンのダウンロードが必要な場合があります。 閉じた後に結果が遅れて届いても、別のファイルの有効なレンダリング結果にはなりません。
PreviewではNodeを作らず図を確認できます。Add to Canvasは別の操作です。
フォルダーを作成・整理する
ツリー内のフォルダーでコンテキストメニューを開きます。
- New Diagram…： Diagrams folderの既定先とは異なる場合も、そのフォルダー内に作成するインラインフォームを開きます。 形式を選び、名前を入力し、パスを確認してください。
- New Folder…： 実際のサブフォルダーを作成します。図が必要になるまで空のままでも構いません。
- Rename Folder…： 別の親ディレクトリを選ぶのではなく、フォルダー名を変更します。影響するDiagram Nodesは新しいパスに追従します。
- Show in File Manager： システムのファイルマネージャーで場所を開きます。
設定されたDocumentation roots自体は、これらの操作で名前変更や削除ができません。 検出ルートや新規作成の既定先を変えるには、フォルダーを削除せずWorkspaceの設定を使ってください。
ファイルの名前変更・移動・バージョン管理
図のコンテキストメニューの**Rename Diagram…**は、.vl.jsonなどの複合拡張子も保ったままファイル名を変更します。
移動するには、行をツリー内の別のフォルダーやルートへドラッグします。Gitで追跡済みのファイルはgit mvで移動し、未追跡のファイルも移動できます。
ファイル名の変更、親フォルダーの名前変更、図の移動後も、Diagram Nodeはパスに追従します。 再追加は不要で、Nodeの識別情報とConnectionsは保持されます。
Gitリポジトリでは、Commit Diagramがそのファイルのパスだけを含むコミットを作成し、生成されたハッシュを表示します。 他のパスですでにステージ済みの変更は含みません。CanvasにNodeがなくても使えます。図のキャプチャではなく、ファイルをバージョン管理する操作です。
未保存のローカル編集がある場合は、ソースの変更やコミットの前に、提示された選択を解決してください。 操作に失敗したら、パネルのメッセージを読み、原因を修正します。操作を開始しただけで、移動やコミットが完了したと考えないでください。
ファイルとNodeを区別して削除する
ファイルのメニューにあるDelete Diagramは、確認後にソースを削除し、そのDiagram Nodesも削除します。 ファイルを残したままCanvasからNodeだけを削除する操作とは異なります。
Delete Folder and Contentsは確認が必要で、認識された図のファイルと実際のディレクトリだけを含むサブツリーに限って削除できます。 Specification、別の種類のファイル、隠し項目、シンボリックリンクを検出した場合、何も変更する前に操作を拒否し、 混在する内容を扱うにはFilesを使うよう案内します。この検査はDiagrams固有のもので、Specsパネルの削除ルールは変わりません。
追跡済みの図を個別に削除する場合、KavorはGitの削除手順を使います。 ローカル変更などの理由でGitが拒否した場合は、示された状態を解決してから再試行してください。確認は、それらの変更を強制破棄する許可ではありません。
ソースをグラフに参加させる
到達可能なDiagramは、CodingAgentの作業にソースと視覚的な結果を提供します。すべてのエージェントを直接接続する必要はありません。
そのペアにdiagram_read_onlyを適用したい場合には、直接のConnectionが重要です。
Diagram + TerminalのConnectionは、File + Terminalと同様に、選んだ環境変数を通じてソースの絶対パスを提供します。 値はパスであり、レンダリングしたSVGやPNGではありません。セッションの開始前に設定するか、パラメーターの変更を受け取るために再起動してください。 Connectionsのマトリクスも参照してください。
ダウンロード・プライバシー・オフライン利用
図はKavor内でレンダリングされ、外部のレンダリングサービスには送信されません。 エンジン、フォント、補助リソースは必要時にダウンロード・検証され、アプリのデータキャッシュに保存されます。 KavorやWorkspaceを開くだけで、すべての形式がダウンロードされることはありません。SVGの表示機能は組み込みです。
初回利用後、取得済みのリソースはオフラインでも再利用できます。Excalidrawのエディターは編集を開始したときだけダウンロードされます。 C4などのPlantUMLライブラリやdraw.ioのリソースも、初回ダウンロードが必要な場合があります。 Kavorの更新でそれらのリソースが変更されると、次回利用時に再ダウンロードが必要な場合があります。
初回利用がオフラインの場合やダウンロードに失敗した場合、Nodeには理由とRetryが表示されます。 編集可能な形式のソースは引き続き利用できます。リソースを取得できる状態になったら再試行してください。
エンジンがキャッシュ済みでも、ネットワークが一切不要とは限りません。 内容自体が画像、データセット、その他のリモートリソースを参照することがあります。 ローカルのincludeは図のフォルダーを基準に解決され、変更が図に反映される場合があります。 知らないソースは開く前に確認してください。オフラインで使うには、自己完結した内容を選び、必要なリソースをすべて事前に準備します。
図の表示領域は、アプリの特権的なインターフェースから隔離されています。それでも、図の参照先が信頼できる情報源になるわけではありません。 CodingAgentに生成や分析を依頼する場合、providerの関与は選んだハーネスの条件に従います。 ローカルでのレンダリングと、モデルのローカル処理を混同しないでください。
次に読む
- 元のファイルを不要にコピーせず、Canvasにコンテンツを追加する。
- 判断はSpecificationに残し、図で説明する。
- サポートされるConnectionsとCodingAgentsのコンテキストの境界を確認する。