Claude Code से तकनीकी कर्ज सुरक्षित तरीके से घटाने की टीम गाइड

हर टीम कहती है कि तकनीकी कर्ज घटाना है। फिर स्प्रिंट में नए फीचर आ जाते हैं, any बढ़ता जाता है, dependencies पुरानी हो जाती हैं, CI कभी-कभी फेल होता है, और TODO टिप्पणियां स्थायी डिजाइन का हिस्सा बन जाती हैं।

Claude Code ऑटोमेटेड refactoring को जोखिम-मुक्त नहीं बनाता। इसका सही उपयोग यह है कि टीम कर्ज की सूची बनाए, सबूत जोड़े, प्राथमिकता तय करे और सुधार को छोटे, reviewable PR में बांटे। इससे तकनीकी कर्ज एक बड़े खतरनाक cleanup की जगह नियमित engineering प्रक्रिया बनता है।

इस गाइड में code smell inventory, dependency debt, flaky tests (कभी पास, कभी फेल होने वाले unstable tests), duplicated logic, unsafe TODOs, ICE/RICE prioritization, छोटे PR और governance शामिल हैं। आधिकारिक संदर्भ के लिए Claude Code Common workflows, Memory और Settings देखें। ClaudeCodeLab पर संबंधित लेखों में testing strategies, CLAUDE.md best practices और approval and sandbox guide उपयोगी हैं।

कर्ज को repayment loop बनाएं

आम गलती है कि टीम “एक बार में बड़ा refactor” शुरू कर देती है। branch बहुत बड़ी हो जाती है, reviewer behavior change समझ नहीं पाता, और release से पहले काम रुक जाता है।

इसके बजाय छोटा loop चलाएं।

flowchart LR
  A["Inventory"] --> B["Evidence"]
  B --> C["ICE/RICE score"]
  C --> D["Small PRs"]
  D --> E["Tests and review"]
  E --> F["Update register"]
  F --> A

Inventory का मतलब “यह code गंदा लगता है” नहीं है। file path, line number, CI logs, outdated packages, any, large files, duplicated logic और TODO/FIXME जैसे प्रमाण इकट्ठा करें।

तरीका	कब उपयोगी	जोखिम	Claude Code कैसे मदद करता है
बड़ा refactor	स्पष्ट सीमा वाली framework migration	diff review करना मुश्किल	research और migration plan
छोटे debt PR	रोज़मर्रा maintenance	impact छोटा दिख सकता है	register, score और checklist
dependency sprint	security fixes और EOL packages	breaking changes छूट सकते हैं	changelog summary और test plan
flaky test cleanup	CI पर भरोसा कम हो गया	retry असली bug छिपा देता है	failure classification और reproduction

Use case 1: code smells की सूची बनाना

Code smell हमेशा bug नहीं होता। यह संकेत है कि भविष्य में बदलाव मुश्किल होंगे: बहुत बड़ी function, बहुत जिम्मेदारियां वाली class, duplicate validation, magic number, या type system से बचने वाला code।

पहले Claude Code से inspection कराएं, editing नहीं।

claude -p "
src/ और tests/ में technical debt inspect करें। अभी files edit न करें।

इन चीजों को देखें:
- 80 lines से बड़ी functions
- 300 lines से बड़ी files
- 4 levels से गहरी nesting
- duplicated validation, date handling, permission checks
- TypeScript any, as any, @ts-ignore
- TODO / FIXME / HACK comments
- बिना tests वाली branches या केवल rendering check करने वाले tests

Output ऐसी Markdown table हो जिसे docs/tech-debt/register.md में paste कर सकें।
Columns: ID, File, Line, Debt type, Evidence, Risk, Suggested first PR, Confidence.
"

“अभी files edit न करें” लिखना जरूरी है। वरना Claude Code अनुमान के आधार पर बदलाव शुरू कर सकता है। पहले उसे जांच, classification और suggestions तक सीमित रखें; पहली debt item टीम चुने।

Use case 2: dependency debt ढूंढना

पुरानी libraries, unmaintained packages, vulnerabilities और एक ही काम के लिए duplicate libraries भी तकनीकी कर्ज हैं। सिर्फ npm audit count देखना ठीक नहीं है, क्योंकि noisy warning असली EOL risk को छिपा सकती है।

claude -p "
package.json, lockfile, npm outdated और npm audit output के आधार पर dependency debt classify करें।

