Loop triase error build Claude Code: persempit penyebab dalam 15 menit

Pecah error sebelum meminta fix

Saat build Node, Astro, Vite, atau Next.js gagal, langkah yang terlihat cepat adalah menempel seluruh log ke Claude Code dan meminta semuanya diperbaiki. Masalahnya, log penuh biasanya mencampur baris gagal pertama, stack trace lanjutan, noise package manager, dan cleanup yang tidak terkait. Build bisa hijau, tetapi review tetap sulit karena penyebab asli tidak terlihat.

Loop ini menerapkan template bug report, checklist review workflow, dan verification receipt workflow ke error build. Targetnya bukan perbaikan besar sekali jalan. Targetnya adalah mempersempit penyebab menjadi satu hipotesis dalam 15 menit, membuat perubahan terkecil, dan meninggalkan bukti yang bisa diperiksa.

Harness berarti pijakan kerja untuk agent. Claude Code bisa membaca repository dan bernalar, tetapi manusia tetap menentukan bagian log mana yang penting, hipotesis mana yang boleh diuji, dan command mana yang membuktikan fix. Pijakan ini mencegah build fix berubah menjadi refactor luas.

flowchart LR
  A[State] --> B[Build log]
  B --> C[First failing line]
  C --> D[One hypothesis]
  D --> E[Small fix]
  E --> F[Proof command]
  F --> G[Receipt]

Loop 15 menit

Bagi pekerjaan menjadi tiga blok lima menit. Blok pertama hanya mengambil bukti: git status, command build yang gagal, baris gagal pertama, dan file terkait. Jangan edit file dulu. Blok kedua memilih satu hipotesis: dependency, import path, frontmatter, data shape, permission, network, atau test expectation.

Blok ketiga baru mengizinkan perubahan kode atau konfigurasi. Setelah itu jalankan command yang gagal dan catat proof. Untuk situs content atau revenue, build hijau belum cukup. Periksa URL artikel, h1, canonical, hero image, CTA, product link, dan training link. Build yang pass tetapi memutus conversion tetap masalah produksi.

Catatan kerja Masa sengaja pendek: cause, change, evidence. Reviewer perlu tahu mengapa hipotesis dipilih, apa yang berubah, dan command atau URL mana yang membuktikan. Minta Claude Code mengembalikan tiga baris ini agar review lebih ringkas dan failure berikutnya punya titik awal.

Ambil bukti dengan urutan tetap

Gunakan command yang sama dengan urutan yang sama. Di macOS, Linux, atau WSL, contoh shell ini menyimpan log dan mempertahankan exit code asli.

git status --short
npm run build 2>&1 | tee build.log
status=${PIPESTATUS[0]}
if [ "$status" -ne 0 ]; then
  grep -Ein "error|failed|ERR_|Cannot|TypeError" build.log | head -n 20
  exit "$status"
fi
npm test -- --runInBand

Di Windows PowerShell, panggil npm.cmd secara eksplisit agar perilaku shell lebih konsisten.

$ErrorActionPreference = "Continue"
git status --short
npm.cmd run build *> build.log
$buildExit = $LASTEXITCODE

if ($buildExit -ne 0) {
  Select-String -Path build.log -Pattern "error|failed|ERR_|Cannot|TypeError" |
    Select-Object -First 20
  exit $buildExit
}

npm.cmd test -- --runInBand

Run pertama tidak harus berhasil. Tugasnya menyimpan failure pertama yang berguna. Stack trace terakhir bisa saja hanya akibat; baris error pertama biasanya lebih dekat ke akar masalah.

Klasifikasikan failure pertama dengan Node

Simpan script ini sebagai scripts/triage-build-log.mjs, lalu jalankan node scripts/triage-build-log.mjs build.log. Script ini tidak memperbaiki kode; ia mereduksi log besar menjadi satu bucket dan arah diagnosis berikutnya.

#!/usr/bin/env node
import { readFileSync } from "node:fs";

const logPath = process.argv[2];

if (!logPath) {
  console.error("Usage: node scripts/triage-build-log.mjs build.log");
  process.exit(1);
}

const rules = [
  { name: "dependency or import path", regex: /Cannot find module|ERR_MODULE_NOT_FOUND|Cannot resolve/i },
  { name: "runtime null or shape mismatch", regex: /TypeError:.*undefined|undefined is not|Cannot read/i },
  { name: "test expectation drift", regex: /Expected.*received|AssertionError|Snapshot/i },
  { name: "permission or sandbox boundary", regex: /EACCES|EPERM|permission denied/i },
  { name: "Astro content or frontmatter", regex: /frontmatter|content collection|InvalidContentEntry|MDX/i },
];

const lines = readFileSync(logPath, "utf8").split(/\r?\n/);
const firstFailure = lines.find((line) => /error|failed|ERR_|Cannot|TypeError/i.test(line));
const matchedRule = rules.find((rule) => firstFailure && rule.regex.test(firstFailure));

console.log(JSON.stringify({
  firstFailure: firstFailure || "No obvious failure line found",
  bucket: matchedRule ? matchedRule.name : "needs manual reading",
  nextDiagnostic: matchedRule
    ? "Run one command that proves or disproves this bucket before editing files."
    : "Read the 30 lines before the first failure and classify manually.",
}, null, 2));

