agentation-self-driving

Agentation の自動運転モード

Agentation ツールバーを使ってデザイン注釈を追加し、Web ページを自律的に批評します。ブラウザーを表示した状態で開き、エージェントが自動運転車のようにページを操作する様子をリアルタイムで確認できます。

起動 — 常に画面を表示

ブラウザーは必ず表示してください。ヘッドレスでは実行しないでください。ユーザーが、スキャン、ホバー、クリック、注釈の追加を行う様子を確認できます。

事前確認：何よりも先に、agent-browser が利用可能であることを確認してください。

command -v agent-browser >/dev/null || { echo "ERROR: agent-browser not found. Install the agent-browser skill first."; exit 1; }

起動：まず直接開いてみてください。既存セッションを閉じてよいのは、開くコマンドが古いセッションのエラーで失敗した場合のみです。これにより、他のユーザーが使用中のブラウザーを終了せずに済みます。

# Try to open. If it fails (stale session), close first then retry.
agent-browser --headed open <url> 2>&1 || { agent-browser close 2>/dev/null; agent-browser --headed open <url>; }

次に、Agentation ツールバーが表示されていることを確認し、展開してください。

# 1. Check toolbar exists on the page. Agentation 3.1+ renders inside a shadow root on <agentation-toolbar>,
#    so query through it (the fallback to document keeps older versions working)
agent-browser eval "(document.querySelector('agentation-toolbar')?.shadowRoot || document).querySelector('[data-feedback-toolbar]') ? 'toolbar found' : 'NOT FOUND'"
# If "NOT FOUND": Agentation is not installed on this page — stop and tell the user

# 2. Expand ONLY if collapsed (clicking when already expanded collapses it)
agent-browser eval "(document.querySelector('agentation-toolbar')?.shadowRoot || document).querySelector('[data-feedback-toolbar][class*=expanded]') ? 'already expanded' : ((document.querySelector('agentation-toolbar')?.shadowRoot || document).querySelector('[class*=toggleContent]')?.click(), 'expanding')"

# 3. Verify: take a snapshot and look for toolbar controls
agent-browser snapshot -i
# If expanded: you'll see "Block page interactions" checkbox, color buttons (Purple, Blue, etc.)
# If collapsed: you'll only see the small toggle button — retry step 2

「ページの操作をブロックする」にチェックが入っている必要があります（デフォルト：オン）。

eval の引用符ルール：eval 文字列では、必ず [class*=toggleContent] を使用してください（属性値を引用符で囲まないでください）。bash が履歴展開として扱うため、eval では二重感嘆符を使用しないでください。また、シェルによって予期せぬ動作を引き起こすため、内側の引用符をバックスラッシュでエスケープすることも避けてください。

重要：注釈の作成方法

通常の要素クリック（click @ref）では、注釈ダイアログは開きません。 Agentation オーバーレイはポインターイベントを座標レベルで捕捉します。座標ベースのマウスイベントを使用してください。これなら、カーソルがページ上を移動する様子もブラウザー上で確認できます。

@ref の互換性：click、fill、type、hover、focus、check、select、drag のみ、@ref 構文に対応しています。scrollintoview、get box、eval コマンドは対応しておらず、CSS セレクターを指定する必要があります。スクロールや位置の取得には、querySelector を使った eval を使用してください。

# 1. Take interactive snapshot — identify target element and build a CSS selector
agent-browser snapshot -i
# Example: snapshot shows  heading "Point at bugs." [ref=e10]
# Derive a CSS selector: 'h1', or more specific: 'h1:first-of-type'

# 2. Scroll the element into view via eval (NOT scrollintoview @ref — that breaks)
agent-browser eval "document.querySelector('h1').scrollIntoView({block:'center'})"

# 3. Get its bounding box via eval (NOT get box @ref — that also breaks)
agent-browser eval "((r) => r.x+','+r.y+','+r.width+','+r.height)(document.querySelector('h1').getBoundingClientRect())"
# Returns: "383,245,200,40"  (parse these as x,y,width,height)

