You wake up to five critical bug reports on a Monday morning. Your review monitoring tool has done its job. It caught ev

સોમવારની સવારે તમે પાંચ ગંભીર બગ રિપોર્ટ્સ (bug reports) સાથે જાગો છો. તમારા રિવ્યુ મોનિટરિંગ ટૂલે તેનું કામ કર્યું છે. તેણે દરેક ક્રેશ રિપોર્ટ, દરેક ગુસ્સાવાળો વન-સ્ટાર રિવ્યુ, અને દરેક "સેવ પર ટેપ કરતી વખતે એપ ફ્રીઝ થઈ જાય છે" એવા રિપોર્ટ્સ પકડી લીધા છે. તમને બરાબર ખબર છે કે શું તૂટી ગયું છે. પણ તમને એ નથી ખબર કે ક્યાં શોધવું.

મારું પહેલું પાઇપલાઇન (pipeline) બનાવ્યા પછી હું આ મુશ્કેલીનો સામનો કરી રહ્યો હતો. તે કોઈપણ મુશ્કેલી વગર એપ રિવ્યુ અને આવતા ક્રેશ લોગ્સનું મોનિટરિંગ કરતું હતું, અને દરેક ફીડબેકને વ્યવસ્થિત રીતે અલગ પાડતું હતું: બગ્સ (bugs), ક્રેશ (crashes), અથવા ફીચર રિક્વેસ્ટ્સ (feature requests). ડેશબોર્ડ હેલ્ધી દેખાતું હતું, પણ વાસ્તવિક ડિબગિંગ પ્રક્રિયા (debugging process) નહોતી.

બગ છે તે જાણવું એ માઇલના રસ્તાના માત્ર પહેલા ઇંચ જેટલું જ છે. મારે હજુ પણ IDE ખોલવું પડતું, મોડ્યુલ્સમાં grep કરવું પડતું, સ્ટેક ટ્રેસ (stack traces) ને હાલના કોડબેઝ સાથે સરખાવવા પડતા, અને મારા મગજમાં નિષ્ફળતાના માર્ગનું પુનઃનિર્માણ કરવું પડતું. જ્યારે ટિકિટોનો પહાડ ઊભો થઈ રહ્યો હોય અને કોફી હજુ ગરમ હોય, ત્યારે આ મેન્યુઅલ આર્કિયોલોજી (manual archaeology) એવો સમય બગાડે છે જે તમારી પાસે નથી. મારે પાઇપલાઇન માત્ર સમસ્યાઓ દર્શાવવા માટે જ નહીં, પણ તેની તપાસ કરવા માટે પણ જોઈતી હતી.

તેથી મેં એક જ લક્ષ્ય સાથે સિસ્ટમને ફરીથી બનાવી: એક કાચા બગ રિપોર્ટને લો અને એક માન્ય નિદાન (validated diagnosis) પરત કરો. LLM ના લાંબા લખાણ તરીકે નહીં, પરંતુ એક સ્ટ્રક્ચર્ડ રિપોર્ટ તરીકે જે ફાઇલનું નામ આપે, લાઇન બતાવે, જોખમનું અનુમાન લગાવે અને સુધારાનો સૂચન કરે. તે કેવી રીતે બન્યું તે અહીં છે.

શા માટે સ્ટ્રક્ચર ચેટ લોગ કરતા વધુ સારું છે

મેં ઇન્વેસ્ટિગેટિંગ એજન્ટ (investigating agent) PydanticAI સાથે બનાવ્યો હતો. તેનું કારણ સરળ હતું. જ્યારે તમે લેંગ્વેજ મોડલને કોડ વિશે વિચારવા માટે કહો છો, ત્યારે તેનું ડિફોલ્ટ આઉટપુટ ટેક્સ્ટનો એક પ્રવાહ હોય છે. તે માનવ વાંચક માટે મદદરૂપ હોઈ શકે છે, પરંતુ ડાઉનસ્ટ્રીમ સ્ક્રિપ્ટ માટે તે નકામું છે. મારે મશીન-રીડેબલ કોન્ટ્રાક્ટ (machine-readable contract) ની જરૂર હતી.

એજન્ટ ચાર ચોક્કસ ફીલ્ડ્સ સાથેનું માન્ય ડેટા મોડલ પરત કરે છે: મૂળ કારણ (root cause), અસરગ્રસ્ત ફાઇલો (affected files), સૂચવેલા ફેરફારો (proposed changes), અને જટિલતા અને જોખમનું મૂલ્યાંકન (assessment of complexity and risk). જો મોડલમાં કોઈ ફીલ્ડ ખૂટતું હોય અથવા તે ખોટો ફાઇલપાથ (filepath) આપે, તો વેલિડેશન નિષ્ફળ જાય છે અને હું તરત જ તેને પકડી લઉં છું. આ સચોટતા પાઇપલાઇનને પ્રમાણિક રાખે છે.

