Claude Codeエラーメッセージ解読術：ログから再現手順と修正方針を作る実践ガイド

エラーメッセージを読むのが苦手な人ほど、Claude Codeに「これ直して」と丸投げしたくなります。けれど、Claude Codeはログの外にある環境差分、直前の操作、失敗したコマンドまでは自動で知りません。強い使い方は、原因を当ててもらうことではなく、ログを再現できるバグ報告に変換して、次に打つコマンドまで絞ることです。

この記事では、スタックトレース、TypeScriptの型エラー、Node.jsの実行時エラー、Docker/Kubernetesログ、GitHub ActionsのCI失敗を、Claude Codeで「再現手順」「有力な原因」「確認コマンド」「修正後の検証」に落とす流れをまとめます。公式の基本操作は Claude Code common workflows、困ったときの確認先は Claude Code troubleshooting、権限や設定を固めたい場合は Claude Code settings も合わせて確認してください。

全体像：エラーを推測ではなく再現に変える

初心者がつまずく原因の多くは、エラー文の難しさそのものではありません。ログの一部だけを貼る、実行コマンドを書かない、修正後の確認をしない。この3つでClaude Codeの回答精度は大きく落ちます。

まず、次の流れを固定します。

flowchart TD
  A["失敗したコマンドを保存"] --> B["ログを短く整形"]
  B --> C["Claude Codeに仮説と再現手順を依頼"]
  C --> D["最小再現を作る"]
  D --> E["修正して同じコマンドで検証"]
  E --> F["再発防止をCLAUDE.mdやテストに残す"]

比較すると、渡すべき情報が見えます。

エラーの種類	Claude Codeに渡す材料	期待する出力	人間が検証すること
TypeScript型エラー	tsc --noEmit --pretty false の全文、該当ファイル名	型の意味、壊れた契約、修正候補	as anyで逃げていないか
Node.jsスタックトレース	先頭のError行、アプリ内フレーム、直前の入力	例外の発生点、再現条件	同じ入力で再現するか
Docker/Kubernetes	describe、前回ログ、イベント	OOM、環境変数、probe失敗の切り分け	kubectlで確認できるか
GitHub Actions	失敗ジョブのログ、変更ファイル、ローカル実行結果	失敗段階、再現コマンド、次の修正	CIだけの環境差分がないか

実務でよくある3つの解読パターン

実務では、エラーは単独で発生するよりも「入力」「環境」「順番」のどれかと結びついて起きます。Claude Codeにログを渡す前に、この3分類で考えておくと、回答の検証がかなり楽になります。

1つ目は、入力データの形が変わったケースです。たとえば、APIのレスポンスから user.id が消えた、CSVの列名が変わった、フォームの任意項目が null で届くようになった、という種類です。この場合、TypeScriptは型エラーとして教えてくれることもありますが、本番では Cannot read properties of undefined のような実行時エラーとして出ることもあります。Claude Codeには、エラー文だけでなく「直前に処理していた入力例」「期待していたデータ形」「実際のレスポンスの一部」を渡すと、型定義、バリデーション、UIの分岐のどこを直すべきか分けやすくなります。

2つ目は、環境が違うケースです。ローカルでは通るのにCIで落ちる、開発環境では起動するのにKubernetesでは落ちる、という問題はこの分類です。原因は、Node.jsのバージョン、環境変数、タイムゾーン、ファイルパスの大文字小文字、Docker imageのビルド手順などに隠れます。Claude Codeに「ローカルでは成功したコマンド」と「CIまたはPodで失敗したコマンド」を並べて渡すと、コードそのものの問題か、環境差分の問題かを切り分けやすくなります。

3つ目は、実行順序や非同期処理のケースです。Promiseに await がない、テストが並列実行で共有ファイルを壊す、DBのmigration前にアプリが起動する、外部APIのretry後に古い状態を使う、といった問題です。この種類のエラーは、スタックトレースの最後だけを見ると別の場所が悪く見えます。Claude Codeには、ログの時刻、直前の操作、並列実行の有無、再実行すると成功するかどうかを伝えると、「常に再現するバグ」と「タイミング依存のバグ」を分けられます。

この3分類は、Claude Codeを信用しすぎないためにも役立ちます。Claude Codeが「この行を直せばよさそう」と答えたとしても、それが入力の問題なのか、環境の問題なのか、順序の問題なのかが説明されていなければ、まだ調査途中です。私はエラー対応の最初に、必ず「これは入力、環境、順序のどれに見えるか。根拠行も示して」と聞くようにしています。これだけで、原因に見える場所を場当たり的に修正する失敗が減ります。

ユースケース1：npmとtscのエラーを保存する

最初にやることは、失敗した出力を消さないことです。ターミナルの最後の数行だけを貼ると、根本原因が消えます。PowerShellなら次の形で保存できます。

