debugging

デバッグ

具体的な失敗を範囲を限定した診断ループに落とし込むことが目的の場合に、このスキルを使用します。

このスキルの中心となる手順は、小さく、繰り返し実行できます。

1. 失敗する挙動をテスト可能な形で定義します。
2. 最も手軽で信頼性の高い再現手順を作成するか、確認します。
3. 失敗が起きる境界を可能な限り絞り込みます。
4. 仮説ごとに、その仮説を判別できるチェックを1つ実行します。
5. 同じ条件下で修正を検証します。

log-analysis、testing-strategies、code-review、performance-optimization の担当範囲に該当する可能性がある作業に着手する前に、references/handoff-boundaries.md をお読みください。 実験ループの詳細な手順については、references/debug-loop.md をお読みください。 明らかな回帰、不安定な失敗、環境／設定の不一致、または成果物を手がかりとする調査の場合は、references/mode-selection-and-fast-checks.md をお読みください。

このスキルを使用する場面

• コマンド、テスト、リクエスト、UI フローが失敗しており、ユーザーが根本原因を突き止めるワークフローを必要としている
• バグを再現できるか、ほぼ再現できており、修正前に原因を絞り込む必要がある
• 回帰の可能性があり、該当する変更期間または最後に正常だった状態が分かっている
• 不安定な失敗について、特定の事例に絞ったうえで、繰り返し実行による根拠の収集、分離、安定化が必要である
• CI／ステージング／本番環境のみで発生する挙動について、環境や設定の違いを比較できるだけの情報が集まっている
• バグの再現、切り分け、二分探索、確認、または修正の検証方法をユーザーが尋ねている

このスキルを使用しない場面

• ユーザーがログ／スタックトレースしか持っておらず、まだ最初の対処可能な失敗を特定できていない → まず log-analysis を使用します
• 本来の作業が、テストプログラムの設計、不安定なテストの方針、またはカバレッジ計画である → testing-strategies を使用します
• 作業が、正確性、リスク、根拠不足の観点から差分／PR をレビューすることである → code-review を使用します
• 主な作業が、テレメトリーの展開、ダッシュボード、または可観測性プラットフォームの設計である → monitoring-observability を使用します
• 主な作業が、ボトルネックの測定と最適化のトレードオフの検討である → performance-optimization を使用します

手順

ステップ 1：失敗の定義を固定する

再テストできる形で失敗を記述します。

以下を記録します。

• 期待される挙動
• 実際の挙動
• 正確なトリガー、入力、または状態
• 環境：ローカル／CI／ステージング／本番／ブラウザー／モバイル／ランタイム
• 再現性があるか、不安定か、不明か
• 回帰の可能性がある場合は、最後に正常だった状態

最低限の形式：

Expected: ...
Actual: ...
Trigger: ...
Environment: ...
Confidence: high | medium | low

報告が「何かが失敗した」という内容にとどまり、膨大なログがあるだけで症状が絞り込まれていない場合は、まず log-analysis に引き継ぎます。

ステップ 2：最初に確認する根拠を選ぶ

次の仮説を否定または確認できる、最も手軽な方法を選びます。

次の振り分けを目安にしてください。

• 失敗することが分かっているコマンド／テスト／リクエスト／UI フロー → そのまま再現します
• 最後に正常だった状態が分かっている回帰 → 最近の変更を比較し、git bisect の使用を検討します
• 不安定／断続的な失敗 → まず繰り返し実行して発生頻度を測定します
• CI／ステージング／本番環境のみで発生 → コードについて推測する前に、環境／設定／ランタイムの情報を比較します
• 成果物を手がかりとする事例 → 最初の意味のあるログ／トレース／スクリーンショットを調べ、疑わしい境界を1つに絞り込みます
• パフォーマンスのみの問題 → 具体的な不具合の診断がまだ必要な場合を除き、performance-optimization に引き継ぎます

ステップ 3：最小限で信頼性の高い再現手順を作る

失敗を再現できる範囲で、最も手軽な方法を優先します。

よくある形式：

• 1つの CLI コマンド
• 1つの HTTP リクエストまたは API 呼び出し
• 正確な手順を示した1つの UI フロー
• 1つの失敗するテストまたはフィクスチャ
• 1つのセーブファイル／シード／ペイロード／設定の組み合わせ
• 回帰を調査するための1つのコミット範囲

役立つ方法：

• 関係のないセットアップを減らします
• 可能であれば、時刻／乱数／ネットワークを固定します
• 異なる環境／設定の値を正確に記録します
• 繰り返し実行のループは、疑わしい対象を1つに絞ります

ステップ 4：修正を提案する前に境界を切り分ける

まず問題の範囲を絞ります。

切り分けの観点：

1. 境界 — UI と API、DB、ワーカー、設定、依存関係、アセット／ランタイムのどこか
2. 入力 — 1 つのペイロード、レコード、シード、シーン、またはフィクスチャ
3. 履歴 — 正常な状態から問題がある状態になるまでに何が変わったか
4. 環境 — ローカル、CI、ステージング、本番のどこか
5. タイミング — 順序、リトライ、キャッシュ、クロック、非同期の待機、共有状態

優先度の高い質問：

• 主な疑いの対象として、特定のファイル／モジュール／設定分岐を挙げられますか？
• 問題は、データの形状、状態遷移、設定のずれ、依存関係の挙動、コードパスのどれに関するものですか？
• 現在のボトルネックはまだ診断ですか？それとも、レビュー／テスト方針／最適化の作業に移っていますか？

