सोमवारी सकाळी उठल्यावर तुम्हाला पाच गंभीर बग रिपोर्ट्स (bug reports) मिळतात. तुमच्या रिव्ह्यू मॉनिटरिंग टूलने (review monitoring tool) आपले काम चोख बजावले आहे. त्याने प्रत्येक क्रॅश रिपोर्ट, प्रत्येक रागीट वन-स्टार रिव्ह्यू आणि "सेव्ह टॅप केल्यावर ॲप फ्रीझ होते" असे प्रत्येक फीडबॅक पकडले आहे. नक्की काय बिघडले आहे हे तुम्हाला माहित आहे, पण कुठे पाहायचे हे माहित नाही.

माझे पहिले पाइपलाइन (pipeline) तयार केल्यानंतर मला याच अडचणीचा सामना करावा लागला. त्याने ॲप रिव्ह्यू आणि येणारे क्रॅश लॉग्स कोणतीही अडचण न येता मॉनिटर केले आणि प्रत्येक फीडबॅक योग्य गटात विभागला: बग्स (bugs), क्रॅश (crashes) किंवा फीचर रिक्वेस्ट (feature requests). डॅशबोर्ड व्यवस्थित दिसत होता, पण प्रत्यक्ष डीबगिंग (debugging) प्रक्रिया मात्र तशी नव्हती.

बग आहे हे समजणे ही केवळ सुरुवातीची पायरी आहे. मला अजूनही IDE उघडावे लागायचे, मॉड्यूल्समध्ये grep करावे लागायचे, सध्याच्या कोडबेसशी स्टॅक ट्रेस (stack traces) क्रॉस-रेफरन्स करावे लागायचे आणि माझ्या डोक्यात बिघाडाचा मार्ग (failure path) पुन्हा तयार करावा लागायचा. जेव्हा तिकिटांचा ढीग साचलेला असतो आणि कॉफी अजूनही गरम असते, तेव्हा हे मॅन्युअल शोधकार्य तुमचा खूप वेळ वाया घालवते. मला पाइपलाइनने फक्त समस्या दाखवून देण्यापेक्षा त्या शोधून काढण्याची (investigate) गरज होती.

म्हणून मी एकच ध्येय ठेवून सिस्टम पुन्हा तयार केली: कच्चा बग रिपोर्ट घ्या आणि त्याचे प्रमाणित निदान (validated diagnosis) द्या. LLM च्या केवळ गप्पा नको होत्या. मला एक स्ट्रक्चर्ड शोध (structured finding) हवा होता जो फाईलचे नाव सांगेल, ओळ (line) दर्शवेल, जोखमीचा अंदाज घेईल आणि उपाय सुचवेल. ते कसे घडले ते पाहूया.

चॅट लॉगपेक्षा स्ट्रक्चर का श्रेष्ठ आहे

मी हा इन्वेस्टिगेटिंग एजंट (investigating agent) PydanticAI वापरून तयार केला. याचे कारण साधे होते. जेव्हा तुम्ही लँग्वेज मॉडेलला कोडबद्दल विचारता, तेव्हा त्याचे डीफॉल्ट आउटपुट मजकुराचा एक ओघ असतो. ते मानवी वाचकासाठी उपयुक्त असू शकते, पण पुढील स्क्रिप्टसाठी (downstream script) ते निरुपयोगी असते. मला मशीन-रीडेबल कॉन्ट्रॅक्ट (machine-readable contract) हवे होते.

हा एजंट चार विशिष्ट फील्ड्ससह एक व्हॅलिडेटेड डेटा मॉडेल (validated data model) परत करतो: मूळ कारण (root cause), प्रभावित फाईल्स (affected files), प्रस्तावित बदल (proposed changes) आणि जटिलता व जोखमीचे मूल्यांकन (assessment of complexity and risk). जर मॉडेलमध्ये एखादे फील्ड नसेल किंवा फाईलपाथमध्ये काही चुकीची माहिती (hallucinate) असेल, तर व्हॅलिडेशन फेल होते आणि मला ते लगेच समजते. ही शिस्त पाइपलाइनला अचूक ठेवते.

