agentation

agentation

agentation は、このリポジトリにおける レンダリング済み UI のフィードバックブリッジです。

人間が実際の UI をクリックし、対象とする正確な要素や領域にフィードバックを添付して、構造化されたパケットをコーディングエージェントに渡す必要があるときに使用します。主な役割は アノテーションの振り分けです。適切なアノテーションモードを選び、正確な根拠を取得して、修正ループを適切な関連スキルまたはエージェントのランタイムに引き継ぎます。

このスキルを使用する場面

次のいずれかが必要なタスクでは、agentation を使用します。

• レビュー担当者が曖昧な説明をする代わりに、実際の UI 要素を指し示す
• セレクター、要素パス、境界ボックス、コピーした Markdown を含む構造化フィードバックパケット
• ブラウザーとコーディングエージェント間でローカルにコピー＆ペーストするレビューのループ
• 新しいアノテーションをエージェントのコンテキストに自動で流し込む、MCP を利用した同期／監視ループ
• レンダリング済み UI の根拠から開始する、自律的な批評／修正ループ
• 保留中の UI アノテーションを Claude Code、Codex、Gemini CLI、または OpenCode に渡すためのプラットフォーム設定

次の場合、デフォルトでは agentation を使用しないでください。

• 新しいセッションでのブラウザー検証や、決定論的な回帰チェック → browser-harness
• 起動中のブラウザー、ログイン済みのブラウザー、または拡張機能に依存するブラウザーの再利用 → playwriter
• 提案された成果物の計画レビュー、差分の承認、またはビジュアルサインオフ → plannotator
• 具体的なレンダリング済み UI パケットを伴わない、一般的なデザインシステム、アクセシビリティ、またはヒューリスティックによる監査

簡単な振り分けルール

必要な作業	使用するもの
人間が UI をクリックし、エージェント向けに正確なフィードバックを残す	agentation
クリーンで再現可能なセッションでのブラウザー検証	browser-harness
ユーザーがすでに開いているブラウザー、Cookie、またはログイン済みのタブ	playwriter
実行前の計画／差分のレビューまたは承認	plannotator

手順

ステップ 1：適切なアノテーションモードを選ぶ

セットアップの詳細に取りかかる前に、モードを 1 つ選びます。

モード	使用する場面	出力
コピー＆ペーストレビュー	1 人のレビュー担当者が UI にアノテーションを付け、パケットをチャットに貼り付ける	構造化された Markdown パケット
同期監視ループ	新しいアノテーションをエージェントのワークフローに自動で表示する	保留中のアノテーションキュー＋ループ
自律的な批評	エージェント／ブラウザーのループがアノテーションを繰り返し生成または使用する	レビュー／修正ループのパケット
プラットフォーム設定	主な課題がアノテーションブリッジを Claude／Codex／Gemini／OpenCode に接続すること	セットアップのチェックリストと設定対象

タスクが実際には「ウェブサイトをテストする」または「ログイン済みブラウザーを操作する」ことである場合は、まず適切な別の手段に振り分けてください。正確な人間による UI フィードバックが不足している場合に限り、agentation に戻ってください。

ステップ 2：ブラウザーの境界を明確にする

agentation はブラウザーのランタイムの選択を 置き換えるものではありません。

• クリーンで破棄可能な検証用ブラウザーが必要な場合は、browser-harness を使用します。
• ユーザーの実際のブラウザーセッションを再利用する必要がある場合は、playwriter を使用します。
• 人間またはループが正確なアノテーションを付けるレンダリング済みページがある場合は、agentation を使用します。

ステップ 3：基本ループに従う

1. レンダリング済み UI を準備する
   • 必要に応じて、まず適切なブラウザー／ランタイムスキルを選びます。
2. 開発中のアプリに Agentation ツールバーを追加する。
3. アノテーションモードを選ぶ：コピー＆ペースト、監視ループ、自律型、または設定。
4. 具体的な UI パケットを 1 つ取得する。
5. パケットをコーディングエージェントに渡す。
6. 同じレビューレーンを使って、修正後に再検証する。

ステップ 4：最も速く安全なインストール方法を使う

ほとんどのセットアップでは、実用的な順序は次のとおりです。

# React toolbar
npm install agentation -D

# MCP bridge / auto-registration for supported agents
npx add-mcp "npx -y agentation-mcp server"

# verify the bridge
npx agentation-mcp doctor

Claude Code のユーザーは、エクスペリエンスを立ち上げる最も簡単な方法であれば、上流の公式スキルをインストールすることもできます。

npx skills add benjitaylor/agentation -g
# then use /agentation in Claude Code

ステップ 5：最小限のツールバー連携から始める

最小限の有用な埋め込みから始めます。

import { Agentation } from 'agentation';

