Imported from yktsnet/dotfiles-public (
.claude/skills/mermaid-diagram/SKILL.md). Install upstream withnpx skills add yktsnet/dotfiles-public --skill mermaid-diagram. Copyright stays with the author.
mermaid-diagram
Mermaid 図の基準と手順を持つ。目的はきれいな図を描くことではなく、その図が無いと伝わらないものだけを、読める大きさで描くこと。
前提は、GitHub が ```mermaid フェンスを本文カラム幅（約 768px）に縮小して描画すること。図を SVG に焼かずフェンスのままコミットする（テーマ追従と差分閲覧が効かなくなるため）。したがって図の幅はそのまま文字サイズになる。
README の Architecture 節からは repo-readme Skill が本 Skill を呼ぶ。単体でも使える。
1. 基準
描くか、描かないか
分岐・失敗経路・境界をまたぐグループ化・対比のどれも無いなら、図にしない。 順番に起きるだけの処理は番号付きリストの方が速く読める。
| 主題 | 図でしか表せない理由 |
|---|---|
| 分岐 | 条件で処理が割れて、また合流する。文章では分岐の先を読み終えるまで全体が見えない |
| 失敗経路 | リトライループ・複数の終了状態。制御フローは線形の文章に写せない |
| 境界 | デバイス・ネットワーク・信頼境界をまたぐ配置。subgraph でしか表せない |
| 対比 | before / after、あるべき姿と現状。並置そのものが主張になる |
「全体像」は主題ではない。 描くと分岐の無い一直線か、抽象度の混ざった図になる。全体像が要るならディレクトリ構成表かコンポーネント表で出す。
図を落とすときは中身に合った形へ置き換える（図をやめることと情報を捨てることは別）。
| 図の中身 | 置換先 |
|---|---|
| 順番に起きる処理の列挙 | 番号付きリスト |
| 名前と役割・段の対応 | 表 |
| 1ステップだけの変換 | 一文 |
描くと決めたら、そのリポで一番おもしろい判断が1ノードに潰れていないかを見る。潰れているなら主題が間違っている。そのノードを展開したものを描き、周辺のパイプラインは本文に落とす。
幅 — 縦は無料、横は有料
| 規則 | 理由 |
|---|---|
TD を既定にする。LR はチェーンが4ノード以下のときだけ |
LR の幅 ∝ チェーン長、TD の幅 ∝ 分岐本数 |
| エッジラベルは最短。API 列挙・引数・条件式を載せない | ノードを増やさず幅だけ増やす |
| ノードラベルは全角12文字程度まで。詳細は図の下の本文へ | 長いラベルはランク全体の幅を押し広げる |
横並びの subgraph は2つまで。3つ以上なら TD で縦に積む |
subgraph は枠とパディングぶんの幅を食う |
しきい値は運用で調整してよい。動かさないのは「幅が文字サイズである」という前提の方。
幅はレンダリングせずに見積もる。最長ランクのノード数 × その行のラベル長 + エッジラベル長の合計が目安（LR なら最長ランク＝チェーン全体、TD なら最も広い分岐の段）。削る順序は エッジラベル → ノードラベル → 向きの変更 → 図の分割。
形と線種に情報を載せる
形と線種は幅を増やさずに情報の次元を1つ足す。全部同じ四角・同じ矢印の図はこの余地を捨てている。
| 記法 | 型 |
|---|---|
([ ]) |
アクター（人・外部の呼び出し元） |
{{ }} |
サービス・変換器 |
[( )] |
データストア |
{ } |
判断・分岐点 |
[/ /] |
外部からの投入・ファイル |
[ ] |
それ以外の処理 |
| 記法 | 意味 |
|---|---|
--> 実線 |
ローカル・同一プロセス内 |
-.-> 点線 |
ネットワーク越し・非同期 |
==> 太線 |
人間の物理操作・主経路 |
割り当ては固定ではないが、1つの図の中では必ず一貫させる。絵文字は幅ゼロの視認アンカーとして、種類が変わる点（アクター・外部サービス）にだけ置く。
記法: 改行は \n ではなく <br/>。ラベルに記号を含むときは ["..."] で引用する。
抽象度を混ぜない
概念（ルート・フェーズ・レイヤー）と実体（プロセス・ファイル・サービス）を同じ平面に置かない。 概念名の subgraph の外に具体的なミドルウェアを並べる形になったら、subgraph を捨てて構造（合流・分岐）に語らせる。
分けるか、まとめるか
1図＝1主題。 分けるかどうかは主題の数で決まり、図の大きさでは決まらない。分けてよい軸は3つに限る。
| 軸 | 例 |
|---|---|
| 時間 | ビルド時 / 実行時、セットアップ / 定常運用 |
| 正常系 / 異常系 | 主経路 / 停止・リトライ・強制終了の経路 |
| before / after | 移行前 / 移行後 |
まとめる前に、片方が単独で主題を持つかを見る。持たない図はまとめる対象ではなく消す対象。分けたら各図に主題を示す見出しか一文を付け、図をまたぐ同じノードはラベルを一致させ、分割の軸を本文で明示する（「以下は正常系。停止経路は次の図」）。
2. 手順
| 入力 | モード |
|---|---|
| 図がまだ無い | 新規 |
| 既存の図がある（読みにくい・直したい・棚卸し） | 監査 |
新規
- 箇条書きで書く。 足りるなら図を作らず、置換先の形に納める。大半がここで落ちる。この手順を飛ばさない
- 主題を1つ決める。 2つ以上なら分割の3軸に当たるかを見て、図ごとに主題を示す一文を付ける
- 対象を読む。 分岐条件・終了状態・デプロイ先を推測で書かない（図は既にあるものの写像）
- 向き・形・線種を決める
- 幅を数える
- 図の下に本文を置く。 ラベルから削った詳細をここへ落とす。図と本文で同じことを二度書かない
監査
ファイルに2枚以上あるなら、先にファイル全体で見る。
[ ] 各図が単独で主題を持っている（持たない図は削除対象。先に落とす）
[ ] 分かれている軸が3つ（時間 / 正常系・異常系 / before・after）のいずれか
[ ] 各図に主題を示す見出しか一文がある
[ ] 1枚に主題が2つ以上詰まっていない（「大きいから割る」ではなく「主題が2つだから割る」）
そのうえで1ブロックずつ見る。
[ ] 主題がある（無い一直線のパイプラインなら、削除して箇条書きへの置換を提案する）
[ ] 一番おもしろい判断が1ノードに潰れていない
[ ] LR なら チェーン4ノード以下
[ ] エッジラベルに API 列挙・引数・条件式が無い
[ ] ノードラベルが全角12文字程度に収まっている
[ ] 横並び subgraph が2つ以下
[ ] 形状・線種が図の中で一貫している
[ ] 抽象度が混ざっていない
[ ] 改行が <br/>
指摘して終わりにせず、修正後の Mermaid をその場で書く。主題ごと差し替える提案は幅の調整ではなく描く対象の変更なので、なぜ今の主題が成立していないかを1〜2文で添える。
3. 検証
Mermaid のレンダリングはローカルで確認できない。SVG に焼いて確認しようとしない。
- 構文: ノード ID の重複・引用符の閉じ忘れ・subgraph の
end抜けを目視で確かめる - 幅: 上の数え方で見積もる。実測は user に委ねる
- 見た目の確認が要るなら、GitHub 上での表示確認を
## 検証手順に書いて user に渡す
4. 注意
- Issue ドリブン期のリポの README を直す場合、相談者は実装しない。
new-issueSkill で Issue を立てるまで（軽量経路の条件を満たす場合を除く） - 図に固有の接続情報（ドメイン実値・Tunnel UUID・VPN の IP 等）を書かない。
secrets-agents/の<PLACEHOLDER>方針に従う - 図を画像化する必要が出ても、外部ホスティングに依存させない