New-Item -ItemType Directory -Force tmp/error-cases | Out-Null
npm test 2>&1 | Tee-Object -FilePath tmp/error-cases/test.log
npx tsc --noEmit --pretty false 2>&1 | Tee-Object -FilePath tmp/error-cases/tsc.log

macOSやLinuxなら次で同じことができます。

mkdir -p tmp/error-cases
npm test 2>&1 | tee tmp/error-cases/test.log
npx tsc --noEmit --pretty false 2>&1 | tee tmp/error-cases/tsc.log

そのうえで、Claude Codeには「答え」ではなく「調査計画」を出してもらいます。

claude -p "
I need a reproducible fix, not a guess.

Read these files if they exist:
- tmp/error-cases/test.log
- tmp/error-cases/tsc.log

Return:
1. One-line failure summary
2. Likely root cause with confidence level
3. Minimal reproduction steps
4. Next 3 commands to run
5. Smallest safe code change to try
6. Verification command after the fix

Do not hide TypeScript errors with any or ts-ignore.
"

ポイントは「confidence level」を入れることです。Claude Codeが確信できない場面では、断定ではなく「70%ならA、20%ならB」のように分けてもらいます。これで、人間側が検証すべき順番を決めやすくなります。

ユースケース2：Node.jsの長いスタックトレースを圧縮する

Node.jsのログは、node_modulesのフレームが多くて読みづらくなります。ただし、削りすぎると原因まで消えるので、全文ログは残したまま、Claude Codeに渡す要約版を別に作ります。

// scripts/minimize-stacktrace.mjs
import { readFileSync } from "node:fs";

const input = readFileSync(0, "utf8");
const lines = input.split(/\r?\n/);
const kept = [];
let nodeModulesFrames = 0;

for (const line of lines) {
  const isStackFrame = /^\s+at /.test(line);
  const isDependencyFrame = line.includes("node_modules");

  if (!isStackFrame || !isDependencyFrame || nodeModulesFrames < 3) {
    kept.push(line);
  }

  if (isStackFrame && isDependencyFrame) {
    nodeModulesFrames += 1;
  }
}

const important = kept.filter((line) =>
  /Error:|TypeError:|ReferenceError:|SyntaxError:|Caused by:|^\s+at |src\/|app\/|packages\//.test(line)
);

console.log(important.slice(0, 80).join("\n"));

実行例です。

node scripts/minimize-stacktrace.mjs < tmp/error-cases/test.log > tmp/error-cases/test.min.log

このスクリプトは「診断」ではありません。依存パッケージ由来のフレームを3つだけ残し、アプリ側のフレームを見やすくするだけです。Claude Codeに依頼するときも、必要なら全文ログを参照できるようにしておきます。

claude -p "
Analyze tmp/error-cases/test.min.log first.
If the minimized log is not enough, ask me for the full log instead of guessing.

Explain:
- Which application frame is the first useful frame
- What input or state is needed to reproduce it
- Whether this looks like async timing, null data, missing env, or dependency mismatch
- The smallest test that would fail before the fix
"

ユースケース3：TypeScriptエラーを「契約違反」として読む

TypeScriptの Type X is not assignable to type Y は、初心者には暗号に見えます。けれど多くの場合、意味は「この関数が期待している形と、渡したデータの形が違う」です。専門用語でいう型契約、つまりコード同士の約束が破れています。

Claude Codeには、型の説明だけでなく、修正案の危険度も出してもらいます。

claude -p "
Explain this TypeScript error as a broken contract between caller and callee.

Use this output:
$(npx tsc --noEmit --pretty false 2>&1)

Return a table with:
- Error location
- Plain Japanese explanation
- Data shape expected
- Data shape actually provided
- Safe fix
- Risky fix to avoid

Do not suggest any, ts-ignore, or deleting strict mode unless there is no other option.
"

この依頼にすると、「型を黙らせる修正」と「バグを直す修正」を分けられます。たとえば User | null のエラーなら、as User で逃げるのではなく、ログイン前の状態をUIで扱う、APIの戻り値を検証する、テストデータに必須フィールドを追加する、という方向に進めます。

ユースケース4：Docker/Kubernetesログを次の確認コマンドに変える

Kubernetesの CrashLoopBackOff は結果であって原因ではありません。原因は、メモリ不足、環境変数不足、DB接続失敗、Readiness probe失敗、起動コマンドの間違いなどに分かれます。

kubectl get pod -n app
kubectl describe pod web-abc123 -n app > tmp/error-cases/pod.describe.txt
kubectl logs web-abc123 -n app --previous > tmp/error-cases/pod.previous.log
kubectl get events -n app --sort-by=.lastTimestamp > tmp/error-cases/events.log

Claude Codeへの依頼は、原因名だけで終わらせません。

claude -p "
Triage this Kubernetes crash.

Files:
- tmp/error-cases/pod.describe.txt
- tmp/error-cases/pod.previous.log
- tmp/error-cases/events.log

