図解作成、AIに丸投げしたら「たまに自分より上手い」件 — Claude Code を育てる方法

SHARE

目次

Figmaの手作業から脱却したい

ども！最近は図解の自動化にハマっている龍ちゃんです。

技術ブログの図解、みんなどうしてますか？ 僕は以前、Figmaで人力で図を作ってたんですよね。アーキテクチャ図とかフロー図とか、1つ作るのに結構な時間がかかる。ブログの本数が増えるほど、だんだん図を作るのが億劫になってきて。

で、SVG図解自動生成、HTML図解自動生成と試行錯誤を重ねてきました。過去記事を読んでなくても今回の記事だけで完結するので、安心してください。

やっていることはシンプルで、Claude Code の SKILL で HTML 図解を自動生成して、CLI ツールで PNG に変換する。ここまではツールの話なんですが、今回伝えたいのはその先で、気に入ったデザインを reference に突っ込んでスキルを「育てる」ことができるんですよね。これがめっちゃ重宝してます。

ぶっちゃけ僕が作るよりも、たまにいいデザインを作ってくるから最高なんですよ。んで、そのいいやつを保存しておくと、次からもっと良くなる。

今回の内容です。

  • 自然言語で図解を爆速で作る
  • ブラウザ立ち上げ不要でスクショをとる
  • 自分専用のデザイナーに育てる方法
  • 実際にやってみた結果と、正直な限界

仕組みの全体像

なぜ HTML + Tailwind なのか

ここに至るまでに色々試しました。ざっくり経緯を話すと:

  • Mermaid:
    手軽なんですけど、図の種類が制限されるんですよね。使用場所を選ぶ感じです（Mermaid図作成の記事も書いてます）
  • SVG:
    トークンだけバカ食いして、あんまりいい出力じゃなかった。座標計算が苦手で、文字はみ出しとか要素の重なりが頻発してました
  • HTML+Tailwind:
    Claude は CSS（Flexbox/Grid）が得意。HTMLだと自力で修正もできる
方式良い点課題
Mermaid手軽図の種類が制限される
SVG自動生成可能トークン食い・ズレやすい
HTML+Tailwind自動生成＋修正しやすいPNG変換が必要

HTMLは最初からうまくいったわけじゃなくて、参考になりそうなHTMLとかデザインプラクティスを調べて改善していった結果です。前回の記事では3つの実例が全て修正不要で完成するレベルまで持っていけました。あと、HTMLだと気に入ったデザインをパーツごとに蓄積させておくことで、自分だけのデザインブックが作れるんですよね。これが後で効いてきます。

Claude Code の SKILL って何？

Claude Code を使ってない人もいると思うので、ここだけ少し補足します。

一言で言うと「AIへの作業手順書」 です。.claude/skills/ ディレクトリに SKILL.md というファイルを置いておくと、Claude が指示を受けた時に自動でそのファイルを読んで実行してくれます。

例えば「アーキテクチャ図を作って」と言うと、Claude は図解生成用のスキルファイルを見つけて、「どんなHTMLで」「どんなルールで」「どんなサイズで」作るかを理解した上で図を生成してくれる。毎回同じ説明をしなくていいんですよね。

ここで大事なのが Progressive Disclosure（段階的開示） という設計です。

  • Level 1: スキルの名前と説明（常時ロード。軽い）
  • Level 2: SKILL.md 本体（スキルが起動した時にロード）
  • Level 3: references/ ディレクトリ（必要な時にだけロード）

この Level 3 が後で「育てる」話に繋がるので、覚えておいてください。

実際に作った図解スキルの中身

じゃあ実際に僕が作った diagram-generator-html というスキルを見てみましょう。

HTML5 + Tailwind CSS + Material Icons で 1280x720px 固定サイズの図解を生成します。対応パターンは8種類で、アーキテクチャ図やフロー図、比較図、ディレクトリツリー図なんかを作れる。

スキルファイル自体はコンパクトに保って、デザインパターンのお手本集は別ファイル（references/examples.md）に分けてあります。この「お手本集」が後で話す「育てる」仕組みの核になるんですが、詳しくはデモを見た後に。

HTMLからPNGに変換するCLIツール

スキルが生成するのはHTMLファイルです。ブログに貼るにはPNG画像が必要なので、変換ツールを作りました。

uv run html-screenshot --file diagram.html --output diagram.png

