Claude Code बिल्ड त्रुटि जाँच चक्र: 15 मिनट में कारण सीमित करें

fix मांगने से पहले error को बांटें

Node, Astro, Vite या Next.js build fail हो तो पूरा log Claude Code में paste करके “सब ठीक कर दो” कहना आसान लगता है। पर पूरे log में पहली failing line, बाद की stack trace, package manager noise और unrelated cleanup साथ मिल जाते हैं। Build pass हो सकता है, लेकिन review में यह साफ नहीं रहता कि असली कारण किस change से ठीक हुआ।

यह article bug report template, review workflow checklist और verification receipt workflow को build error पर लागू करता है। लक्ष्य बड़ा repair नहीं है। लक्ष्य है 15 मिनट में cause को एक hypothesis तक सीमित करना, सबसे छोटा fix करना और proof छोड़ना।

Harness का अर्थ यहां agent का काम करने वाला आधार है। Claude Code repository पढ़ता है और reason करता है, लेकिन कौन सा log देखना है, कौन सी hypothesis allow है और कौन सा command proof देगा, यह पहले human तय करता है। यही आधार build fix को broad refactor बनने से रोकता है।

flowchart LR
  A[State] --> B[Build log]
  B --> C[First failing line]
  C --> D[One hypothesis]
  D --> E[Small fix]
  E --> F[Proof command]
  F --> G[Receipt]

15 मिनट का loop

काम को तीन पांच-मिनट blocks में बांटें। पहला block सिर्फ evidence है: git status, failing build command, पहली failing line और related files। अभी file edit न करें। दूसरा block एक hypothesis चुनता है: dependency, import path, frontmatter, data shape, permission, network या test expectation drift.

तीसरे block में ही code या config बदलें। उसके बाद failing command फिर चलाएं और proof लिखें। Content या revenue site में green build पर्याप्त नहीं है। Article URL, h1, canonical, hero image, CTA, product link और training link भी check करें। Build pass होकर conversion तोड़ दे तो वह production problem ही है।

Masa की work note तीन lines रखती है: cause, change, evidence. Reviewer को लंबे explanation से अधिक यह चाहिए कि hypothesis क्यों चुनी, क्या बदला और कौन सा command या URL proof है। Claude Code से अंत में यही तीन lines मांगना next failure को तेज बनाता है।

evidence हमेशा same order में लें

हर बार same order रखें। macOS, Linux या WSL पर यह shell example log save करता है और exit code preserve करता है।

git status --short
npm run build 2>&1 | tee build.log
status=${PIPESTATUS[0]}
if [ "$status" -ne 0 ]; then
  grep -Ein "error|failed|ERR_|Cannot|TypeError" build.log | head -n 20
  exit "$status"
fi
npm test -- --runInBand

Windows PowerShell में npm.cmd explicit रखें, क्योंकि अलग shell में npm resolve अलग हो सकता है।

$ErrorActionPreference = "Continue"
git status --short
npm.cmd run build *> build.log
$buildExit = $LASTEXITCODE

if ($buildExit -ne 0) {
  Select-String -Path build.log -Pattern "error|failed|ERR_|Cannot|TypeError" |
    Select-Object -First 20
  exit $buildExit
}

npm.cmd test -- --runInBand

पहला run pass होना जरूरी नहीं। उसका काम पहली useful failure बचाना है। Last stack trace अक्सर consequence होती है; पहली error line root cause के पास होती है।

Node से पहली failure classify करें

नीचे script को scripts/triage-build-log.mjs में save करें और node scripts/triage-build-log.mjs build.log चलाएं। यह code ठीक नहीं करता; यह बड़े log को एक bucket और next diagnostic में बदलता है।

#!/usr/bin/env node
import { readFileSync } from "node:fs";

const logPath = process.argv[2];

if (!logPath) {
  console.error("Usage: node scripts/triage-build-log.mjs build.log");
  process.exit(1);
}

const rules = [
  { name: "dependency or import path", regex: /Cannot find module|ERR_MODULE_NOT_FOUND|Cannot resolve/i },
  { name: "runtime null or shape mismatch", regex: /TypeError:.*undefined|undefined is not|Cannot read/i },
  { name: "test expectation drift", regex: /Expected.*received|AssertionError|Snapshot/i },
  { name: "permission or sandbox boundary", regex: /EACCES|EPERM|permission denied/i },
  { name: "Astro content or frontmatter", regex: /frontmatter|content collection|InvalidContentEntry|MDX/i },
];

const lines = readFileSync(logPath, "utf8").split(/\r?\n/);
const firstFailure = lines.find((line) => /error|failed|ERR_|Cannot|TypeError/i.test(line));
const matchedRule = rules.find((rule) => firstFailure && rule.regex.test(firstFailure));

console.log(JSON.stringify({
  firstFailure: firstFailure || "No obvious failure line found",
  bucket: matchedRule ? matchedRule.name : "needs manual reading",
  nextDiagnostic: matchedRule
    ? "Run one command that proves or disproves this bucket before editing files."
    : "Read the 30 lines before the first failure and classify manually.",
}, null, 2));

