Workflow debugging Claude Code: observasi, reproduksi, fix, test

Claude Code bisa memberi fix yang masuk akal dari pesan error, tetapi debugging produksi butuh lebih dari patch yang terlihat benar. Sesi yang reliabel memisahkan observasi, hipotesis, reproduksi minimal, implementasi, dan regression test. Jika langkah ini dilewati, bug bisa hilang di satu layar lalu kembali lewat input, bahasa, atau deploy path lain.

Artikel ini memakai TypeScript, Node, dan Vitest. Pakai bersama Claude Code and TDD saat kondisi gagal perlu dipertahankan, error handling patterns saat model exception belum jelas, dan build error triage loop saat command bukti gagal sebelum bug utama.

Beri Claude Code urutan investigasi

Request samar seperti “fix error ini” mendorong Claude Code ke patch pertama yang terlihat wajar. Lebih baik berikan full error, stack trace, langkah reproduksi, shape input, expected behavior, actual behavior, dan file yang baru berubah. Lalu minta tiga hipotesis sebelum edit.

Observasi menangkap fakta. Hipotesis menjelaskan kemungkinan penyebab. Reproduksi minimal mengubah hipotesis menjadi test atau script yang gagal. Fix tetap kecil dan regression test tinggal di repository.

{
  "name": "claude-debug-lab",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "vitest run",
    "typecheck": "tsc --noEmit"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.6.0",
    "vitest": "^3.0.0"
  }
}

Contoh 1: ubah undefined map menjadi aturan

Bug pertama umum: code memanggil map pada data yang belum datang. Goal bukan hanya menghilangkan crash. Aturannya adalah payload yang hilang menjadi list kosong, nama kosong dibuang, dan nama valid di-trim.

export type User = {
  id: string;
  name?: string | null;
};

export function normalizeUsers(users: User[] | null | undefined): string[] {
  if (!Array.isArray(users)) return [];

  return users
    .filter((user): user is User & { name: string } => typeof user.name === "string")
    .map((user) => user.name.trim())
    .filter((name) => name.length > 0);
}

import { describe, expect, it } from "vitest";
import { normalizeUsers } from "../src/normalize-users.js";

describe("normalizeUsers", () => {
  it("returns an empty list when the API payload is missing", () => {
    expect(normalizeUsers(undefined)).toEqual([]);
    expect(normalizeUsers(null)).toEqual([]);
  });

  it("keeps only usable display names", () => {
    expect(
      normalizeUsers([
        { id: "u1", name: " Masa " },
        { id: "u2", name: "" },
        { id: "u3", name: null },
      ]),
    ).toEqual(["Masa"]);
  });
});

Gunakan prompt ini:

Kami melihat Cannot read properties of undefined (reading 'map').
normalizeUsers harus toleran terhadap API payload yang hilang dan membuang display name kosong.
Tambahkan kasus Vitest yang gagal lebih dulu, lalu lakukan fix terkecil.
Jalankan npm test dan npm run typecheck di akhir.

Jebakannya adalah berhenti di users ?? []. Itu mungkin mencegah crash, tetapi null name, string kosong, dan payload non-array tetap tidak jelas. Beri Claude Code aturan produk, bukan hanya exception.

Contoh 2: async retry tanpa menyembunyikan error terakhir

Bug retry async sering terlihat intermittent. Test yang baik memeriksa jumlah call, perilaku wait, sukses akhir, dan gagal total. Jika error terakhir ditelan, incident response kehilangan petunjuk ke service yang gagal.

type RetryOptions = {
  times: number;
  delayMs: number;
  sleep?: (ms: number) => Promise<void>;
};

const defaultSleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));

export async function retry<T>(
  task: () => Promise<T>,
  { times, delayMs, sleep = defaultSleep }: RetryOptions,
): Promise<T> {
  let lastError: unknown;

  for (let attempt = 1; attempt <= times; attempt += 1) {
    try {
      return await task();
    } catch (error) {
      lastError = error;
      if (attempt < times) await sleep(delayMs);
    }
  }

  throw lastError instanceof Error ? lastError : new Error("Retry failed");
}

Saat meminta test, sebutkan mock isolation, jangan broad refactor, dan pertahankan last error. Log sementara boleh untuk investigasi, tetapi harus keluar dari patch final kecuali produk memang butuh structured logging.

Contoh 3: reproduksi boundary tanggal sebelum mengubah UI

Contoh ketiga adalah bug batas tanggal. Di layar terlihat seperti export Maret kehilangan order tanggal 31 Maret, tetapi akar masalah biasanya ada pada perbandingan awal bulan yang dipilih dan awal bulan berikutnya.

