Claude Code ने bug दिया, मैंने 4 fixes से उसे नामुमकिन किया

Claude Code ने एक असली repo पर numbering bug ship किया, और चार approved बदलावों ने उसे दोबारा ship होना नामुमकिन कर दिया। इस session ने एक छोटे invoicing API के लिए credit notes लिखे, test suite हरा आया, और बाद में हाथ से चलाए गए एक check ने पकड़ा कि एक reject हुई request ने एक invoice number जला दिया था। फिर हमने उस session पर retro चलाया, fixes को एक-एक करके approve किया, और वही task दोबारा चलाया: इस बार वो साफ़ आया।

retro वो review है जो कोई team incident के बाद करती है, और यहाँ वो Claude Code के अपने session log पर चलाया गया है। हमारे पहले retro की शुरुआत "This session was smooth" से हुई, और उसकी किसी भी finding में वो bug नहीं था। हल सात gestures हैं, इसी क्रम में: install, task चलाना, retro चलाकर उसे बताना क्या फ़ेल हुआ, हर candidate को trace करना, हर survivor को एक carrier में approve करना, commit और audit, और आख़िर में task दोबारा चलाना।

/retro Matt Pocock का एक skill है जो आपके code की नहीं, एक coding session की review करता है। वो session log पढ़ता है, यानी वो फ़ाइल जिसमें Claude Code हर prompt और हर tool call रखता है, और सात categories में candidates ढूँढता है, जैसे कोई ऐसा check जो गलती पकड़ सकता था। वो उन्हें severity के क्रम में दिखाता है और, अपने docs के अनुसार, सिर्फ़ सुझाव देता है: जब तक आप कोई candidate नहीं चुनते, कुछ नहीं बदलता।

इसे install करना पहला gesture है: अपने repo में official marketplace को update कीजिए, फिर skills pack को project scope में install कीजिए ताकि वो सिर्फ़ इसी repo में रहे। हमारा marketplace एक पुराने release पर pinned था जिसमें retro नहीं था, इसलिए पहले update करना पड़ा। नए session में slash टाइप कीजिए और retro command लिस्ट में दिख जाएगा।

एक सीमा: cloud session आपकी मशीन के logs नहीं पढ़ सकता, इसलिए retro वहीं चलाइए जहाँ session हुआ था।

दूसरा gesture वही है जो आप रोज़ करते हैं: अपना असली task एक सादे session में टाइप कीजिए, उसे पूरा होने दीजिए, और session को खुला रखिए, क्योंकि retro यही पढ़ेगा।

हमने Node और TypeScript में बना एक छोटा invoicing API इस्तेमाल किया, जिसका अपना test suite था, और कहीं कोई instructions file, pipeline या commit hook नहीं था। task छोटा था, वैसे ही जैसे आप खुद टाइप करते: paid invoices में क्रम से numbered credit notes जोड़ो, और बचे हुए पैसे का credit देकर एक paid invoice को void करने दो।

session ने route, एक migration और अपने tests लिखे, और रुकने से पहले suite चलाया। फिर हमने वो check चलाया जो finance हाथ से चलाता, यानी पहले से लिखा हुआ एक hidden test, और एक requirement फ़ेल हो गई।

Signal	नतीजा
Test suite	42 tests pass
Type check	साफ़
Hidden finance check	फ़ेल: उम्मीद से बाद का credit note number मिला

वजह: handler request को validate करने से पहले counter से अगला number ले लेता है, और counter उसी पल save हो जाता है जब वो पढ़ा जाता है। बहुत बड़ा credit note reject हो जाता है, जो सही है, और number फिर भी चला जाता है, जो सही नहीं है। session ने ये क्रम मौजूदा issue route से कॉपी किया था, जो invoice numbers को इसी तरह leak करता है।

हमने task दो बार चलाया और दूसरा run साफ़ आया, यानी एक सादा session कभी-कभी ऐसा ही करता है।

तीसरा gesture है उसी session में retro command टाइप करना, और फिर उसे दोबारा चलाना, उसके बाद failure लिखकर। हमारा शुरू हुआ: "This session was smooth."

उसने मुट्ठी भर items rank किए, कोई भी bug नहीं था: एक missing guardrail, एक migration rule जिसे कोई check नहीं करता, और reviewer के लागू करने के लिए कुछ नहीं। retro session log पढ़ता है, और session को कभी पता ही नहीं चला कि वो फ़ेल हुआ।

