diagram

図は飾りではなく、理解に不可欠なものです。 読者が全体像を一度に頭の中に保たなければならない場合にだけ図を使い、文章から再構成するのではなく、全体像を把握できる最小限のビューを選びます。ここにあるものはすべて、会話内でテキストブロックまたは Mermaid として表示され、成果物ファイルが書き出されるのは最大 1 つです。

図の種類

ビューは 1 つ、多くても 2 つにします。それ以上はノイズです。

擬似コード — 言語固有のノイズを除いたロジックです。判断の分岐構造を示します。

on(request)
  if state file locked by another writer
    queue and return pending
  acquire lock
  write
  release

呼び出しツリー — 実行時の制御フローです。深さでフローの所有者を示し、重要なエッジに注釈を付けます。

acquireStateFileLockSync()
  resolveLockPath()
  openExclusive()
  writePid()

コンポーネントツリー — UI またはモジュールの構造を、重要な境界にインラインで注釈を付けて示します。

<SettingsPage> (src/routes/settings)
  <SessionList> (owns its fetches)
  <DangerZone>
    <ConfirmButton> (disabled until typed confirmation)

ファイルツリー — 責任の所在を示します。浅く保ち、ディレクトリごとに注釈を 1 つ付けます。

src/
├── hooks/        # hook registry + types
├── tools/        # MCP tool handlers
└── workflow/     # registry + projections

Mermaid — 関係者間のやり取り、データフロー、または状態遷移を示します。

sequenceDiagram
    participant CLI
    participant Hook
    participant State
    CLI->>Hook: PreToolUse
    Hook->>State: read mode
    Hook-->>CLI: allow / deny + facts

差分 — 周囲の構造がすでに存在する場合に、変更の形を示します。トピックに合った差分を選びます。

コンポーネントの変更：

 <SettingsPage>
   <SessionList />
   <DangerZone>
+    <ConfirmButton />
   </DangerZone>

ファイル配置の変更：

 src/tools/
-└── state-tools.ts
+└── state-tools/
+   ├── handlers.ts
+   └── schema.ts

制御フローの変更：

 commit()
   stage()
     hashBlobs()
+  writeObject()
   updateRef()
+    acquireStateFileLock()

状態機械の変更：

 on(request)
-  write immediately
+  if locked
+    queue and return pending
+  acquire lock
+  write
+  release

ブロック全体 — 省略すると、所有者や実行順序が分からなくなる場合は、単位全体を一度だけ、コピー可能な形で示します。

export function isRegistryEnabled(): boolean {
  const flag = process.env.OMC_WORKFLOW_REGISTRY;
  return flag !== '0' && flag !== 'false';
}

テキストでは足りない場合

UI レイアウト、変更前後の比較、または Mermaid では複雑すぎる概念には、焦点を絞った HTML ファイルを 1 つ作成します。図、インフォグラフィック、または数枚のスライドとして、製品独自の色、書体、コンポーネントに合わせてスタイルを設定し、実際のラベルとデータを入れ、デスクトップとモバイルの両方で動作するようにします。プラットフォームのオープナー（Windows では start、macOS では open、Linux では xdg-open）で開き、そこで終わりにします。成果物は 1 つだけにし、ギャラリーにはしません。

規律

• 各図は、それを補足する 2、3 文のすぐそばに配置します。
• 現在の問いへの答えに必要な呼び出し、ファイル、props、状態、境界だけを含めます。ノードを余分に加えるたび、読者の解読コストが増えます。
• 率直な答えが 1 文に収まるなら、その文を書きます。