作図規約(図解ファースト)

本プロジェクトは「文章より図」が原則です。新規概念のページでは、まず図を設計してから本文を書きます。このページは全執筆者(人・AI)共通の作図規約です。

手段の使い分け

graph TD
  Q{何を伝えたい?} -->|流れ・構造・関係| M[Mermaid で作図]
  Q -->|雰囲気・比喩・世界観| G[画像生成]
  Q -->|厳密な UML が必要| U[PlantUML 等を検討<br>現状未導入・要 Issue]
  M --> MR[テキストとして差分レビュー可能]
  G --> GR[文字は入れない<br>ラベルが要るなら Mermaid へ]

Mermaid 第一選択: 構造・流れ・関係はすべて Mermaid。テキストなので差分レビューでき、テーマ(ライト/ダーク)にも自動追従する
生成画像は限定用途: ヒーロー画像・概念イメージなど。画像内に文字は入れない(崩れやすく、翻訳もできないため)

Mermaid 記法の選択表

説明したいもの	記法	用途例
プロセスの流れ・フェーズ遷移	`graph LR`	開発フェーズの全体像
階層・分類	`graph TD` + `subgraph`	プロセス体系の分類
ロール間のやりとり・承認フロー	`sequenceDiagram`	DR での承認・レビュー依頼
状態遷移	`stateDiagram-v2`	チケットや成果物のライフサイクル
判断分岐	`flowchart` + 菱形	テーラリング判断
時系列計画	`gantt`	マイルストーン計画

記法サンプル

ロール間のやりとり(シーケンス図)の例:

sequenceDiagram
  participant Dev as [人] 開発リーダー
  participant AI as [AI] レビュー支援
  participant QA as [人] 品質保証部門
  Dev->>AI: 設計書のセルフチェック依頼
  AI-->>Dev: 指摘一覧(トリアージ前)
  Dev->>QA: DR 申請(設計書 + 指摘対応表)
  QA-->>Dev: 承認 / 差し戻し

状態遷移(ステート図)の例:

stateDiagram-v2
  [*] --> Todo: Issue 起票
  Todo --> InProgress: 着手
  InProgress --> Review: 成果物提出
  Review --> Done: 受け入れ条件充足
  Review --> InProgress: 差し戻し
  Done --> [*]

プロセスの階層図解パターン

プロセスは「全体 → フェーズ内ワークフロー → 個別作業」の3階層で描きます。

1ページに全体図は1つ。ノードは7個前後まで(超えるなら分割のサイン)
掘り下げは subgraph、それでも収まらなければ別ページに分けて全体図のノードから内部リンクで誘導する
上位図のノード名と下位図のページタイトルを一致させる(読者が迷子にならないため)

graph LR
  subgraph 全体プロセス
    A[要件定義] --> B[仕様設計] --> C[実装]
  end
  B -.掘り下げ.-> D[仕様設計の<br>ワークフロー詳細ページ]

スタイル規約

ノードラベルは日本語。矢印ラベルには「何が渡るか」(成果物・承認)を書く
流れは原則 LR(横)を使い、階層・分類なら TD(縦)を使う
色は直接指定しない(テーマ自動追従を壊さないため)
ロールの接頭辞: [人] と [AI] を付けて、人とAIの分担が一目で分かるようにする

生成画像の規約

配色はヒーロー画像を基準に統一: 落ち着いた青・スレートグレー基調、琥珀色のアクセント
スタイルはモダンでフラットなテックイラスト。ダークテーマでも映えること
使用したプロンプト・モデル名は Issue か research/ のメモに記録する(再現性のため)
alt テキストを必ず付ける