MasashiFukuzawa ASCII Diagram — 会話内の即席図解
原則
- その場で読める最小の図を描く。HTML 生成のトークンコストをかけずに構造を伝えるのが役割
- 図は等幅フォント前提。1行の表示幅は最大 100 セル（ターミナル・チャット両対応）
- 図の中も日本語で書く。利用者が指定した用語と、API・DB・Queue など日本語化すると不自然な技術用語だけ英語を使う
- 箱の幅は byte 数・文字数・px 数ではなく、後述の表示セル幅で合わせる。日本語を一律に避けることで整列を代用しない
- ラベルは短い名詞句にする。説明文を箱へ詰め込まず、必要な補足は図の直後に1-3行で添える
- 要素が多すぎて崩れるなら、詳細を削って階層を1段落とすか、html-artifact への切替を提案する
日本語の幅合わせ
- ASCII と通常の半角文字を 1 セル、日本語など Unicode East Asian Width が
WまたはFの文字を 2 セルとして数える - 結合文字と variation selector は 0 セルとして数える。ただし、絵文字・ZWJ sequence・East Asian Width が
A（Ambiguous）の文字はレンダラー依存なので図中では使わない - 枠と矢印には ASCII の
+ - | > < ^ vを使う。Unicode の罫線・矢印もAであり、環境によって 1 または 2 セルになるため、表示先で幅を確認できる場合だけ使う - 箱の内幅を先に表示セル数で決め、各ラベルの右側へ
内幅 - ラベルの表示幅個の半角空白を入れる。左右に余白を置く場合、その空白も各 1 セルとして内幅へ含める - 日本語1文字を常に2セルと仮定するだけでは、英数字・結合文字が混ざるラベルでずれる。各ラベル全体を上の規則で数える
- filesystem と Python 3 を使える host では、完成したコードブロックを
SKILL.mdと同じディレクトリにあるscripts/display_width.pyの標準入力へ渡し、各行の表示セル幅と不安定な文字を確認する。使えない host では同じ規則で手動確認する。箱を構成する行の幅が一致しない場合は空白を調整して再確認する
例: 利用者 は 6 セル、API受付 は 7 セル、DB は 2 セル。内幅を 9 セル（左右の空白を含む）にすると次のように揃う。
+---------+
| 利用者 |
| API受付 |
| DB |
+---------+
罫線パレット
- 箱・線:
+ - |（基本）。表示先を確認できる場合のみ┌ ┐ └ ┘ ─ │ ├ ┤ ┬ ┴ ┼ - 矢印:
--> <-- ^ v <--> ==>。斜め・分岐は/ \か折れ線で - ラベルは箱の中に。箱の外の注記は
#で
型（用途別）
構成図 / データフロー:
+----------+ +-----------+ +----------+
| 利用者 | ---> | API受付 | ---> | DB |
+----------+ +-----+-----+ +----------+
| 発行
v
+-----------+
| キュー |
+-----------+
シーケンス（時系列は上から下・関与者は列）:
利用者 Agent 外部API
| 依頼 | |
| ------------> | API呼出 |
| | ------------> |
| | <------------ |
| <------------ | 結果 |
状態遷移 / フロー（分岐は条件ラベル必須）:
[開始] -> [確認] -- OK --> [実行] -> [完了]
|
+-- NG --> [修正] --+
^-------------+ # 最大3回
比較・対置（2案の構造差は横並び。案の説明は図の下の日本語で）:
案A: 直接呼出し 案B: キュー経由
+----+ +----+ +----+ +-----+ +----+
| S1 |-->| S2 | | S1 |-->|Queue|-->| S2 |
+----+ +----+ +----+ +-----+ +----+
# 同期・単純 # 非同期・疎結合
※ 案A=同期で単純、案B=キュー経由で非同期・疎結合（このような日本語の補足は図の直後に書く）
ディレクトリ構造: tree 形式（├── └──）。既存ファイルと新規/変更はコメントで区別
品質チェック（描画後に自己確認）
- 図中の説明が日本語になっているか（自然な技術用語・固有名詞は除く）
- 各行を byte 数や文字数ではなく表示セル幅で数えたか
- 絵文字・ZWJ sequence・Ambiguous 幅の記号を避けたか
- 表示先を確認できないのに Unicode の罫線・矢印を使っていないか
- 箱の左右の縦線が同じ表示セル位置に揃っているか
- 矢印の向きは因果・データの流れと一致しているか
- 5秒で構造が掴めるか（掴めないなら要素を減らす）
- 日本語での説明が必要な内容は、図の直後の1-3行に書けているか