レッスン05

実践トラブルシューティング：AI対話で未知の問題を解決する思考テンプレート

ツールを使っても、実際の開発現場では予期せぬ問題が必ず発生します。このレッスンでは、単なる個別の解決策（ケーススタディ）を学ぶだけでなく、AIとの対話を通じて未知の問題を自力で解決に導くための「汎用的な思考テンプレート」を習得します。トラブルシューティングをスキルアップの最大のチャンスに変えましょう。

1. AIとの対話による問題解決フレームワーク

行き当たりばったりで質問するのではなく、以下のフレームワークに沿ってAIと対話することで、解決への道のりが劇的に早まります。

Step 1：問題の言語化と仮説立て

  • 問題を正確に言語化する：「なんか変」ではなく、「WordPressで生成したHTMLが全幅にならず、左右に余白ができる」のように、何がどうなっているかを具体的に記述します。
  • 原因の仮説を立てる：「おそらく、使用しているテーマのCSSが、コンテンツ全体の幅を制限しているのが原因だろう」のように、考えられる原因を推測します。この仮説がAIへの質問の質を高めます。

Step 2：AIへの的確な質問（プロンプトの型）

良い質問は、良い答えを引き出します。以下の「型」を意識してプロンプトを作成しましょう。

# 良いプロンプトの型

■ 状況説明（何が起きているか）
（例）WordPressの固定ページで、ツールで生成したHTMLを3つのカスタムHTMLブロック（CSS用、インタラクティブ部、記事部）に分けて配置しています。しかし、意図した全幅にならず、左右に余白ができてしまいます。

■ 仮説（原因についての推測）
（例）おそらく、WordPressテーマ（AFFINGER）が持つコンテナ要素のスタイルが原因だと考えています。

■ 期待する出力（AIに何をしてほしいか）
（例）この問題を解決するため、一番上のカスタムHTMLブロックに記述すべき「LP化用のCSSコード」を教えてください。

■ 参考情報（コードやスクリーンショット）
（例）現在のページのスクリーンショットと、ブラウザの検証ツールで確認したHTML構造を添付します。

Step 2.5：スクリーンショットと言語の併用

問題解決の精度を劇的に高めるコツは、スクリーンショットと言語説明を組み合わせることです。「百聞は一見に如かず」で、問題が発生している画面をAIに見せることで、言葉では伝わりにくい状況を即座に共有できます。

効果的な伝え方：
問題箇所のスクリーンショットを撮り、画像編集ツールで赤枠などで印をつけます。その上で、「この赤枠の部分が、スマホ表示の際にはみ出してしまいます」のように、言語で具体的に補足説明します。

この手法は、GeminiのようなマルチモーダルAIの能力を最大限に引き出し、AIが文脈を正確に理解するのを助け、より的確な解決策を引き出すことにつながります。

Step 3：検証と具体的フィードバック

AIの回答を試してもうまくいかない場合、その結果を具体的にフィードバックすることが最も重要です。

ダメなフィードバック

「ダメでした」「何も変わりません」
→ これではAIも次の手が打てません。

良いフィードバック

「提案されたCSSを試しましたが、まだ左右に余白が残っています。検証ツールで調べたところ、#container というIDを持つさらに外側の要素が余白を持っているようです。この要素も含めて全幅にするにはどうすれば良いですか？」
→ AIは新たな情報をもとに、より精度の高い解決策を提案できます。

Step 4：解決策のテンプレート化

問題が解決したら、その知識を「未来の自分」や「他のメンバー」のために再利用可能な形で保存します。これがナレッジマネジメントの第一歩です。

  • 解決に至ったCSSやHTMLコードを、使い方や注意点をコメントで追記してテキストファイルに保存します。
  • プロジェクト内に「_templates」や「テンプレート」フォルダを作り、そこに集約します。

2. 手動実行モードによる体系的な復旧フロー

