用語集

English · 日本語（このファイル）

karasu のコアな語彙のクイックリファレンスです。karasu は C4 Model に着想を得つつ独自の語彙を持ち、システムの論理・物理・組織の構造を分離して表現します。

このページは 正典ではなくインデックス です。各項目は 1 行の定義と、正典となるドキュメント（コアコンセプト・構文・スタイル・タグ・アノテーション・診断）へのリンクを示します。ここの定義と正典が食い違う場合は正典が優先されます — リンク先を参照してください。

Related TPLs: TPL-20260511-02 — この用語集は他所に正典がある定義の再掲であり、各項目はリンク先の正典と矛盾してはならない。

コアコンセプト

三面構造 — karasu はアーキテクチャを 3 つの独立した面で記述する。論理（何を / なぜ）・物理（どのように）・組織（誰が）。別々のファイルに書きつつまとめてナビゲートできる。 Concepts
論理構造 — 何を / なぜ の面。アクセス経路（誰がどのクライアント経由でどのサービスに到達するか）とサービス階層（各サービスが含む業務機能）。 Concepts
物理構造 — どのように の面。論理サービスを実際に動かすデプロイユニット。論理モデルとは別の .krs ファイルに書く。 Concepts
組織構造 — 誰がの面。どのチームがどのサービス / ドメインを所有するかをアーキテクチャと並べて明示する。 Concepts
ドリルダウン — モデルを理解する方法。限定された俯瞰から始め、子を持つノードへ降りて詳細を見る。 Concepts
scoped glance — ドリルダウンの背後にある認知設計の原則。一度にすべてを描くのではなく、限定された視野を提示する。 Concepts
ghost — 現在の視点の外にありながら依存に参加するノードの半透明プレースホルダー。視野が狭まっても境界を保つ。 Concepts
テキストが正典 — 図やバイナリではなく .krs テキストが正典のモデル。すべての入力経路はテキストに収束する。 Concepts

論理要素の種別

system — 所有サービス・外部サービス・クライアント・到達するユーザーを含む境界。 Concepts
service — 業務能力の独立した単位。アクセス経路とサービス階層の中間層。 Concepts
domain — サービス内の業務関心の境界。DDD の Bounded Context に近く、サービス間依存を論じる粒度。 Concepts
usecase — ドメイン内の業務操作 / タスク。リソースへの CRUD 操作を宣言する粒度。 Concepts
resource — usecase が操作する対象。テーブル・外部 API・ファイルなど。 Concepts
user — システムを駆動するアクター。[human] / [ai] でタグ付けする。 Syntax
client — プロジェクト自身がユーザーの代理として出荷するソフトウェア（mobile / web / desktop / cli / device / extension / embed）。サードパーティのブラウザやエージェントとは区別する。 Concepts
form-factor タグ — client に付く 7 つの認識されるタグ（[mobile]・ [web]・[desktop]・[cli]・[device]・[extension]・[embed]）。ユーザーがシステムに到達する面を分類する。 Syntax
infra — サービスが共有するデータストア。system レベルで宣言する: database（table の集まり）・queue（メッセージ）・storage（バケット）。サービスが infra に依存し、逆はない。 Syntax

関係

エッジ — 論理ノード間の有向の関係。-> は同期、--> は非同期の通信 / 依存。 Concepts
explicit / implicit エッジ — explicit は手で書くエッジ。implicit はドメインレベルのエッジがサービス境界をまたぐときに service レベルで合成される（[implicit] タグ付き）。 Concepts
集約 — 同じサービス対の間の複数のドメインエッジを、system ビュー上で同期 / 非同期ごとに 1 本の implicit エッジにまとめること。 Concepts
realizes — 物理のデプロイユニット（具体）から、それが実装する論理の service / domain / client / infra ノード（抽象）へ向かう関係。 Concepts
owns — team の中で宣言する、チームが service / domain などの論理ノードを所有するという関係。 Concepts
handles — client / service が呼び出し側に公開する domain id を宣言するプロパティ。one-hop の expose 規則で検証される。 Syntax
delivers — service から、それが出荷する client への関係（BFF / SSR パターン）。ビルドパイプラインではなく所有と出荷の関係。 Syntax

物理 / デプロイの語彙

デプロイユニット — 論理ノードを realize する物理の形態。種別: war・jar・oci・lambda・function・assets・job（単発、または schedule 付きで定期実行）・artifact（その他全般）。 Syntax
store — マネージドなデータストア（Aurora・SQS・S3 など）を realize する専用のデプロイ種別。type と realizes を持つが runtime / schedule は持たない。 Syntax

組織の語彙

organization — 組織階層のルート。ネストした team を含む。 Syntax
team — 責任を持つグループ。service / domain を所有し、member を含み、親 team の下にネストできる。 Syntax
member — team に属する個人。連絡先プロパティ（slack・github など）を任意で持つ。 Syntax
role — user がシステム内で何をするかの短い記述。アクターの類型であり、 認可の仕組みではない（RBAC ではない）。 Syntax

タグとアノテーション

