Claude Code से दूसरे की code में घुसने का पहला घंटा: नक्शा बनाएं, फिर ठीक करें

Handover के पहले दिन मैंने वह internal tool वाली repository खोली जो पिछले developer ने छोड़ी थी. README सिर्फ तीन लाइन का था, और आखिरी update आठ महीने पुराना. मैंने बस Claude Code से कहा, “इस project को समझो और login screen का text ठीक कर दो.” पाँच मिनट बाद उसने login text के साथ-साथ authentication के config files और वह production deploy वाली script भी “बीच में आ ही गई, इसलिए साफ कर दी” — जिसे महीनों से किसी ने छुआ तक नहीं था.

अच्छा हुआ कि git status से मुझे पता चल गया और मैंने सब वापस लौटा दिया. पर सोचता हूँ कि अगर बिना देखे git commit कर देता तो — आज भी रीढ़ में सिहरन दौड़ जाती है. दिक्कत model के बुद्धिमान होने में नहीं थी. दिक्कत यह थी कि मैंने यह तय किए बिना ही काम सौंप दिया कि कहाँ छूना ठीक है और कहाँ नहीं.

दूसरे की code में घुसने का पहला घंटा ठीक करने का समय नहीं होता, नक्शा बनाने का समय होता है. इस article में मैं वही नक्शा बनाने का तरीका बता रहा हूँ — ऐसा क्रम जिससे पहली बार खोली गई repository में भी हादसा न हो.

मुख्य बातें

• पहला घंटा “ठीक करने” का नहीं, “नक्शा बनाने” का है. कहाँ छूना ठीक है और कहाँ नहीं, यह पहले अलग करें.
• Claude Code को सिर्फ “पढ़कर सूची बनाने” तक का काम दें. किसे protected area बनाना है, यह इंसान तय करे.
• fix शुरू करने से पहले एक verify command (build या test) जरूर तय करें. यही “ठीक हो गया” का सबूत बनता है.
• पहला fix सिर्फ उतना छोटा रखें जिसे git के एक command से वापस लौटाया जा सके.
• जो समझा, उसे एक पन्ने के note में रखें. ताकि अगली बार इसी repository में आने वाला (आने वाला आप खुद भी) वही जाँच दोबारा न करे.

पहले घंटे में हादसा क्यों होता है

नई repository में अटकना अक्सर code की कठिनाई से नहीं होता. होता है इसलिए कि repository की बनावट दिखती ही नहीं.

कौन-सा folder screen है, कहाँ पीछे की logic है, कौन-सी file production का config है — यह जाने बिना “अच्छे से ठीक कर दो” कहने पर Claude Code नेक नीयत से बड़े दायरे में बदलाव कर देता है. AI को जब तक न कहो “यहाँ मत छूना,” तब तक वह मान लेता है कि छूना ठीक है.

Handover वाले काम खास तौर पर खतरनाक हैं. पिछले developer के अनकहे नियम, naming की आदतें, और वह comment-out किया हुआ code जो न जाने क्यों पड़ा है — यह context code में कहीं लिखा नहीं होता. इंसान भी पहले दिन सब नहीं समझ पाता. इसीलिए सबसे पहला काम editing नहीं, नक्शा बनाना होना चाहिए.

नक्शा बनाने के 4 step

क्रम मायने रखता है. पहले पढ़ने का दायरा तय करें, फिर protected area तय करें, फिर verify command तय करें, और आखिर में जाकर एक छोटा-सा fix करें. इसी क्रम में आगे बढ़ें.

Step 1: आज का लक्ष्य एक वाक्य में लिखें

“इस project को समझना है” बहुत चौड़ा है. इतने बड़े लक्ष्य में Claude Code और इंसान, दोनों यह भूल जाते हैं कि रुकना कहाँ है.

इसके बजाय ऐसे लिखें: “login screen का text सिर्फ एक जगह ठीक करना है और build pass होना confirm करना है.” जो लक्ष्य एक वाक्य में कहा जा सके, उसका पूरा होना भी एक नजर में दिख जाता है.

Step 2: पढ़ने का दायरा और न छूने का दायरा अलग करें

