Claude Code प्लान मोड: डिज़ाइन रिव्यू-फर्स्ट रीफैक्टरिंग लूप्स

कई डेवलपर Claude Code का इस्तेमाल एक ही तरह से शुरू करते हैं: कोई टास्क पेस्ट करें, उसे चलने दें, और डिफ की समीक्षा करें। यह छोटे बदलावों के लिए काम करता है, लेकिन जैसे ही कई फाइलों में बदलाव पड़ता है, चीजें बिगड़ने लगती हैं। 

Claude द्वारा लिया गया हर बिना-निर्देश वाला निर्णय अधिकतर बार सही हो सकता है, जो ठीक लगता है—जब तक आप उसके योगफल को न देखें: मान लीजिए प्रति निर्णय 80% शुद्धता है; 20 निर्णय बिंदुओं वाले किसी फीचर में 0.8^20 आपको लगभग 1% तक पहुँचा देता है।

प्लान मोड पढ़ने-भर के चरण को जोड़कर यह गणित बदल देता है। आप Claude को कोडबेस पढ़ने, प्रश्न उठाने, और एक ऐसा प्लान बनाने के लिए बाध्य करते हैं जिसे आप किसी एक फाइल को छुए बिना पहले समीक्षा करते हैं। 

यह ट्यूटोरियल उसी वर्कफ़्लो को एक बिखरे हुए FastAPI ब्लॉग API के उदाहरण से समझाता है, जिसमें Explore-Plan-Execute लूप, Ctrl+G से प्लान एडिटिंग, और Agent Teams के साथ बड़े रीफ़ैक्टर तक स्केल करना शामिल है। 

हमारा Claude Code सर्वश्रेष्ठ प्रथाएँ ट्यूटोरियल संयोजित त्रुटि समस्या को विस्तार से समझाता है, और Claude Code 2.1 गाइड इंस्टॉलेशन और फीचर्स के बारे में बताता है यदि आपको सेटअप में मदद चाहिए।

Claude Code के पीछे के मॉडलों के बारे में अधिक जानकारी के लिए, हमारे Claude Sonnet 4.6 और Opus 4.6 गाइड देखें, या हमारा Introduction to Claude Models कोर्स करें।

Claude Code प्लान मोड क्या है?

प्लान मोड Claude को केवल-पढ़ने के ऑपरेशनों में लॉक कर देता है। यह फाइलें पढ़ सकता है, कोडबेस में खोज सकता है, और आपसे सवाल पूछ सकता है, लेकिन फाइल लिखने, कोड एडिट करने, या शेल कमांड चलाने की किसी भी कोशिश को मना कर दिया जाता है। प्लान मोड में रहते हुए उससे "बस एक छोटी-सी फिक्स कर दो" कह कर देखें—वह नहीं करेगा।

आप इसे चार तरीकों से सक्रिय कर सकते हैं:

• इनपुट फ़ील्ड में Shift+Tab दो बार दबाने से Normal, Auto-Accept, और Plan Mode के बीच साइकिल होता है

• /plan कमांड प्लान मोड में डाल देता है जब तक आप फिर मोड न बदलें

• --permission-mode plan CLI फ्लैग नई सत्र को प्लान मोड में शुरू करता है

• settings.json में permissions.defaultMode के तहत एंट्री प्लान मोड को आपका स्थायी डिफॉल्ट बनाती है

जब Claude प्लान बनाना पूरा कर लेता है, तो यह नतीजे को ~/.claude/plans/ में एक मार्कडाउन फाइल के रूप में एक रैंडम नाम (जैसे dreamy-orbiting-quokka.md) के साथ सेव कर देता है। 

यह फाइल एक रिव्यू योग्य कॉन्ट्रैक्ट है: यह सत्रों के पार बनी रहती है, /clear और कॉन्टेक्स्ट कंपैक्शन दोनों से बची रहती है, और जब तक आप मंजूरी न दें, कुछ भी लागू नहीं होता। ध्यान दें कि प्लान फाइल खुद तो बनी रहती है, लेकिन कॉन्टेक्स्ट कंपैक्शन के बाद, जब तक आप उसे प्लान फिर से पढ़ने के लिए न कहें, Claude कभी-कभी उसका ट्रैक खो सकता है।

