reproduce-bug

バグの再現

Issue の報告からバグを再現して調査するための、フレームワークに依存しない、仮説に基づくワークフローです。あらゆる言語、フレームワーク、プロジェクトタイプで動作します。

フェーズ 1：Issue を理解する

コードベースに手を加える前に、バグ報告を取得して分析し、構造化された情報を抽出します。

Issue を取得する

引数として Issue 番号または URL が指定されていない場合は、先にユーザーへ確認してから進めます（プラットフォームの質問ツールを使用します。例：Claude Code の AskUserQuestion、Codex の request_user_input、Gemini の ask_user。または質問を提示して、返信を待ちます）。

gh issue view $ARGUMENTS --json title,body,comments,labels,assignees

引数が番号ではなく URL の場合は、Issue 番号を抽出するか、URL を gh に直接渡します。

重要な詳細を抽出する

Issue とコメントを読み、次の内容を特定します。

• 報告された症状 -- ユーザーが確認した内容（エラーメッセージ、誤った出力、表示上の不具合、クラッシュ）
• 期待される動作 -- 本来どのような動作になるべきだったか
• 再現手順 -- 報告者が提示した手順
• 環境に関する手がかり -- ブラウザー、OS、バージョン、ユーザーの役割、データの条件
• 発生頻度 -- 常に再現するか、断続的に発生するか、1 回限りか

Issue に再現手順がない場合や内容が曖昧な場合は、不足している情報を記録します。これは調査方針を決めるうえで役立ちます。

フェーズ 2：仮説を立てる

何かを実行する前に、根本原因について仮説を立てます。これにより調査に焦点を合わせ、目的のない探索を防げます。

関連するコードを検索する

ネイティブのコンテンツ検索ツール（例：Claude Code の Grep）を使い、報告された症状に関連するコードパスを見つけます。次の内容を検索します。

• Issue に記載されたエラーメッセージや文字列
• 報告で説明されている機能名、ルートパス、UI ラベル
• 関連するモデル／サービス／コントローラー名

仮説を立てる

Issue の詳細とコード検索の結果に基づいて、妥当な仮説を 2～3 個書き出します。それぞれ、次の内容を特定します。

• 何が問題の可能性があるか（例：「セッション更新時の競合状態」「オプションのフィールドに nil チェックがない」）
• コードベースのどこで起きているか（具体的なファイルと行の範囲）
• なぜ報告された症状が発生するのか

可能性の高い順に仮説を並べます。まず、最も可能性の高いものから調査します。

フェーズ 3：再現する

バグの発生を試みます。再現方法はバグの種類によって異なります。

ルート A：テストによる再現（バックエンド、ロジック、データのバグ）

疑わしいコードパスを実行するテストを作成するか、既存のテストを見つけます。

1. ネイティブのファイル検索ツール（例：Claude Code の Glob）を使って、影響を受けるコードを対象とする既存のテストファイルを検索します
2. 既存のテストを実行し、すでに失敗するものがあるか確認します
3. そのシナリオを対象とするテストがない場合は、報告された動作を示す最小限の失敗するテストを作成します
4. 報告された症状と一致するテストの失敗によって、バグが確認できます

ルート B：ブラウザーによる再現（UI、表示、操作のバグ）

ブラウザー自動化には agent-browser CLI を使います。代替のブラウザー MCP 連携や組み込みのブラウザー操作ツールは使用しないでください。セットアップと CLI の詳しい使い方については、agent-browser スキルを参照してください。

サーバーが実行中か確認する

agent-browser open http://localhost:${PORT:-3000}
agent-browser snapshot -i

サーバーが実行されていない場合は、開発サーバーを起動し、正しいポート番号を知らせるようユーザーに依頼します。

正しいポートを特定するには、まずプロジェクトの指示ファイル（AGENTS.md、CLAUDE.md）でポートの記載を確認し、次に package.json の dev スクリプト、続いて .env ファイルを確認します。見つからない場合は 3000 を使用します。

再現手順を実行する

Issue の影響を受けている箇所に移動し、Issue の手順を実行します。

agent-browser open "http://localhost:${PORT}/[affected_route]"
agent-browser snapshot -i

ページを操作するには、agent-browser コマンドを使います。

• agent-browser click @ref -- 要素をクリックします
• agent-browser fill @ref "text" -- フォームフィールドに入力します
• agent-browser snapshot -i -- 現在の状態をキャプチャします
• agent-browser screenshot bug-evidence.png -- 視覚的な証拠を保存します

