Content Mermaid
技術的なプロセスや構造のMermaid図を生成します。これは content-diagrams の高速な構文駆動版です。同じ視覚的明瞭性の基準を持ちますが、正確な幾何学配置を保証する言語に基づいているため、労力は図のタイプ選択と読みやすく一貫性のあるカラーシステムの構築に集中され、座標の検証は不要です。
content-diagrams との関係
両スキルは同じ基準（読みやすいテキスト、装飾ではなく実用的なカラーシステム、密度より明瞭性）を共有していますが、content-diagrams は手動でSVGジオメトリを計算するのに対し、本スキルはジオメトリを完全にMermaidのレイアウトエンジンに委ねます。図が実際に表示される環境（ネイティブMermaid描画面 vs. 静的画像のみを表示するプラットフォーム）に基づいて選択してください。本当に迷った場合は質問してください。Mermaidソースは、実際に手を加えなければ、洗練されたスタンドアロングラフィックとしてきれいにスクリーンショットを撮ることはできません。
検証ループがない理由
content-diagrams はジオメトリに多くの労力を費やします。SVGの線、ボックス、ラベルはClaudeが計算した数値であり、計算された数値は間違っている可能性があります。そのため、レンダリング、スクリーンショット、トリミング、チェックが必要です。
Mermaidはその障害モードを完全に排除します。ノードの幅、テキストの折り返し、矢印のパス、要素間の衝突回避はレンダラーの仕事であり、Claudeの仕事ではありません。レンダラーはボックスの上にラベルを配置したり、図形を通る線を引いたりしません。ここで検証ループ（レンダリングされた図のスクリーンショット、トリミング、重なりのチェック）を再現することは、ツールがすでに保証していることを確認するためにトークンとレイテンシを浪費するだけです。
問題が発生する可能性があるのは、まったく別の、テキスト関連の箇所です:
- 壊れた構文（閉じられていない括弧、ノードIDとして使用された予約語、誤った矢印タイプ）
- 定義されていないノードIDを参照するエッジ
- 貧弱な色のコントラスト（塗りつぶしとテキストの色が実際に互いに読み取れない）
- コンテンツの実際の構造に合わない図のタイプ
したがって、ここでの検証とは、構文を正しさのために一度読み、すべての classDef が塗りつぶしと本当に対照的なテキスト色をペアにしていることを確認し、図のタイプがモデル化されているものと一致することを確認することを意味します。画像のレンダリングは必要ありません。
図のタイプ選択
コンテンツの構造が何であるかに基づいてタイプを選択します。これは、content-diagramsのモチーフ選択に相当するMermaid版です:
| コンテンツの構造 | Mermaid タイプ |
|---|---|
| 分岐/ループを含む順次ステップ（プロセス、ワークフロー、アルゴリズム） | flowchart TD（上から下）または LR（左から右、パイプライン/タイムライン用） |
| アクター/サービス間の時系列メッセージ（API呼び出し、プロトコル交換） | sequenceDiagram |
| エンティティの状態とその間の遷移（ライフサイクル、ステートマシン） | stateDiagram-v2 |
| データモデル/エンティティ関係（スキーマ、DBテーブル） | erDiagram |
| オブジェクト指向構造（クラス、継承、インターフェース） | classDiagram |
| 期間と依存関係を持つスケジュール | gantt |
| 厳密な順序のない階層的ブレイクダウン/ブレインストーム | mindmap |
| 時系列のナラティブ（プロジェクト履歴、バージョン履歴） | timeline |
| 2軸の優先順位付け（影響 vs. 労力など） | quadrantChart |
すべてを flowchart にデフォルト設定しないでください。「サービスがどのように相互に呼び出し合うかを図示して」というリクエストは、ボックスと矢印で描画したくなるかもしれませんが、sequenceDiagram です。「チケットが通過する状態を示して」というリクエストは、状態を表すひし形のあるフローチャートではなく、stateDiagram-v2 です。
色と可読性のシステム
ここは手動検証が依然として重要な唯一の場所です。Mermaidは文句を言わずに読みにくい色の選択をレンダリングするからです。
ルール: すべての classDef は、塗りつぶしと、それと対照的になるように意図的に選択されたテキスト色をペアにしなければなりません。color を設定せずに、テーマのデフォルトが機能することを期待してはいけません。 Mermaidのデフォルトパレット（柔らかい緑/ピンク/青と黒のテキスト）は、塗りつぶしとテキストが一緒に選択されているため、問題ありません。塗りつぶしをより彩度の高い、または暗い色に上書きした瞬間、明示的に color も設定しなければ、一般的な欠陥を再現することになります。見た目は読みやすいボックスでも、テキストが実際には背景に対して低コントラストになります。
2つのパレットレシピ。1つを選択し、1つの図内のすべてのクラスで一貫して使用してください（混在させないでください）:
- 暗い塗りつぶし / 白いテキスト（デフォルト — 実績あり、高コントラスト、ライト/ダーク両方のチャットテーマでよく読み取れます）:
classDef category1 fill:#1e3a5f,stroke:#0d1f33,stroke-width:2px,color:#ffffff - 薄い色の塗りつぶし / 暗いテキスト / 彩度の高いストローク（図を、薄い色の規則に従うcontent-diagrams SVGの隣に視覚的に配置する必要がある場合に使用）:
classDef category1 fill:#e1f0ff,stroke:#1e3a5f,stroke-width:2px,color:#1a1a1a
content-diagramsのルールを直接借用します: カテゴリごとに1つの色相、そのカテゴリが現れるすべての場所に適用 — その役割のすべてのノードで同じ色の塗りつぶし/ストロークを使用し、1回限りの使用は避けます。役割ごとに色相を割り当てます。例:
- 青 → 入力 / データ / バックログ項目
- 緑 → プロセス / アクティブな作業ステップ
- 琥珀色または茶色 → 決定ポイント / ゲート
- 紫 → 出力 / リリース / 最終状態
- 赤 → フィードバックループ / 障害パス / レトロスペクティブ
キャンバスを固定して、ホストのライト/ダークモードに依存しないようにします。 図の最初の行としてinitディレクティブを配置します:
%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Trebuchet MS, Verdana, Arial, sans-serif', 'fontSize': '16px', 'primaryColor': '#1e3a5f', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0d1f33', 'lineColor': '#666666', 'background': '#ffffff' } } }%%
theme: 'base' に明示的な themeVariables を加えることで、ホスト環境がデフォルトとするMermaidテーマ（default、dark、forestなど）に関係なく、図は同じように見えます。デフォルトのテーマ名だけに依存しないでください。実際の色はレンダラーの任意の決定に委ねられるからです。
フォントサイズ: 多数のノードがある図では最低16px。14pxは、図が十分に単純で読みやすさが問題にならない場合のみ。図がラベルを収めるために14px未満に縮小する必要がある場合、それはcontent-diagramsと同じ「密度より明瞭性」のシグナルです。図を分割するかコンテンツを削減し、テキストをこれ以上縮小しないでください。
スタイリングの範囲は図のタイプによって異なります: flowchart、stateDiagram-v2、classDiagram はすべて、ノードごとに classDef/class を直接サポートしているため、上記のカテゴリカラーシステムをノードごとに使用します。sequenceDiagram、erDiagram、gantt は要素ごとのスタイリングが非常に限られているため、これらの図では、ノードレベルのクラスが同じように機能することを期待するのではなく、initブロック内の themeVariables（シーケンス図の場合は actorBkg、actorTextColor、noteBkgColor など）に労力を注ぎます。
矢印の文法
手書きのSVGとは異なり、Mermaidは矢印ラベルを自動配置でクリーンにレンダリングします。-->|label| のテキストが、手動で配置されたSVGラベルのように図形の上に配置されるリスクはありません。したがって、content-diagramsの「矢印のテキストを避け、凡例でデコードする」というデフォルトとは異なり、ここでは矢印に直接ラベルを付けることは問題なく、多くの場合より明確です。それでもラベルは短い断片（「承認済み」「リトライ」「失敗時」）に抑え、フレーズにしないでください。ラベルはタグであり、文ではありません。
線のスタイルは、content-diagramsが使用するのと同じ広範な区別のために予約します:
- 実線の矢印 (
-->) → 主要/通常フロー - 破線の矢印 (
-.->) → フィードバック、オプションパス、または外部/間接的な相互作用 - 太い矢印 (
==>) → 強調された、または重要なパス。控えめに使用します。
ラベルは短く保ち、サブグラフでグループ化する
ノードテキストは短いフレーズにし、文にしないでください。Mermaidは段落長のラベルを他のツールと同様に折り返したりオーバーフローしたりします。ノードが複数行を必要とする場合は、自動折り返しが適切な場所で改行することを信頼するのではなく、ラベル内に明示的に <br/> を挿入します。
subgraph を使用して関連するステップをクラスター化します（例：1つのスプリント、1つのデプロイメントステージ、1つのサービス境界内のすべて）。これはグループ化ボックスに相当するMermaid版であり、style SubgraphName fill:...,stroke:... 行で独自のスタイルを設定できます。サブグラフは1レベルより深くネストしないでください。すぐに読みにくくなります。
ワークフロー
- 基礎となる構造を特定し、構文を書く前に上記の表から図のタイプを選択します。
- カテゴリカラーを割り当て、存在する役割（入力、プロセスステップ、決定、出力、フィードバック）に割り当てます。これをclassDefを書く前に1、2文でスケッチします。content-diagramsの「モチーフの推論をスケッチする」ステップと同じで、ユーザーが1つの要素を調整したい場合に選択が監査可能になります。
- 図を記述します。
%%{init: ...}%%ディレクティブから始め、次に構造、次にclassDef/classの割り当て（またはノードごとのクラスをサポートしないタイプの場合はthemeVariables）を記述します。 - 構文を自己チェックします — エッジで使用されるすべてのノードIDがどこかで定義されていること。すべての
classDefにfillとcolorの両方が設定されていること。括弧/引用符のバランスが取れていること。段落長のラベルがないこと。レンダリングもスクリーンショットも不要です。 .mermaidファイルとして保存します (create_fileを使用)。これにより、アーティファクトとしてインラインでレンダリングされます。説明的なスラッグを使用します:/mnt/user-data/outputs/<slug>.mermaid。present_filesで提示します。- ユーザーがポータブルな静的画像（Mermaidをレンダリングしない場所に埋め込むため、またはアーカイブ用）として図を必要とする場合、その旨を明確に述べてください。この環境では、ヘッドレスMermaidから画像へのエクスポートは確実に機能しません（サンドボックス化されたネットワークが通常到達できないChromiumのダウンロードに依存します）。手動エクスポートには mermaid.live を指すか、本当の要件がスタンドアロングラフィックである場合は
content-diagramsに切り替えてください。
やってはいけないこと
fillを上書きした後、classDefのcolorを設定しないままにしないでください。それはこのスキルが存在する理由であるコントラストバグそのものです。- 1つの図内で、暗い塗りつぶしと薄い塗りつぶしのパレットレシピを混在させないでください。
- すべてのリクエストを
flowchartにデフォルト設定しないでください。実際の構造（シーケンス、状態、ERなど）に一致するタイプを選択してください。 - ここでcontent-diagramsのレンダリング/トリミング/検証ループを再導入しないでください。それはMermaidのレイアウトエンジンには存在しない問題を解決するものです。
- ノードラベルに段落長のテキストを入れないでください。
<br/>で折り返すか、コンテンツを削減してください。 - サブグラフを1レベルより深くネストしないでください。
- このサンドボックスからクリーンなPNG/SVGエクスポートを、ヘッドレスMermaidレンダリングがここでは機能しない可能性があることを断りなく約束しないでください。