debug

デバッグ

基本原則

推測しないでください。まず情報を集めてください。

悪い例：何かが壊れた → 適当に修正を試す → うまくいかない → 別の修正を試す → 5回試してもまだ壊れている。

良い例：何かが壊れた → 再現する → 診断情報を集める → 根本原因を診断する → 修正する（通常は最初の試みで解決します）。

修正する前に診断してください。

---

ツール別のデバッグ

デバッグ方法は、使用しているツールによって異なります。

Claude Code（直接アクセスできます）

Claude Code は独自に診断情報を収集できます。創業者にスクリーンショットやログを頼む前に、まず自動で次を実行してください。

Auto-debug steps (do these yourself):
1. Check git history: git log --oneline -10 and git diff HEAD~3
2. Search for the error: Grep for error text across the codebase
3. Read the failing file: Read the file + surrounding context
4. Run the app/tests: Bash to run dev server, test suite, or reproduce
5. Check logs: Read server logs, build output, or error logs
6. Check environment: Verify .env.example vs actual config

自分では取得できない情報だけを創業者に尋ねてください。たとえば、ブラウザーで何が表示されたか、何をクリックしたか、視覚的な不具合のスクリーンショットなどです。

Lovable / Replit（創業者がチャットに貼り付けます）

創業者が手動で情報を収集し、貼り付ける必要があります。DEBUG-PROMPTS.md の「AI への指示：」プロンプトを使ってください。必要な情報を漏れなく含められるように構成されたテンプレートです。

本番環境の不具合（まず監視を確認してください）

本番環境の問題をデバッグする前に、監視とエラートラッキングを確認してください。

1. Error tracker (Sentry, LogRocket): exact error + stack trace + user context
2. Server logs: filter by timestamp of report
3. Hosting dashboard: any deployment or outage at that time?
4. Database: any failed migrations or connection issues?

監視の設定については、/monitor スキルを参照してください。ロールバック手順については、/deploy スキルを参照してください。

---

ワークフロー

Debug process:
- [ ] Reproduce bug consistently
- [ ] Gather diagnostic info (auto in Claude Code, manual elsewhere)
- [ ] Check what changed recently
- [ ] Diagnose root cause before proposing fixes
- [ ] Fix the root cause
- [ ] Test fix works
- [ ] Verify didn't break anything else
- [ ] Ask: how do we prevent this?

---

不具合の再現

修正する前に、問題を再現してください。

Can you reproduce it?
- [ ] Exact steps to trigger bug
- [ ] Happens every time or intermittently?
- [ ] Specific browser/device?
- [ ] Specific data or user?

If can't reproduce:
- Ask user for exact steps or screen recording
- Try different browser/device/account
- Try with different data
- Clear cache and retry
- Check if timing-dependent

AI への指示：

Bug: [description]

Steps to reproduce:
1. [Step]
2. [Step]
3. [Bug happens]

Happens: [Always / Sometimes / Once]
Browser: [Chrome 120 on Mac]
Screenshot: [attach]

---

エラー情報の収集

ブラウザーのコンソール

1. ページを右クリック → 検証 → コンソールタブ
2. 赤いエラーを探します
3. スタックトレースを含むエラー全体のスクリーンショットを撮ります

AI への指示：

Console error: [paste full error message]
When it happens: [what you were doing]

ネットワークタブ

1. DevTools → ネットワークタブ → 不具合を再現します
2. 失敗したリクエスト（赤色、4xx、5xx）を探します
3. 失敗したリクエストをクリック → レスポンスタブを確認します

AI への指示：

API call failing:
URL: /api/endpoint
Method: [GET/POST]
Status: [status code]
Response: [paste error response]
This happens when: [action]

視覚的な不具合

期待していた表示と実際の表示をそれぞれスクリーンショットに撮ってください。デバイスとブラウザーも記載してください。

---

よくある不具合の種類

