コンテンツにスキップ

karasu アプリの使い方

English · 日本語(このファイル)

karasu には、.krs ファイルをリアルタイムで操作可能な図に変換するグラフィカル アプリが付属しています。利用方法は 2 通りあります。

  • karasu serve — ディレクトリ内の .krs ファイルを監視し、保存のたびに ブラウザで再描画する、ローカルのプレビュー専用サーバー。編集は普段使いの エディタで続けたまま、プレビューだけが追従します。
  • ブラウザ版プレイグラウンド https://karasu.kompiro.dev/ — エディタ・ ファイルツリー・ライブプレビューを備えたフル機能版。すべてブラウザ内で動作し、 インストール不要・データは外部に出ません。

どちらも同じプレビューペインを共有するため、後述の プレビューペインの節はどちらの使い方にも当てはまります。

karasu serve — 手元のファイルをプレビューする

Section titled “karasu serve — 手元のファイルをプレビューする”

.krs ファイルを含むディレクトリで serve を実行します。

ターミナルウィンドウ
# .krs ファイルのあるディレクトリで
npx --yes karasu@latest serve
# ディレクトリとポートを指定する場合
npx --yes karasu@latest serve ./architecture --port 4000
karasu serve
Directory : /path/to/architecture
Preview : http://localhost:3000
Watching for .krs and .krs.style file changes...

