debug-error

デバッグエラースキル

自由度：混合。 根本原因の判断［自由度：高］、赤のフィードバックループとグリーン確認の再実行［自由度：低 — 指示どおりに実行］。

エラーや予期しない動作を体系的にデバッグする方法です。あらゆるプロジェクトで使用できます。

推論方法

1. 観察 — 正確な症状、スタック、環境、最初に発生した時期
2. 解釈 — クラッシュ箇所と発生元を区別する。FE／BE／統合／データ
3. 分類 — null アクセス／コントラクト／環境／競合状態／不明
4. 重大度 — 本番環境全体の認証障害は、単一ユーザーのエッジケースより優先度が高い

例

観察： サインアップ後、/account で TypeError: Cannot read property 'email' of undefined が発生します。 解釈： プロフィールカードでクラッシュしています。API はオンボーディングが未完了の場合に null を返します。 分類： データの不具合です。発生元は null を返し、利用側はオブジェクトを前提としています。 修正： 発生元のコントラクトと UI の空状態でオンボーディング未完了の null を処理します。クラッシュ箇所に ?. を追加するだけでは不十分です。

報告前のセルフチェック

• まず赤のループ — 仮説を立てる前に、失敗するコマンドを実行した
• 症状ではなく根本原因 — ?. や catch の握りつぶしだけを修正にしていない
• グリーンのループ — 同じコマンドを再実行し、成功した
• 適切な担当先 — FE↔BE の不整合 → debug-fe-be-integration、Sentry のバックログ → debug-sentry-monitor

デバッグ前の確認

デバッグを始める前に：

1. 関連ドキュメントを読む

README.md (project overview)
src/[domain]/@_[domain]-README.md (domain-specific behavior)
docs/ (system documentation)

2. Sentry のコンテキストを確認する（本番環境のエラーの場合）

エラーが本番環境で発生し、Sentry が設定されている場合は、完全なコンテキストを取得します。

sentry:search_issues
{
 "organizationSlug": "<ORG_SLUG>",
 "query": "<error message or description>",
 "projectSlugOrId": "<PROJECT_SLUG>",
 "regionUrl": "<REGION_URL>",
 "limit": 5
}

次に、一致する Issue の詳細を取得します。

sentry:get_sentry_resource
{
 "organizationSlug": "<ORG_SLUG>",
 "resourceType": "issue",
 "resourceId": "<ISSUE_ID>"
}

抽出する情報：スタックトレース、パンくず、タグ（ブラウザー、OS、URL、リリース）、イベントの発生頻度。

3. データベースの状態を確認する（データ関連の場合）

データが関係する場合は、Supabase MCP または直接クエリを使用して、想定と実際の状態を照合します。

4. 検証内容の明示 — 読んだ情報と取得した情報に基づいて診断するため

デバッグに入る前に、次のように明示します。

"Pre-debug check:
- README/docs read: [list]
- Sentry context: [YES with details / NO — not production / not configured]
- Database state verified: [YES/NO — findings]
- Backend API checked: [YES/NO — status]
- Error scope identified: [FE only / BE only / Integration / Data]"

---

デバッグプロセス

1. Reproduce → 2. Isolate → 3. Research → 4. Identify → 5. Fix → 6. Verify → 7. Prevent

---

フェーズ 1：再現する

まず、短いフィードバックループを作る

これがこのスキルの要点です。それ以降はすべて機械的な作業です。 仮説を立てるためにコードを読む前に、このバグで失敗し、修正後に成功するコマンドを 1 つ作成します（mattpocock/skills、MIT を参考にしています）。優先順位の目安は、最も近い境界で失敗するテスト → 開発サーバーに対する curl／HTTP スクリプト → フィクスチャ入力を使った CLI 呼び出し → ヘッドレスブラウザースクリプト → キャプチャしたトレース／ペイロードをコードパスに単独で再生、の順です。

次の条件を満たしたら、ループは完成です。

• 失敗を検知できる — 「エラーなしで実行される」ではなく、ユーザーの正確な症状を検証する
• 決定論的である — 実行のたびに同じ判定になる（不安定なバグの場合は、デバッグ可能になるまでトリガーを繰り返して再現率を高める）
• 高速である — 数秒で終わり、数分かからない
• 一度は実行済みである — コマンドと失敗時の出力をそのまま貼り付けられる

このコマンドができる前に仮説を立てていることに気づいたら、作業を止めてください。それこそが、このフェーズで防ぐべき失敗です。どうしてもループを作れない場合は、その旨を明記し、試したことを列挙して、手探りで進める代わりにキャプチャした成果物（HAR、ログダンプ、録画）を依頼してください。

情報を収集する

Error Report:
- What happened: [description]
- Expected behavior: [what should happen]
- Steps to reproduce:
 1. [step]
 2. [step]
- Environment: [browser/OS/Node version]
- Error message: [exact message]
- Stack trace: [if available]
- First seen: [when — correlate with deploys]

範囲を特定するための質問

• 毎回、一貫して再現できますか？
• いつから発生していますか？（最近の変更について git log を確認してください）
• すべてのユーザーで発生しますか、それとも特定のユーザーだけですか？（Sentry のタグ分布を確認してください）
• 環境に依存しますか？（開発環境、ステージング環境、本番環境）

---

