Claude Code に「Markdown ではなく HTML で成果物を出力させる」という運用が、2026 年 5 月初旬から英語圏・日本語圏でじわじわ広がっている。私もこの流れを追って 2 本の HTML ダッシュボードを試作した。結果として、「HTML が便利だった」以上に大きな発見があった。19 件のガバナンス事故ログを縦タイムライン HTML に並べた瞬間、それが「読む道具」から「監査ツール」に変わり、Markdown のままだと見落とし続けていた組織側の負債が初めて可視化されたのだ。本稿は試作 2 本（記事ステータスダッシュボードとガバナンス事故タイムライン）を通じて、HTML 成果物が「読む道具」から「問題を可視化する道具」へ拡張していく筋道を、発見の順序のまま追体験する技術記事である。
1. なぜ HTML を試したのか
きっかけは Anthropic Claude Code チームのエンジニア Thariq Shihipar（@trq212）が 2026-05-08 に投稿した「HTML is the new markdown」というツイートだった。Markdown ファイルを書くのをやめて、Claude Code に HTML を生成させるようにしたという主張で、英語圏で広く話題になった。Simon Willison も自身のブログで「GPT-4 時代から Markdown をデフォルトにしていたが再考させられた」と言及しており（出典: simonwillison.net/2026/May/8/unreasonable-effectiveness-of-html/）、Claude Code を使う開発者層への波及が大きい。
私の関心は「流行を追う」ことよりも、自分の運用にどう取り込むかだった。最初に researcher エージェントに公式情報源（anthropic.com / docs.anthropic.com / claude.com）への調査を依頼したところ、Anthropic 公式が HTML 成果物の生成を紹介・推奨しているのは次の 3 文脈に集中していることがわかった。
- claude.ai Artifacts: 会話から分離した専用ウィンドウで HTML を生成・公開する機能
- Claude Cowork Live Artifacts: MCP 経由でリアルタイムデータを取り込んだ永続インタラクティブ HTML
-
Data Analyst Plugin の
/build-dashboard: Chart.js を使った自己完結型 HTML ダッシュボード
いずれも「Markdown では表現できないインタラクティブ性・視覚的リッチさ」を理由に HTML を選んでいる。Markdown vs HTML を直接比較した公式ドキュメントは見つからなかったが、Thariq 自身も二次ソース経由で「人間が読む成果物に限定する」と述べているとされる（X 上の一次投稿は認証制限のため直接確認できておらず、複数の二次ソースから整合する形で引用している）。エージェントループ内のファイル（CLAUDE.md・handoff など）は Markdown のままが妥当、という線引きだ。
この線引きは重要だった。私のリポジトリには handoff（セッション引き継ぎ）・netacho（ネタ帳）・playbook が大量にある。そのすべてを HTML 化する理由はないし、エージェントが読み取って処理する SSoT を HTML に変えるとパース処理が壊れる。「どこに使うか」を間違えると HTML 化はただの肥大化になる——この前提から始まった。
そこで最初に「HTML 成果物を出すスキルを 1 本作って、週次レビューやリサーチレポート等の特定用途に固定的に適用する」案を考えたが、すぐに方針を「固定スキル化はしない、都度判断する」に切り替えた。根拠は 2 点ある。ひとつは、Thariq の companion サイト（thariqs.github.io/html-effectiveness）に公開された 9 カテゴリ 20 本のサンプルを眺めると、タイムライン・ダッシュボード・モックアップ・PR レビュー・スライドデッキなど用途ごとに HTML の構造がまったく違うこと。もうひとつは、机上のガイドラインを先に書くより実物を 1〜2 本作ったほうが判断軸が早く見えること。先に試作 2 本を作ってから汎用化を判断する、というスタンスに切り替えた。この判断が後から効いてくる——先にスキルを 1 本作ってしまっていたら、試作 2 本目で起きた発見にたどり着く前に「便利だね」で終わっていた可能性が高い。
2. 試作 1 本目: 記事ステータスを「見るダッシュボード」に変える
最初の試作は /blog-status スキルの HTML 化だ。私は記事を 100 本以上書いており、はてな・Zenn・Qiita の 3 プラットフォームに展開している。SSoT は content/writing/articles/<slug>.md の frontmatter で、platforms.hatena.status / platforms.zenn.status / platforms.qiita.status が各プラットフォームの公開状態を持つ。これまでは content/article-status.md という集計 Markdown を眺めて状態を把握していた。
Claude Code に依頼して、Tailwind CDN と Chart.js を使った自己完結型 HTML を tmp/preview/blog-status.html に生成させた。データは frontmatter を集計したオブジェクトを <script type="text/plain"> でインライン埋め込みする方式で、外部ファイルへの依存はない。Anthropic 公式 Cookbook が推奨するのは <script type="application/json"> 方式だが、text/plain を選んだのはブラウザが MIME 評価を一切しないため、JavaScript で textContent を読んで JSON.parse する単純経路に固定できるからだ（コメント・改行などの混入リスクも回避できる）。生成ファイルのサイズは実測で 74,143 バイト（約 72KB） ——ブラウザでダブルクリックすれば即座に開ける軽量さに収まった。
試作を開いた瞬間のユーザー（私自身）の反応は「すごい。めちゃくちゃみやすい」だった。Markdown の集計テーブルでは縦に伸びるだけだった情報が、KPI カード（総記事数・公開済み・下書き）と公開状態のドーナッツチャート、プラットフォーム別のソート可能テーブルに展開され、「どこに偏りがあるか」が一目で見える。
ただし、ここで終わっていれば「読みやすくなった」止まりだった。発見はその次の一言から始まる。「この画面から次に投稿する、クロスポストするが指示できたら楽だね」——HTML を見ている最中に、ユーザーが「読む」から「次のアクションを起こす」へ自然に頭を切り替えた。
そこで実装したのが、各記事行にアクションボタンを置き、押すと自然言語の指示文をクリップボードにコピーする navigator.clipboard.writeText() 仕掛けだ。例えば「クロスポストする」ボタンを押すと、「<slug> を Zenn と Qiita に公開して」という指示がコピーされる。ユーザーはそれを Claude Code のターミナルに Cmd+V で貼り付けるだけで実行できる。
// 概念的な実装イメージ
button.addEventListener('click', () => {
const cmd = `${slug} を Zenn と Qiita に公開して`;
navigator.clipboard.writeText(cmd);
});
この瞬間、HTML 成果物の役割が変わった。「ビューワー（読む道具）」から「コントローラー（次のアクションのトリガー）」へ拡張された。記事ステータスを HTML で表示するだけなら BI ツールでも代替できる。しかし「画面 → 自然言語 → Claude Code への貼り付け」という導線が加わると、Claude Code 環境の中でしか成立しない使い方になる。これは Thariq の 20 パターンには出てこない、自分たちの運用に固有のフィットだった。
3. 試作 2 本目: ガバナンス事故を時系列で並べたら、68% という数字が出た
2 本目の試作は、私のリポジトリで「ガバナンス事故記録」と呼んでいるディレクトリの可視化だった。logs/governance-incidents/ には、AI エージェントが組織ルールを破った事例を 1 件 1 ファイルで記録している。事故が起きるたびに「何が起きたか・原因（独断判断 / トリガー見落とし / ルール不備）・再発防止策・ルール更新箇所」を構造化して残す運用だ。
実測で 19 件が蓄積されていた。
これを縦タイムライン形式の HTML に変換する。Claude Code に依頼すると tmp/preview/governance-incidents.html が生成された。ファイルサイズは実測で 99,219 バイト（約 97KB）。<title>Governance Incidents Timeline</title> のシンプルな単一ページで、19 件が日付降順で縦に並ぶ。
開いた瞬間、想定していなかった反応が出た。「これで見ると、インシデント溜めてるだけで、フィードバック適用していないのがかなりあるね」——HTML 化したことで初めて、構造的問題が見えた。
事故記録ファイルには rule_updates フィールドがあり、「この事故を受けてどのルールをどう更新すべきか」が書かれている。Markdown を 1 件ずつ開いて読んでいた頃は、個々の事故の改善策を見て「対処済みだな」と感じていた。ところが時系列で 19 件を並べると、「rule_updates が書かれているのに実際は CLAUDE.md にも Playbook にも反映されていない」という事故が散見されたのだ。
researcher エージェントに依頼して、19 件の rule_updates が実際に該当ファイルへ反映されているかを点検してもらった。結果は次のとおり（出典: logs/audit/2026-05-19_incident-rule-application.md §1）。
| 区分 | 件数 | 比率 |
|---|---|---|
| 完全反映 | 13 件 | 68% |
| 部分反映 | 4 件 | 21% |
| 未反映 | 2 件 | 11% |
※ この集計は audit 実施時点（後述の CLAUDE.md trigger 追加対応前）のスナップショット。本記事の発見をきっかけに CLAUDE.md に 1 行追記した結果、未反映が 1 件解消し、現時点の実態は 完全反映 14 件 / 74% / 部分反映 4 件 / 未反映 1 件 に更新済み（同じ audit ファイルの §2 個別判定を直接カウントすると 14/4/1 になる。§1 サマリーの 13/4/2 は内訳の数え方の違いによる差で、本稿では「個別判定 + 追記対応後」の数値を最終とする）。
特に再発リスクが高かったのが、3 回連続で発生していた同型事故だ。CWD 依存・blogsync 系のファイル破壊事故が 2026-05-04 → 2026-05-14 → 2026-05-15 の 3 回起きており、5/04 時点で「CLAUDE.md の trigger リストに『blogsync 直接実行』禁止を追記する」という対策は反映されていた。ところが「scripts/article/hatena-publish.sh 経由でも blogsync push を呼ぶため同等のリスクがある」という追記が漏れていた。スクリプト側のガード実装は完了していたが、エージェントが trigger リストを見たときに「scripts 経由なら安全」と誤読する余地が残っていたのだ。
ここで実施したのは、CLAUDE.md の trigger リストへの 1 行追記だった。「scripts/article/hatena-publish.sh 等の blogsync を呼ぶラッパー実行」も事前承認の対象とする、と明記した（audit と同一コミット e279bda に含めた）。地味な変更だが、これがなければ 4 回目の同型事故が確実に起きていた。上の表の「未反映 1 件減」はこの追記によるものだ。
4. HTML 成果物が「読む道具」から「監査ツール」に変わる 3 条件
試作 2 本目で起きたことを抽象化すると、HTML がどんな条件下で「読む道具」から「問題を可視化する道具」に変わるかが見えてくる。今回のケースで条件として効いたのは次の 3 点だ。
- 時系列で並ぶこと: 19 件のインシデント Markdown を 1 件ずつ読んでも「滞留している」感覚は出ない。日付軸で並べた瞬間、「最近 3 件が同型事故」「rule_updates が書かれているのに反映が滞っている」という分布が一気に視野に入る
- 比率が出ること: 68%・21%・11% という反映率を、19 件を 1 件ずつ追って暗算するのは無理だ。HTML 化に合わせて反映状況の集計を併走させたことで、初めて「9 割未満で滞留している」と判断できる定量基準ができた
- 個別事例とサマリーが同一画面にあること: 「68% という数字が出た」だけでは行動につながらない。同じ画面で個別事故のカードを開き、最も再発リスクが高い 2026-05-15 の事故を特定できたことが、CLAUDE.md への追記アクションを呼んだ
これは Thariq が示した「人間が読む成果物に限定」という線引きの内側で起きた効果だ。エージェントが読む handoff や CLAUDE.md は引き続き Markdown が SSoT で、HTML 化していない。HTML 化したのは「人間が定期的に俯瞰して判断するべきデータ」——記事ステータスとガバナンス事故記録——だけだ。
裏返すと、HTML 化が向かない成果物もはっきりした。ops/handoff/ のセッション引き継ぎは Claude Code のサブエージェントが読むため Markdown が必要だし、content/writing/netacho/ のネタ帳は writer エージェントが grep する素材なので HTML 化すると検索性が落ちる。「人間が判断する場面で時系列・比率・個別事例を同時に見たいデータ」がある場合のみ HTML 化する、というのが現時点での判断基準だ。
5. Claude Code で HTML 成果物を使うべき場面: 試作 2 本が出した答え
ここまでの流れを振り返ると、最初に方針を「固定スキル化」ではなく「都度判断」に切り替えたのが結果的に正解だった。もし最初に「全成果物を HTML 化するスキル」を 1 本作っていたら、handoff やネタ帳まで HTML 化してしまってエージェントが壊れた可能性が高い。逆に「実物を作らずガイドラインを先に書く」を選んでいたら、tmp/preview/governance-incidents.html を開いた瞬間の「68% しか反映できていない」という発見にはたどり着かなかった。
試作 2 本を通して得たものを整理すると次のとおり。
- 試作 1 本目（記事ステータス）で、HTML 成果物の役割を「読む道具」から「次のアクションを起こすコントローラー」へ拡張する筋を発見した（クリップボードコピー仕掛け）
- 試作 2 本目（ガバナンス事故タイムライン）で、HTML 化が「組織の負債を可視化する監査ツール」として機能することを発見した（68% という数字）
- 副産物として、3 回連続で起きていた同型事故の根本原因（trigger リストへの追記漏れ）が特定でき、
CLAUDE.mdに 1 行追記して再発リスクを下げた
ガイドラインを先に書こうとしていたら、これらは全部「机上で並ぶ可能性」のままだった。実物 2 本がガイドラインより先に答えを返してきた、というのが本稿で残せる最も実感のある教訓だ。
/blog-status の HTML 化は、その後 bash scripts/article/blog-status.sh html の定常コマンドとして組織に編み込んだ。一方でガバナンス事故タイムラインのほうは、定期生成ではなく「半月に一度くらい点検したくなったら手動で生成する」運用のままにしている。HTML 化は便利だが、定常化するかどうかは「効果が実証されてから」決めればよく、最初から固定スキルにする必要はない——という最初の方針判断は、試作後も変わらず正しいと思っている。
「HTML is the new markdown」というフレーズは強い断定で覚えやすいが、私の運用では「Markdown の上に HTML を 1 層被せる場面を、人間が判断するときに限定する」が現時点の落とし所だ。皆さんのリポジトリにも、Markdown のままでは見えない構造的問題が眠っているかもしれない。試作 1 本作ってみると、思っていない場所から答えが返ってくることがある。
ガバナンス事故記録という仕組みを持っていない読者にとっての最初の一手は、もっと地味な場所にある。手元に「溜まったけど活用していない縦長 Markdown」——例えばリリースノート、週次レポートのバックログ、エージェント設定の変更履歴、ふりかえりログなど——があるなら、まずそれを Claude Code に頼んで「日付降順の縦タイムライン HTML を 1 本」作ってもらうのがいちばん最小の入口になる。今回の私のケースも、最初から「監査するぞ」と思って HTML 化したわけではなく、「ガバナンス事故記録を見やすく並べただけ」だった。並べた結果として「68% しか反映されていない」が見えた。眠っている Markdown を縦に並べることが、可視化の第一歩だ。
この記事は はてなブログ からのクロスポストです。