Categories:
1. Security fix required
2. Major update required with likely breaking changes
3. Unmaintained or replacement recommended
4. Duplicate libraries for the same job
5. Safe to defer

हर item के लिए impact area, पहले पढ़ने वाला changelog, required tests और smallest safe PR लिखें।
Automated changes और human review required changes अलग करें।
"

Dependency update सिर्फ इसलिए सुरक्षित नहीं है कि tests एक बार pass हो गए। date handling, auth, crypto, routing, build tools और test runners को isolated branch और rollback note चाहिए।

Use case 3: flaky tests और duplicate logic चुकाना

Flaky tests CI पर भरोसा खत्म करते हैं। जब टीम सोचने लगे कि “CI फिर से चलाओ, pass हो जाएगा”, test suite सुरक्षा नहीं रह जाती।

claude -p "
पिछले 20 CI failure logs पढ़कर likely flaky tests classify करें।

Classify by:
- Time, timezone, या random data dependency
- Network या external API dependency
- Shared state leaking between tests
- Unstable async waiting
- Likely product bug जिसे flaky नहीं कहना चाहिए

हर candidate के लिए reproduction command, minimal fix और add करने वाली assertion लिखें।
"

Duplicate logic में पहला PR boring होना चाहिए। अगर permission checks चार files में copy हैं, तो पहले pure helper निकालें और behavior को tests से lock करें। call sites बाद के PR में एक-एक करके बदलें।

Copy-paste scanner

Claude Code analysis में मदद करता है, लेकिन mechanical markers script से भी मिलना चाहिए। इसे scripts/debt-scan.mjs में save करें और node scripts/debt-scan.mjs src चलाएं।

import fs from "node:fs";
import path from "node:path";

const root = process.argv[2] || "src";
const maxLines = Number(process.env.MAX_LINES || 300);
const extensions = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"]);
const findings = [];

function walk(dir) {
  if (!fs.existsSync(dir)) return;

  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const fullPath = path.join(dir, entry.name);

    if (entry.isDirectory()) {
      if ([".git", "node_modules", "dist", "build", ".next", "coverage"].includes(entry.name)) continue;
      walk(fullPath);
      continue;
    }

    if (entry.isFile() && extensions.has(path.extname(entry.name))) {
      scanFile(fullPath);
    }
  }
}

function add(file, line, type, severity, detail) {
  findings.push({ file, line, type, severity, detail });
}

function scanFile(file) {
  const text = fs.readFileSync(file, "utf8");
  const lines = text.split(/\r?\n/);

  if (lines.length > maxLines) {
    add(file, 1, "large-file", 3, `${lines.length} lines`);
  }

  lines.forEach((line, index) => {
    const lineNumber = index + 1;

    if (/\b(FIXME|TODO|HACK)\b/i.test(line)) {
      add(file, lineNumber, "unsafe-comment", /FIXME|HACK/i.test(line) ? 4 : 3, line.trim());
    }

    if (/\.(ts|tsx)$/.test(file) && /(:\s*any\b|as\s+any\b|<any>)/.test(line)) {
      add(file, lineNumber, "typescript-any", 4, line.trim());
    }
  });
}

walk(root);

console.log("| file | line | type | severity | detail |");
console.log("| --- | ---: | --- | ---: | --- |");
for (const item of findings.sort((a, b) => b.severity - a.severity || a.file.localeCompare(b.file))) {
  const detail = item.detail.replaceAll("|", "\\|");
  console.log(`| ${item.file} | ${item.line} | ${item.type} | ${item.severity} | ${detail} |`);
}

if (findings.length === 0) {
  console.error("No obvious debt markers found.");
}

यह script architecture नहीं समझती और सारी duplication नहीं पकड़ती। फिर भी यह TODO, FIXME, any और large files के लिए हर हफ्ते एक consistent baseline देती है।

Debt register template

Issues बनाने से पहले findings को एक register में रखें।

# Technical Debt Register

| ID | Area | Evidence | User or team impact | ICE | RICE | Owner | Next PR | Status |
| --- | --- | --- | --- | ---: | ---: | --- | --- | --- |
| TD-001 | Auth permissions | src/auth/guard.ts duplicates role checks in 4 places | New role changes take 2 days and often miss one path | 420 | 1680 | Backend | Extract pure canAccess() with tests | Ready |
| TD-002 | Dependencies | vite is 2 major versions behind | Security patches and plugin updates are blocked | 280 | 900 | Platform | Upgrade in isolated branch and run build/test | Investigating |