「クリックしても何も起きない」

確認事項：コンソールエラーはありますか？ネットワークリクエストは失敗していますか？要素は実際にクリックできますか（別の要素に覆われていませんか）？

「ページが読み込まれない」

確認事項：ネットワークエラーはありますか？JavaScript エラーはありますか？リダイレクトが無限に続いていませんか？環境変数が不足していませんか？

「表示されるデータが違う」

確認事項：API が誤ったデータを返していませんか（ネットワークタブ）？キャッシュの問題ですか？状態が更新されていませんか？ユーザーコンテキストが間違っていませんか？

「フォームが送信されない」

確認事項：バリデーションエラーが表示されていますか？コンソールエラーはありますか？ネットワークリクエストは実行されていますか？

「開発環境では動くが、本番環境では壊れる」

確認事項：環境変数は設定されていますか？データベースが異なりますか？ビルド時に何かが取り除かれていませんか？本番環境のドメインに対して CORS が設定されていますか？

「Chrome では動くが、Safari では壊れる」

確認事項：CSS / JS の互換性に問題はありますか？Safari 固有のデフォルト動作ですか？日付の解析方法に違いがありますか？

---

エスカレーションの心得

修正に1回失敗した後

状況を再評価してください。診断を誤っていませんか？さらに集めるべき情報はありませんか？

Fix didn't work. Here's what happened after applying it: [new info].
Are we fixing the right thing?

修正に2回失敗した後

修正を試すのはやめてください。 診断が間違っている可能性が高いです。

2 fixes failed.
Fix 1: [tried] → [result]
Fix 2: [tried] → [result]

Are we fixing the wrong thing? Should we rethink the approach entirely?

修正に3回失敗した後

4回目を試さないでください。方針を変えましょう。

1. よりシンプルな方法で機能を作り直す
2. 人間の開発者に確認してもらう（/hiring を参照）
3. 回避策をリリースし、後で適切に修正する

---

さらに深く掘り下げる：真の根本原因を見つける

デバッグが失敗する原因のほとんどは、実際の根本原因ではなく、最初にもっともらしく思えた原因で止めてしまうことです。「なぜ？」を問い続ける手法を使ってください。

Problem: Server crashed
  Why? → Out of memory
  Why? → Memory leak in the auth service          ← Most people stop here and "add more RAM"
  Why? → Database connections not being released
  Why? → Error handler doesn't close connections
  Why? → No cleanup in the finally block           ← THIS is the fix

真の根本原因を見つけたと判断する方法：

• 実際に変更できるもの（コード、設定、プロセス）である
• それを修正すれば、問題の再発を防げる
• もう一度「なぜ？」と尋ねても、実行可能な対応にはつながらない

よくある間違い：「AI が壊した」で止めてしまうこと。 それは原因ではなく、責任を問うだけです。代わりに、どのプロセスがあればこれを検出できたのかを考えてください。テストがなかったのか？バリデーションがなかったのか？コードレビューがなかったのか？

不具合に複数の原因がある場合

不具合は、2つの問題が同時に起きたときに発生することがあります。明らかな原因だけでは問題を完全に説明できない場合は、2つ目の分岐を探してください。

Problem: Deployment failed
  Why? → Database migration timed out
    Branch A: Why was the migration slow?
      → Table lock from a long-running query → Missing index
    Branch B: Why is the timeout so short?
      → Using default timeout → No deployment-specific config

両方の分岐を修正する必要があります。そうしないと、少し条件が変わっただけで不具合が再発します。

診断を検証する

修正を実装する前に、原因をさかのぼって確認します。「Xを修正すればYを防げる。Yを防げばZを防げる。Zを防げば元の問題を防げるか？」と考えてください。このつながりが途切れたら、根本原因を見誤っています。

---

発生したりしなかったりするバグ

「動くこともあれば、動かないこともある」場合は、競合状態、キャッシュの問題、または外部 API の不安定さが原因である可能性があります。