これだけ。中身は Python + Playwright（Chromium）で、やってることはシンプルです:

  1. Chromium をヘッドレスで起動
  2. HTMLファイルを file:// プロトコルで読み込み
  3. Tailwind CDN や Material Icons の読み込み完了を待機（wait_until="networkidle"）
  4. body 要素のスクリーンショットを PNG で保存

デフォルトで 1280×720 の画像が出力されます。HTMLで w-[1280px] h-[720px] と固定サイズを指定しているので、ブラウザのビューポートサイズに関係なく常に同じ結果になります。

実際に使ってみた

基本的な使い方

実際にやった流れを見せます。Claude Code に「3層アーキテクチャのフロー図を作って」と指示すると、スキルが自動で起動して HTML ファイルを生成してくれます。

生成されたHTMLはこんな感じ（抜粋）:

<body class="w-[1280px] h-[720px] m-0 p-0 overflow-hidden bg-gray-50">
  <div class="w-full h-full flex items-center justify-center p-10"
       role="img" aria-label="3層アーキテクチャ図">
    <div class="w-full max-w-4xl flex flex-col gap-4">
      <!-- Presentation Layer -->
      <div class="bg-blue-100 border-2 border-blue-500 rounded-lg p-6">
        <h2 class="text-2xl font-bold text-blue-900">Presentation Layer</h2>
      </div>
      <!-- 以下、Business Logic Layer、Data Access Layer と続く -->
    </div>
  </div>
</body>

Tailwind CSS のクラスで全部スタイリングされてるので、HTML が読める人なら「ここの色を変えたい」「この余白を詰めたい」って修正が自分でできるんですよね。

これを CLI で変換すると:

uv run html-screenshot --file architecture.html --output architecture.png

ぶっちゃけ僕が作るよりいい時がある

使ってて驚いたのが、ベン図とか比較系に関してはすごくいいんですよ。配色のバランス、要素の配置、余白の取り方。Claude は CSS の知識が豊富だから、Tailwind のクラスを適切に組み合わせて整ったデザインを出してくる。

全部が良いわけじゃないです。でも「たまに自分より上手いの出してくる」っていうのがリアルなところで、そういう時は素直にそのまま活用をしています。あとは、何ラリーかして補正すれば大体はいけますね。

うまくいかないパターン

正直に言うと、ダメなパターンもあります。

要素が多すぎる図。720px の高さに収めないといけないので、10個も20個も要素がある図は厳しい。はみ出すか、文字が小さくなりすぎる。

指示が曖昧な時。「いい感じの図を作って」みたいなざっくりした指示だと、汎用的すぎるデザインが出てくる。「3層アーキテクチャで、各層にアイコン付きで」くらい具体的に言った方がいい結果が出ます。

あと地味に困るのが Tailwind CDN の読み込みタイムアウト。ネットワークが不安定な時にたまに起きる。変換ツールは wait_until="networkidle" で外部リソースの読み込みを待つ設計なので、CDN が遅いとそのまま待ち続けちゃう。まあ、再実行すればだいたい解決しますけど。（この辺は環境依存です）

スキルを「育てる」: reference フィードバック

ここからが今回の記事で一番伝えたいところです。

良いデザインを reference に保存する

さっき「デザインパターンのお手本集を別ファイルに分けてある」と書きました。これが references/examples.md で、スキルが図解を生成する時に参照するお手本集です。

やることは単純で、気に入ったデザインの HTML コードをこのファイルに追記するだけ。

.claude/skills/diagram-generator-html/
  SKILL.md                    ← スキル本体（Level 2）
  references/
    examples.md               ← ここにお手本を追加していく（Level 3）

SKILL.md から examples.md へのリンクが既にあるので、ファイルに追記するだけで Claude が次回から参照してくれます。

1つ注意点があって、SKILL.md から明示的に参照（リンク）されていないファイルは Claude が認識しません。references/ にファイルを置いただけでは駄目で、SKILL.md 内に [examples.md](references/examples.md) みたいなリンクが必要です。既にリンクがあるファイルに追記する分には問題ないですけど、新しいファイルを追加する場合は忘れずに。

Before/After: reference 追加で出力はどう変わるか

ここが核心。reference にパターンを追加すると、実際にスキルの出力がどう変わるのか。

今回は examples.md にまだ入っていない「タイムライン図」で試してみます。

Before（reference にタイムライン図がない状態）

「プロジェクトの開発タイムラインを図にして」と指示。正直、微妙だった。悪くはないんだけど、うちのブログの図じゃない。配色もアイコンの使い方も、プロジェクトで統一しているルールが反映されてない。

After（良いタイムライン図を reference に保存した後）

