このレッスンで学ぶこと
- エラーメッセージ・スタックトレースをClaude Codeに効果的に伝える方法
- ログ追跡と再現手順の特定をClaudeと一緒に進める進め方
- 仮説を立てて検証する「科学的」なデバッグワークフロー
- 再現が難しいバグに対する条件の絞り込みアプローチ
- デバッグを効率化するCLAUDE.mdの書き方
前提条件
- 入門コースを修了し、Claude Codeでファイル編集・コマンド実行ができること
- デバッグ対象のプロジェクトがあること（バグがなくても、過去に直した不具合を題材にして構いません）
なぜ「エラーメッセージの貼り方」が結果を左右するのか
Claude Codeにバグ調査を頼むとき、多くの人が テストが落ちる、直して のような一行だけを投げてしまいます。これでは、Claudeは自力でテストを実行し、エラーを観測するところから始めることになり、調査に余計なターンを消費してしまいます。
逆に、エラーメッセージとスタックトレースをそのまま貼り付けるだけで、Claudeは「どのファイルのどの行で」「どんな例外が」「どんな入力で」発生したかを最初から把握でき、調査の精度とスピードが大きく変わります。
- エラーメッセージ全文（省略しない）
- スタックトレース（少なくとも自分のコードに該当する部分まで）
- 実行したコマンド
- 期待していた動作と、実際の動作の違い
悪い例と良い例
# 悪い例
ログインができません。直してください。# 良い例
npm run test:auth を実行すると以下のエラーが出ます。
FAIL src/auth/login.test.ts
● ログイン > 不正なパスワードでエラーを返す
TypeError: Cannot read properties of undefined (reading 'hash')
at verifyPassword (src/auth/login.ts:42:18)
at Object.<anonymous> (src/auth/login.test.ts:15:5)
期待: 不正なパスワード入力時はAuthErrorを投げる
実際: verifyPassword内でTypeErrorが発生してテストが落ちる
直前にuser.passwordHashのカラム名をpassword_hashに変更したコミットがあるので、
それが関係しているかもしれません。良い例には「自分なりの仮説」も添えています。これが次のセクションで説明する仮説検証型デバッグの第一歩です。
ブラウザのコンソールエラーやUIの崩れはスクリーンショットも有用ですが、テキストで取得できるエラーログは必ずテキストのまま貼りましょう。画像からの文字起こしより、Claudeが正確に解析できます。
ログ追跡と再現手順の特定
バグ報告には「再現手順が書かれていない」ケースが頻繁にあります。この場合、Claude Codeに丸投げするのではなく、再現手順の特定そのものを一緒に進める方が早く解決に到達します。
既知の情報を共有する
バグレポート、ユーザーからの報告内容、関連しそうなログファイルのパスなど、手元にある断片的な情報をすべて伝えます。「情報が少ない」と感じても、まず共有してから一緒に絞り込む方が効率的です。
ログを読ませて時系列を整理させる
logs/app-2026-06-28.log の18:00〜18:30の範囲を読んで、
エラーが発生する直前に何が起きていたか時系列で整理して大量のログを人間が目で追うのは骨が折れますが、Claudeはパターンマッチングと時系列整理が得意です。
再現コードを書かせる
ログから怪しい操作の流れが見えてきたら、それを最小限のスクリプトやテストケースとして再現させます。
ログから推測すると「カート追加→クーポン適用→数量変更」の順で
操作するとエラーになりそうです。この手順を再現するテストを
tests/cart-coupon.test.ts に書いて、実際に失敗するか確認して再現できたら原因を特定させる
再現コードが安定して失敗するようになったら、初めて原因調査と修正に進みます。再現確認をスキップして直接「直して」と言うと、見当違いの修正がされがちです。
仮説検証型のデバッグワークフロー
エラーメッセージだけでは原因が一つに絞れないことも多いです。そんなときは、Claudeに複数の仮説を立てさせ、それぞれを検証させる進め方が有効です。これは経験豊富なエンジニアが頭の中で自然にやっていることを、明示的にプロンプトに落とし込むイメージです。
ユーザーが特定の条件下でログアウトされてしまう不具合があります。
考えられる原因を3つ仮説として挙げて、それぞれどう検証すればいいか教えて。
その後、検証しやすい順に1つずつ確認していきましょう。Claudeはこの指示に対して、たとえば以下のような仮説を返してくることがあります。
- セッショントークンの有効期限設定が短すぎる（設定ファイルを確認すれば検証可能）
- 複数タブで操作した際にトークンの上書きが発生している（ブラウザの挙動を再現すれば検証可能）
- APIサーバー側のクロックスキューでトークン検証が失敗している（サーバーログのタイムスタンプを確認すれば検証可能）
仮説を立てさせるだけでなく、「検証コストが低い順に並べて」と付け加えましょう。設定ファイルを1行確認するだけで否定できる仮説から潰していく方が、無駄な調査を避けられます。
このサイクルを繰り返すと、Claudeは「仮説1は否定されました。ログを見るとトークンの有効期限は24時間に設定されていて問題ありません。次に仮説2を検証します」というように、調査の過程を逐次報告しながら絞り込んでくれます。人間が横で進捗を追えるので、見当違いの方向に進んだ場合もすぐに軌道修正できます。
再現が難しいバグへのアプローチ
「本番環境でだけ起きる」「特定のユーザーでだけ起きる」「たまにしか起きない」といった再現困難なバグは、デバッグの中でも特に厄介です。こうしたケースでは、いきなり原因を探させるのではなく、条件を絞り込むプロセスを明示的に依頼します。
このバグは再現率が低く、10回に1回程度しか発生しません。
以下の方針で条件を絞り込みたいです。
1. 発生時のログと発生しなかった時のログを比較して差分を洗い出す
2. 差分の中から怪しい要素（タイミング、データ量、並行処理など）を仮説化する
3. 仮説をもとに、発生確率を上げるための再現条件を提案する
まずは1から始めてください。発生時のログは logs/incident-001.log、
正常時のログは logs/normal-001.log にあります。再現率が低いバグの多くは、非同期処理のタイミング依存や競合状態（レースコンディション）が原因です。Claudeに「並行処理やタイミング依存の可能性を重点的に調べて」と明示すると、見落としを減らせます。
条件を絞り込めたら、その条件を意図的に再現する仕組み（遅延を意図的に挿入する、特定のデータ量を用意するなど）を作ってもらい、安定して再現できる状態を目指します。再現さえできれば、あとは通常のデバッグフローに戻れます。
デバッグ専用のCLAUDE.md設定
デバッグのたびに同じ説明を繰り返さないために、CLAUDE.mdにデバッグ関連の規約を書いておくと効果的です。ログ出力の場所やフォーマットを事前に伝えておくことで、Claudeが自力でログを探しに行けるようになります。
# デバッグ関連の規約
## ログ出力
- アプリケーションログは `logs/app-YYYY-MM-DD.log` に出力される
- ログフォーマット: `[ISO8601タイムスタンプ] [LEVEL] [モジュール名] メッセージ`
- デバッグ時は `LOG_LEVEL=debug npm run dev` で詳細ログを有効化できる
## エラー調査の進め方
- エラー調査時はまず再現手順を確立してから修正に着手する
- 複数の原因が考えられる場合は仮説を提示してから検証する
- 修正後は必ず再現テストを追加し、回帰を防ぐ
## よくある原因のパターン
- 認証関連の不具合はまず `src/auth/middleware.ts` のトークン検証ロジックを疑う
- 日付関連の不具合はタイムゾーン変換（UTC⇔JST）を疑うデバッグを重ねるうちに「またこのパターンか」と感じる原因が見えてきます。気づいたタイミングでCLAUDE.mdに追記しておくと、次回以降の調査時間が短縮されます。
まとめ
このレッスンでは、デバッグ作業をClaude Codeと一緒に加速させる方法を学びました。
- エラーメッセージの伝え方: エラー全文・スタックトレース・実行コマンド・期待値と実際の差分をセットで伝える
- ログ追跡と再現手順の特定: ログの時系列整理から再現コードの作成まで、段階的に進める
- 仮説検証型のデバッグ: 複数の仮説を検証コストが低い順に立てさせ、一つずつ潰していく
- 再現困難なバグ: 発生時と正常時のログ差分から条件を絞り込み、安定再現を目指す
- デバッグ専用のCLAUDE.md: ログの場所・フォーマット・よくある原因パターンを書いておく
次のステップ
次のレッスンでは、コミットメッセージの生成やPR作成、ブランチ整理など、Git操作をClaude Codeで効率化する方法を学びます。デバッグで見つけた修正を、意味のある単位でコミットに分割するテクニックも紹介します。
Lesson 6: Git操作を効率化する に進みましょう。