フェーズ 2：切り分ける

問題を絞り込む

Works in: Fails in:
├─ Production? ├─ Production?
├─ Staging? ├─ Staging?
├─ Local? ├─ Local?
├─ All browsers? ├─ Specific browser?
├─ All users? ├─ Specific user?
└─ All data? └─ Specific data?

データフローを追跡する

データ関連のバグでは、パイプライン全体を追跡します。

User Action → Frontend Handler → API Call → Backend Controller → Database → Response → State Update → Render

各境界を確認して、データの不整合が発生している箇所を特定します。

再現ケースを最小化する

フィードバックループが失敗したら、失敗を再現できる最小のシナリオまで縮小します。入力、呼び出し元、設定、データを一つずつ削除し、そのたびにループを再実行します。残っている要素がすべて必要不可欠になったら完了です。どれか一つを取り除くと、ループが成功します。最小の再現ケースは仮説の範囲を絞り込み、フェーズ 6 で回帰テストになります。

---

フェーズ 3：修正前にエラーパターンを調査する

複雑なエラーの場合は、実装する前に正しい修正方法を調査します。フレームワークやエラーを認識しているだけでは、現在の動作を把握したことにはなりません。修正方法を知っているつもりでも、正確なエラーメッセージを検索し、最新のドキュメントを読みます。

firecrawl:firecrawl_search
{
 "query": "<framework> <exact error message> fix best practice",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

次に、最も関連性の高い結果をスクレイピングします。

firecrawl:firecrawl_scrape
{
 "url": "<best-result-url>",
 "formats": ["markdown"],
 "onlyMainContent": true
}

エラーがライブラリに関係する場合は、Context7 を使って公式ドキュメントも確認します。

context7:resolve-library-id
{
 "libraryName": "<library>",
 "query": "<error description>"
}

信頼性の優先順位：公式ドキュメント ＞ メンテナーの投稿 ＞ エンジニアリングブログ ＞ Stack Overflow（当年の投稿で、投票数の多いもの）。

---

フェーズ 4：根本原因を特定する

根本原因の定式化

修正を書く前に、次の点を明確にします。

1. 何が起きたか：エラーの原因となった具体的な実行時の状態
2. なぜ起きたか：その状態が生じ得た上流の理由
3. どこを修正するか：適切なレイヤー（通常、クラッシュした箇所ではありません）

---

フェーズ 5：修正する

アンチパターンのチェックリスト

次の対処だけを修正として適用してはいけません。

• TypeError を抑制するために ?. を追加する → 値が null である理由を修正します
• try/catch で囲んでエラーを握りつぶす → 根本のエラーを修正します
• ?? [] のフォールバックを追加する → 読み込み状態やエラー状態を明示的に処理します
• 利用側に if ガードを追加する → 生成側を修正します

修正の原則

1. クラッシュした箇所ではなく、根本原因のレイヤーで修正します（同じ箇所である場合を除きます）
2. 不正な状態を表現できないようにします
3. 既存のプロジェクトの規約に従います
4. 共有関数に修正を加える場合は、すべての呼び出し元を確認します
5. このバグだけを修正します。気づいた既存のバグは差分に含めず、フォローアップとしてレポートに記載します。フィードバックループのスクリプトは、フェーズ 6 の回帰テストとして、リポジトリに既存のテスト置き場へ追加する場合を除き、リポジトリに含めません。変更は必要最小限にし、ファイルを書き換えないでください。

---

フェーズ 6：検証する

修正をテストする

• フェーズ 1 のフィードバックループを再実行し、成功することを確認する（実行コマンドと出力を貼り付けます）
• 最小化した再現ケースを、適切な境界で回帰テストに変換する（実際のバグパターンを検証するものにします。適切な境界がない場合は、信頼性に欠けるテストを書くのではなく、アーキテクチャ上の課題として記録します）
• テストスイートがある場合は実行し、出力を貼り付けます

回帰チェック

# Run tests
npm test
# Or framework-specific
pytest
cargo test
go test ./...

---

フェーズ 7：予防する

モニタリングを追加する

バグが別の形で再発する可能性がある場合は、モニタリングを追加します。

• 該当するコードパスに対するカスタム Sentry コンテキスト
• 主要なユーザー操作のパンくず
• データフローのチェックポイントに対する構造化ログ

自明でない修正を文書化する

自明でない相互作用が原因のバグの場合は、その制約を説明するコメントを追加します。

// Profile can be null for users who haven't completed onboarding.
// The API returns null (not 404) in this case. See: ISSUE-123.

---

デバッグチェックリスト

## Bug Investigation: [Title]

**Pre-Debug:**
- [ ] Docs/README read
- [ ] Sentry context fetched (if applicable)
- [ ] Database state checked (if data-related)
- [ ] Error scope identified

**Investigation:**
- [ ] Can reproduce locally (or have Sentry reproduction)
- [ ] Isolated to specific component/function/layer
- [ ] Research completed (Firecrawl/Context7)
- [ ] Root cause identified and stated

**Fix:**
- [ ] Fix addresses root cause (not symptoms)
- [ ] No anti-patterns used as sole fix
- [ ] Side effects checked (other callers)
- [ ] Tests pass

**Prevention:**
- [ ] Monitoring added (if applicable)
- [ ] Documentation updated (if non-obvious)