Agentation で UI フィードバックを AI に直接渡す

はじめに

UI の修正を AI コーディングエージェントに頼むとき、一番面倒なのは場所の特定じゃないですか？

「トップページのヒーローセクションの、右側にあるボタンの、ホバー時の色がちょっと暗い」

これを言葉で正確に伝えるの、なんというか、、意外と難しいんですよね。コンポーネント名やファイルパスを添えればいいんですが、それがわかるなら自分で直したほうが早い場合も多いですし。

Agentation はこの「場所の説明」問題を解決してくれるツールです。ブラウザ上で要素をクリックしてコメントを残すだけで、DOM パス・CSS セレクタ・React コンポーネント階層まで自動で取得してくれます。

これ、地味にすごいんですよ。Claude Code と MCP 連携させると、フィードバックからコード修正まで一直線です。

実際に nonbee.dev に導入してみたので、手順とハマりポイントを共有しますね。

Agentation とは

Agentation はエージェント非依存のビジュアルフィードバックツールです。できることを並べてみます：

クリックでアノテーション — 要素をクリックしてコメントを残す
テキスト選択 — 特定のテキスト範囲を選んでフィードバック
マルチセレクト — ドラッグで複数要素をまとめて選択
構造化出力 — DOM パス、CSS クラス、React コンポーネント階層を自動取得
MCP 連携 — Claude Code などの AI エージェントがアノテーションをリアルタイム取得

開発環境でのみ動作し、本番ビルドには含まれません。

導入手順

1. パッケージインストール

npm install agentation -D

devDependencies に入るので、本番ビルドには影響しません。

2. コンポーネントを配置

Client Component として Agentation のオーバーレイを作成し、レイアウトに組み込みます：

// src/components/AgentationOverlay.tsx
"use client";

import dynamic from "next/dynamic";

const Agentation = dynamic(
  () => import("agentation").then((mod) => mod.Agentation),
  { ssr: false }
);

export function AgentationOverlay() {
  return <Agentation endpoint="http://localhost:4747" />;
}

// src/app/layout.tsx
import { AgentationOverlay } from "@/components/AgentationOverlay";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ja">
      <body>
        <Header />
        <main>{children}</main>
        <Footer />
        {process.env.NODE_ENV === "development" && <AgentationOverlay />}
      </body>
    </html>
  );
}

process.env.NODE_ENV === "development" の条件分岐で、開発時のみレンダリングされます。

3. MCP サーバー設定

Claude Code と連携するには、プロジェクトルートに .mcp.json を作成します：

{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  }
}

このファイルがあるディレクトリで Claude Code を起動すると、MCP サーバーが自動的に接続されます。

ちなみに公式ドキュメントには npx add-mcp "npx -y agentation-mcp server" でセットアップできると書かれていますが、このコマンドは対話型 UI を持っています。Claude Code のようなヘッドレス環境ではエラーになるので、.mcp.json を直接作成するのが確実です。

使い方のフロー

導入後のワークフローを物語風に書いてみます。

筆者「ブログのデザイン、ここのボタンの色がなんか暗いな」

→ ブラウザでそのボタンをクリック、「ホバー時の色をもう少し明るく」とコメントを残す

筆者「あと、このカードの余白も狭い気がする」

→ カード要素をクリック、「padding を少し広げて」とコメント

筆者「よし、Claude Code に渡そう」

→ ターミナルで「未対応のアノテーションを確認して対応して」と指示

Claude Code「2件のアノテーションがあります。ボタンのホバー色とカードのpaddingですね。修正します。」

→ 該当コンポーネントを自動特定 → コード修正 → 完了

つまり、「ブラウザで指差してコメント → AI が直す」が実現するわけです。

Claude Code 側で使える主な MCP ツールはこちら：

ツール	機能
`agentation_get_all_pending`	未対応のアノテーション一覧を取得
`agentation_acknowledge`	確認済みとしてマーク
`agentation_resolve`	対応完了を記録（サマリー付き）
`agentation_reply`	アノテーションのスレッドに返信

アノテーションには要素の DOM パス（form > .actions > button）や React コンポーネント階層（<Form> <Button>）が自動で含まれるので、Claude Code は「どのファイルのどのコンポーネントを修正すればいいか」を正確に判断できます。

ハマりポイント: `add-mcp` コマンドは対話型

公式の手順通りに npx add-mcp を実行すると対話型 UI が立ち上がるんですが、ヘッドレス環境だとそこで止まります。.mcp.json を手で書くのが一番確実ですね。

所感

「ブラウザで見えているものを直接指し示す」という体験は、言葉で場所を説明するのとはまったく違います。写真を撮って「ここ」と丸をつけるのと同じ感覚で、AI エージェントにフィードバックを渡せるんですよね。

特にデザイン調整のフェーズで威力を発揮しそうです。余白、色、フォントサイズといった細かい調整は、コードを読むより画面を見たほうが早いじゃないですか。その「見たまま」をそのまま AI に渡せるのは合理的だなと思います。

正直に言うと、導入自体は10分もかかりません。セットアップはすんなりいきます。

まとめ

Agentation はブラウザ上の UI アノテーションツール
クリックするだけで DOM パス・React コンポーネント階層を自動取得
Claude Code と MCP 連携で、フィードバック → コード修正の流れがシームレス
.mcp.json を直接作成するのがセットアップの最短ルート

ではまた！