यदि आप वर्शन कंट्रोल के लिए अपने प्रोजेक्ट के अंदर प्लान सहेजना चाहते हैं, तो settings.json में plansDirectory को ./plans जैसे किसी प्रोजेक्ट-रिलेटिव पाथ पर सेट करें।

प्रोजेक्ट-रिलेटिव प्लान ऐसे वर्कफ़्लो खोलते हैं जिन्हें ~/.claude/plans/ सपोर्ट नहीं कर सकता:

• किसी के कोडिंग शुरू करने से पहले पुल रिक्वेस्ट में प्लान डिफ़्स की समीक्षा करें
• कॉन्टेक्स्ट कंपैक्शन पर निर्भर हुए बिना एनोटेशन को सत्रों के पार आगे बढ़ाएँ
• मार्कडाउन फाइल को एक जीवंत स्पेसिफिकेशन की तरह ट्रीट करें जिसे टीम के कई सदस्य सीधे एडिट करें

लंबे समय तक चलने वाले रीफैक्टर या मल्टी-सत्र कार्य के लिए, वर्शन-कंट्रोल्ड प्लान फाइल आपको केवल Ctrl+G से कहीं अधिक नियंत्रण देता है।

Claude Code Explore-Plan-Execute वर्कफ़्लो लागू करना

यह देखने के लिए कि ये तीनों चरण कैसे साथ काम करते हैं, हम fastapi-blog-api रिपो को रीफैक्टर करेंगे। इसमें कोई टेस्ट शामिल नहीं हैं और तीन फाइलें हैं जो हर एक जरूरत से ज्यादा काम करती हैं: 

• main.py: सभी रूट्स, इनलाइन ऑथ चेक, हार्डकोडेड कॉन्फ़िग, ईमेल भेजना

• models.py: ORM मॉडल, Pydantic स्कीमा, क्वेरी फ़ंक्शंस, सीड डेटा

• utils.py: पासवर्ड हैशिंग, JWT टोकन, S3 अपलोड, मार्कडाउन रेंडरिंग, कैशिंग, रेट लिमिटिंग, CSV एक्सपोर्ट

चरण 1: सबसे पहले संदर्भ एकत्र करें

टास्क को प्लान मोड में शुरू करें (पहले GitHub रिपो को लोकली क्लोन करें)। शुरुआती प्रॉम्प्ट में Claude को बताना चाहिए कि आप क्या चाहते हैं और उसे संबंधित फाइलें पढ़ने के लिए निर्देशित करना चाहिए:

I want to refactor this FastAPI blog API into a clean module structure with proper separation of concerns and full test coverage. Read through main.py, models.py, and utils.py first. Map out which functions belong together, flag any shared state or circular dependency risks, and identify what needs testing most.

Claude कोडबेस रिसर्च को केवल-पढ़ने वाले टूल्स तक सीमित बिल्ट-इन सबएजेंट को सौंपता है। इसने सभी तीन फाइलें पढ़ीं, उनके बीच इम्पोर्ट्स को ट्रेस किया, और अस्पष्टताओं को सामने लाने के लिए AskUserQuestion का उपयोग किया। 

प्रश्नों ने कुछ उच्च-स्तरीय निर्णयों को कवर किया:

• आर्किटेक्चरल गहराई (फ्लैट राउटर्स बनाम पूर्ण सर्विस लेयर्स)
• हार्डकोडेड कॉन्फ़िग को कैसे संभालें
• क्या मृत यूटिलिटी फ़ंक्शंस हटाए जाएँ या रखे जाएँ
• कौन-सा टेस्ट फ़्रेमवर्क इस्तेमाल करें

ये सवाल मायने रखते हैं। सिर्फ आर्किटेक्चर का सवाल ही मानव इनपुट के बिना सिक्का उछालने जैसा होता। Claude डिफॉल्ट रूप से उसी पैटर्न पर जाता है जो इसे ट्रेनिंग डेटा में सबसे ज़्यादा दिखा हो—जो FastAPI के लिए आमतौर पर फ्लैट राउटर स्ट्रक्चर है। यहाँ "सर्विस लेयर का उपयोग करें" कहना आगे की एक पूरी री-रीफैक्टरिंग राउंड बचा गया।

