draw-diagram
図・フローチャート・シーケンス図・状態遷移図・アーキテクチャ図・ポンチ絵を mermaid(`.mmd`)と SVG で作る規範。データ可視化のグラフ・チャートは対象外。「図を描いて」「フローチャートにして」「シーケンス図を作って」「アーキテクチャ図を作って」「ポンチ絵で説明して」と頼まれたときに使う。
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- draw-diagram
- description
- 図・フローチャート・シーケンス図・状態遷移図・アーキテクチャ図・ポンチ絵を mermaid(`.mmd`)と SVG で作る規範。データ可視化のグラフ・チャートは対象外。「図を描いて」「フローチャートにして」「シーケンス図を作って」「アーキテクチャ図を作って」「ポンチ絵で説明して」と頼まれたときに使う。
02 资源文件 5
- 参考文档references/examples/cache-read.mmd441 B
- 资产文件references/examples/cache-read.svg2.0 KB
- 参考文档references/mermaid.md6.6 KB
- 参考文档references/svg.md11.0 KB
- 脚本scripts/render.py20.2 KB
03 SKILL.md 正文
作図規範
1. 図を描くかどうかの判断
文や表で済むなら描かない。図は、要素どうしの関係・データの流れ・境界・状態遷移など、文では追いにくい構造を示すときだけに描く。1 図には 1 つの主張だけを持たせる。複数の主張があるときは図を分ける。説明のための図で主体・コンポーネントが 3 つ以上あるときは全部を 1 図に描かない。前の図を描き直してつなぐ辺と一緒に主体・コンポーネントを 1 つずつ加えた図の列にする。読み手は主体・コンポーネントが組み上がる順に仕組みを追える。列の各図の主張は新しく加えた主体・コンポーネントの役割である。そのため列は 1 図 1 主張の規則と両立する。列の最後の図は全部の主体・コンポーネントを描いた参照用の図を兼ねる。仕様書の構成図のような参照用の図には本規則を適用しない。スライド・報告書などの配布資料に埋め込む図も本規範で描く。.mmd は構造の確認に使い、配布物には 2. の工程で書いた SVG を使う。mermaid の描画をそのまま埋め込まない。
2. 工程
- 種類と構図を決める(
references/mermaid.md)。 - 構造を
.mmdに書く。ノードと辺だけを決め、配置と装飾は決めない。 - SVG を書く(
references/svg.md)。 render.pyで.mmdと SVG の対応を照合し、禁止事項を検査する。--pngで PNG にして画像として目視する。サンドボックス内では Chrome が起動できないため、サンドボックス外で実行する。目視では、括弧・矢印・三角の向きと矢尻の有無を 1 つずつ確かめる。render.pyが見るのは、data-idとdata-edgeの属性の照合と、data-edgeを持つ path・line の斜めの線分(polyline・polygon と transform は対象外)であり、ほかの図形の形は見ない。- 埋め込む(
)。alt には図が伝える主張を書く。
.mmd と SVG は同じ basename で対にして残す(references/examples/cache-read.mmd と cache-read.svg が対応例)。1. の図の列では図ごとに .mmd と SVG を対にして残す。basename には列の順の番号を付ける(cache-read-1・cache-read-2)。references/examples/cache-read は列の最後の図に当たり単独では参照用である。PNG は生成物であり、リポジトリに残さず一時ディレクトリへ出す。
render.py の呼び方。
python3 <スキルのディレクトリ>/scripts/render.py <x.mmd> <x.svg> [--png OUT]
<スキルのディレクトリ> には CLI がスキル読み込み時に示す絶対パスを入れる。
3. 参照ファイル
| ファイル | 扱う規範 | 読むとき |
|---|---|---|
references/mermaid.md |
.mmd の書き方、先頭のコメント、種類ごとの構図、主体と処理の描き分け、原典の箱の扱い |
構造を .mmd に書くとき |
references/svg.md |
SVG の書式、寸法と配置(埋め込み先の幅・辺の端点・帯の連続)、色トークン、文字幅とはみ出しの対処、塗り分けと凡例、円筒、data-id・data-edge の規則、HTML 閲覧ページ、接続線の規則 |
SVG を書くとき |
4. 規範の要点
- 名前を書いた箱の羅列でなく、仕組み(データの流れ・境界・追加される辺)を描く。
- 主体・領域は subgraph の枠、処理・情報はノードで描き、動作主の箱と処理の箱を同じ粒度で並べない。
- フローチャートの順序は辺と判定のひし形の分岐(はい / いいえ)で示し、番号つきの矢印で示さない。
- 比較は Before/After の値の並びでなく、差分そのものを描く。
- 矢印にはラベルを付ける。何が渡る辺なのかを矢印だけで示す。
- 接続線は水平・垂直の線分と角丸の曲がりで描き、線を箱より先に描く(
references/svg.md9.)。斜めの線分はrender.pyが検出する。 - 説明文は図の中に書き込まず、図の外のキャプションに記載する。軸(横が時間、縦が主体など)と帯・レーンが何を表すかも、キャプションに書く。図の中の帯の題だけでは、読み手は帯の目的を取れない。
- 要素の区別は枠線の色でなく塗りで付ける。凡例は塗り・線色に意味を持たせた図にだけ付け、見本の図形と意味の文を書き、見れば分かること(色名・塗り・線種・形)を書かない。ファイル・DB は色でなく円筒の形で示す。
- 見積もった文字幅が箱を超えないようにし、PNG で目視する。
5. 優先規則
render.pyの照合(references/mermaid.mdに定める記法の範囲)を、図の見た目より優先する。照合が通らない書き方は、通る書き方に描き直す。- 日本語のラベル・キャプションは write-doc の規範(
../write-doc/SKILL.mdと references)に従う。
04 同仓库更多 Skills
write-slide
スライド・プレゼン資料・発表資料・説明資料(読み返す用のスライド)・Marp の構成を作る・直すときの規範。メッセージラインや章立てを設計・点検するとき、ページの役割分担や強調の入れ方を決めるときに使う。
write-page
HTML で配布する説明資料(図・表・切り替えの UI を持つ 1 ページの文書)を作る・直すときの規範と工程。本文は write-doc、図は draw-diagram、見た目は design-ui の閲読モードを参照し、HTML 固有の規則(表の列の並び、一覧の全件表示、操作と表示先の近接、表の面、折りたたみのラベル、行幅、図の幅)を write-doc の format/html.md から読み、本文・図・スクリプト・見た目の検査を定める。「HTML の資料を作って」「1 ページの説明資料にして」「ブラウザーで読める資料にして」「HTML で配布したい」と言われたとき、Markdown の文書を HTML の資料に組み替えるときに使う。アプリの画面は design-ui、Markdown の文書は write-doc、スライドは write-slide が扱う。
write-message
他者へ送る短い日本語メッセージ(issue・PR のコメント、レビューコメント、業務チャット、短いメール)を敬語で書く・直すときの規範。宛先・場・用件を確かめ、用件から書き、定型の謝辞・結び・申し出と敬語の誤用を除く。これらのメッセージの執筆・返信・投稿を頼まれたとき、既存の文を敬語や丁寧な文体に直すとき、メッセージが AI っぽいと言われたときに使う。
write-doc
日本語の開発ドキュメント・技術文書(README、仕様書・規約、手順書・マニュアル、調査・分析・評価レポート、議事録、リサーチメモ・企画書、スライド構成、技術書の章・記事・解説文)の作成規範。これらの文書を書く・推敲・リライトするとき、文書の brief・骨組みの合意をするとき、アウトラインの設計や構成の点検・再編をするとき、「AIっぽい」「機械翻訳っぽい」「不自然」といった指摘への修正、「読みにくい」「一文が長い」「何が言いたいか分からない」といった読みやすさの改善に使う。
verify
対象リポジトリに検証の手引き `docs/verify/` を生成して保守する手順。検証の手引きは実アプリを利用者と同じ経路で動かして証拠を取る手順書である。生成ではリポジトリから触る面・起動・操作・観測・隔離を調べる。次に README の 6 節(起動・健康診断・操作・証拠・後始末・補助スクリプト)と機能ごとの機能マップを書く。1 つの機能で通して証明する。保守では機能ごとの調査役がソースとのずれを探す。統括が全機能をライブで通して変更なし・1 PR・停止のどれかで終える。「検証の手引きを作って」「docs/verify を作って」「実アプリで確かめる手順を作って」「検証の手引きを点検して」「機能マップを今のアプリに合わせて」と言われたときに使う。手引きに従った検証は develop と planner と gate-reviewer が引く。
specify
曖昧な着想から、ユーザーとの対話で「何を作るか」を聞き出し、build がそのままタスクに分解できる PRD(製品要求仕様書)を書く手順と雛形。PRD のタスクへの分解と実装は build が行う。「PRD を書いて」「要求を整理して」「アイデアを仕様にして」「specify」と言われたときに使う。