vis

# Vis 会話で扱った内容、または引数で指定されたテーマを、**図中心のHTML1枚**にして `tmp/visual/` に書き出すスキル。縦スクロールで読む解説資料を作る。 ## 目的は、人間の認知負荷を減らすこと この文書の数値規約はすべて、その目的の**代理指標**でしかない。節数も段落数も、それ自体に価値はない。 > [!IMPORTANT] > **（AI・必須）** 数値規約を全部満たしていても、読んで分からない資料は失敗である。最後の検査（「図だけを見て要点を言えるか」）を必ず通すこと。 ## 手順 上から順に実行する。 1. **対象と厚さを決める**：引数があればそれを、無ければこれまでの会話をもとにする。会話が対象のときは、どこからどこまでを扱うかも決める。引数に `--details` があれば厚く書き、無ければ既定の薄さで書く（後述の規約）。 2. **見出し構成を承認してもらう**：タイトル・各節の見出し・各節で何を図にするかを、箇条書きで短く提示する。**良しと言われるまでHTMLを書き始めない。** 確認はこの1回だけで、以降は最後まで自律で進める。 3. **雛形をコピーして書く**：`.claude/skills/vis/assets/template.html` を出力先へコピーし、中身を差し替える。図は `.claude/skills/vis/references/figure-patterns.md` の骨格を土台にする。 4. **描画を確かめて直す**：後述の手順でブラウザに描画させ、崩れを直す。 5. **図だけで要点を言えるか確かめる**：後述の最終検査を通す。 6. **渡す**：`SendUserFile` で `display: "render"` を指定して送る。パスを伝えるだけにしない。 ## 出力先 - **ディレクトリ**：`tmp/visual/`（無ければ作る。git 管理外） - **ファイル名**：`YYYYMMDD-<題名のケバブケース>.html`（例：`20260817-vis-skill.html`） - **日付**：`date +%Y%m%d` で取る - **既存ファイル**：上書きしない。同名なら末尾に `-2` を足し、それも在れば空いている番号まで増やす 後から読み返したり、他人に見せたりする使い方をするので、過去の分を消さない。 ## 書くときの規約 | 項目 | 規約 | 外れたときの直し方 | | ---------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | 節の数 | 既定は2〜3。`--details` 指定時は3〜8 | 統合するか、資料を分ける | | 1節の本文 | 既定は1〜2段落、`--details` 指定時は3段落以内。どちらも1段落2文以内 | **削るか、節を割るか**の2択 | | 図のある節 | 全節の半分以上 | 図にできる切り口で節を割り直す | | 図にするかの判定 | ノード関係が分岐・合流・ループ・並行・多対多・階層・状態遷移のいずれも含まない一直線の内容なら、図にせず表か箇条書きにする | —— | | 図の描き方 | 手書きの inline SVG のみ | —— | | 見た目 | 雛形のCSSは変えない | —— | 既定を薄くするのは、**書く量がそのまま待ち時間になる**からである。実測では、5節の資料1本を作った376秒のうち275秒（73%）が執筆で、ブラウザで描画を確かめる工程は76秒（20%）だった。節を減らせば、その73%がほぼ比例して減る。 > [!IMPORTANT] > **（AI・必須）** 本文が上限の段落数に収まらないときに、理由を書いて超えてはならない。収まらないのは「冗長」か「1節に2つ以上の話を詰めている」かのどちらかなので、削るか節を割るかしか選べない。理由を書けば超えられる形にすると、書き手であるAI自身が毎回それを許してしまう。 Mermaid は使わない。**外部のライブラリを読まずに図が出る**ようにするためで、この資料はネットの無い環境でもそのまま開ける必要がある。したがって `/design-doc-mermaid` は呼ばない。 ## 描画を確かめて直す 崩れは書いた文字列を見ても分からないので、必ず実際に描画させる。 1. 出力先ディレクトリで `python3 -m http.server 8765 --bind 127.0.0.1` をバックグラウンド起動する。`navigate` は `file:///` を開けないので、HTTPで配信する（ポートが埋まっていたら別の番号にする） 2. `mcp__claude-in-chrome__navigate` に `http://127.0.0.1:<起動したポート>/<出力ファイル名>` を渡す 3. `mcp__claude-in-chrome__computer` の `screenshot` で見る。入りきらなければ下へ `scroll` して続きを撮る。**戻って撮り直さない**（同じ場所を往復すると枚数だけが増える） 4. 縮小されて細部が読めず、崩れが疑わしい節だけ、`computer` の `zoom` にその範囲を渡して撮り直す 5. 下の崩れを直す 6. 直したら **`navigate` を呼び直す**。表示は読み込んだ時点のスナップショットなので、直しただけでは反映されない。直しが無ければ呼び直さない 7. 確認が終わったら、起動したサーバを停止する - **文字が箱からはみ出す**：言葉を短くする（フォントを小さくしない） - **線と文字が重なる**：線をずらすか、ラベルの位置を動かす - **矢印の先が箱に刺さっていない**：`path` の終点座標を箱の縁に合わせる - **文字が読めない（黒地に黒）**：雛形の `body` の背景色を消していないか見る ブラウザのツールが使えない環境では、**崩れを見ていない旨を明記して渡す**。黙って飛ばすと、崩れた資料が検査済みとして渡る。 ## 最終検査 > [!IMPORTANT] > **（AI・必須）** 完了を報告する前に、スクリーンショットを見ながら次を確かめ、すべて「はい」になるまで直すこと。 > > - **本文を読まず、図と見出しだけで各節の要点を言えるか**。言えない節は、図が本文の飾りになっているので図を描き直す > - 図のある節が、全節の半分以上あるか > - 節の数と本文の段落数が、「書くときの規約」の上限に収まっているか（`--details` の有無で上限が変わる） > - 崩れが残っていないか > - 雛形の `{{ }}` が1つも残っていないか（`grep -c '{{' <出力ファイル>` が 0 になるか）。`<head>` の `<title>` は画面に出ないので目視では気づけない 最初の1つが本体である。以降は、それを満たしやすくするための数値と手当てでしかない。 ## 使用方法 ``` /vis # ここまでの会話を2〜3節の薄い資料にする /vis リトライ設計の選択肢 # 指定したテーマで薄い資料を作る /vis リトライ設計の選択肢 --details # 節も本文も増やして厚く書く ``` まず薄いものを受け取り、足りなければ `--details` で作り直す方が、厚いものを待つより速く要点に届く。