Decoder Pesan Error Claude Code: dari Log ke Perbaikan yang Bisa Direproduksi

Saat baru memakai Claude Code, wajar jika Anda ingin menempelkan pesan error panjang lalu meminta: “perbaiki ini”. Kadang berhasil, tetapi itu bukan workflow yang stabil. Claude Code tidak otomatis tahu command yang Anda jalankan, variabel environment, versi package, atau perbedaan antara laptop dan CI. Cara yang lebih kuat adalah mengubah error menjadi bug report yang bisa direproduksi, lalu meminta kemungkinan akar masalah, command berikutnya, dan rencana verifikasi.

Panduan ini membahas stack trace, error TypeScript, log runtime Node.js, Docker/Kubernetes, dan kegagalan GitHub Actions. Untuk rujukan resmi, simpan Claude Code common workflows, Claude Code troubleshooting, dan Claude Code settings.

Alur utama: reproduksi, bukan tebakan

Pesan error adalah bukti. Simpan bukti lengkap, baru kurangi noise.

flowchart TD
  A["Simpan output command yang gagal"] --> B["Kurangi noise tanpa menghapus log lengkap"]
  B --> C["Minta hipotesis dan langkah reproduksi"]
  C --> D["Buat kasus gagal paling kecil"]
  D --> E["Perbaiki dan jalankan command yang sama"]
  E --> F["Tambahkan pencegahan: test, checklist, atau CLAUDE.md"]

Sumber error	Berikan ke Claude Code	Minta output	Verifikasi sendiri
TypeScript	Output lengkap `tsc --noEmit --pretty false` dan path file	Kontrak type yang rusak, fix aman, fix berisiko	Tidak memakai `any` atau `ts-ignore`
Stack trace Node.js	Baris Error pertama, frame aplikasi, input pemicu	Frame aplikasi pertama yang berguna, input reproduksi	Input yang sama gagal lokal
Docker/Kubernetes	`describe`, previous logs, events	Kategori OOM, env, probe, image, atau error aplikasi	Baris bukti dan command `kubectl`
GitHub Actions	Log job gagal dan file yang berubah	Step gagal, command lokal, beda CI	Lokal dan CI lulus

Use case 1: simpan error npm dan tsc

Jangan hanya menyalin baris terakhir. Simpan output asli.

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

Lalu minta rencana debugging, bukan jawaban instan.

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 membuat Claude Code jujur tentang ketidakpastian. Jika keyakinannya rendah, command konfirmasi lebih penting daripada patch.

Use case 2: kecilkan stack trace Node.js

Stack trace Node.js sering penuh frame node_modules. Simpan log lengkap dan buat versi pendek untuk triage.

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

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

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

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

  if (isStackFrame && isDependencyFrame) {
    dependencyFrames += 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

claude -p "
Analyze tmp/error-cases/test.min.log first.
If the minimized log is not enough, ask 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
"

Script ini bukan alat diagnosis. Ia hanya mengurangi noise agar frame aplikasi pertama terlihat.

Use case 3: baca TypeScript sebagai kontrak yang rusak

Type X is not assignable to type Y biasanya berarti satu fungsi mengharapkan bentuk data tertentu, tetapi pemanggil mengirim bentuk lain. Type adalah kontrak antarkode.

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 Indonesian explanation
- Data shape expected
- Data shape actually provided
- Safe fix
- Risky fix to avoid

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

Dengan prompt ini, fix sungguhan terpisah dari cara membungkam compiler. Untuk User | null, arah aman biasanya menangani state belum login, memvalidasi respons API, atau memperbaiki fixture test.

Use case 4: ubah log Kubernetes menjadi command konfirmasi

CrashLoopBackOff adalah gejala, bukan akar masalah.

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 -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.
"

Jika jawaban tidak menunjukkan baris bukti, anggap itu hipotesis.

Use case 5: triage GitHub Actions

Log CI sering menyembunyikan error pertama di balik output lanjutan. Ambil log dan pisahkan reproduksi lokal dari perbedaan CI.

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

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.
"

Ini berguna untuk flaky test, perbedaan timezone, secret hilang, cache rusak, dan masalah permission.

Template bug report

# 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:

Jebakan umum

Jangan tempel hanya tiga baris terakhir. Penyebab asli sering ada di tengah.

Jangan hilangkan command persisnya. npm test, npm run build, dan vitest --run src/foo.test.ts punya konteks berbeda.

Jangan menjadikan any, ts-ignore, atau menghapus test sebagai fix TypeScript default. Itu bisa menjadi emergency workaround, bukan kebiasaan aman.

Jangan tempel secret. Redact API key, cookie, JWT, dan URL database. Untuk tim, cek permission dan konfigurasi di settings.

Setelah patch, jalankan dulu command yang gagal. Setelah itu baru lint, build, dan CI.

Training, template, dan konsultasi

Untuk penggunaan pribadi, prompt di atas sudah cukup untuk mulai. Untuk tim, bagian sulitnya adalah menyepakati log apa yang boleh dibagikan, fix apa yang dilarang, bagaimana CI ditriage, dan bukti apa yang wajib ada di review.

ClaudeCodeLab menyediakan produk dan template Claude Code serta training dan konsultasi Claude Code untuk membuat prompt debugging reusable, template bug report, checklist CI, dan aturan CLAUDE.md.

Kesimpulan

Tujuannya bukan membuat Claude Code menebak lebih keras. Tujuannya memberi bukti yang cukup agar ia menghasilkan langkah berikutnya yang bisa direproduksi. Simpan command gagal, pertahankan log lengkap, kurangi noise dengan hati-hati, minta confidence, dan verifikasi dengan command yang sama.

Setelah mencoba workflow ini dalam maintenance ClaudeCodeLab yang nyata, Masa melihat peningkatan terbesar pada 10 menit pertama debugging. Menyimpan tsc --pretty false, mengecilkan stack trace tanpa menghapus log asli, dan memecah kegagalan CI menjadi job, step, command, dan reproduction membuat saran Claude Code bisa diverifikasi, bukan diterima begitu saja.