यही नक्शे का केंद्र है. Claude Code को “सब पढ़ सकते हो” देने से पहले, न छूने वाली जगहें पहले शब्दों में लिख दें.

मैं हर बार जिन्हें protected area में डालता हूँ वे हैं: authentication, billing, environment variable file (.env), और production deploy की script. ये गलत हो जाएँ तो नुकसान बड़ा होता है, और वापस लौटाना भी मुश्किल. इसलिए शुरू में साफ कह देता हूँ — “पढ़ना ठीक है, लिखना मत.”

Step 3: verify command पहले तय करें

“ठीक हो गया” कह दिया गया, तो किस आधार पर मानें कि सच में ठीक हुआ? यह पहले ही तय कर लें.

ज्यादातर project में build command या test command ही verify का काम करते हैं. npm run build pass हो, npm test हरा हो जाए. यह एक command fix से पहले तय कर लें, तो Claude Code के “हो गया” पर आँख मूँदकर भरोसा करने के बजाय machine के pass/fail से फैसला किया जा सकता है.

Step 4: सिर्फ एक छोटा reversible fix

नक्शा बन जाए, तो पहले fix में लालच न करें. text का सुधार, comment जोड़ना, या साफ दिख रहा typo ठीक करना — जैसा कुछ जिसे git checkout के एक झटके में वापस लौटाया जा सके, ऐसा एक चुनें.

“बीच में यह भी कर ही दूँ” वाली ललक रोकें. बड़े diff को कोई review नहीं कर पाता, और हादसा हो तो वापस लौटाना भी भारी पड़ता है.

Claude Code को क्या सौंपें, और इंसान क्या तय करे

नक्शा बनाते समय क्या सौंपना है और क्या अपने हाथ में रखना है — यहाँ गड़बड़ी होते ही शुरुआत वाला हादसा होता है.

काम	जिम्मेदारी	वजह
file सूची और folder बनावट समझना	Claude Code	यांत्रिक पढ़ाई तेज और सटीक है
”यह feature कहाँ है?” की खोज	Claude Code	search और summary इसका मजबूत पक्ष है
किसे protected area बनाना है	इंसान	नुकसान कितना बड़ा है यह context पर निर्भर; AI नहीं जानता
verify command का अंतिम फैसला	इंसान	project की खास बातें इंसान ही जानता है
production / billing / auth में बदलाव	इंसान	जो वापस लौटाना मुश्किल हो, उसे इंसान मंजूर करे

सिद्धांत सीधा है. पढ़ना और सूची बनाना सौंप दें. जो फैसला वापस लौटाना मुश्किल हो, उसे इंसान अपने हाथ में रखे. जिन operations को safe साबित कर लें, सिर्फ उन्हें बाद में Claude Code को बढ़ाकर दें.

permission का बारीक design मैंने अलग article में रखा है. शुरू में क्या रोकना है, इसमें उलझन हो तो permissions guide देख लें.

कॉपी-पेस्ट के लिए नक्शा-बनाने वाला prompt

पहले घंटे में मैं सच में यही prompt भेजता हूँ. इसे जस का तस paste करें और सिर्फ repository का नाम अपना बना लें.

इस repository को पहली बार छू रहा हूँ. अभी कुछ भी edit मत करना.
नीचे की चीजें क्रम से जाँचो और नतीजा bullet points में बताओ.

1. top-level folder बनावट और हर folder की भूमिका (अनुमान चलेगा, पर अनुमान लिखकर बताना)
2. build / test / start के लिए वाले commands (package.json या README से)
3. authentication / billing / environment variable / production deploy से जुड़ी files कहाँ हैं
4. "login screen का text" किस file में है

रिपोर्ट के बाद, 3 वाली files इस बार "सिर्फ पढ़ना, edit मना" रहेंगी.
edit सिर्फ 4 में मिली एक file में करनी है.

खास बात यह है कि पहली ही लाइन में “अभी edit मत करना” की कील ठोक दें. यह न हो तो कुछ AI जाँच के बीच ही ठीक करना शुरू कर देते हैं.

कॉपी-पेस्ट से चलने वाला verify script