Classification perfect होना जरूरी नहीं। इसका लाभ यह है कि prompt “build fix करो” से बदलकर “edit से पहले इस bucket को prove या disprove करो” बन जाता है। इससे dependency upgrade, wide null checks और unrelated cleanup कम होते हैं।

official docs से boundary रखें

Claude Code की connection, auth, limits और runtime messages के लिए Claude Code Error reference देखें। अगर CLAUDE.md, settings, hooks या MCP load नहीं हो रहे लगें, तो Debug your configuration देखें।

Astro content site में frontmatter और content collection issues के लिए Astro Content Collections को आधार बनाएं। ERR_MODULE_NOT_FOUND जैसे Node codes के लिए Node.js Errors देखें। इससे Claude Code session issue, app build issue और Node runtime issue अलग रहते हैं।

log shape के हिसाब से पहला कदम

log shape	पहले क्या शक करें	पहला कदम
Cannot find module	import path, generated file, dependency	package add से पहले file और path check करें
ERR_MODULE_NOT_FOUND	ESM/CJS, extension, package exports	Node error और package config compare करें
undefined is not	data shape, frontmatter, API response	null check से पहले एक real record print करें
Expected ... received	spec change, fixture, snapshot	intended change या regression classify करें
permission denied	sandbox, CI user, write path	working directory और permission check करें
सिर्फ Build failed	ऊपर की first error	last trace नहीं, first error निकालें

Astro article site में undefined is not an object का कारण किसी locale में missing heroImage, pubDate या lang हो सकता है। Global guard build pass करा सकता है, लेकिन editorial quality issue छिपा देगा।

Claude Code prompt

इस failed build log को पढ़ें।
broad refactors suggest न करें।
अभी files edit न करें।

लौटाएं:
1. पहली failing line
2. सबसे likely cause, केवल एक
3. इस cause को verify करने वाला smallest diagnostic command
4. allowed smallest code या config change
5. fix के बाद proof command
6. PR के लिए तीन lines: cause, change, evidence

जब same repository में और लोग काम कर रहे हों, scope जोड़ें: केवल यह slug, reports न छुएं, unrelated changes revert न करें, frontmatter identity fields preserve करें। यह boundary conflict रोकती है।

चार practical use cases

पहला case Astro multilingual content site है। एक locale का invalid frontmatter, unclosed MDX code fence, missing hero image या गलत internal link build गिरा सकता है। Claude Code से कहें कि target slug की केवल 10 files compare करे और YAML, fences, body length validate करे।

दूसरा case Node CLI या package import failure है। Cannot find module हमेशा dependency missing नहीं होता। Typo, generated file missing, exports rule या ESM/CJS mix भी कारण हो सकते हैं। Dependency change से पहले node -p "require.resolve('package-name')" या direct file check करें।

तीसरा case CI-only failure है। Permission, case-sensitive path, different Node version, गलत secret name या missing proxy कारण हो सकते हैं। App code बदलने से पहले CI OS, working directory, Node version, env vars और write targets list करें।

चौथा case test expectation drift है। Expected ... received snapshot update से छिप सकता है, पर regression approve हो सकती है। CTA, price copy, Gumroad link, training form या article metadata में पहले तय करें कि change intended था या नहीं।

common pitfalls

पहला pitfall है log का अंत ही पढ़ना। Final stack trace consequence हो सकती है। पहली failing line और उससे पहले की 30 lines save करें।

दूसरा pitfall है dependency जल्दी upgrade करना। Package update lockfile, CI cache और runtime compatibility को छूता है। अगर cause import path typo था, review unnecessary बड़ा हो जाता है।

तीसरा pitfall है green build पर रुकना। Public site में /en/products/, /en/training/, free PDF form, h1 और canonical भी confirm करें।

चौथा pitfall है opportunistic cleanup. Build-fix PR में hypothesis visible होनी चाहिए। Formatting, refactor, dependency और content rewrite मिलेंगे तो proof गायब हो जाएगा।

product और training CTA

इस loop को reusable prompts, checklists और setup material में बदलना हो तो ClaudeCodeLab products देखें। Team को CI gates, CLAUDE.md, permission rules, review receipts और production verification real repository पर लागू करनी हो तो Claude Code training and consultation बेहतर है।

आगे पढ़ने के लिए permission audit checklist और CI/CD setup उपयोगी हैं। Individual practice के लिए free PDF commands fix करता है; team adoption में shared prompt, shared proof format और approval owner जरूरी हैं।

test करने पर क्या बदला

इस loop से diff छोटा होता है। Claude Code को पूरा log देने के बजाय session एक failing line, एक hypothesis और एक proof command से शुरू होता है। इससे missing frontmatter, generated file gap, import path typo और CI permission issue जल्दी अलग होते हैं। सबसे बड़ा लाभ पहला fix नहीं, बल्कि next failure के लिए बचा हुआ छोटा evidence है।