目次

AIエージェントに、ある機能を実装する3つの方法を尋ねたとします。返ってくるのは長いMarkdownの回答です。まず方法A、次に方法B、そして方法C。どの案がリトライに対応しているか確かめるために上へスクロールし、複雑さを比べるために下へスクロールします。選び終えるころには、頭の中で比較表を組み立て直しているはずです。

代わりに、単一のHTMLファイルを頼んでみましょう。エージェントは各案を横に並べ、関連するコードのそばにトレードオフを置き、違いを1つの画面で見えるようにできます。

これが、HTMLの驚くべき有効性 — 実例集 ↗の基本的な考え方です。このページでは、実装計画からチケットの仕分けまで、9種類の作業にわたる20の例を紹介しています。どの例も、ビルド工程が不要な単一ファイルのページです。

役に立つのは、ちょっとした頼み方の変更です。最初から最後まで読む文章を毎回書かせるのではなく、確認したり操作したりできるものを作るよう、エージェントに頼むのです。

1. 検討と計画：方針を決める前に比較する#

方針が明確になった後は、Markdownがよく機能します。しかし検討の段階では、目的が比較であっても、選択肢を順番に読まなければなりません。

HTMLなら、それらの選択肢を同じ画面に並べられます。このページには、次の例があります。

  • 3つのコード実装案： 3つの解決策を横に並べ、それぞれにトレードオフを添える。
  • ビジュアルデザインの方向性： レイアウトや配色の候補を描画し、見たものに対して意見を出せるようにする。
  • 実装計画： マイルストーン、データフロー図、モックアップ、リスクのあるコード、リスク一覧表を、実装に使える1つの文書にまとめる。

デザインの例を見ると、利点は明らかです。「控えめな配色のコンパクトなインターフェース」という説明には、解釈の余地が大きく残ります。実際に描画されたレイアウトなら、採用するかどうかを具体的に判断できます。

コードを比較するときは、すべての案に同じ見出しを使うよう指定しましょう。依存関係、障害への対処、想定される作業範囲、保守コストなどです。そうしないと、見栄えのよいカードに、比較条件の不揃いが隠れてしまうことがあります。

まず方向性を選びましょう。その後で、その選択を実装計画に落とし込むようエージェントに頼みます。

2. コードレビューと理解：コードのそばに文脈を置く#

差分は、もともと空間的な配置に意味がある文書です。行の位置、近くの変更、ファイル間の関係が重要になります。Markdownのレビューでは、指摘と、その指摘が説明しているコードが離れてしまいがちです。

HTMLなら、説明を根拠の近くに置けます。

  • 注釈付きプルリクエスト： 差分に余白の注釈、重要度タグ、該当箇所へのリンクを追加する。
  • レビュアー向けのPR説明： 変更の動機、変更前後の挙動、各ファイルを変更した理由、重点的に確認すべき箇所を説明する。
  • モジュールマップ： なじみのないパッケージを箱と矢印で描き、エントリーポイントやよく使われる経路を示す。

これらのページは、それぞれ異なる読み方を支えます。注釈付き差分は変更の精査に、PR説明は変更の目的の理解に、マップはコードベース内の移動に役立ちます。

可能な場合は、ファイルパスと行番号を必ず付けるよう指定しましょう。モジュールマップでは、確認済みの呼び出しと推測した関係を区別するようエージェントに頼みます。整った図は、裏付けのない仮定まで確かなものに見せてしまうことがあります。

レビュアーが元のコードへすぐにたどり着けるページにしましょう。

3. デザイン：実際の見た目を確認する#

Markdownで色の値を列挙すれば、パレットを記録できます。しかし、色を組み合わせたときの見え方は分かりません。無効状態のボタンも、文章で説明するより実物を表示したほうが伝わります。

HTMLはブラウザを使い、検討しているものを実際に描画します。

  • 生きたデザインシステム： リポジトリから色、タイポグラフィ、余白のトークンを抽出し、コピーできる見本として表示する。
  • コンポーネントのバリエーション： コンポーネントのサイズ、状態、想定用途を1つのページに並べる。

