ascii-visualizer

ASCII ビジュアライザー

アーキテクチャ、ワークフロー、ファイルツリー、データの可視化に使える、一貫性のある読みやすい ASCII 図です。外部ツールなしで、モノスペース端末に正しく表示されます。

基本原則： 装飾ではなく構造に情報を盛り込みます。図の各要素には、意味のある情報を伝えさせてください。

ボックス描画文字のリファレンス

このブロックでは、キーとして複数のセットを意図的にまとめて表示しています。実際の図ではセットを1つだけ使用してください。single-set リントルールにより、本番用の図ではこのルールが適用されます。

default:   ┌─┐ │ └─┘  ├─┤ ┬ ┴ ┼
emphasis:  ┏━┓ ┃ ┗━┛  ┣━┫ ┳ ┻ ╋
title:     ╔═╗ ║ ╚═╝  ╠═╣ ╦ ╩ ╬
soft:      ╭─╮ │ ╰─╯
portable:  +-+ | +-+  +-+ + + +
Arrows:    → ← ↑ ↓ ─> <─ ──> <──
Blocks:    █ ▓ ░ ▏▎▍▌▋▊▉
Status:    ● ○ ✓ ✗ ⚠ ◆ ◇ ▶ ▷  ↑↓→ ▓▒░  (closed-set vocab — see rules)

セットの規約（D8：意図に基づく命名）

トークンは tokens.json にあります。名前は見た目ではなく用途を表します。

セット	文字	用途
default ─│	通常のボックスとコネクター	ほとんどの図
emphasis ━┃	見出し、注目箇所、視線を引く要素	重要なコンポーネント、外枠
title ═║	ドキュメントのタイトル	§0 形式のバナーのみ
soft ╭╮╰╯ ─│	ステータスカード、控えめな UI	差分ブロック
portable +-|	NO_COLOR／CI／通常の TTY	フォールバック

名前を変更する codemod（D8）：旧 light/heavy/double/rounded/ascii-fallback を上記の新しい名前に変更します。旧名は、マイナーリリース1回分に限り、警告付きで引き続き使用できます。

ステータスグリフの語彙

11個の意味を持つグリフによる、v1 の固定語彙です（●○✓✗⚠◆◇▶▷ ↑↓→ ▓▒░）。信頼できる唯一の情報源については、rules/status-glyph-vocabulary.md を参照してください。グリフ追加の手順は CONTRIBUTING.md にあります。

図のパターン

アーキテクチャ図

┌──────────────┐      ┌──────────────┐
│   Frontend   │─────>│   Backend    │
│   React 19   │      │   FastAPI    │
└──────────────┘      └───────┬──────┘
                              │
                              v
                      ┌──────────────┐
                      │  PostgreSQL  │
                      └──────────────┘

注釈付きファイルツリー

src/
├── api/
│   ├── routes.py          [M] +45 -12    !! high-traffic path
│   └── schemas.py         [M] +20 -5
├── services/
│   └── billing.py         [A] +180       ** new file
└── tests/
    └── test_billing.py    [A] +120       ** new file

Legend: [A]dd [M]odify [D]elete  !! Risk  ** New

進捗バー

[████████░░] 80% Complete
+ Design    (2 days)
+ Backend   (5 days)
~ Frontend  (3 days)
- Testing   (pending)

スイムレーン／タイムライン図

Backend  ===[Schema]======[API]===========================[Deploy]====>
                |            |                                ^
                |            +------blocks------+             |
                |                               |             |
Frontend ------[Wait]--------[Components]=======[Integration]=+

=== Active work   --- Blocked/waiting   | Dependency

影響範囲（同心円）

            Ring 3: Tests (8 files)
       +-------------------------------+
       |    Ring 2: Transitive (5)      |
       |   +------------------------+   |
       |   |  Ring 1: Direct (3)     |   |
       |   |   +--------------+      |   |
       |   |   | CHANGED FILE |      |   |
       |   |   +--------------+      |   |
       |   +------------------------+   |
       +-------------------------------+

比較表

BEFORE                          AFTER
┌────────────┐                  ┌────────────┐
│  Monolith  │                  │  Service A │──┐
│  (all-in-1)│                  └────────────┘  │  ┌──────────┐
└────────────┘                  ┌────────────┐  ├─>│  Shared  │
                                │  Service B │──┘  │  Queue   │
                                └────────────┘     └──────────┘

可逆性のタイムライン

Phase 1  [================]  FULLY REVERSIBLE    (add column)
Phase 2  [================]  FULLY REVERSIBLE    (new endpoint)
Phase 3  [============....]  PARTIALLY           (backfill)
              --- POINT OF NO RETURN ---
Phase 4  [........????????]  IRREVERSIBLE        (drop column)

主なルール

ルール	説明
フォント	常にモノスペースにします。ボックス描画文字には固定幅が必要です
線の太さ	通常は標準、強調には太線、タイトルには二重線を使用します
矢印	─>、──>、または方向を示す v／^ を付けた │ を使用します
配置	列幅に合うよう、ラベルの右側に空白を入れます
注釈	リスクには !!、新規には **、変更の種類には [A/M/D] を使用します
幅	端末との互換性のため、80文字未満にします
入れ子	読みやすさが損なわれる前に、ボックスの入れ子は最大3階層にします

各パターンの用途

パターン	用途
レイヤーボックス	システムアーキテクチャ、デプロイトポロジー
同心円	影響範囲、影響分析
タイムラインバー	可逆性、移行フェーズ
スイムレーン	実行順序、並行する作業の流れ
注釈付きツリー	ファイル変更一覧、ディレクトリー構造
比較表	レイヤー間の一貫性、変更前と変更後
進捗バー	ステータスの追跡、完了状況の指標

関連スキル

• brainstorm — 図でアイデアを伝える設計の検討
• architecture-patterns — ASCII 図が役立つシステムアーキテクチャ
• code-review-playbook — インライン図を使ったレビューコメント