प्रत्यक्ष शोधकार्य करण्यासाठी, एजंटला फक्त चार 'रीड-ओन्ली' (read-only) टूल्स मिळतात आणि दुसरे काहीही नाही. तो grep द्वारे कोड शोधू शकतो, फाईलमधील विशिष्ट ओळी वाचू शकतो, डिरेक्टरीमधील मजकूर पाहू शकतो आणि क्लासेस किंवा फंक्शन्ससारखी सिम्बॉल्स (symbols) शोधू शकतो. 'रीड-ओन्ली' असणे हा महत्त्वाचा भाग आहे. मला असा एजंट नको होता ज्याला 'राईट ॲक्सेस' (write access) असेल आणि तो रात्री २ वाजता माझ्या रिपॉझिटरीमध्ये फिरत राहील. आधी समजून घेणे, मग बदल करणे.

रेपो मॅप (Repo Map): टूल्स वापरण्यापूर्वी संदर्भ

एजंटची पहिली आवृत्ती अचूक होती पण खूप खर्चिक होती. तो टोकन्सचा (tokens) प्रचंड वापर करत असे. मॉडेल आधी list-dir कॉल करायचे, मग grep, मग फाईल वाचणे आणि पुन्हा list-dir, अशा प्रकारे प्रोजेक्ट स्ट्रक्चरचे मानसिक मॉडेल तयार करण्यासाठी तो एक एक महागडा टोकन खर्च करत असे.

याचे निराकरण म्हणजे एजंट सुरू होण्यापूर्वी एक संक्षिप्त 'रेपो मॅप' (repo map) तयार करणे. हा मॅप रिपॉझिटरीचा एक सारांश असतो: महत्त्वाच्या फाईल्स, त्यांची मुख्य फंक्शन्स किंवा क्लासेस आणि प्रमुख मॉड्यूल्स एकमेकांशी कसे जोडलेले आहेत. हे एजंटला चुकून रस्ते शोधण्याऐवजी GPS देण्यासारखे आहे.

या मॅपमुळे एजंटला src/utils/parser.ts अस्तित्वात आहे की नाही हे शोधण्यासाठी वेळ वाया घालवावा लागत नाही. त्याला आधीच परिसराची माहिती असते. तो थेट त्या ठिकाणी जातो जिथे समस्या आहे. या एका बदलामुळे अनावश्यक फिरण्याचा टप्पा (wandering phase) पूर्णपणे संपला.

टूल फनेल (Tool Funnel): निष्कर्षाकडे नेणारा मार्ग

मॅप असूनही, एजंट गोंधळू शकत होता. तो एखादी संशयास्पद फाईल शोधायचा, मग स्वतःच्या निर्णयावर शंका घ्यायचा, पुन्हा शोधायचा, मग दुसरी फाईल वाचायचा; अशा प्रकारे तो एका अंतहीन लूपमध्ये अडकून पडायचा. मला त्याला गती देण्यासाठी एक मार्ग हवा होता.

मी तीन टप्प्यांचे 'टूल फनेल' (tool funnel) लागू केले, जे एजंट प्रगती करत असताना त्याच्या क्षमतांवर मर्यादा आणते.

पहिला टप्पा म्हणजे एक्सप्लोरेशन (exploration). एजंटला चारही टूल्सचा पूर्ण एक्सेस असतो. तो बग समजून घेण्यासाठी जे काही आवश्यक असेल ते शोधू शकतो, ब्राउझ करू शकतो आणि वाचू शकतो.

दुसरा टप्पा म्हणजे डीप-डायव्ह (deep-dive). एकदा का एजंटने संभाव्य दोष शोधले की, तो डिस्कव्हरी टूल्स गमावतो. तो फक्त फाईल्स वाचू शकतो. आता grep किंवा डिरेक्टरी लिस्टिंग चालणार नाही. या टप्प्यावर त्याने आधीच शोधलेल्या कोडचा अभ्यास करून पुराव्यांची साखळी तयार करणे आवश्यक असते.