नक्शा बन जाए, तो fix के पहले और बाद वही जाँच दोबारा चला सकें, इसका इंतजाम रखें तो निश्चिंती रहती है. नीचे की script देखती है कि बदलाव से पहले-बाद build pass होता है या नहीं, और diff हद से ज्यादा फैला तो नहीं. यह Node.js पर चलती है.

// verify-edit.mjs
// fix से पहले-बाद build pass होता है या नहीं, और diff सोची हुई हद से बड़ा तो नहीं — यह जाँचता है
import { execSync } from "node:child_process";

// एक command से वापस लौटाने लायक दायरा हो, इसलिए बदली गई file की संख्या की हद तय कर लें
const MAX_CHANGED_FILES = 3;

function run(cmd) {
  return execSync(cmd, { encoding: "utf8" }).trim();
}

try {
  // बदली गई files की संख्या गिनें
  const changed = run("git diff --name-only")
    .split("\n")
    .filter(Boolean);

  console.log(`बदली गई files: ${changed.length}`);
  changed.forEach((f) => console.log(`  - ${f}`));

  if (changed.length > MAX_CHANGED_FILES) {
    console.error(
      `diff बहुत बड़ा है (${changed.length} > ${MAX_CHANGED_FILES}).`,
    );
    console.error("एक बार git checkout से वापस लौटाएँ और fix को छोटे हिस्सों में बाँटें.");
    process.exit(1);
  }

  // protected area में हाथ तो नहीं लगा, यह जाँचें
  const protectedHits = changed.filter((f) =>
    /(^|\/)\.env|auth|billing|deploy/i.test(f),
  );
  if (protectedHits.length > 0) {
    console.error("protected area में बदलाव हुआ है:");
    protectedHits.forEach((f) => console.error(`  - ${f}`));
    process.exit(1);
  }

  // build pass होता है या नहीं, यह जाँचें (अपने project के हिसाब से बदल लें)
  console.log("build जाँच रहे हैं...");
  run("npm run build");
  console.log("build ठीक. fix safe दायरे में है.");
} catch (err) {
  console.error("verify नाकाम रहा:", err.message);
  process.exit(1);
}

node verify-edit.mjs से चलाएँ. बदली गई files ज्यादा हों, या protected area में हाथ लगा हो, तो यह वहीं रुक जाती है. शुरुआत वाला “authentication file तक साफ हो गई” हादसा, अगर इस script से गुजारा होता तो वहीं रुक जाता.

तीन जगहें जहाँ यह काम आता है

ठोस रूप में किन repositories में काम आता है, मेरे आजमाए हुए तीन pattern बता रहा हूँ.

1. handover में मिला internal tool बिना documentation वाली codebase में घुसते समय. पहले folder बनावट और start command की सूची बनवाएँ, और authentication व config files को protected area में fix कर दें. पहला fix ऐसा रखें जिसका नतीजा दिखे — जैसे admin screen का label बदलना.

2. public repository में पहला contribution किसी और के open source में पहली बार Pull Request भेजते समय. पहले test command पता करवाएँ, और npm test हरा रहते हुए एक छोटा fix भेजें. बड़े-बड़े सुधार के सुझावों से ज्यादा, वापस लौटाने लायक एक file का fix स्वीकार होने की संभावना ज्यादा रहती है.

3. पुराने project को फिर से चालू करना छह महीने से पड़े code को दोबारा शुरू करते समय. “कहाँ तक चलता है” यह Claude Code से जँचवाएँ, और जो रास्ते टूटे हैं उन्हें नक्शे पर लाएँ. ठीक उसी जगह से करें जिसे लौटाना सबसे आसान हो.

आम pitfall और उन्हें ठीक करना

Pitfall 1: एक बार में सब कुछ ठीक करने की कोशिश “बीच में refactor भी कर दूँ” से diff 50 files तक फूल जाए, तो कोई review नहीं कर पाता. ठीक करने का तरीका — ऊपर वाली verify script में बदली गई files की संख्या की हद रखें. हद पार हो तो एक बार लौटाकर हिस्सों में बाँटें.

Pitfall 2: सिर्फ build pass होने को पूरा मान लेना local पर build pass हो जाए, इसका मतलब यह नहीं कि screen वैसी ही है जैसी सोची थी. text का fix हो तो उस screen को सच में खोलकर अक्षर आँखों से जाँचना — यह पूरा एक set है.

