Claude Code में अटके हुए टास्क: retry कब रोकें और स्थिति कैसे बहाल करें

Claude Code के साथ काम करते समय अनियंत्रित retry loop टोकन की फिजूल खपत, संदर्भ की गुणवत्ता घटने और कोडबेस खराब होने के बड़े कारणों में से एक है। जब एजेंट को लगातार टेस्ट फेल होने, ज़रूरी environment variable न मिलने या उन्हीं फ़ाइलों में गोल-गोल बदलाव करने जैसी समस्या मिलती है, तो बिना किसी नए बाहरी संकेत के फिर से कोशिश करना मूल कारण नहीं सुधारता; वह सत्र को और गहरे गतिरोध में धकेल देता है।

सही रणनीति है कि इस चक्र को जल्दी रोका जाए, API और कोडबेस दोनों स्तरों पर विफलता को वर्गीकृत किया जाए, वास्तविक repository स्थिति को दर्ज किया जाए और एक निश्चित सत्यापन कदम के साथ टास्क बहाल किया जाए।

---

1. विफलताओं का वर्गीकरण: retry कब काम नहीं करता

हर त्रुटि केवल कमांड दोबारा चलाने से ठीक नहीं होती। स्पष्ट निदान न हो तो अस्थायी API सीमा को एजेंट के तर्कगत चक्र से भ्रमित करना आसान है:

विफलता का प्रकार	संकेत	retry का व्यवहार	सुझाया गया समाधान
अस्थायी नेटवर्क समस्या / 429	थोड़ी देर का API timeout या rate limit	अधिकतम 3 प्रयासों तक exponential backoff के साथ उपयोगी हो सकता है	बाहरी API कॉल को रोककर कुछ देर बाद दोहराएँ
तर्कगत गतिरोध	एजेंट उन्हीं 2 फ़ाइलों को बार-बार बदलता है	बेकार: गलत धारणा फिर दोहराई जाती है	सत्र रोकें (Ctrl+C) और git diff जाँचें
अनुमति / environment त्रुटि	Permission denied, .env गायब	बेकार: environment अपने-आप नहीं बदलेगा	अनुमति या स्थानीय configuration हाथ से ठीक करें
आर्किटेक्चर का असंगत होना	अमान्य schema के कारण integration test विफल	बेकार: योजना बदलनी होगी	बदलाव वापस लें और prompt की सीमा स्पष्ट करें

अनुमान लगाकर टोकन खर्च करने से बचने के लिए बाहरी API समस्या को कोड की खामी से अलग करें। BetterToken की Claude Code गाइड के अनुसार API workflow में आप Dashboard में अनुरोध का status, इस्तेमाल किया गया model, अनुरोध का समय तथा input, output और cached prompt token की खपत देख सकते हैं। यदि API gateway timeout या 429 दे रहा है, तो सीमित retry उचित हो सकता है; लेकिन API लगातार 200 OK दे रहा हो और एजेंट चक्रीय बदलाव करता रहे, तो सत्र तुरंत बंद करें।

---

2. बहाली के लिए प्राथमिकता क्रम

जब एजेंट लगातार 2–3 निष्फल प्रयास कर चुका हो, तो यह क्रम अपनाएँ:

एजेंट retry loop में प्रवेश करता है
  │
  ├─> चरण 1: तुरंत रोकें (Ctrl+C)
  │
  ├─> चरण 2: Git स्थिति जाँचें (git status --short, टूटी फ़ाइलें वापस लें)
  │
  ├─> चरण 3: मूल कारण वर्गीकृत करें (API metrics बनाम एजेंट का तर्क)
  │
  └─> चरण 4: Recovery Card लिखें और साफ़ सत्र शुरू करें

चरण-दर-चरण कार्यवाही

1. चरण 1: सत्र बंद करें। अनियंत्रित रन की जाँच के लिए तुरंत Ctrl+C दबाएँ। एजेंट को लंबे स्पष्टीकरण बनाकर संदर्भ खर्च न करने दें।
2. चरण 2: स्थिति देखें और साफ़ करें। git status --short चलाएँ। यदि एजेंट ने टूटा हुआ कोड बनाया है, तो अनट्रैक की गई या खराब फ़ाइलों को साफ़ करें: git checkout -- <file>।
3. चरण 3: मूल कारण वर्गीकृत करें। समस्या कहाँ है यह जानने के लिए Dashboard के API metrics और एजेंट के execution logs की तुलना करें।
4. चरण 4: संरचित Recovery Card सहेजें।

---

3. संरचित Recovery Card

नया recovery सत्र शुरू करने से पहले टास्क की सटीक स्थिति दर्ज करें:

### Recovery Card: इंपोर्ट सर्विस विफलता

- **मूल लक्ष्य**: `auth/service.ts` में email validation जोड़ना।
- **वास्तविक प्रगति**: Regex जोड़ा गया, लेकिन unit test `auth_test.go` विफल रहा।
- **मूल कारण**: एजेंट ने public interface के बजाय private method को mock करने की कोशिश की।
- **Git स्थिति**: Branch `fix/auth-email`; `auth/service.ts` में वैध diff रखा गया है।
- **साफ़ सत्र के लिए अगला कदम**: public `AuthClient` interface का उपयोग करके unit test को refactor करें।

[!IMPORTANT] Secrets को अलग रखें: Recovery Card में API key, access token या raw memory dump कभी न डालें। API key और endpoint configuration को BetterToken की Claude Code गाइड से जाँचें।

---

4. सुरक्षित बहाली और सत्यापन

काम सुरक्षित रूप से फिर शुरू करने के लिए:

1. साफ़ context window के साथ नया Claude Code सत्र खोलें।
2. एजेंट को केवल टास्क का लक्ष्य और Recovery Card का “अगला कदम” दें।
3. एजेंट से एक सीमित target check चलाने को कहें: npm test -- tests/auth.test.ts।
4. पुष्टि करें कि चुने हुए checks Passed हैं और अंतिम diff जाँचें: git diff --check।

यह troubleshooting protocol अनियंत्रित agent loop को नियंत्रित checkpoint में बदलता है, जिससे आपका codebase और token budget सुरक्षित रहते हैं।