表示された URL(既定は **http://localhost:3000**)を開きます。どのファイルを 表示するかは URL のパスで決まります。

URL 表示されるファイル
/ index.krs(.krs が 1 つだけならそのファイル)
/payment payment.krs
/services/order services/order.krs

serve はプレビュー専用で、エディタは内蔵しません。次の短いループで 作業します。

  1. 普段使いのエディタ(または VS Code 拡張)で .krs を編集する。開いているファイルでも、それが import するファイルや @import する .krs.style でもよい。
  2. 保存する。
  3. サーバーが変更を検知してブラウザに通知し、図が自動で再描画される。手動 リロードは不要。

構文エラーがある間は、直前の正常な図が 「outdated」 バナー付きで表示され 続けます。詳しくは診断を参照してください。

アプリがサポートするエントリファイルは index.krs です。トップレベルの モデルをここに置けば / でそのまま開けます。

とりあえず karasu を試したいだけなら https://karasu.kompiro.dev/ を開いて ください。エディタを有効にした同じアプリです。

  • .krs 構文ハイライト付きの Monaco エディタ(ライト / ダークテーマ)。
  • .krs / .krs.style ファイルを作成・リネーム・削除できるファイルツリー。 すべてブラウザ内(OPFS)に保存されるため、再訪時も作業が残り、サーバーには 一切送信されません。
  • 入力に追従して更新される、後述と同じプレビューペイン。

プレイグラウンドは既定で index.krs を開きます。編集機能については エディタを参照してください。

初めて開いたとき:Welcome とガイドツアー

Section titled “初めて開いたとき:Welcome とガイドツアー”

初めて訪れたときは、プレイグラウンドが Welcome ダイアログとともに開き、 3 つの入口を示します。

  • サービス分割を設計する:service-split サンプルを新しいプロジェクトとして開き、 5 ステップのガイドツアーを始めます。現在のアーキテクチャ、それを持つチーム(Org ビュー)、 計画中のアーキテクチャと現在の比較(差分モード)、移行途中の状態 (@migration_target、@planned)、結果の共有のしかたを順に見ます。ツアーは左下の小さな パネルで、ツアーを終了でどのステップからでも終えられ、最後のステップでは エディタに進むで終わります。 操作を頼むステップ(ドリル、チーム依存の表示、共有か書き出し)は、その操作をすると ✓ を 示します。先へ進むのは、見終わったときに次へを押してからです。 EC サイトが自分の業務から遠ければ、Step 1 で同じガイドを給与システムの題材 (payroll-split サンプル)に切り替えられ、戻ることもできます。切り替えはサンプルと 一致するコピーがあればそれを使い、無ければ新しいコピーを開きます。
  • 既存のシステムを理解する:Getting Started プロジェクトで 4 ステップのガイドツアーを 始めます。システム全体、どう動いているか(Deploy ビュー)、誰が持っているか(Org ビュー)、 見つけたことの共有のしかたを順に見ます。サンプルのままの Getting Started があればそれを使い、 無ければ新しいコピーを開くので、編集した内容はそのまま残ります。
  • アーキテクチャの変化を追う:service-split サンプルを新しいプロジェクトとして開き、 4 ステップのガイドツアーを始めます。移行を今のシステムと比べた差分(差分モード)、モデルにある 移行の印(@migration_target、@planned、@deprecated)、目標を移行と比べた差分(残りの仕事)、 現在地の共有のしかたを順に見ます。

3 つのツアーの使い方は同じです。Welcome のサンプルが既存のプロジェクトを書き換えることはありません。 特定の場所へのリンク(ギャラリーの example や #krs-… のパーマリンク)から開いたとき、 一度どれかを選んだあとは、Welcome は出ません。コマンドパレット(Ctrl/Cmd+Shift+P)の Show Welcome… で再び開けます。同じパレットの Restart Guided Tour… は、 最後に始めたガイドを Step 1 からやり直します。以前使ったプロジェクトを、そこでの編集ごと使います。 そのプロジェクトが無ければ Welcome の入口と同じように(給与のガイドは切り替えと同じように)開き、まだどのツアーも始めていなければ サービス分割を設計するを始めます。

ツアーの途中でページを再読み込みしたり、アドレス欄からアプリを開き直したりすると、ツアーのプロジェクトで 同じステップに戻ります。特定の場所を開くリンク(ギャラリーの example、パーマリンク、別のプロジェクト)から 開いたときはツアーは戻らず、戻りたいときは Restart Guided Tour… を使います。

プレビューペインはアプリの中核で、serve でもプレイグラウンドでも同一です。

モデルは 4 つのビューで表示でき、ビュータブまたはキーボードショートカットで 切り替えます。

ビュー ショートカット 内容
System Ctrl/Cmd+1 サービス・システムのアーキテクチャ
Deploy Ctrl/Cmd+2 デプロイトポロジ(物理構造)
Org Ctrl/Cmd+3 チームとロール(組織構造)
CRUD Ctrl/Cmd+4 ユースケース × リソースの読み書きマトリクス

System / Deploy / Org が表す 3 つの次元については コアコンセプトで説明しています。

  • ズーム — 図の上でマウスホイールを回す。
  • パン — クリックしてドラッグする。
  • ドリルダウン — 子を持つノードをクリックして内部へ降りる。深さはパンくず リストで追跡される。
  • ノード詳細 — リーフノード(または情報ボタン)をクリックすると、id・説明・ タグ・関連する接続を表示するサイドパネルが開く。
  • 定義へジャンプ — ノードを Cmd/Ctrl+クリックすると、エディタがそのノードを定義した 行へ移る。定義が別のファイルにあればそのファイルを開く。子を持つノードもドリル せずにジャンプする。詳細パネルの ↗ エディタへジャンプ も同じ動作をする。
  • edge を焦点に — edge をクリックすると、両端のノードとその 2 つの間の edge 全部を、ラベルを省略せずに描いた 2 枚目の canvas がプレビューの上に開く。密な図 では長いラベルが短く描かれ、重なるラベルは描かれないので、全文はここで読む。
  • ノードを焦点に — ノードに hover すると、そのノードに繋がらない edge が薄く なる。角に出る ⇄ 関係 を押すと、そのノードと接続先が開く。片側にそれに依存する ノード、反対側にそれが依存するノードが並ぶ。中のノードや edge をクリックすると そこへ移り、ドラッグで表示範囲を動かせる(文字の上で押すと文字を選択する)。← 戻る で戻り、Esc で閉じる。 マウスを使わない場合: touch の端末ではノードの ⓘ を tap し、詳細パネルの ⇄ 関係 を 押す。キーボードでは Outline でノードを選び、コマンドパレット(Ctrl/Cmd+Shift+P) から Show Relations of Highlighted Node を実行する。開いた中は Tab でノードと edge を移り、Enter か Space で focus のあるものを開く。
  • ビュー間ナビゲーション — 関連するビューへジャンプする。例えば System のサービスから、それが動作する Deploy、所有する Org のチームへ移動。

database キャンバスのエッジの色

Section titled “database キャンバスのエッジの色”

System ビューで database をクリックすると、簡易 ER ビューに降りる。ストアの table リーフと、その間の関連が描かれる。関連の色は、その関連を誰が確認したかを表す。 線種はふだんと同じ意味で、実線が sync、破線が async。下の色は既定スタイルのもので、 .krs.style で変えられる。

色(dark / light テーマ) タグ 意味
スレートグレー、エッジの既定色(#94A3B8 / #64748B) なし .krs に table → table エッジとして記録されている。手書き、または translate --from db が宣言された外部キーから出力したもの。確認済み。
スカイブルー(#38BDF8 / #0369A1) [projected] .krs には無い。両端の entity がともにこのストアの table に対応している entity 関連から描いたもの。entity 層の断定であり、ストアに対しては誰も記録していない。
暖色寄りのグレー(#A8A29E / #78716C) [inferred] translate --from db が命名規約(外部キー宣言の無い <stem>_id / <stem>_code 列)から推測して書いたもの。関連を確認できたらタグを消す。
  • 記録済みエッジと投影エッジが同じ 2 つの table を結ぶときは、記録済みのほうだけが 描かれる。
  • 図の凡例にはこれらの色は出ない。色は既定スタイルから来ており、モデルの legend ブロックから来ているのではないため。
  • このビューはストアの完全な ER 図ではない。記録済みエッジは常に描かれるが、entity 関連が投影されるのは、両端の entity がともにこのストアの table に対応しているとき だけ。何が描かれないかは ストアスコープの ER ビュー、 描画時に付くタグの一覧は エッジへの自動タグ を参照。

パースエラー・警告・情報メッセージは図の上部のバナーに表示されます。エラーが ある間は最後に正常にパースできた図が表示され続け、 「⚠ Diagram is outdated — fix errors to update」 と表示されるため、タイプ ミスで画面が真っ白になることはありません。

プレビューの操作は、何をするかで 2 つの面に分かれています。描かれる図を変える コントロールは、図のすぐ上のパンくず行に。図を外へ持ち出すコントロールは上端の ツールバーに置かれます。両方をツールバーに並べていた頃は、通常のウィンドウ幅で 2 行に折り返していました。

  • グループ化(System ビュー、モデルに organization ブロックがある場合)— チームを選ぶと、各チームが所有するサービスを折り畳み可能な境界フレームで 囲む。フレームごとに ⊖/⊕ トグルがある。
  • ファセット(System ビュー、モデルが facet を宣言または参照している場合)— 強調したい facet を選ぶ。所属要素に色付きのリングが付き、それ以外は減光し、 legend に色の凡例が出る。メニューは開いたままなので続けて複数選べる。複数の facet に属する要素には所属数だけリングが重なり、順序は常に同じなので 2 枚の カードを一目で比較できる。overlay は グループ化と直交する — team / boundary のバンド表示と同時に読める — し、ドリルダウン・畳み込み・書き出しでも 残る。選択はビューア側の状態で、.krs には何も書かれない。選択を解除すれば 図は元の見た目に完全に戻る。 同じメニューの下部にある所属一覧は、もう一方の問い —— facet X に属する 要素はどれか —— に 1 つのパネルで答える。各 facet の description・ポリシー リンク・所属要素の一覧が出る。この一覧はコンパイルのたびに facets プロパティ から導出されるので、保守する対象ではない。facet 名をクリックすると、メニューと 同じように強調のオン / オフが切り替わる。
  • すべて畳む / すべて展開(System ビュー)— ビューに畳めるものがあるとき —— チーム境界フレーム または external / infra のレイヤー帯 —— それらを まとめて一括開閉するボタン。すべて畳むと俯瞰ビューになる(「既定で畳んでおき、 必要な所だけ開く」)。グループ化していなくても、external / infra 帯があれば 表示される。単一・非グループ化の system では、すべて展開方向で全サービスを その場に一括展開する(各サービスの domain が境界フレームに入る)—— すべて畳む の一括版。トグルは全畳み ⇄ 全開きの二値なので、external / infra 帯を持つモデル (帯は起動時は開いている)はまず「すべて畳む」表示になり、すべて畳む → すべて展開 の順で全展開に到達する。帯の無いモデルは 1 クリックで展開できる。多数のサービスを 開くと意図的に overload ヒントが出る。すべて畳むで 1 クリックで俯瞰へ戻れる。
  • エンティティ(System ビュー、エンティティを持つ domain までドリルしている 場合)— ユースケースビューをその domain のエンティティビューに切り替える。
  • ツリー表示(Org ビュー)— 組織のグリッド表示をツリー表示に切り替える。
  • チーム依存(Org ビュー、organization を宣言したモデルのみ)— 組織のグリッド 表示を、導出されたチーム依存グラフに切り替える。どのチームがどのチームに依存 しているかを owns と論理エッジの join から導く。.krs にこれを宣言する構文は 無く、同じ導出は karasu team-dependencies が表として出力する。実線が sync、 破線が async、薄い線は一方が他方の org ツリー上の内側にいる対。所有チームに 解決しなかった端点の件数がフッタに出るので、疎なグラフは「疎結合な組織」では なく「owns の記述不足」として読める。フッタの 2 行目は、囲みを跨いで所有されて いるノード(あるチームが持つノードが、別のチームが持つノードの内側にある状態)の 件数。呼び出しではなく囲みについての事実なので、ここでは矢印として描かない (同じ境界を論理エッジが跨ぐかどうかは別の話)。一覧は karasu team-dependencies が出す。
  • 全レイヤー表示 — すべてのドリルダウン階層を重ねて描画する。

ウィンドウが狭いときは、パンくずを潰す代わりにその下へ折り返します。

ツールバー — 図を持ち出すもの

Section titled “ツールバー — 図を持ち出すもの”
  • エクスポート — 現在のビューを SVG で保存。分割ボタンのメニューからは、 ドリルダウンツリー、全ビューを束ねた 1 枚の SVG、手作業で編集できる draw.io(mxGraph XML)、そして同じ全ビュー SVG をダウンロードせず新しい タブで開く全ビューを開くも選べる。
  • Share — モデルを URL に載せた共有リンクをコピーする。karasu serve では、 リンクの宛先は手元のサーバーではなく公開版の app(https://karasu.kompiro.dev) になり、受け取った人は karasu を動かしていなくても開ける。
  • Docs — 組み込みのタグ / アノテーションリファレンスを図の横に並べておける ポップアウトウィンドウで開く。公開ドキュメントサイトへのリンクも同じメニューにある。 リファレンスが答えるのは「何が書けるか」で、どのタブからもガイドと記法クックブック (いつ使うか)、Examples ギャラリー(どう描かれるか)へのリンクが出る。 ポップアウトの中でも同じ。
  • フォーカス(Ctrl/Cmd+Shift+F)— プレビューを全幅に広げる。

エディタ(プレイグラウンド)

Section titled “エディタ(プレイグラウンド)”

エディタが利用できる場合(serve ではなくプレイグラウンド)、.krs の記述は 次の機能で支援されます。

  • .krs / .krs.style の構文ハイライト。システム設定に追従するライト / ダークテーマ。
  • フォーマット(Shift+Alt+F、または ⌥ Format ボタン)で .krs を整える。 .krs.style ファイルでは代わりに ✨ Tidy ボタンが重複ルールをまとめる。
  • 入力に追従して再描画されるライブプレビュー(保存不要)。
  • 折りたたみ可能なサイドバー(Ctrl/Cmd+B)。ファイルツリー (Ctrl/Cmd+Shift+E)と現在のモデルのアウトライン(Ctrl/Cmd+Shift+O)を 切り替えられる。アウトラインのノードを選択すると図中でハイライトされる。

編集ペインには Chat と Settings タブもあります。Chat は .krs の下書きや 編集を支援する任意の AI アシスタントで、利用するには事前に Settings で API キーを 保存する必要があります。

Settings には、図 1 枚を超えて残る設定を置いています。言語・テーマ・ 表示・Chat の API キーです。

表示 → ノードの表示では、ノードの描かれ方を選べます。

  • シェイプカード(既定) — 内容に合わせて幅が変わるカード。
  • アイコンカード(非推奨) — すべてのノードを固定サイズで描き、種別の アイコンを添えます。ラベルの長さにかかわらずレイアウトが一定に保たれます。 このモードは非推奨であり、将来のメジャーバージョンで削除します(削除する版は未定です)。 外部 SVG アイコン(shape: url())を使ったシェイプカードへ移行してください。シェイプ モードでも、宣言したカード枠が描かれ、アイコンの縦横比が保たれるようになった ため、枠も絵も失わずに移行できます(docs/spec/style.ja.md の shape プロパティ節を参照)。

表示の設定は編集ペインの中にあるため、プレビューだけを描画する karasu serve では利用できません。言語・テーマ・Chat の API キーも同じ場所にあり、同じ制約を 受けます。

ショートカット 動作
Ctrl/Cmd+Shift+P コマンドパレットを開く — 全コマンドを検索して実行
Ctrl/Cmd+1 … Ctrl/Cmd+4 System / Deploy / Org / CRUD ビューへ切り替え
Ctrl/Cmd+Shift+F プレビューフォーカス(全幅)を切り替え
Ctrl/Cmd+B サイドバーを切り替え(プレイグラウンド)
Ctrl/Cmd+Shift+E ファイルツリーを表示(プレイグラウンド)
Ctrl/Cmd+Shift+O アウトラインを表示(プレイグラウンド)
Shift+Alt+F 現在の .krs をフォーマット(プレイグラウンド)

© 2026 Hiroki Kondo · Licensed underApache-2.0

Built with Cloudflare