メインコンテンツへスキップ
見出し画像

Claude Code Xで話題のMarkdownよりHTMLで出力させる方が良い理由 GPT-5.5 ClaudeCode OpenClaw Antigravity Codex Obsidian Cursor Windsurf Cowork Mythos Skills NVIDIA ハーネスエンジニアリング

    こんにちはクドクラです
    今回はXで話題になったClaudeCodeにMarkdownファイルを読み込ませるよりHTMLファイルを読み込ませる方が良い理由について書かれている記事を日本語に翻訳してそのまま解説します

    画像

    元記事

    【衝撃】
    Anthropic Claude Code エンジニアチームがMarkdownよりAI時代はHTMLと断言!
    ClaudeCode Antigravity Codex Cursor Agent,Gemini CLI,OpenCode,GitHub Copilot AIエージェント使用している人はブクマ必須!pic.twitter.com/EDnRrwAjj3
    Claude Codeに読み込ませるものはMarkdownではなくHTML!… https://t.co/nkaEOwKxEX

    — Claude Code AI駆動開発 OpenClaw@クドクラ (@KudouCraft) May 9, 2026


    画像

    メンバーシップ記事↓

    人気記事↓


    AIエージェントが私たちとコミュニケーションを取る際に使用するファイル形式として、Markdownが主流になりました。シンプルで移植性が高く、リッチテキスト機能も備えており、編集も簡単です。クロードは、Markdownファイル内でASCIIを使って図を作成する技術も驚くほど上達しました。

    しかし、エージェントの能力がますます高まるにつれ、マークダウンは制約の多いフォーマットになってしまったと感じるようになりました。100行を超えるマークダウンファイルを読むのは困難です。もっと豊かな視覚化、色、図表を使いたいし、それらを簡単に共有したいのです。

    私もこれらのファイルを自分で編集することはほとんどなくなり、仕様書、参考資料、ブレインストーミングの成果物などとして利用しています。編集を行う場合も、通常はクロードに編集を依頼する形になるため、マークダウンの最大の利点の1つが失われてしまいます。

    私は出力形式としてMarkdownではなくHTMLを好んで使うようになり、Claude Codeチームの他のメンバーもHTMLを使うようになっているのを目にするようになりました。その理由は以下の通りです。

    (その理由については、後日改めてお読みください。)(例から始めたい場合は、こちらにたくさんの例があります。)

    https://thariqs.github.io/html-effectiveness

    なぜHTMLなのか?

    情報密度

    画像

    HTMLはMarkdownに比べてはるかに豊富な情報を伝達できます。もちろん、ヘッダーや書式設定といった単純な文書構造も表現できますが、その他にも以下のようなあらゆる種類の情報を表現できます。

    • 表を使用した表形式データ

    • CSSでデータをデザインする

    • SVGを使用したイラスト

    • スクリプトタグ付きのコードスニペット

    • JavaScriptとCSSを使用したHTML要素のインタラクション

    • SVGとHTMLを使用したワークフロー

    • 絶対位置とキャンバスを使用した空間データ

    • 画像タグを使用した画像

    クロードが読み取れる情報のほとんどは、HTMLでかなり効率的に表現できると言っても過言ではありません。そのため、モデルが詳細な情報をあなたに伝え、あなたがそれをレビューするのに非常に効率的な方法となります。

    これができない場合、モデルはマークダウンでASCII図や、私のお気に入りのClaude CodeのスクリーンショットにあるようなUnicode文字で色を推定するなど、より非効率的な処理を行う可能性があることがわかりました。

    Claude Code trying to show color in markdown

    画像

    視覚的な明瞭さと読みやすさ

    画像

    Claudeはより複雑な作業をこなせるようになるにつれ、作成する仕様書や計画書もどんどん長くなってきています。実際には、私自身は100行を超えるMarkdownファイルを読むことはほとんどなく、ましてや組織内の他の誰にも読んでもらうことはまず不可能です。

    しかし、HTMLドキュメントははるかに読みやすく、クロードはタブ、イラスト、リンクなどを使って視覚的に構造を整理し、ナビゲーションに最適な状態にすることができます。さらに、モバイル対応にすることもできるので、デバイスの画面サイズに応じて表示方法を変えることも可能です。

    共有のしやすさ

    Markdownファイルは、ほとんどのブラウザがネイティブで適切にレンダリングできないため、共有するのがかなり難しい。多くの場合、メールやメッセージに添付ファイルとして追加する必要がある。

    HTMLファイルであれば、ファイルをアップロードするだけで(例えばS3にアップロードするなど)、簡単にリンクを共有できます。同僚は好きな場所でファイルを開き、簡単に参照できます。

    仕様書、レポート、またはプレスリリースを実際に読んでもらえる可能性は、HTML形式であればはるかに高くなります。

    双方向のやり取り

    画像

    HTMLを使えば、ドキュメントと対話することができます。例えば、デザインを調整するためのスライダーやノブを追加したり、アルゴリズムのさまざまなオプションを微調整して結果を確認したりできます。また、これらの変更をプロンプトにコピーしてClaude Codeに貼り付けることも可能です。 双方向のやり取りの例については、私の遊び場に関する投稿をご覧ください。

    https://x.com/trq212/status/2017024445244924382

    データ取り込み

    例えばClaudeAIやClaude Designではなく、Claude Codeを使ってHTMLファイルを作成する理由は?最大の理由の一つは、Claude Codeが取り込める豊富なコンテキストです。 例えば、この記事を書く際、私はクロード・コードに私のコードフォルダを読み込み、私が生成したすべてのHTMLファイルを探し出し、それらをグループ化して分類し、各タイプを表すすべての図を含むHTMLファイルを作成するよう依頼しました。この記事に掲載されている図は、まさにその結果です。

    ファイルシステムに加えて、Claude Codeは、MCP(Slack、Linearなど)、Webブラウザ(ChromeでClaudeを使用する場合)、gitの履歴などを使用して、追加のコンテキストを見つけることができます。

    楽しい

    Claudeを使ってHTMLドキュメントを作成するのは、単純に楽しいし、作成作業への関与度や情熱も高まる。それだけで十分だ。

    始め方

    この記事を読んだ人が、これを/htmlスキルなどにしてしまうのではないかと少し心配しています。確かにそういう側面もあるかもしれませんが、Claudeにこれをさせるのに大した手間はかからないということを強調しておきたいと思います。「HTMLファイルを作成」​​または「HTML成果物を作成」と指示するだけで良いのです。

    重要なのは、そのアーティファクトに何をさせたいのか、そしてどのように使うのかを把握することです。時間をかけてスキルを作成することもできますが、今のところは、さまざまな状況でどのように使うかを習得するために、最初からプロンプトを表示させることをお勧めします。

    ユースケース

    しかし、概要は以下のとおりです。これをより具体的に示すために、さまざまな用途に対応した複数のHTMLファイルを作成しました。それらはすべてこちらからご覧いただけます。

    https://thariqs.github.io/html-effectiveness/

    仕様、計画、探査

    HTMLは、Claudeが問題に取り組むための豊かなキャンバスです。問題に取り掛かるとき、単純なマークダウンプランではなく、HTMLファイルのネットワークを構築することを想定しています。たとえば、Claude Codeにブレインストーミングを依頼し、さまざまな選択肢を検討してもらうことから始めるかもしれません。次に、さらに発展させて、モックアップやコードスニペットを作成するように依頼します。最後に、納得のいくものができたら、実装プランを作成するように依頼します。プランに満足したら、新しいセッションを作成し、これらのファイルをすべて渡して実装させます。

    検証を行う際には、検証エージェントにファイルを読み込ませるようにします。そうすることで、必要な情報についてより広範なコンテキストを把握できるようになります。

    画像

    プロンプトの例:

    • オンボーディング画面のデザインをどうするか迷っています。レイアウト、トーン、情報密度を変えて、6種類の異なるデザイン案を作成し、それらを1つのHTMLファイルにグリッド形式で並べて比較できるようにしてください。それぞれのデザイン案には、どのようなトレードオフがあるのか​​を明記してください。

    • HTMLファイルで詳細な実装計画を作成してください。モックアップを作成し、データフローを示し、私が確認したい重要なコードスニペットを追加してください。読みやすく、理解しやすいものにしてください。

    ユースケース:

    • コードで何かを実装する他の方法を探る

    • 複数のビジュアルデザインを探求する

    コードレビューと理解

    Markdownファイルではコードが読みにくい場合があります。しかし、HTMLを使えば、差分、注釈、フローチャート、モジュールなどを表示できます。これを利用して、エージェントが書いたコードを理解したり、コードレビューを受けたり、コードレビュー担当者にプルリクエストの内容を説明したりできます。私は、これがGitHubのデフォルトの差分表示よりも効果的だと感じており、今ではすべてのプルリクエストにHTMLコードの説明文を添付しています。

    画像

    プロンプトの例:

    このプルリクエストをレビューするために、内容を説明するHTMLアーティファクトを作成してください。ストリーミング/バックプレッシャーのロジックにはあまり詳しくないので、その点に重点を置いてください。実際の差分をインラインのマージン注釈付きで表示し、検出結果を重要度に応じて色分けするなど、概念を分かりやすく伝えるために必要な要素をすべて含めてください。

    ユースケース:

    • PRを作成する

    • PRのレビュー

    • コードにおけるトピックの理解

    デザインとプロトタイプ

    Claude DesignはHTMLをベースにしています。なぜなら、最終的なインターフェースがHTMLでなくても、HTMLはデザインにおいて非常に表現力に富んでいるからです。ClaudeはHTMLでデザインの概要を作成し、その後、React、Swiftなど、お客様が選択した言語で実装することができます。

    アニメーションやアクションなど、インタラクションのプロトタイプを作成することもできます。クロードにスライダーやノブなどを作成してもらい、思い通りの調整をしてみてはいかがでしょうか。

    画像

    プロンプトの例:

    新しいチェックアウトボタンのプロトタイプを作成したいのですが、クリックするとアニメーションが再生され、その後すぐに紫色に変わるようにしたいです。このアニメーションのさまざまなオプションを試せるように、複数のスライダーとオプションを含むHTMLファイルを作成してください。うまく機能したパラメータをコピーするためのコピーボタンも用意してください。

    以下の用途にご利用ください:

    • デザインシステム成果物の作成

    • コンポーネントの調整

    • コンポーネントライブラリの可視化

    • 楽しいアニメーションのプロトタイプ作成

    レポート、研究、学習

    Claude Codeは、複数のデータソースから情報を統合し、読みやすいレポートに変換する能力に非常に優れています。ClaudeにSlack、コードベース、Git履歴、インターネットなどを検索させ、自分自身、経営陣、チームなどに向けた非常に読みやすいレポートを生成させることができます。

    これを長いHTMLドキュメント、インタラクティブな解説動画、あるいはスライドショーやプレゼンテーション資料といった形式でまとめることができます。視覚化を助けるために、クロードにSVGを使って図を作成するよう依頼してください。 例えば、プロンプトキャッシュに関する私の記事では、Gitの履歴を読んだ後、プロンプトキャッシュへの変更点すべてを網羅した詳細な調査ファイルをHTML形式で作成してもらうよう、クロードに依頼しました。

    画像

    例: レートリミッターの仕組みがよく分かりません。関連するコードを読み、トークンバケットの流れを示す図、注釈付きの重要なコードスニペット3~4個、そして最後に注意点をまとめたHTML解説ページを作成してください。一度読んだだけで理解できるように最適化してください。

    以下の用途にご利用ください:

    • 機能の仕組みを要約する

    • 概念を説明してください

    • 上司への週次進捗報告

    • 上司へのインシデント報告

    • SVGイラスト、フローチャート、技術図など

    カスタム編集インターフェース

    テキストボックスだけで自分の要望を説明するのは難しい場合があります。このような場合、クロードに、私が現在取り組んでいる作業専用の使い捨てエディタを作成してもらうよう依頼します。製品でも再利用可能なツールでもなく、この特定のデータのために特別に作成された単一のHTMLファイルです。

    コツは必ずエクスポートで締めくくることです。「JSONとしてコピー」または「プロンプトとしてコピー」ボタンを使って、UIで行った操作をClaude Codeに貼り付けられる形式に戻すのです。

    画像

    プロンプトの例:

    • これらの30件のLinearチケットの優先順位を再設定する必要があります。各チケットを「今すぐ」「次」「後」「キャンセル」の列にドラッグ可能なカードとして配置したHTMLファイルを作成してください。事前に、あなたの推測に基づいて並べ替えてください。「Markdownとしてコピー」ボタンを追加し、各項目ごとに1行の理由説明を添えて最終的な順序をエクスポートできるようにしてください。

    • これが機能フラグの設定です。これに対応するフォームベースのエディタを作成し、フラグを領域ごとにグループ化し、フラグ間の依存関係を表示し、前提条件が無効になっているフラグを有効にした場合は警告を表示するようにしてください。変更されたキーのみを表示する「差分をコピー」ボタンも追加してください。

    • システムプロンプトを調整しています。左右に並んだエディタを作成します。左側に編集可能なプロンプトがあり、変数スロットがハイライト表示されます。右側には、入力済みのテンプレートをリアルタイムで再レンダリングする3つのサンプル入力フィールドがあります。文字数/トークン数カウンターとコピーボタンを追加します。

    以下の用途にご利用ください:

    • チケット、テストケース、フィードバックなど、あらゆるものを並べ替えたり、優先順位を付けたり、分類したりする。

    • 構造化設定(機能フラグ、環境変数、制約付きJSON/YAML)の編集

    • チューニングのプロンプト、テンプレート、またはコピーをライブプレビューで表示

    • データセットのキュレーション、行の承認/拒否、例へのタグ付け、選択内容のエクスポート

    • 文書、トランスクリプト、または差分に注釈を付け、注釈をエクスポートする

    • テキストで表現するのが難しい値を選択する:色、イージングカーブ、切り抜き領域、cronスケジュール、正規表現。

    よくある質問

    私がHTMLに移行した経緯を多くの人に話してきたところ、いくつか同じ質問を繰り返し受けました。

    トークン効率は劣るのではないでしょうか? マークダウンはトークン数が少ないことが多いですが、HTMLの表現力の高さと、私がHTMLを読む可能性がはるかに高いことを考えると、全体的に見てより良い出力が得られると思います。Opus 4.7の1MMコンテキストウィンドウでは、トークン使用量の増加はコンテキストウィンドウではほとんど気になりません。

    今はどんな時にマークダウンを使っていますか? 正直なところ、私はほとんどすべての場面でマークダウンを使うのをやめてしまいましたが、おそらく私はHTMLを極力活用するタイプでしょう。

    HTMLファイルを表示するにはどうすればいいですか? 私は通常、ローカルのブラウザで開きます(Claudeに開いてもらうこともできます)。共有可能なリンクが必要な場合は、S3にアップロードします。

    これってマークダウンより生成に時間がかかるんじゃないの? 確かに時間がかかりますね!HTMLはマークダウンの2~4倍かかることもありますが、その分得られる結果は素晴らしいと思います。

    バージョン管理はどうでしょうか? これは正直言ってHTMLの最大の欠点の1つです。HTMLの差分はマークダウンに比べて情報量が多く、レビューが困難です。

    Claudeで自分の好みに合ったデザインを作成したり、見栄えの悪いデザインにならないようにするにはどうすればいいですか? フロントエンドデザインプラグインは、Claudeが質の高いHTMLファイルを作成するのに役立ちます。しかし、自社のスタイルに合わせるには、Claudeにコードベースを指定することで、単一のデザインシステムHTMLファイルを作成できます。その後、そのデザインシステムファイルを他のHTMLファイルの参照として使用できます。

    最新情報を入手しよう

    以上のことから言えるのは、私がHTMLを使う本当の理由は、Claudeとの連携をより深く理解できるようになったからだということです。設計図をじっくり読まなくなったことで、Claudeに選択を任せるしかなくなるのではないかと不安になり始めていました。

    しかし、嬉しいことに、HTMLを使うことで以前よりもずっと状況を把握できていると感じています。皆さんもそう感じていただければ幸いです。

    もし「便利そう!」「使ってみたい!」と思っていただけたら、
    以下の応援アクションをしていただけると嬉しいです。

    おすすめ記事↓


    • STEP 1: この記事への「スキ♡」

    • STEP 2: noteで「クドクラ KudouCraft」をフォロー

    • STEP 3: X(Twitter)での拡散

    メンバーシップ記事も更新していくので見てくれたら嬉しいです

    皆さんの感想や「こんな使い方してるよ!」という報告、
    お待ちしています!
    最後まで読んで頂きありがとうございます
    それではまた次回の記事でお会いしましょう。

     
     
    KudouCraft AI駆動開発で未経験から上級者まで生成AI活用! 質が良い完成品のある自動化をコンセプトに 最新AIエージェントの情報をお届け これであなたもAIを使いなす側に。

    あなたへのおすすめ