વાસ્તવિક ડિટેક્ટિવ કામ કરવા માટે, એજન્ટ પાસે માત્ર ચાર રીડ-ઓન્લી (read-only) ટૂલ્સ છે અને બીજું કંઈ નહીં. તે grep દ્વારા કોડ સર્ચ કરી શકે છે, ફાઇલમાંથી ચોક્કસ લાઇન રેન્જ વાંચી શકે છે, ડિરેક્ટરી કન્ટેન્ટની યાદી બનાવી શકે છે, અને ક્લાસ અથવા ફંક્શન જેવા સિમ્બોલ્સ શોધી શકે છે. રીડ-ઓન્લી હોવું એ મહત્વનો ભાગ છે. હું એવો એજન્ટ નહોતો ઈચ્છતો જે રાત્રે ૨ વાગ્યે મારા રિપોઝિટરીમાં લખવાની (write access) સત્તા સાથે ફરે. પહેલા સમજો, પછી એડિટ કરો.

રેપો મેપ (Repo Map): ટૂલ્સ પહેલા સંદર્ભ (Context)

એજન્ટનું પ્રથમ વર્ઝન સચોટ હતું પરંતુ ખૂબ જ મોંઘું હતું. તે ટોકન્સ (tokens) એવી રીતે વાપરતું હતું જાણે કોઈ પ્રવાસી ગોળ-ગોળ ફરી રહ્યો હોય. મોડલ પહેલા list-dir કોલ કરતું, પછી grep, પછી ફાઇલ વાંચતું, અને ફરીથી list-dir કરતું, જેનાથી પ્રોજેક્ટ સ્ટ્રક્ચરનું માનસિક મોડેલ એક પછી એક મોંઘા ટોકન્સ દ્વારા ધીમે ધીમે બનતું.

આનો ઉકેલ એજન્ટ શરૂ કરે તે પહેલાં એક કોમ્પેક્ટ રેપો મેપ (compact repo map) બનાવવાનો હતો. આ મેપ રિપોઝિટરીનો સારાંશ છે: મુખ્ય ફાઇલો, તેમના પ્રાથમિક કાર્યો અથવા ક્લાસ, અને મુખ્ય મોડ્યુલ્સ કેવી રીતે જોડાયેલા છે. તેને એજન્ટને ભૂલ અને પ્રયત્ન દ્વારા રસ્તાઓ શોધવા કહેવાને બદલે GPS આપવા જેવું સમજો.

તેના કોન્ટેક્સ્ટ વિન્ડો (context window) માં તે મેપ હોવાથી, એજન્ટ src/utils/parser.ts અસ્તિત્વમાં છે તે જાણવા માટે સમય બગાડતો નથી. તે પહેલેથી જ ભૂપ્રદેશ જાણે છે. તે સીધો તે ભાગ તરફ જાય છે જ્યાં સમસ્યા છે. આ એક ફેરફારથી ભટકવાની અવસ્થા (wandering phase) સંપૂર્ણપણે દૂર થઈ ગઈ.

ટૂલ ફનલ (Tool Funnel): નિષ્કર્ષ તરફ દોરવું

મેપ હોવા છતાં, એજન્ટ અનિશ્ચિત રહી શકતો હતો. તે એક શંકાસ્પદ ફાઇલ શોધશે, પછી પોતાની જાત પર શંકા કરશે, ફરીથી સર્ચ કરશે, પછી બીજી ફાઇલ વાંચશે, અને માત્ર "હજી એક ચેક" ના અનંત લૂપમાં ફસાઈ જશે. મારે ગતિ જાળવી રાખવા માટે એક રસ્તો જોઈતો હતો.

મેં ત્રણ તબક્કાવાળી ટૂલ ફનલ અમલમાં મૂકી જે એજન્ટ જેમ આગળ વધે તેમ તેની ક્ષમતાઓને મર્યાદિત કરે છે.

પ્રથમ તબક્કો એક્સપ્લોરેશન (exploration) છે. એજન્ટ પાસે ચારેય ટૂલ્સનો સંપૂર્ણ એક્સેસ છે. તે તેના તર્ક (reasoning) માં બગને ફરીથી બનાવવા માટે જે પણ જરૂરી હોય તે સર્ચ કરી શકે છે, બ્રાઉઝ કરી શકે છે અને વાંચી શકે છે.