तिसरा टप्पा म्हणजे आउटपुट (output). सर्व टूल्स लॉक केले जातात. एजंट आता कोडबेसवर कोणतेही प्रश्न विचारू शकत नाही. त्याला आता शांत बसून रिपोर्ट लिहावा लागतो. यामुळे "मला अजून एक गोष्ट तपासायला द्या" या अंतहीन चक्राला आळा बसतो.

या फनेलमुळे सरासरी टूल कॉल्सची (tool calls) संख्या एका विश्लेषणासाठी चाळीसपेक्षा जास्तवरून कमी होऊन साधारण दहावर आली. एजंट अधिक वेगवान, स्वस्त आणि आश्चर्यकारकपणे अधिक आत्मविश्वासी झाला, कारण त्याला एका निष्कर्षावर ठाम राहावे लागत होते.

बॅकएंड स्वॅपेबल (Swappable) ठेवणे

मला सिस्टम एकाच मॉडेल प्रोव्हायडरवर हार्डकोड करायची नव्हती. मी कामाच्या स्वरूपानुसार वेगवेगळे इंजिन्स वापरतो. कधी Claude Code, कधी Grok Build, तर कधी त्या क्षणी जे सर्वात स्वस्त असेल ते. मुख्य लॉजिक कोणत्याही विशिष्ट प्रोव्हायडरवर अवलंबून न राहण्यासाठी, मी कामाचे दोन टप्प्यांत विभाजन केले आहे.

पहिला टप्पा म्हणजे एक्सप्लोरेशन (Exploration). कोडिंग एजंट, जो कोणताही सक्षम मॉडेल असू शकतो, तो रेपो मॅप वाचतो, टूल्स वापरतो आणि एक रॉ मार्कडाउन रिपोर्ट तयार करतो. हा विचार करण्याचा खर्चिक भाग आहे.

दुसरा टप्पा म्हणजे स्ट्रक्चरिंग (Structuring). एक स्वस्त, वेगवान LLM तो मार्कडाउन घेतो आणि त्याचे कडक Pydantic मॉडेलमध्ये पुनर्रचना करतो. या टप्प्यासाठी तर्कशक्तीची (reasoning) फारशी गरज नसते. हे फक्त एक्सट्रॅक्शन आणि फॉरमॅटिंग आहे, त्यामुळे ते हलक्या हार्डवेअरवर देखील चालू शकते.

सीमा स्पष्ट असल्यामुळे, मी व्हॅलिडेशन लॉजिकला स्पर्श न करता बॅकएंड बदलू शकतो. मार्कडाउन रिपोर्ट हा एक्सप्लोरेटरी ब्रेन आणि मी प्रत्यक्षात वापरत असलेले स्ट्रक्चर्ड आउटपुट यांच्यामध्ये एक युनिव्हर्सल अडॅप्टर म्हणून काम करतो.

प्रत्यक्षात काय काम करून गेले

या सेटअपमुळे मी येणाऱ्या समस्या (issues) हाताळण्याची पद्धत बदलली आहे. क्लासिफिकेशन लेयर अजूनही बग्स आणि फीचर रिक्वेस्ट्स वेगळे करते, पण आता ॲनालिसिस लेयर लगेच त्यानंतर काम सुरू करते. जेव्हा मी माझा एडिटर उघडतो, तेव्हा फाईल पाथ, लाईन रेंज आणि प्रस्तावित बदल माझ्यासाठी तयार असतात. मी अजूनही सर्व काही मॅन्युअली तपासतो. हे सहाय्य (assistance) आहे, ऑटोपायलट नाही. पण पूर्वी जे कॉन्टेक्स्ट गॅदरिंग करावे लागायचे...