Claude Code debugging workflow: observation, reproduction, fix, test

Claude Code error message से plausible fix दे सकता है, लेकिन production debugging को केवल plausible patch से ज्यादा चाहिए। Reliable session observation, hypothesis, minimal reproduction, fix और regression test को अलग रखता है। अगर ये steps skip होते हैं, bug एक screen से गायब होकर दूसरे input, language page या deploy path से लौट सकता है।

यह article TypeScript, Node और Vitest पर आधारित है। Failed condition बचानी हो तो Claude Code and TDD देखें। Exception model unclear हो तो error handling patterns देखें। Proof command ही fail हो तो build error triage loop देखें।

Claude Code को investigation order दें

“यह error fix करो” जैसा vague request Claude Code को पहले reasonable patch तक ले जाता है। बेहतर है full error, stack trace, reproduction steps, input shape, expected behavior, actual behavior और recently changed files दें। फिर edit से पहले तीन hypotheses माँगें।

Observation facts रखता है। Hypothesis possible cause बताती है। Minimal reproduction उस hypothesis को failing test या script बनाती है। Fix छोटा रहता है और regression test repository में रहता है। इससे reviewer को context दोबारा build नहीं करना पड़ता।

{
  "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"
  }
}

example 1: undefined map error को rule में बदलें

पहला bug common है: data आने से पहले code map call करता है। Goal केवल crash हटाना नहीं है। Rule यह है कि missing payload empty list बने, blank names हटें और valid names 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"]);
  });
});

Claude Code से ऐसे कहें:

Cannot read properties of undefined (reading 'map') error है।
normalizeUsers को missing API payload tolerate करना है और blank display names हटाने हैं।
पहले failing Vitest case जोड़ें, फिर smallest fix करें।
अंत में npm test और npm run typecheck चलाएँ।

Trap है users ?? [] पर रुक जाना। इससे crash रुक सकता है, लेकिन null names, blank strings और non-array payload का behavior undefined रहता है। Claude Code को exception ही नहीं, product rule भी दें।

example 2: async retry अंतिम error न छिपाए

Async retry bugs intermittent लगते हैं। अच्छा test call count, wait behavior, eventual success और total failure देखता है। Final error swallow हो जाए तो incident response असली failed service तक नहीं पहुँचती।

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");
}

Testing माँगते समय mock isolation, broad refactor न करने और last error preserve करने को लिखें। Temporary logs investigation में ठीक हैं, लेकिन final patch से हटने चाहिए, जब तक structured logging product requirement न हो।

example 3: date boundary को पहले reproduce करें

तीसरा use case date boundary bug है। UI में यह ऐसा दिखता है कि March export में March 31 के orders missing हैं, लेकिन root cause अक्सर button में नहीं, selected month start और next month start की comparison में होता है।

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"]);
  });
});

Claude Code को बताएं कि local timezone parsing पर depend नहीं करना है। Rule simple है: selected month का start include करें और next month का start exclude करें।

copy-paste debugging prompt

Goal:
  cause खोजें, regression test जोड़ें, और smallest useful diff से fix करें।

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

Constraints:
  - edit से पहले तीन hypotheses लिखें
  - broad refactor न करें
  - any से type errors न छिपाएँ
  - temporary logs अंत में हटाएँ
  - अंत में npm test और npm run typecheck चलाएँ

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

इससे Claude Code patch generator नहीं, investigation partner बनता है। Reviewer हर line पढ़ने से पहले cause, evidence और remaining risk देख सकता है। Team में यही fields review gate में डालें, ताकि AI और human diff पर same standard लगे।

debugging में revenue path न टूटे

Public site debugging में CTA भी check करें। Content fix free PDF form को नीचे धकेल सकता है, Gumroad link बदल सकता है, या consultation path को कम visible बना सकता है। Article जितना popular हो, revenue routing को debugging scope में उतना ही रखना चाहिए।

छोटी rule उपयोग करें:

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"));

Beginners और comparison readers के लिए free cheatsheet सही है। Repeated debugging और review के लिए 50 Prompt Templates सही है। Permissions, CI/CD और setup blockers के लिए Setup Guide सही है। Team rollout और operating decisions के लिए consultation सही है।

इस article में क्या verify किया

इस rewrite में clean UTF-8 body, executable code blocks, internal links, external links और free PDF, Gumroad, consultation path शामिल हैं। Next metrics हैं PDF signups, Prompt Templates clicks, Setup Guide clicks और Training visits from this debugging slug.

publish के बाद debugging check

Debugging article publish करते समय केवल code correctness पर न रुकें। Public URL खोलकर h1, canonical, opening body, hero image, free PDF form, Gumroad links और consultation links देखें। Popular article में debugging workflow improvement reader के next action को सीधे बदल सकता है। Explanation बेहतर है लेकिन PDF signup, Gumroad product या consultation route गलत है, तो revenue path incomplete है।

Localized versions में code examples shared हो सकते हैं, पर explanation और CTA target language में होने चाहिए। Reader को observation, reproduction, fix और test का order बिना language switch किए समझ आना चाहिए। Screenshot review में opening body, prompt template area और CTA area देखें।

Next metrics हैं free PDF registrations, Prompt Templates clicks, Setup Guide clicks और Training page visits from this slug। Debugging readers के पास active pain होता है, इसलिए raw PV से ज्यादा downstream movement मायने रखता है। Next rewrite से पहले ये numbers Claude Code को दें।