## Scoring note

- ICE = Impact x Confidence x Ease
- RICE = Reach x Impact x Confidence / Effort
- Keep evidence links concrete: file path, line, CI run, or user-facing incident.

ICE जल्दी sorting के लिए अच्छा है। RICE तब बेहतर है जब reach और effort भी साफ दिखाना हो। ये formulas absolute truth नहीं हैं; ये discussion को structured बनाते हैं।

Safe refactor plan prompt

Debt item चुनने के बाद edit से पहले plan मांगें।

claude -p "
TD-001 के लिए safe repayment plan बनाएं। अभी files edit न करें।

Scope:
- src/auth/guard.ts
- src/auth/roles.ts
- tests/auth/guard.test.ts

Constraints:
- External API behavior न बदलें
- Existing tests पहले inspect करें
- Behavior under-tested हो तो refactor से पहले characterization tests add करें
- PR को 300 changed lines से कम रखने का लक्ष्य रखें
- Risks, rollback plan और reviewer focus areas लिखें

Output:
1. Current behavior summary
2. Explicit non-goals
3. First PR diff plan
4. Test commands to run
5. PR review request
"

non-goals scope creep रोकते हैं। Claude Code मदद करते हुए सीमा बढ़ा सकता है, इसलिए PR boundary पहले लिखें।

Refactor PR checklist

## Refactor PR checklist

- [ ] This PR changes structure, not product behavior.
- [ ] Existing behavior is covered by tests before the refactor.
- [ ] New helper names describe domain behavior, not implementation detail.
- [ ] Public API, response shape, permissions, and logging are unchanged or explicitly documented.
- [ ] The diff is small enough to review in one sitting.
- [ ] Rollback is simple: revert this PR without reverting unrelated work.
- [ ] The debt register is updated with status and follow-up PRs.

इसे Claude Code से बनवाए गए PR body में शामिल करें। इससे “सिर्फ refactor है” reviewable evidence में बदलता है।

आम pitfalls

Automation पर ज्यादा भरोसा Types pass होना काफी नहीं है। authorization, billing, date logic, async behavior और migrations के लिए characterization tests और human review चाहिए।

सारे TODO हटाना कुछ TODO release blocker हैं, कुछ सिर्फ notes। remove before release, bypass auth, temporary token, FIXME जैसे शब्द पहले देखें।

Dependency updates को एक साथ बांधना दस major updates एक PR में डालने से failure isolate करना मुश्किल होता है। build tools, UI, auth और test runners अलग करें।

Scores को politics बनाना ICE/RICE में evidence होना चाहिए: file path, CI run, incident और effort assumptions।

Team memory न रखना “permission code needs approval” और “refactor PR under 300 lines” जैसी rules CLAUDE.md या settings में रखें। Memory और Settings repeated prompts घटाते हैं।

Team governance

व्यावहारिक cadence है हर सप्ताह 30 मिनट की debt review:

1. Scanner और Claude Code inventory देखें।
2. सिर्फ top 10 items का ICE/RICE update करें।
3. अगले sprint के लिए एक repayment PR चुनें।
4. flaky tests और security dependencies को ज्यादा priority दें।
5. PR के बाद register में लिखें कि क्या आसान हुआ।

ClaudeCodeLab इस workflow को debt register, PR checklist, settings और CLAUDE.md starter rules के रूप में आपकी टीम के लिए तैयार कर सकता है। अपने repository और review culture के अनुसार setup चाहिए तो Claude Code training, templates और consultation देखें।

सारांश

Claude Code से technical debt सुरक्षित तरीके से घटाने का मतलब “सब कुछ refactor करो” नहीं है। सही क्रम है evidence collect करना, score देना और एक छोटे PR में एक debt चुकाना। code smells, dependency debt, flaky tests, duplicated logic और unsafe TODOs एक ही loop में संभाले जा सकते हैं।

इस लेख का workflow Masa के छोटे projects में आज़माने पर सबसे बड़ा लाभ यह था कि urgent debt और सिर्फ record करने वाली debt अलग दिखने लगी। any cleanup और पुराने TODO removal को छोटे PR में बांटने से review load ज्यादा नहीं बढ़ा, लेकिन risky areas कम हुए। Dependency major updates अपेक्षा से भारी निकले, इसलिए Claude Code से सीधे बदलाव करवाने से पहले tests और release notes तैयार करना ज्यादा सुरक्षित रहा।