Template bug report Claude Code: ubah bug samar menjadi perbaikan reproducible

Jika Anda hanya memberi Claude Code kalimat “halamannya rusak” atau “test gagal”, ia harus menebak. Patch pertama bisa terlihat masuk akal, tetapi sering melewatkan root cause, command verifikasi, dan konteks yang dibutuhkan reviewer PR. Bug report yang baik mengubah keluhan samar menjadi tugas debugging yang bisa direproduksi.

Panduan ini memberi template untuk sesi Claude Code: symptom, expected behavior, actual behavior, minimum reproduction, log, environment, failing test, constraint, dan PR handoff. Gunakan setelah first task runbook, lanjutkan dengan debugging techniques, lalu tutup dengan PR quality checklist.

Referensi resmi yang berguna: CLI reference, commands reference, common workflows, dan GitHub Actions guide. Ini membantu membedakan --verbose, /debug, /feedback, /bug, dan automation untuk PR.

Isi report yang berguna

Field	Isi	Manfaat untuk Claude Code
Symptom	Page, command, route, atau API yang rusak	Titik awal investigasi
Expected	Aturan produk atau UI yang benar	Definisi “selesai”
Actual	Error, status, visual break, output salah	Fakta, bukan dugaan
Reproduction	Jalur paling kecil yang gagal cepat	Cara menguji hipotesis
Environment	OS, runtime, browser, branch, nama env	Bedakan local dan CI
Evidence	Log, screenshot, stack trace, failing test	Bukti sebelum/sesudah
Constraints	Area yang boleh dan tidak boleh disentuh	Diff lebih kecil
Handoff	Root cause, verifikasi, risiko, follow-up	Review lebih cepat

Kesalahan paling umum adalah tidak menulis expected behavior. “Hilangkan error” bukan requirement. API harus mengembalikan empty list, 400, warning untuk user, atau retry? Tulis sebagai aturan yang bisa diuji.

Template siap pakai

Simpan sebagai bug-report.md, isi bagian kosong, lalu berikan ke Claude Code sebelum meminta perubahan.

# Bug report for Claude Code

## Goal
- Bug to fix:
- Desired outcome:
- Out of scope:

## Environment
- OS:
- Node / package manager:
- Browser / device:
- Branch:
- Relevant env var names, not values:

## Symptom
- Where it happens:
- Who sees it:
- Frequency: always / intermittent / unknown

## Expected behavior
-

## Actual behavior
-

## Minimum reproduction
1.
2.
3.

## Evidence
- Error message:
- Logs:
- Screenshot:
- Failing command:

## Recent changes
- PR / commit:
- Likely files:

## Constraints
- Allowed scope:
- Do not touch:
- Do not paste secrets or customer data:

## Request to Claude Code
1. Do not patch immediately
2. List the top three hypotheses
3. Propose the smallest check that could disprove each hypothesis
4. Create a minimum reproduction or failing test first
5. Apply the smallest useful fix
6. Report verification commands and remaining risk

Template ini cocok untuk ticket internal, support handoff, dan komentar PR. Intinya: definisikan sukses sebelum Claude Code mengedit.

Script runnable untuk mengumpulkan konteks

Branch, versi Node, dan diff saat ini mudah terlupa. Script Node ini tanpa dependency eksternal dan memasker secret yang jelas.

