ascii-diagram-validator

ASCII 図検証ツール

アーキテクチャのドキュメント、README ファイル、コードコメントでよく使われる ASCII の罫線図について、配置のずれを検証して修正します。

自己進化型スキル：このスキルは使用を通じて改善されます。指示が誤っている場合、パラメーターにずれがある場合、または回避策が必要だった場合は、先延ばしにせず、直ちにこのファイルを修正してください。実際に再現可能な問題がある場合にのみ更新してください。

概要

罫線文字（─│┌┐└┘├┤┬┴┼ および二重線のバリエーション ═║╔╗╚╝╠╣╦╩╬）を使った ASCII 図では、列を正確にそろえる必要があります。このスキルでは、次の機能を提供します。

1. 検証スクリプト - 位置をファイル名、行、列で示し、配置のずれを検出します
2. 具体的な修正案 - 各問題を修正するための具体的な提案を提示します
3. 複数ファイルのサポート - 個別のファイルやディレクトリ全体を検証します

このスキルを使用する場面

次の場合に実行してください。

• Markdown で ASCII のアーキテクチャ図を作成または編集するとき
• 罫線図を含むドキュメントをレビューするとき
• 「図がおかしく見える」という指摘を修正するとき
• docs/ARCHITECTURE.md や同様のファイルをコミットする前
• ユーザーが「ASCII の配置」「図の配置」「罫線」について言及したとき

対応文字

1 本線の罫線

Corners: ┌ ┐ └ ┘
Lines:   ─ │
T-joins: ├ ┤ ┬ ┴
Cross:   ┼

2 本線の罫線

Corners: ╔ ╗ ╚ ╝
Lines:   ═ ║
T-joins: ╠ ╣ ╦ ╩
Cross:   ╬

混合（2 本線と 1 本線）

╞ ╟ ╤ ╧ ╪ ╫

クイックスタート

単一ファイルを検証する

/usr/bin/env bash << 'PREFLIGHT_EOF'
uv run "$(cc-plugin-root doc-tools)/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py" docs/ARCHITECTURE.md
PREFLIGHT_EOF

複数のファイルを検証する

/usr/bin/env bash << 'PREFLIGHT_EOF_2'
uv run "$(cc-plugin-root doc-tools)/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py" docs/*.md
PREFLIGHT_EOF_2

ディレクトリを検証する

/usr/bin/env bash << 'PREFLIGHT_EOF_3'
uv run "$(cc-plugin-root doc-tools)/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py" docs/
PREFLIGHT_EOF_3

出力形式

スクリプトは、問題箇所に簡単に移動できるよう、コンパイラーのような形式で問題を出力します。

docs/ARCHITECTURE.md:45:12: error: vertical connector '│' at column 12 has no matching character above
  → Suggestion: Add '│', '├', '┤', '┬', or '┼' at line 44, column 12

docs/ARCHITECTURE.md:67:8: warning: horizontal line '─' at column 8 has no terminator
  → Suggestion: Add '┐', '┘', '┤', '┴', or '┼' to close the line

重大度

レベル	説明
error	接続が切れている、縦線の配置がずれている
warning	線が閉じていない、潜在的な問題がある
info	スタイルに関する提案（任意のクリーンアップ）

検証ルール

スクリプトでは、次の項目を確認します。

1. 縦方向の配置 - 縦の接続線（│║）は、上下の文字と位置をそろえる必要があります
2. 角の接続 - 角（┌┐└┘╔╗╚╝）は、隣接する線に正しく接続する必要があります
3. 接合部の妥当性 - T 字接合部と交差部では、入出力の接続が正しくなければなりません
4. 線の連続性 - 横線（─═）は、有効な端点で終端する必要があります
5. ボックスの閉鎖 - ボックスは適切に閉じている必要があります（辺が宙に浮いていないこと）

終了コード

コード	意味
0	問題は見つかりませんでした
1	エラーを検出しました
2	警告のみ（--warn-only を指定するとエラーは無視されます）

Claude Code との連携

Claude Code で ASCII 図を作成または編集するときは、次の手順に従います。

1. ファイルに対して検証スクリプトを実行します
2. 出力にあるエラーを確認します
3. 提案された修正を適用します
4. 問題がなくなるまで再実行します

ワークフローの例

/usr/bin/env bash << 'PREFLIGHT_EOF_4'
# After editing docs/ARCHITECTURE.md
uv run "$(cc-plugin-root doc-tools)/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py" docs/ARCHITECTURE.md

# If errors found, Claude Code can read the output and fix:
# docs/ARCHITECTURE.md:45:12: error: vertical connector '│' at column 12 has no matching character above
# → Edit line 44, column 12 to add the missing connector
PREFLIGHT_EOF_4

制限事項

• 検出するのは構造上の配置の問題であり、見た目の間隔ではありません
• 罫線文字を一貫して使用する必要があります（+---+ のような ASCII 文字との混在は不可）
• タブ文字が誤検出の原因になる場合があります（先にスペースに変換してください）
• Unicode の正規化は行われません（合成済み文字を使用してください）

同梱スクリプト

スクリプト	目的
scripts/check_ascii_alignment.py	メインの検証スクリプト

関連情報

• ARCHITECTURE.md のベストプラクティス
• Unicode の罫線ブロック

---

トラブルシューティング

問題	原因	解決策
スクリプトが見つからない	プラグインがインストールされていない	claude plugin list でプラグインがインストールされていることを確認します
タブによる誤検出	タブ文字の位置がずれている	検証の前にタブをスペースに変換します
ASCII の混在が検出されない	+---+ 形式を使用している	スクリプトは Unicode の罫線文字のみを検証します
列番号がずれる	Unicode の幅の計算	合成済み文字を使用し、結合文字は避けます
問題はないのに表示がおかしい	見た目の間隔はチェックされない	バリデーターがチェックするのは構造であり、視覚的な間隔ではありません
終了コード 2 が予期せず発生	警告のみモード	警告を成功として扱うには --warn-only フラグを使用します
検証エラーが見つからない	複雑な入れ子の図	出力の行番号を確認し、該当セクションのみを検証します
Unicode 文字が表示されない	ターミナルのフォントにグリフがない	Unicode 罫線文字を完全にサポートするフォントを使用します

実行後の振り返り

このスキルの実行が完了したら、終了する前に以下を確認します。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった指示またはエラーテーブルを修正します。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに差異が生じていた場合は、「使用例」と「パラメーター」テーブルを実態に合わせて更新します。
3. 回避策が必要でしたか？ — 即興の対応（異なるフラグや追加の手順）が必要だった場合は、次回同じ回避策が不要になるよう、この SKILL.md を更新します。

問題が実際に発生し、再現可能な場合にのみ更新します。推測に基づく更新は行いません。