Tips & Tricks (अपडेट: 3/6/2026)

Claude Code bug report template: vague bug को reproducible fix में बदलें

Claude Code के लिए repro steps, logs, environment, failing test और PR handoff वाला practical template.

Claude Code bug report template: vague bug को reproducible fix में बदलें

अगर आप Claude Code को सिर्फ “page broken है” या “tests fail हो रहे हैं” बताते हैं, तो वह अनुमान से शुरू करता है। पहला patch ठीक दिख सकता है, लेकिन उसमें root cause, verification command और PR reviewer के लिए जरूरी context छूट सकता है। अच्छा bug report vague complaint को reproducible debugging task में बदलता है।

यह guide Claude Code sessions के लिए practical template देती है: symptom, expected behavior, actual behavior, minimum reproduction, logs, environment, failing test, constraints और PR handoff। इसे first task runbook के बाद इस्तेमाल करें, deeper investigation के लिए debugging techniques पढ़ें, और fix के बाद PR quality checklist से review करें।

Official references भी पास रखें: CLI reference, commands reference, common workflows, और GitHub Actions guide। इनसे --verbose, /debug, /feedback, /bug और PR automation का सही उपयोग साफ होता है।

Useful report में क्या होना चाहिए

Fieldक्या लिखेंClaude Code को क्या मिलता है
Symptomकौन सा page, command, route या API टूटता हैinvestigation का entry point
Expectedसही business या UI rule”fixed” की definition
Actualerror text, status, visual issue, wrong outputfacts, guesses नहीं
Reproductionसबसे छोटा failing pathhypothesis test करने का तरीका
EnvironmentOS, runtime, browser, branch, env nameslocal और CI difference
Evidencelogs, screenshot, stack trace, failing testbefore/after proof
Constraintsक्या edit करना है और क्या नहींछोटा diff
Handoffroot cause, verification, risk, follow-upfaster PR review

सबसे आम mistake expected behavior छोड़ना है। “error हटा दो” requirement नहीं है। API empty list दे, 400 दे, user warning दिखाए या retry करे? इसे testable sentence में लिखें।

Copy-paste template

इसे bug-report.md के रूप में save करें, खाली जगह भरें, फिर Claude Code को दें।

# 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

यह internal ticket, support handoff और PR comment में काम आता है। मुख्य बात है: Claude Code edit करे उससे पहले success criteria तय करें।

Context collect करने के लिए runnable script

Branch name, Node version और current diff manually लिखते समय छूट जाते हैं। यह dependency-free Node script basic context collect करती है और obvious secrets mask करती है।

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

Run करें:

mkdir -p scripts
# ऊपर वाला code scripts/collect-bug-context.mjs में save करें
node scripts/collect-bug-context.mjs > bug-context.json

Masking सिर्फ safety layer है। Real API keys, customer data या full production logs paste न करें।

Use case 1: mobile CTA overflow

Weak report:

Mobile page broken है।

Useful report:

Symptom:
  390px viewport में pricing CTA right side से बाहर निकलता है।

Expected behavior:
  दोनों CTAs vertical stack हों और horizontal scroll न आए।

Minimum reproduction:
  1. Chrome DevTools में width 390px करें
  2. affected page खोलें
  3. pricing section तक scroll करें

Evidence:
  document.documentElement.scrollWidth is 412
  Screenshot attached

Constraints:
  Product links और copy न बदलें। सिर्फ CSS/layout inspect करें।

अब Claude Code width, gap, button text और parent containers देख सकता है। Monetized pages में products और training path भी verify करें।

Use case 2: checkout API 500 देता है

API bug में request shape, expected response, actual error और config names जरूरी हैं।

Symptom:
  POST /api/checkout सिर्फ plan=pro पर 500 देता है।

Expected behavior:
  200 और payment URL लौटे। Config missing हो तो clear setup error मिले।

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:
  STRIPE_SECRET_KEY और PRICE_PRO_ID use होते हैं। Values paste न करें।

Constraints:
  Real provider calls न बढ़ाएँ। पहले config loading और input validation check करें।

Claude Code से तीन hypotheses compare कराएँ: config loading, request validation, price mapping। अगर local reproduction है, failing test handler या config module में बन सकता है।

Use case 3: date boundary regression

Timezone और month-end bugs में screenshot से ज्यादा useful failing test होता है।

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

Instruction साफ रखें: “इस test को पहले fail कराओ, फिर local timezone पर depend किए बिना implementation fix करो।” Common pitfall है UI date label ठीक कर देना, लेकिन aggregation boundary गलत छोड़ना।

Claude Code investigation prompt

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

Official common workflows भी error, reproduction command, steps और intermittent/consistent nature बताने को कहते हैं। /debug Claude Code session diagnose करता है। /feedback और /bug Claude Code product issue के लिए हैं, आपकी app bug report के लिए नहीं।

PR handoff template

## 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:

इसे session handoff template और testing strategies के साथ जोड़ें।

Common pitfalls

Unrelated bugs को एक report में न मिलाएँ। Login, checkout और layout अलग reproductions मांगते हैं।

Full logs paste न करें। Error के आस-पास 20 lines, request ID और reproduction command काफी होते हैं।

Boundary, data mapping, API contract या permission bug को failing test के बिना finish न करें।

Claude Code से “सब देखो” न कहें। छोटी reproduction broad edit permission से बेहतर है।

PR handoff न छोड़ें। Reviewer को cause, proof और remaining risk चाहिए।

Monetization path भी verify करें

ClaudeCodeLab जैसे content site में bug fix CTA, product cards, free PDF form, Gumroad links या consultation links तोड़ सकता है। Article layout या product route बदलने पर इन्हें verification scope में रखें।

Individual use के लिए free checklist को अपने repository के हिसाब से adapt करें। Reusable prompts, review gates और setup material चाहिए तो products देखें। Team को bug reports, Claude Code permissions, PR review और CI handoff standardize करना हो तो training से शुरू करें।

Practical result

Practical testing में reproduction steps, expected behavior, failing test और PR handoff वाले reports ने vague “please fix” prompt की तुलना में छोटे diffs और कम review questions दिए। सबसे बड़ा improvement edit से पहले तीन hypotheses मांगने से आया। गलत रास्ते जल्दी हटे और session guessing patch से evidence-based debugging में बदल गया।

#claude-code #debugging #bug report #template #triage #communication
मुफ़्त

मुफ़्त PDF: Claude Code cheatsheet

Email डालें और commands, review habits तथा safe workflow वाली एक-page PDF पाएँ.

हम आपका data सुरक्षित रखते हैं और spam नहीं भेजते.

Masa

लेखक के बारे में

Masa

Claude Code workflow और team adoption पर काम करने वाला engineer.

संबंधित लेख