// scripts/collect-bug-context.mjs
import { execFileSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";
import { platform, release } from "node:os";
import { cwd } from "node:process";

function run(command, args) {
  try {
    return execFileSync(command, args, {
      cwd: cwd(),
      encoding: "utf8",
      stdio: ["ignore", "pipe", "pipe"],
    }).trim();
  } catch (error) {
    return `(failed: ${command} ${args.join(" ")})`;
  }
}

function maskSecrets(text) {
  return text
    .replace(/(api[_-]?key|token|secret|password)=([^\\s]+)/gi, "$1=***")
    .replace(/Bearer\\s+[A-Za-z0-9._-]+/g, "Bearer ***");
}

function readPackageScripts() {
  if (!existsSync("package.json")) return "package.json not found";
  const pkg = JSON.parse(readFileSync("package.json", "utf8"));
  return JSON.stringify(pkg.scripts ?? {}, null, 2);
}

const report = {
  generatedAt: new Date().toISOString(),
  cwd: cwd(),
  os: `${platform()} ${release()}`,
  node: process.version,
  branch: run("git", ["branch", "--show-current"]),
  status: run("git", ["status", "--short"]),
  lastCommit: run("git", ["log", "-1", "--oneline"]),
  diffStat: run("git", ["diff", "--stat"]),
  packageScripts: readPackageScripts(),
};

console.log(maskSecrets(JSON.stringify(report, null, 2)));

Jalankan:

mkdir -p scripts
# Simpan kode di atas sebagai scripts/collect-bug-context.mjs
node scripts/collect-bug-context.mjs > bug-context.json

Masking hanya lapisan tambahan. Jangan tempel API key asli, data pelanggan, atau log production penuh.

Use case 1: CTA mobile overflow

Report lemah:

Halaman mobile rusak.

Report berguna:

Symptom:
  Pada viewport 390px, CTA pricing melewati sisi kanan layar.

Expected behavior:
  Dua CTA tersusun vertikal dan tidak ada horizontal scroll.

Minimum reproduction:
  1. Buka Chrome DevTools pada 390px
  2. Buka halaman yang bermasalah
  3. Scroll ke section pricing

Evidence:
  document.documentElement.scrollWidth is 412
  Screenshot attached

Constraints:
  Jangan ubah link atau copy produk. Periksa CSS/layout saja.

Dengan ini Claude Code bisa memeriksa width, gap, teks tombol, dan parent container. Untuk halaman monetisasi, pastikan juga jalur products dan training masih bekerja.

Use case 2: checkout API mengembalikan 500

Bug API butuh payload, response yang diharapkan, error aktual, dan nama konfigurasi.

Symptom:
  POST /api/checkout mengembalikan 500 hanya saat plan=pro.

Expected behavior:
  Mengembalikan 200 dengan payment URL. Jika konfigurasi kurang, tampilkan setup error yang jelas.

Actual behavior:
  TypeError: Cannot read properties of undefined (reading 'prices')

Minimum reproduction:
  curl -X POST http://localhost:3000/api/checkout \
    -H "content-type: application/json" \
    -d '{"plan":"pro"}'

Environment:
  Menggunakan STRIPE_SECRET_KEY dan PRICE_PRO_ID. Jangan tempel nilainya.

Constraints:
  Jangan menambah panggilan nyata ke provider. Cek config loading dan input validation dulu.

Minta Claude Code membandingkan tiga hipotesis: config loading, request validation, price mapping. Jika reproduksi lokal, failing test biasanya cocok di handler atau module konfigurasi.

Use case 3: regresi batas tanggal

Untuk timezone dan akhir bulan, failing test lebih kuat daripada screenshot.

import { describe, expect, it } from "vitest";
import { exportMonthlyOrderIds } from "../src/export-orders";

describe("exportMonthlyOrderIds", () => {
  it("includes March orders and excludes April 1 UTC", () => {
    const orders = [
      { id: "mar-start", createdAt: "2026-03-01T00:00:00.000Z" },
      { id: "mar-end", createdAt: "2026-03-31T23:59:59.999Z" },
      { id: "apr-start", createdAt: "2026-04-01T00:00:00.000Z" },
    ];

    expect(exportMonthlyOrderIds(orders, "2026-03")).toEqual(["mar-start", "mar-end"]);
  });
});

Instruksinya harus jelas: “Buat test ini gagal dulu, lalu perbaiki implementasi tanpa bergantung pada local timezone.” Jebakannya adalah memperbaiki label tanggal di UI saja, sementara boundary agregasi tetap salah.

Prompt investigasi Claude Code

Read bug-report.md and bug-context.json.

Process:
1. Do not edit yet
2. Separate facts from guesses
3. Rank the top three root-cause hypotheses
4. Propose the smallest check that could disprove each one
5. Create a minimum reproduction or failing test first
6. After approval, make the smallest useful fix

Done means:
- The expected/actual gap is explained
- A failing test or reproduction command remains
- Verification commands are reported
- The PR handoff includes root cause, fix, risk, and follow-up

Common workflows resmi juga menyarankan memberi error, command reproduksi, langkah, dan apakah bug intermittent. /debug untuk mendiagnosis sesi Claude Code. /feedback dan /bug untuk masalah produk Claude Code, bukan bug aplikasi Anda.

Template PR handoff

## Root cause
-

## Fix
-

## Regression coverage
- Added failing test:
- Manual reproduction checked:

## Verification
- [ ] npm test
- [ ] npm run typecheck
- [ ] npm run build
- [ ] mobile / desktop visual check if UI changed

## Risk
-

## Claude Code notes
- Hypotheses rejected:
- Files intentionally not touched:
- Follow-up issue:

Gabungkan dengan session handoff template dan testing strategies.

Pitfall umum

Jangan gabungkan bug yang tidak terkait. Login, checkout, dan layout perlu reproduksi terpisah.

Jangan tempel log penuh. Dua puluh baris sekitar error, request ID, dan command reproduksi biasanya cukup.

Jangan selesai tanpa failing test jika bug menyangkut boundary, data mapping, API contract, atau permission.

Jangan minta Claude Code “lihat semuanya”. Reproduksi kecil lebih berguna daripada izin edit yang luas.

Jangan lewati PR handoff. Reviewer perlu cause, proof, dan residual risk.

Masukkan jalur monetisasi ke verifikasi

Di ClaudeCodeLab, bug fix bisa merusak CTA, kartu produk, form PDF gratis, link Gumroad, atau link konsultasi. Jika layout artikel atau route produk berubah, masukkan semua itu ke scope verifikasi.

Untuk penggunaan personal, adaptasi checklist gratis ke repository Anda. Jika butuh prompt reusable, review gate, dan materi setup, lihat products. Jika tim perlu menstandarkan bug report, permission Claude Code, PR review, dan CI handoff, mulai dari training.

Hasil praktik

Dalam percobaan nyata, report yang berisi reproduction steps, expected behavior, failing test, dan PR handoff menghasilkan diff lebih kecil dan pertanyaan review lebih sedikit daripada prompt “tolong perbaiki”. Perbaikan terbesar datang dari meminta tiga hipotesis sebelum editing. Hipotesis salah cepat dibuang, dan sesi berubah dari tebak patch menjadi debugging berbasis bukti.