Claude Codeの出力をMarkdownからHTMLに逃がす
目次
Claude Codeに長いMarkdownを書かせると、比較表、差分、設計案のような情報が縦に流れすぎる。
3案の比較を順番に読んで頭の中で突き合わせる作業は地味にきつい。
Thariqの付属ページ The unreasonable effectiveness of HTML が、この問題にかなり実用寄りの回答を出していた。
Claude Codeから自己完結した .html を出させ、CSS・SVG・少しのJavaScriptまで1ファイルに閉じて、ブラウザで見る。
AIにWebサイトを作らせる話ではなく、レビュー用の中間成果物をMarkdownからHTMLに逃がす話だ。
付属ページには20個のHTML例がある。
全部見て、おもしろいと思ったところを掘る。
比較はMarkdownが一番辛い場面だった
Claude Codeに「3案出して」と頼むと、案A、案B、案Cが縦に流れる。
案Aを読み終えてから案Bに移り、差分を頭に保持したまま案Cを読む。
テキストの量が多いほどしんどい。
HTMLなら横に並べられる。
カードごとに色を変えて、採用候補に印を付けて、リスクだけ別枠に出せる。
文章量が同じでも比較対象が同時に視界に入る。
WUPHFのLLM wiki では、エージェント記憶の正本をMarkdownとGitに置く設計を書いた。
あれは長期保存としてMarkdownが強い話だった。
今回のHTMLは逆で、今この場で見て判断するための表示面として強い。
保存と表示を同じ形式にする必要はない。
使い捨て編集UIが一番おもしろい
付属ページで一番引っかかったのはCustom Editing Interfacesの例だ。
チケットの優先順位ボード、feature flag editor、prompt tunerが並んでいる。
「30件のチケットをNow / Next / Later / Cutに分ける」作業をMarkdownのリスト編集でやると事故る。
ドラッグして並べ替えて、最後にMarkdownやJSONへエクスポートするHTMLを作れば、人間はUIで判断できるし、エージェントには構造化された結果を返せる。
プロンプト調整もそうだ。
テンプレートの変数部分をハイライトし、横にサンプル入力の出力を並べる。
チャット欄で「ここを変えて」「もう一回」を繰り返すより、専用UIのほうが早い。
ここでClaude Codeの出力がドキュメントから道具に変わる。
説明文を読ませるのではなく、操作できる状態を渡す。
CLIからAIへ、人間がソフトウェアと話す入口が変わる ではAIが入力レイヤーになる話を書いたが、HTML出力はその裏面で、AIが人間に返すときもテキストだけでなくブラウザを使う。
使い捨て前提だから凝る必要がない。
アクセシビリティは雑でいいし、レスポンシブ対応も不要。
自分が今使えればいい、というラインで出す。
コードレビューの差分注釈
コードレビューもHTMLに向いている。
MarkdownのPR説明は動機・変更点・テスト結果を書くには十分だが、差分そのものに注釈を付けたり、重要行をハイライトしたり、危険度で色分けしたりするには弱い。
Thariqの例にはannotated pull request、PR writeup、module mapがある。
差分の横に注釈を置く。
ファイルごとの意図をカードにする。
モジュールの依存を箱と矢印で描く。
Claude Codeの返答欄で読むより、ブラウザで1枚の資料として見たほうが速い。
Claude CodeのマルチエージェントPRレビュー でも、問題は「レビューできるか」ではなかった。
複数の指摘をどう並べ、どこから見るかの判断が残る。
HTMLなら重大度、対象ファイル、再現手順、該当diffを同じ画面に載せられる。
触れる説明はテキストに戻せない
アニメーションのeasingは文章で説明されてもわからない。
クリックフローも、画面遷移を箇条書きで読んだだけでは触感がない。
Thariqの例ではアニメーションsandbox、クリック可能なフロー、矢印キーで進むスライド、折りたたみ付きの機能解説が出てくる。
単体HTMLでこれが動く。
ビルドも依存関係もない。
PRに添付する、Slackで共有する、ローカルで開く、どれも軽い。
Markdownより重いフォーマットではあるが、ミニアプリを立てるほどではない。
雑にHTMLを開くリスク
他人が作ったHTMLを雑に開かないほうがいい。
<script> を含められるので、ローカルファイルとして開く場合でもリンク先、外部リソース、フォーム送信、クリップボード操作は確認する。
Claude Codeに作らせるなら外部通信なし、依存なし、保存は手動エクスポートのみ、くらいは指定したい。
Git上でも面倒がある。
長いCSSとSVGとJavaScriptが1ファイルに詰まると差分レビューのノイズになる。
レビュー用の一時ファイルとして生成し、読み終えたら捨てるのが現実的だ。
成果物としてコミットする必要はない。
記事を書く途中でMarkdownが辛い場面だけHTMLに出す
ここまで掘ってみて、自分のブログの実験フローとほぼ同じ構造だと気づいた。
このブログでは、おもしろそうなネタを見つけたらまず深掘りした記事を書く。
そこから試したいことを選んで実験記事を作り、進捗を追記していく。
中間成果物を文章で可視化し、途中の判断を記録し、次にやることを決める場所として使っている。
Thariqの提案するHTMLは使い捨てだが、記事は最終的に公開する。
でも書いている途中での役割は同じだ。
違いは、Markdownの記事では横並び比較やドラッグ操作ができないこと。
記事の構成を考えるとか、実験ログを文章で残すにはMarkdownで回っている。
でも CLAUDE.mdを分離しても読まれない問題 と同じで、ファイルの中に情報があっても見え方が合わなければ使われない。
3案を横に並べて選ぶとか、30件をドラッグで並べ替えるとかはHTMLのほうが速い。
記事を書く途中でMarkdownだと辛いと感じた場面だけHTMLに逃がす、という使い分けが試したいところだ。
AIだけが読む出力にMarkdownもHTMLも要らない
ここまでの話は全部、最終的に人間が見る前提だった。
比較をHTMLに出すのも、記録をMarkdownで残すのも、人間の目に合わせた選択だ。
でもAIエージェントのワークフローには、人間が一切見ない中間出力がある。
Claude Codeにタスクを分解させて、ステップAの結果をステップBのプロンプトに渡すだけなら、その中間結果はHTMLどころかMarkdownにする必要もない。
JSONで十分だし、構造が単純ならプレーンテキストでいい。
次のステップが機械的にパースできれば形式は何でもいい。
厄介なのは、人間が途中で割り込むケースだ。
AIだけで回していた中間結果を「ちょっと確認させて」と言われた瞬間、JSONの配列では判断できない。
3案の比較データがJSONに入っていても、人間が横に並べて選ぶにはHTMLへの変換が要る。
逆に、最初は人間が確認していたHTML出力を、運用が安定してAIだけで回すようになったら、もうHTMLを生成する意味がない。
この記事の前半で「保存と表示を同じ形式にする必要はない」と書いた。
もう少し正確に言うと、読み手が人間かAIかでも形式の正解が変わる。
AIが消費する中間データ、人間が今見て判断する表示面、人間があとからGitで検索する記録。
同じ情報でもフェーズによって合う形式が違うし、AIに任せる範囲が広がると人間が目で見るフェーズ自体が減る。
HTMLの出番は、人間がまだ確認を手放せない段階に集中する。