Pitfall 3: protected area सिर्फ मुँह से बताना “authentication मत छूना” prompt में कह भी दें, तो लंबे काम के बीच यह भूल जाया जा सकता है. ठीक करने का तरीका — verify script से protected area के बदलाव यांत्रिक रूप से रोकें. इंसानी याददाश्त नहीं, command से बचाव करें.

Pitfall 4: बनाए नक्शे को न रखना एक घंटा लगाकर समझ भी लें, पर note न रखें तो अगली बार वही जाँच दोबारा करनी पड़ती है. folder बनावट, verify command, और protected area एक पन्ने के note में लिख रखें तो आने वाला आप खुद बच जाएँगे.

वह नक्शा-note, project के नियम के तौर पर CLAUDE.md में लिख दें तो और असरदार हो जाता है. लिखने का तरीका मैंने CLAUDE.md best practices में रखा है.

अक्सर पूछे जाने वाले सवाल

Q. पहले घंटे में सच में कुछ भी ठीक न करूँ तो चलेगा? A. ठीक करें तो हर्ज नहीं, पर ठीक सिर्फ “वापस लौटाने लायक छोटी एक जगह” ही करें. बाकी समय नक्शा बनाने में लगाना, नतीजे में हादसा कम करके तेज भी निकलता है.

Q. Claude Code को “सब पढ़ सकते हो” देना खतरनाक है? A. सिर्फ पढ़ना खतरनाक नहीं है. खतरा “लिखने” की permission में है. पढ़ना चौड़ा, लिखना संकरा — यही बँटवारे का मूल है.

Q. जिस project का verify command पता न हो, उसमें क्या करूँ? A. पहले Claude Code से package.json या README से उम्मीदवार बताने को कहें. फिर भी पता न चले, तो फिलहाल git status में कोई diff न आना — इतना ही न्यूनतम verify मान लें.

Q. PowerShell में भी यही हो सकता है? A. हाँ. git diff --name-only के नतीजे गिनकर हद से तुलना करने वाली logic, PowerShell में भी वैसी ही लिखी जा सकती है. verify script को अपने environment के हिसाब से बदल लें.

Q. क्या यह तरीका शुरुआती भी चला सकते हैं? A. चला सकते हैं. बल्कि शुरुआती के लिए ज्यादा असरदार है. code पूरी तरह समझे बिना भी, “छूना ठीक कहाँ है” पहले तय कर लें तो बड़ा हादसा रुक जाता है. बुनियाद से पकड़ना चाहें तो शुरुआती guide पहले पढ़ लें, तो आगे आसान रहेगा.

असल में आजमाने का नतीजा

यह तरीका शुरुआत वाले हादसे के बाद मैंने अपने लिए बनाया था. आजमाकर सबसे ज्यादा जो काम आया, वह था verify script में “बदली गई files की संख्या की हद” और “protected area की अपने-आप जाँच” डालना.

सच में, handover में मिली repository पर इसे तीन बार चलाया, तो एक बार बदली गई files की संख्या हद पार कर गई और script रुक गई. अंदर देखा तो Claude Code text के fix के साथ-साथ common component तक बदल बैठा था — अगर वह pass हो जाता तो ऐसा diff बनता जिसका असर समझ ही नहीं आता. रुक जाने की वजह से मैं fix को दो हिस्सों में बाँटकर भेज पाया.

“बुद्धिमान AI को सौंप दो तो ठीक रहेगा” नहीं, बल्कि “गिर भी जाएँ तो वापस लौटा सकें, उतने दायरे में सौंपो.” नक्शा पहले बना लेने भर से पहले घंटे का एहसास ही बदल जाता है. जो engineer नहीं हैं और team में यह बँटवारा बाँटना चाहते हैं, उनके लिए non-engineers के लिए शुरुआत भी काम का है.

Claude Code का आधिकारिक इस्तेमाल Anthropic की official documentation में भी देखा जा सकता है. अपने operating नियम पक्के करके team में दोहराने लायक रूप देना चाहें, तो training / consultation में हम आपकी असल repository का नक्शा साथ मिलकर बनाएँगे.