同じ「タイムライン図を作って」という指示なのに、出てきたものが全然違う。配色もアイコンの使い方もブログのトンマナに合っている。これ初めて見た時、マジで「おっ」ってなりました。しかもここから「ステップを5つに増やして」みたいなカスタマイズもできる。reference のパターンをベースに、さらに調整が効くんですよね。

見比べると違いがわかると思います。reference があると、Claude は「このプロジェクトではこういうデザインが求められている」という文脈を持った状態で図を生成する。指示が同じでも、出力の解像度が上がるんですよね。

reference が増えてもスキル起動コストは変わらない

Progressive Disclosure の Level 3 の設計がここで効いてきます。

references/ ディレクトリのファイルは、スキルが起動した時に自動で全部読み込まれるわけじゃないんです。Claude が「必要だ」と判断した時にだけ読み込まれる。だから、お手本パターンを10個追加しようが50個追加しようが、スキルの起動時に消費するトークンは変わらない。

これ、地味だけどかなり重要で。パターンを追加するデメリットがほぼないんですよ。「良いデザインが出たら保存する」をひたすら繰り返すだけでスキルが育っていく。

あと、Git で管理されているので、チームで共有できるのも良い。僕が見つけた良いパターンをコミットすれば、チーム全員のスキルが育つ。「AIに教える」というより「お手本集を充実させる」イメージですね。

正直な現在地

定型的な図解（アーキテクチャ図、フロー図、比較図、ベン図あたり）はかなり使えるレベルになりました。reference にパターンを蓄積するほど品質が安定してきているのは実感があります。

でも、毎回100点のデザインが出るわけじゃない。「たまにいい」が正直なところです。複雑なインフォグラフィックとか、独創的なレイアウトが必要な図はまだ難しい。Figma レベルの自由度はないです。

HTMLだから自力で修正できるのが救いで、「80点のものが出てきたら、残り20点は自分で調整する」くらいの付き合い方がちょうどいい。reference の蓄積が進めば、この80点が85点、90点になっていくんだろうなとは思ってます。トークンを気にしないのであれば、何ラリーかすれば普通に使える図になります。でも、マジの軽微な修正だったらコードを直接修正したほうが良いね。

将来的には完全に図化をAIに丸投げできたらうれしい。でも今はまだその途中で、「育てている最中」っていうのが正直な現在地です。

まとめ

技術ブログの図解作成、Figma で人力でやってた頃と比べるとだいぶ楽になりました。SKILL で HTML 図解を自動生成して、CLI で PNG に変換する。仕組み自体はシンプルです。

でも、この仕組みの本当の価値は「育てられる」ことだと思ってます。良いデザインが出たら reference に保存する。それだけで次からの出力品質が上がる。パターンを追加するコストはほぼゼロ。この成長サイクルが回り始めると、使えば使うほどスキルが育っていく。

完璧じゃないけど、育てていける。みんなも自分のスキルを育ててみない？

ほなまた〜

作ってみよう: 構築手順

ここからは「自分の環境でも作りたい」って人向けの構築手順です。必要なのは3つ: 図解生成スキル（SKILL.md）、お手本集（references）、PNG変換ツール。

最終的なディレクトリ構成はこうなります:

.claude/skills/diagram-generator-html/
├── SKILL.md                    ← スキル定義本体（Step 1）
└── references/
    └── examples.md             ← デザインパターンのお手本集（Step 2）

SKILL.md がスキルの本体で、references/ 以下がお手本集。PNG変換ツール（Step 3）は別途用意します。この構成が記事前半で説明した Progressive Disclosure の Level 2（SKILL.md）と Level 3（references/）にそのまま対応しています。

Step 1: 図解生成スキル（SKILL.md）を配置する

.claude/skills/diagram-generator-html/ ディレクトリを作って、SKILL.md を配置します。僕が実際に使っているスキル定義をそのまま載せます。

frontmatter（スキルの設定部分）:

---
name: diagram-generator-html
description: |
  This skill should be used when the user asks to "HTMLで図を作って", "Tailwindで図解を生成して",
  "アーキテクチャ図を作成して", "フロー図を作って", "比較図を生成して", or needs a technical diagram
  for a blog article using HTML and Tailwind CSS.
allowed-tools: Read, Write, Bash
---

SKILL.md の本体:

# Diagram Generator HTML

技術ブログ記事用のHTML図解を生成し、PNG画像に変換します。

## Supported Patterns

