Claude Code Error Diagnosis: Logs से Regression Tests तक

Error diagnosis का मतलब terminal की आखिरी लाल line देखकर अंदाजे से code बदलना नहीं है। असली काम है failure को ऐसी evidence में बदलना जिसे दूसरा developer, test runner या Claude Code दोबारा reproduce कर सके।

तीन शब्द पहले समझ लें। Log वह record है जो command या app output करता है। Stack trace function calls का रास्ता दिखाता है जहां से error तक पहुंचे। Minimal reproduction वह सबसे छोटा example है जो unrelated UI, data और config हटाने के बाद भी fail होता है।

Claude Code से सिर्फ “fix this” कहने पर बदलाव बहुत बड़े हो सकते हैं। बेहतर है कि failed command, पहली failing line, सीमित hypotheses और fix के बाद चलने वाला verification command साथ दें।

Diagnosis Flow

flowchart LR
  A["Failed command save करें"] --> B["पहली failing line खोजें"]
  B --> C["तीन hypotheses तक सीमित करें"]
  C --> D["Minimal repro बनाएं"]
  D --> E["Regression test जोड़ें"]
  E --> F["सबसे छोटा fix करें"]
  F --> G["उसी command से verify करें"]
  G --> H["Handoff note लिखें"]

यह order इसलिए जरूरी है क्योंकि पहले edit और बाद में proof करने से accidental fixes बनते हैं। Claude Code बहुत files पढ़ सकता है, इसलिए broad instruction देने पर वह unrelated cleanup भी कर सकता है। Diagnosis का goal ज्यादा बदलाव नहीं, बल्कि root cause narrow करना है।

पहले चार evidence collect करें।

Evidence	क्यों जरूरी है	Claude Code को example
Failed command	Reproduction fix करता है	`npm run build`, `node --test`
First failing line	Log tail noise हटाता है	`TypeError`, `ERR_MODULE_NOT_FOUND`
Runtime context	Environment difference अलग करता है	Node.js version, OS, CI
Expected behavior	सही fix define करता है	null empty array बने, 404 retry न हो

JavaScript errors के नाम समझने के लिए MDN JavaScript error reference देखें। Node.js में Node.js Errors docs useful हैं, क्योंकि stable diagnosis में message text के बजाय error.code बेहतर होता है। E2E tests में Playwright debugging docs Inspector, Trace Viewer और VS Code debugging समझाते हैं।

Claude Code Workflow

Real failure के लिए यह prompt use करें।

claude -p "
Diagnose the following error.

1. Confirm the failing command
2. Separate the first failure from unrelated log noise
3. List up to three root-cause hypotheses
4. Create a minimal reproduction
5. Add a regression test
6. Apply the smallest fix
7. Verify with the same command and write a handoff note

Constraints:
- Do not perform unrelated refactors
- Explain any public API change before making it
- Do not call the fix complete if verification still fails
"

“Up to three” important है। दस hypotheses से जांच फैल जाती है। Cannot read properties of undefined के लिए common hypotheses हैं: API shape बदल गया, initial value missing है, या async data आने से पहले render हो रहा है।

Use Case 1: React undefined error

Common case है कि API null लौटाती है और UI users.map(...) call करता है। Error React render जैसा दिखता है, पर root cause data shape contract होता है।

// user-list.mjs
export function names(users) {
  if (!Array.isArray(users)) {
    return [];
  }

  return users.map((user) => user.name ?? "(no name)");
}

// user-list.test.mjs
import assert from "node:assert/strict";
import test from "node:test";
import { names } from "./user-list.mjs";

test("names returns an empty array when the API returns null", () => {
  assert.deepEqual(names(null), []);
});

test("names keeps valid user names", () => {
  assert.deepEqual(names([{ name: "Masa" }]), ["Masa"]);
});

node --test user-list.test.mjs

अगर old code सिर्फ return users.map(...) था, पहला test fail होगा। Claude Code से पहले failing test add करवाएं, फिर smallest fix करवाएं।

Use Case 2: Node.js ENOENT और import failures

ENOENT आम तौर पर file या directory missing होने पर आता है। Trap यह है कि config/local.json laptop पर मौजूद होता है, पर CI या Docker image में नहीं।

Failed command, error.code, error.path, Dockerfile COPY, .gitignore और CI working directory देखें।

claude -p "
Diagnose this Node.js ENOENT failure.
Inspect error.code, error.path, current working directory, Dockerfile, and CI config.
Suggest only fixes that do not depend on a local-only file.
"

“Missing file बना दो” पर न रुकें। Config mandatory है तो startup पर clear error दें। Optional है तो default रखें। CI को sample चाहिए तो repository में checked-in sample file copy करें।

Use Case 3: Playwright CI-only failure

Playwright timeout में app bug, गलत wait condition, slow CI, expired auth या network difference mix हो सकते हैं। Timeout बढ़ाना अक्सर cause hide करता है।

Failure पर traces रखें।

// playwright.config.ts
import { defineConfig } from "@playwright/test";

export default defineConfig({
  use: {
    screenshot: "only-on-failure",
    trace: "retain-on-failure",
    video: "retain-on-failure",
  },
});