バグの状態を記録する

バグを再現できたら、次の操作を行います。

1. エラーが発生している状態のスクリーンショットを撮ります
2. コンソールエラーを確認します。ブラウザーの出力と、表示されているエラーメッセージを確認してください
3. バグを引き起こした手順を正確に記録します

ルート C：手動または環境固有の再現

特定のデータ条件、ユーザーロール、外部サービスの状態が必要なバグや、自動化できないバグの場合：

1. 必要な条件を記録します
2. ユーザーに、（プラットフォームの質問ツールを使ってください。たとえば、Claude Code では AskUserQuestion、Codex では request_user_input、Gemini では ask_user を使うか、選択肢を提示して返答を待ちます）必要な条件を整えられるか尋ねます
3. 必要に応じて、手動での再現手順を案内します

再現できない場合

可能性の高い仮説を試してもバグを再現できない場合：

1. 残っている仮説を再検討します
2. バグが環境固有かどうか（バージョン、OS、ブラウザー、データ依存）を確認します
3. 影響を受ける領域の最近の変更をコードベースで検索します：git log --oneline -20 -- [affected_files]
4. 試したことと、不足している可能性のある条件を記録します

フェーズ 4：調査する

プロジェクトが提供するあらゆる可観測性を活用して、根本原因をさらに詳しく調べます。

ログとトレースを確認する

再現時刻の前後に、エラー、警告、予期しない動作がないか検索します。確認する内容は、バグの種類やプロジェクトで利用できるものによって異なります。

• アプリケーションログ -- ネイティブのコンテンツ検索ツールを使って、ローカルのログ出力（開発サーバーの標準出力、ログファイル）から、エラーパターン、スタックトレース、警告を検索します
• エラー追跡 -- プロジェクトのエラー追跡ツール（Sentry、AppSignal、Bugsnag、Datadog など）で、関連する例外を確認します
• ブラウザーコンソール -- UI のバグでは、開発者コンソールの出力を確認し、JavaScript エラー、ネットワークリクエストの失敗、CORS の問題を探します
• データベースの状態 -- バグがデータに関係する場合は、関連するレコードを調べ、予期しない値、関連付けの欠落、制約違反がないか確認します
• リクエスト／レスポンスのサイクル -- 特定のリクエストについて、ステータスコード、パラメーター、タイミング、ミドルウェアの動作をサーバーログで確認します

コードパスを追跡する

フェーズ 2 で特定したエントリーポイントから、実行パスを追跡します。

1. ネイティブのファイル読み取りツールを使って、関連するソースファイルを読みます
2. 動作が期待から逸脱する箇所を特定します
3. エッジケースを確認します。nil／null 値、空のコレクション、境界条件、競合状態などが該当します
4. バグの原因となった可能性のある最近の変更を探します：git log --oneline -10 -- [file]

フェーズ 5：調査結果を記録する

調査で判明した内容をすべて要約します。

レポートをまとめる

調査結果を次の項目に整理します。

1. 根本原因 -- 実際の問題とその箇所（ファイルパスと行番号を記載します。例：app/services/example_service.rb:42）
2. 再現手順 -- バグを引き起こすことを確認した手順（確認済みか未確認かを明記します）
3. 証拠 -- スクリーンショット、テスト出力、ログの抜粋、コンソールエラー
4. 修正案 -- 修正方法が明らかな場合は、必要なコード変更を具体的に説明します
5. 未解決の質問 -- まだ不明な点や、さらなる調査が必要な点

外部への操作を行う前にユーザーに提示する

レポート全体をユーザーに提示します。明示的な確認を得るまでは、GitHub の Issue にコメントを投稿したり、外部への操作を行ったりしないでください。

ユーザーに尋ねます（プラットフォームの質問ツールを使うか、選択肢を提示して返答を待ちます）。

Investigation complete. How to proceed?

1. Post findings to the issue as a comment
2. Start working on a fix
3. Just review the findings (no external action)

ユーザーが Issue への投稿を選択した場合：

gh issue comment $ARGUMENTS --body "$(cat <<'EOF'
## Bug Investigation

**Root Cause:** [summary]

**Reproduction Steps (verified):**
1. [step]
2. [step]

**Relevant Code:** [file:line references]

**Suggested Fix:** [description if applicable]
EOF
)"