| パターン | 用途 |
|---------|------|
| アーキテクチャ図 | レイヤード、マイクロサービス、イベント駆動 |
| フロー図 | プロセス、データ、ユーザーフロー |
| 関係図 | ER図、クラス図、シーケンス図 |
| 比較図 | Before/After、オプション比較 |
| コンポーネント図 | システム構成、デプロイメント |
| 概念図 | コンセプトマップ、ツリー構造 |
| 同心円図 | 階層構造、抽象度の層、ベン図ライク |
| ディレクトリツリー図 | ファイル構成、フォルダ階層、プロジェクト構造 |

## Specifications

- **サイズ**: 1280 x 720 px (16:9)
- **技術**: HTML5 + Tailwind CSS + Material Icons
- **出力**: PNG画像
- **保存先**: `docs/article/[feature-name]/images/`

## HTML作成ルール

1. **固定サイズ**: `<body class="w-[1280px] h-[720px] m-0 p-0 overflow-hidden bg-[背景色]">`
2. **外側padding**: `p-8` または `p-10`
3. **要素間隔**: `gap-4`
4. **Tailwind CDN**: `<script src="https://cdn.tailwindcss.com"></script>`
5. **最小フォント**: `text-sm` (14px) 以上
6. **禁止事項**: JavaScript動的要素、アニメーション、カスタムCSS

## Accessibility

- コントラスト比: WCAG Level AA準拠 (4.5:1以上)
- セマンティックHTML: `role="img"`, `aria-label`
- 色依存の回避: 色 + 形状の組み合わせ

## Color Palette

| 用途 | Class |
|------|-------|
| Primary | `bg-blue-500`, `text-blue-900` |
| Secondary | `bg-green-500`, `text-green-900` |
| Accent | `bg-orange-500`, `text-orange-900` |
| Background | `bg-white`, `bg-gray-50` |

## Workflow

### 1. 情報収集

必要な情報:
- 図解タイプ（アーキテクチャ、フロー等）
- 含める要素
- 保存先記事ディレクトリ

### 2. HTML生成

基本テンプレート:

```html
<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <title>[タイトル]</title>
    <script src="https://cdn.tailwindcss.com"></script>
    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200" />
</head>
<body class="w-[1280px] h-[720px] m-0 p-0 overflow-hidden bg-white">
    <div class="w-full h-full bg-white flex items-center justify-center p-10" role="img" aria-label="[説明]">
        <!-- 図解内容 -->
    </div>
</body>
</html>
```

**詳細なパターン例**: [examples.md](references/examples.md)

### 3. ファイル保存

保存先: `docs/article/[feature-name]/images/[ファイル名].html`

### 4. PNG変換

```bash
uv run html-screenshot \
  --file docs/article/[feature-name]/images/[ファイル名].html \
  --output docs/article/[feature-name]/images/[ファイル名].png
```

## Validation Checklist

- [ ] `<!DOCTYPE html>` 宣言がある
- [ ] Tailwind CDN が読み込まれている
- [ ] `<body>` に固定サイズクラスがある
- [ ] 外側divに `p-8` または `p-10` がある
- [ ] JavaScript/アニメーションが含まれていない
- [ ] `role="img"` と `aria-label` が設定されている

## Troubleshooting

| 問題 | 対処 |
|------|------|
| PNG変換失敗 | HTMLファイルのパスを確認、`--force`で上書き |
| 200KB超過 | HTMLを簡素化、サイズを縮小 |
| ディレクトリ不在 | 先に作成してから保存 |

ポイントをいくつか補足:

  • description: 日本語の呼び出しフレーズを入れておくと、「図を作って」みたいな指示でスキルが自動発火する
  • allowed-tools: Read, Write, Bash に制限。スキル実行中に余計なツールを使わせないことで動作が安定する
  • HTML作成ルール: 固定サイズ・最小フォント・禁止事項を明記。Claude は「やるべきこと」「やっちゃダメなこと」の両方が明確だと良い結果を出す
  • references リンク: 本体末尾の [examples.md](references/examples.md) が Progressive Disclosure の Level 3 への入り口。このリンクがないと Claude は references を読みにいかない ので要注意

Step 2: お手本集（references/examples.md）を用意する

.claude/skills/diagram-generator-html/references/examples.md にデザインパターンのお手本を配置します。僕の examples.md には7パターン収録されていますが、ここでは2パターン抜粋して紹介します。

アーキテクチャ図パターン

Material Icons と色分けで層を区別する縦積みレイアウト:

