reproduce

/reproduce — Issue の分析とバグの再現

GitHub Issue が有効で再現可能なバグかどうかを判断するソフトウェアエンジニアです。以下の手順に正確に従ってください。

Step 1: Issue を分類する

これが Bug、Feature Request、Question、Enhancement のいずれに該当するか判断します。

• Bug でない場合は、分類を報告して終了します。それ以上先に進まないでください。
• Issue に複数のバグが含まれている場合は、作業を進める前に開発者に Issue を分割するよう依頼してください。

Step 2: 環境をセットアップする

1. 製品の zip が利用可能な場合はそれを使用し、そうでない場合は該当するブランチから製品をビルドします。
2. 確認します：ポートが利用可能であること、製品が起動し、ヘルスチェックに合格すること。

セットアップに失敗した場合は、失敗を報告して終了します

Step 3: バグを再現する

この手順は必須です。実行中の製品で実際にバグを発生させてください。

「再現」とは、実行時にバグが起きるのを確認することです。ソースコードを読んだり、ロジックを分析したり、コンパイル済みの出力を grep したりすることではありません。Playwright のスクリーンショット、curl のレスポンス、または実行中のサーバーのログ出力を通して、実際の誤った動作を自分の目で確認していない場合、バグを再現したことにはなりません。再現済みとしてマークしないでください。

コードの調査は根本原因の分析（Step 5）には役立ちますが、再現ではありません。根本原因の分析を書く前に、この手順を完了してください。

再現方法

1. 製品サーバーを起動し、準備が整うまで待ちます。
2. Issue に記載された再現手順に従います（記載がない場合は、妥当な手順を推測します）。
3. フロントエンドの問題かバックエンドの問題かを判断します。
   • フロントエンドの問題（クリック、フォーム、ナビゲーションなどの UI 動作が関係する場合）：Playwright を使用して実際のブラウザーを操作します。verify-fix で再利用できるよう、スクリプトを .ai/reproduce-<issue_number>.mjs として保存します。Playwright のガイドについては CLAUDE.md を参照してください。
   • バックエンドの問題（REST API のレスポンス、サーバーエラーが関係する場合）：curl を使用して、実行中のサーバーに実際の HTTP リクエストを送信します。
4. 具体的な証拠を記録します。
   • フロントエンド：各重要な手順で、実際にバグが起きていることを示すスクリーンショット。
   • バックエンド：HTTP レスポンス全体（ステータスコード、ヘッダー、本文）とサーバーのエラーログ。
5. コードから読み取った内容ではなく、実際に観察した内容に基づいて、期待される動作と実際の動作を記録します。

再現の証拠として認められるもの

• 表示されるはずの UI 要素が非表示になっていることを示す Playwright のスクリーンショット
• HTTP 200 が返るはずのところで HTTP 500 が返っていることを示す curl のレスポンス
• 実際に送信した API 呼び出し中の例外を示すサーバーログ

再現の証拠として認められないもの

• 「コード分析でバグが確認できた」—これは再現ではありません
• 「ロジックを見ると enableDirectToken が復元されない」—これは分析であり、再現ではありません
• curl -sk -o /dev/null -w "%{http_code}" <url> が 200 を返す — これはページが読み込まれることを証明するだけで、バグの存在を示すものではありません REST API リファレンス： CLAUDE.md の REST API Reference セクションを参照してください

Step 4: 関連するテストを特定する

Issue に関連するユニットテストのカバレッジのみを分析します。

Step 5: 出力成果物を作成する

リポジトリのルートに .ai/ ディレクトリが存在しない場合は作成します。以下の正確な形式を使用して、分析結果を .ai/ia-<issue_number>.md に書き込みます。

# Issue Analysis — [Issue #ID]: [Issue Title]

## Classification
- **Type:** Bug / Not a Bug (with explanation)
- **Severity Assessment:** Critical / High / Medium / Low
- **Affected Component(s):** [component names]
- **Affected Feature(s):** [feature names]

## Reproducibility
- **Reproducible:** Yes / No (ONLY "Yes" if you triggered the bug at runtime and observed it. Code analysis alone = "No")
- **Reproduction method:** Playwright / curl / server logs (specify which)
- **Environment:** [branch, language/runtime version, OS, relevant config]
- **Steps Executed:**
  1. [step]
  2. [step]
- **Expected Behavior:** [what should happen]
- **Actual Behavior:** [what actually happened — describe what you OBSERVED, not what you read in code]
- **Evidence:** [screenshots in .ai/screenshots-<issue_number>/, curl output, or server log excerpts — MUST be from runtime, not code]

## Root Cause Analysis
Brief analysis of what is likely causing the bug based on reproduction results.

## Test Coverage Assessment
- **Existing tests covering this path:** [list test files/functions]
- **Coverage gaps identified:** [paths with no tests]
- **Proposed test plan:**
  - Unit test: [description]
  - Negative/edge cases: [description]

Step 6: クリーンアップ

• 一時的な設定やデータの変更を元に戻します。
• 作業ツリーがクリーンであることを確認します。

重要なルール

• 推測しないでください。 利用可能なドキュメントから解決できない曖昧さがある場合は、作業を中断して開発者に確認してください。
• 記憶より成果物を優先します。 出力成果物は、別のエージェントが作業を引き継げるだけの十分な内容を含めてください。
• サーバーの起動： 起動コマンドとログのポーリングループは、timeout: 200000 を指定した同じ Bash ツール呼び出し内に含める必要があります。別々の呼び出しに分けないでください。
• Playwright のベストプラクティス： 固定時間のスリープではなく、要素が現れるまで待機してください（page.waitForSelector()、page.locator().waitFor()）。アサーションの内容は明確にログに出力し、成果物で役立つように期待値と実際の値を表示してください。