इसलिए आपको उसे बताना होता है: command को failure के साथ argument बनाकर दोबारा चलाइए, यानी command के बाद का text। हमारे argument में लिखा था कि finance ने build को test किया, कि बहुत बड़ा credit note reject हुआ, कि अगला valid note देर से निकला, और कि retro को कुछ भी fix नहीं करना है।

इस बार उसे वजह अपने ही code में मिली: वो पहले number लेता है और बाद में validate करता है, और उसने कहा कि उसने ये क्रम मौजूदा issue handler से कॉपी किया। नए candidates आए: उसका लिखा एक test जो फ़ेल होने वाला sequence चलाता था पर सिर्फ़ status codes check करता था, एक counter function जो pure दिखता है पर है नहीं, और एक convention जो किसी ने लिखी नहीं।

session के बाद आपको जो भी मिले, उसे argument में टाइप कीजिए, वरना retro एक ऐसे session को audit करता है जिसे वो ठीक चला हुआ मानता है।

चौथा gesture वो है जो skill खुद से नहीं करता: retro से कहिए कि हर candidate के पीछे transcript का पल quote करे, और जो candidate वो न दिखा सके उसे हटा दीजिए।

docs बताते हैं कि सिर्फ़ ranked list काफ़ी क्यों नहीं है: काम खत्म होते ही model session के संघर्ष भूल जाता है और सामान्य सलाह गढ़ने लगता है। इसलिए जिस candidate को आप किसी ख़ास पल तक trace नहीं कर सकते उसे छोड़ दीजिए: बस एक वाक्य जो retro से हर candidate के लिए transcript quote करवाए।

हमारे पहले retro पर जवाब सीधा था: ज़्यादातर candidates का transcript में कोई आधार नहीं था। उसने missing guardrail रखा, क्योंकि hooks folder की उसकी अपनी listing में कुछ छपा ही नहीं था, और migration check को काल्पनिक मानकर हटा दिया।

दूसरे retro पर, जिसे bug का पता था, trace ने चार candidates रखे और एक हटाया।

Candidate	Trace के बाद
उसका लिखा test (accepted, rejected, accepted, number कभी check नहीं हुआ)	रखा, पक्का
बिना चेतावनी वाला counter function	रखा, पक्का
अनलिखी convention	रखा, कमज़ोर
missing guardrail	रखा, हालाँकि उसने कहा कि guardrail इस bug को नहीं पकड़ता
आख़िरी candidate	हटाया: उसने एक ही पल को दो बार गिना था

skill के repo पर एक open issue गिनता है कि ज़्यादातर retro runs के बाद user ने सबूत माँगा। trace किया हुआ candidate भी model का अपना log पढ़ना है, इसलिए "कमज़ोर" चिह्नित row एक judgement है, और आप तय करते हैं कि कौन से आगे ले जाने हैं।

पाँचवाँ gesture वो जगह है जहाँ loop का फ़ायदा मिलता है: एक बार में एक survivor को approve कीजिए, हर एक को उसके carrier में, यानी वो जगह जहाँ rule रहेगा। skill आपको सीढ़ी देता है। mechanical violation के लिए deterministic check, बिना किसी अपवाद के: आपके linter में एक rule, एक commit hook, या आपकी pipeline में एक job। judgement call एक coding standards फ़ाइल में जाता है जिसे reviewer पढ़ता है। आपकी instructions file, docs के शब्दों में, "incredibly sparingly" इस्तेमाल होती है, दूसरी फ़ाइलों के pointers के लिए।

हमने चार बदलाव approve किए:

• Missing guardrail एक tracked commit hook बना जो type check और tests चलाता है और दोनों में से कोई फ़ेल हो तो commit रोक देता है। harness ने फ़ाइल को executable बनाने से मना कर दिया, इसलिए वो command हमने खुद चलाया।
• Test एक vitest test बना जो rule को पक्का करता है: एक credit note accepted, एक credit note rejected, और अगला valid note अगला number ही लेना चाहिए। वो पहले run में फ़ेल हुआ, यही तो मक़सद है: उसने वही bug पकड़ा जो session ने ship किया था।
• Judgement call नई CODING_STANDARDS.md में एक लाइन बनी: sequence number तभी लीजिए जब सारी validations पास हो जाएँ, ताकि reject हुई request sequence में gap न छोड़े।
• Navigation gap counter function के ऊपर एक comment बना: वो counter को तुरंत persist करता है, इसलिए caller के बाद में फ़ेल होने पर भी number खर्च हो जाता है, तो इसे validation के बाद ही call कीजिए।