# 4. Move cursor to element center, then click
#    centerX = x + width/2,  centerY = y + height/2
agent-browser mouse move <centerX> <centerY>
agent-browser mouse down left
agent-browser mouse up left

# 5. Get the annotation dialog refs — read the FULL snapshot output
#    Dialog refs appear at the BOTTOM of the list, don't truncate with head/tail
agent-browser snapshot -i
# Look for: textbox "What should change?" and "Cancel" / "Add" buttons

# 6. Type critique — fill and click DO support @ref
agent-browser fill @<textboxRef> "Your critique here"

# 7. Submit (Add button enables after text is filled)
agent-browser click @<addRef>

クリックしてもダイアログが表示されない場合は、ツールバーが折りたたまれている可能性があります。折りたたまれている場合のみ再展開して、もう一度試してください。

agent-browser eval "(document.querySelector('agentation-toolbar')?.shadowRoot || document).querySelector('[data-feedback-toolbar][class*=expanded]') ? 'ok' : ((document.querySelector('agentation-toolbar')?.shadowRoot || document).querySelector('[class*=toggleContent]')?.click(), 'expanded')"

スナップショットからの CSS セレクターの作成

スナップショットには、要素のロール、名前、参照が表示されます。それらを CSS セレクターに対応付けます。

スナップショットの行	CSS セレクター
heading "Point at bugs." [ref=e10]	h1 または h1:first-of-type
button "npm install agentation Copy" [ref=e15]	button:has(code) または eval を使ってテキスト内容で指定
link "Star on GitHub" [ref=e28]	a[href*=github]
paragraph (long text...) [ref=e20]	セクションで指定：section:nth-of-type(2) p

迷った場合は、より広範なセレクターを使い、eval で確認してください。

agent-browser eval "document.querySelector('h2').textContent"

手順

ページの上から下へ順に進めます。注釈ごとに、次の手順を実行してください。

1. eval（scrollIntoView）で対象の領域までスクロールします
2. 見出し、段落、ボタン、セクションコンテナーなど、具体的な要素を選びます
3. eval（getBoundingClientRect）でその要素のバウンディングボックスを取得します
4. 座標クリックの手順（mouse move → mouse down → mouse up）を実行します
5. スナップショットの全文を読み、末尾にあるダイアログの参照を確認します
6. 批評を入力し（fill @ref）、送信します（click @ref）
7. 注釈が追加されたことを確認します（下記参照）
8. 次の領域へ進みます

注釈の確認

注釈を送信するたびに、件数が増えたことを確認してください。

agent-browser eval "(document.querySelector('agentation-toolbar')?.shadowRoot || document).querySelectorAll('[data-annotation-marker]').length"
# Should return the expected count (1 after first, 2 after second, etc.)

件数が増えていない場合、送信が無言で失敗しています。スナップショットを再取得し、ダイアログが開いたままか確認してください。

特に指示がない限り、ページごとに5～8件の注釈を目指してください。

批評する項目

領域	確認する点
ヒーロー／ファーストビュー	見出しの階層、CTA の配置、視覚的なグループ分け
ナビゲーション	ラベルのスタイル、カテゴリーのグループ分け、視覚的な強弱
デモ／イラスト	分かりやすさ、奥行き、アニメーションの見やすさ
コンテンツセクション	余白のリズム、コールアウトの表現、タイポグラフィの階層
主要なタグライン	印象に残るフレーズが十分に視覚的な強調を受けているか
CTA とフッター	コンバージョンへの訴求力、視覚的な区切り、最後のアクション

批評のスタイル

注釈は最大2〜3文にします。

• 具体的で実行可能：「レイアウトを直す」ではなく、「インストールコマンドを小見出しの下に16pxで配置する」
• 具体的な代替案を1〜2個：CSSの値、レイアウトパターン、デザインシステムを挙げる
• 原則を明示する：視覚的階層、ゲシュタルトのグルーピング、余白、強調、コンバージョン設計
• 類似製品を参考にする：「Stripe／Linear／Vercelのこの部分の処理を参考にする」

