アプリケーションサービス部ディベロップメントサービス4課の越後です。
今回は最近話題に上がっている「ClaudeにHTMLで出力してもらう」を実際に試してみた話を書きます。Markdownとの使い分けに迷っている方の参考になれば！
ClaudeにHTMLで出してもらったら、MarkdownとHTMLの使い分けが一気に見えてきた
2026年5月、Xで話題になった「The Unreasonable Effectiveness of HTML」という投稿をきっかけに、ClaudeにHTML形式で出力させることを試してみました。試してみると意外といいものだと感じつつ、棲み分けが必要だなという印象です。
やってみた中でHTMLで良かったのは以下の3点です。
- AIが実装したPRの内容を自分で把握しやすくなった：diff・インライン注釈・severity色分けをまとめた1枚のHTMLでGitHubのdiffビューより「何をなぜ変えたか」がつかみやすい
- 複数案の比較・選択判断がしやすくなった：タブや比較表で「どれにするか」の判断コストが下がる
- HTMLをS3で共有するワークフローができた：
/share-html-s3スキルを自作し、URLをSlackに貼るだけで共有が完結する
何を試したか
① AIが実装したPRの内容把握
「このPRの変更をHTMLで解説して」と指示して /tmp/ に出力、ブラウザで確認する使い方。diff・インライン注釈・severity色分け・フローチャートを1枚にまとめることで、GitHubのdiffより「何をなぜ変えたか」がつかみやすくなります。PRが複雑なときのために pr-html-explainer スキルを自作しました。
② 実装計画・ブレインストーミング
「HTMLで選択肢一覧を作って」と指示し、タブや比較表で複数案を並べる使い方。「どれにするか」の判断コストが下がり、決定後はMarkdownの計画書に起こします。また、
③ レポート・ドキュメント共有
レポートをHTML形式で出力し、S3にアップしてURLで共有する使い方。/share-html-s3 スキルを自作し、アップロードから署名付きURL発行まで一発完結。URLをSlackに貼るだけで済みます。
判断軸: 誰のための情報か
これらの体験を通じて、使い分けの判断軸がシンプルに言語化できました。「その情報は人間が読むのか、AIが読むのか」です。
| 情報の受け手 | フォーマット | 理由 |
|---|---|---|
| 人間が今すぐ読む | HTML | 認知コストが大幅に下がる。色・構造・図で「何を見ればいいか」が一目でわかる |
| AIや将来の自分が参照する | Markdown | HTMLはAIの認知コストが高い。AIはMarkdownのほうが正確に解析できる |
HTMLは人間の認知コストを下げる代わりに、AIの認知コストを上げます。この非対称性を意識すると、用途ごとに自然に使い分けが決まります。
やってみてわかったこと
HTMLの強み
- テーブル・色・SVG・タブで構造化できる。100行超の出力でも迷子にならない
- 共有はS3にアップしてURLを送るだけ。受け取った側がすぐブラウザで開ける
Markdownの強み（HTMLが苦手な場面）
- Git管理するドキュメント（README・CHANGELOG等）: HTMLのdiffはノイジーで読めたものじゃない
- Slack・Discordへの貼り付け: HTMLをそのまま貼るとタグがテキストでどっさり出る
- AIが読むファイル（CLAUDE.md・コンテキストファイル等）: MarkdownのほうがAIが正確に解析できる
- 人間が後から直接編集するもの: HTMLは「ちょっと直したい」だけでも再プロンプトが必要になる
気をつけたほうがいいこと
トークンコストは増えるが、認知コスト削減でペイできる
MarkdownよりHTMLのほうが2〜5倍程度トークンを多く消費します（Thariqの投稿で言及されていた数字をもとにした概算）。ただ人間向けの情報であれば認知コストの削減効果が上回るので、使い分けを「人間向けのもの」に絞れば問題になることはほぼありません。
Gitに入れるものではない
HTMLのdiffはノイジーすぎます。/tmp/ に出力して使い捨てにするか、S3にアップしてURLを渡すかが基本です。
使い分けの判断軸まとめ
| HTMLにする | Markdownにする |
|---|---|
| 調査結果・レポート | READMEやCHANGELOG（Gitで管理するもの） |
| PRのコード解説 | AIが読むファイル（CLAUDE.md・コンテキスト） |
| 複数案の比較・選択判断 | TODO・実装計画（後でAIに渡すもの） |
| 上司・クライアント向け共有 | Slack / Discordへの貼り付け |
| 今すぐ人間が判断する情報 | 保存して後で参照する情報 |
保管パターンの目安：
- 自分だけ確認:
/tmp/に出力してopen ファイル名でブラウザで開く - 人と共有: S3にアップしてURLをPRやSlackに貼る
- 次のセッションのコンテキスト用: Markdownで保存（AIに渡すのでHTML不可）
まとめ
人間が今すぐ読む情報はHTML、AIや将来の自分が参照する情報はMarkdown。
HTMLは人間の認知コストを大幅に下げますが、AIの認知コストを上げます。この非対称性を意識すると、使い分けが迷わず決まります。まず試すなら次のPRのコード解説をHTMLで出してみるのがわかりやすいです。GitHubのdiffと見比べると、HTMLのほうが向いている理由が一発で体感できます。