function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === 'development' && <Agentation />}
    </>
  )
}

選択したモードで実際に必要な場合にのみ、endpoint、コールバック、または Webhook の動作を追加してください。

ステップ 6：適切な引き継ぎパターンを選ぶ

A. コピー＆ペーストによるレビュー

人がページを積極的に確認し、フィードバックパケットをエージェントとのチャットに貼り付ける場合に使用します。

次の用途に適しています：

• 素早いバグ修正／UI の磨き込み
• 単発の的を絞った修正
• セットアップを最小限に抑えた共同作業

B. 同期ウォッチループ

エージェントが保留中の注釈を継続的にポーリングまたは取り込む場合に使用します。

次の用途に適しています：

• 繰り返し行う QA／修正サイクル
• デザイナー ↔ エージェントのやり取り
• フロントエンド作業中のローカルレビューキュー

ループを信頼する前に、同梱の検証スクリプトを実行してください：

bash .agent-skills/agentation/scripts/verify-loop.sh

C. 自律的な批評

エージェント／ブラウザーのループが UI を繰り返し確認し、agentation をブラウザーの実行環境そのものではなく、構造化されたフィードバックパケットとして使用する場合に適しています。

一般的な流れ：

• ブラウザーツールが現在の状態をキャプチャする
• agentation が具体的なフィードバック対象をエンコードする
• コーディングエージェントが修正を適用する
• ブラウザーツールが結果を再確認する

Step 7：プラットフォームのセットアップ範囲を絞る

依頼が実際にはプラットフォームの接続設定に関するものであれば、次の内容だけを回答します：

• 設定ファイルの場所
• agentation-mcp の登録方法
• 保留中の注釈をエージェントのループに取り込む方法
• セットアップの検証方法

メインのワークフローが肥大化しないよう、プラットフォーム固有の設定ブロックはリファレンスに移してください。

スクリプト

長いコマンドを再入力する前に、同梱のスクリプトを使用してください：

スクリプト	目的
scripts/setup-agentation-mcp.sh	対応するエージェントに MCP ブリッジを登録します
scripts/verify-loop.sh	注釈キュー／ACK → RESOLVE 形式のウォッチループの動作を検証します

例

例 1：人間のレビュアーが正確な UI フィードバックを求めている

• プロンプト：「壊れているチェックアウトボタンを指摘できますが、セレクターを手作業で説明するのは避けたいです。」
• 期待される動作：agentation を選び、コピー＆ペーストによるレビューまたは同期モードを推奨し、ブラウザーの実行環境の選択は別に扱います。

例 2：ブラウザーでの検証が本来の作業である

• プロンプト：「再現可能なヘッドレス UI 回帰チェックを実行し、結果を比較してください。」
• 期待される動作：人間による注釈が後続の手順にならない限り、agentation ではなく browser-harness に案内します。

例 3：ログイン済みブラウザーの再利用

• プロンプト：「すでにサインインしているブラウザーを使って、請求ページの問題に注釈を付けさせてください。」
• 期待される動作：ブラウザーの実行環境には playwriter を使い、注釈パケットには agentation を使います。

例 4：UI レビューではなく計画のレビュー

• プロンプト：「生成された計画をブラウザーで開いて、コーディング開始前に各ステップを承認または却下できるようにしてください。」
• 期待される動作：成果物はレンダリングされた UI の問題ではなく計画／差分なので、plannotator に案内します。

ベストプラクティス

1. まずブラウザー／実行環境の経路を選びます。agentation はフィードバックを橋渡しするものであり、あらゆるブラウザーツールの代わりではありません。
2. コピー＆ペースト、ウォッチループ、プラットフォーム設定を1つの回答に混在させず、一度に1つの注釈モードを選ぶことを推奨します。
3. 最初の統合は最小限にとどめ、ワークフローで必要な場合にのみフック、コールバック、Webhook を追加します。
4. 修正後は、注釈を作成したものと同じレビュールートで再検証します。
5. 納品物は正確な UI フィードバックとし、インストール方法の組み合わせを大量に列挙しないようにします。
6. 実際のタスクが計画のレビュー、新規ブラウザーでの検証、または実行中ブラウザーの再利用である場合は、積極的に別のツールへ案内します。

リファレンス

このスキルの詳細ドキュメント：

• modes-and-routing
• platform-setup-and-hooks
• watch-loop-and-self-driving

主な情報源：

• https://github.com/benjitaylor/agentation
• https://agentation.com
• https://www.npmjs.com/package/agentation
• https://www.npmjs.com/package/agentation-mcp

メタデータ

• バージョン：1.1.0
• 最終更新日：2026-04-15
• 対象範囲：コーディングエージェント向けの、レンダリング済み UI の正確なフィードバックパケット、ウォッチループ、プラットフォームへの引き継ぎ