iterating-with-ai-and-mcp

AI と MCP による反復処理：エージェントによる編集、再読み込み、スクリーンショットの撮影、反復

Compose HotSwan は、IntelliJ プラグイン内に組み込みの HTTP MCP サーバーを搭載しています。MCP 互換の AI クライアント（Claude Code、Cursor、Model Context Protocol に対応するあらゆるツール）は、そのツールを呼び出して反復処理のループを実行できます。エージェントは Kotlin ファイルを編集し、hotswan_reload を呼び出して、実行中のデバイスのスクリーンショットを撮影し、デザインの意図に照らして結果を評価して、次の変更を決定します。1 回の反復にかかる時間は人間によるループと同程度の数秒なので、各手順を人間が指示しなくても、エージェントは UI の調整を収束させられます。

このスキルでは、標準的なエージェントループ、7 つの MCP ツール（名称は原文どおり）、ループの信頼性を保つための安全上の習慣（最初にステータスを確認する、ロールバック用にスナップショットで囲む、スキーマ変更にはフルインストールに切り替える）について説明します。

このスキルを使う場面

• 開発者が AI による UI の反復調整を希望している：「この画面がモックに一致するまで調整して」「エージェントに色を選ばせて」。
• 開発者が、変更が機能したかどうかを推測するのではなく、AI に自分の編集内容を視覚的に確認させたい。
• 開発者が、実行中のアプリに MCP ツールでアクセスする必要がある Claude Code または Cursor のワークフローを構築している。
• ユーザーが「AI は何が変わったか確認できますか？」「AI はデバイスのスクリーンショットを撮れますか？」「Claude Code は HotSwan をどのように操作しますか？」と尋ねている。
• ユーザーが「MCP server」「hotswan_reload」「hotswan_take_screenshot」「agent loop」「snapshot rollback」に言及している。

このスキルを使わない場面

• 実行時のフィードバックが不要な、純粋なコードレビュー（MCP ツールは一切不要です）。
• リリース品質のビジュアル回帰テスト。HotSwan のスナップショットではなく、Macrobenchmark とスクリーンショット差分ハーネスを使用してください。../../measurement/generating-baseline-profiles/SKILL.md を相互参照してください。
• 対象の変更によってフルリビルドが必要になる場合（パラメーターの追加、コンストラクターの変更、新しいリソース ID）。MCP ループを使う前に ../understanding-hot-reload-limits/SKILL.md を読み、編集内容を分類してください。
• 再読み込みのたびにティア 2 またはティア 3 へエスカレートして状態が失われる場合。自律ループをその上に追加する前に、../preserving-state-across-reloads/SKILL.md に従って解決してください。

前提条件

• Compose HotSwan がインストールされ、IDE プラグインが有効になっていること。セットアップについては ../setting-up-compose-hotswan/SKILL.md を参照してください。
• 対象アプリが、接続されたデバイスまたはエミュレーターですでに実行されており、HotSwan ウォッチャーの状態が WATCHING と報告されていること。
• MCP サーバーの検出が有効で、HotSwan プラグインの HTTP MCP エンドポイントを参照するよう設定された、MCP 対応 AI クライアント（Claude Code、Cursor）。

MCP ツール（名称は原文どおり）

HotSwan MCP サーバーが公開するツールは、次の 7 つだけです。エージェントは追加のツール名を決して作り出してはなりません。

• hotswan_get_status(): デバイス、アプリ、ウォッチャーの状態を返します。エージェントに接続先があり、ウォッチャーが WATCHING であることを確認するため、各ループの開始時に 1 回呼び出してください。
• hotswan_reload(filePaths): 指定したファイルパスを明示的に再読み込みします。実行されたティア（1 / 2 / 3）を返します。エージェントはティアを読み取り、前回の編集でもループの速さが保たれたかを判断します。
• hotswan_take_screenshot(): 現在のデバイス画面をキャプチャします。画像バイト列、またはエージェントが読み込んで確認できるパスを返します。
• hotswan_start_snapshot(): スナップショットセッションを開始します。この呼び出しの後は、再読み込みのたびに HotSwan がスクリーンショットとソースの状態を自動的にキャプチャするため、エージェントは中間のどのバリエーションにもロールバックできます。
• hotswan_stop_snapshot(): 現在のスナップショットセッションを終了し、履歴を確定します。
• hotswan_select_variant(): 記録された履歴から優先するスナップショットを選択します。エージェントが以前の反復のほうが最良だったと判断した場合、選択したバリエーションにソースコードをロールバックするために使用します。
• hotswan_build_and_install(): フルインストールに切り替えます。新しいパラメーター、コンストラクターの変更、新しいリソース ID など、ホットリロードパイプラインで処理できないスキーマ変更をエージェントが検出した場合に使用します。デフォルトではなく、フォールバックとして扱ってください。

ワークフロー

標準的なエージェントループ：

1. 編集を行う前にステータスを確認する

hotswan_get_status() を呼び出します。watcher が WATCHING でない場合は、人間に問題を伝えて停止します。ウォッチャーが実行されていない場合、リロードツールは何もせずに終了し、エージェントは画面に何も変化がない理由を探して処理を無駄に繰り返すことになります。

2. スナップショットセッションを開始する

hotswan_start_snapshot() を呼び出して、ループの視覚的な記録を残します。セッション中の各リロードで自動的にキャプチャされるため、エージェント（または後から確認する人間）は各反復を比較し、任意のバリアントに戻すことができます。

3. 対象ファイルを編集する

エージェントが利用できるファイル編集ツールを使って、Kotlin ファイルを編集します。可能であれば、変更を 1 つのコンポーザブルスコープ内に収めて、リロードがティア 1 にとどまるようにします（../preserving-state-across-reloads/SKILL.md への相互リンクを参照してください）。

