karasu Guides

English（this file） · 日本語

Task-oriented how-to guides (5 chapters). For the precise syntax spec see docs/spec/; for the design philosophy see docs/concepts.md. Each guide has an English version (.md) and a Japanese version (.ja.md).

Recommended reading order

Read end to end and you traverse the full loop of working with architecture in karasu: design it → read it → evolve it → communicate it. Later chapters build on the vocabulary of earlier ones, so on a first pass, read top to bottom. Each guide links to its previous / next chapter at the top.

Ch.	Guide	Audience	Contents
1	Service/Team Boundary Design (JA)	Architects	service splits from domain dependencies, the inverse Conway maneuver, per-team file splitting, CRUD matrix
2	Onboarding (JA)	New hires / hand-offs	scaffold from existing assets with `translate`, read a system down into diagrams
3	Evolution & Migration (JA)	People driving change	lifecycle annotations & inheritance, `karasu diff`, staged migration (Strangler Fig)
4	Access Paths & Clients (JA)	Product architects	`user → client → service`, `handles` / `delivers`, form-factors / capabilities
5	Communicating Diagrams (style, legend, CI) (JA)	Everyone	`.krs.style` theming, `legend`, keeping diagrams fresh in CI, draw.io export

Chapter flow

Ch.1 Boundary Design → Ch.2 Onboarding → Ch.3 Evolution → Ch.4 Access Paths → Ch.5 Communicating
(design)               (comprehension)    (change)         (product surfaces)   (sharing diagrams)

Chapters 1–3 follow the architecture lifecycle (design → comprehension → evolution). Ch.1 teaches the foundational vocabulary (domains / services / implicit edges / owns / file splitting), Ch.2 uses it to read an existing system down, and Ch.3 changes it over time.
Chapters 4–5 are cross-cutting perspectives useful at any stage, placed later because they build on the earlier vocabulary. Ch.4 covers a product’s surfaces (access paths); Ch.5 covers making diagrams shareable (style / legend / CI).

If you only need one topic, each chapter also stands alone — in-chapter links point to any prerequisites.

Rendered diagrams (generated — do not hand-edit)

Selected “hero” .krs snippets carry a rendered SVG right below the code, so you see karasu’s actual auto-layout output next to the source. The fenced ```krs block stays the single source of truth: an HTML-comment marker above the block (e.g. ) tells the generator which snippet to render and which view (system / deploy / org) to use. The SVG and the ![](https://github.com/kompiro/karasu/blob/main/docs/guide/diagrams/…) image reference are generated — the image lives in a  region; don’t hand-edit it.

Regenerate after changing a marked snippet: pnpm gen:guide-diagrams
CI runs pnpm gen:guide-diagrams --check (and lefthook on push); it fails if a committed SVG or image ref is stale. Snippets render to diagrams/<id>.svg (English) and diagrams/<id>.ja.svg (Japanese), with the light theme for GitHub’s white background.