AIエージェントとフロントエンド開発をつなぐAgentationが便利そう

Agentationを触ってみたのでメモ。

概要

Agentationは、Webページ上の要素にアノテーションを付けて、AIコーディングエージェント向けの構造化フィードバックを生成できる開発ツール。開発環境として記事執筆時点ではReactが対象。

要素クリック・テキスト選択・メモ追加で、任意のエージェントに渡せるMarkdownを出力する。クラス名やセレクタ、位置情報など含められるため、AIエージェントが該当コードを素早く特定できる。

「Annotating for agents」の投稿が起点になっているらしい。

導入

インストール

npm install agentation

セットアップ

アプリのルート（もしくはルートに近い場所）で<Agentation />を追加する。NODE_ENVを参照して、開発環境でのみ有効にする。

tsx

import { Agentation } from "agentation";

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

使い方

ざっくり以下の手順で使う。

右下のメニューアイコンをクリックして有効化
要素にホバーすると要素名がハイライト表示される
対象の要素をクリックしてアノテーションを追加
フィードバックを書いてAddをクリック
コピーアイコンでMarkdownをコピー
エージェントに貼り付ける

エージェントとの連携

Agentationはコードベースにアクセスできるエージェント（Claude Code、Cursor、Windsurfなど）と組み合わせて使う。

実行中のアプリでバグや修正したい箇所を見つける
Agentationで要素にアノテーションを付ける
出力をコピーしてエージェントに貼る
エージェントがクラス名やセレクタでコードを検索
該当するコンポーネント/ファイルを見つけて修正

Agentationを使うことで簡単に .sidebar > .nav-actions > button.primary の様なコンテキストを渡せるので、エージェントが直接grepで特定しやすくなる。

動作デモ

公式ドキュメントでデモを試せる。以下はこのブログでClaude Codeと組み合わせて使ってみた様子。

出力形式

Agentationは4つの出力フォーマットを提供している。

※詳しくは「Output | Agentation」を参照。

フォーマット	説明	用途
Compact	最小限のコンテキストで迅速なフィードバック	小規模な修正
Standard	位置情報やクラス名を含むバランス型	一般的なユースケース
Detailed	バウンディングボックスや周辺テキストを含む詳細情報	複雑な問題
Forensic	計算されたスタイル（computed styles）を含む最大詳細度	レイアウト・スタイル問題のデバッグ

出力はプレーンなMarkdown形式なので、コピー後に編集してからエージェントに渡すこともできる。コンテキストの追加、優先順位の変更、不要なアノテーションの削除、指示の追加など、自由にカスタマイズ可能。

API

<Agentation /> コンポーネントのAPI（Props）として以下が用意されている。Annotationはコールバックに渡されるオブジェクト。

※詳しくは「API | Agentation」を参照。

プロパティ	型	説明
`onAnnotationAdd`	`(annotation: Annotation) => void`	追加時に呼ばれる
`onAnnotationDelete`	`(annotation: Annotation) => void`	削除時に呼ばれる
`onAnnotationUpdate`	`(annotation: Annotation) => void`	コメント編集時に呼ばれる
`onAnnotationsClear`	`(annotations: Annotation[]) => void`	全削除時に呼ばれる
`onCopy`	`(markdown: string) => void`	コピー時にMarkdownを渡す
`copyToClipboard`	`boolean`	`false`でクリップボード書き込みを抑止（default: `true`）

コード例

基本的な使い方の例：

tsx

import { Agentation, Annotation } from "agentation";

function App() {
  const handleAnnotation = (annotation: Annotation) => {
    console.log(annotation.element, annotation.comment);
  };

  return (
    <>
      <YourApp />
      <Agentation onAnnotationAdd={handleAnnotation} />
    </>
  );
}

Annotationオブジェクト

Annotationオブジェクトの型定義は以下の通り：

type Annotation = {
  id: string; // 一意識別子
  element: string; // 要素名
  elementPath: string; // CSSセレクタパス
  comment: string; // ユーザーのコメント
  timestamp: number; // タイムスタンプ
  x: number; // 位置（ビューポート幅の%）
  y: number; // 位置（上からのpx）
  selectedText?: string; // 選択テキスト
  boundingBox?: {
    // 要素のサイズ
    x: number;
    y: number;
    width: number;
    height: number;
  };
  // Detailed/Forensicモード用
  nearbyText?: string;
  cssClasses?: string;
  nearbyElements?: string;
  computedStyles?: string;
  fullPath?: string;
  accessibility?: string;
  isMultiSelect?: boolean;
  isFixed?: boolean;
};

おわりに

AIエージェントにUIの修正を伝える手段として、Agentationは便利そうだと感じた。ブラウザ上でセレクタや環境を取得できるので、開発者がコードを追わなくても良いのが非常に楽。今後実際に使いながら、精度を検証してみようと思う。

参考

Agentation