यदि आपके पास कोई संदर्भ प्रोजेक्ट है जो आपके लक्षित आर्किटेक्चर से मेल खाता है, तो उसका लिंक अपने प्रॉम्प्ट में शामिल करें। Claude तब बेहतर प्लान बनाता है जब उसके पास अमूर्त विवरणों की बजाय एक काम करता उदाहरण होता है।

किसी भी प्लान को स्वीकार करने से पहले एक चीज़ जाँचें: क्या Claude के सवाल विशिष्ट फ़ंक्शंस और लाइन-स्तरीय विवरणों का हवाला देते हैं, या सिर्फ फाइल नामों का? यदि वह "ऑथ सिस्टम" के बारे में पूछता है लेकिन verify_jwt_token या main.py में मिडलवेयर चेन का ज़िक्र नहीं करता, तो उसने फाइलों को ध्यान से पढ़ने की बजाय सरसरी निगाह दौड़ाई है। चरण 2 पर जाने से पहले उसे अधिक ध्यान से पढ़ने के लिए प्रेरित करें।

चरण 2: प्लान जनरेट करें और एडिट करें

आपके सवालों के जवाब देने के बाद Claude अपने-आप एक प्लान जनरेट करता है। अलग प्रॉम्प्ट की ज़रूरत नहीं होती। प्लान ~/.claude/plans/ में सेव होता है और इसमें शामिल होते हैं: 

• संदर्भ का सार-संक्षेप
• लक्षित डायरेक्टरी संरचना
• कदम-दर-कदम इम्प्लीमेंटेशन क्रम
• सत्यापन अनुभाग जिसमें रीफैक्टरिंग के काम करने की पुष्टि के लिए कमांड्स हों

आगे कैसे बढ़ना है यह चुनने से पहले Ctrl+G दबाकर अपने डिफॉल्ट टेक्स्ट एडिटर ($EDITOR द्वारा सेट) में प्लान खोलें। वैकल्पिक रूप से, सक्रिय प्लान फाइल सीधे खोलने के लिए /plan open का उपयोग करें।

यही वह चरण है जहाँ प्लान मोड अपनी कीमत वसूलता है। आप स्टेप्स में इनलाइन नोट्स जोड़ सकते हैं, जिन चरणों से आप सहमत नहीं हैं उन्हें हटा सकते हैं, ऑपरेशंस का क्रम बदल सकते हैं, और सेव कर सकते हैं। टर्मिनल पर लौटते ही Claude हर संपादन को पकड़ लेता है।

ब्लॉग API प्लान के लिए, एनोटेशन कुछ ऐसे दिख सकते हैं:

## Step 3: Extract auth module
Move JWT validation and password hashing to auth/
> NOTE: extract auth middleware BEFORE splitting routes,
> otherwise the route files will import from utils.py
> and we'll have to update imports twice
 
## Step 5: Database layer
Create a repository pattern for database operations
> NOTE: keep the SQLAlchemy session factory in a shared
> db.py, don't put it in models.py

जटिल प्लानों के लिए, सिर्फ एक Ctrl+G पास पर्याप्त नहीं हो सकता। एनोटेट करें, वापस आएँ, Claude से कहें "प्लान में सभी एनोटेशंस को संबोधित करें, अभी इम्प्लीमेंट मत करें," संशोधित संस्करण की समीक्षा करें, और फिर Ctrl+G करें। हर राउंड वह अस्पष्टता कम करता है जो अन्यथा किसी गलत इम्प्लीमेंटेशन निर्णय में बदल जाती।

एक बार कॉन्ट्रैक्ट सही लगे, Claude कुछ विकल्प देता है: 

1. प्लान पर काम करें और कॉन्टेक्स्ट साफ करें (अच्छा है जब सत्र बासी हो रहा हो), 
2. साफ किए बिना काम करें (संवाद इतिहास बनाए रखने के लिए), या 
3. प्लान पर बातचीत जारी रखें। 