Return:
1. Most likely category: OOMKilled, missing env, image pull, app exception, probe failure, or dependency outage
2. Evidence lines from the logs
3. One kubectl command to confirm each remaining hypothesis
4. Temporary mitigation
5. Permanent fix
6. Rollback check

If evidence is insufficient, say what command is missing.
"

「証拠行」を求めるのが重要です。Claude Codeがもっともらしい説明をしても、ログのどの行に基づくのか言えないなら、まだ仮説です。

ユースケース5：GitHub Actionsの失敗をローカル再現に落とす

CIの失敗は、ローカルでは通るのにGitHub Actionsだけ落ちることがあります。Node.jsのバージョン、OS、キャッシュ、環境変数、並列実行、タイムゾーンの違いが原因になります。

gh run list --limit 5
gh run view RUN_ID --log > tmp/error-cases/github-actions.log

ログを取ったら、次のプロンプトで「CIだけの問題」と「コードの問題」を分けます。

claude -p "
You are triaging a GitHub Actions failure.

Analyze tmp/error-cases/github-actions.log and return:
1. Failed job and failed step
2. Exact command that failed
3. Whether this should reproduce locally
4. Local reproduction command
5. CI-only differences to inspect: Node version, env vars, cache, timezone, OS, permissions
6. Smallest patch to try
7. Verification plan for local and CI

Do not assume the root cause if the log only shows a downstream symptom.
"

この形にすると、CIログの最後に出る大量の依存エラーではなく、最初に壊れたステップに戻りやすくなります。

コピペ用：構造化バグ報告テンプレート

Claude Codeに貼る前に、次のテンプレートを埋めると会話が短くなります。チームで使う場合は、.github/ISSUE_TEMPLATE/bug_report.md や docs/debug-template.md に置いても便利です。

# Bug report: short title

## Goal
What I was trying to do:

## Environment
- OS:
- Node version:
- Package manager:
- Branch:
- Commit:

## Exact command
```bash
paste the exact command here
```

## Expected result
What should have happened:

## Actual result
What happened instead:

## Logs
Paste the full error or attach the saved log file path.

## Minimal reproduction
Smallest steps that still fail:

## What I already tried
- Attempt 1:
- Attempt 2:

## Verification plan
Command that must pass after the fix:

MDXの記事内にこのテンプレートを置くときは、上のようにコードブロック内にさらにコードブロックを書くため、実ファイルではフェンスの閉じ忘れに注意してください。

よくある落とし穴

1つ目は、ログの最後だけを貼ることです。最後の行は「失敗した結果」であり、原因は中盤にあることが多いです。全文を保存してから、要約版を作りましょう。

2つ目は、「直して」とだけ頼むことです。何を実行して、何を期待して、どの環境で落ちたのかがないと、Claude Codeは一般論を返しやすくなります。

3つ目は、型エラーを any や ts-ignore で消すことです。短期的には通りますが、テストや本番で別のエラーになります。型エラーは「契約違反の警告」として扱うのが安全です。

4つ目は、ログにシークレットを入れることです。APIキー、Cookie、JWT、DB接続文字列は削除してから渡してください。チーム利用では、Claude Codeの設定と権限を settings で確認しておくと事故を減らせます。

5つ目は、修正後に別のコマンドで検証することです。落ちたコマンドをもう一度通すのが先です。その後に関連テスト、lint、build、CIを広げます。

ClaudeCodeLabの実務向け導線

個人で試すなら、この記事のテンプレートを1つずつコピーして十分です。チームで標準化するなら、ログの残し方、Claude Codeに渡してよい情報、レビューで禁止する修正、CIで必ず見る証拠を決める必要があります。

ClaudeCodeLabでは、実務向けの Claude Code教材・テンプレート と、チーム導入を整理する Claude Code導入相談・研修 を用意しています。エラー対応を属人化させたくない場合は、バグ報告テンプレート、CI triageプロンプト、CLAUDE.mdの運用ルールまでまとめて整備するのが近道です。

関連して読むなら、原因調査の型を固める Claude Codeエラー診断、修正ループを扱う Claude Codeデバッグ技術、本番ログの見方を整理する Claude Codeログ監視 がつながります。

まとめ

Claude Codeでエラーメッセージを読むコツは、長いログを短くすることではなく、再現できる形に整えることです。失敗したコマンド、全文ログ、最小再現、確認コマンド、修正後の検証をそろえると、Claude Codeの回答は「それっぽい推測」から「次に実行できる作業指示」に変わります。

この記事で紹介した内容を実際に試した結果、Masaの作業ではTypeScriptエラーの初動調査がかなり安定しました。特に、tsc --pretty false の保存、スタックトレースの最小化、CIログの「失敗ジョブ、失敗ステップ、再現コマンド」分解を固定したことで、Claude Codeの提案をそのまま信じるのではなく、同じコマンドで検証しながら安全に修正できるようになりました。