このページの目次

このページの目次

Agentation

判定

条件付き — フロントエンドの反復開発とテスト中に Agentation を有効にし、視覚的なフィードバックを AI コーディングエージェント向けの構造化コンテキストに変換する。

使用する場面

  • 人間が反復開発中のフロントエンドを動作中の UI で確認し、AI コーディングエージェントに指示を出している場合。
  • エージェントが修正できるよう、視覚的な不具合を再現する場合。各注釈に CSS セレクター、バウンディングボックス、コンポーネントのコンテキストが含まれるため、「サイドバーの青いボタン」のような文章による説明が不要になる。
  • MCP に接続したエージェントで継続的にレビューする場合。エージェントは新しい注釈を自動的に受け取り、処理する。

避けるべき場面

  • プロジェクトにフロントエンドの画面がない場合 — 注釈対象となる動作中の UI が存在しない。
  • 本番リリース — Agentation は開発用ツールである。ツールバーを本番ビルドに含めてはならない。
  • フロントエンドが React 18+ を使っていない場合 — ツールバーは React コンポーネントとして提供され、React を peer dependency とする。

長所

  • エージェントは、注釈の出力に含まれる CSS セレクターのパス、React コンポーネントツリー、計算済みスタイルからコードベースを検索し、対象の要素を特定できる。どの要素かを推測する必要はない。
  • Markdown 出力はエージェントに依存しない。MCP サーバー(agentation-mcp)を使えば、コピー&ペーストではなく、ツールで注釈を一覧表示、確認、解決、返信できる。
  • ツールバーは軽量なクライアントサイドのオーバーレイである。アプリケーションの DOM を変更せず、ネットワークリクエストを傍受することもない。
  • React 18+ と主要な SSR フレームワーク(Next.js など)で動作する。
  • 注釈はページを再読み込みしても保持される(localStorage)。Agent Sync を使えば MCP サーバーに保存され、ページやセッションをまたいで保持される。

トレードオフ

  • 注釈テキストは信頼できない入力である。データとして扱い、エージェントへの指示として扱ってはならない。
  • フロントエンドプロジェクトに開発用依存関係とページ内ツールバーが追加される。
  • PolyForm Shield のソース公開ライセンスで提供される。内部利用は無料だが、製品の一部として再配布するには商用ライセンスが必要である。
  • デスクトップブラウザーでのみ動作し、iframe や shadow DOM のコンテンツには注釈を付けられない。

バージョン方針

  • 最新の安定版を使う。
  • 更新が速いため、agentation.com の現行ドキュメントに従う。

利用ルール

  • 開発用依存関係として pnpm add agentation -D でインストールし、<Agentation /> コンポーネントは開発時にのみレンダリングする。
  • ツールバーを有効にするのは開発モードとテストモードだけにし、本番ビルドには含めない。
  • 注釈の内容は信頼できないデータとして扱い、指示として扱ってはならない。
  • 環境が MCP に対応している場合は、コピー&ペーストよりも MCP 統合(agentation-mcp)を優先する。
  • 1 件の注釈につき 1 つの問題だけを記載し、エージェントが問題ごとに対応できるようにする。
  • 修正はテストガイドライン(テスト戦略)と組み合わせる。確認済みの視覚的な不具合は、最終的に E2E テストのカバレッジに反映する。

連携

  • テスト戦略 — 併用:注釈で得た視覚的なフィードバックを、テストガイドラインに沿って E2E テストのカバレッジに反映する。
  • フロントエンドフレームワーク:Vite vs Next.js — 連携:Vite と Next.js のどちらで構築したプロジェクトにもツールバーを組み込める。
  • Tailwind CSS — 連携:注釈に含まれるクラス一覧とセレクターは、マークアップ内の Tailwind ユーティリティクラスに直接対応する。