export type Order = {
  id: string;
  createdAt: string;
  total: number;
};

export function exportMonthlyOrderIds(orders: Order[], month: string): string[] {
  const [yearText, monthText] = month.split("-");
  const year = Number(yearText);
  const monthIndex = Number(monthText) - 1;
  const start = new Date(Date.UTC(year, monthIndex, 1));
  const end = new Date(Date.UTC(year, monthIndex + 1, 1));

  return orders
    .filter((order) => {
      const createdAt = new Date(order.createdAt);
      return createdAt >= start && createdAt < end;
    })
    .map((order) => order.id);
}

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

describe("exportMonthlyOrderIds", () => {
  it("includes orders from the first day through the last moment of the month in UTC", () => {
    const orders = [
      { id: "feb-end", createdAt: "2026-02-28T23:59:59.999Z", total: 1000 },
      { id: "mar-start", createdAt: "2026-03-01T00:00:00.000Z", total: 2000 },
      { id: "mar-end", createdAt: "2026-03-31T23:59:59.999Z", total: 3000 },
      { id: "apr-start", createdAt: "2026-04-01T00:00:00.000Z", total: 4000 },
    ];

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

Beri tahu Claude Code agar tidak bergantung pada timezone lokal. Aturannya: sertakan awal bulan yang dipilih dan kecualikan awal bulan berikutnya.

Prompt debugging siap salin

Goal:
  Temukan penyebab, tambahkan regression test, dan fix dengan diff berguna terkecil.

Observations:
  - Full error:
  - Reproduction steps:
  - Expected behavior:
  - Actual behavior:
  - Recently changed files:

Constraints:
  - Tulis tiga hipotesis sebelum edit.
  - Hindari broad refactor.
  - Jangan sembunyikan type error dengan any.
  - Hapus temporary log di akhir.
  - Jalankan npm test dan npm run typecheck di akhir.

Report:
  - Root cause
  - Files changed
  - Regression test added
  - Remaining risks

Ini mengubah Claude Code menjadi partner investigasi. Reviewer melihat cause, evidence, dan risk sebelum membaca semua diff. Untuk tim, masukkan field yang sama ke review gate agar diff AI dan manusia memakai standar yang sama.

Debugging tanpa merusak revenue path

Pada situs publik, debugging juga harus memeriksa CTA. Fix konten bisa mendorong form PDF gratis ke bawah, mengubah link Gumroad, atau membuat jalur konsultasi sulit ditemukan. Semakin populer artikel, semakin penting revenue routing masuk scope debugging.

Gunakan aturan kecil:

const debuggingRoutes = {
  first_error: "free_pdf",
  repeated_bugfixes: "prompt_templates",
  setup_or_ci_blocked: "setup_guide",
  team_process_blocked: "consultation",
};

export function chooseDebuggingCta(intent) {
  return debuggingRoutes[intent] ?? "free_pdf";
}

console.log(chooseDebuggingCta("repeated_bugfixes"));

free cheatsheet cocok untuk pemula dan pembaca comparison. 50 Prompt Templates cocok untuk debugging dan review berulang. Setup Guide cocok untuk permission, CI/CD, dan setup blocker. Konsultasi cocok untuk rollout tim dan keputusan operasi.

Yang diverifikasi di artikel ini

Rewrite ini menjaga body UTF-8 bersih, code block executable, internal link, external link, serta path PDF gratis, Gumroad, dan konsultasi. Metrik berikutnya adalah PDF signups, klik Prompt Templates, klik Setup Guide, dan Training visits dari slug debugging ini.

Catatan check setelah publikasi

Saat menerbitkan artikel debugging, jangan berhenti pada code correctness saja. Buka URL publik dan cek h1, canonical, awal body, hero image, form PDF gratis, link Gumroad, dan link konsultasi. Pada artikel populer, perbaikan workflow debugging bisa langsung mengubah aksi berikutnya pembaca. Jika penjelasan membaik tetapi PDF signup, produk Gumroad, atau route konsultasi salah, revenue path belum selesai.

Pada versi lokal, contoh code boleh sama, tetapi penjelasan dan CTA harus dalam bahasa target. Pembaca harus memahami urutan observasi, reproduksi, fix, dan test tanpa ganti bahasa. Saat review screenshot, cek opening body, area prompt template, dan area CTA.

Metrik berikutnya adalah registrasi PDF, klik Prompt Templates, klik Setup Guide, dan kunjungan Training dari slug ini. Pembaca debugging punya pain aktif, jadi downstream movement lebih penting daripada PV mentah.