બીજો તબક્કો ડીપ-ડાઇવ (deep-dive) છે. એકવાર એજન્ટ સંભવિત ખામીઓ ઓળખી લે, પછી તે ડિસ્કવરી ટૂલ્સ ગુમાવે છે. તે ફક્ત ફાઇલો વાંચી શકે છે. હવે grep કે ડિરેક્ટરી લિસ્ટિંગ કરી શકાશે નહીં. આ તબક્કે તેણે જે કોડ પહેલેથી જ શોધી લીધો છે તેનો અભ્યાસ કરવો પડશે અને પુરાવાઓ ભેગા કરવા પડશે.

ત્રીજો તબક્કો આઉટપુટ (output) છે. બધા ટૂલ્સ લોક કરી દેવામાં આવે છે. એજન્ટ હવે કોડબેઝને ક્વેરી કરી શકતો નથી. તેણે શાંતિથી બેસીને રિપોર્ટ લખવો પડશે. આ "ચાલો હજી એક વસ્તુ ચેક કરી લઈએ" ના અનંત ચક્રને અટકાવે છે.

તે ફનલને કારણે સરેરાશ ટૂલ કોલ્સની સંખ્યા દરેક વિશ્લેષણ દીઠ ચાલીસથી ઘટીને લગભગ દસ થઈ ગઈ. એજન્ટ ઝડપી, સસ્તો અને વિરોધાભાસી રીતે વધુ આત્મવિશ્વાસુ બન્યો કારણ કે તેણે એક નિષ્કર્ષ પર પહોંચવું જ પડતું હતું.

બેકએન્ડને બદલી શકાય તેવું રાખવું (Keeping the Backend Swappable)

હું સિસ્ટમને કોઈ એક સિંગલ મોડેલ પ્રોવાઈડર સાથે હાર્ડકોડ કરવા માંગતો નહોતો. હું કાર્યના પ્રકાર મુજબ અલગ-અલગ એન્જિનનો ઉપયોગ કરું છું. ક્યારેક Claude Code, ક્યારેક Grok Build, તો ક્યારેક જે તે સમયે જે સૌથી સસ્તું હોય તે. મુખ્ય લોજિકને પ્રોવાઈડર પર નિર્ભર ન રહે તેવું રાખવા માટે, મેં કામને બે તબક્કામાં વહેંચ્યું છે.

પ્રથમ તબક્કો એ એક્સપ્લોરેશન છે. કોડિંગ એજન્ટ, જે કોઈપણ સક્ષમ મોડેલ હોઈ શકે છે, તે repo map વાંચે છે, ટૂલ્સનો ઉપયોગ કરે છે અને એક કાચો markdown રિપોર્ટ તૈયાર કરે છે. આ વિચારવાની મોંઘી પ્રક્રિયા છે.

બીજો તબક્કો સ્ટ્રક્ચરિંગ છે. એક સસ્તું, ઝડપી LLM તે markdown લે છે અને તેને સખત Pydantic મોડેલમાં રિફોર્મેટ કરે છે. આ તબક્કામાં લગભગ કોઈ રીઝનિંગની જરૂર પડતી નથી. તે ફક્ત એક્સટ્રેક્શન અને ફોર્મેટિંગ છે, તેથી તે હળવા હાર્ડવેર પર ચાલે છે.

કારણ કે તેની સીમા સ્પષ્ટ છે, હું વેલિડેશન લોજિકને અડક્યા વગર બેકએન્ડ બદલી શકું છું. માર્કડાઉન રિપોર્ટ એ એક્સપ્લોરેટરી બ્રેઈન અને હું ખરેખર જે સ્ટ્રક્ચર્ડ આઉટપુટનો ઉપયોગ કરું છું તે વચ્ચે એક યુનિવર્સલ એડેપ્ટર તરીકે કામ કરે છે.

ખરેખર શું કામ લાગ્યું

આ સેટઅપે ઇનકમિંગ ઇશ્યુઝને હું કેવી રીતે હેન્ડલ કરું છું તે બદલી નાખ્યું છે. ક્લાસિફિકેશન લેયર હજુ પણ બગ્સને ફીચર રિક્વેસ્ટ્સથી અલગ કરે છે, પરંતુ હવે એનાલિસિસ લેયર તરત જ તેની પછીનું કામ પકડી લે છે. જ્યારે હું મારું એડિટર ખોલું છું, ત્યારે મારી પાસે ફાઇલ પાથ, લાઇન રેન્જ અને સૂચિત ફેરફાર તૈયાર હોય છે. હું હજુ પણ બધું મેન્યુઅલી તપાસું છું. આ સહાય છે, ઓટોપાયલોટ નથી. પરંતુ કોન્ટેક્સ્ટ ગેધરિંગ જે પહેલા...