ADR-003: インタラクティビティレイヤーとしてのHTMX
HyperGenがカスタムJavaScriptフレームワークやJSONベースのインタラクションモデルの代わりにHTMX属性をインタラクティビティに使用する理由。
ステータス: 承認済み 日付: 2026-03-28
コンテキスト
HyperGenのコアテーゼ（ADR-001参照）は、HTML自体がGenerative UIのプロトコルであるべきだということです。しかし静的HTMLだけでは不十分です — ユーザーにはインタラクティブなインターフェースが必要です: 送信するフォーム、更新するコンテンツ、クリックに応答するウィジェット。
問題は: エージェントに複雑なJavaScriptの生成を要求せず、クライアントに重いフレームワークのインストールを要求せずに、エージェント生成HTMLにインタラクティビティをどう追加するか？
Anthropicの知見
ClaudeのGenerative UIアプローチ（Saurabh Singhのアーキテクチャ分析で文書化）は重要な知見を実証しています: LLMは生のHTMLとCSSの生成に優れている。 ClaudeはインターフェースのJSON記述ではなく、完全なスタイル付きインターフェースを生成します。
これが機能する理由:
- LLMはどんなJSON UIスキーマよりもはるかに多くのHTML/CSSで学習されている。 WebのコーパスはHTML。生成品質と信頼性は本質的に高い。
- HTML + CSSは自己完結。 ビルドステップ不要、バンドラー不要、フレームワークランタイム不要。出力がそのままUIになる。
- CSSカスタムプロパティがデザインシステム統合を可能にする。
--color-surface、--color-accentなどを定義することで、ホストアプリケーションのデザインシステムが自動的に生成UIに流れ込む。
しかし、Anthropicのアプローチは生成されたUIをインタラクティブにするために重要なインフラストラクチャを必要とする:
- ストリーミングツールコール引数のための部分JSONパース
- インクリメンタルDOM差分のためのMorphdom
- カスタムスクリプト実行（
<script>タグをプログラム的に作成された要素で置換） - 双方向通信ブリッジ（
window.sendToAgent）
ここでHTMXが登場します。 HTMXはこれらすべてのインタラクティビティを — 宣言的に、HTML属性で、カスタムインフラストラクチャゼロで提供します。
決定
HyperGenはインタラクティビティレイヤーとしてHTMXを採用します。 エージェントはHTMX属性付きのHTMLを生成してインタラクティブUIを作成。ホストアプリケーションはHTMX（14KB、単一スクリプトタグ）を含めてこれらの属性を処理。
HyperGenが生成するもの
HyperGen準拠のエージェントは、3つのレイヤーで構成される完全なUIアーティファクトを生成します:
1. HTML構造（必須）
インタラクティビティのためのHTMX属性付きセマンティックHTML:
<form hx-post="/api/agent/submit" hx-target="#result" hx-swap="innerHTML">
<input type="text" name="query" placeholder="Ask a question..." />
<button type="submit">Send</button>
</form>
<div id="result"></div>これは単なるHTML。LLMはこれを段落を書くのと同じように自然に生成します。
2. CSSスタイリング（HTMLと並行して生成）
ホストのCSSカスタムプロパティを使用するインラインスタイルまたは<style>ブロック:
<style>
.hg-card {
background: var(--hg-surface);
color: var(--hg-text);
border: 1px solid var(--hg-border);
border-radius: var(--hg-radius);
padding: var(--hg-space-4);
}
.hg-btn {
background: var(--hg-accent);
color: var(--hg-accent-foreground);
}
</style>Anthropicのアプローチに従い: エージェントはCSS変数経由でホストのデザイントークンを参照するCSSを生成。ホストがこれらの変数を定義し、エージェントが使用する。スタイルの競合なし、CSS-in-JSランタイムなし。
3. JavaScript（最小限、必要な場合のみ）
ほとんどのインタラクティビティはHTMX属性だけで処理されます。追加の動作が必要な場合（ローカル計算、アニメーション、チャートレンダリングなど）、インライン<script>ブロックが含まれます:
<script>
// Local-only logic that doesn't need server round-trips
document.querySelector('#slider').addEventListener('input', (e) => {
document.querySelector('#value').textContent = e.target.value;
});
</script>重要な原則: JavaScriptはクライアントローカルの動作用。サーバー通信は常にHTMX属性を通じて行う。
なぜHTMXなのか
検討した代替案
| アプローチ | 利点 | 欠点 |
|---|---|---|
| 生JavaScript | 最大の柔軟性 | LLMが生成するJSは信頼性が低い; innerHTMLではスクリプトが実行されない; 宣言的パターンなし |
| Alpine.js | 軽量、宣言的 | 別のDSL追加（x-data、x-on）; HTMXよりエコシステムが小さい; クライアントサイド状態に焦点、サーバー通信ではない |
| Stimulus (Hotwire) | HTMLセントリック、Railsで実証済み | コントローラー登録が必要; Railsエコシステム偏重; より複雑なメンタルモデル |
| カスタム属性 | 完全な制御 | HTMXが存在するのに独自の属性システムを発明するのは不要; エコシステム、コミュニティ、ドキュメントなし |
| HTMX | HTMLネイティブ、14KB、依存関係ゼロ、大規模エコシステム、LLMフレンドリー | Web限定（ADR-001で許容可能なトレードオフ） |
HTMXが勝つ理由
1. LLMが完璧に生成できる。
HTMX属性は単なるHTML属性。新しい構文なし、DSLなし、コンパイルステップなし。<a href="...">を書けるLLMなら<button hx-get="/data" hx-target="#output">を書ける。学習データには何百万ものHTMXの例が含まれています。
2. JavaScriptなしのインタラクティビティ。
HTMXはClaudeのGenerative UIアーキテクチャで特定された5つの問題を解決します:
| 問題 | Claudeのソリューション | HyperGen + HTMXソリューション |
|---|---|---|
| HTMLとテキストの混在 | 構造化ツールコール | 構造化ツールコール（同じ） |
| スクリプトが実行されない | 手動スクリプト置換 | HTMX属性 — サーバーインタラクションにスクリプト不要 |
| ストリーミングなし | 部分JSON + Morphdom | SSE拡張（hx-ext="sse"）— HTMXに組み込み |
| デザインシステムなし | CSS変数 | CSS変数（同じアプローチ） |
| インタラクティビティループなし | window.sendToAgentブリッジ | hx-post/hx-get — エージェントへの標準HTTP |
3. ストリーミングがファーストクラス。
HTMXのSSE拡張がプログレッシブレンダリングをネイティブに実現:
<div hx-ext="sse" sse-connect="/api/agent/stream" sse-swap="message">
<!-- Content appears here as the agent generates it -->
</div>Morphdomなし。部分JSONパースなし。カスタムストリーミングインフラなし。HTMXが処理します。
4. 双方向通信が組み込み。
ユーザーが生成されたUI（ボタンクリック、フォーム送信）を操作すると、HTMXがサーバーに標準HTTPリクエストを送信します。エージェントはこれを新しい入力として受信し、更新されたHTMLで応答できます。Claudeのwindow.sendToAgentと同じフィードバックループですが、標準Webメカニクスを使用しています。
5. プログレッシブエンハンスメント。
HyperGen UIは3つのレベルで動作:
- HTMXなし: 静的HTMLがレンダリング。リンクとフォームは標準ナビゲーションで動作。機能は低下するが動作する。
- HTMXあり:
hx-*属性による完全なインタラクティビティ。ページリロードなし。ストリーミング動作。 - HTMX + インラインJS: 拡張されたローカル動作（アニメーション、計算、チャート）。
6. 14KB、依存関係ゼロ。
HTMXは単一のスクリプトタグ。npm installなし。ビルドステップなし。推移的依存関係グラフなし。HyperGenの哲学に完璧に一致。
HyperGenコンテキストでのHTMX属性
以下のHTMX属性がGenerative UIに最も関連します:
| 属性 | HyperGenでの目的 |
|---|---|
hx-get / hx-post | ユーザーアクションをエージェントエンドポイントに送信 |
hx-target | エージェントのレスポンスを受信するDOM要素を指定 |
hx-swap | 新しいHTMLが既存コンテンツをどう置換するか制御（innerHTML、outerHTML、beforeendなど） |
hx-trigger | リクエストがいつ発火するか定義（click、submit、load、revealed、every 2sなど） |
hx-ext="sse" | エージェント出力のストリーミング用Server-Sent Eventsを有効化 |
sse-connect | エージェントのSSEエンドポイントに接続 |
sse-swap | 名前付きSSEイベントからコンテンツをスワップイン |
hx-vals | リクエストに追加データを含める（エージェントへのコンテキスト） |
hx-indicator | エージェントレスポンス待機中のローディング状態を表示 |
hx-confirm | 破壊的アクション送信前にユーザーに確認を促す |
結果
ポジティブ
- 最小限のクライアントインフラストラクチャ。 1つの
<script>タグ（HTMX）が、Morphdom、部分JSONパーサー、カスタムストリーミングコード、双方向ブリッジを置き換える。 - LLM生成の信頼性。 HTML属性はLLMの最も強力な生成領域。JSONスキーマバリデーション不要。
- 標準Webパターン。 HTTPリクエスト、SSE、HTMLフラグメント — すべて実戦テスト済み、充分に文書化、広く理解されている。
- プログレッシブエンハンスメント。 生成されたUIはHTMXがロードされなくても機能する。
ネガティブ
- Web限定。 HTMXはブラウザ技術。ネイティブモバイル/デスクトップアプリにはWebViewが必要。（許容可能なトレードオフ — ADR-001参照。）
- インタラクション時のサーバーラウンドトリップ。 すべてのユーザーアクションがHTTPリクエストをトリガー。高頻度のインタラクション（ドラッグ&ドロップ、リアルタイム描画）には代わりにインラインJavaScriptが必要。
- LLMにとってのHTMX学習曲線。 HTMX属性はシンプルなHTMLだが、LLMが正しく使用するためにプロンプトエンジニアリングやシステム指示が必要な場合がある。仕様が推奨プロンプトパターンを定義する。
オープンクエスチョン
- HTMXバージョンの固定。 HyperGenは特定のHTMXバージョンをターゲットすべきか、機能セットをターゲットすべきか？ HTMX 2.xが現在の安定版。
- 拡張戦略。 HTMXには拡張（SSE、WebSocketなど）がある。どの拡張がHyperGen仕様の一部で、どれがオプションか？
- HTMX属性のサニタイズ。
hx-getとhx-postは任意のURLをターゲットにできる。セキュリティモデル（将来のADR）でどの属性が安全でどれがサニタイズを必要とするか定義しなければならない (MUST)。
参考資料
- HTMX — 公式ドキュメント
- HTMX SSE Extension — Server-Sent Eventsサポート
- Hypermedia Systems — 思想的基盤
- How Claude's Generative UI Works — Anthropicのアプローチ分析
- Hypermedia Friendly MCP App Architecture — HTMX + MCPエッセイ
- HTMX: Replace React with 14KB HTML — 実用的な比較
- Locality of Behaviour — HTMX設計原則