コンポーネントのレビューでは、マトリクス形式を指定しましょう。列にサイズ、行に状態を配置します。該当する場合は、読み込み中、無効、フォーカス、エラーの各状態も含めます。

ブラウザで見ると、余白の不揃いや見た目の区別の弱さに気づきやすくなります。また、レビュアー同士で共通の参照先を持てます。「小サイズの読み込み中ボタン」と言えば、ボタンの挙動を説明する段落より正確に対象を示せます。

ページを正確な参照資料として扱う前に、抽出されたトークンを元のファイルと照合しましょう。便利なスナップショットですが、最新の状態に保つかどうかは別途決める必要があります。

4. プロトタイピング：挙動を実際に試してもらう#

Markdownでは、画面遷移の時間やイージング曲線を説明できます。しかし、その遷移が遅すぎるかどうかを体感することはできません。

HTMLなら、小さな動作実験を作れます。

  • アニメーションの実験環境： 1つの遷移を切り出し、時間とイージングを調整するスライダーを付ける。
  • クリックできる操作フロー： 4つの画面をつなぎ、一連の操作を試せるようにする。

こうしたプロトタイプは、範囲を絞りましょう。アニメーションの実験環境は、動きに関する疑問に答えるものにします。クリックできる操作フローは、次に何をすればよいか利用者が理解できるかを確かめるものにします。

サンプルデータを使い、簡単にリセットできるようにしましょう。確認したいのが画面間の移動だけなら、認証、データの永続化、バックエンドは追加しません。

4つの画面をつなぐだけでも、戻る操作の欠落や分かりにくい確認ステップを発見できます。実装後に修正コストが膨らむ前に、問題を見つけられるのです。

5. イラストと図：関係を描く#

文章は、個々の手順を説明するのに向いています。しかし、複数の経路が分岐したり、合流したり、異なる形で失敗したりすると、追いにくくなります。

HTMLにはインラインSVGを含められるため、エージェントは編集可能な図や操作できるダイアグラムを作れます。

  • SVG図版シート： 記事用の図版を1つのページに集め、それぞれを修正したり取り出したりできるようにする。
  • 注釈付きフローチャート： デプロイの流れを示し、各ステップをクリックすると、実行内容、所要時間、失敗後の処理が分かるようにする。

デプロイの図では、正常時の経路と失敗時の経路の両方を指定しましょう。成功する手順しか含まない図は、完成しているように見えても、運用担当者に必要な情報が抜けている場合があります。

重要なラベルは常に表示しておきましょう。基本的な流れを隠すのではなく、補足情報をクリックで開くようにします。

インラインSVGは、ラベルや矢印を修正したいときに特に便利です。図がファイルの一部として残るため、別の画像を再生成する必要がありません。

6. スライド：短い説明をブラウザのページにする#

Markdownの見出しで概要は作れますが、会議では話を進めるテンポも必要です。参加者が文書全体をスクロールせずに、いま説明している要点を見られるようにしましょう。

矢印キーで操作するスライドの例は、単一のHTMLファイルを短いプレゼンテーションに変えます。各セクションがスライドになり、少量のJavaScriptで移動を制御します。スライドの例 ↗で、この方法を確認できます。

役に立つ依頼には、対象者、決めたいこと、分量の上限を含めます。「10分間のアーキテクチャレビュー用に6枚のスライドを作ってください。最後に、決定が必要な事項を示してください」といった具合です。

会議で使うブラウザでファイルを開き、事前にキーボード操作を確認しましょう。オフラインで使う必要があるなら、すべてのスタイル、スクリプト、アセットをファイル内に含めるよう指定します。

7. 調査と学習：説明を調整できるようにする#

長いMarkdownの説明では、読者がそれぞれ異なる疑問を持っていても、ほぼ同じ順序で読み進めることになります。