चयन इस आधार पर करें कि आपने कितना कॉन्टेक्स्ट बनाया है। यदि आप लंबे सत्र में गहरे हैं, तो क्लियर करना Claude को निष्पादन के लिए एक ताज़ा विंडो देता है।

चरण 3: स्वीकृत प्लान को निष्पादित करें

कोई वर्क विकल्प चुनें, और Claude चरण दर चरण इम्प्लीमेंट करना शुरू कर देता है। यह हर स्टेप से गुजरता है और तब रुकता है जब उसे मैनुअल हस्तक्षेप (जैसे टर्मिनल में इंटरैक्टिव ऑथ) की आवश्यकता होती है या जब पूरा प्लान पूरा हो जाता है।

ड्रिफ्ट पर नज़र रखें। प्लान ने पहले ऑथ को अलग मॉड्यूल में निकालने को कहा था, लेकिन Claude कोई शॉर्टकट देखकर रूट्स और ऑथ लॉजिक दोनों को एक साथ खींचना शुरू कर सकता है। इस तरह की हरकत से आधा-माइग्रेटेड कोडबेस बन जाता है जहाँ कुछ इम्पोर्ट पुराने स्थान की ओर और कुछ नए की ओर इशारा करते हैं। 

अन्य ड्रिफ्ट संकेत: 

• वर्तमान स्टेप में उल्लेखित न होने वाली फाइल को एडिट करना
• प्लान द्वारा खुला छोड़ा गया कोई आर्किटेक्चर निर्णय चुपचाप लेना
• दो ऐसे स्टेप्स को मिला देना जिन्हें प्लान ने अलग रखा था

जब ड्रिफ्ट हो, तो Shift+Tab दबाकर वापस प्लान मोड में जाएँ। Claude वर्तमान फाइल स्थिति पढ़ता है, शेष चरणों के लिए एक संशोधित प्लान बनाता है, और आप आगे बढ़ने से पहले उसे समीक्षा करते हैं। यह कोई आपातकालीन उपाय नहीं है। अधिकांश मल्टी-फाइल रीफैक्टर्स पूरा होने से पहले 2-3 प्लान संशोधनों से गुजरते हैं।

ऐसे रीफैक्टर्स जो एक ही सत्र में नहीं समा पाते, उनके लिए एक बड़े प्लान की बजाय काम को क्रमिक प्लानों में बाँटें। ऑथ एक्सट्रैक्शन को उसके अपने प्लान के तहत पूरा करें, फिर नया सत्र और रूट स्प्लिटिंग के लिए ताज़ा प्लान शुरू करें। 

/rename का उपयोग करके प्रत्येक सत्र को लेबल करें (जैसे, "blog-api-auth-extraction") ताकि आप /resume के साथ वहीं से फिर शुरू कर सकें। छोटे प्लान कॉन्टेक्स्ट विंडो को केंद्रित रखते हैं और चरणों के बीच एक स्वाभाविक चेकपॉइंट देते हैं।

Claude Code प्लान मोड के व्यावहारिक उपाय

अब जब हमने पूरा प्रोसेस एक बार देख लिया है, तो कुछ सर्वश्रेष्ठ प्रथाएँ देखते हैं ताकि सुनिश्चित हो कि आप प्लान मोड का पूरा लाभ उठा रहे हैं।

कब प्लान मोड उपयोग करें (और कब छोड़ दें)

हर टास्क को प्लान की ज़रूरत नहीं होती। सिंगल-लाइन फिक्स, टाइपो सुधार, और अलग-थलग फ़ंक्शन अपडेट बिना प्लानिंग ओवरहेड के तेज़ होते हैं। यही बात मैकेनिकल बदलावों पर भी लागू होती है, जैसे किसी फाइल में एक वेरिएबल का नाम बदलना।

एक अच्छा नियम: यदि बदलाव तीन या अधिक फाइलों को छूता है, या आप पूरे बदलाव को एक वाक्य में नहीं बता सकते, तो पहले प्लान करें। तीन फाइलें वही सीमा हैं जहाँ संयोजित त्रुटियाँ डसना शुरू करती हैं, क्योंकि हर फाइल अपने-अपने फैसलों का सेट जोड़ती है जिन्हें Claude को सही लेना होता है।