Claude Code को failing spec, locator, expected screen state, trace path और CI command दें। Instruction रखें: “timeout बढ़ाने से पहले UI state, API response, auth और locator problem अलग करें।“

Use Case 4: TypeScript cascading errors

बीस TypeScript errors का मतलब बीस bugs नहीं होता। एक API type change से बाकी derived errors आ सकते हैं।

npx tsc --noEmit --pretty false 2>&1 | tee tsc.log
claude -p "
Read tsc.log and choose the first type error to fix.
Separate derived errors from the likely root cause.
After the fix, verify with npx tsc --noEmit --pretty false.
"

सब कुछ एक साथ fix न करें। पहले root type ठीक करें, वही command फिर चलाएं, फिर remaining errors देखें। इससे unnecessary as any कम होते हैं।

Logs को पहले classify करें

यह छोटा script सीधे run हो सकता है और log को first bucket देता है।

// triage-log.mjs
import fs from "node:fs";

const sample = `
TypeError: Cannot read properties of undefined (reading 'map')
    at ProductList (src/ProductList.tsx:42:18)
`;

const input = process.argv[2]
  ? fs.readFileSync(process.argv[2], "utf8")
  : sample;

const rules = [
  [/ERR_MODULE_NOT_FOUND|Cannot find module/i, "dependency or import path"],
  [/ENOENT/i, "file path or working directory"],
  [/TypeError:.*undefined|Cannot read properties/i, "data shape or initial value"],
  [/Timeout.*expect|locator/i, "E2E wait condition or screen state"],
  [/TS\d{4}/, "TypeScript type error"],
];

const matches = rules
  .filter(([pattern]) => pattern.test(input))
  .map(([, label]) => label);

console.log(matches.length ? matches.join("\n") : "Unclassified: inspect first failure");

node triage-log.mjs
node triage-log.mjs tsc.log

यह complete diagnosis नहीं है। इसका काम है dependency, path, data shape, E2E wait और TypeScript errors को बातचीत शुरू होने से पहले अलग करना।

Reproducible Bug Report Template

Claude Code से investigation मांगने से पहले bug को इस format में लिखें। GitHub Issues में official GitHub issue forms syntax से यही fields form बन सकते हैं।

## Summary
Describe the broken behavior in one sentence.

## Failed command
`npm run build`

## Expected result
The build succeeds and creates `dist/`.

## Actual result
The command fails with `TypeError: Cannot read properties of undefined`.

## First failing line
`src/components/ProductList.tsx:42:18`

## Reproduction steps
1. `npm ci`
2. `npm run build`

## Environment
- Node.js: 22.x
- OS: Windows 11 / GitHub Actions ubuntu-latest
- Branch: feature/product-list

## Already tried
- Regenerated lockfile
- Checked API response fixture

## Verification after fix
- `node --test`
- `npm run build`

मुख्य बात “कुछ टूट गया है” नहीं, बल्कि “इन steps से वही failure reproduce होता है” है।

Common pitfalls

पहला, सिर्फ log की आखिरी line paste करना। First failure और उसके आसपास की lines रखें।

दूसरा, message text पर branch करना। Node.js में possible हो तो error.code या name use करें।

तीसरा, minimal repro skip करना। Full page में debugging करने से पता नहीं चलता कि cause fix हुआ या timing बदली।

चौथा, regression test के बिना fix करना। अगली refactor में bug वापस आ सकता है।

पांचवां, Claude Code को बहुत broad scope देना। सिर्फ इस specific failure को pass कराने वाला smallest change मांगें। Team review boundaries के लिए Claude Code review workflow checklist देखें।

Handoff note लिखें

Verification pass होने पर short note छोड़ें।

## Diagnosis note
- Failure: `npm run build`
- Cause: `users.map` was called when the API returned null
- Fix: Normalize non-array input to an empty array in `names()`
- Regression test: `node --test user-list.test.mjs`
- Verification: `npm run build` passed
- Remaining risk: Confirm separately whether API null is intentional

claude -p "
Write a Markdown diagnosis note for this fix.
Include cause, changed files, regression test, verification command,
and remaining risk. Keep it short enough for a reviewer to read in five minutes.
"

Templates और consulting

Solo project में इस article के commands और templates copy करना काफी है। Team में यह तय करें कि कौन से logs share हो सकते हैं, कौन से secrets Claude Code में नहीं जाने चाहिए, minimal repro कहां रहेगा, CI artifacts कौन से mandatory हैं और reviewer कौन सा proof मांगेगा।

ClaudeCodeLab Claude Code products and templates और Claude Code training and consultation देता है। Teams bug report forms, CI triage prompts, regression-test patterns और handoff notes को standardize कर सकती हैं।

Masa ने ClaudeCodeLab maintenance में यह workflow अपनाया तो सबसे बड़ा improvement तीन habits से आया: first failing line बचाना, minimal reproduction बनाना और fix के बाद वही command चलाना। Claude Code की suggestions अनुमान नहीं रहीं; वे evidence, hypothesis, test और verification result के साथ आने लगीं।