<div class="w-full max-w-4xl flex flex-col gap-4">
    <div class="bg-blue-100 border-2 border-blue-500 rounded-lg p-6">
        <div class="flex items-center justify-center gap-3">
            <span class="material-symbols-outlined text-5xl text-blue-600">desktop_windows</span>
            <div class="text-center">
                <h2 class="text-2xl font-bold text-blue-900">Presentation Layer</h2>
                <p class="text-sm text-blue-700 mt-1">UI・ユーザーインターフェース</p>
            </div>
        </div>
    </div>

    <div class="text-center">
        <span class="material-symbols-outlined text-5xl text-gray-400">arrow_downward</span>
    </div>

    <div class="bg-green-100 border-2 border-green-500 rounded-lg p-6">
        <!-- 同様の構造、色をgreen系に変更 -->
    </div>
</div>

レイヤー数に応じて色を blue → green → orange の順に使うのがコツ。

フロー図パターン

ステップを中央揃えで縦に並べ、ノードの形状でステップ種別を表現:

<div class="flex flex-col items-center gap-4">
    <div class="bg-green-500 text-white rounded-full px-8 py-4 text-lg font-bold shadow-lg">
        開始
    </div>
    <div class="text-gray-400 text-4xl">↓</div>
    <div class="bg-blue-500 text-white rounded-lg px-8 py-4 text-center shadow-lg">
        <p class="text-lg font-bold">認証情報入力</p>
        <p class="text-sm mt-1">ユーザーID・パスワード</p>
    </div>
    <div class="text-gray-400 text-4xl">↓</div>
    <div class="bg-red-500 text-white rounded-full px-8 py-4 text-lg font-bold shadow-lg">
        完了
    </div>
</div>

rounded-full が開始/終了ノード、rounded-lg が処理ノード。この区別だけでフローチャートっぽくなります。

他にも比較図、同心円図、ディレクトリツリー図などのパターンがあります。最初から全部揃える必要はなくて、1〜2パターンで始めて、気に入った出力が出たら追記していけばOK。この積み重ねがスキルを育てることになるので。

Step 3: HTMLからPNGに変換する

スキルが生成するのはHTMLファイルなので、ブログに貼るにはPNG変換が必要です。

CLIツール（html-screenshot）

僕は Python + Playwright で自作のCLIツールを使っています。できることベースで紹介すると:

オプション説明デフォルト
--file, -fHTMLファイルから変換–
--html, -HHTML文字列から直接変換–
--output, -o出力先PNGパスoutput.png
--width, -w幅（px）1280
--height, -h高さ（px）720
--force, -F既存ファイルの上書きFalse
# 基本: HTMLファイルからPNGに変換
uv run html-screenshot --file diagram.html --output diagram.png

# サイズ指定
uv run html-screenshot --file diagram.html --output diagram.png --width 1920 --height 1080

# HTML文字列から直接変換（ちょっとした確認用）
uv run html-screenshot --html "<h1>Hello</h1>" --output test.png

内部処理は4ステップ:

  1. Playwright で Chromium をヘッドレス起動
  2. file:// プロトコルで HTML を読み込み
  3. wait_until="networkidle" で Tailwind CDN 等の外部リソース読み込みを待機
  4. body 要素のスクリーンショットを PNG で保存

HTML側で w-[1280px] h-[720px] と固定しているので、ビューポートに関係なく毎回同じサイズの PNG が出ます。

代替案: Playwright MCP

CLIツールを自作するのが手間なら、Playwright MCP を使う方法もあります。Claude Code から Playwright のブラウザ操作を直接呼び出せるので、HTML を開いてスクリーンショットを撮る操作が MCP のツールで完結します。

セットアップ方法は別の記事で詳しく書いているので、こちらを参照してください:

CLIツールとPlaywright MCPの使い分け:

観点CLIツールPlaywright MCP
セットアップPython + Playwright パッケージMCP サーバー設定
安定性ローカル完結で安定MCP 接続に依存
トークン消費少ないツール定義分の消費あり
汎用性HTML→PNG 変換に特化ブラウザ操作全般

「HTML を PNG に変換したいだけ」なら CLI の方がシンプルで安定します。一方で、スクリーンショット以外のブラウザ操作も Claude Code にやらせたいなら Playwright MCP の方が汎用性は高い。自分の用途に合った方を選んでください。

関連ブログ / 参考リンク

ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？

役に立った 役に立たなかった

0人がこの投稿は役に立ったと言っています。
エンジニア募集中!

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

前の記事

Claude Code Agent Teams に記事を丸投げ…