タグ — アーキテクチャ上の位置や役割を表す [name] 宣言（例: [external]）。スタイルが反応する。 Tags & annotations
アノテーション — ライフサイクル / 開発状態を表す @name 宣言。上書きされない限り子ノードに継承される。 Tags & annotations
タグとアノテーションの違い — タグは ノードが何であるか（位置 / 役割）、アノテーションは ライフサイクル上のどこにいるか を表す。 Tags & annotations
[external] — システム境界の外にあるノードに付くタグ。破線の枠とグレー基調で描画される。 Tags & annotations
システム自動付与タグ — karasu がエッジに自動で付けるタグ: [implicit]・ [cyclic]・[read] / [write]（usecase の CRUD 操作から）。 Tags & annotations
ライフサイクルアノテーション — @deprecated・@new・@experimental・ @migration_target。一部はパラメータ（until・from）を取る。 Tags & annotations
アノテーションの継承 — 親のアノテーションは、子が自前のものを持つまで子へ流れ、drill-down をまたいでライフサイクルの文脈を保つ。 Concepts
capability — client が要求するデバイス / ブラウザの権限（オープンセットの識別子）。ストレージである resource とは区別する。 Tags & annotations

CRUD

operations — usecase が resource に対して行う CRUD 動詞（create / read / update / delete）。 Syntax
verb-decoration — ドメインの動詞を CRUD 意図に対応づける verb:crud 記法（例: list:read・enqueue:create）。独自の語彙を保ちつつ CRUD マトリクスに反映できる。 Syntax
CRUD マトリクス — 宣言された operations から導出される usecase × resource の読み書きマトリクス（ビュー、または karasu matrix で出力）。 Syntax

スタイル

.krs.style — セレクタを視覚プロパティに対応づけるスタイルシート。CSS のようにモデルにカスケードする。 Style
セレクタ — 種別・タグ・アノテーション・id、またはそれらの複合でノードやエッジを対象にする CSS 風のパターン。 Style
詳細度 — 複数のセレクタが同じノードに一致したときどのルールが勝つかを決めるスコア（種別 = 1 … id = 100）。 Style
レイアウトヒント — レイアウトを誘導する escape-hatch プロパティ（column・ direction・label-position・label-offset）。エンジンは強制しない。 Style
凡例（legend） — 色と意味の対応を宣言するトップレベルブロック。フッター帯として描画される。項目は swatch（リテラルの hex）か ref（スタイルカスケードで解決）。 Syntax

診断

規則（rule） — 言語が何を許し何を禁じるかの言明（例:「エッジはそれを囲むブロック内から発する」）。 Diagnostics
診断（diagnostic） — 規則違反を報告する名前付きの仕組み。診断コード （例: edge-source-mismatch）で識別される。 Diagnostics
診断コード — 診断の安定した（リネームされない）文字列 id。LSP・アプリ・ツールが消費する。 Diagnostics
重大度（severity） — 診断のレベル: error（モデルが不正で構文が拒否される）・ warning（直すべき実害のある欠陥）・info（欠陥ではない事実）。 Diagnostics
warn-don’t-error — 未解決の参照は warning として報告し、source ノードを残す。リンク切れがあっても構造的事実が生き残る。 Diagnostics
ドメイン分散 — 同じ domain id が 1 つの system 内の複数 service に現れること。 error ではなく info として提示される。 Concepts
循環依存 — 同期（->）エッジが作るサイクル。静的に検出され、[cyclic] を付与し赤で描画される。非同期エッジは意図的な疎結合として除外される。 Concepts

マルチファイル

import — 別の .krs ファイルの内容を取り込むこと。named （import { Foo } from "p.krs"）・whole-file（import "p.krs"）・directory （import "dir/"）。 Syntax
system 再オープン — 同じ system id が複数ファイルに現れると、重複ではなく 1 つのブロックに merge される（衝突時はルートに近いファイルのプロパティが勝つ）。 Syntax

プロジェクト運営の語彙

これらはモデリング言語ではなく、karasu プロジェクトの運営 に関する用語です。コントリビュート時に役立ちます。出典はサイトではなくリポジトリにあります。

Design Doc（設計ドキュメント） — 「どう作るか」の詳細設計（制約・代替案・実装方針）。決定が下りるまで docs/design/ に置く。決定後は ADR に昇格させ、 Design Doc は削除する。 process.md
ADR（Architecture Decision Record） — 確定した 設計判断（採用・見送り）の簡潔な記録、すなわち「なぜそうしたか」。docs/adr/ に置く。 docs/adr/
TPL（Test Perspective Library / テスト観点ライブラリ） — 再発しうる失敗パターンを検証可能な観点として構造化した記録。docs/test-perspectives/ に置く。各観点は proactive（原則・非目標から事前に予測） か retrospective（過去の bug から事後に一般化）。ADR が 過去の判断 を残すのに対し、TPL は 未来の検証 を促す。 docs/test-perspectives/
受け入れテスト（AT） — 変更の受け入れ基準の記録。docs/acceptance/ に置き、どの基準が自動化済みか / 手動確認かを示す。 process.md
ロードマップ — karasu の全体方針と Syntax v1.0 readiness を記す living ドキュメント。docs/roadmap.md に置く。 roadmap.md

用語集