సోమవారం ఉదయం ఐదు కీలకమైన బగ్ రిపోర్ట్లతో మీరు నిద్రలేస్తారు. మీ రివ్యూ మానిటరింగ్ టూల్ తన పనిని చక్కగా చేసింది. ప్రతి క్రాష్ రిపోర్ట్ను, ప్రతి కోపంతో కూడిన వన్-స్టార్ రివ్యూను, ప్రతి "సేవ్ చేసినప్పుడు యాప్ ఫ్రీజ్ అవుతోంది" అనే ఫిర్యాదును అది పట్టుకుంది. ఏది విరిగిపోయిందో మీకు ఖచ్చితంగా తెలుసు. కానీ ఎక్కడ వెతకాలో మాత్రం తెలియదు.
నా మొదటి పైప్లైన్ను నిర్మించిన తర్వాత నేను ఎదుర్కొన్న సమస్య ఇదే. అది యాప్ రివ్యూలను మరియు వచ్చే క్రాష్ లాగ్లను ఎటువంటి ఇబ్బంది లేకుండా మానిటర్ చేస్తూ, ప్రతి ఫీడ్బ్యాక్ను బగ్స్, క్రాషెస్ లేదా ఫీచర్ రిక్వెస్ట్లు అనే క్రమబద్ధమైన విభాగాల్లోకి వర్గీకరించింది. డ్యాష్బోర్డ్ అంతా బాగున్నట్లు కనిపిస్తోంది, కానీ అసలైన డీబగ్గింగ్ ప్రక్రియ మాత్రం అంత సులభంగా లేదు.
ఒక బగ్ ఉందని తెలియడం అనేది మైలు దూరం ప్రయాణంలో మొదటి అంగుళం మాత్రమే. నేను ఇంకా IDEని ఓపెన్ చేసి, మాడ్యూల్స్లో grep చేయాలి, ప్రస్తుత కోడ్బేస్తో స్టాక్ ట్రేస్లను సరిపోల్చాలి మరియు ఫెయిల్యూర్ పాత్ను నా మెదడులో పునర్నిర్మించాలి. టికెట్లు పేరుకుపోతున్నప్పుడు, కాఫీ ఇంకా వేడిగా ఉన్నప్పుడే, ఈ మాన్యువల్ పరిశోధన మీకు లేని సమయాన్ని వృథా చేస్తుంది. పైప్లైన్ కేవలం సమస్యలను గుర్తించడమే కాకుండా, వాటిని విచారించగలగాలి (investigate) అని నేను కోరుకున్నాను.
అందుకే నేను ఒకే లక్ష్యంతో సిస్టమ్ను మళ్లీ నిర్మించాను: ఒక ముడి బగ్ రిపోర్ట్ను తీసుకుని, ధృవీకరించబడిన డయాగ్నోసిస్ను (validated diagnosis) అందించడం. అది LLM ఇచ్చే ఒక పేరాగ్రాఫ్ లాంటి ఆలోచనలు కాకూడదు. ఫైల్ను పేర్కొంటూ, లైన్ నంబర్ను చూపిస్తూ, రిస్క్ను అంచనా వేస్తూ మరియు పరిష్కారాన్ని సూచిస్తూ ఒక నిర్మాణాత్మకమైన ఫలితం (structured finding) కావాలి. అది ఎలా సాధ్యమైందో ఇక్కడ చూడండి.
చాట్ లాగ్ల కంటే స్ట్రక్చర్ ఎందుకు మేలు?
నేను ఇన్వెస్టిగేటింగ్ ఏజెంట్ను PydanticAIతో నిర్మించాను. దీనికి కారణం సరళమైనది. మీరు ఒక లాంగ్వేజ్ మోడల్ను కోడ్ గురించి ఆలోచించమని అడిగినప్పుడు, దాని డిఫాల్ట్ అవుట్పుట్ ఒక స్నేహపూర్వకమైన టెక్స్ట్ స్ట్రీమ్ లాగా ఉంటుంది. అది మనుషులకి సహాయపడవచ్చు, కానీ తదుపరి స్క్రిప్ట్లకు అది పనికిరాదు. నాకు మెషిన్-రీడబుల్ కాంట్రాక్ట్ (machine-readable contract) అవసరమైంది.
ఈ ఏజెంట్ నాలుగు నిర్దిష్ట ఫీల్డ్లతో కూడిన ధృవీకరించబడిన డేటా మోడల్ను తిరిగి ఇస్తుంది: రూట్ కాజ్ (root cause), ప్రభావితమైన ఫైల్లు (affected files), ప్రతిపాదిత మార్పులు (proposed changes), మరియు సంక్లిష్టత మరియు రిస్క్ అంచనా (assessment of complexity and risk). ఒకవేళ మోడల్లో ఏదైనా ఫీల్డ్ లేకపోయినా లేదా ఫైల్ పాత్ తప్పుగా ఉన్నా (hallucinates), వాలిడేషన్ ఫెయిల్ అవుతుంది మరియు నేను దానిని వెంటనే గుర్తించగలను. ఈ కచ్చితత్వం పైప్లైన్ను నమ్మదగినదిగా ఉంచుతుంది.
అసలైన డిటెక్టివ్ పని చేయడానికి, ఏజెంట్కు కేవలం నాలుగు రీడ్-ఓన్లీ (read-only) టూల్స్ మాత్రమే ఉంటాయి. అది grep ద్వారా కోడ్ను వెతకగలదు, ఫైల్ నుండి నిర్దిష్ట లైన్ రేంజ్లను చదవగలదు, డైరెక్టరీ కంటెంట్ను జాబితా చేయగలదు మరియు క్లాస్లు లేదా ఫంక్షన్ల వంటి సింబల్స్ను గుర్తించగలదు. రీడ్-ఓన్లీ అనేది ఇక్కడ ముఖ్యమైన భాగం. రాత్రి 2 గంటల సమయంలో నా రిపోజిటరీలో ఏజెంట్ ఏదో ఒకటి మార్చేస్తుంటే (write access) నేను కోరుకోలేదు. ముందు అర్థం చేసుకోవాలి, ఆ తర్వాతే ఎడిట్ చేయాలి.
రెపో మ్యాప్: టూల్స్ కంటే ముందు కాంటెక్స్ట్
ఏజెంట్ యొక్క మొదటి వెర్షన్ ఖచ్చితంగా ఉంది కానీ చాలా ఖరీదైనది. అది టోకెన్లను విపరీతంగా వృథా చేసేది. మోడల్ మొదట list-dirని పిలుస్తుంది, తర్వాత grepని, తర్వాత ఒక ఫైల్ను చదువుతుంది, మళ్ళీ list-dirని పిలుస్తుంది... ఇలా ప్రాజెక్ట్ స్ట్రక్చర్ గురించి ఒక మానసిక నమూనాను రూపొందించడానికి ఒక్కో ఖరీదైన టోకెన్ను వాడుతూ నెమ్మదిగా ముందుకు సాగేది.
దీనికి పరిష్కారం ఏంటంటే, ఏజెంట్ పని ప్రారంభించకముందే ఒక కాంపాక్ట్ రెపో మ్యాప్ను (compact repo map) రూపొందించడం. ఈ మ్యాప్ అనేది రిపోజిటరీ యొక్క సారాంశం: ముఖ్యమైన ఫైల్లు, వాటి ప్రాథమిక ఫంక్షన్లు లేదా క్లాస్లు మరియు ప్రధాన మాడ్యూల్లు ఎలా అనుసంధానించబడి ఉన్నాయో తెలియజేస్తుంది. ఏజెంట్ను దారి వెతకమని అడిగే బదులు, దానికి ఒక GPS ఇచ్చినట్లుగా ఇది పనిచేస్తుంది.
ఆ మ్యాప్ దాని కాంటెక్స్ట్ విండోలో ఉండటం వల్ల, src/utils/parser.ts ఉందో లేదో తెలుసుకోవడానికి ఏజెంట్ అనవసరమైన కాల్స్ చేయదు. దానికి ఇప్పటికే ఆ ప్రాంతం గురించి తెలుసు. అది నేరుగా సమస్య ఉన్న చోటుకే చేరుకుంటుంది. ఈ ఒక్క మార్పు వల్ల అనవసరంగా తిరిగే దశ (wandering phase) పూర్తిగా తొలగిపోయింది.
టూల్ ఫన్నెల్: ఒక నిర్ణయానికి తీసుకువెళ్లడం
మ్యాప్ ఉన్నప్పటికీ, ఏజెంట్ తటపటాయించే అవకాశం ఉంది. అది ఒక అనుమానాస్పద ఫైల్ను కనుగొని, మళ్ళీ దానిని సందేహించి, మళ్ళీ వెతికి, మళ్ళీ ఇంకో ఫైల్ను చదువుతూ, "ఇంకొక్కసారి చెక్ చేద్దాం" అనే అనంతమైన లూప్లో చిక్కుకుపోయేది. దానికి ఒక వేగాన్ని (momentum) ఇవ్వడానికి నాకు ఒక మార్గం కావాలి.
ఏజెంట్ పని చేసే కొద్దీ దాని సామర్థ్యాన్ని పరిమితం చేసే మూడు దశల టూల్ ఫన్నెల్ను నేను అమలు చేశాను.
మొదటి దశ అన్వేషణ (exploration). ఏజెంట్కు నాలుగు టూల్స్పై పూర్తి యాక్సెస్ ఉంటుంది. తన రీజనింగ్లో బగ్ను పునరావృతం చేయడానికి దానికి అవసరమైనవన్నీ వెతకడానికి, బ్రౌజ్ చేయడానికి మరియు చదవడానికి వీలుంటుంది.
రెండవ దశ డీప్-డైవ్ (deep-dive). ఏజెంట్ బగ్ ఎక్కడ ఉందో గుర్తించిన తర్వాత, దానికి అన్వేషణ టూల్స్ (discovery tools) అందుబాటులో ఉండవు. అది కేవలం ఫైల్లను మాత్రమే చదవగలదు. ఇక grep చేయడం లేదా డైరెక్టరీ లిస్టింగ్ చేయడం సాధ్యం కాదు. ఈ దశలో అది ఇప్పటికే కనుగొన్న కోడ్ను అధ్యయనం చేసి, ఆధారాలను సేకరించాలి.
మూడవ దశ అవుట్పుట్ (output). అన్ని టూల్స్ లాక్ చేయబడతాయి. ఏజెంట్ ఇక కోడ్బేస్ను క్వెరీ చేయలేదు. అది రిపోర్ట్ను రాయడంపై మాత్రమే దృష్టి పెట్టాలి. ఇది "ఇంకొకటి చెక్ చేస్తాను" అనే అనంతమైన వలయాన్ని (spiral) నివారిస్తుంది.
ఆ ఫన్నెల్ వల్ల విశ్లేషణకు అవసరమైన సగటు టూల్ కాల్స్ సంఖ్య నలభై కంటే ఎక్కువగా ఉన్న స్థితి నుండి దాదాపు పదికి తగ్గింది. ఏజెంట్ వేగంగా, తక్కువ ఖర్చుతో మరియు మరింత నమ్మకంగా పనిచేయడం ప్రారంభించింది, ఎందుకంటే అది ఒక నిర్ణయానికి రావాల్సి ఉంటుంది.
Keeping the Backend Swappable
నేను సిస్టమ్ను ఒకే మోడల్ ప్రొవైడర్కు కట్టిపడేయాలని అనుకోలేదు. పనిని బట్టి నేను వేర్వేరు ఇంజిన్లను ఉపయోగిస్తాను. కొన్నిసార్లు Claude Code, కొన్నిసార్లు Grok Build, లేదా ఆ సమయంలో ఏది చౌకగా ఉంటే అది ఉపయోగిస్తాను. కోర్ లాజిక్ ప్రొవైడర్పై ఆధారపడకుండా ఉండటానికి, నేను పనిని రెండు దశలుగా విభజించాను.
మొదటి దశ అన్వేషణ (exploration). కోడింగ్ ఏజెంట్, ఇది ఏదైనా సమర్థవంతమైన మోడల్ కావచ్చు, రిపో మ్యాప్ను చదువుతుంది, టూల్స్ను ఉపయోగిస్తుంది మరియు ఒక రా (raw) మార్క్డౌన్ రిపోర్ట్ను రూపొందిస్తుంది. ఇది ఖరీదైన ఆలోచనా భాగం.
రెండవ దశ స్ట్రక్చరింగ్ (structuring). ఒక చౌకైన, వేగవంతమైన LLM ఆ మార్క్డౌన్ను తీసుకుని, దానిని ఖచ్చితమైన Pydantic మోడల్లోకి రీఫార్మాట్ చేస్తుంది. ఈ దశకు దాదాపు ఎటువంటి రీజనింగ్ అవసరం లేదు. ఇది కేవలం ఎక్స్ట్రాక్షన్ మరియు ఫార్మాటింగ్ మాత్రమే, కాబట్టి ఇది తేలికపాటి హార్డ్వేర్పై కూడా నడుస్తుంది.
ఈ విభజన స్పష్టంగా ఉండటం వల్ల, నేను వాలిడేషన్ లాజిక్ను మార్చకుండానే బ్యాకెండ్ను మార్చుకోగలను. మార్క్డౌన్ రిపోర్ట్, అన్వేషణాత్మక మెదడు (exploratory brain) మరియు నేను వాడే స్ట్రక్చర్డ్ అవుట్పుట్ మధ్య ఒక యూనివర్సల్ అడాప్టర్గా పనిచేస్తుంది.
నిజంగా ఏది పని చేసింది
ఈ సెటప్ నేను వచ్చే ఇష్యూలను హ్యాండిల్ చేసే విధానాన్ని మార్చింది. క్లాసిఫికేషన్ లేయర్ ఇప్పటికీ బగ్స్ను ఫీచర్ రిక్వెస్ట్ల నుండి వేరు చేస్తుంది, కానీ ఇప్పుడు అనాలిసిస్ లేయర్ వెంటనే దాని తర్వాత పనిని ప్రారంభిస్తుంది. నేను నా ఎడిటర్ను తెరిచే సమయానికి, నాకు ఫైల్ పాత్, లైన్ రేంజ్ మరియు ప్రతిపాదిత మార్పు సిద్ధంగా ఉంటాయి. నేను ఇప్పటికీ ప్రతిదీ మాన్యువల్గా రివ్యూ చేస్తాను. ఇది సహాయం మాత్రమే, ఆటోపైల్ కాదు. కానీ గతంలో చేసే కాంటెక్స్ట్ గ్యాదరింగ్...