AI への指示：

Bug is intermittent.
Works: [X] out of 10 times
Fails: [Y] out of 10 times

Pattern: Fails more when [condition]. Never fails when [condition].

Add logging to capture state when it fails.

---

エッジケースのテスト

修正が通常のケースで機能したら、次のケースもテストしてください。

• 空の状態：データがない、リストが空、フィールドが欠けている
• データ量：1件、100件、10,000件
• タイミング：低速な接続（DevTools で 3G にスロットリング）、すばやいダブルクリック、期限切れのセッション、複数のタブ
• 境界条件：非常に長いテキスト、特殊文字、ゼロの値、負の数

---

本番環境のバグ

優先度 1：ユーザーが回避策を使えますか？

• はい → 次回のデプロイで修正
• いいえ → 緊急の修正が必要

緊急の修正：

Production bug blocking users.
Bug: [description]
Impact: [how many users affected]

Need the simplest fix that unblocks users. Can improve later.

---

複数のバグが同時に発生した場合

1つのバグに見える症状が、実際には複数のバグである場合や、複数の症状が1つの根本原因に由来する場合があります。

List all symptoms:
1. [Symptom]
2. [Symptom]
3. [Symptom]

Are these separate bugs or one root cause?

優先順位に従って修正します： ブロッキング（アプリを使えない）→ 重大（主要機能が動かない）→ 大 → 小。重大なバグが未修正の間は、小さなバグを修正しないでください。

---

デバッグログの追加

バグの診断が難しい場合は、要所にログを追加します。

Add logging at:
- Function entry with input values
- Before/after API calls with request/response
- State changes with before/after values
- Error handlers with full context
- Decision points (which branch was taken)

Format: [TIMESTAMP] [LEVEL] [CONTEXT] Message
Example: [2025-01-13 10:30:45] [ERROR] [UserAuth] Login failed for [email protected] - Reason: Invalid password - Attempts: 3

バグを修正したら、ログを削除するか、量を減らしてください。

---

予防

修正のたびに、次の3つのレベルで考えてください。

1. 即時の修正 — すでに実施済みです（バグが解消されています）
2. 予防策 — 今後同じことが起きないようにするには何が必要ですか？（検証、テスト、型チェック）
3. 検出の仕組み — 予防に失敗した場合、どうすれば早期に検出できますか？（モニタリングアラート、エラー追跡）

Bug is fixed. Now:
- What validation or test would prevent this from recurring?
- What monitoring or alert would catch it early if it does recur? (see /monitor)
- Is this a pattern? Could the same type of bug exist elsewhere in the codebase?

---

助けを求めるタイミング

次の場合は、開発者への依頼を検討してください。

• このプロセス全体に従っても行き詰まっている
• 原因を特定できない、本番環境の重大なバグがある
• 修正しても同じバグが繰り返し発生する
• 複雑なサードパーティとの連携にバグがある
• セキュリティ上の問題、またはデータ破損のリスクがある

ほとんどのバグは、AI ツールを使ったこのプロセスで解決できます。

---

よくある間違い

間違い	対処法
情報なしで修正を試す	まず診断に必要な情報を集める
「動きません」（曖昧）	具体的にする：具体的に何が動かないのか？
先に再現しない	バグを確実に発生させる手順を見つける
AI に手当たり次第の修正を求める	まず根本原因を診断する
コンソール／ネットワークのエラーを無視する	必ず両方のタブを確認する
修正後にテストしない	修正が機能し、ほかの箇所を壊していないことを確認する
重大なバグがあるのに小さなバグを修正する	ユーザーへの影響に基づいて優先順位を付ける
最もらしい最初の原因を受け入れる	実際に修正できる原因にたどり着くまで「なぜ？」と問い続ける
「AI が壊した」（責任転嫁であり、診断ではない）	どういうプロセスなら検出できたかを考える