Visuals
図のスタイルガイドと索引
複数の人が描いた図でも「同じ著者の本を読んでいる」一貫感が出るよう、配色・線幅・フォント・図種までを規約として明文化しています。
図の 8 種類
「何を伝えたいか」によって最適な図種は変わります。本ガイドではこの 8 種類を主に使い、 読者がどの図を見ているか直感的にわかるよう、種類ごとにアイコンと配色を一定にしています。
概念図
「Agentとは何か」のような中核概念を、アナロジーや擬人化で1枚絵に落とすもの。
- · Agent = 関数 + 知性 + ツール
- · Toolの位置づけ
シーケンス図
User / Agent / LLM / Tool の往復を時系列に追う。Mermaid sequenceDiagram。
- · LLM呼び出し
- · Tool呼び出し
- · Hand-off
アーキテクチャ図
コンポーネントとデータフローを示す箱と矢印の図。
- · MCPクライアント連携
- · Multi-Agent構成
データ形状図
JSONスキーマや入出力の対応関係を視覚化する。
- · output_typeの構造
- · Toolの引数/戻り値
コード注釈図
コードに矢印で「各行が何をしているか」を直接書き込む解説図。
- · Agent定義の3要素
- · @agent.toolの構成
比較図
Before/After や Option A vs B を並列で示す。
- · 生テキスト vs 構造化出力
- · GLA vs Vertex AI
状態遷移図
リトライ・Reflection など、内部状態の遷移を矢印で示す。
- · ModelRetryの流れ
- · Reflectionサイクル
メンタルモデル
「Agentは関数 + α」のような、頭の中にイメージとして残す図。
- · Agentの正体
- · Dependenciesの注入位置
デザイントーン
すべての図は次のスタイル規約に従います。レビューで規約逸脱を見つけたら作り直します。
配色 / メイン
#E5005B
PydanticPink
配色 / アクセント
#4285F4
GeminiBlue
フォント
Aa あ
Inter (英)
Noto Sans JP (日)
プリミティブ
角丸 8px
線幅 1.5px
背景 #F8F8F8
編集ルール
ガイドの一貫性は、図の品質よりも「規約が守られているか」で決まります。次の 4 つは PR レビューで必ずチェックします。
1スクロール 1 図
画面 1 スクロール (約 800〜1000px) ごとに必ず 1 つは図を配置します。文章だけが連続するページは「構成失敗」とみなし、レビューでブロックします。
Mermaid を第一選択肢に
テキストとして差分管理ができるため、構造図・フロー・シーケンスはまず Mermaid で書きます。手書き感が必要な箇所のみ Excalidraw に逃げます。
ヒーロー図はレッスン冒頭に必須
各レッスンの最初に「中核概念を 1 枚で表すヒーロー図」を必ず配置します。文章を読まずとも要点が掴める設計です。
図は内容を“補完”するもの、装飾ではない
「図があるから格好いい」ではなく、「この図がないと伝わらない構造がある」場合にのみ図を増やします。冗長な図はレビューで削ります。
作画ツールの使い分け
図の用途によって最適なツールは異なります。ガイド全体ではこの 4 ツールに限定し、 ツールごとに役割を固定しています。
Mermaid
構造図・フロー・シーケンス
MDXに直接埋め込み。差分レビュー可能。
Excalidraw
手書き風 / 親しみやすさ重視
アナロジーや概念絵に。SVG書き出しで public/diagrams/ に置く。
Figma
厳密なレイアウトが必要なとき
ピクセル単位の調整が要る場合のみ。SVG書き出し。
Screenshot
実物を見せたいとき
Logfireダッシュボード等。public/screenshots/ に置く。
※ 全レッスンの図索引 (どの図がどのレッスンで使われているか) は、レッスン本体の公開と同時に このページに追加されます。