ShadCN UI崩壊を防ぐAIコーディング戦略：RALPHループと視覚的検証プロトコル

ClaudeやCursorのようなAIエージェントに複雑なUI実装を任せたことがあるなら、特有の虚脱感をよくご存じでしょう。「作業完了」というメッセージを信じてブラウザを立ち上げたとき、レイアウトが紙屑のように崩れていたり、ドロップダウンメニューがモーダルの背後に隠れてしまっていたりする悲惨な光景のことです。

2026年現在、Claude Codeのようなツールは自らファイルシステムを探索してコードを書きますが、依然として「中途放棄」と「虚偽の完了」という慢性的な問題を抱えています。特にShadCN UIのように精巧なコンポーネントを扱う際、AIは文法的な無欠性にのみ執着し、実際の画面がユーザーにどう見えるかを無視しがちです。AIの嘘を根絶し、無欠陥のUIを構築するための実戦戦略を解説します。

RALPHループ：AIの「ナイーブな粘り強さ」を強制する方法

RALPH (Repeated Agent Loop for Prompt Heuristics) ループは、技術的には単純ですが強力な「ナイーブな粘り強さ（Naive Persistence）」に基づいています。核心は、AIエージェントが事前に約束した**完了の約束（Completion Promise）**の文言を出力するまで、初期プロンプトを繰り返し注入することです。

典型的なAIは一度の呼び出しで作業を終わらせようとしますが、RALPHループはこれを複数のイテレーションに強制的に分割します。エージェントがセッションを終了しようとするとき、システムがこれをインターセプトし、出力テキスト内に <promise>COMPLETE</promise> のような特定のキーワードがあるか確認します。キーワードがなければ、前のループのGit履歴と状態を含めて、再び初期プロンプトを投げます。

この方式の真の価値は、**フレッシュなコンテキスト（Fresh Context）**にあります。会話が長くなるほど発生するコンテキストの腐敗現象を防ぎ、エージェントが毎回ファイルシステムの客観的な証拠だけを読み取って作業を再開するように仕向けます。実際のベンチマークデータによると、このような反復ループを適用した場合、複雑なUIバグの修正成功率は従来の単発プロンプトに比べて65%以上向上しました。

ShadCN UIでAIが犯す致命的なミス

AIは「コードが綺麗ならUIも完璧だ」と錯覚します。しかし、視覚的な文脈理解が不十分なAIエージェントは、次のようなミスを繰り返します。

• z-indexの衝突: ShadCNのDialog内部にSelectを配置する際、AIはよく z-index: 9999 を付与するという初歩的なミスを犯します。親要素がすでにスタックコンテキストを形成している場合、これは視覚的な遮蔽やクリックイベントの消失につながります。
• レイアウトシフト: モーダルが開くときに data-scroll-locked 属性がこじれ、画面が左右にガタつく現象を、AIはテキストログだけでは捉えることができません。
• イベントの遮断: 不必要な pointer-events-none を乱用し、ボタンが見えているにもかかわらずクリックできない状態のまま放置されるケースが頻発します。

こうした推測に基づいたコーディングを防ぐには、ShadCN UI MCP サーバーを導入すべきです。エージェントに最新のAPIドキュメントと標準パターンをリアルタイムで提供すれば、存在しない属性を使用するミスを80%以上削減できます。

Playwrightを活用した視覚的TDDの統合

機能テストが「ボタンが動作するか」を問うなら、視覚的検証はその「ボタンが正しく見えているか」を確認します。2026年型のPlaywrightエージェントを活用すれば、このプロセスを自動化できます。

まず npx playwright init-agents --loop=claude を通じてMCP接続を有効化します。検証時にはアニメーションを無効化してピクセル誤差を減らし、日付やユーザー名などの動的領域はマスキング処理して検証対象から除外します。既存の画像とピクセルの差異が閾値を超えた場合、エージェントが自動的に修正ループに入るよう設定するのが肝要です。

AIの形骸化を防ぐ2段階検証プロトコル

エージェントが検討プロセスを適当に済ませられないようにするには、検討を「記録可能な行動」で証明させる必要があります。

1段階：強制的なファイル命名規則 (The Rename Step)

エージェントが実装を終えたら、Playwrightですべてのコンポーネントのスクリーンショットを撮らせます。エージェントは各ファイルを直接開き、完璧だと判断したときだけファイル名を verified_ 接頭辞に変更しなければなりません。「書き込み作業」を強制することで、画像を実際に分析せずにはループを進められないようにする仕組みです。

2段階：ループ脱出条件 (The Verification Gate)

システムは次のイテレーションで、すべてのスクリーンショットに verified_ が付いているか全数調査します。一つでも漏れていれば、「検証されていない要素が発見されました」というフィードバックとともにループを再稼働させます。

視覚的整合性保証ガイドラインの例

1. すべてのUIコンポーネントのPlaywrightスクリーンショットを生成せよ。
2. スクリーンショットを全数調査し、z-indexの衝突およびレイアウト崩れを確認せよ。
3. 完璧なファイルにのみ verified_ 接頭辞を付けてファイル名を変更せよ。
4. すべてのファイルが変更されるまでは、絶対に完了の約束を出力するな。

リスク管理とコスト最適化

自律的なループは強力ですが、設計を誤るとAPIコストの爆発を招く恐れがあります。これを防ぐため、 --max-iterations フラグを使用して、単一機能の実装を10回から20回程度に制限する必要があります。

同一のエラーが3回以上繰り返されるデッドロックが検知された場合は、実装戦略を完全に破棄し、新しいアーキテクチャでアプローチするよう指示してください。また、複雑なUI設計には Claude 4.5 のような高性能モデルを使用し、単純なリント修正やファイル整理は Haiku 系のモデルにルーティングしてコストを削減する賢明さも必要です。

現代のエンジニアは、もはや一行ずつコードを修正するベビーシッターではありません。AIが自ら正解を見つけるように追い込む「検証システムの設計者」であるべきです。RALPHループと視覚的検証プロトコルは、AIが征服できていなかったユーザーエクスペリエンスの無欠性を確保する最後の砦となるでしょう。今すぐプロジェクトにRALPHループプラグインをインストールし、検証されたスクリーンショットに裏打ちされた「本当の完了」を体験してください。