HTMLなら、読者が詳細を展開したり、例を切り替えたり、モデルを操作したりできます。

  • 機能の仕組み： 要約ボックス、折りたためる処理段階、タブで切り替える設定例、FAQを使って、リポジトリのレート制限を説明する。
  • 概念の解説： 読者がノードを追加・削除できるリングでコンシステントハッシュ法を教え、比較表とリンク付き用語集で補足する。

操作に価値があるのは、原因と結果が見えるときです。ハッシュリングからノードを削除したら、どのキーが移動するのか、その理由とともに示すべきです。

リポジトリの説明では、関連コードへのリンクや参照を求めましょう。概念モデルでは、どこを単純化したか明記するようエージェントに頼みます。操作できるデモは、実運用の細部をすべて再現せずとも、原理を説明できます。

8. レポート：定期的な情報をひと目で把握できるようにする#

週次報告やインシデント報告では、同じ構成が繰り返されることがよくあります。Markdownでも事実は伝えられますが、読者は遅延、変更、未解決の作業を段落の中から探さなければなりません。

HTMLなら、繰り返し登場する情報を毎回同じ位置に配置できます。

  • 週次の進捗報告： リリース済みの作業と遅延している作業を分け、データがある場合は小さなグラフを添える。
  • インシデントのタイムライン： ログの抜粋と再発防止チェックリストを添え、出来事を分単位の時系列で並べる。

毎週同じレイアウトを使えば、読者は見る場所が分かります。報告対象期間を上部に置き、グラフには単位を付け、欠けているデータを明示しましょう。

インシデントでは、観測された出来事と後からの解釈を区別します。タイムスタンプ付きのログと、推定される原因を同じように扱ってはいけません。

書式は、読者が根拠を見つける助けになります。しかし、収集されていない根拠を補うことはできません。

9. 専用の編集画面：結果を普段の作業に戻す#

テキストボックスでは表現しにくい判断もあります。30件のチケットの並べ替えは、その一例です。ドラッグ＆ドロップできるボードなら、順序を直接変更できます。

このページには、次の編集ツールがあります。

  • チケットのトリアージボード： チケットを「今やる」「次にやる」「後でやる」「対象外」に移動し、結果をMarkdownとしてコピーする。
  • 機能フラグエディター： 切り替え項目を領域ごとにまとめ、前提条件がオフなら警告し、変更したキーだけをコピーする。
  • プロンプト調整ツール： 変数を強調表示したテンプレートと3つのサンプル入力を並べ、入力に合わせて生成結果の表示を更新する。

最も重要な要件は、エクスポートボタンです。これがなければ、判断した内容がページの中に閉じ込められてしまいます。

画面を依頼する前に、出力形式を指定しましょう。計画書ならMarkdown、構造化データならJSON、設定変更なら差分です。リセット時の動作と、未保存の編集があることを明確に示す表示も指定します。

編集ツールが役に立つのは、エージェントとの会話に貼り付けたり、リポジトリにコミットしたりできる結果を返すときです。

明日試すなら、この3つから1つ選ぶ#

結果をすぐに確認できる作業から始めましょう。

1. 実際の意思決定を比較する。 比較基準を統一し、前提条件の一覧を見える場所に置いた3つのコード実装案を頼みます。 2. 定期的な報告を改善する。 既存の報告書と確認済みの数値を使い、週次の進捗報告を頼みます。 3. 既存のバックログを仕分ける。 チケットIDを保持し、分類した結果をMarkdownで出力するチケットのトリアージボードを頼みます。

どれを選ぶ場合も、次の指示を加えましょう。

> CSSとJavaScriptをインラインで含む、自己完結した単一のHTMLファイルを返してください。提供された事実だけを使い、不明な点は明示し、ページ上で行った判断を出力できるエクスポートボタンを付けてください。

編集、検索、バージョン管理が必要な文章には、引き続きMarkdownが適しています。比較、空間的な関係、動き、直接操作が必要な作業では、HTMLを使う価値があります。

実例ギャラリー ↗を開き、明日の作業に合うページを1つ選んで、自分の資料を使った版を作るようエージェントに頼んでみましょう。

目次