図は飾りではなく、構造を支えるものです。 散文だけで読者に全体の形状を頭の中で保持させる場合にのみ、図を使ってください。その際、読者が文章から形状を再構築しなくて済む最小のビューを選びます。ここにあるものはすべて、会話内でテキストブロックまたは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> (自身のフェッチを所有)
<DangerZone>
<ConfirmButton> (確認入力が完了するまで無効)
ファイルツリー — 責任の所在。浅く保ち、ディレクトリごとに1つの注釈:
src/
├── hooks/ # フックレジストリ + 型
├── tools/ # MCPツールハンドラ
└── workflow/ # レジストリ + プロジェクション
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レイアウト、before/after比較、またはMermaidには複雑すぎる概念: 1つの焦点を絞ったHTMLファイルを書きます — 図、インフォグラフィック、または数枚のスライド — プロダクト自身の色、タイプ、コンポーネントでスタイルを整え、実際のラベルとデータを入れ、デスクトップとモバイルで動作するようにします。プラットフォームのオープナー（Windowsでは start、macOSでは open、Linuxでは xdg-open）で開き、そこで止めます: 1つのアーティファクト、ギャラリーではありません。
規律
- 各ビジュアルを、それがサポートする2〜3文のすぐ隣に配置します。
- 現在の質問に答えるために必要な呼び出し、ファイル、プロパティ、状態、境界だけを運びます — 余分なノードはすべて読者にかかるデコードの負荷です。
- 正直な答えが1文で収まるなら、その文を書きます。