APIエラーなどでツールの自動処理が中断した場合、GUIの「手動実行モード」タブを活用することで、問題が発生した箇所から処理を再開できます。このタブは、自動処理の各ステップを個別に実行するためのプロンプトを生成する機能です。

  1. エラー箇所の特定: コマンドプロンプトのログを見て、どのステップ（例: `【2】記事本文リライト用`）でエラーが発生したかを確認します。
  2. プロンプトの生成: GUIの「手動実行モード」タブから、エラーが発生したステップに対応するボタン（例: `【2】記事本文リライト用`）をクリックします。
  3. AI Studioでの実行: ツールが生成したプロンプトファイル（output/manual_prompts/内）と、必要な入力ファイル（例: `input/manuscript.md`）をGoogle AI Studioにアップロードして実行します。
  4. 結果の保存: AIが生成した結果を、プロンプト生成時に指示された場所（例: `output/_temp/temp_3_article_rewritten.html`）に貼り付けて保存します。
  5. 後続処理の実行: エラーが発生したステップ以降の処理を、GUIの「メイン実行」タブから個別実行ボタンを使って手動で進めます。

3. ケーススタディ：AIとの対話で解決する具体例

ケース1：テーマのCSS競合によるレイアウト崩れ

AIとの対話ログ（要約）

自分：「WordPressでHTMLが全幅にならない。たぶんテーマのせい。LP化用のCSSコードを教えて。」
↓
AI：「承知しました。こちらのCSSを一番上のカスタムHTMLブロックに記述してください。<style> .page-id-XXXX .entry-content { max-width: none; } ... </style>」
↓
自分：「ダメだった。まだ余白がある。検証したら #content-w っていう親要素がいるみたい。」
↓
AI：「失礼しました。では、その要素も対象に加えたこちらのコードをお試しください。... #content-w { max-width: none; } ...」
↓
自分：「まだダメだ…もっと外側に #container がいた。」
↓
AI：「なるほど。では最終手段として、考えられる親要素を全て指定したこのコードを試してください。... .page-id-XXXX #container, .page-id-XXXX #content-w ...」
↓
自分：「解決した！ありがとう！」

ケース2：Gemini Canvasで生成したコードの微調整

Gemini Canvasで生成したLPのコードをWordPressに移植した際に発生する、典型的な問題とその解決策です。

AIとの対話・コード修正のポイント

  • AIには複数の改善案を出させる: 「このコードを修正して」という単一の指示より、「このコードの問題点を5つ指摘し、それぞれの修正案を提示して」のように、複数の選択肢を出させる方が良い結果に繋がりやすいです。場合によっては「考えられる対策を10個リストアップして」のように、少し多めにアイデアを出させることで、自分では思いつかなかった解決策が見つかることもあります。
  • 背景色が抜ける: テーマのヘッダーは表示させつつ、コンテンツエリアだけ背景色を変えたい場合、LP全体のコンテナである<main>タグに直接背景色を指定するのが最も確実です。
  • フッターとの隙間が消えない: WordPressテーマによっては、コンテンツの末尾に目に見えない要素や余白が自動で挿入されます。これをCSSで消すのが困難な場合、LP内のフッター（<footer>）を、<main>タグ内の最後のセクション（<section>）として作り替えると、構造的に隙間がなくなり根本解決します。
  • アコーディオンが開かない: JavaScriptで高さを計算（scrollHeight）する方法は、CSSの環境に依存し不安定です。代わりに、クリックイベントでTailwind CSSのクラス（例: max-h-0 と max-h-screen）を付け替える方法が堅牢です。見た目の制御をCSSクラスに任せるのがモダンな実装です。そもそも、アコーディオンはエラーが出やすいため、どうしても上手くいかない場合は無理に採用せず、最初から全て展開された状態で表示するなど、よりシンプルなUIに変更することも有効な選択肢です。

ケース3：YouTube埋め込みコードが正常に表示されない