Klasifikasi ini tidak perlu sempurna. Manfaatnya adalah mengubah prompt dari “fix build” menjadi “buktikan atau gugurkan bucket ini sebelum edit file”. Ini mengurangi dependency upgrade, null check lebar, dan cleanup yang menutupi penyebab.

Pakai dokumentasi resmi sebagai batas

Masalah koneksi, autentikasi, limit, dan runtime message Claude Code perlu dicek di Claude Code Error reference. Jika CLAUDE.md, settings, hooks, atau MCP terlihat tidak dimuat, gunakan Debug your configuration.

Untuk situs Astro, frontmatter dan content collection sebaiknya dibandingkan dengan Astro Content Collections. Untuk kode Node seperti ERR_MODULE_NOT_FOUND, gunakan Node.js Errors. Memisahkan sumber ini membuat diagnosis lebih jujur: masalah Claude Code, build aplikasi, dan runtime Node tidak tercampur.

Langkah pertama menurut bentuk log

Bentuk log	Curigai dulu	Langkah pertama
Cannot find module	import path, file generated, dependency	Cek file dan path sebelum install package
ERR_MODULE_NOT_FOUND	ESM/CJS, extension, package exports	Cocokkan error Node dan package config
undefined is not	data shape, frontmatter, API response	Print satu record nyata sebelum null check
Expected ... received	spec change, fixture, snapshot	Klasifikasikan sebagai perubahan valid atau regression
permission denied	sandbox, CI user, write path	Cek working directory dan permission
hanya Build failed	error pertama di atasnya	Ambil error pertama, bukan trace terakhir

Di situs artikel Astro, undefined is not an object bisa berarti satu locale kehilangan heroImage, pubDate, atau lang. Guard global bisa membuat build pass tetapi menyembunyikan masalah kualitas content.

Prompt Claude Code siap salin

Baca build log yang gagal ini.
Jangan usulkan refactor luas.
Jangan edit file dulu.

Kembalikan:
1. baris gagal pertama
2. satu penyebab paling mungkin
3. command diagnosis terkecil untuk penyebab itu
4. perubahan kode atau config terkecil yang boleh dilakukan
5. command proof setelah fix
6. tiga baris untuk PR: cause, change, evidence

Saat orang lain juga mengedit repository yang sama, tambahkan scope: hanya slug ini, jangan sentuh reports, jangan revert perubahan tidak terkait, dan pertahankan identity fields frontmatter. Batas ini mengurangi konflik kerja.

Empat use case praktis

Use case pertama adalah situs Astro multibahasa. Frontmatter salah di satu locale, MDX code fence yang tidak tertutup, hero image hilang, atau internal link salah bisa menjatuhkan build. Minta Claude Code membandingkan hanya sepuluh file slug itu dan memvalidasi YAML, fences, serta panjang body.

Use case kedua adalah import failure di Node CLI atau package. Cannot find module tidak selalu berarti dependency belum terpasang. Penyebabnya bisa typo, file generated belum dibuat, aturan exports, atau campuran ESM/CJS. Sebelum mengubah dependency, jalankan node -p "require.resolve('package-name')" atau cek keberadaan file langsung.

Use case ketiga adalah failure hanya di CI. Penyebab umum adalah permission, path case-sensitive, versi Node berbeda, secret salah nama, atau proxy belum disetel. Sebelum mengubah kode aplikasi, daftar CI OS, working directory, Node version, env vars, dan write targets.

Use case keempat adalah test expectation drift. Expected ... received mudah ditutup dengan snapshot update, tetapi itu bisa menyetujui regression. Untuk CTA, copy harga, link Gumroad, form training, atau metadata artikel, pastikan perubahan memang diinginkan.

Pitfall yang konkret

Pitfall pertama adalah membaca akhir log saja. Stack trace terakhir bisa akibat, bukan penyebab. Simpan baris gagal pertama dan 30 baris sebelumnya.

Pitfall kedua adalah terlalu cepat upgrade dependency. Package update mengubah lockfile, CI cache, dan kompatibilitas runtime. Jika penyebabnya import path typo, review menjadi besar tanpa manfaat.

Pitfall ketiga adalah berhenti di build hijau. Situs publik juga harus mengonfirmasi /en/products/, /en/training/, form PDF gratis, h1, dan canonical.

Pitfall keempat adalah membiarkan cleanup oportunistik. PR build-fix harus mempertahankan hipotesis yang terlihat. Jika formatting, refactor, dependency, dan content rewrite dicampur, proof hilang.

CTA produk dan training

Untuk mengubah loop ini menjadi prompts, checklists, dan setup material yang reusable, mulai dari ClaudeCodeLab products. Jika tim perlu CI gates, CLAUDE.md, permission rules, review receipts, dan production verification untuk repository nyata, gunakan Claude Code training and consultation.

Bacaan lanjutan yang cocok adalah permission audit checklist dan CI/CD setup. Untuk individu, PDF gratis cukup untuk membentuk kebiasaan command. Untuk tim, perlu prompt bersama, format bukti bersama, dan owner approval yang jelas.

Hasil setelah dicoba

Dengan loop ini, diff menjadi lebih kecil. Alih-alih memberi seluruh log ke Claude Code, sesi dimulai dari satu baris gagal, satu hipotesis, dan satu command proof. Cara ini lebih cepat memisahkan missing frontmatter, file generated yang belum ada, import path typo, dan permission CI. Nilai terbesarnya bukan fix pertama, tetapi receipt singkat yang bisa dipakai saat failure berikutnya muncul.