ステップ 5：仮説ごとに識別力のあるチェックを 1 つ実行する

5 つのことを一度に修正しないでください。

仮説ごとに：

• その仮説が問題を説明できる理由を述べます
• まず読み取り専用または元に戻せるチェックを 1 つ実行します
• 結果を記録します
• 根拠に基づいて仮説を維持するか棄却します

最初に行うとよいチェック：

• 絞り込んだ境界でリクエスト／ペイロード／設定を調べる
• 正常な状態と問題のある状態を 1 つずつ比較する
• スイート全体ではなく、対象を絞ったテストを 1 つ再実行する
• 疑わしいコミット範囲の差分を確認する
• 絞り込んだ境界にだけ、一時的な計測を追加する

ステップ 6：適切なモードパケットを使う

ケースの種類が明確になったら、references/mode-selection-and-fast-checks.md の対応するパケットに従います：

• リグレッションデバッグ
• 不安定な失敗のデバッグ
• 環境／設定不一致のデバッグ
• ログ／トレース／スクリーンショットのトリアージ後の、アーティファクトに基づくデバッグ
• ランタイム／ブラウザー／ゲームループのデバッグ

ステップ 7：原因を修正し、その後で実証する

適切なデバッグ結果では、症状を抑えるだけでなく、原因に対処したことを示します。

検証チェックリスト：

• 再現手順が成功する
• 近接するエッジケースも引き続き正しく動作する
• 実用的であれば、リグレッションを防ぐ仕組みがある
• 説明が観測された問題と一致する
• 修正の範囲が、調査を始めた時点の探索範囲より小さい

ステップ 8：根拠がまだ弱い場合は、正直にエスカレーションする

再現または切り分けにまだ失敗する場合：

1. 確信度が低いと伝えます。
2. 不足している最小限のアーティファクトだけを求めます。
3. 根本原因が分かっているかのように装いません。
4. 推測でパッチを当てるより、識別力のあるチェックをもう 1 つ行います。

出力形式

必ず簡潔なデバッグ概要またはデバッグ計画を返します。

# Debugging Brief

## Failure definition
- Expected: ...
- Actual: ...
- Reproducer: ...
- Confidence: high | medium | low

## Isolation result
- Narrowed boundary: ...
- Recent change / env difference / artifact clue: ...

## Hypotheses and checks
1. Hypothesis: ...
   - Check: ...
   - Result: ...

## Likely root cause
- 1-3 sentences grounded in evidence

## Fix direction
1. ...
2. ...

## Verification
- Reproducer rerun: ...
- Regression guard: ...

## Handoff
- Stay in `debugging` | route to `diagnosing-bugs` (hard/flaky bug needing a HITL feedback loop) | route to `log-analysis` | route to `testing-strategies` | route to `code-review` | route to `performance-optimization`

例

例 1：リファクタリング後のリグレッション

入力

新しいアバターをアップロードせずにプロフィールを保存すると、既存のアバターが消えるようになりました。リファクタリング前は問題ありませんでした。

出力の概要

• 1 回の再現可能なフォーム送信で、期待される動作と実際の動作を定義する
• リファクタリング前後の更新パスを比較する
• フィールドがない場合と明示的な null が同じように扱われていないか確認する
• 集中的なリグレッションテストと、元のフローの再実行で検証する

例 2：不安定な CI の失敗

入力

このチェックアウトのテストはローカルでは成功しますが、CI では 8 回に 1 回ほど失敗します。

出力の概要

• 決定的な失敗ではなく、不安定なケースとして扱う
• 繰り返し実行するループを回し、タイミング／共有状態／環境の違いを比較する
• まず失敗するテストと近接するフィクスチャだけを調べる
• ジョブがスイート全体の不安定なテストに関する方針の話に広がる場合に限り、testing-strategies に誘導する

例 3：アーティファクトの手掛かりがある、本番環境限定の動作

入力

このジョブはステージングでのみ失敗します。最初に失敗したリクエストのペイロードと、設定の差分があります。

出力の概要

• 環境／設定不一致のデバッグとして扱う
• コードにパッチを当てる前に、ステージングとローカル／ランタイムの事実を比較する
• 動作を変える 1 つのフラグ／バージョン／シークレットの分岐に絞り込む
• 修正後の設定で同じペイロードを使って検証する

例 4：症状だけのログ出力

入力

リトライとスタックトレースが 500 行あります。デバッグできますか？

出力の概要

• まず log-analysis に誘導する
• 最初に対処可能な失敗について、まだ絞り込みが必要だと伝える
• 根本原因の調査を始められるかのように装わない

ベストプラクティス

1. パッチを適用する前に再現する — 実証されていない修正は推測にすぎません。
2. まず最も低コストの証拠を使う — 直接の再現、繰り返し実行、環境の差分、または成果物の手掛かりを確認します。
3. モード選択を明確にする — 回帰、不安定なテスト、環境／設定、成果物起点、ランタイムの各ケースでは、最初に確認すべき項目が異なります。
4. 症状のトリアージと診断を分ける — ログは調査の出発点にはなりますが、結論ではありません。
5. 一度に一つだけ変更する — デバッグは実験を繰り返すプロセスです。
6. 検証して終える — 原因をどのように確認したか、すべての結果に記載します。

参考資料

• Visual Studio Code：デバッグ
• Playwright：テストのデバッグ
• GitHub Docs：デバッグログを有効にする
• Git：git-bisect のドキュメント
• Google Testing Blog：Google における不安定なテストとその対策