fukurou

karasu — システムの論理・物理・組織を一つの言語で描くテキストベース DSL

  • #karasu
  • #ai
  • #productivity
  • #context engineering

TL;DR

  • karasu（鴉） は、システムの 論理・物理・組織 を1つのテキスト言語（.krs）で記述するアーキテクチャモデリングツール。
  • C4 Model / Structurizr / Mermaid に着想を得つつ、三面構造・drill-down（段階的開示）・人間と AI の共同編集 の 3 点で独自の立ち位置を取る。
  • ブラウザですぐ試せる → https://karasu.pages.dev/
  • ドキュメント → https://kompiro.github.io/karasu/ ／ ソース → https://github.com/kompiro/karasu
  • 個人の 学習プロジェクト であり、メンテナンスは ベストエフォート。.krs / .krs.style の言語仕様は v1.0（安定版） として公開する。

なぜ作ったのか

システムが育つほど、アーキテクチャの全体像は頭の中に収まらなくなります。新しくチームに入った人は「どのサービスが何を担っていて、どこにデプロイされ、誰が責任を持っているのか」を掴むのに時間がかかります。図が描かれてもすぐ古くなり、コードとドキュメントは乖離していきます。

既存のモデリングの多くは、論理的な構造（サービスやドメインの関係）を描くことには長けていても、物理的な構造（どこにデプロイされるか）や 組織的な構造（誰が所有するか）を同じ語彙で扱えません。結果として、別々のツール・別々の図に分散し、整合性を保てなくなります。

karasu は、この 3 つの面を 1つの .krs 言語 で記述できるように設計しました。人が1度に認識できる情報量には限りがあるので、構造は段階的に表現したい。そして逆コンウェイ戦略を議論するなら、論理構造と組織構造を同じテーブルの上に並べられる必要がある。この 2 つの発想が出発点です。

論理の面 — 何があり、どう繋がるか

論理ビューは、システムの内部構造を段階的に表現します。

  • system: ユーザー・クライアント・サービス・共有インフラ（database / queue / storage）
  • service: その中の domain（ドメイン）の構造
  • domain: usecase（ユースケース）と、それが触れる resource（リソース）
system Shop {
  label "オンラインショップ"

  user Customer [human] {
    label "顧客"
    role "購入者"
  }

  service Storefront {
    label "ストアフロント"
    domain Order {
      label "受注"
      usecase PlaceOrder { label "注文を確定する" }
    }
  }
  service Payment [external] { label "決済" }

  Customer   -> Storefront "注文する"
  Storefront -> Payment    "カードに請求する"
}

ポイントは、すべてを 1 枚に押し込まないことです。最上位ではサービス間の関係だけを見せ、必要になったらサービス → ドメイン → ユースケースへと drill-down して降りていきます。これは「認知負荷を抑える」ための意図的な設計選択です。karasu ではこれを scoped glance + drill-down（段階的開示 / progressive disclosure） と呼んでいます。

論理ビュー

→ ストアフロントサービスにドリルダウン。

論理ドメインビュー

→ 受注ドメインにドリルダウン。

論理ユースケースビュー

物理の面 — どこにデプロイされるか

deploy ブロックで、論理的なサービスが どの物理アーティファクトとして 動くのかを記述します。oci（コンテナ）・jar・lambda・job などの種別を持ち、realizes で論理ノードと結びつけます。

deploy Production {
  label "本番環境"
  oci api {
    label "api"
    runtime  "Node.js 20"
    realizes Storefront
  }
}

論理と物理を 分離して 記述し、realizes で明示的に橋渡しする——これが karasu の中核的なアイデアです。「サービス」と「それが動く場所」は別の関心事であり、別々に進化するからです。

物理ビュー

組織の面 — 誰が所有するか

organization ブロックで、チーム（team）・メンバー（member）と、それぞれが 所有する（owns） サービスやドメインを記述します。Slack / GitHub などの連絡先も属性として持てます。

organization Acme {
  team Commerce {
    owns Storefront
    member Alice { slack "@alice" }
  }
}

これにより、「このサービスの責任者は誰か」「逆コンウェイ的にチーム境界とサービス境界は揃っているか」を、論理構造と同じ言語の上で議論できます。

組織ビュー

特徴

人間と AI が共同編集できる DSL

.krs は AI のために設計された中間表現ではなく、人間が読み書きする独立した道具 です。だからこそ双方向性が生まれます——AI が生成した .krs を人間が手で編集でき、逆に手書きしたモデルを AI に洗練させられます。テキストである以上、差分や Pull Request も自然に扱えます。

scoped glance + drill-down

全体を 1 枚に詰め込む “at a glance” な鳥瞰図ではなく、一度に見せる情報量を絞り、必要な詳細があればその場所へ降りる——これを言語と描画の両方でサポートします。

バージョンの約束

  • .krs / .krs.style 言語仕様 — v1.0（安定版）。 後方互換性はコミットメントであり、破壊的変更を入れるなら v2 とする。
  • packages/core TypeScript API — v0.x（安定性の保証なし）。 プログラマブル API はマイナーリリース間で変わりうる。

例 — 三面を一つのファイルで

以下は、論理・物理・組織の三面を1つの .krs で記述した最小例です。

system Shop {
  label "オンラインショップ"

  user Customer [human] {
    label "顧客"
    role "購入者"
  }

  service Storefront {
    label "ストアフロント"
    domain Order {
      label "受注"
      usecase PlaceOrder { label "注文を確定する" }
    }
  }
  service Payment [external] { label "決済" }

  Customer   -> Storefront "注文する"
  Storefront -> Payment    "カードに請求する"
}

deploy Production {
  label "本番環境"
  oci api {
    label "api"
    runtime  "Node.js 20"
    realizes Storefront
  }
}

organization Acme {
  label "Acme"
  team Commerce {
    label "コマースチーム"
    owns Storefront
    member Alice {
      label "Alice"
      slack "@alice"
    }
  }
}

この 1 ファイルから、論理 / 物理 / 組織の 3 つのビューが生成されます（上の各セクションの図がそれです）。 krsのレンダリングはこちらから確認できます。

使い方

おわりに

karasu は 個人の学習プロジェクト です。Claude Code を使った開発をオープンに学ぶことも目的の1つで、メンテナンスは ベストエフォート で行います。Issue や Pull Request は歓迎します。そのうえで、言語仕様を v1.0 として固めました。

フィードバックを心待ちにしています。気になった点があれば、ぜひ GitHub の Discussion に聞かせてください。

おまけ

karasu の syntax.md を Claude 等にファイルとして読み込ませた後、任意のOSSプロジェクトのリポジトリから krs を生成させてみたのが下記のリンクです。