वे टास्क जो हमेशा प्लान मोड से लाभ पाते हैं:

• ऐसे रीफैक्टर्स जो कोड को फाइलों के बीच ले जाते हैं या साझा इंटरफेसेज़ का नाम बदलते हैं
• ऐसी नई फीचर्स जो मौजूदा मॉड्यूल्स को छूती हैं
• ब्रेकिंग API चेंजेज़ के साथ डिपेंडेंसी अपग्रेड्स
• कोई भी टास्क जहाँ आपको यकीन न हो कि कोडबेस किसी विशेष मामले को कैसे संभालता है
• ब्रेनस्टॉर्मिंग सत्र जहाँ आप Claude के साथ किसी दृष्टिकोण पर इटरेट करना चाहते हैं बिना समय से पहले एडिट्स के जोखिम के

कमज़ोर प्लानों को समय रहते पकड़ना

संरचित दिखने वाला प्लान हमेशा अच्छा नहीं होता। मौजूदा Claude Code वर्ज़नों में, काल्पनिक फाइल संदर्भ और अस्पष्ट "ज़रूरत पड़ने पर अपडेट करें" जैसे स्टेप दुर्लभ हैं। समस्या जो अधिकतर मिलती है, वह है ऐसा प्लान जो सारे इम्प्लीमेंटेशन स्टेप्स पहले रख देता है और अंत में "टेस्ट जोड़ें" टाँक देता है।

इस तरह संरचित प्लान अपेक्षा से भी बुरे नतीजे देते हैं। इम्प्लीमेंटेशन के दौरान टेस्ट न होने पर, Claude के पास मध्य-सत्र में अपने काम को सत्यापित करने का कोई तरीका नहीं होता। ब्लॉग API रीफैक्टरिंग के लिए, ऐसा प्लान जो कहता है "स्टेप 1-6: सभी मॉड्यूल निकालें, स्टेप 7: टेस्ट लिखें"—मतलब छह स्टेप्स का कोड बिना किसी फ़ीडबैक लूप के। 

एक मजबूत प्लान टेस्ट-ड्रिवन डेवलपमेंट (TDD) अपनाता है और टेस्टिंग को इम्प्लीमेंटेशन के साथ मिलाता है: auth/ के लिए फ़ंक्शंस निकालने से पहले टेस्ट लिखें, उनके पास होने की पुष्टि करें, फिर posts/ के लिए रूट्स निकालने से पहले टेस्ट लिखें। हर पास होता टेस्ट Claude को स्पष्ट संकेत देता है कि रीफैक्टरिंग सही दिशा में है। 

अपने प्रोजेक्ट की CLAUDE.md में TDD परंपराएँ जोड़ने से Claude डिफॉल्ट रूप से टेस्ट स्टेप्स शामिल करता है। Claude Code Hooks ऐसे प्रवर्तन को स्वचालित कर सकते हैं, जो प्लान की गुणवत्ता को मंज़ूरी से पहले जाँचने वाले वैलिडेशन स्क्रिप्ट्स चलाते हैं।

Agent Teams के साथ बड़े रीफैक्टर्स को स्केल करना

ऐसे प्लान जो सात या अधिक फाइलों को छूते हैं, निष्पादन के दौरान कॉन्टेक्स्ट विंडो भरने के कारण गुणवत्ता खोने लगते हैं। ब्लॉग API रीफैक्टरिंग इस सीमा को छूता है जब आप रूट्स, मॉडल्स, सर्विसेज़, कॉन्फ़िग, टेस्ट्स, और नई डायरेक्टरी संरचना गिनते हैं।

Agent Teams एक प्रायोगिक फीचर है जो इस तरह के काम को कई Claude Code इंस्टैंसेज़ में विभाजित करता है। एक सत्र टीम लीड की तरह काम करता है जबकि प्रत्येक टीममेट को अपना स्वतंत्र कॉन्टेक्स्ट विंडो मिलता है। 

