01:02:50
Figma
イベント
該当するコンテンツが見つかりませんでした
マガジン
該当するコンテンツが見つかりませんでした
技術ブログ
ジャンプTOON ソフトウェアエンジニアの國師 (@ronnnnn_jp) です。 この記事では、仕 ...
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）で、やってることはシンプルです: Chromium をヘッドレスで起動 HTMLファイルを file:// プロトコルで読み込み Tailwind CDN や Material Icons の読み込み完了を待機（ wait_until="networkidle" ） 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 , -f HTMLファイルから変換 – --html , -H HTML文字列から直接変換 – --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ステップ: Playwright で Chromium をヘッドレス起動 file:// プロトコルで HTML を読み込み wait_until="networkidle" で Tailwind CDN 等の外部リソース読み込みを待機 body 要素のスクリーンショットを PNG で保存 HTML側で w-[1280px] h-[720px] と固定しているので、ビューポートに関係なく毎回同じサイズの PNG が出ます。 代替案: Playwright MCP CLIツールを自作するのが手間なら、 Playwright MCP を使う方法もあります。Claude Code から Playwright のブラウザ操作を直接呼び出せるので、HTML を開いてスクリーンショットを撮る操作が MCP のツールで完結します。 セットアップ方法は別の記事で詳しく書いているので、こちらを参照してください: Playwright MCPで始めるブラウザ自動化｜環境別セットアップガイド CLIツールとPlaywright MCPの使い分け: 観点 CLIツール Playwright MCP セットアップ Python + Playwright パッケージ MCP サーバー設定 安定性 ローカル完結で安定 MCP 接続に依存 トークン消費 少ない ツール定義分の消費あり 汎用性 HTML→PNG 変換に特化 ブラウザ操作全般 「HTML を PNG に変換したいだけ」なら CLI の方がシンプルで安定します。一方で、スクリーンショット以外のブラウザ操作も Claude Code にやらせたいなら Playwright MCP の方が汎用性は高い。自分の用途に合った方を選んでください。 関連ブログ / 参考リンク 図解作成が驚くほど楽に！Claude SkillでSVG自動生成 Claude Code SkillでHTML図解を自動生成！時短テクニック ClaudeでMermaid図作成を自動化！2時間→5分の劇的時短術 Playwright MCPで始めるブラウザ自動化｜環境別セットアップガイド Claude Code 公式ドキュメント（Skills） Playwright 公式ドキュメント ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post 図解作成、AIに丸投げしたら「たまに自分より上手い」件 — Claude Code を育てる方法 first appeared on SIOS Tech Lab .
こんにちは。ラクス フロントエンド開発課 新卒2年目の持永です。 最近AI活用が進み、コードを書く速度は以前とは比較にならないほど上がりました。 そこで私は、 「AIに並列で実装を任せれば、複数の画面/機能を"爆速"で開発できるのでは？」 と考え、複数画面・複数機能を並列で進めるスタイルに挑戦しました。 並列開発の中で、工夫してうまくいった点もありました。 ただ、期待したほどの効率化には至らず、「手戻りの連鎖」と「レビュー負荷の増大」も招きました。 今回は、並列開発で工夫した点と誤算を整理し、そこから得た気づきを共有します。 1. 試したアプローチと結果 2. 工夫した点①：AI向けの仕様書と計画書を用意した 作成の流れ 効果 3. 工夫した点②：ローカル構成の整理 ポイント 効果 4. 誤算①：未確定要素による「手戻りの増加」 何が起きたか なぜ起きたか どうすべきだったか 5. 誤算②：並列ばかり意識して、レビューを含む全体最適を見失った 何が起きたか なぜ起きたか どうすべきだったか 6. まとめ 工夫した点 誤算 気づき さいごに 1. 試したアプローチと結果 使用したAIツールはCodexとClaude Codeです。 私が担当しているプロダクトのフロントエンド開発チームは二人体制で進めていました。 試したアプローチとしては、約1ヶ月半の実装期間で主に画面単位（一覧画面、詳細画面、編集画面など）でコンフリクトが起きない範囲を見極めつつ、4〜5画面を並列で進めました。 結論から言うと、直列で進める前提で立てていた見積もりを約1週間ほどオーバーしてしまいました。 2. 工夫した点①：AI向けの仕様書と計画書を用意した AIに正確に実装させるかつ人間側が進捗と作業範囲を把握することを目的に、AI向けの仕様書と実装計画書を用意しました。 作成の流れ 1. フロントエンド向け仕様書の作成 案件の情報（要求仕様や概要設計などの上流仕様書、Figmaのリンク、API定義）を材料に、フロントエンド実装に必要な情報だけを抽出した仕様書をAIで作成 2. 仕様書のレビュー・修正 AIが出力した仕様書を自分でレビューし、不足や誤りがあれば修正を指示して内容を整形 3. 実装計画書の作成 整形した仕様書をもとに、実装計画書をAIと共に作成 4. 計画書に沿った実装 実装計画書に沿って、AIに実装を進めてもらう 実装計画書(イメージ) - [x] 1. コンポーネントの基本構造を作成 - [x] 2. API呼び出し処理を実装 - [ ] 3. バリデーションロジックを追加 ← 今ここ - [ ] 4. エラーハンドリングを実装 - [ ] 5. ローディング状態の表示を追加 効果 計画書をチェックリスト形式にしたことで、AIが今どこを実装しているのかが一目でわかるようになりました。 並列で複数の機能を進めていても、それぞれの計画書を見れば「機能Aは3番目のステップ」「機能Bは5番目で完了間近」といった進捗を把握しやすくなりました。 結果として、作業を切り替えるたびに私が進捗を思い出したり確認したりする手間が減りました。 3. 工夫した点②：ローカル構成の整理 AIへの参照範囲の説明コストを下げつつ、並列開発の作業切り替えを分かりやすく素早く行うことを目的に、ローカルの資材配置を整理していました。 git worktree などで複数ブランチを同時に触ると、作業ディレクトリが増えていきます。 その状況でAIに、「案件や機能ごとに、現状のフロントエンド実装がバックエンド実装やAPI仕様と整合しているか」を確認させるとき、参照させる範囲や前提（どのブランチ/どの資材なのか）を的確に渡すための手間が増えてしまいます。 そこで、案件/機能ごとにフロントエンド/バックエンド/API仕様の資材をひとまとまりにしつつ、別途「バージョン確定時点の固定セット」も置く、という形にしていました。 この構成自体もAIに指示して組んでもらいました。 ローカルディレクトリ構成(イメージ) ＊ 担当プロダクトはポリレポ構成（フロントエンド・バックエンド・API仕様がそれぞれ別リポジトリ）で開発されています。 workspace/ ├── vX.Y.Z/ │ ├── epic-1/ # 案件ごと │ │ ├── feature-a/ # 主に機能/画面ごと │ │ │ ├── AGENTS.md # ブランチ指定、役割等の説明 │ │ │ ├── CLAUDE.md # ブランチ指定、役割等の説明 │ │ │ ├── plan.md # 実装計画書 │ │ │ ├── frontend/ │ │ │ ├── backend/ │ │ │ └── api-spec/ # API定義 │ │ ├── feature-b/ │ │ │ └── ... │ │ └── spec-epic-1/ # 案件の仕様 │ └── fixed-vX.Y.Z/ # 確定資材（ブランチ/コミット固定） │ ├── frontend/ │ ├── backend/ │ └── api-spec/ └── templates/ └── spec_template.md #仕様書のテンプレート ポイント 各feature直下に配置したAGENTS.mdやCLAUDE.mdにて、「このブランチで作業すべき」「このディレクトリ内のapi-specは今回開発したい案件の確定済みのAPI定義である」といった前提情報をAIに伝えるようにしていたことで、AIによる意図しないブランチ変更や誤った参照を減らすことができました。 効果 この構成にしたことで、AIに依頼するときに「どこを見てほしいか」を一言で指定しやすく、横断的な参照もしてもらいやすくなりました。 例えば「このバージョンのこの範囲で、フロントエンド/バックエンド実装とAPI仕様の不整合箇所を見てほしい」といった依頼を、細かいブランチなどの指定を毎回することなく依頼できるようになりました。 結果として、開発中のAPI仕様や実装との整合性チェックや、バージョンごとの不具合調査における原因切り分けといった場面での横断的な分析で、この整理が役に立ちました。 4. 誤算①：未確定要素による「手戻りの増加」 開発段階では、画面の文言や共通仕様が完全には確定していないこともあります。 その状態で複数の機能を並列で進めていき、次のような事態が起きました。 何が起きたか 実装途中で「文言の変更」や「仕様の微調整」が発生 文言が少し変わるだけでも、実装計画書の該当箇所をすべて修正する必要があった 並列で実装していた他の機能にも同じ変更が関係する場合、そちらの計画書も修正が必要に 「資料の修正 → AIへの再依頼 → 生成物の差分確認」という往復が複数の作業で同時に発生し、手戻りが連鎖していきました。 なぜ起きたか AIになるべく正確に実装させようと実装計画書をAIと共に調整していく際に、細かく書きすぎていたことが主な原因でした。 並列で動かしているほど、確定していない要素の影響が広がりやすくなります。 細かすぎる実装計画書を作成したために小さな変更が入るだけで周辺資料の調整コストが積み上がり、結果として全体の効率が落ちてしまいました。 どうすべきだったか 並列開発そのものが悪いのではなく、「後で変わりやすいもの」と「早めに固めたいもの」を切り分けるべきだったと考えます。 具体的には、以下の点が挙げられます。 文言のように後で直せるものは差分を小さく保つか、Figma上の文言を正として計画書にはリンクのみを記載して参照先を分離しておく。 変更されやすい要素を最初から細かく指定しすぎず、揺れにくい部分（ロジックや設計）から先に積み上げる計画にする。 5. 誤算②：並列ばかり意識して、レビューを含む全体最適を見失った もう一つの問題は、並列で進めることに意識が向きすぎて、レビューまで含めた「全体としての進めやすさ」を考えきれていなかった点です。 何が起きたか 複数を並行して進めていたため、最初のPRを出すまでに時間がかかった その間、レビュワーはレビューできる対象がない状態が続いた 複数のレビュー依頼がほぼ同時期になり、レビュワーへの負荷が集中 指摘対応も同時期に重なる 自分以外から見ると進捗が把握しづらい状態に なぜ起きたか 自分としては「手を止めない」ことを優先して作業を積み上げがちになっていました。 AIを活用することで自分の実装ペースだけは維持できてしまうため、レビュワーとのペースのズレに気づきにくくなっていました。 どうすべきだったか 並列で進めるなら、なおさらPRの粒度・順番・レビュー依頼のタイミングを「自分の都合」だけで決めず、レビュワーと認識合わせした上で進めるべきでした。 具体的には、以下の点が挙げられます。 先に固めたいロジックや設計だけを小さく切って早めに見てもらうことを留意して、並列で進める優先順位を決める。 レビューが走っている間に次の作業を進めつつ、指摘対応が滞らない余白も確保する。 6. まとめ 工夫した点 AI向けの仕様書と計画書（チェックリスト形式）を用意したことで、並列で進めていても各機能の進捗状況が一目で把握できた。 AIが参照しやすいようにローカル構成を整理したことで、開発中のAPI仕様や実装との整合性チェックや、不具合の原因切り分けがやりやすくなった。 誤算 細かすぎる実装計画書を作成して並列で進めた結果、「資料修正 → AIへの再依頼 → 差分確認」の往復が連鎖した。 PRの粒度やタイミングが極端になり、レビュー負荷と待ちが増えた。 気づき 今回の経験を振り返ると、「手戻りを減らす計画」「レビュワーとの連携の意識」といった内容は、基本的なことばかりでした。 AIによって上がった実装スピードを過信して、その「当たり前」を見失っていたことに気づきました。 今回の挑戦を踏まえた反省点は以下の通りです。 計画書に変わりやすい要素を細かく書きすぎない 文言はFigmaを参照させるように指定したり、仕様に絡む部分は仕様書側に記載することで、仕様変更時の「資料修正 → 再依頼 → 差分確認」の往復を減らす。 並列で進める上での優先度を留意する レビューも含めて、どの粒度・順序で進めるべきかを着手前に計画/認識合わせしておく。 さいごに AIのおかげで、実装自体は確かに速くなりました。 ただ、「速く作れる」ことと「全体が早く終わる」ことは別だと、今回改めて実感しました。 仕様が揺れやすい部分は揺れる前提で切り分け、レビューが滞らない粒度と優先度で小さく出して、確実にマージしていく。 結果的にチーム全体の進みが良くなるような進め方を考える力は、AIで開発を行っていく上でも変わらず求められていくものだと考えます。 同じようにAI活用×並列開発を試している方の参考になれば幸いです。
動画
書籍