悪い例：「このセクションは改善が必要です」 良い例：「この箇条書きはショーケースというよりドキュメントのように見えます。Stripeのガイドラインのパターンのように、アイコン付きの3列カードグリッドを使います。視覚的なリズムが生まれ、内容をすばやく把握しやすくなります。」

インストール

Claude Code がスキルを検出できるように、スキルを ~/.claude/skills/ にシンボリックリンクする必要があります。

ln -s "$(pwd)/skills/agentation-self-driving" ~/.claude/skills/agentation-self-driving

インストール後、Claude Code を再起動します。/agentation-self-driving を実行して確認してください。スキルの指示が読み込まれれば、シンボリックリンクは正しく機能しています。

トラブルシューティング

• 「ブラウザーが起動していません。まず launch を呼び出してください。」：前回の実行時の古いセッションが残っています。agent-browser close 2>/dev/null を実行してから、--headed open コマンドを再試行します
• ページにツールバーが見つからない：Agentation がインストールされていません。まず /agentation を実行してセットアップします
• クリックしてもダイアログが表示されない：ツールバーが折りたたまれています。状態を確認する eval（最初に [class*=expanded] を確認）で再展開してから、再試行します
• 対象の要素が間違っている：「キャンセル」をクリックし、目的の要素までスクロールして、正しい座標で再試行します
• 追加ボタンが無効のまま：テキストが入力されていません。スナップショットを再取得して、テキストボックスに入力します
• ページが移動した：「ページの操作をブロック」がオフになっています。ツールバーの設定から有効にします
• 注釈の数が増えない：送信に失敗しています。ダイアログがまだ開いている可能性があるため、スナップショットを再取得して確認します
• 実行の途中で中断した（Ctrl+C）：ブラウザーは中断時の状態のまま開いています。新しいセッションを開始する前に agent-browser close を実行して終了します

agent-browser の注意点

以下を知らないと、ワークフローがエラー表示なく中断されることがあります。

注意点	発生すること	対処法
scrollintoview @ref	クラッシュ：「CSSセレクターの解析中に、未対応のトークン @ref が見つかりました」	eval "document.querySelector('sel').scrollIntoView({block:'center'})" を使います
get box @ref	同様にクラッシュします。get box は ref を CSS セレクターとして解析します	eval "((r)=>r.x+','+r.y+','+r.width+','+r.height)(document.querySelector('sel').getBoundingClientRect())" を使います
二重感嘆符を含む eval	コマンドの実行前に、Bash が二重感嘆符を履歴置換します	代わりに expr !== null または expr ? true : false を使います
バックスラッシュでエスケープした引用符を含む eval	内側の引用符をエスケープすると、シェル間で問題が発生します	引用符を省略します。スペースを含まない単純な値なら [class*=toggleContent] を使えます
snapshot -i | head -50	注釈ダイアログの ref（textbox "What should change?"、Add、Cancel）はスナップショットの末尾に表示されます	スナップショットの出力は必ずすべて読み取ります。途中で切り詰めないでください
オーバーレイ要素に対する click @ref	クリックが Agentation オーバーレイを迂回し、実際の DOM に届きます	オーバーレイに認識される座標クリックを行うため、mouse move → mouse down left → mouse up left を使います
--headed open が「ブラウザーが起動していません」で失敗する	前回の実行時の古いセッションが新しい起動を妨げます	agent-browser close 2>/dev/null を実行してから、open コマンドを再試行します

覚えておくこと：@ref は操作コマンド（click、fill、type、hover）で使えます。それ以外（eval、get、scrollintoview）では、eval 内で querySelector を使って CSS セレクターを指定します。

2 セッションのワークフロー（完全自動運転）

MCP が接続されている場合（ツールバーに「MCP Connected」と表示）、注釈はリッスン中のエージェントに自動送信されます。これにより、次のことが可能になります。

• セッション 1（このスキル）：ページを確認し、表示中のブラウザーで批評の注釈を追加します
• セッション 2：agentation_watch_annotations をループで実行し、注釈を受け取り、それぞれに対応するコードを編集します

ユーザーがセッション 1 にブラウザー内のページを操作させる間に、セッション 2 がコードベースの問題を修正します。デザインレビューから実装まで、すべてが自律的に行われます。