4. リロードを実行してティアを確認する

hotswan_reload(["app/src/main/kotlin/com/example/Foo.kt"]) を呼び出します。返されたティアを確認します。ティア 1 はループが高速なままだったことを意味します。ティア 2 またはティア 3 の場合は状態が失われた可能性が高いため、次のスクリーンショットを撮る前に、ナビゲーションまたは一時的な UI 状態を再確立する必要があるとエージェントは想定してください。

5. スクリーンショットを撮って評価する

hotswan_take_screenshot() を呼び出します。返された画像をデザインの意図と比較します。問題がなければループを終了します。そうでなければ、編集内容を調整してステップ 3 に戻ります。

6. スキーマ変更時はフォールバックする

次の編集で関数シグネチャ、コンストラクター、インターフェースを変更する場合、または新しいリソース ID を追加する場合は、hotswan_build_and_install() を呼び出して、続行する前にフルインストールを行います。スキーマに違反する編集に対して hotswan_reload を繰り返し実行しないでください。リロードツールは失敗を報告し、ループが停止します。

7. ループを終了する

反復結果に問題がなければ、hotswan_stop_snapshot() を呼び出します。必要に応じて hotswan_select_variant() を呼び出し、最終状態よりも好ましい中間バリアントにソースを戻すこともできます。

パターン

パターン：ステータス確認を省略する

// WRONG
1. Edit file
2. Call hotswan_reload
3. Wonder why nothing happened
// WRONG because: HotSwan needs the app running and the watcher in WATCHING state. If neither is true the reload silently no-ops. Always call hotswan_get_status first.

// RIGHT
1. status = hotswan_get_status()
2. require(status.watcher == "WATCHING")
3. edit, reload, screenshot, iterate

パターン：スナップショットセッションなしでリロードする

// WRONG (for visual iteration)
edit -> reload -> screenshot -> discard -> repeat
// WRONG because: the agent loses the ability to roll back to a previous variant. Always wrap visual iteration loops in hotswan_start_snapshot / hotswan_stop_snapshot.

// RIGHT
hotswan_start_snapshot()
repeat { edit; hotswan_reload([target]); hotswan_take_screenshot() }
hotswan_stop_snapshot()

パターン：タイトなループ内でのスキーマ変更

// WRONG
Edit a composable to add a new parameter, then call hotswan_reload.
// WRONG because: parameter additions are a class-schema change. ART rejects the swap and hotswan_reload reports failure. The agent must detect the schema change first and call hotswan_build_and_install instead.

// RIGHT
if (editChangesSchema(plannedEdit)) {
    applyEdit(target)
    hotswan_build_and_install()
} else {
    applyEdit(target)
    hotswan_reload([target])
}

スキーマに違反する編集の完全な一覧については、../understanding-hot-reload-limits/SKILL.md への相互リンクを参照してください。

パターン：標準的なループ全体

// RIGHT
status = hotswan_get_status()
require(status.watcher == "WATCHING")
hotswan_start_snapshot()
repeat {
    edit_file(target)
    result = hotswan_reload([target])
    screenshot = hotswan_take_screenshot()
    if (accepts(screenshot, intent)) break
}
hotswan_stop_snapshot()

ループの動作要素は、編集、リロード、スクリーンショット、評価の 4 つだけです。それ以外はすべて記録管理です（ステータス確認、スナップショットの開始と終了、任意のロールバック）。

必須ルール

• 必須： すべてのループの開始時に hotswan_get_status() を呼び出し、編集を行う前にウォッチャーの状態を確認します。
• 必須： エージェントが元に戻せるように、視覚的な反復ループを hotswan_start_snapshot() と hotswan_stop_snapshot() で囲みます。
• 禁止： MCP ツール名をでっち上げてはいけません。MCP ツールのセクションに記載されている次の 7 つの名前のみを使用します：hotswan_get_status、hotswan_reload、hotswan_take_screenshot、hotswan_start_snapshot、hotswan_stop_snapshot、hotswan_select_variant、hotswan_build_and_install。
• 禁止： タイトな内部ループで hotswan_build_and_install() を呼び出してはいけません。これはスキーマ変更時のフォールバックであり、デフォルトの方法ではありません。デフォルトとして使用すると、HotSwan の速度面での利点が失われます。
• 推奨： ../understanding-hot-reload-limits/SKILL.md と組み合わせて、hotswan_reload を使用する前に、エージェントが予定している編集を分類できるようにします。
• 推奨： ../preserving-state-across-reloads/SKILL.md と組み合わせて、リロードがティア 2 またはティア 3 にエスカレートし、一時的な UI 状態が失われる場合をエージェントが認識できるようにします。

検証

• ループの実行前に hotswan_get_status() が WATCHING を返す
• 各 hotswan_reload 呼び出しがティア（1、2、または 3）を報告する
• hotswan_take_screenshot() がエージェントの確認可能な画像バイト列を返す
• ループ後にスナップショット履歴が空でなく、hotswan_stop_snapshot() がセッションを確定する
• スキーマに違反する編集が hotswan_reload ではなく hotswan_build_and_install() を経由する

参考資料

• HotSwan MCP サーバーのドキュメント：https://github.com/skydoves/compose-hotswan-web （/docs/mcp-server 内）
• HotSwan エージェントスキルの例：同じリポジトリの/docs/agent-skill
• HotSwan スナップショットのドキュメント：同じリポジトリの/docs/snapshot
• HotSwan JetBrains プラグインの掲載ページ：https://plugins.jetbrains.com/plugin/30551-compose-hotswan/
• Model Context Protocol のオープンスタンダード：https://modelcontextprotocol.io