ब्लॉग API के लिए, आप तीन टीममेट्स में बाँट सकते हैं: एक रूट एक्सट्रैक्शन संभाले, एक डेटाबेस और मॉडल लेयर संभाले, और एक टेस्ट कवरेज का मालिक हो। लीड टास्क असाइन करता है, टीममेट्स उन्हें क्लेम और पूरा करते हैं, और ब्लॉक हुए टास्क (जैसे "मॉड्यूल्स निकालो" पर निर्भर "इम्पोर्ट्स अपडेट करो") डिपेंडेंसी पूरी होते ही अपने-आप अनब्लॉक हो जाते हैं। 

यही बाँट रिपॉजिटरीज़ के पार भी काम करता है: यदि आपका API किसी साझा लाइब्रेरी पर निर्भर है, तो एक टीममेट लाइब्रेरी को रीफैक्टर कर सकता है जबकि दूसरा API की खपत को अपडेट करता है।

प्लान मोड के लिए बेहतरीन सेटअप है टीममेट्स के लिए प्लान अप्रूवल आवश्यक करना। लीड से कहें: "ब्लॉग API रीफैक्टरिंग के लिए तीन टीममेट्स स्पॉन करें। किसी भी बदलाव से पहले प्लान अप्रूवल आवश्यक करें।" 

1. हर टीममेट केवल-पढ़ने वाले मोड में प्लान करता है
2. लीड समीक्षा करता है और फीडबैक के साथ स्वीकृत या अस्वीकृत करता है
3. केवल स्वीकृत प्लान निष्पादित होते हैं

आप लीड के निर्णय को मानदंड देकर आकार दे सकते हैं: "सिर्फ वही प्लान स्वीकृत करें जिनमें टेस्ट कवरेज शामिल हो" या "ऐसे प्लान अस्वीकार करें जो सीधे डेटाबेस स्कीमा में बदलाव करें।" Agent Teams को सक्रिय करने के लिए अपने settings.json के env ब्लॉक में "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" जोड़ें।

प्रायोगिक फ़्लैग के बिना सरल पैरेललाइज़ेशन के लिए, git worktrees आपको अलग-अलग ब्रांचों पर अलग-अलग प्लान मोड सत्र चलाने देते हैं, जहाँ हर एक अपना प्लान स्वतंत्र रूप से पूरा करता है।

यदि कोई लंबा सत्र कॉन्टेक्स्ट कंपैक्शन से गुजरता है, तो टीममेट्स को स्पष्ट रूप से अपनी प्लान फाइलें फिर से खोलकर पढ़ने के लिए कहें ताकि ड्रिफ्ट से बचा जा सके।

Claude Code प्लगइन्स ट्यूटोरियल मल्टी-फेज़ कार्य को प्रबंधित करने के लिए अतिरिक्त पैटर्न कवर करता है।

निष्कर्ष

प्लान मोड की उपयोगिता एक बात पर आ टिकती है: निष्पादन से पहले समीक्षा। आपके द्वारा जोड़ा गया हर एनोटेशन राउंड, Claude द्वारा अंदाज़ा लगाने के बजाय पूछे गए हर सवाल, एक ऐसे निर्णय को हटा देता है जो गलत निकल सकता था। 

अपने अगले मल्टी-फाइल बदलाव से शुरू करें, Claude को पहले प्लान करने के लिए बाध्य करें, और लिखने की अनुमति देने से पहले Ctrl+G के साथ उस प्लान को एडिट करें। CLAUDE.md कॉन्फ़िगरेशन, कॉन्टेक्स्ट मैनेजमेंट, और हुक-आधारित गार्डरेल्स के लिए, सर्वश्रेष्ठ प्रथाएँ ट्यूटोरियल यहीं से आगे बढ़ता है। 

AI-सहायता प्राप्त कोडिंग की व्यापक तस्वीर के लिए, मैं हमारे AI for Software Engineering स्किल ट्रैक की जाँच करने की सलाह देता हूँ, जो आपको बुनियादी अवधारणाएँ सिखाता है और GitHub Copilot, Windsurf, या Replit जैसे समान टूल्स में हाथ-से-हाथ अनुभव देता है।