code-debug-skill

バグ調査スキル

調査の考え方（どのように考えるか）

• 事実を最優先します。常に観察結果と推論を分けてください。
• 複数の競合する仮説を維持し、可能性と影響度に基づいて順位付けしてください。
• 仮説ごとに、次の項目を定義します。
  • 予測（仮説が正しい場合に観察されるはずのこと）
  • 反証条件（仮説を否定するもの）
  • 必要な計測（測定またはログ記録するもの）
• 説明よりも決定的なシグナルを優先します。証拠を捉える計画なしに再現を求めないでください。
• 可能な場合は比較（失敗対成功）と二分探索型のアプローチで絞り込んでください。
• 1回の再現で決定的なシグナルを捉えられるよう、デバッグ計測を十分に追加してください。
  • 再現にはコストがかかると想定し、追加の再現を必要とせずに根本原因を絞り込めるだけの計測を行ってください。
• 推測でコードを修正しないでください。本番コードを変更する前に、証拠をもって根本原因を確認してください。

ツールの選択（何を使うか）

• 新たな計測には、ローカル HTTP 取り込みロガー（debugsk）を主に使用します。
  • AI は計測を追加する前に、npx debugsk@latest server start --json で必ずサーバーを起動してください。
  • JSON 出力を使ってスニペットとエンドポイントをコピーしてください。
  • サーバーは CORS プリフライト（OPTIONS）を受け付けるため、デフォルトの JSON スニペットはオリジンをまたいで動作します。
• AI は sessionId/runId を自動生成し、計測コードに直接埋め込む必要があります。
  • ユーザーにコンソールからこれらを設定するよう求めないでください。
• 再現可能な場合は、予測を直接検証するログ／メトリクスを優先してください。
• 再現できない場合は、既存のシグナルに切り替えてください。
  • ログ／メトリクス／トレース、設定の差分、データのスナップショット、ダンプ、決定論的なプローブを使用します。
• ネイティブのシグナルで疑問を解決できない場合は、新たな観察には debugsk を優先してください。
  • これにより、ネイティブのログへの混入を避け、調査ログを分離できます。
• 新たな計測に加えて、参照用にネイティブのログも使用してください。

運用原則

• 事実（観察されたもの）と仮説（推論されたもの）を分けてください。
• 証拠によって排除されるまで、複数の競合する仮説を維持してください。
• 仮説ごとに、予測、反証条件、必要な計測を定義してください。
• **AI は自動化可能なタスクをすべて実行します。**サーバーの起動、ID の生成、ログの収集、分析が含まれます。
• ユーザーが行うのは、自動化できない UI 操作（クリック、フォーム入力など）のみです。
• 計測計画の準備が整うまで、再現を求めないでください。

基本的な手順

1. バグを正確に明らかにします。
   • 環境（ローカル／ステージング／本番）、バージョン／コミット、発生頻度、影響。
   • 最小限の再現手順、期待される動作と実際の動作、エラーとタイムスタンプ。
2. 該当するコードパスを特定します。
   • エンドポイント／ルート／機能／設定キー／エラーテキストで検索します。
   • リクエスト → ハンドラー → データ／依存関係の流れをマッピングします。
3. 少なくとも3つの仮説を立てます。
   • クライアント／入力、サーバーロジック、データ／状態、並行処理、設定、依存関係、リソース。
4. デバッグサーバーを起動して ID を生成します。
   • npx debugsk@latest server start --json を実行してエンドポイントを取得します。
   • sessionId/runId を自動生成し、計測コードに埋め込みます。
5. 仮説を検証するために計測します。
   • 判断箇所と境界にログ／メトリクスを追加します。
   • 自動生成した相関キーを含めます（ユーザーの操作は不要です）。
6. 制御された再現を実行します。
   • 必要であれば、AI がサーバーを起動します。
   • ユーザーには UI 操作の手順のみを伝えます（クリック、ドラッグ、送信など）。
   • コンソールコマンドは禁止、ファイル操作も禁止です。
7. ログを収集して分析します。
   • AI は Read/Grep ツールを使用してログファイルを直接読み取ります。
   • 成功した実行と失敗した実行を比較します。
   • 可能な場合は二分探索型の絞り込みを優先します。
8. 根本原因が確認されるまで反復します。

計装ポリシー

• 利用可能な場合は、ローカルの HTTP インジェストロガーを優先してください。それ以外の場合は、既存のロギングと統合してください。
• ネイティブシグナルが不十分な場合は、ネイティブログを追加するよりも debugsk を優先してください。
• 追加した計装と併せて、ネイティブログを参照してください。
• ログは決して例外を発生させず、秘密情報や個人を特定できる情報を含めず、簡単に削除できるようにしてください。
• すべてのイベントに、場所、メッセージ、タイムスタンプ、相関フィールドを記録してください。
• すべてのログイベントに、すべてのログフィールド（timestamp、message、sessionId、runId、hypothesisId、location）を必ず含めてください。フィールドを省略してはいけません。
• 環境フラグで計装を有効・無効にしないでください。調査中はログを記録し、完了後に削除してください。
• AI がデバッグサーバーを起動し、ID を生成して計装を挿入し、ログを収集・分析します。
• ユーザーが行うのは UI 操作（クリック、フォーム入力など）のみです。コンソールコマンドやファイル操作は行いません。

ユーザー操作のルール

• ユーザーの負担を最小限に抑えてください。 自動化可能な作業はすべて AI が行います。
  • デバッグサーバーの起動・停止
  • sessionId/runId の生成と埋め込み
  • ログファイルの読み取りと分析
  • トンネリングが必要かどうかの判断（環境を調査し、質問しない）
• ユーザーが行うのは自動化できない UI 操作のみです。
  • ボタンのクリック、要素のドラッグ、フォームへの入力
  • 画面間の移動
  • 目に見える動作の確認
• 再現が必要な場合は、UI の手順のみを提示してください。コンソールコマンドやファイル操作は提示しないでください。
• 再現できない場合は、既存のログ、メトリクス、トレース、設定差分、または安全なプローブを活用してください。
• 外部やモバイルからのアクセスでは、環境を調査して AI がトンネリングの必要性を判断します。
  • リモート環境やステージング環境の場合は、既存のトンネルを確認するか、具体的な設定方法を提案してください。
  • 「トンネルを使いますか？」のような、自由回答形式の質問はしないでください。

クリーンアップポリシー

• ユーザーが問題の解決または調査の終了を確認したら、デバッグサーバーを停止し、すべての調査ログ（例：.logs/）を削除してください。
• ログの削除に git checkout、git clean、またはその他の一括 Git クリーンアップを使用しないでください。ファイルを明示的かつ安全に削除してください。
• 削除によって無関係なファイルに影響する可能性がある場合は、削除前に対象のパスを正確に確認してください。

報告形式

assets/report-template.md のテンプレートを使用してください。見出しは英語／日本語の併記とし、本文はユーザーの言語で記述してください。

参考資料

• 計装の追加または検証には references/logging-schema.md を使用してください。
• 仮説と予測の整理には references/hypothesis-template.md を使用してください。