AIが生成したYouTubeの<iframe>埋め込みコードをカスタムHTMLブロックに貼り付けた際、動画が表示されなかったり、レイアウトが崩れたりすることがあります。これは、テーマやプラグインがコンテンツの表示を制御しているために起こる典型的な問題です。

解決策：WordPress標準の埋め込みブロックを利用する

このような場合、<iframe>コードを直接貼り付けるのではなく、WordPressのブロックエディタが提供する標準の「YouTube」ブロックや「埋め込み」ブロックを利用するのが最も安全で確実です。

カスタムHTMLブロックの代わりに「YouTube」ブロックを追加し、動画のURLを貼り付けるだけで、WordPressが自動的にテーマと互換性のある、レスポンシブ対応済みの安全なコードを生成してくれます。以下はそのコード構造の一例です。

<figure class="wp-block-embed is-type-video is-provider-youtube wp-block-embed-youtube wp-embed-aspect-16-9 wp-has-aspect-ratio"><div class="wp-block-embed__wrapper"> https://youtu.be/XXXXXXXXXXX </div></figure>

ケース4：LPのテキストが意図せず黒色になる

ダークテーマのLPを作成したにもかかわらず、特定のテキストがテーマの基本色である黒で表示されてしまうことがあります。これは、テーマのCSSがLP内のスタイルよりも優先されてしまう（詳細度が高い）ために発生します。

解決策：専用のユーティリティクラスを追加して個別に対応する

この問題は、LP全体のスタイルを上書きするのではなく、問題が発生している箇所だけをピンポイントで修正するのが最も安全です。

  1. まず、LPのHTMLを貼り付けたカスタムHTMLブロックの一番上（<style>タグ内）に、以下の「ユーティリティクラス」を追加します。
  2. 次に、ブラウザで表示を確認しながら、文字色が黒くなってしまっているHTMLタグ（例：<p>や<h3>など）に、class="text-white"を追加します。

この方法により、テーマのスタイルに影響を与えることなく、必要な部分だけ文字色を確実に白に変更できます。

/* <style>タグ内に追加するユーティリティクラスの例 */ #my-interactive-wrapper .text-white { color: #ffffff !important; } /* HTML側での適用例 */ <p class="text-white">このテキストは確実に白くなります。</p>

4. 【応用】AIによる視覚的自動修正（P11）

本ツールには、デザイン崩れをAIが「見て」自動で修正する、実験的で強力な機能【P11】が搭載されています。この機能は、WordPressのプレビュー環境と連携し、AIがスクリーンショットを分析してコードを修正するという、未来のデバッグ手法を体験できます。

実行ワークフロー
  1. 事前準備：サイト設定ファイル（.yaml）に、プレビュー用の固定ページIDとパスワードを設定します。
  2. 機能の実行：GUIの「品質・AI連携」タブから【P11】AIによるHTML視覚的自動修正ボタンをクリックします。
  3. 初期分析：ツールが「正解」となるデザイン（input/design.html）と、WordPressプレビュー環境での「現状」のスクリーンショットを撮影・比較し、ユーザーに初期の問題点を報告するよう促します。
  4. 対話による修正サイクル：ユーザーがテキストで問題点を指摘すると、AIがその指示を解釈し、コードを修正してプレビューを更新します。ユーザーは更新されたプレビューを確認し、問題が解決するまで対話を繰り返します。
  5. 最終結果の保存：修正が完了すると、最終的なHTMLコードが元のファイルに上書き保存されます。
【注意】この機能は高度な処理を行うため、正常に動作しない場合や、AIが意図しない修正を行う可能性があります。必ずバックアップを取った上で、実験的な機能としてご活用ください。

5. まとめ：トラブルはスキルアップの機会

トラブルシューティングとは、単なる「エラー潰し」の作業ではありません。それは、AIとの対話を通じて、システムの構造を深く理解し、自身の問題解決能力を鍛える絶好の機会です。このフレームワークを実践し、あらゆる問題を自らの成長の糧に変えていきましょう。