agent-browser-debug

デバッグ診断 — 実行プロトコル

内部テンプレート。 エントリーポイント：agent-browser スキル。

---

絶対にしないこと

NEVER jump to DOM inspection before checking `errors` — JS errors explain 80% of broken UIs
NEVER assume auth is fine — check `cookies` + `storage local` first when login suspected
NEVER think `inspect` kills CLI — DevTools and CLI work simultaneously

---

トリアージ手順（順番に実行し、最初に問題が見つかった時点で停止）

agent-browser --headed open <url>
agent-browser wait --load networkidle

# Step 1: JS errors (explains 80% of broken UIs)
agent-browser errors

# Step 2: Console warnings
agent-browser console --pattern "error|warn"

# Step 3: Failed network requests — filter to relevant calls
agent-browser network requests --filter "api"
agent-browser network requests --type xhr,fetch --status 4xx   # 4xx only
agent-browser network requests --method POST --status 5xx      # failed writes

# Step 4: Inspect full request/response body of a failed request
agent-browser network request <requestId>   # get requestId from step 3

# Step 5: Auth state (check first if login/session suspected)
agent-browser cookies         # token cookie present?
agent-browser storage local   # JWT in localStorage?

# Step 6: DOM state
agent-browser snapshot -i
agent-browser is enabled @e5
agent-browser is visible @e3

# Step 7: Form validity (if button appears enabled but won't submit)
agent-browser eval "document.querySelector('form').checkValidity()"

# Step 8: Deep investigation
agent-browser inspect         # DevTools (CLI stays live)

---

継続的な証拠を残すためのネットワーク HAR

# Record full network trace (start BEFORE navigation)
agent-browser network har start ./debug-trace.har
agent-browser open <url>
agent-browser wait --load networkidle
# ... reproduce the issue ...
agent-browser network har stop
# Open debug-trace.har in browser DevTools → Network → Import

---

復旧パターン

症状	次のアクション
JS エラーが見つかった	エラーを報告 → 判断ゲート：続行するか停止するか
認証トークンが見つからない	認証フローを再実行し、cookies を再確認
ネットワーク 4xx/5xx	network request <id> で本文全体を確認 → 報告 → 判断ゲート
is enabled が false	eval でフォームの有効性を確認
ヘッドレスでは問題を再現できない	視覚的に確認するため、--headed を付けて実行

---

判断ゲート

次の場合は一時停止します。

• JS エラーが見つかった（ユーザーに提示し、バグか既知の問題かを確認します）
• 認証トークンが見つからない（認証情報なしでは自動復旧が困難です）
• API が予期しないエラーを返す（次の手順をユーザーが決める必要があります）
• network request <id> でレスポンス内に機密データが見つかった（記録せず、ユーザーに確認します）

---

注意点

誤り	修正方法
errors をスキップして DOM に進む	エラーで問題の 80% は説明できます — 必ず最初に確認します
認証の問題から JS デバッグに進む	まず cookies と storage local を確認します
inspect が CLI を終了させると思い込む	終了しません — 両方を同時に使用できます
URL だけで network requests を絞り込む	絞り込むには --status 4xx または --method POST も指定します
リクエスト本文を見落とす	ペイロード全体を確認するには network request <requestId> を使用します