यानी चार फ़ाइलें बदलीं और CLAUDE.md में शून्य लाइनें, क्योंकि दोनों retros ने एक लिखने से मना किया। पहले ने कहा कि steering-file pointer हर turn पर context खर्च करेगा और पुराना पड़ जाएगा; दूसरे ने कहा कि उसे function पर comment बनाकर रखिए। docs भी यही कहते हैं: Claude उन फ़ाइलों को context मानता है, enforced configuration नहीं, और किसी action को रोकने के लिए आप hook इस्तेमाल करते हैं।

दो सीमाएँ: hook सिर्फ़ commits की रक्षा करता है, और comment, retro के अपने शब्दों में, अगले caller पर एक दाँव है, कोई साबित हुआ fix नहीं।

छठा gesture commit है, और आख़िरी gesture वही task दोबारा चलाना है, जहाँ आपको पता चलता है कि loop टिका या नहीं।

जब हमने approved फ़ाइलें stage करके commit किया, hook पहले चला और उसने commit रोक दिया। type check पास हुआ, फिर नया numbering test फ़ेल हुआ, उम्मीद से बाद का number मिलने पर। hook फ़ाइलों को वैसे ही जाँचता है जैसे वो disk पर हैं, और disk पर अब भी bug वाला code था।

इसलिए session में लौटिए और सिर्फ़ fix माँगिए: validation पास होने के बाद number लीजिए, checks चलाइए, commit मत कीजिए। फिर दोबारा commit कीजिए, hook हरा चलता है, और आपको दो commits मिलते हैं: पहले retro के बदलाव, फिर fix के साथ feature। retro ने खुद कुछ commit नहीं किया, जिसे repo पर एक open issue हूबहू बताता है, इसलिए commit आप करते हैं।

इसके बाद /doctor prompt-audit चलाइए, जो Claude Code का अपना check है आपकी instruction files में पुरानी पड़ चुकी लाइनों के लिए। यहाँ एक जाल है: path के बिना वो आपकी global files को audit करता है, repo को नहीं। path देने पर उसने नई standards फ़ाइल को साफ़ बताया, और ये भी बताया कि पुराना issue route इस rule को तोड़ता है, यानी code bug, prompt की समस्या नहीं।

आख़िरी gesture: वही task लेकर एक नया session खोलिए। हमारे वाले ने code लिखने से पहले coding standards फ़ाइल, readme, hook और लाल numbering test पढ़े, फिर अपनी summary में लिखा कि number सिर्फ़ उन सारी checks के पास होने के बाद लिया जाता है, इसलिए reject हुई request sequence में gap नहीं छोड़ती।

	पहला session	Loop के बाद का नया session
Tests pass	42	हरे
Hidden finance check	फ़ेल	5 में से 5
Reject हुई request के बाद के numbers	जल गए, gap	gapless

एक ईमानदार चेतावनी: इस नए session को सबक एक लाल test और एक standards लाइन के रूप में दिया गया था, इसलिए ये loop के बाद का एक run है, benchmark नहीं।

retro session को पढ़ता है, इसलिए जो session ने नहीं देखा, उसे आप argument में लिखिए। यही वो हिस्सा है जहाँ आप ठोकर खाएँगे।

retro उस session के बाद चलाइए जो गलत गया, उसे clear करने से पहले, या पुराने session के log पर। उसे autopilot पर मत चलाइए और hook से मत जोड़िए: skill के लेखक ने खुद अपने शब्दों में कहा है कि आप इसे automate नहीं करना चाहेंगे। docs एक सीमा जोड़ते हैं: वो पिछले महीने सुझाए गए checks को audit नहीं करता, इसलिए उन्हें छाँटना आपका ही काम है।

याद रखने वाला एक rule docs का अपना वाक्य है: अपनी instructions file को code की तरह मानिए, गड़बड़ होने पर उसकी review कीजिए, नियमित रूप से उसे छाँटिए, और बदलावों को ये देखकर परखिए कि Claude का व्यवहार सच में बदला या नहीं। loop agent को सही नहीं बनाता, वो उसी गलती को तेज़ी से पकड़वाता है, और जो checks आप जोड़ते हैं वो अब आपका maintain किया हुआ code हैं।

इस वीडियो के मुफ़्त pack में retro checklist है जिसमें हर gesture, trace वाला सवाल और carriers हैं, साथ में हमारे run का commit hook script और numbering test भी, ताकि आप हमारे वाले से शुरू कर सकें।