karasu ガイド

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

タスク指向の how-to ガイド集（全5章）。構文の正確な仕様は docs/spec/、設計思想は docs/concepts.md を参照してください。各ガイドは英語版（.md）と日本語版（.ja.md）を持ちます。

推奨の読む順番

通して読むと、アーキテクチャを karasu で「設計し → 読み解き → 変えていき → 伝える」までを一周できます。後の章は前の章の語彙を前提にするため、初めての場合は上から順に読むのがおすすめです。各ガイド冒頭に前章 / 次章へのリンクがあります。

章	ガイド	対象	内容
第1章	サービス/チーム境界設計（EN）	アーキテクト	ドメイン依存からのサービス分割、逆コンウェイ戦略、チーム別ファイル分割、CRUD マトリクス
第2章	オンボーディング（EN）	中途入社・引き継ぎ	`translate` で既存資産から骨格を起こし、読み下しながら図にまとめる
第3章	進化・移行（EN）	変更を進める人	ライフサイクルアノテーション・継承、`karasu diff`、段階的移行（Strangler Fig）
第4章	アクセス経路とクライアント（EN）	プロダクトアーキテクト	`user → client → service`、`handles` / `delivers`、form-factor / capability
第5章	伝達（スタイル・凡例・CI）（EN）	全員	`.krs.style` のテーマ、`legend`、CI で図を最新に保つ、draw.io エクスポート

章の流れ

第1章 境界設計 → 第2章 オンボーディング → 第3章 進化・移行 → 第4章 アクセス経路 → 第5章 伝達
（設計）          （読解）                 （変更）            （プロダクトの面）    （図を共有物に）

第1〜3章 はアーキテクチャのライフサイクル（設計 → 読解 → 進化）に沿う。第1章で土台となる語彙（ドメイン / サービス / implicit edge / owns / ファイル分割）を学び、第2章でそれを使って既存システムを読み下し、第3章で変えていく。
第4・5章 はどの段階にも効く横串の観点だが、前章までの語彙の上に乗るため後半に置いた。第4章でプロダクトの「面」（アクセス経路）を、第5章で図を共有物にする方法（スタイル・凡例・CI）を扱う。

特定の課題だけ知りたい場合は、各章は単独でも読めます（必要な前提には章内からリンクしています）。

レンダリング済み図（自動生成 — 手で編集しない）

代表的な「hero」スニペットには、コードの直下にレンダリング済み SVG を併置しており、karasu が実際に出す auto-layout 出力をソースの隣で確認できます。fenced ```krs ブロックが単一の正典で、ブロック直上の HTML コメントマーカー（例: ）が「どのスニペットを」「どのビュー（system / deploy / org）で」レンダリングするかを指定します。SVG と ![](https://github.com/kompiro/karasu/blob/main/docs/guide/diagrams/…) 画像参照は生成物で、画像は  管理区間に置かれます。手で編集しないでください。

マーカー付きスニペットを変更したら再生成: pnpm gen:guide-diagrams
CI は pnpm gen:guide-diagrams --check を実行（push 時は lefthook も）。コミット済み SVG または画像参照が古いと失敗します。スニペットは diagrams/<id>.svg（英語）と diagrams/<id>.ja.svg（日本語）に出力し、GitHub の白背景に合わせて light テーマでレンダリングします。