Maguyva ब्लॉग

संदर्भ जो आपके साथ यात्रा करता है

Mon, 07 Sep 2026 00:00:00 GMT

Cursor का इंडेक्सर Cursor के भीतर बेहतरीन है। टैब कम्प्लीशन, इनलाइन एडिटिंग, चैट, और उस विंडो के भीतर का एजेंट पहले से ही उस प्रोजेक्ट इंडेक्स पर निर्भर करते हैं जिसे Cursor खुले वर्कस्पेस के लिए चलाता है। अगर Cursor वह एकमात्र सतह है जहाँ आप लिखते हैं, और वह इंडेक्स पहले से ही सही फ़ाइलें ढूँढ रहा है, तो वहीं बने रहें। यह ‘जहाँ हैं वहीं रहें’ का ईमानदार मामला है, और यह इस पेज की पहली पंक्ति बनने का हकदार है।

यह लेख सामान्य सप्ताह के दूसरे आधे हिस्से के बारे में है। वही रिपॉज़िटरी Claude Code में भी खुली है, Codex CLI से पूछी जा रही है, दूसरी मशीन पर समीक्षा की जा रही है, या CI में चलने वाले किसी एजेंट द्वारा पूछी जा रही है। सवाल यह नहीं है कि ‘कौन सा इंडेक्सर बेहतर है’। सवाल यह है कि क्या एक विंडो में एजेंट जिस मैप पर भरोसा करता है, वह अगली विंडो में भरोसा किए जाने वाले मैप जैसा ही है।

Maguyva वही मैप है जो साथ यात्रा करता है। यह एक रिमोट MCP कोडबेस संदर्भ परत है। एजेंट इसे उसी तरह पूछता है जैसे वह किसी अन्य MCP टूल को पूछता है। परिणाम लाइन नंबर वाले उद्धृत पथों के रूप में वापस आते हैं। Cursor एडिटर बना रहता है। संदर्भ ही वह चीज़ है जो चलती है।

Cursor का इंडेक्सर किसलिए है

Cursor में निर्मित इंडेक्सिंग इसलिए मौजूद है ताकि एडिटर के भीतर चैट, एजेंट और सर्च केवल कच्ची मॉडल संदर्भ विंडो में जो फिट होता है उस पर निर्भर रहने के बजाय प्रासंगिक कोड ला सकें। एक IDE के लिए यह सही डिज़ाइन है। यह इंडेक्स Cursor के लिए नेटिव है। यह MCP सर्वर नहीं है और अन्य क्लाइंट्स से पहुँच योग्य नहीं है।

यह इस तरह काम करता है, जैसा कि Cursor के सार्वजनिक दस्तावेज़ों और लेखन के समय Cursor के अपने स्पष्टीकरणों में वर्णित है: प्राथमिक सर्च पथ अब क्लाउड embedding इंडेक्स नहीं रहा। Cursor टीम ने अपने कम्युनिटी फ़ोरम में कहा है कि समर्पित semantic/embedding-आधारित सर्च को grep-आधारित पुनर्प्राप्ति के पक्ष में कम किया जा रहा है, क्योंकि आज के मॉडल स्वयं जीवित ट्री को एक्सप्लोर करने में पहले से ही काफ़ी अच्छे हैं। इसके बजाय Instant Grep है, एक स्थानीय सर्च इंडेक्स जो एन-ग्राम, इनवर्टेड लिस्ट और ब्लूम फ़िल्टर से बना है, मेमोरी-मैप्ड लुकअप टेबल में संग्रहीत है, ताकि क्वेरी सर्वर के बजाय डेवलपर की अपनी मशीन पर हल हो सके।

यह इंडेक्स स्वयं रिपॉज़िटरी के अपने .git/cursor/ डायरेक्टरी में रहता है, एक विशिष्ट git कमिट पर एंकर किया हुआ; उस कमिट के बाद के बदलाव नए स्कैन को ट्रिगर करने के बजाय उसके ऊपर लेयर होते हैं, और इंडेक्स तभी फिर से बनता है जब स्थानीय स्थिति उस चीज़ से काफ़ी हट जाती है जिस पर वह बना था। क्योंकि यह .git के भीतर बैठता है, यह कभी ट्रैक नहीं होता और कभी पुश नहीं होता — उस फ़ोल्डर को हटा दें, और इंडेक्स चला जाता है। .gitignore का सम्मान इसके निर्माण में किया जाता है, क्योंकि केवल ट्रैक की गई सामग्री ही योग्य होती है, और .cursorignore को रीड पथ पर लागू किया जाता है। उस पथ पर अब कोई सर्वर-साइड embedding चरण या रिमोट वेक्टर डेटाबेस नहीं है। पुराने दस्तावेज़ों ने एक क्लाउड-सहायता प्राप्त डिज़ाइन का वर्णन किया था — चंक एन्क्रिप्शन, Merkle ट्री सिंकिंग, टीम के सदस्यों के बीच इंडेक्स पुन:उपयोग — और Cursor टीम ने स्वयं तब से कहा है कि उस डिज़ाइन को कम किया जा रहा है, इसलिए यह लेख अब इसे वर्तमान के रूप में वर्णित नहीं करता।

एडिटर के भीतर जो चीज़ सबसे अलग खड़ी है वह है Cursor का Explore सबएजेंट। यह एक तेज़ मॉडल पर अपनी संदर्भ विंडो में कई समानांतर सर्च चला सकता है और केवल प्रासंगिक निष्कर्ष वापस ला सकता है, ताकि मुख्य बातचीत सर्च परिणामों से न फूले। यह एडिटर के भीतर एक वास्तविक ताकत है। इसे बनाए रखें।

मल्टी-रूट वर्कस्पेस समर्थित हैं: प्रत्येक खुले फ़ोल्डर का संदर्भ Agent के लिए उपलब्ध है। कुछ git-निर्भर सुविधाएँ, जैसे वर्कट्री, मल्टी-रूट सेटअप में अक्षम हो जाती हैं, और Cloud Agents मल्टी-रूट वर्कस्पेस का बिल्कुल समर्थन नहीं करता।

इनमें से कोई भी Cursor छोड़ने का कारण नहीं है। यह उस जगह के एक बहुत अच्छे मैप का सटीक वर्णन है जहाँ यह रहता है।

‘साथ यात्रा करना’ का वास्तव में क्या मतलब है

एक मैप तब आपके साथ यात्रा करता है जब वही सवाल एक से अधिक क्लाइंट्स से उसी तरह के जवाब, उद्धरणों के साथ जिन्हें आप खोल सकते हैं, वापस लाता है।

Cursor में: ‘क्या parseConfig कहाँ परिभाषित है, और इसे कौन कॉल करता है?’
Claude Code में, उसी repo पर: वही सवाल।
Codex CLI में, एक ऐसी मशीन पर समीक्षा की जा रही है जिसने कभी Cursor विंडो नहीं खोली: वही सवाल।
MCP बोलने वाले CI एजेंट में: वही सवाल, उसी होस्टेड स्नैपशॉट के विरुद्ध।

अगर हर सतह अपना खुद का निजी इंडेक्स बनाती है, तो आपके पास एक मैप नहीं है। आपके पास कई कैश हैं जो अलग होते जा रहे हैं। एडिटर का इंडेक्स डिस्क पर मौजूद ट्री के लिए ताज़ा हो सकता है। CLI सत्र एक दिन पीछे हो सकता है। CI जॉब एक अलग चेकआउट देख सकती है। और एजेंट फिर भी आत्मविश्वासी लगेगा।

Cursor का इंडेक्सर इसे हल करने के लिए नहीं बनाया गया है। क्योंकि यह एडिटर के भीतर रहता है, इसका बनाया गया संदर्भ उस एडिटर के लिए है। जिन पाठकों को CLI, CI पाइपलाइन, या किसी अलग एडिटर की भी ज़रूरत है, उन्हें उन सतहों के लिए एक अलग टूल चाहिए। यह एक स्कोप तथ्य है, कोई खामी नहीं। Maguyva वह अलग टूल है।

Cursor के इंडेक्सर के लिए प्रकाशित भाषाओं की संख्या इस लेख की उपयोग योग्य सामग्री में नहीं बताई गई है। Maguyva 279 से अधिक भाषाओं और टेक्स्ट-आधारित तकनीकों के लिए समर्थन प्रकाशित करता है। Cursor की क़ीमत भी यहाँ दोहराई नहीं गई है; उनका मूल्य निर्धारण पेज देखें। Maguyva सीट्स के बजाय प्रति वर्कस्पेस चार्ज करता है, इंडेक्स की गई कवरेज और वर्कस्पेस आकार के आधार पर $0, $19, $49, और $149 पर प्रकाशित योजनाओं के साथ।

एक होस्टेड मैप, हर MCP क्लाइंट

Maguyva एक रिमोट MCP सर्वर है। आप GitHub कनेक्ट करते हैं, एक रिपॉज़िटरी चुनते हैं, और क्लाउड पाइपलाइन सिंबल, ग्राफ़ एज और उद्धृत मैप बनाती है। आप उस क्लाइंट के MCP कॉन्फ़िग में एक API कुंजी जोड़ते हैं जिसे आप पहले से उपयोग करते हैं। Maguyva के पास 24 दस्तावेज़ीकृत MCP क्लाइंट्स के लिए सेटअप गाइड है — जिसमें Cursor शामिल है — और यह किसी भी अन्य MCP-संगत क्लाइंट से बात कर सकता है जो मानक कॉन्फ़िगरेशन का समर्थन करता है।

Cursor सेटअप पेज एक एडिटर-विशिष्ट पथ है अगर वहीं आप काम करते हैं। वही सर्वर Claude Code, VS Code, Windsurf, Codex CLI और बाकियों को जवाब देता है। आप एडिटर नहीं बदल रहे। आप हर एजेंट को समान टूल सतह दे रहे हैं: सर्च, सिंबल, dependency विश्लेषण, फ़ाइल पुनर्प्राप्ति, रिपॉज़िटरी संदर्भ, और नियतात्मक यूटिलिटी-टूल वर्कफ़्लो में 11 ग्राहक-सामना करने वाले MCP टूल। Semantic, structural, graph, और text सर्च एक उद्धृत परिणाम में मिल जाते हैं।

यही पोर्टेबिलिटी लाभ है। जो उद्धरण आप आज सुबह Cursor में जाँचते हैं, वे उसी आकार के होते हैं जो आज रात Codex CLI वापस लाएगा। फ़ाइल पथ और लाइन नंबर। खोलें। अगर गलत है, तो आप देख लेंगे। अगर सही है, तो अगले बदलाव के लिए एक जगह है जहाँ वह उतर सकता है। जो दावा किया गया है वह है कम भ्रामक बदलाव, यह वादा नहीं कि हर बदलाव सही होगा।

ताज़गी प्रकाशित है। स्नैपशॉट टाइमस्टैम्प किए जाते हैं, ताकि एजेंट को पता हो कि वह ट्री का कौन सा संस्करण पढ़ रहा है। पुनर्निर्माण दर मुफ़्त योजना पर दैनिक और भुगतान योजनाओं पर प्रति घंटा है। ईमानदार सीमा असिंक्रोनाइज़्ड स्थानीय काम है: जो बदलाव केवल वर्किंग ट्री में मौजूद हैं वे अभी तक होस्टेड मैप में नहीं हैं। यह सीमा उस क्लाइंट से स्वतंत्र है जिसका उपयोग आप पूछने के लिए करते हैं, और यही असली बात है। क्लाइंट्स के बीच बहाव अब एक दूसरी छिपी हुई सीमा नहीं है।

दस्तावेज़ीकरण हर क्लाइंट के लिए वही एक्टिवेशन लूप देता है: उस repo को इंडेक्स करें जिसे आप पहले से जानते हैं, क्लाइंट कनेक्ट करें, एक सवाल पूछें जिसे आप सत्यापित कर सकते हैं। इसे Cursor में एक बार करें। इसे उस CLI से फिर से करें जिसका आप समीक्षा वाले दिन वास्तव में उपयोग करते हैं। अगर दोनों जवाब एक ही हैंडलर को उद्धृत करते हैं, तो मैप वास्तव में आपके साथ यात्रा कर चुका है।

दोनों मैप साथ-साथ कैसे मौजूद हैं

दोनों का उपयोग करें। यह तुलना पेज के अर्थ में कोई विकल्प नहीं है।

डिस्क पर मौजूद प्रोजेक्ट के लिए Cursor का इंडेक्सर चालू रखें। एडिटर के भीतर Explore, Instant Grep और एजेंट को इसका उपयोग करने दें। वह लूप नेटिव और तेज़ है।
Cursor में Maguyva को MCP सर्वर के रूप में जोड़ें ताकि वही सत्र होस्टेड वर्कस्पेस मैप भी पूछ सके। Cursor एक दस्तावेज़ीकृत Maguyva क्लाइंट है। आप एक इंडेक्स चुनकर दूसरे को नहीं हटा रहे।
Claude Code, Codex CLI, या किसी भी अन्य MCP क्लाइंट में वही Maguyva सर्वर जोड़ें जो repo को छूता है। एक API कुंजी फ़ॉर्म। एक वर्कस्पेस।
अगर CI एजेंट MCP-संगत है, तो इसे उसी सर्वर की ओर इंगित करें। यह वही टाइमस्टैम्प वाला स्नैपशॉट पढ़ेगा जो लैपटॉप पढ़ता है।

एडिटर का इंडेक्स ‘इस विंडो में डिस्क पर अभी क्या है’ के लिए सबसे अच्छा टूल बना रहता है। होस्टेड मैप ‘यह वर्कस्पेस हर उस एजेंट के लिए कैसा दिखता है जो आज इसे छूएगा’ के लिए सबसे अच्छा टूल है। ये वाक्य प्रतिस्पर्धा नहीं करते।

वर्कस्पेस कोटा मूल्य निर्धारण पेज पर प्रकाशित हैं: रिपो, इंडेक्स की गई लाइनें, और उपयोगकर्ता, प्रति वर्कस्पेस चार्ज किए जाते हैं। एजेंट और मनुष्य एक ही उपयोगकर्ता गिनती साझा करते हैं। किसी ऐसी repo के साथ मुफ़्त में शुरू करें जिसे आप पहले से आंक सकते हैं। वर्कस्पेस को केवल तब बढ़ाएँ जब उद्धरण उस ट्री के संपर्क में टिके रहें।

यह पेज क्या दावा नहीं करता

यह दावा नहीं करता कि Cursor का इंडेक्सर कमज़ोर है, अधूरा है, या एडिटर बदलने का कारण है। इस लेख की पहली पंक्ति ही इसके विपरीत कहती है।

यह दावा नहीं करता कि Maguyva Instant Grep या Explore सबएजेंट की जगह लेता है। वे Cursor की विशेषताएँ हैं। वे Cursor में बनी रहती हैं।

यह किसी भी उत्पाद के लिए भाषा गिनती, लेटेंसी संख्या, या टोकन बचत का आविष्कार नहीं करता। जो संख्याएँ अज्ञात हैं वे अप्रकाशित रहती हैं।

यह ऐसा दिखावा नहीं करता कि जो स्थानीय काम अभी तक पुश नहीं हुआ वह होस्टेड मैप में है। टाइमस्टैम्प वाला स्नैपशॉट उस सीमा को दिखाई देने योग्य बनाता है। यह उसे मिटाता नहीं है।

परीक्षण साधारण है। किसी ऐसी repo को इंडेक्स करें जिसे आप पहले से जानते हैं। पहले Cursor में, फिर एक दूसरे MCP क्लाइंट में, एक सवाल पूछें जिसे आप सत्यापित कर सकते हैं। जो संदर्भ साथ यात्रा करता है वह दोनों जगह वही उद्धरण है।

// same map, wherever you opened it.

पहले मैप, फिर समीक्षा

Mon, 07 Sep 2026 00:00:00 GMT

पुल रिक्वेस्ट के दोनों ओर दो अलग-अलग काम बैठे हैं। एजेंट के लिखने से पहले, उसे उस ट्री के मैप की ज़रूरत होती है जिसे वह बदलने वाला है। एजेंट के PR खोलने के बाद, कुछ को उस बदलाव को बाकी सिस्टम के मुकाबले पढ़ना चाहिए और मनुष्य के लिए कार्रवाई योग्य टिप्पणी छोड़नी चाहिए।

ये काम दूर से एक जैसे दिखते हैं क्योंकि दोनों में ‘कोडबेस को समझना’ शामिल है। यह एक ही उत्पाद नहीं है। एक जवाब देता है ‘यह बदलाव कहाँ उतरना चाहिए?’। दूसरा जवाब देता है ‘इस diff में क्या टूटता है जिसे लाइन-दर-लाइन लिंटर मिस कर देगा?’। इन्हें मिलाने से बदतर पहला ड्राफ्ट और शोरगुल भरी समीक्षा मिलती है।

यह लेख एक जोड़ी वर्कफ़्लो गाइड है। Maguyva वह मैप है जिसे एजेंट पहले पूछता है। Greptile वह समीक्षा एजेंट है जो बाद में PR पर टिप्पणी करता है। यह जोड़ी निर्माण के अनुसार पूरक है: Maguyva पुल रिक्वेस्ट की समीक्षा नहीं करता, और Greptile उस संदर्भ परत की जगह नहीं लेता जिसका उपयोग एजेंट इसे लिखने के लिए करता है।

यह विभाजन क्यों उपयोगी है

एक कोडिंग एजेंट जो प्रशिक्षण पूर्वाग्रह और कुछ चिपकाई गई फ़ाइलों से शुरू होता है, वह एक प्रशंसनीय पथ का आविष्कार करेगा और उसे संपादित करेगा। यह ‘गलत फ़ाइल’ विफलता है, और यह एक पुनर्प्राप्ति समस्या है। Maguyva एक रिमोट MCP कोडबेस संदर्भ परत है: semantic, structural (AST), graph/dependency, और text पुनर्प्राप्ति एक रैंक किए गए परिणाम में मिलती है, साथ ही सिंबल सर्च और फ़ाइल पुनर्प्राप्ति भी। आधारित जवाब path/file.ext:line के रूप में वापस आते हैं, ताकि आप पैच बनने से पहले गलती को अस्वीकार कर सकें। जो दावा किया गया है वह जानबूझकर मामूली है: कम भ्रामक बदलाव। मॉडल फिर भी अनुमान लगा सकता है। बस पहला कदम अब अनुमान नहीं रहता।

Greptile एक AI-संचालित कोड समीक्षा एजेंट है। अपने ही शब्दों में, यह कोडबेस की पूरी समझ के साथ हर पुल रिक्वेस्ट की स्वचालित रूप से समीक्षा करता है, और इसे उन पारंपरिक लिंटर के मुकाबले रखता है जो पूरे सिस्टम के बजाय फ़ाइलों को अलग-अलग जाँचते हैं। सेटअप में GitHub या GitLab ऐप इंस्टॉल करना और एक रिपॉज़िटरी चुनना शामिल है। कोई स्थानीय इंडेक्स नहीं जो आपको चलाना पड़े। होस्टिंग Greptile Cloud है (वे SOC 2 Type II अनुपालन बताते हैं, जिसकी रिपोर्ट अनुरोध पर उपलब्ध है), साथ ही एंटरप्राइज़ के लिए सेल्फ़-होस्ट का विकल्प भी दिया गया है।

उनका अपना क्रमांकित प्रवाह है: कनेक्ट करें और हर फ़ंक्शन, क्लास व dependency का dependency ग्राफ़ बनाएँ; हर पुल रिक्वेस्ट पर, उस पूर्ण repo ग्राफ़ का उपयोग करके बदलाव का विश्लेषण करें और लगभग तीन मिनट में सुझाए गए सुधारों के साथ निष्कर्षों को PR टिप्पणी के रूप में प्रकाशित करें; हर टिप्पणी उस मुद्दे को टीम के पहले से उपयोग किए जा रहे कोडिंग एजेंट को सौंप सकती है। वे यह भी बताते हैं कि टीम के कोड मानकों को सीखने और शोरगुल वाले सुझावों को कम करने के लिए वे समय के साथ पिछली मानवीय PR टिप्पणियाँ पढ़ते हैं। उनका सीखने का सिस्टम, उनके अपने अनुसार, समायोजित होने में 2-3 सप्ताह लेता है।

यह समीक्षा है, ड्राफ्टिंग नहीं। Greptile की ताकत PR में पहले से उतरे बदलाव के विरुद्ध पूर्ण repo ग्राफ़ संदर्भ है, इसके बाद एक बंद लूप जो निष्कर्षों को Claude Code, Codex, Conductor, Cursor, या Devin को भेजता है। Maguyva की ताकत वह रैंक किया गया मैप है जिसे एजेंट बदलाव लिखे जाने से पहले पूछता है। दोनों का उपयोग करें। एक से दूसरे का काम करने के लिए न कहें।

Maguyva और Greptile के बीच कोई प्रथम-पक्ष उत्पाद एकीकरण नहीं बताया गया है। आपको इसकी ज़रूरत भी नहीं है। Maguyva MCP के ज़रिए एजेंट्स से बात करता है। Greptile अपने ऐप के ज़रिए GitHub या GitLab से बात करता है। वे पुल रिक्वेस्ट पर मिलते हैं। कोई जोड़-तोड़ वाली स्क्रिप्ट नहीं, कोई cron नहीं जो एक टूल को दूसरे में फीड करे। इस जोड़ी को bash की ज़रूरत नहीं क्योंकि हर उत्पाद पहले से ही उस सतह पर बैठा है जो उसकी है।

यह क्या नहीं है

यह Greptile को नीचा दिखाना नहीं है। यह ‘अपना समीक्षक बदलें’ पेज नहीं है। Greptile Hacker News पर 5 मार्च, 2024 को Y Combinator W24 कंपनी के रूप में लॉन्च हुआ, और वह थ्रेड कई लोगों के इस उत्पाद से पहली बार परिचित होने का तरीका था। अगर आप उन्हें इसी तरह से जानते हैं, तो उनका उपयोग जारी रखें। यह पेज उस लूप का लापता अगला हिस्सा है: एजेंट को पहले आधार देना ताकि Greptile जो PR देखे वह पहले से ही सही फ़ाइलों को लक्ष्य कर रहा हो।

Greptile की मार्केटिंग सामग्री समीक्षा गति और बग-पकड़ने के दावों के साथ आगे बढ़ती है। इसे Greptile का अपना दावा मानें, स्वतंत्र रूप से सत्यापित संख्या नहीं। यह लेख उन्हें तथ्य के रूप में दोहराता नहीं है।

भाषा कवरेज उसी तरह की ईमानदारी है। Greptile समर्थन को सूचीबद्ध सूची के बजाय सभी प्रोग्रामिंग भाषाओं को कवर करने के रूप में फ्रेम करता है; सटीक संख्या नहीं बताई गई है। Maguyva 279 से अधिक भाषाओं और टेक्स्ट-आधारित तकनीकों के लिए समर्थन प्रकाशित करता है, जब सवाल तकनीकी हो तो साइट पर एक तकनीकी विभाजन (पार्सर-समर्थित AST बनाम केवल-टेक्स्ट) के साथ। ये अलग-अलग दावे करने वाले अलग-अलग उत्पाद हैं। इन्हें न मिलाएँ।

Greptile की क़ीमत इस लेख की उपयोग योग्य सामग्री में नहीं बताई गई है। भुगतान योजनाएँ मौजूद हैं; उनका मूल्य निर्धारण पेज देखें। Maguyva सीट्स के बजाय प्रति वर्कस्पेस चार्ज करता है। योजनाएँ मुफ़्त से शुरू होती हैं। मूल्य निर्धारण पेज अगर आपको वर्कस्पेस संख्याएँ चाहिए तो प्रकाशित स्तर सूचीबद्ध करता है।

वर्कफ़्लो

तीन नामित चरण। इसी क्रम में चलाएँ। पहली बार जब आप इस जोड़ी को आज़माएँ तो इनमें से किसी को न छोड़ें।

1. Maguyva संदर्भ

एक ऐसी repository को इंडेक्स करें जिसे आप पहले से जानते हैं। उस MCP क्लाइंट को कनेक्ट करें जहाँ आप पहले से लिखते हैं — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, या कोई अन्य MCP-संगत क्लाइंट। Maguyva के पास 24 दस्तावेज़ीकृत MCP क्लाइंट्स के लिए सेटअप गाइड है और यह अन्य क्लाइंट्स से बात कर सकता है जो मानक MCP कॉन्फ़िगरेशन का समर्थन करते हैं।

किसी के लिखने से पहले एक ऐसा सवाल पूछें जिसे आप आंक सकें। ‘सत्र समाप्ति कहाँ संभाली जाती है, और इसे कौन कॉल करता है?’ ‘auth ठीक करो’ से बेहतर पहला कदम है। उद्धरण मांगें। file.ext:line परिणाम खोलें। सिंबल का पीछा करें। उन डिपेंडेंसी की पुष्टि करें जिन्हें आप छूने वाले हैं।

Maguyva सर्च, सिंबल, dependency विश्लेषण, फ़ाइल पुनर्प्राप्ति, रिपॉज़िटरी संदर्भ, और नियतात्मक यूटिलिटी-टूल वर्कफ़्लो में 11 ग्राहक-सामना करने वाले MCP टूल उजागर करता है। चार पुनर्प्राप्ति मोड एक रैंक किए गए परिणाम में मिलते हैं; find_symbol एक अलग टूल है जब आप पहले से नाम जानते हैं। दस्तावेज़ीकरण सबसे छोटा पथ बताता है: मुफ़्त में शुरू करें, उस repo को इंडेक्स करें जिसे आप पहले से जानते हैं, क्लाइंट कनेक्ट करें, फिर एक सवाल पूछें जिसे आप सत्यापित कर सकते हैं।

स्नैपशॉट टाइमस्टैम्प किए जाते हैं, ताकि एजेंट बता सके कि यह ट्री का कौन सा संस्करण पढ़ रहा है। ईमानदार सीमा असिंक्रोनाइज़्ड स्थानीय काम है। अगर कोई बदलाव केवल वर्किंग ट्री में मौजूद है और पुश नहीं हुआ, तो होस्टेड मैप में अभी भी वह बदलाव नहीं है। इंस्ट्रक्शन फ़ाइलें (CLAUDE.md, AGENTS.md) फिर भी यहाँ एक जगह रखती हैं, कन्वेंशन और जो नहीं छूना चाहिए उसके लिए। यह जीवित मैप नहीं है। व्यवहार के लिए इसका उपयोग करें। तथ्यों के लिए Maguyva का उपयोग करें।

उद्धरण repo के संपर्क में टिकने से पहले एजेंट को PR खोलने न दें। वह गेट इस चरण का पूरा उद्देश्य है।

2. एजेंट का PR

वही एजेंट अब उस क्लाइंट में बदलाव लिखता है जिसके लिए आप पहले से भुगतान करते हैं। Maguyva न तो एडिटर है, न समीक्षक। एजेंट फिर भी diff बनाता है। आप फिर भी GitHub या GitLab पर पुल रिक्वेस्ट खोलते हैं जैसा आप पहले से करते हैं।

जो अलग होना चाहिए वह है पहली फ़ाइल। PR को उस असली हैंडलर का नाम लेना चाहिए जो व्यवहार को लागू करता है, वे कॉलर जो टूटेंगे, और वे टेस्ट जो अगर बदलाव गलत है तो विफल होंगे। अगर चरण 1 छोड़ दिया गया, तो चरण 3 अपनी टिप्पणी गलत पैकेज में उतरे बदलाव पर बर्बाद करेगा। Greptile फिर भी प्रणालीगत समस्याएँ ढूँढ सकता है। इसे भ्रामक पथ से भी उबरना नहीं पड़ना चाहिए।

PR को छोटा रखें। एक आधारित पहली फ़ाइल किसी मॉड्यूल को फिर से लिखने का लाइसेंस नहीं है। यह पूरक जोड़ी तब काम करती है जब एजेंट मैप के साथ एक काम करता है, फिर समीक्षक से सीमित diff पर दूसरा काम करने को कहता है।

3. Greptile की समीक्षा

Greptile पहले से ही GitHub या GitLab ऐप के ज़रिए repository से जुड़ा हुआ है। एक नए पुल रिक्वेस्ट पर, यह उस पूर्ण repo ग्राफ़ का उपयोग करके बदलाव का विश्लेषण करता है जिसे उसने बनाया है, और सुझाए गए सुधारों के साथ निष्कर्षों को टिप्पणी के रूप में प्रकाशित करता है। उनकी अपनी सामग्री इस चरण को लगभग तीन मिनट पर रखती है।

टिप्पणी को उसी तरह पढ़ें जैसे आप एक चौकस टीममेट को पढ़ेंगे: उद्धृत स्थान खोलें, तय करें कि निष्कर्ष सही है या नहीं, फिर कार्रवाई करें। जहाँ Greptile ‘Fix with your Agent’ प्रस्तुत करता है, यह मुद्दे को — फ़ाइल पथ, लाइन नंबर, सुझाया गया कोड — Claude Code, Codex, Conductor, Cursor, या Devin को भेजता है। ‘Fix All’ उस समीक्षा में सभी मुद्दों को एक साथ भेजता है। वे उस हैंडऑफ़ के लिए Greptile MCP और एक Claude Code प्लगइन भी प्रदान करते हैं। Maguyva उस नामित लक्ष्य सूची में नहीं है; वह अनुपस्थिति समस्या नहीं है। Maguyva ने अपना काम चरण 1 में पहले ही कर लिया। जिस कोडिंग एजेंट ने PR लिखा वह वह पक्ष है जिसे फ़िक्स पेलोड मिलना चाहिए।

पहले 2-3 सप्ताह के दौरान शोरगुल की उम्मीद करें जब Greptile का सीखने वाला सिस्टम उन वास्तविक टिप्पणियों के अनुकूल होता है जो आपकी टीम छोड़ती है। यह वह समयसीमा है जो वे बताते हैं, जोड़ी की खामी नहीं। मानवीय समीक्षा उस लूप में रहती है। Greptile एक स्वचालित पहला कदम है, मर्ज बटन नहीं।

अगर Greptile की टिप्पणी किसी ऐसी फ़ाइल की ओर इशारा करती है जिसे चरण 1 में एजेंट ने कभी नहीं पूछा, तो यह एक उपयोगी संकेत है। या तो मैप ने एक कॉलर मिस किया, या एजेंट ने एक उद्धरण छोड़ दिया। टिप्पणी के अनुसार ड्राफ्ट ठीक करें। समीक्षक को अक्षम न करें।

इस पूरक को ईमानदार कैसे रखें

Maguyva हमेशा पहले। गलत फ़ाइल के साथ PR की समीक्षा फिर भी गलत फ़ाइल की समीक्षा ही है।
Greptile हमेशा बाद में। अच्छी तरह उद्धृत ड्राफ्ट को भी सिस्टम-स्तरीय diff रीडिंग की ज़रूरत होती है।
Maguyva से PR टिप्पणियाँ प्रकाशित करने के लिए न कहें। यह ऐसा नहीं करता।
Greptile को एजेंट की पहली पुनर्प्राप्ति परत बनने के लिए न कहें जबकि वह अभी भी पथ चुन रहा है। यह उनके GitHub या GitLab ऐप के लिए डिज़ाइन किया गया काम नहीं है।
ऐसी bash पाइपलाइन का आविष्कार न करें जो दोनों को ‘सिंक’ करती है। PR ही वह इंटरफ़ेस है।
दोनों पक्षों को अलग-अलग सत्यापित करें। उस repo को इंडेक्स करें जिसे आप पहले से जानते हैं। एक सवाल पूछें जिसे आप सत्यापित कर सकते हैं। फिर एक छोटा PR खोलें और पढ़ें कि Greptile वास्तव में क्या टिप्पणी करता है।

एक बार नाम दिए जाने के बाद यह लूप साधारण बन जाता है। पहले मैप। एजेंट का PR। बाद में समीक्षा। हर उत्पाद पुल रिक्वेस्ट के उस पक्ष पर रहता है जिसमें वह विशेषज्ञ है।

// map first. review second. in that order.

बिना स्थानीय इंडेक्सर के AI एजेंट्स को बड़े repo का संदर्भ देना

Fri, 14 Aug 2026 00:00:00 GMT

बड़े रिपॉज़िटरी संदर्भ विंडो में फिट नहीं होते, और अगर आपने कभी लैपटॉप-आधारित इंडेक्सर को किसी वास्तविक monorepo पर चलाया है, तो आप जानते हैं कि यह वहाँ भी आराम से फिट नहीं होता — RAM बढ़ जाती है, पहला इंडेक्सिंग एक घंटे लेता है, और आपका एजेंट फिर भी अगला सत्र यह अनुमान लगाते हुए शुरू करता है कि कौन सी फ़ाइलें महत्वपूर्ण हैं।

सामान्य उत्तर है एडिटर के बगल में एक इंडेक्सर चलाना, और जो repo एक मशीन पर आराम से फिट होता है उसके लिए, यह एक अच्छा जवाब है। अगर आपका monorepo पहले से ही Cursor में तेज़ी से इंडेक्स होता है और वही एकमात्र जगह है जहाँ आपको मैप चाहिए, तो इस लेख में जोड़ने के लिए कुछ नहीं है — इसे छोड़ दें।

यह लेख दूसरे मामले के बारे में है — जब एक एजेंट को एक बड़े repo का उद्धृत करने योग्य मैप चाहिए, और आप उसे पाने के लिए स्थानीय इंडेक्सर नहीं चलाना चाहते।

स्थानीय इंडेक्सर कब गलत टूल बन जाता है

एक स्थानीय इंडेक्स मानता है कि कोड उसी मशीन पर रहता है जो इसे पूछती है, और असली monorepo पैमाने पर, वह धारणा एक ही एडिटर के भीतर भी खिंचती है। repo केवल उससे बड़ा है जितना आप अपने लैपटॉप पर ‘गर्म’ रखना चाहते हैं: आप एक पैकेज में काम कर रहे हैं जबकि ब्लास्ट रेडियस तीन डायरेक्टरी दूर है, और उस दो-मिलियन-लाइन ट्री के लिए पहला ठंडा इंडेक्स कुछ ऐसा नहीं है जिसे आप दो बार गुज़रना चाहते हैं — चाहे आपकी अपनी मशीन पर हो, या उस CI रनर पर जिसने पहले कभी वह ट्री क्लोन नहीं किया। या एक टीममेट को आपके जैसे ही मैप पूछने में सक्षम होना चाहिए, बिना अपनी मशीन को उसी इंडेक्स से जूझने का इंतज़ार किए।

इनमें से कोई भी एक अच्छे एडिटर इंडेक्सर को छोड़ने का कारण नहीं है। यह एक होस्टेड मैप भी रखने का कारण है जिसे आपका कोई भी एजेंट MCP के ज़रिए पूछ सकता है।

और वह पैमाना समस्या ‘चिपकाने के लिए बहुत सारी फ़ाइलें’ से गहरी है। एक बड़े ट्री पर, दिलचस्प सवाल लगभग कभी ‘मुझे यह फ़ाइल दिखाओ’ नहीं होता — यह होता है कौन सी फ़ाइल, कौन सा सिंबल, कौन कॉल करता है, कौन सा टेस्ट। एक एजेंट जो src/ सूचीबद्ध करके और पहले तीन परिणाम पढ़कर शुरू करता है, वह apps/api में हैंडलर और packages/sdk में जनरेट किए गए क्लाइंट को खुशी-खुशी मिस कर देगा। आपको जो चाहिए वह है पूरे ट्री से बनी पुनर्प्राप्ति, फिर रैंक की गई, फिर उद्धृत।

‘बड़े repo का संदर्भ’ का असल में क्या मतलब है

फ़ाइलों को प्रॉम्प्ट में डालना संदर्भ नहीं है — यह छोटे और खराब तरीके से किया गया ट्री का प्रतिलिपिकरण है। आपके एजेंट को वास्तव में जो चाहिए वह है सवाल पूछना और उद्धृत जवाब पाना: यह सिंबल कहाँ परिभाषित है और इसे कौन कॉल करता है, मैं जो मॉड्यूल बदलने वाला हूँ उस पर क्या निर्भर करता है, कौन सी टेस्ट फ़ाइलें इस व्यवहार को कवर करती हैं, और वह ट्री अभी कैसा दिखता है, पिछली तिमाही नहीं।

वे जवाब आपके repo से बने इंडेक्स से आने चाहिए, किसी और के repo के बारे में मॉडल की याददाश्त से नहीं, और वह इंडेक्स एजेंट की संदर्भ विंडो के बाहर कहीं रहना चाहिए। इस समस्या के लिए, यह आपके लैपटॉप के बाहर भी कहीं रहना चाहिए।

एक और चीज़ जो इंस्ट्रक्शन फ़ाइलें आपके लिए नहीं कर सकतीं: CLAUDE.md और AGENTS.md कन्वेंशन और व्यवहार के लिए सही जगह हैं, लेकिन वे दो-मिलियन-लाइन ट्री के लिए जीवित, रैंक की गई, उद्धरण योग्य मैप नहीं हैं। व्यवहार के लिए नियमों का उपयोग करें; तथ्यों के लिए repo इंटेलिजेंस का उपयोग करें।

हम क्लाउड में मैप बनाते हैं, आप इसे किसी भी क्लाइंट से पूछते हैं

Maguyva एक रिमोट MCP कोडबेस संदर्भ परत है। आप GitHub कनेक्ट करते हैं, अपनी repo चुनते हैं, और चले जा सकते हैं जबकि क्लाउड पाइपलाइन ट्री को पार्स करती है, सिंबल और ग्राफ़ एज बनाती है, और रैंक किया गया मैप बनाए रखती है — कभी भी स्थानीय इंडेक्सर की ज़रूरत नहीं।

जब आप कोड पुश करते हैं, बदली हुई फ़ाइलें क्रमिक रूप से पार्स होती हैं, और ग्राफ़ व रैंकिंग परतें एक शेड्यूल पर फिर से बनाई जाती हैं: मुफ़्त योजना पर दैनिक, भुगतान योजनाओं पर प्रति घंटा। हर स्नैपशॉट टाइमस्टैम्प किया जाता है, ताकि आपका एजेंट बता सके कि यह ट्री का कौन सा संस्करण पढ़ रहा है। यहाँ ईमानदार सीमा असिंक्रोनाइज़्ड स्थानीय काम है — जो बदलाव केवल आपकी वर्किंग ट्री में मौजूद हैं, कभी पुश नहीं हुए, वे अभी तक होस्टेड मैप में नहीं हैं।

फिर आप उस क्लाइंट के MCP कॉन्फ़िग में एक API कुंजी जोड़कर, जिसे आप पहले से उपयोग करते हैं, कनेक्ट करते हैं। 24 दस्तावेज़ीकृत MCP क्लाइंट्स के लिए सेटअप गाइड मौजूद हैं, और कोई भी अन्य MCP-संगत क्लाइंट जो मानक कॉन्फ़िगरेशन का समर्थन करता है, वह भी कनेक्ट हो सकता है। अगर Cursor वह जगह है जहाँ आप रहते हैं, Cursor पेज उस पथ को नक्शा करता है; वही सर्वर Claude Code, VS Code, Windsurf, Codex CLI और बाकियों को जवाब देता है।

आप एडिटर नहीं बदल रहे। आप अपने एजेंट को एक टूल सतह दे रहे हैं — सर्च, सिंबल, dependency विश्लेषण, फ़ाइल पुनर्प्राप्ति और रिपॉज़िटरी संदर्भ में 11 MCP टूल — जो 279 से अधिक भाषाओं और टेक्स्ट-आधारित तकनीकों को कवर करता है, जिसका मतलब है उससे कहीं ज़्यादा जितना आपने उस monorepo पर सोचा था जो बहुत पहले एक-भाषा होना बंद कर चुका है।

जवाब आधारित होकर वापस आते हैं, फ़ाइल पथों के रूप में लाइन नंबरों के साथ। Semantic, structural, graph, और text सर्च एक रैंक किए गए परिणाम में मिल जाते हैं, ताकि ‘parseConfig पर क्या निर्भर करता है’ जैसे सवाल आपको केवल grep का ढेर या एक ही semantic उद्धरण न दें, बल्कि उन कुछ जगहों को दें जो वास्तव में मायने रखती हैं।

एक ठोस गाइड

पूरी कंपनी को इंडेक्स करके शुरू न करें। यह वह पथ है जो काम करता है:

एक ऐसी repo चुनें जिसे आप पहले से अच्छी तरह जानते हैं — एक पैकेज जिसे आप मैन्युअल रूप से आंक सकते हैं, वह आपके पास मौजूद सबसे बड़े ट्री से ज़्यादा मूल्यवान है।
मुफ़्त में शुरू करें: 3 रिपो, 50 हज़ार इंडेक्स की गई लाइनें, सभी 11 टूल, कोई मासिक क्वेरी कोटा नहीं। अगर आपका प्रतिनिधि repo बड़ा है, तो मूल्य निर्धारण पेज इंडेक्स की गई कवरेज के अनुसार वर्कस्पेस स्तर ($0, $19, $49, $149) सूचीबद्ध करता है — सीट गिनती के अनुसार नहीं।
GitHub कनेक्ट करें और पहले इंडेक्सिंग के पूरा होने का इंतज़ार करें। आप स्थानीय रूप से कुछ भी संकलित नहीं कर रहे हैं।
अपना MCP क्लाइंट कनेक्ट करें — कुछ कॉन्फ़िग लाइनें। Maguyva एक रिमोट MCP सर्वर है, इसलिए कोई प्लगइन नहीं, कोई एक्सटेंशन नहीं, और कोई दूसरा एडिटर नहीं अपनाना है।
एक सवाल पूछें जिसे आप सत्यापित कर सकते हैं। ‘parseConfig पर क्या निर्भर करता है?’ या ‘लॉगिन सत्र समाप्ति कहाँ संभाली जाती है?’ फिर उद्धृत file.ext:line परिणाम खोलें और अपने सामने के ट्री से जाँचें।
उस उद्धरण के संपर्क में टिके रहने के बाद ही, आप एजेंट को संपादित करने देते हैं।

अगर पहली repo अच्छी तरह फिट बैठती है और आपकी ट्री बड़ी है, तो अपनी इंडेक्स की गई लाइनों और पुनर्निर्माण दर के अनुसार वर्कस्पेस को बढ़ाएँ। मनुष्य और एजेंट एक ही उपयोगकर्ता गिनती साझा करते हैं — Maguyva सीट्स के बजाय प्रति वर्कस्पेस चार्ज करता है — इसलिए लूप में तीसरा एजेंट जोड़ने से आपको कुछ अतिरिक्त नहीं मिलता।

एक्टिवेशन टेस्ट किसी भी पहली रन के लिए दस्तावेज़ीकरण की सिफारिश के समान है: उस repo को इंडेक्स करें जिसे आप पहले से जानते हैं, एक सवाल पूछें जिसे आप सत्यापित कर सकते हैं। बड़ा repo उस टेस्ट को नहीं बदलता; यह केवल पहली ग़लत फ़ाइल को अधिक महंगा बनाता है।

कनेक्ट होने के बाद क्या देखें

तीन चीज़ों पर नज़र रखें। ताज़गी: भुगतान योजनाएँ प्रति घंटा फिर से बनती हैं, मुफ़्त योजना दैनिक, और वह स्थानीय काम जो पुश नहीं हुआ वह मैप में नहीं होगा — यही व्यापार है जो आप स्वीकार कर रहे हैं। स्कोप: उन रिपो के प्रतिनिधि सेट को इंडेक्स करें, हर आर्काइव किए गए फ़ोर्क को नहीं; मुफ़्त स्तर जानबूझकर इतना बड़ा बनाया गया है कि यह जानने के लिए कि जवाब रखने लायक हैं या नहीं। और सत्यापन: एक बड़े repo का मैप जो पथ और लाइन नंबर उद्धृत नहीं कर सकता, वह केवल एक धीमा अनुमान इंजन है, इसलिए अपने एजेंट को पैच भेजने से पहले स्थान दिखाने के लिए कहें।

फिर वही टेस्ट चलाएँ जो आप एक छोटे repo पर चलाते। उस repo को इंडेक्स करें जिसे आप पहले से जानते हैं। एक सवाल पूछें जिसे आप सत्यापित कर सकते हैं। अगर मैप सही है, तो आपका एजेंट ठंडे ट्री से शुरू करना बंद कर देता है।

// no laptop got hot building this map.

आपके AI कोडिंग एजेंट फ़ाइल पथों का भ्रम क्यों बनाते हैं

Fri, 14 Aug 2026 00:00:00 GMT

यह संकेत गलत फ़ंक्शन बॉडी नहीं है। यह एक ऐसी फ़ाइल पर आत्मविश्वासी बदलाव है जो मौजूद ही नहीं है, या एक ऐसी फ़ाइल पर जो मौजूद है लेकिन वह उस व्यवहार को लागू नहीं करती।

आपने सत्र समाप्ति का फ़िक्स मांगा। एजेंट src/auth/session.ts खोलता है। पथ प्रशंसनीय है। यह गलत भी है। असली हैंडलर apps/api/src/middleware/expiry.ts में रहता है, जिसका नाम दो पुनर्संरचनाओं पहले बदला गया था। एजेंट आपसे झूठ नहीं बोल रहा। यह प्रशिक्षण पूर्वाग्रह और संदर्भ विंडो में पहले से मौजूद जो कुछ भी है, उसके आधार पर पथ-आकार की स्ट्रिंग पूरी कर रहा है।

यह वास्तविक रिपॉज़िटरी पर एक सामान्य विफलता पैटर्न है। मॉडल कोड लिख सकता है। इसकी गलती इसे लिखने के लिए गलत जगह चुनना है।

एजेंट्स पथों का आविष्कार क्यों करते हैं

कोडिंग एजेंट्स टूल्स से लैस अगला-टोकन भविष्यवाणी मॉडल हैं। जब आप कहते हैं ‘सत्र समाप्ति ठीक करो’, इसे कुछ भी पढ़ने या पैच करने से पहले एक फ़ाइल का नाम लेना चाहिए। अगर इसके पास पहले से आधारित मैप नहीं है, तो यह इनसे पथ बनाता है:

नामकरण कन्वेंशन जो इसने अन्य रिपॉज़िटरी में देखी हैं। src/auth/session.ts एक सामान्य रूप है।
फ़ाइलें जो पहले से बातचीत में हैं, जो वह फ़ाइल हो सकती है जो आपने पिछले हफ़्ते चिपकाई थी, न कि जो अभी मायने रखती है।
एक डायरेक्टरी लिस्टिंग जो इसने संयोग से चलाई, एक बड़े ट्री पर अधूरी।
इंस्ट्रक्शन फ़ाइलें। CLAUDE.md और AGENTS.md एजेंट को व्यवहार करने का तरीका बताती हैं। यह सिंबल, कॉलर, या वर्तमान पथों का जीवित इंडेक्स नहीं है।

इनमें से कोई भी स्रोत इस repo का मैप नहीं है, आज। मॉडल अंतराल को उसी तरह भरता है जैसे वह किसी भी अंतराल को भरता है: उच्च-संभावना निरंतरता के साथ। वह निरंतरता अक्सर एक वास्तविक पथ जैसी दिखती है। कभी-कभी फ़ाइल मौजूद होती है और सही पड़ोस में बैठी होती है। कभी-कभी यह पिछले महीने मर्ज हुई एक शाखा पर मौजूद होती है। कभी-कभी यह कभी अस्तित्व में ही नहीं थी।

Grep यहाँ आपको नहीं बचाता अगर एजेंट पहले सही स्ट्रिंग की खोज ही नहीं करता। एजेंट एक पथ का अनुमान लगाता है, फिर वह पथ जो लौटाता है उसे पढ़ता है, फिर उसे संपादित करता है। पहला गलत कदम पथ है, पैच नहीं।

फ़ाइलें पढ़ना सही खोजने के समान भी नहीं है। Claude Code, Cursor, Codex, और इसी तरह के टूल आपके द्वारा दिखाई गई किसी भी चीज़ को खोल सकते हैं। सवाल यह है कि क्या वे संपादित करने से पहले विश्वसनीय रूप से सही फ़ाइल, महत्वपूर्ण सिंबल, डिपेंडेंसी, टेस्ट, और ब्लास्ट रेडियस ढूँढते हैं। बिना मैप के फ़ाइल एक्सेस अभी भी अनुमान से शुरू होता है।

गलत फ़ाइल संपादित करना एक पुनर्प्राप्ति समस्या है

आविष्कृत पथ को एक पुनर्प्राप्ति गलती के रूप में सोचें, कोई चरित्र दोष नहीं।

अगर एजेंट को संपादित करने की अनुमति देने से पहले path/file.ext:line वापस लाना पड़े, तो दो चीज़ें होती हैं। पहला, आप उद्धरण खोल सकते हैं और दस सेकंड में काम को अस्वीकार कर सकते हैं। दूसरा, एजेंट को कुछ ऐसा पूछना पड़ता है जो वास्तव में उस ट्री को जानता है।

यही कोडबेस संदर्भ परत का काम है। अकेले semantic सर्च पर्याप्त नहीं है। एक उद्धरण जो ‘सत्र समाप्ति जैसा लगता है’ फिर भी एक अप्रचलित पैकेज में उतर सकता है। आपको सटीक टेक्स्ट भी चाहिए जब आप स्ट्रिंग जानते हैं, सिंबल सर्च जब आप नाम जानते हैं, structural सर्च जब आप आकार जानते हैं, और dependency ग्राफ़ जब आपको कॉलर व ब्लास्ट रेडियस चाहिए।

Maguyva MCP-संगत कोडिंग एजेंट्स के लिए वह परत है। यह एडिटर नहीं है। Claude Code, Cursor, Codex CLI, VS Code, Windsurf, और अन्य MCP क्लाइंट्स अपनी जगह पर बने रहते हैं। एजेंट एक लाइन छूने से पहले रैंक किए गए मैप को पूछता है।

जो दावा किया गया है वह जानबूझकर मामूली है: कम भ्रामक बदलाव। Maguyva मॉडल से अनुमान लगाने की क्षमता नहीं छीनता। यह डिफ़ॉल्ट पहले कदम को ‘प्रशंसनीय पथ का आविष्कार करो’ से बदलकर ‘रैंक किए गए, उद्धृत स्थान मांगो’ कर देता है।

एक आधारित जवाब कैसा दिखता है

‘सत्र समाप्ति कहाँ संभाली जाती है’ का उपयोगी जवाब एक पैराग्राफ नहीं है। यह छोटे स्थानों की एक सूची है:

apps/api/src/middleware/expiry.ts:48 - हैंडलर
apps/web/src/lib/auth-client.ts:112 - कॉलर
apps/api/tests/expiry.test.ts:20 - टेस्ट जो अगर बदलाव गलत है तो विफल होगा

आप इन लाइनों को खोल सकते हैं। अगर गलत हैं, तो आप रुक जाते हैं। अगर सही हैं, तो एजेंट संपादित कर सकता है। सत्यापन ही मुख्य बात है, नारा नहीं।

Maguyva सर्च, सिंबल, dependency विश्लेषण, फ़ाइल पुनर्प्राप्ति, रिपॉज़िटरी संदर्भ, और नियतात्मक यूटिलिटी-टूल वर्कफ़्लो में 11 ग्राहक-सामना करने वाले MCP टूल उजागर करता है। चार पुनर्प्राप्ति मोड (semantic, structural, graph/dependency, और text) एक रैंक किए गए परिणाम में मिलते हैं; सिंबल सर्च एक अलग MCP टूल है (find_symbol)। आधारित जवाब फ़ाइल पथों और लाइन नंबरों के साथ वापस आते हैं, ताकि आप उन्हें अपने सामने के ट्री के मुकाबले आंक सकें।

दस्तावेज़ीकरण सबसे छोटा पथ बताता है: मुफ़्त में शुरू करें, उस repo को इंडेक्स करें जिसे आप पहले से जानते हैं, क्लाइंट कनेक्ट करें, फिर एक सवाल पूछें जिसे आप सत्यापित कर सकते हैं।

वह लूप जो पहला बदलाव बदल देता है

आपको एक नए वर्कफ़्लो धर्म की ज़रूरत नहीं है। आपको पहली लिखाई से पहले एक अतिरिक्त कदम चाहिए।

एक ऐसा सवाल पूछें जिसे आप पहले से आंक सकते हैं। ‘लॉगिन और सत्र समाप्ति किस कोड में संभाली जाती है?’ ‘auth ठीक करो’ से बेहतर है।
उद्धरण मांगें। फ़ाइल पथ और लाइन नंबर, न कि ‘auth मॉड्यूल’ का सारांश।
उद्धृत फ़ाइल खोलें। सिंबल का पीछा करें। उन डिपेंडेंसी की पुष्टि करें जिन्हें आप छूने वाले हैं।
उसके बाद ही एजेंट को पैच करने दें।

अगर चरण 2 कुछ भी उपयोगी नहीं लौटाता, तो एजेंट को पथ पर सुधार करने का कोई अधिकार नहीं। यह फिर से खोज करता है, या आप उसे दिखाते हैं। यही एक गेट है जो कम भ्रामक बदलाव पैदा करता है। मॉडल वही मॉडल है। मैप वह चीज़ है जो बदलती है।

इंस्ट्रक्शन फ़ाइलें फिर भी मायने रखती हैं। उन्हें बनाए रखें। कन्वेंशन, समीक्षा नियम, और जो नहीं छूना चाहिए उसके लिए उनका उपयोग करें। इसे इंडेक्स बनने के लिए न कहें। CLAUDE.md जो तीन महत्वपूर्ण डायरेक्टरी सूचीबद्ध करता है, वह एक पैकेज विभाजन के एक हफ़्ते बाद पुराना हो जाएगा। जिस मैप को पूछा जा सकता है वह repo के अपडेट होने पर अपडेट होता है।

एक संबंधित विफलता है लगभग-सही फ़ाइल: एजेंट auth.ts खोलता है जबकि व्यवहार auth-client.ts में रहता है, या स्रोत के बजाय जनरेट की गई फ़ाइल को पैच करता है, या packages/legacy में एक प्रतिलिपि को संपादित करता है क्योंकि नाम मेल खाता है। उद्धरण इन गलतियों को असंभव नहीं बनाते। वे इन्हें diff उतरने से पहले दिखाई देने योग्य बनाते हैं।

मैप आपके लिए क्या ठीक नहीं करेगा

आपको जो मिलता है उसके बारे में ईमानदार रहें। एक आधारित मैप हर बदलाव को सही नहीं बनाएगा — आपका एजेंट फिर भी बिल्कुल सही फ़ाइल पर एक खराब पैच लिख सकता है। अगर आपका कोडबेस डायनामिक डिस्पैच, रिफ़्लेक्शन, या मंकी-पैचिंग पर निर्भर है, तो कुछ सिंबल सर्च आपकी उम्मीद से पतले परिणाम देंगे, क्योंकि रनटाइम अप्रत्यक्षता किसी भी स्टेटिक इंडेक्स के साथ यही करती है। और अगर आप एक प्रतिशत की उम्मीद कर रहे हैं — ‘भ्रामक पथ X% कम हुए’ — तो आपको यह यहाँ नहीं मिलेगा, क्योंकि कोई भी आपके repo के लिए वह संख्या ईमानदारी से आपके सिवा किसी और के लिए माप नहीं सकता।

जो आप उम्मीद कर सकते हैं वह संकरा और अधिक उपयोगी है: एजेंट अपने बदलाव को अनुमानित पथ से शुरू करना बंद कर देता है। वह पहला कदम असली मैप में आधारित हो जाता है, और वहीं से कम भ्रामक बदलाव आते हैं। उद्धरण के बाद की हर चीज़ — diff पढ़ना, पैच को आंकना — फिर भी आपका काम है, जैसा यह हमेशा से रहा है।

यह टेस्ट लगभग आपको कुछ भी खर्च नहीं करता: उस repo को इंडेक्स करें जिसे आप पहले से जानते हैं और एक सवाल पूछें जिसे आप सत्यापित कर सकते हैं। उस पथ से शुरू करें जिसने पहले आपको जलाया था। अगर उद्धरण गलत है, तो आप इसे तुरंत देखेंगे। अगर सही है, तो आपके एजेंट का अगला बदलाव उतरने के लिए एक बेहतर जगह रखता है।

// it doesn't know the file. it knows how to find it.

हमने कोड सर्च को voyage-4-large में क्यों अपग्रेड किया

Tue, 09 Jun 2026 00:00:00 GMT

इस पोस्ट में दिए गए बेंचमार्क आंकड़े प्रकाशन के समय (जून 2026) के RTEB लीडरबोर्ड को दर्शाते हैं। लीडरबोर्ड बदलते रहते हैं; रैंकिंग को एक स्नैपशॉट मानें, स्थायी तथ्य नहीं।

सिमेंटिक सर्च सिर्फ़ उतनी ही अच्छी होती है जितनी उसके नीचे मौजूद एम्बेडिंग।

जब कोई एजेंट Maguyva से पूछता है “हम रीट्राई कहां हैंडल करते हैं,” तो वह “retry” शब्द के लिए grep नहीं कर रहा होता। वह अर्थ पूछ रहा होता है — बैकऑफ़ लूप, सर्किट ब्रेकर, वह चीज़ जो किसी अस्थिर कॉल को लपेटती है। उस सवाल का जवाब एक वेक्टर मॉडल देता है जो कोड को स्पेस में एक बिंदु में बदल देता है और पड़ोसियों को खोजता है। बेहतर मॉडल चुनें और प्रोडक्ट में हर सिमेंटिक क्वेरी के नतीजे बेहतर हो जाते हैं।

तो हमने अपना बदल दिया। जून 2026 से, Maguyva की कोड एम्बेडिंग voyage-4-large पर चलती हैं, जिसने voyage-code-3 की जगह ली है।

बेंचमार्क

हमने यह फ़ैसला किसी अनुमान पर नहीं लिया। पब्लिक Retrieval Embedding Benchmark (RTEB) असली रिट्रीवल टास्क पर एम्बेडिंग मॉडल को रैंक करता है, और इसके Code लीडरबोर्ड पर voyage-4-large कुल मिलाकर #1 (90.86) पर है — gemini-embedding-2-preview (90.26) से आगे, और उल्लेखनीय रूप से, उस मॉडल से भी आगे जिसे हम पहले से उपयोग कर रहे थे, voyage-code-3 (89.73, #3)।

यह निरपेक्ष रूप से छोटा-सा अंतर है। लेकिन यह सही दिशा में एक अंतर है, एक पब्लिक बेंचमार्क पर, ठीक उसी टास्क पर जिसकी हमें परवाह है: अर्थ के आधार पर कोड को रिट्रीव करना।

जो ट्रेड-ऑफ़ हम स्वीकार करते हैं: बाइनरी क्वांटाइज़ेशन

यहां वह हिस्सा है जिसे ज़्यादातर “हमने अपना मॉडल अपग्रेड किया” पोस्ट छोड़ देती हैं।

Maguyva पूर्ण-सटीकता वाले वेक्टर स्टोर नहीं करता। हम बाइनरी-क्वांटाइज़्ड एम्बेडिंग स्टोर करते हैं: हर 2048-डायमेंशनल वेक्टर एक 2048-बिट सिग्नेचर में सिमट जाता है — प्रति वेक्टर 256 बाइट्स। उन सिग्नेचर को Hamming distance से सर्च किया जाता है, इंडेक्स्ड और प्रति टेनेंट पार्टीशन्ड।

यह एक जानबूझकर किया गया ट्रेड-ऑफ़ है। बाइनरी क्वांटाइज़ेशन कुछ रिट्रीवल प्रिसिज़न के बदले नाटकीय रूप से छोटा स्टोरेज और तेज़, सस्ता डिस्टेंस मैथ देता है, बिना किसी अलग वेक्टर डेटाबेस को ऑपरेट किए। ऐसे प्रोडक्ट के लिए जो प्रति वर्कस्पेस पूरी रिपॉज़िटरी इंडेक्स करता है, यह इकोनॉमिक्स बेंचमार्क पॉइंट के आख़िरी हिस्से को निचोड़ने से ज़्यादा मायने रखती है।

voyage-4-large स्टोरेज लेयर के माइग्रेशन को मजबूर किए बिना इस डिज़ाइन में फ़िट बैठता है: यह 2048-डायमेंशनल आउटपुट देता है, ठीक voyage-code-3 की तरह, तो हमारे bit(2048) कॉलम और Hamming सर्च पथ नहीं बदले। मॉडल बेहतर हो गया; स्कीमा जगह पर बनी रही।

कोड तो बस शुरुआत थी

Maguyva एक कोड-इंटेलिजेंस टूल है। लेकिन हम ख़ुद भी अपने पहले ग्राहक हैं, और हम इसे किसी और चीज़ पर भी लगाते हैं: वह मार्कडाउन जो कोड के साथ हमारी रिपॉज़िटरी में रहता है। आर्किटेक्चर डिसीज़न रिकॉर्ड, रनबुक, कॉन्ट्रैक्ट, फ़ाइनेंस और पॉलिसी डॉक्स — यह सब Git में वर्ज़न-कंट्रोल्ड है, यह सब उसी MCP सर्वर के पीछे है, दस्तावेज़ों पर एक सिमेंटिक इंडेक्स, न कि सिर्फ़ सोर्स पर।

यही ठीक वह वजह है कि voyage-4-large की व्यापकता मायने रखती है। लीडरबोर्ड के उसी RTEB परिवार पर यह फ़ाइनेंस पर #1, हेल्थकेयर पर #1, और कुल टेक्स्ट रिट्रीवल पर #1 है — Google के Gemini Embedding, Cohere के Embed v4, और OpenAI के text-embedding-3-large से आगे। (Voyage, RTEB का सह-निर्माता है, इसलिए हम इसे एक बिल्कुल निष्पक्ष रेफ़री के बजाय एक मज़बूत पब्लिक सिग्नल के रूप में पढ़ते हैं — लेकिन इसे हर बड़े कमर्शियल मॉडल के विरुद्ध, प्राइवेट होल्ड-आउट सेट पर, आमने-सामने बेंचमार्क किया गया है।) वही इंडेक्स जो किसी एजेंट के लिए सही फ़ंक्शन खोजता है, किसी कॉन्ट्रैक्ट में सही क्लॉज़ या किसी पॉलिसी में सही लाइन भी खोजता है — और उन डोमेन में, voyage-4-large कोई समझौता नहीं है, यह लीडर है।

हम प्रीमियम एम्बेडिंग के लिए भुगतान क्यों करते हैं

सर्च करने का एक सस्ता तरीक़ा है, और उसका बड़ा हिस्सा मुफ़्त है। लेक्सिकल सर्च — BM25 और उसके जैसे — कीवर्ड मैच करते हैं, लोकली चलते हैं, और कुछ भी ख़र्च नहीं करते। BGE, Nomic, और embeddinggemma जैसे ओपन-सोर्स एम्बेडिंग मॉडल वाक़ई ठीक-ठाक सिमेंटिक रिट्रीवल देते हैं, और आप इन्हें एक GPU की क़ीमत पर सेल्फ़-होस्ट कर सकते हैं। Maguyva मुफ़्त पक्ष का भी उपयोग करता है: हर क्वेरी टेक्स्ट, AST, ग्राफ, और सिमेंटिक सर्च को मिलाती है। जिस चीज़ पर हम कंजूसी नहीं करते वह है सिमेंटिक लेयर।

हम एक मुफ़्त मॉडल सेल्फ़-होस्ट करने के बजाय प्रीमियम एम्बेडिंग — voyage-4-large — के लिए प्रति टोकन भुगतान करते हैं, दो वजहों से। पहला, अकेले कीवर्ड सर्च “हम रीट्राई कहां हैंडल करते हैं” का जवाब नहीं दे सकती जब कोड backoff और circuit breaker कहता है और कभी “retry” शब्द नहीं कहता — अर्थ ही एम्बेडिंग का पूरा मक़सद है, और हम जिन डोमेन को सर्व करते हैं उन पर ओपन मॉडल प्रीमियम मॉडल से पीछे रहते हैं: सामान्य टेक्स्ट पर कुछ पॉइंट पीछे, और कोड, कॉन्ट्रैक्ट, और फ़ाइनेंस जैसी नीश में और ज़्यादा पीछे। दूसरा, हमारे अनुभव में रिट्रीवल क्वालिटी अंतिम जवाब को दूसरी तरफ़ के मॉडल से कहीं ज़्यादा आकार देती है — एक मज़बूत एजेंट को भी ग़लत कॉन्टेक्स्ट दिया जाए तो वह ग़लत जवाब ही देता है, और वह उस दस्तावेज़ को कभी नहीं देखता जो उसे कभी दिया ही नहीं गया।

तो प्रीमियम एम्बेडिंग एक प्रति-टोकन बिल है जो हर रिपॉज़िटरी और दस्तावेज़ के साथ स्केल करता है जिसे हम इंडेक्स करते हैं — और हम इसे जानबूझकर चुकाते हैं। हमारे उपयोगकर्ताओं को मिलने वाले नतीजे के लिए, सही फ़ंक्शन या सही क्लॉज़, हमें लगता है कि यह ट्रेड-ऑफ़ इसके लायक़ है।

ईमानदार हिस्सा

Voyage का अपना डॉक्यूमेंटेशन अब भी voyage-code-3 को कोड-ऑप्टिमाइज़्ड मॉडल के रूप में लेबल करता है। तो हमने बदलाव क्यों किया?

क्योंकि हमने पब्लिक बेंचमार्क पढ़ा, सिर्फ़ वेंडर की मॉडल टेबल नहीं, और बेंचमार्क ने कोड रिट्रीवल के लिए voyage-4-large को सबसे ऊपर रखा। यह भविष्य को ध्यान में रखकर लिया गया फ़ैसला था: नए, आम तौर पर मज़बूत मॉडल को लें और उन टास्क पर एक पब्लिक लीडरबोर्ड के विरुद्ध उसे वैलिडेट करें जो मायने रखते हैं। हम यह दांव लगाने में सहज हैं क्योंकि साक्ष्य व्यापक है — voyage-4-large सिर्फ़ कोड पर नहीं जीतता, यह फ़ाइनेंस, हेल्थकेयर, और कुल रिट्रीवल पर भी आगे है।

शांत बुनियाद

हम जो भी टूल एक्सपोज़ करते हैं — सिमेंटिक सर्च, टास्क-कॉन्टेक्स्ट संग्रह, साक्ष्य-आधारित प्रश्नोत्तर — आख़िर में रिट्रीवल पर टिकते हैं। जब रिट्रीवर बेहतर होता है, तो दूसरी तरफ़ मौजूद एजेंट को बेहतर साक्ष्य मिलता है, वह कम ग़लत मोड़ लेता है, और अपने जवाबों को सही कोड में — या सही क्लॉज़, या सही पॉलिसी में — जड़ देता है। ज़्यादा सटीक नतीजे देने वाला एम्बेडिंग मॉडल कोई चमकदार फ़ीचर नहीं है। यह बाक़ी सब कुछ के नीचे की बुनियाद है, और हमने उसे अभी ऊंचा किया है। आपको इसका पता नहीं चलेगा। यही तो मक़सद है।

भाषाओं के लिए पुनरावर्ती स्व-सुधार: लगभग 280 भाषाओं में कोड इंटेलिजेंस को अनथक मेहनत से निखारना

Tue, 26 May 2026 00:00:00 GMT

इस पोस्ट में दिए गए आंकड़े प्रकाशन के समय (मई 2026) की सिस्टम स्थिति दर्शाते हैं। मौजूदा आंकड़ों के लिए हमारा टीम पेज देखें।

Maguyva लगभग 280 भाषाओं के सोर्स कोड से सिंबल, रेफ़रेंस, और एक डिपेंडेंसी ग्राफ एक्सट्रैक्ट करता है। हर भाषा एक कस्टम tree-sitter हैंडलर है — क्वेरी, हेयुरिस्टिक्स, एज केस — और हर हैंडलर अपने ही तरीक़े से सूक्ष्म रूप से ग़लत हो सकता है। एक मेथड कॉल जो रीड के रूप में उत्सर्जित हो जाए। एक फ़ंक्शन जो ग़लत संलग्न स्कोप को दे दिया जाए। एक रिलेशनशिप जो सिरे से मौजूद ही न हो।

यह हाथ से ऑडिट नहीं किया जा सकता। कोई भी टीम 280 ग्रामर में एक्सट्रैक्शन आउटपुट पढ़कर ख़राब एज नहीं पकड़ सकती। तो दिलचस्प सवाल यह नहीं है कि “क्या हमारा एक्सट्रैक्शन सही है” — यह है कि “इतने बड़े विस्तार पर, बिना हर लूप में इंसान को शामिल किए, आप यह पता कैसे लगाते हैं कि वह ग़लत है।” हमारा जवाब है भाषाओं के लिए पुनरावर्ती स्व-सुधार: भाषा एजेंट्स से संचालित एक क्वालिटी लूप, जज के रूप में काम करता एक LLM, और एक नियम जिसे हम बार-बार सीखते रहते हैं: ग्रीन होना सही होने के बराबर नहीं है।

ग्रीन होना सही नहीं है

हर भाषा के पास एक फ़िक्स्चर सुइट है, और एक रिलीज़ गेट उसे पांच आयामों पर स्कोर करता है — सटीकता, संरचनात्मक अखंडता, पूर्णता, गुणवत्ता, और परफ़ॉर्मेंस। कोई भाषा GREEN तभी बनती है जब, अपने फ़िक्स्चर पर, precision ≥ 0.95, recall ≥ 0.99, और F1 ≥ 0.97 हो, साथ ही सांख्यिकीय भरोसे के लिए कम-से-कम 20 अपेक्षित एज हों। इससे नीचे यह YELLOW या RED है, और यह शिप नहीं होती।

वह गेट ज़रूरी तो है, लेकिन पर्याप्त नहीं। फ़िक्स्चर के ज़रिए वैलिडेशन उन्हीं मामलों तक सीमित रहता है जो हमने लिखे। वे उन मामलों को दर्ज करते हैं जिनके बारे में हम पहले ही सोच चुके थे। कोई हैंडलर अपने फ़िक्स्चर पर बेदाग़ हो सकता है और फिर भी ऐसे पैटर्न को बिगाड़ सकता है जो सिर्फ़ असली कोड में दिखाई देता है — कोई मैक्रो मुहावरा, कोई जेनेरिक-बाउंड मेथड, कोई भाषा फ़ीचर जिसके लिए किसी ने फ़िक्स्चर नहीं लिखा। GREEN का मतलब है कि फ़िक्स्चर पास हो गए। इसका मतलब यह नहीं कि कोई असली रिपॉज़िटरी साफ़-सुथरे तरीक़े से एक्सट्रैक्ट होती है। तो लूप को फ़िक्स्चर से आगे बढ़कर वास्तविक कोड को देखना पड़ता है।

भीतरी लूप: स्पॉट-चेक, जज, फ़िक्स, साबित करो

कोर लूप एक बार में एक भाषा चलाता है:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

कुछ चीज़ें इसे बेकार की उठापटक के बजाय असरदार बनाती हैं।

जज एजेंट है, कोई API कॉल नहीं। जब हम कहते हैं “LLM-as-judge,” तो हमारा मतलब है कि भाषा एजेंट ख़ुद हर सैंपल की गई एज को असली सोर्स के विरुद्ध पढ़ता है और उसे एक तय पांच-श्रेणी रूब्रिक से वर्गीकृत करता है: क्या यह एज सही है, एक फ़ॉल्स पॉज़िटिव है, सही रिलेशनशिप है लेकिन ग़लत टाइप के साथ, ग़लत स्कोप से जुड़ी है, या ग़लत मेटाडेटा ले जा रही है? वह रूब्रिक ही पूरा खेल है — “23% एरर रेट” तब तक बेमानी है जब तक आपको पता न हो कि वे असली दोष हैं या जज की ग़लत गिनती।

एक चीज़ ठीक करो, फिर उसे साबित करो। हर इटरेशन ठीक एक एडिटेबल एसेट को बदलता है, फिर एक तय हार्नेस के विरुद्ध दोबारा चलता है और बदलाव को तभी बनाए रखता है जब F1 सुधरे और दोबारा वर्गीकरण बेहतर दिखे। अगर ऐसा नहीं होता, तो वह वापस पलट जाता है। अटकलबाज़ी वाले एडिट का कोई बैच नहीं, कोई “बेहतर होना चाहिए” नहीं। कोई बदलाव अपनी जगह कमाता है या ख़त्म हो जाता है। और जब कोई फ़िक्स टिक जाता है, तो उसे फ़िक्स्चर सुइट में प्रमोट कर दिया जाता है — ताकि जो बग उसने ठीक किया वह चुपचाप कभी वापस न आ सके। यही प्रमोशन चरण है जो लूप को सिर्फ़ दोहराव की जगह पुनरावर्ती बनाता है: हर पास अगले पास के वैलिडेशन के लिए ओरेकल को और मज़बूत करता है।

वह सबक़ जिसे हम बार-बार सीखते रहते हैं: मेट्रिक्स ओवर-रिपोर्ट करते हैं

यहां वह जाल है, जिसमें हम सीधे जा फंसे। सेकंडरी कॉर्पस मेट्रिक्स — कितनी बार किसी एक्सट्रैक्ट किए गए टारगेट का कोई रिज़ॉल्व करने योग्य सिंबल नहीं होता, कितने सिंबल “अनाथ” दिखते हैं, वगैरह — समस्याओं को बहुत ज़्यादा ओवर-रिपोर्ट करते हैं। वे ज़्यादातर पैराडाइम आर्टिफ़ैक्ट हैं, बग नहीं।

सबसे साफ़ उदाहरण: llvm ने एक बार 73% “सोर्स-बिना-सिंबल” रेट दिखाई और उसे विनाशकारी क़रार दे दिया गया। हमने गहराई से देखा। असली सटीकता 98.5% थी। “मिसिंग सिंबल” लगभग सभी वैध बाहरी रेफ़रेंस थे — स्टैंडर्ड लाइब्रेरी में, फ़्रेमवर्क में, ऐसे कोड में जो रिपॉज़िटरी के बाहर रहता है, किए गए कॉल। यह मेट्रिक भाषा की एक विशेषता माप रहा था, हैंडलर का कोई दोष नहीं। Zig, COBOL, और Odin जैसी भाषाएं 65–70% “अनाथ” रेट दिखाती हैं और पूरी तरह सही हैं; COBOL में शून्य असली त्रुटियां थीं।

अगर हमने उन आंकड़ों को काम की दिशा तय करने दी होती, तो हम उन हैंडलर को “ठीक” करने में हफ़्तों बिता देते जो पहले से ही सही थे, और उन भाषाओं को नज़रअंदाज़ कर देते जिनमें ख़ामोश, असली बग थे। नतीजा सीधा है: कुल मिलाकर मेट्रिक्स ज़्यादा-से-ज़्यादा एक मोटा ट्राइएज सिग्नल हैं। असली क्वालिटी सिग्नल एज क्लासिफ़िकेशन के साथ स्पॉट-चेक है — असली रिपॉज़िटरी में असली एज को देखना और उन्हें एक-एक करके परखना। अंतर्ज्ञान से ऊपर डेटा, लेकिन तभी जब आपको पता हो कि कौन-सा डेटा सच बोल रहा है।

बाहरी लूप: एक फ़्लीट, कोई मैराथन नहीं

280 भाषाओं में एक बार में एक भाषा चलाने में बेहद लंबा समय लग जाता, इसलिए भीतरी लूप को एक बाहरी लूप में लपेट दिया गया है जो कई भाषाओं को समानांतर में चलाता है।

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

हर एजेंट एक डिस्पोज़ेबल worktree में काम करता है ताकि वे एक-दूसरे के रास्ते में न आएं। ऑर्केस्ट्रेटर उनके फ़िक्स को एक-एक करके इंटीग्रेट करता है, हर एक फ़ुल-मैनिफ़ेस्ट रिग्रेशन चेक के पीछे: कोई बदलाव जो अपनी ही भाषा की मदद करे लेकिन चुपचाप तीन और को तोड़ दे, लैंड नहीं होता। कुछ भी पुश होने से पहले इंटीग्रेशन गेटेड और कन्फ़र्म्ड होता है — रिग्रेशन गेट तय करता है कि क्या सुरक्षित है, कोई इंसान अब भी तय करता है कि क्या शिप होगा। फिर पूल अगली भाषाओं के सेट पर घूम जाता है और पूरी प्रक्रिया फिर से चलती है।

अब भी क्या अधूरा है

जज ग़लत हो सकता है, और ग़लती की एक दिशा होती है: बहुत कम कॉन्टेक्स्ट के साथ चल रहा एजेंट ओवर-रिपोर्ट करता है। एक बैच में, आठ भाषाओं को 5–20% एरर पर फ़्लैग किया गया; जांच करने पर सिर्फ़ एक असली प्रति-भाषा बग निकला — बाक़ी भाषा के अपने सिमेंटिक्स को चूकने से हुई जज की ग़लतियां थीं (एक सोर्स लाइन जो वैध रूप से कई एज उत्सर्जित करती है, पैरामीटर बाइंडिंग जिन्हें असाइनमेंट के रूप में मॉडल किया गया, हर आइडेंटिफ़ायर के लिए एक रेफ़रेंस बनाने वाली भाषाएं)। यही वजह है कि हम दो सीड के साथ सैंपल करते हैं और क्रॉस-चेक करते हैं, और यही वजह है कि जज और फ़िक्स्चर के बीच असहमति को सबसे दिलचस्प सिग्नल माना जाता है, कोई तय फ़ैसला नहीं — कभी-कभी ग़लत चीज़ ख़ुद फ़िक्स्चर होता है।

हम लक्ष्य के बारे में भी ईमानदार हैं। लक्ष्य शून्य असली त्रुटियां हैं, बस — लेकिन “शून्य” वह दिशा है जिसकी ओर हम भाषा-दर-भाषा अनथक मेहनत करते हैं, कोई ऐसा बॉक्स नहीं जिसे चेक कर दिया जाए। हमेशा कोई और रिपॉज़िटरी किसी और मुहावरे के साथ मौजूद रहती है।

दावा नहीं, अर्जित

Maguyva किसी एजेंट के लिए जो कुछ भी करता है — कोई सिंबल खोजना, कोई डिपेंडेंसी ट्रेस करना, उद्धृत कोड के साथ किसी सवाल का जवाब देना — यह सब नीचे मौजूद एक्सट्रैक्शन के सही होने पर टिका है। 280 भाषाओं में, “सही” होने का दावा नहीं किया जा सकता; इसे असली कोड के विरुद्ध लगातार अर्जित करना पड़ता है। लूप ही वह तरीक़ा है जिससे हम इसे अर्जित करते हैं: एक ऑटोनॉमस स्पॉट-चेक-और-फ़िक्स चक्र जो अपने ही मेट्रिक्स को शक की नज़र से देखता है, हर बदलाव को साबित करता है, और हर फ़िक्स को अगले रिग्रेशन के ख़िलाफ़ एक गार्ड में बदल देता है। यह चमकदार नहीं है। यह वह काम है जो हमें “हम आपकी भाषा सपोर्ट करते हैं” कहने और उसका मतलब निभाने की इजाज़त देता है। ग्रीन होना आसान है। सही होना अर्जित किया जाता है।

मल्टी-मोडल फ़्यूज़न सर्च: हर क्वेरी के लिए सही रिट्रीवर चुनना

Wed, 15 Apr 2026 00:00:00 GMT

ऐतिहासिक डिज़ाइन नोट: अप्रैल 2026 का यह लेख उस समय के रूटिंग डिज़ाइन का वर्णन करता है, वर्तमान डिफ़ॉल्ट व्यवहार का नहीं। नीचे दिया गया सितंबर का सुधार केवल मापन-संबंधी दावे को संबोधित करता है। वर्तमान रूटिंग, प्रीसेट और स्पष्ट मोडैलिटी नियंत्रणों के लिए यह कैसे काम करता है देखें।

सर्च क्वेरी कोई एक चीज़ नहीं होती।

“parseConfig कहां परिभाषित है” को एक सटीक सिंबल चाहिए — एक सटीक लोकेशन, तेज़ी से। “authentication कैसे काम करता है” को अर्थ चाहिए — संबंधित कोड का वह फैलाव जो किसी अवधारणा को समझाता है। “अगर मैं यह फ़ंक्शन बदलूं तो क्या टूटता है” को डिपेंडेंसी ग्राफ चाहिए। “स्ट्रिंग ECONNREFUSED खोजें” को एक लिटरल मैच चाहिए, कुछ भी चतुराई भरा नहीं।

grep लिटरल मैच के लिए बेहतरीन है और कुछ रेफ़रेंस खोजों के लिए उपयोगी है, लेकिन यह कोई डिपेंडेंसी ग्राफ नहीं है और यह अर्थ नहीं समझता। एम्बेडिंग सिमेंटिक पक्ष को कवर करती हैं, लेकिन ये सटीक स्ट्रिंग और इम्पैक्ट विश्लेषण के लिए ग़लत टूल हैं। ज़्यादातर कोड सर्च टूल एक इंजन चुनते हैं और हर क्वेरी को उसी चुनाव के साथ जीने पर मजबूर करते हैं। Maguyva नहीं चुनता। यह पता लगाता है कि आपने किस तरह का सवाल पूछा, फिर उस सवाल की ज़रूरत के अनुसार चार रिट्रीवर को मिलाता है।

चार मोडैलिटी

अंदरखाने, कोड खोजने के चार स्वतंत्र तरीक़े हैं:

semantic — Voyage बाइनरी एम्बेडिंग पर वेक्टर सर्च; अर्थ के आधार पर कोड खोजता है।
text — ट्राइग्राम मैचिंग; लिटरल, एरर स्ट्रिंग, सटीक आइडेंटिफ़ायर खोजता है।
structural — AST क्वेरी; परिभाषाएं, सिग्नेचर, और भाषाई संरचनाएं खोजता है।
ग्राफ़ — डिपेंडेंसी ग्राफ; कॉलर, कैली, और ब्लास्ट रेडियस खोजता है।

हर एक अलग तरह के सवाल पर मज़बूत है। तरक़ीब यह तय करने में है कि आपके सामने वाली क्वेरी के लिए किस पर कितना भरोसा किया जाए।

इंटेंट क्लासिफ़िकेशन

किसी भी रिट्रीवल के चलने से पहले, एक हल्का क्लासिफ़ायर क्वेरी को छह इंटेंट में से एक में, एक कॉन्फ़िडेंस स्कोर के साथ छांटता है। यह जानबूझकर सस्ता है — क्रमबद्ध हेयुरिस्टिक्स, पहला मैच जीतता है — क्योंकि यह हॉट पथ पर चलता है और सिर्फ़ एक-दो मिलीसेकंड जोड़ता है:

def , class , func , import … से शुरू होता है → find_definition (कॉन्फ़िडेंस 0.95)
“who calls”, “usages of”, “references to” → find_references (0.90)
“impact”, “blast radius”, “what depends on” → impact_analysis (0.90)
कोई कोटेड "string" या traceback जैसा कोई एरर टोकन → exact_match (0.85–0.90)
एक CamelCase या snake_case आइडेंटिफ़ायर → find_definition (0.60–0.80)
“how”, “why”, “explain”, “architecture” → understand_code (0.75)
कुछ भी मैच नहीं होता → understand_code, कम कॉन्फ़िडेंस (0.40)

हर इंटेंट चार मोडैलिटी में एक वेट प्रोफ़ाइल रखता है। ये असली आंकड़े हैं:

मंशा	semantic	text	structural (AST)	ग्राफ़
find_definition	0.2	0.1	0.6	0.1
find_references	0.1	0.2	0.2	0.5
understand_code	0.5	0.2	0.2	0.1
find_similar	0.4	0.3	0.2	0.1
impact_analysis	0.1	0.1	0.1	0.7
exact_match	0.0	0.9	0.1	0.0

तो “parseConfig कहां परिभाषित है” ज़ोरदार तरीक़े से AST (0.6) पर झुकता है। “auth कैसे काम करता है” सिमेंटिक वेक्टर (0.5) पर झुकता है। “इस पर क्या निर्भर करता है” लगभग पूरी तरह ग्राफ़ (0.7) है। “ECONNREFUSED खोजें” लगभग पूरी तरह ट्राइग्राम (0.9) है, जिसमें एम्बेडिंग मॉडल पूरी तरह बंद रहता है — क्योंकि सिमेंटिक समानता किसी सटीक स्ट्रिंग के लिए बिल्कुल अनुपयुक्त टूल है।

तेज़ पथ, और फ़्यूज़्ड पथ

जब क्लासिफ़ायर आश्वस्त हो — स्कोर ≥ 0.85 — और क्वेरी सामान्य हो, तो Maguyva फ़्यूज़न को पूरी तरह छोड़ देता है और सीधे एकल प्रभावी मोडैलिटी की ओर रूट करता है। “X कहां परिभाषित है” को चार रिट्रीवर की ज़रूरत नहीं; इसे अभी AST इंडेक्स चाहिए। वह डायरेक्ट पथ fusion_strategy: "direct" के रूप में वापस रिपोर्ट किया जाता है।

जो कुछ भी अस्पष्ट है वह फ़्यूज़न से गुज़रता है। चारों (या डिफ़ॉल्ट प्रीसेट पर तीनों) मोडैलिटी समानांतर में चलती हैं, हर एक अपनी ख़ुद की रैंक्ड लिस्ट लौटाती है, और हम उन्हें मिलाते हैं।

वेटेड Reciprocal Rank Fusion

अलग-अलग तरह के रिट्रीवर को मिलाना जितना आसान लगता है, उससे कहीं ज़्यादा मुश्किल है: 0.82 की कोसाइन सिमिलैरिटी और 137 का ट्राइग्राम स्कोर और 0.004 की ग्राफ सेंट्रैलिटी एक ही पैमाने पर नहीं हैं, तो आप उन्हें बस जोड़ नहीं सकते। Reciprocal Rank Fusion कच्चे स्कोर को फेंककर और सिर्फ़ हर इंजन द्वारा दी गई रैंक को रखकर इस समस्या को टाल देता है। किसी एक मोडैलिटी से किसी नतीजे का योगदान यह है:

contribution = weight × 1 / (k + rank + 1)

जहां rank उस मोडैलिटी की लिस्ट में उसकी पोज़िशन है और k एक स्मूदिंग कॉन्स्टेंट है। ऐसे किसी भी नतीजे के लिए, जिसे एक से ज़्यादा इंजन ने खोजा हो, योगदान मोडैलिटी में जोड़े जाते हैं — रिट्रीवर के बीच सहमति स्वाभाविक रूप से ऊपर तैर आती है। हम डिफ़ॉल्ट प्रीसेट पर k = 40 और thorough पर 60 इस्तेमाल करते हैं (quick सिर्फ़-सिमेंटिक चलता है, तो वहां फ़्यूज़न कभी शुरू नहीं होता)। मूल RRF काम सामान्य-प्रयोजन रिट्रीवल के लिए k = 60 पर पहुंचा था; हम थोड़ा तीखा डिफ़ॉल्ट रखते हैं, जो मोडैलिटी के बीच टॉप-रैंक्ड सहमति को थोड़ा ज़्यादा वेट देता है — और हम इसे हाथ से ट्यून करने की सलाह नहीं देते।

इसके ऊपर, नतीजे एक ग्राफ-इम्पॉर्टेंस बूस्ट लेकर चलते हैं। एक हब — एक ऐसा फ़ंक्शन जिस पर पूरा कोडबेस निर्भर करता है — को उसी टेक्स्चुअल रेलेवेंस पर भी किसी कम परिचित लीफ़ से आगे निकलना चाहिए, तो हम हर योगदान को इससे गुणा करते हैं:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

सेंट्रैलिटी पाइपलाइन के प्री-कंप्यूटेड PageRank/डिग्री मेट्रिक्स से आती है, और बूस्ट को 1.5× पर क्लैम्प किया गया है ताकि कोई लोकप्रिय फ़ंक्शन किसी ज़्यादा प्रासंगिक लेकिन कम परिचित फ़ंक्शन को पूरी तरह दबा न सके। आख़िर में हम vendor, build, और archive पथों से आने वाले नतीजों को डिमोट करते हैं, और प्रति फ़ाइल सबसे अच्छे चंक तक डिड्यूप करते हैं।

अब भी क्या अधूरा है

आशय वर्गीकारक regex का एक समूह है, सीखा हुआ मॉडल नहीं। यह प्रश्नों के आम रूपों को ह्यूरिस्टिक से संभालता है, और अस्पष्ट प्रश्न understand_code तथा अर्थ-आधारित खोज की ओर झुके मिश्रण पर लौटता है। इस लेख के पहले संस्करण में शून्य-परिणाम दर को लगभग 15% से 5% से नीचे लाने को हासिल किया गया सुधार बताया गया था। दिसंबर 2025 के प्रस्ताव में वास्तव में एक अनुमानित आधार और एक लक्ष्य दर्ज थे; कोई सहायक प्रश्न-समूह या मापन रिकॉर्ड उपलब्ध नहीं है। हम सुधार हासिल होने का वह दावा वापस लेते हैं; मूल साक्ष्य और सुधार देखें। हमने वर्गीकारक को प्रशिक्षित मॉडल से नहीं बदला है, क्योंकि सस्ता संस्करण तेज़ है और अपनी निर्धारित रूटिंग भूमिका के लिए पर्याप्त है, और क्योंकि गलत लेकिन आत्मविश्वास से भरा वर्गीकारक अपनी सीमा स्वीकार करके वैकल्पिक रास्ता अपनाने से बदतर है। भार स्वयं हाथ से चुनी गई पूर्वधारणाएँ हैं, उन क्लिक डेटा से सीखे हुए नहीं जिन्हें हम एकत्र ही नहीं करते।

सवाल पूछें, टूल नहीं

किसी एजेंट को यह जानने की ज़रूरत नहीं होनी चाहिए कि grep, एम्बेडिंग, या कॉल ग्राफ में से किसका सहारा लें — उसे अपना सवाल सीधे शब्दों में पूछना चाहिए और सही जवाब पाना चाहिए। मल्टी-मोडल फ़्यूज़न ही है जो find_symbol, सिमेंटिक सर्च, और डिपेंडेंसी विश्लेषण को एक क्वेरी सरफ़ेस के पीछे बिठाता है: सिस्टम सवाल के आकार को पढ़ता है और चुपचाप उसके लिए सही रिट्रीवर जोड़ देता है। जो मॉडल एम्बेडिंग को स्कोर करता है वह मायने रखता है, लेकिन यह जानना भी मायने रखता है कि उन्हें कब इस्तेमाल न करें। हर क्वेरी के लिए सही टूल चुनना अपने आप में एक तरह की क्वालिटी है, और हम इसे कॉलर पर थोपने के बजाय ख़ुद संभालना पसंद करते हैं।

// you bring the question. it brings the tools.

एजेंट ऑब्ज़र्वेबिलिटी: Hooks, Alloy, और Grafana

Tue, 24 Mar 2026 00:00:00 GMT

एजेंट सिस्टम अजीबोग़रीब तरीकों से फ़ेल होते हैं।

कभी-कभी समस्या मॉडल में होती है। कभी-कभी समस्या टूल में होती है। कभी-कभी आपका MCP सर्वर बिल्कुल ठीक होता है, लेकिन एजेंट ने ग़लत स्पेशलिस्ट चुन लिया, या सेशन का आधा हिस्सा ऐसे शेल वर्क में बिता दिया जिसकी आपने उम्मीद नहीं की थी, या चुपचाप ऐसे लूप में पैसे ख़र्च कर दिए जो बाहर से देखने पर उत्पादक लग रहा था।

अगर आप यह अंतर नहीं देख पा रहे हैं, तो आप वास्तव में एक एजेंट सिस्टम को ऑपरेट नहीं कर रहे हैं। आप अंदाज़ा लगा रहे हैं।

तो हमने अपने ही वर्कफ़्लो के लिए एक ऑब्ज़र्वेबिलिटी स्टैक बनाया: Claude Code, Codex, Claude हुक घटनाएँ, Codex सूचना घटनाएँ, नेटिव OpenTelemetry, Grafana Alloy, और दूसरी ओर Grafana Cloud।

दिलचस्प हिस्सा यह नहीं है कि “हमने एक डैशबोर्ड बनाया।” दिलचस्प हिस्सा यह है कि हमें टेलीमेट्री को दो अलग-अलग स्ट्रीम में बांटना पड़ा, क्योंकि किसी एक फ़ीड से हमें पूरी तस्वीर नहीं मिल रही थी।

समस्या: एजेंट टेलीमेट्री बिखरी हुई है

आधुनिक कोडिंग एजेंट पहले से ही कुछ टेलीमेट्री उत्सर्जित करते हैं। इससे मदद मिलती है, लेकिन यह काफ़ी नहीं है।

नेटिव OTEL इन जैसे सवालों के जवाब देने में अच्छा है:

हमने कितने रिक्वेस्ट किए?
किसी सेशन की लागत कितनी रही?
स्पैन और ट्रेस कहां हैं?
क्या लेटेंसी में उछाल आया?

यह इन जैसे सवालों के जवाब देने में कहीं ज़्यादा कमज़ोर है:

एजेंट किस MCP सर्वर पर निर्भर रहा?
क्या यह विफलता Bash में थी, किसी बिल्ट-इन फ़ाइल टूल में, या किसी MCP कॉल में?
वास्तव में कौन-सा स्किल एक्टिवेट हुआ?
किस तरह का सबएजेंट डिस्पैच किया गया?
क्या सेशन उपयोगी काम कर रहा था, या बिना प्रगति के बार-बार कोशिश कर रहा था?

सवालों की वह दूसरी श्रेणी ट्रेस की तुलना में hooks के ज़्यादा करीब रहती है।

लेकिन इसका उल्टा भी सच है: कुछ सबसे महत्वपूर्ण परफ़ॉर्मेंस सवाल hooks की तुलना में ट्रेस के ज़्यादा करीब रहते हैं।

अगर आप जानना चाहते हैं कि लेटेंसी वास्तव में कहां जमा हुई, कौन-से स्पैन धीमे थे, या सेशन ने मॉडल कॉल बनाम टूल एक्ज़िक्यूशन में समय कहां जलाया, तो आपको सिमेंटिक इवेंट के साथ-साथ ट्रेस डेटा भी चाहिए।

जिस आर्किटेक्चर पर हम पहुंचे

हम दो टेलीमेट्री पथ एक साथ, समानांतर में चलाते हैं।

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

यह बंटवारा जानबूझकर किया गया है।

यह असममित भी है। Claude Code हमें एक कहीं ज़्यादा समृद्ध लाइफ़साइकल hook सरफ़ेस देता है। Codex हमें नेटिव OTEL के साथ-साथ एक notify सरफ़ेस देता है, इसलिए हम कम विवरण वाले टर्न-कम्प्लीशन इवेंट को उसी लॉग स्कीमा में नॉर्मलाइज़ करते हैं, बजाय यह दिखावा करने के कि दोनों रनटाइम एक जैसे कंट्रोल एक्सपोज़ करते हैं।

नेटिव OTEL हमें बेसलाइन स्ट्रीम देता है: रनटाइम से आने वाले लॉग और ट्रेस, साथ ही वे मेट्रिक्स जहां रनटाइम वास्तव में उन्हें उत्सर्जित करता है।

Hook और notify इवेंट हमें सिमेंटिक लेयर देते हैं: जैसे PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, और वह वर्गीकृत मेटाडेटा जिसकी हमें एजेंट व्यवहार डीबग करते समय वास्तव में परवाह है। यहां Claude Code ज़्यादा समृद्ध इवेंट स्ट्रीम देता है। Codex कम विवरण वाली, लेकिन फिर भी उपयोगी नॉर्मलाइज़्ड स्ट्रीम देता है।

Hooks आख़िर होते ही क्यों हैं

हमारी hook पाइपलाइन इवेंट को Loki तक पहुंचने से पहले समृद्ध करती है।

सिर्फ़ यह कहने के बजाय कि “एक टूल चला,” हम इवेंट को इन जैसे फ़ील्ड में वर्गीकृत करते हैं:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: किस MCP बैकएंड ने कॉल हैंडल किया
bash_cli: शेल कमांड फ़ैमिली
subagent_type: किस तरह का स्पेशलिस्ट डिस्पैच किया गया
agent_tool: क्या स्रोत Claude Code था या Codex

इसका मतलब है कि हम ऐसे सवाल पूछ सकते हैं जो परिचालन रूप से मायने रखते हैं:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

ये दिखावटी फ़ील्ड नहीं हैं। ये “एजेंट धीमा महसूस हुआ” और “एजेंट ने पिछले दस मिनट शेल-भारी git ऑपरेशन में उच्च टूल फ़ेल्योर रेट के साथ बिताए” के बीच का फ़र्क़ हैं।

एक इम्प्लीमेंटेशन डिटेल जो वास्तव में जितनी है उससे ज़्यादा अजीब दिखती है: साझा Loki स्ट्रीम अब भी service_name="claude-code-hooks" को लेबल के रूप में इस्तेमाल करती है, भले ही इवेंट Codex से आया हो। रनटाइम के बीच असली बंटवारा agent_tool पर होता है।

Alloy बीच में क्यों बैठता है

इस सेटअप में Grafana Alloy सिर्फ़ एक फ़ॉरवर्डर नहीं है। यह पॉलिसी सीमा है।

हम Claude Code और Codex से आने वाली नेटिव OTEL स्ट्रीम को localhost:4318 पर एक लोकल Alloy प्रॉक्सी की ओर पॉइंट करते हैं, फिर Alloy को Grafana Cloud तक फ़ॉरवर्ड करने से पहले पेलोड साफ़ करने देते हैं।

यह इसलिए मायने रखता है क्योंकि कच्ची एजेंट टेलीमेट्री उन हाई-कार्डिनैलिटी फ़ील्ड से भरी होती है जो विश्लेषण के लिए उपयोगी हैं लेकिन इंडेक्स्ड लेबल के रूप में भयानक हैं:

session_id
prompt_id
टोकन काउंट
अवधियां
टूल पैरामीटर ब्लॉब

अगर आप सब कुछ इंडेक्स करते हैं, तो आपको एक लेबल विस्फोट और एक बुरा दिन मिलता है।

तो Alloy हमारे लिए तीन काम करता है:

लो-कार्डिनैलिटी लेबल का एक बहुत छोटा सेट इंडेक्स्ड रखता है।
शोरगुल वाले लेकिन उपयोगी फ़ील्ड को संरचित मेटाडेटा में ले जाता है।
शुद्ध नॉइज़ को पूरी तरह हटा देता है।

महत्वपूर्ण विचार सरल है: ज़्यादा ऑब्ज़र्व करो, कम इंडेक्स करो।

Hook स्ट्रीम, Alloy को क्यों बायपास करती है

Hook स्ट्रीम पहले से ही Loki के लिए आकार में ढली होती है।

जब तक send_event.py कोई इवेंट पुश करता है, तब तक हम पहले ही तय कर चुके होते हैं कि कौन-से फ़ील्ड लेबल ट्रीटमेंट के लायक हैं और कौन-से संरचित JSON बॉडी में जाने चाहिए। वह स्ट्रीम Alloy से दोबारा गुज़रने के बजाय सीधे Grafana Cloud के OTLP गेटवे तक जाती है।

तो सिस्टम में काम का स्पष्ट बंटवारा है:

Alloy कच्ची नेटिव OTEL स्ट्रीम को क़ाबू में करता है।
Hook एनरिचमेंट सिमेंटिक इवेंट को क्वेरी करने लायक बनाता है।

इससे सब कुछ एक ही पथ से ज़बरदस्ती गुज़ारने की कोशिश करने की तुलना में आर्किटेक्चर सरल बना रहता है।

डैशबोर्ड वास्तव में क्या दिखाता है

नीचे दिया गया स्क्रीनशॉट हमारे एजेंट वर्कफ़्लो के पीछे मौजूद ऑब्ज़र्वेबिलिटी डैशबोर्ड में से एक का है। यह कोई बेंचमार्क नहीं है, और आंकड़े सिर्फ़ एक निश्चित पल की झलक हैं। मुद्दा डेटा का आकार है: एक्टिविटी फ़ीड, टूल कॉल, विफलताएं, प्रॉम्प्ट, और एजेंट, बिल्ट-इन टूल, MCP उपयोग, शेल कमांड, और स्किल के हिसाब से ब्रेकडाउन।

उपयोगी बात यह है कि यह डैशबोर्ड बाक़ी एजेंट टेलीमेट्री के साथ उसी Grafana स्टैक पर रहता है। हम स्रोत एजेंट और टूल फ़ैमिली के हिसाब से फ़िल्टर कर सकते हैं और हर सिस्टम के लिए अलग ऑब्ज़र्वेबिलिटी कहानी गढ़े बिना रनटाइम के आर-पार देख सकते हैं।

हमारे एजेंट वर्कफ़्लो के पीछे मौजूद लाइव डैशबोर्ड में से एक। यह स्क्रीनशॉट एक साझा Grafana स्टैक की सिर्फ़ एक झलक है, जो हमारे अन्य एजेंट रनटाइम और सिस्टम से भी टेलीमेट्री प्राप्त करता है। पूरे रिज़ॉल्यूशन वाला वर्ज़न देखने के लिए इमेज पर क्लिक करें।

ट्रेस पहली नज़र में दिखने से कहीं ज़्यादा क्यों मायने रखते हैं

लॉग हमें बताते हैं कि किस श्रेणी का काम हुआ। ट्रेस हमें बताते हैं कि काम समय के साथ कैसे सामने आया।

यह फ़र्क़ एजेंट सिस्टम में मायने रखता है क्योंकि “धीमा” उपयोगी होने के लिए बहुत ही अस्पष्ट शब्द है।

एक ट्रेस हमें बता सकता है कि तकलीफ़ कहां से आई:

मॉडल लेटेंसी
टूल एक्ज़िक्यूशन समय
बार-बार रीट्राई
एक खासतौर पर महंगा MCP इंटरैक्शन
छोटे ऑपरेशन की एक लंबी शृंखला जो अलग-अलग देखने पर हानिरहित लगती थी

व्यवहार में हम hook स्ट्रीम और Tempo ट्रेस को साथ इस्तेमाल करते हैं।

Hook लॉग जवाब देते हैं: किस तरह की चीज़ हुई?
ट्रेस जवाब देते हैं: समय कहां गया?

यही मेल है जो ऑब्ज़र्वेबिलिटी को एक डैशबोर्ड से एक स्पष्टीकरण में बदल देता है।

Codex कहां फ़िट बैठता है

Codex उसी स्टैक का हिस्सा है, लेकिन यह Claude Code जैसा बिल्कुल नहीं है।

Codex के लिए हम दो हिस्से जोड़ते हैं:

Codex से Alloy में नेटिव OTEL
codex_notify.py में एक notify वेबहुक, जो टर्न कम्प्लीशन को उसी Loki स्कीमा में मैप करता है जिसका उपयोग हम hook इवेंट के लिए करते हैं

इससे हमें उसी लॉग स्ट्रीम के भीतर agent_tool="codex-cli" जैसा एक एकीकृत फ़िल्टर मिलता है।

ईमानदार चेतावनी: Codex का notify पेलोड फ़िलहाल Claude Code के hook पेलोड से कम विवरण वाला है, क्योंकि यह उसी तरह की इंटीग्रेशन सरफ़ेस नहीं है। हमारे आज के सेटअप में, Codex टर्न कम्प्लीशन को साझा स्कीमा में नॉर्मलाइज़ किया जा सकता है, लेकिन समृद्ध टूल-दर-टूल एक्सट्रैक्शन अब भी notify ब्रिज की तुलना में नेटिव OTEL स्ट्रीम में बेहतर है।

यह पोस्ट से बचने की कोई वजह नहीं है। यही तो इस पोस्ट का मक़सद है। असली ऑब्ज़र्वेबिलिटी सिस्टम अपूर्ण सिग्नल से मिलकर बनते हैं।

MCP पर Grafana खेल बदल देता है

बड़ा बदलाव यह है कि Grafana सिर्फ़ वह जगह नहीं है जहां इंसान ब्राउज़र में जाते हैं।

इस रिपॉज़िटरी में हम Grafana को MCP के ज़रिए भी एक्सपोज़ करते हैं। इसका मतलब है कि कोई एजेंट, किसी इंसान के पहले मैनुअली डैशबोर्ड देखने का इंतज़ार करने के बजाय, सीधे Loki, Prometheus, और Tempo को क्वेरी कर सकता है।

इससे ऑब्ज़र्वेबिलिटी वर्कफ़्लो का एक सक्रिय इनपुट बन जाती है।

कोई एजेंट पूछ सकता है:

पिछले एक घंटे में कौन-सी टूल फ़ैमिली सबसे ज़्यादा फ़ेल हुईं?
किसी सेशन पर किस MCP सर्वर का दबदबा रहा?
क्या हाल के बदलावों ने टूल फ़ेल्योर घटाए, या बस काम को उन्हीं ग़लतियों के साथ ज़्यादा शेल-भारी पथों में शिफ़्ट कर दिया?
कौन-से ट्रेस सबसे ज़्यादा लेटेंसी या बार-बार रीट्राई दिखाते हैं?

एक बार आपके पास यह हो, तो आप एक सेल्फ़-इम्प्रूवमेंट लूप के बहुत करीब होते हैं।

डैशबोर्ड से फ़ीडबैक लूप तक

यह वह हिस्सा है जो हमें सबसे दिलचस्प लगता है।

एक बार जब ऑब्ज़र्वेबिलिटी स्टैक एजेंट लेयर से क्वेरी करने लायक हो जाए, तो टेलीमेट्री एक निष्क्रिय रिपोर्टिंग सरफ़ेस बनना बंद कर देती है और एक कंट्रोल सिग्नल बन जाती है।

लूप कुछ ऐसा दिखता है:

एजेंट गतिविधि ट्रेस, मेट्रिक्स, और समृद्ध hook लॉग उत्सर्जित करती है।
Grafana इस साक्ष्य को Loki, Tempo, और Prometheus में स्टोर करता है, जहां मेट्रिक्स मौजूद हैं।
एजेंट Grafana MCP के ज़रिए उस साक्ष्य को क्वेरी करते हैं।
सिस्टम ख़राब टूल मिश्रण, नाज़ुक स्किल, कमज़ोर रूटिंग, या शेल-भारी वर्कफ़्लो की पहचान करता है जो लगातार टाली जा सकने वाली ग़लतियां पैदा करते रहते हैं।
एजेंट या ऑपरेटर प्रॉम्प्ट, एजेंट कॉन्फ़िग, स्किल विवरण, रूटिंग नियम, या टूल एक्सेस में बदलाव करते हैं।
अगला सेशन एक नया टेलीमेट्री आकार पैदा करता है, और चक्र फिर से चलता है।

यही तरीक़ा है “दिलचस्प डैशबोर्ड” से “मापने योग्य सुधार प्रणाली” तक जाने का।

लक्ष्य किसी एक टूल श्रेणी को अधिकतम करना नहीं है। लक्ष्य वास्तव में हो रहे काम के लिए CLI, बिल्ट-इन टूल, MCP कॉल, और स्किल का सही मिश्रण पाना है।

यह हमें क्या जवाब देने देता है

एक बार जब दोनों रनटाइम एक ही Grafana स्टैक में उतर जाते हैं, तो हम परिचालन सवालों के जवाब कहीं तेज़ी से दे सकते हैं:

क्या विफलताएं किसी एक टूल फ़ैमिली में केंद्रित हैं?
क्या शेल-भारी वर्कफ़्लो ऐसी टाली जा सकने वाली ग़लतियां पैदा कर रहे हैं जहां एक उच्च-स्तरीय टूल मौजूद होना चाहिए?
कौन-से MCP सर्वर कार्यभार उठा रहे हैं?
क्या हम ऐसी एजेंट गतिविधि के लिए भुगतान कर रहे हैं जो सार्थक प्रगति पैदा नहीं कर रही?
क्या कोई सेशन मॉडल, टूल, या ऑर्केस्ट्रेशन लेयर की वजह से अस्वस्थ है?

यह मल्टी-एजेंट वर्कफ़्लो में खासतौर पर उपयोगी है, जहां “एजेंट व्यस्त था” कहना लगभग कुछ नहीं बताता।

अगर एक स्पेशलिस्ट लगातार डिस्पैच होता रहे और उच्च फ़ेल्योर रेट पैदा करता रहे, तो यह रूटिंग या प्रॉम्प्ट-शेपिंग की समस्या है।

अगर एक MCP सर्वर सभी कॉल पर हावी है, तो यह अच्छा आर्किटेक्चर हो सकता है, या इस बात का संकेत कि बाक़ी सब बेकार बोझ है।

अगर टूल फ़ेल्योर बढ़ते हैं जबकि लागत ऊंची बनी रहती है, तो आपके पास एक परिचालन समस्या है, गुणवत्ता की समस्या नहीं।

अगर शेल वर्क लगातार अनुमानित, टाले जा सकने वाले तरीक़ों से फ़ेल होता रहे जहां एक उच्च-स्तरीय टूल मौजूद होना चाहिए, तो यह एक प्रोडक्ट सिग्नल है।

अगर कोई एक स्किल लगातार एक्टिवेट होती है लेकिन नतीजों को बेहतर नहीं बनाती, तो यह एक प्रॉम्प्ट या रूटिंग सिग्नल है।

असली सबक़

यहां गहरा सबक़ यह है कि एजेंट ऑब्ज़र्वेबिलिटी को रनटाइम टेलीमेट्री और वर्कफ़्लो टेलीमेट्री, दोनों की ज़रूरत है।

रनटाइम टेलीमेट्री आपको बताती है कि सिस्टम ने क्या किया।

वर्कफ़्लो टेलीमेट्री आपको बताती है कि एजेंट को क्या लगा कि वह क्या कर रहा था।

हमें दोनों चाहिए।

अगर आप सिर्फ़ ट्रेस और काउंटर रखते हैं, तो आप सिमेंटिक लेयर चूक जाते हैं। अगर आप सिर्फ़ hook इवेंट रखते हैं, तो आप लेटेंसी, स्पैन, और व्यापक रनटाइम तस्वीर चूक जाते हैं।

और अगर आप दोनों रखते हैं लेकिन उन्हें कभी वापस एजेंट लेयर में फ़ीड नहीं करते, तो आपके पास मॉनिटरिंग है, अनुकूलन नहीं।

यही मेल है जो सिस्टम को ऑपरेट करने लायक़ इतना समझाने योग्य और सुधारने लायक़ इतना ट्यून करने योग्य बनाता है।

अब भी क्या अधूरा है

अब भी कुछ कमियां बाकी हैं।

हर hook इवेंट में वे अवधि और token डेटा शामिल नहीं होते जो हम चाहते।
कुछ सबसे अच्छे टाइमिंग व्यू अब भी hook लॉग से नहीं, बल्कि Tempo ट्रेस से आते हैं।
Codex आज समृद्ध इवेंट स्ट्रीम में Claude Code जितना सिमेंटिक रूप से समृद्ध नहीं है।
डैशबोर्ड स्क्रीनशॉट एक लाइव ऑपरेशन सरफ़ेस है, कोई पॉलिश किया हुआ मार्केटिंग आर्टिफ़ैक्ट नहीं।

वह आख़िरी बात जानबूझकर है। हम यह दिखावा करने के बजाय, कि एजेंट सिस्टम जादुई रूप से खुद-ब-खुद समझ में आ जाते हैं, असली इंस्ट्रूमेंट पैनल दिखाना पसंद करेंगे।

Maguyva के लिए यह क्यों मायने रखता है

Maguyva एजेंट को बेहतर कोड इंटेलिजेंस देने के बारे में है। लेकिन जैसे ही एजेंट वास्तव में उपयोगी काम करने लगते हैं, एक नई ज़रूरत तुरंत सामने आ जाती है: आपको यह देखने की ज़रूरत है कि वे कैसा व्यवहार कर रहे हैं।

सर्च क्वालिटी, रूटिंग क्वालिटी, टूल सिलेक्शन, और कॉन्टेक्स्ट एफ़िशिएंसी — ये सब ऑब्ज़र्वेबल समस्याएं बन जाती हैं।

यही वजह है कि हमें लगता है कि इस बारे में लिखना सार्थक है। भविष्य का एजेंट स्टैक सिर्फ़ प्रॉम्प्ट और टूल नहीं है। यह प्रॉम्प्ट, टूल, और वह इंस्ट्रुमेंटेशन लेयर है जो आपको बताती है कि पूरी चीज़ काम कर रही है या नहीं।

अगर आप गंभीर एजेंट वर्कफ़्लो बना रहे हैं, तो ऑब्ज़र्वेबिलिटी कोई वैकल्पिक इन्फ़्रास्ट्रक्चर नहीं है। यह प्रोडक्ट का हिस्सा है।

लूप की माइनिंग: बदलाव संस्थागत स्मृति कैसे बनते हैं

Tue, 03 Feb 2026 00:00:00 GMT

इस पोस्ट में दिए गए आंकड़े प्रकाशन के समय (फ़रवरी 2026) की सिस्टम स्थिति दर्शाते हैं। मौजूदा आंकड़ों के लिए हमारा टीम पेज देखें।

हर इंजीनियरिंग टीम एक ही चुनौती का सामना करती है: बदलाव लगातार होते रहते हैं, लेकिन उन बदलावों के पीछे का क्यों ग़ायब हो जाता है। छह महीने बाद, कोई पूछता है “हमने पाइपलाइन स्टेज के लिए DuckDB क्यों अपनाया था?” और जवाब सिर्फ़ उस इंसान के दिमाग़ में रहता है जिसने वह फ़ैसला लिया था — अगर वह अब भी मौजूद है तो।

हमने एक माइनिंग वर्कफ़्लो बनाया जो इस लूप को बंद करता है। बदलाव git कमिट के ज़रिए बहते हैं, हमारी माइनिंग पाइपलाइन से प्रोसेस होते हैं, संरचित चेंजलॉग एंट्री और आर्किटेक्चरल डिसीज़न रिकॉर्ड बन जाते हैं, और फिर CLI क्वेरी के ज़रिए वापस हमारे AI एजेंट में फ़ीड हो जाते हैं। नतीजा: संस्थागत स्मृति जिसे इंसान और AI, दोनों एक्सेस कर सकते हैं।

समस्या: फ़ैसलों के कारण भुला दिए जाते हैं

एक सामान्य परिदृश्य पर विचार करें। एक डेवलपर कमिट करता है:

feat(canonical): add DuckDB runtime for pipeline stages

यह कमिट एक महत्वपूर्ण आर्किटेक्चरल चुनाव दर्शाता है। टीम ने विकल्पों का मूल्यांकन किया, ट्रेड-ऑफ़ पर विचार किया, और विशिष्ट कारणों से DuckDB पर पहुंची। लेकिन वह सारा कॉन्टेक्स्ट यहां रहता है:

एक Slack थ्रेड (शायद डिलीट हो चुका)
किसी की याददाश्त (निश्चित रूप से धुंधली पड़ रही)
कोड में एक कमेंट (शायद, अगर आप ख़ुशक़िस्मत हैं)

तीन महीने बाद, एक नया टीम मेंबर पूछता है: “क्या मुझे इस नए स्टेज के लिए DuckDB या SQLite इस्तेमाल करना चाहिए?” संस्थागत स्मृति के बिना, वे या तो पहिया फिर से बना लेते हैं, या असंगत चुनाव कर बैठते हैं।

लूप: कमिट से कॉन्टेक्स्ट तक

हमारा माइनिंग वर्कफ़्लो git इतिहास को क्वेरी करने योग्य ज्ञान में बदल देता है:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

मुख्य इनसाइट: चेंजलॉग और आर्किटेक्चरल डिसीज़न, दोनों उसी git इतिहास से बहते हैं, एक एकीकृत पाइपलाइन से प्रोसेस होकर। इससे यह सुनिश्चित होता है कि कुछ भी छूट न जाए।

माइनिंग कैसे काम करती है

चरण 1: इंडेक्स सिंक करें

uv run orkestra mine sync

यह कमांड git इतिहास स्कैन करता है और सभी कमिट का एक इंडेक्स बनाता है। यह हर कमिट से संरचित सिग्नल एक्सट्रैक्ट करता है:

कन्वेंशनल कमिट टाइप (feat, fix, chore, docs)
स्कोप (कौन-सा पैकेज या क्षेत्र)
ब्रेकिंग चेंज मार्कर
छुई गई फ़ाइलें और जटिलता मेट्रिक्स

चरण 2: कवरेज स्टेटस जांचें

uv run orkestra mine status

हमारी मौजूदा स्थिति कुछ ऐसी दिखती है:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15,637 कमिट प्रोसेस किए गए। 476 आर्किटेक्चरल डिसीज़न बने। 6,799 चेंजलॉग एंट्री बनीं। हर कमिट वर्गीकृत।

चरण 3: समीक्षा के लिए उम्मीदवार पाएं

uv run orkestra mine candidates --limit 50 --full

यह उन कमिट को सामने लाता है जो अब तक प्रोसेस नहीं हुए, वर्गीकरण के लिए पूरे कॉन्टेक्स्ट के साथ:

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

सिग्नल वर्गीकरण में मार्गदर्शन करते हैं: is_releasable_type: true बताता है कि इसे चेंजलॉग में दिखना चाहिए। बड़ी इंसर्शन काउंट और इन्फ़्रास्ट्रक्चर फ़ाइलें बताती हैं कि यह एक आर्किटेक्चरल डिसीज़न भी हो सकता है।

चरण 4: कमिट वर्गीकृत करें

यहां दो रास्ते अलग हो जाते हैं: चेंजलॉग एंट्री और आर्किटेक्चरल डिसीज़न।

चेंजलॉग एंट्री के लिए:

uv run orkestra mine classify abc123 --changelog added

यह दर्ज करता है कि कमिट abc123 को चेंजलॉग में “Added” श्रेणी के अंतर्गत दिखना चाहिए।

आर्किटेक्चरल डिसीज़न के लिए:

पहले, एक असली डिसीज़न ID पाएं:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

फिर डिसीज़न ID के साथ वर्गीकृत करें:

uv run orkestra mine classify abc123 --decision DEC-PL-143

यह कमिट को एक डिसीज़न रिकॉर्ड से जोड़ता है जो बनाया या अपडेट किया जाएगा।

बैच प्रोसेसिंग के लिए (जो हम वास्तव में करते हैं):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

JSONL फ़ॉर्मैट एक ही पास में दोनों डोमेन को सपोर्ट करता है:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

चरण 5: आउटपुट रेंडर करें

uv run orkestra registry changelog render --package <pkg>

यह लेजर से प्रति-पैकेज CHANGELOG.md फ़ाइलें जनरेट करता है। चेंजलॉग व्युत्पन्न आर्टिफ़ैक्ट हैं — उन्हें डिलीट करें और वे सोर्स लेजर से बिल्कुल सही ढंग से दोबारा बन जाते हैं।

डिसीज़न रिकॉर्ड की संरचना

एक्सट्रैक्ट किए गए डिसीज़न समृद्ध मेटाडेटा वाली YAML फ़ाइलें बन जाते हैं:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

हर डिसीज़न वापस अपने सोर्स कमिट से जुड़ता है। हर डिसीज़न बताता है कि वह किन फ़ाइलों को प्रभावित करता है। डिसीज़न के बीच रिलेशनशिप स्पष्ट होती हैं।

CLI इंटीग्रेशन: संस्थागत स्मृति को क्वेरी करना

यहीं पर लूप बंद होता है। एजेंट CLI के ज़रिए डिसीज़न क्वेरी कर सकते हैं:

# Search by topic
uv run orkestra registry decisions search --query "retry"

रीट्राई लॉजिक, एरर हैंडलिंग, रिकवरी पैटर्न के बारे में डिसीज़न लौटाता है।

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

कॉन्टेक्स्ट, तर्क, और प्रभाव के साथ पूरा डिसीज़न रिकॉर्ड लौटाता है।

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

दिखाता है कि हाल में कौन-से आर्किटेक्चरल चुनाव किए गए।

एजेंट इसका उपयोग कैसे करते हैं

हमारे ऑर्केस्ट्रेटर के बेसलाइन निर्देशों में शामिल है:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

जब किसी एजेंट से DuckDB से जुड़ी कोई चीज़ इम्प्लीमेंट करने के लिए कहा जाता है, तो वह पहले यह जांच सकता है:

uv run orkestra registry decisions search --query "DuckDB"

और DEC-PL-142 खोज सकता है, यह सीखते हुए:

हमने DuckDB क्यों चुना (context)
इसका सही उपयोग कैसे करें (agent_guidance)
किन फ़ाइलों को देखना है (files)
कौन-से संबंधित डिसीज़न मौजूद हैं (related)

एजेंट पहिया फिर से नहीं बनाता। यह स्थापित पैटर्न पर आगे बढ़ता है।

तीन सवालों का टेस्ट

हर कमिट को डिसीज़न रिकॉर्ड की ज़रूरत नहीं होती। हम फ़िल्टर करने के लिए तीन सवालों के टेस्ट का उपयोग करते हैं:

क्या यह फ़ैसला लेना मुश्किल था? क्या इसके लिए महत्वपूर्ण विश्लेषण, ट्रेड-ऑफ़ मूल्यांकन, या बहस ज़रूरी थी?
क्या इसे बदलना महंगा है? क्या इस फ़ैसले को पलटने के लिए बड़े पैमाने पर दोबारा काम करना पड़ेगा?
क्या इसका सिस्टम-व्यापी प्रभाव है? क्या यह कई पैकेज को प्रभावित करता है या ऐसे पैटर्न स्थापित करता है जिनका दूसरे अनुसरण करेंगे?

अगर कोई कमिट इनमें से कम-से-कम एक सवाल का जवाब “हां” में देता है, तो यह डिसीज़न एक्सट्रैक्शन का उम्मीदवार है। हमारी सामान्य दर: प्रति 100 कमिट पर 1-4 डिसीज़न (लगभग 1-4%)।

चेंजलॉग एंट्री के लिए, मानदंड कम है: उपयोगकर्ताओं को दिखने वाला कोई भी बदलाव (फ़ीचर, फ़िक्स, सुधार) दर्ज किया जाता है। आंतरिक रखरखाव कार्य, डॉक्यूमेंटेशन अपडेट, और रीफ़ैक्टर आमतौर पर छोड़ दिए जाते हैं। हमारी सामान्य दर: प्रति 100 कमिट पर 30-50 चेंजलॉग एंट्री।

डेटा स्टोरेज: एपेंड-ओनली लेजर

माइनिंग सिस्टम टकराव-मुक्त मल्टी-एजेंट ऑपरेशन के लिए एपेंड-ओनली JSONL लेजर का उपयोग करता है:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

merge=union वाले .gitattributes के साथ JSONL फ़ॉर्मैट का मतलब है कि कई एजेंट मर्ज कॉन्फ़्लिक्ट के बिना एक साथ कमिट वर्गीकृत कर सकते हैं। हर लाइन स्वतंत्र है।

वैलिडेशन गेट

किसी भी माइनिंग सेशन से पहले, हम वैलिडेशन चलाते हैं:

uv run orkestra mine validate --quick

यह जांचता है:

SHA फ़ॉर्मैट की वैधता
डिसीज़न ID फ़ॉर्मैट अनुपालन
एक ही SHA के लिए कोई डुप्लिकेट एंट्री नहीं
रेफ़रेंस किए गए डिसीज़न वास्तव में मौजूद हैं

वर्गीकरण के बाद, हम बदलाव कमिट करने से पहले दोबारा वैलिडेट करते हैं।

यह क्यों मायने रखता है

हमने जो फ़ीडबैक लूप बनाया है, वह कई समस्याएं सुलझाता है:

नए टीम मेंबर के लिए: “हमने X क्यों किया?” पूछने के बजाय, वे डिसीज़न रजिस्ट्री सर्च कर सकते हैं। कॉन्टेक्स्ट सुरक्षित रहता है।

AI एजेंट के लिए: वे किसी शून्य में काम नहीं करते। वे सिफ़ारिशें करने से पहले संस्थागत ज्ञान क्वेरी कर सकते हैं। जब उनसे कोई नया पाइपलाइन स्टेज जोड़ने के लिए कहा जाता है, तो वे DuckDB पैटर्न खोज सकते हैं और उसका पालन कर सकते हैं।

आर्किटेक्चरल संगति के लिए: डिसीज़न स्पष्ट और सर्च करने योग्य हैं। जब कोई ऐसा अप्रोच प्रस्तावित करता है जो किसी मौजूदा डिसीज़न के विरुद्ध जाता है, तो सिस्टम उस टकराव को सामने ला सकता है।

चेंजलॉग जनरेशन के लिए: रिलीज़ नोट्स आख़िरी पल की भागदौड़ नहीं हैं। वे डेवलपमेंट के दौरान लगातार वर्गीकरण का एक उपोत्पाद हैं।

ऑनबोर्डिंग के लिए: नए एजेंट कोडबेस का पूरा कॉन्टेक्स्ट विरासत में पाते हैं। वे सिर्फ़ कोड नहीं देखते — वे उन डिसीज़न को देखते हैं जिन्होंने उसे आकार दिया।

मौजूदा स्थिति

आज तक:

पाइपलाइन के ज़रिए 15,637 कमिट प्रोसेस किए गए
476 आर्किटेक्चरल डिसीज़न एक्सट्रैक्ट और दस्तावेज़ीकृत किए गए
6,799 चेंजलॉग एंट्री दर्ज की गईं
दोनों डोमेन में 100% कवरेज

हमारे शुरू करने के बाद से हर कमिट वर्गीकृत किया जा चुका है। संस्थागत स्मृति पूर्ण और क्वेरी करने योग्य है।

शुरुआत कैसे करें

अगर आप कुछ ऐसा ही इम्प्लीमेंट करना चाहते हैं:

कन्वेंशनल कमिट से शुरू करें। माइनिंग पाइपलाइन तब सबसे अच्छा काम करती है जब कमिट में संरचित प्रीफ़िक्स हों (feat:, fix:, chore:)।
अपने डोमेन परिभाषित करें। हम pipeline, agent-design, observability, data-modeling जैसे डोमेन का उपयोग करते हैं। ये डिसीज़न को क्षेत्र के हिसाब से व्यवस्थित करते हैं।
वर्गीकरण की आदत बनाएं। माइनिंग तब काम करती है जब टीमें नियमित रूप से कमिट वर्गीकृत करती हैं। LLM सहायता के साथ बैच प्रोसेसिंग स्केल करने में मदद करती है।
डिसीज़न को क्वेरी करने योग्य बनाएं। जब एजेंट CLI के ज़रिए डिसीज़न सर्च कर सकते हैं, तो मूल्य कई गुना बढ़ जाता है। अपने आउटपुट को मशीन-उपभोग के लिए संरचित करें।
लूप बंद करें। डिसीज़न को भविष्य के काम को प्रभावित करना चाहिए। एजेंट निर्देशों और कोड समीक्षा चेकलिस्ट में डिसीज़न रेफ़रेंस शामिल करें।

लक्ष्य मुकम्मल डॉक्यूमेंटेशन नहीं है। यह बदलावों के पीछे के क्यों को इंसानों और AI, दोनों के लिए सुलभ बनाना है, आज भी और आज से छह महीने बाद भी। जब बदलाव संस्थागत स्मृति बन जाते हैं, तो टीमें उन्हें दोबारा गढ़ने के बजाय स्थापित पैटर्न पर आगे बढ़ती हैं।

माइनिंग वर्कफ़्लो हमारे ऑर्केस्ट्रेशन इंजन का हिस्सा है, ख़ासतौर पर हमारे ऑर्केस्ट्रेशन पैकेज में मौजूद कॉन्टेक्स्ट इंजन मॉड्यूल का।

स्किल माइनिंग: 3,500 उम्मीदवारों से 466 क्षमताओं तक

Tue, 27 Jan 2026 00:00:00 GMT

इस पोस्ट में दिए गए आंकड़े प्रकाशन के समय (जनवरी 2026) की सिस्टम स्थिति दर्शाते हैं। मौजूदा आंकड़ों के लिए हमारा टीम पेज देखें।

3,500 स्किल की समस्या

जब हमने एक एजेंट ऑर्केस्ट्रेशन सिस्टम बनाना शुरू किया, तो हमें एक दिलचस्प चुनौती का सामना करना पड़ा: AI इकोसिस्टम में हज़ारों संभावित स्किल बिखरी हुई हैं। GitHub रिपॉज़िटरी, वेंडर डॉक्यूमेंटेशन, कम्युनिटी प्रोजेक्ट, आंतरिक पैटर्न — स्किल हर जगह मौजूद हैं। लेकिन कौन-सी मायने रखती हैं? कौन-सी काम करती हैं? और आप एक सुसंगत स्किल लाइब्रेरी कैसे बनाए रखते हैं जिसे एजेंट वास्तव में इस्तेमाल कर सकें?

हमारा जवाब: एक व्यवस्थित माइनिंग और इंजेशन लूप।

आज के आंकड़े

Anthropic द्वारा 16 अक्टूबर, 2025 को Agent Skills लॉन्च करने के तीन महीने से कुछ ही ज़्यादा समय बाद, जब यह पोस्ट 27 जनवरी, 2026 को प्रकाशित हुई, तब हमारी स्थिति यह थी:

मेट्रिक	संख्या
पहचाने गए उम्मीदवार	3,500+
अपनाई गई स्किल	466
वेंडर स्किल	373
आंतरिक स्किल	93
सक्रिय वेंडर	25+
प्रति स्किल औसत टोकन	2,834
संदर्भित टूल	89
यूनीक टैग	635

हमने 3,500 से ज़्यादा स्किल उम्मीदवारों की समीक्षा की है। हमने 466 अपनाई हैं। यह 13% अपनाने की दर है — और यह चयनात्मकता जानबूझकर है।

नॉलेज टियर सिस्टम

सभी स्किल एक जैसी नहीं बनाई जातीं। हम उन्हें पांच नॉलेज लेयर (K0-K4) में व्यवस्थित करते हैं, हर एक लागू होने के अलग दायरे का प्रतिनिधित्व करती है:

K0: Foundations (सार्वभौमिक)

ऐसी स्किल जो हर एजेंट के पास होनी चाहिए। ये “अच्छे विचारक” की क्षमताओं का प्रतिनिधित्व करती हैं जो कहीं भी काम करती हैं।

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

K0 स्किल किसी भी प्रोजेक्ट, किसी भी डोमेन, किसी भी स्टैक में पोर्टेबल हैं। ये सार्वभौमिक संज्ञानात्मक पैटर्न को एनकोड करती हैं।

K1: Identities (अनुशासन)

“अच्छे इंजीनियर” या “अच्छे रिसर्चर” वाली स्किल जो किसी अनुशासन के भीतर प्रोजेक्ट में लागू होती हैं।

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: Domains (विषय विशेषज्ञता)

“अच्छा डेटाबेस विशेषज्ञ” या “अच्छा सिक्योरिटी इंजीनियर” वाली स्किल जो किसी क्षेत्र के भीतर पोर्टेबल हैं।

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Stacks (टेक्नोलॉजी)

विशिष्ट टेक्नोलॉजी स्टैक के लिए “अच्छा Supabase उपयोगकर्ता” या “अच्छा Cloudflare डेवलपर” वाली स्किल।

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: Project (संगठन)

हमारे संगठन और वर्कफ़्लो के लिए विशिष्ट स्किल।

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

माइनिंग लूप

चरण 1: डिस्कवरी

स्किल हर जगह से आती हैं:

वेंडर रिपॉज़िटरी: AWS, Anthropic, Cloudflare, Supabase, और कम्युनिटी कंट्रीब्यूटर स्किल कलेक्शन प्रकाशित करते हैं। हम 25+ वेंडर रूट ट्रैक करते हैं।

कम्युनिटी प्रोजेक्ट: GitHub Claude Code टेम्पलेट, एजेंट पैटर्न, और वर्कफ़्लो परिभाषाओं से भरा है।

आंतरिक पैटर्न: जैसे-जैसे हमारी टीम समस्याएं सुलझाती है, पैटर्न उभरते हैं। इन्हें स्किल में औपचारिक रूप दिया जाता है।

डॉक्यूमेंटेशन माइनिंग: तकनीकी डॉक्यूमेंटेशन में अक्सर अंतर्निहित स्किल होती हैं — प्रक्रियाएं, चेकलिस्ट, डिसीज़न ट्री।

डिस्कवरी निरंतर चलती रहती है। हम औपचारिक मूल्यांकन से पहले उम्मीदवारों को ट्रैक करने के लिए एक स्किल बैकलॉग का उपयोग करते हैं।

चरण 2: मूल्यांकन

हर उम्मीदवार एक ही रूब्रिक से गुज़रता है:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

सभी पांच प्रोडक्ट मानदंडों को पास करना ज़रूरी है। यही वजह है कि 87% उम्मीदवार रिजेक्ट कर दिए जाते हैं।

फिर हर उम्मीदवार एक अलग ट्रस्ट रिव्यू से गुज़रता है। हम किसी आधिकारिक वेंडर रिपॉज़िटरी, किसी जाने-माने कम्युनिटी मेंटेनर, और किसी रैंडम GitHub रिपॉज़िटरी को सच्चाई के समकक्ष स्रोत नहीं मानते।

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

भरोसेमंद वेंडर को स्रोत की कम विस्तृत समीक्षा से गुज़रना पड़ता है, लेकिन जाँच से छूट नहीं मिलती। अविश्वसनीय या अज्ञात स्रोतों को गहरा मैनुअल ऑडिट मिलता है, और हम बंडल की गई स्क्रिप्ट तब तक एक्ज़िक्यूट नहीं करते जब तक उन्हें पढ़ा, स्कोप किया, और सुरक्षित के रूप में वर्गीकृत नहीं किया जाता।

गैप विश्लेषण: अपनाने से पहले, हम अपनी रजिस्ट्री सर्च करते हैं:

uv run orkestra skills search "<capability>"

अगर हमारे पास पहले से है, तो हमें इसकी ज़रूरत नहीं। अगर हमारे पास कुछ मिलता-जुलता है, तो हम शायद अपनाने के बजाय मर्ज करें।

डेप्थ और स्टैंडर्ड्स स्कोरिंग: हम यह भी स्कोर करते हैं कि कोई उम्मीदवार agent-skill मॉडल का कितनी पूरी तरह उपयोग करता है। एक अकेला SKILL.md अब भी उपयोगी हो सकता है, लेकिन गहरी स्किल तब ज़्यादा मूल्यवान होती हैं जब वे निर्देशों को रेफ़रेंस, स्क्रिप्ट, और एसेट से उसी तरह अलग करती हैं जैसा agentskills.io प्रोत्साहित करता है।

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

GitHub स्टार क्रेडिबिलिटी स्कोर को थोड़ा ऊपर उठा सकते हैं, लेकिन वे किसी उथली या असुरक्षित स्किल को कभी नहीं बचाते। एक अस्पष्ट SKILL.md और अपारदर्शी स्क्रिप्ट वाला हाई-स्टार रिपॉज़िटरी, एक सटीक विवरण, क्यूरेटेड references/, और ऐसे एटॉमिक हेल्पर वाले छोटे रिपॉज़िटरी से नीचे स्कोर करता है जो वास्तव में पूरी स्किल क्षमता का लाभ उठाते हैं।

संरचनात्मक विश्लेषण: हम स्किल क्वालिटी जांचते हैं:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

अगर किसी उम्मीदवार में स्क्रिप्ट शामिल हैं, तो वह समीक्षा और सख़्त हो जाती है। एक अच्छी स्किल सिर्फ़ उपयोगी नहीं होती; उसे पठनीय, सीमित, और किसी एजेंट को सौंपने के लिए सुरक्षित भी होना पड़ता है। अकेला यह सेफ़्टी फ़िल्टर अन्यथा दिलचस्प लगने वाले उम्मीदवारों के एक बड़े हिस्से को अयोग्य ठहरा देता है।

चरण 3: इंजेशन

जब कोई स्किल मूल्यांकन पास कर लेती है, तो वह रजिस्ट्री में प्रवेश करती है। लेकिन स्किल कभी बिना बदले नहीं अपनाई जातीं। इन्हें हमारे सिस्टम में फ़िट करने के लिए संशोधित किया जाता है।

अपनाने पर संशोधन:

मेटाडेटा नॉर्मलाइज़ेशन: हर स्किल को हमारा फ़्रंटमैटर स्कीमा मिलता है
K-स्तर असाइनमेंट: स्किल को उपयुक्त नॉलेज लेयर में रखा जाता है
टैग एनरिचमेंट: डिस्कवरी के लिए टैग जोड़े जाते हैं
टूल डिक्लेरेशन: अनुमत टूल स्पष्ट रूप से घोषित किए जाते हैं
सेक्शन अलाइनमेंट: कॉन्टेंट को हमारे टेम्पलेट से मेल खाने के लिए पुनर्गठित किया जाता है

इंजेशन के बाद एक सामान्य स्किल YAML:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

चरण 4: स्कोप असाइनमेंट

स्किल को स्कोप सौंपे जाते हैं — ऐसी श्रेणियां जो तय करती हैं कि कौन-सा एजेंट कौन-सी स्किल लोड करता है:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

एजेंट अपने स्कोप घोषित करते हैं, और स्किल अपने-आप असाइन हो जाती हैं:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

चरण 5: मैटीरियलाइज़ेशन

प्रोडक्शन में स्किल YAML के रूप में नहीं रहतीं। इन्हें SKILL.md फ़ाइलों में रेंडर किया जाता है जिन्हें Claude Code लोड कर सकता है:

uv run orkestra sync

यह कमांड:

सभी स्किल YAML परिभाषाएं पढ़ता है
उन्हें Jinja टेम्पलेट के ज़रिए रेंडर करता है
SKILL.md फ़ाइलें .claude/skills/ में लिखता है
K-स्तर के हिसाब से व्यवस्थित करता है (foundations/, identities/, domains/, stacks/, project/)

अंतिम आउटपुट संरचना:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

डॉरमेंट स्कोप पैटर्न

हमारे सबसे शक्तिशाली पैटर्न में से एक “अपनाई-गई-लेकिन-लोड-नहीं-हुई” स्किल है। हम इन्हें डॉरमेंट स्कोप कहते हैं।

k-dense-scientific रिपॉज़िटरी की साइंटिफ़िक कंप्यूटिंग स्किल पर विचार करें। हमने बायोइन्फ़ॉर्मेटिक्स, केमिस्ट्री, क्वांटम कंप्यूटिंग, और क्लिनिकल इन्फ़ॉर्मेटिक्स को कवर करने वाली 120+ स्किल अपनाई हैं। लेकिन हमारे ज़्यादातर एजेंट को मॉलिक्यूलर डॉकिंग या जीन एक्सप्रेशन विश्लेषण की ज़रूरत नहीं होती।

हर एजेंट में सभी 120 स्किल लोड करने (कॉन्टेक्स्ट विंडो को फुलाने) के बजाय, हम:

स्किल को एक विशिष्ट स्कोप के साथ अपनाते हैं (जैसे, bioinformatics)
उन्हें डॉरमेंट रखते हैं — रजिस्टर्ड लेकिन लोड नहीं
उन्हें तभी एनेबल करते हैं जब कोई एजेंट वह स्कोप घोषित करता है

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

यह पैटर्न हमें रजिस्ट्री में 466 स्किल रखने देता है, जबकि सामान्य एजेंट सिर्फ़ 40-60 प्रासंगिक स्किल लोड करते हैं।

स्किल के प्रकार

स्किल तीन संज्ञानात्मक पैटर्न में आती हैं:

Workflow

क्रमबद्ध प्रक्रियात्मक चरण: “1. X करो, 2. फिर Y, 3. आख़िर में Z”

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Discipline

व्यवहार संबंधी गार्डरेल: “हमेशा X”, “कभी Y नहीं”, “Z को प्राथमिकता दो”

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Checklist

वैरिफ़िकेशन मानदंड: “X कन्फ़र्म करो”, “Y वेरिफ़ाई करो”, “Z चेक करो”

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

क्वालिटी गेट

हर स्किल को शिप होने से पहले वैलिडेशन पास करना ज़रूरी है:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

विवरण 50-400 अक्षरों के होने चाहिए, ट्रिगर वाक्यांशों (“Use when…”, “When you need…”) के साथ, ताकि Claude Code को पता हो कि उन्हें कब सुझाना है।

हम लगातार वैलिडेट करते हैं:

uv run orkestra validate --show-warnings

वेंडर इकोसिस्टम

हमारी 373 वेंडर स्किल यहां से आती हैं:

प्रदाता	स्किल	डोमेन
AWS Agent	19	क्लाउड सर्विसेज़
Anthropic	12	डॉक्यूमेंट जनरेशन
Cloudflare	8	एज कंप्यूटिंग
Supabase	5	डेटाबेस
k-dense	100+	साइंटिफ़िक कंप्यूटिंग
silvainfm	4	डेटा साइंस
Java Developer Kit	45+	Spring/Java
Vercel	1	ब्राउज़र ऑटोमेशन

हर वेंडर रूट metadata.yaml में घोषित है:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

जब orkestra sync चलता है, तो वेंडर स्किल को उनके प्रोवाइडर नेमस्पेस के साथ .claude/skills/vendor/ में सिमलिंक कर दिया जाता है।

हमने क्या सीखा

चयनात्मकता फल देती है। हर उपयोगी दिखने वाली चीज़ अपनाने का लालच होता है। लेकिन हर स्किल टोकन ख़र्च करती है। प्रति स्किल औसतन 2,834 टोकन के साथ, ब्लोट तेज़ी से नुक़सान पहुंचाता है। हमारी 13% अपनाने की दर एजेंट को हल्का रखती है।

संरचना डिस्कवरी को सक्षम बनाती है। K-स्तर सिस्टम सिर्फ़ व्यवस्था नहीं है — यह पोर्टेबिलिटी के बारे में है। K0 स्किल कहीं भी दोबारा इस्तेमाल की जा सकती हैं। K4 स्किल जानबूझकर प्रोजेक्ट-विशिष्ट हैं। यह स्पष्टता इंसानों और एजेंट, दोनों को वह खोजने में मदद करती है जिसकी उन्हें ज़रूरत है।

डॉरमेंट स्कोप स्केल करते हैं। आप सैकड़ों स्किल अपना सकते हैं बिना उन सभी को लोड किए। स्कोप आपको एक व्यापक रजिस्ट्री बनाने देते हैं जबकि हर एजेंट के कॉन्टेक्स्ट विंडो को प्रबंधनीय रखते हैं।

अपनाने पर संशोधन ज़रूरी है। कच्ची वेंडर स्किल शायद ही कभी आपके सिस्टम में फ़िट बैठती हैं। इंजेशन प्रक्रिया — मेटाडेटा जोड़ना, टियर असाइन करना, टैग समृद्ध करना — बाहरी स्किल को आंतरिक रूप से काम करने लायक़ बनाती है।

माइनिंग निरंतर है। 3,500 का आंकड़ा बढ़ता ही रहता है। नए वेंडर रिपॉज़िटरी सामने आते हैं। कम्युनिटी पैटर्न उभरते हैं। आंतरिक वर्कफ़्लो मज़बूत होते हैं। लूप कभी नहीं रुकता।

आगे क्या है

हम कई सुधारों पर काम कर रहे हैं:

ऑटोमेटेड गैप डिटेक्शन: जब कोई सामान्य एजेंट विफलता किसी अभी तक न अपनाई गई स्किल से हल हो सकती हो, तो अलर्ट करना
स्किल डेप्रीकेशन वर्कफ़्लो: उन स्किल को रिटायर करने की औपचारिक प्रक्रिया जो पुरानी पड़ चुकी हैं या इस्तेमाल में नहीं हैं
क्रॉस-स्किल डिपेंडेंसी: स्किल की पूर्वापेक्षाओं की स्पष्ट घोषणा
उपयोग एनालिटिक्स: ट्रैक करना कि एजेंट वास्तव में कौन-सी स्किल इनवोक करते हैं बनाम सिर्फ़ लोड करते हैं

स्किल माइनिंग लूप इन्फ़्रास्ट्रक्चर है। यह चमकदार नहीं है। लेकिन यही वह चीज़ है जो 41 एजेंट को कॉन्टेक्स्ट सीमाओं के भीतर रहते हुए 466 क्षमताओं के साथ सुसंगत रूप से काम करने देती है।

यही कहानी है कि 3,500 कैसे 466 बन जाते हैं। 3,000 को नज़रअंदाज़ करके नहीं — उन्हें व्यवस्थित रूप से परखकर और सिर्फ़ वही अपनाकर जो काम करता है।

स्किल सिस्टम को काम करते देखना चाहते हैं? हमारी मौजूदा रजिस्ट्री एक्सप्लोर करने के लिए uv run orkestra skills list देखें।

प्रोग्रेसिव डिस्क्लोज़र: एजेंट सिस्टम में झांकती CLI खिड़कियां

Tue, 20 Jan 2026 00:00:00 GMT

इस पोस्ट में दिए गए आंकड़े प्रकाशन के समय (जनवरी 2026) की सिस्टम स्थिति दर्शाते हैं। मौजूदा आंकड़ों के लिए हमारा टीम पेज देखें।

एजेंट सिस्टम डिज़ाइन से ही अपारदर्शी होते हैं। वे फ़ैसले लेते हैं, टूल इनवोक करते हैं, और दर्जनों स्पेशलिस्ट में काम समन्वित करते हैं। लेकिन जब कुछ ग़लत हो जाए — या जब आप बस यह समझना चाहें कि क्या हो रहा है — तो आप कहां देखते हैं?

जवाब है प्रोग्रेसिव डिस्क्लोज़र: एक परतदार इंटरफ़ेस जो ठीक उतनी ही जटिलता दिखाता है जितनी आपको चाहिए, ठीक तभी जब आपको चाहिए।

अपारदर्शिता की समस्या

एक आधुनिक एजेंट ऑर्केस्ट्रेशन सिस्टम में हो सकता है:

40+ स्पेशलिस्ट एजेंट, हर एक की अपनी अलग क्षमताएं
आंतरिक ऑटोमेशन और वेंडर इंटीग्रेशन में फैली 700+ स्किल
व्यवहार को आकार देते 470+ आर्किटेक्चरल डिसीज़न
बाहरी क्षमताएं देने वाले दर्जनों MCP टूल सर्वर

यह जटिलता जानबूझकर है। एजेंट को अच्छे फ़ैसले लेने के लिए समृद्ध कॉन्टेक्स्ट — डोमेन ज्ञान, कोड इंटेलिजेंस, डेटाबेस स्कीमा — तक पहुंच चाहिए। लेकिन वही समृद्धि एक दृश्यता समस्या पैदा करती है।

आपको कैसे पता चलेगा कि कौन-सा एजेंट डेटाबेस माइग्रेशन संभालता है? किन डिसीज़न ने सर्च सिस्टम के रैंकिंग व्यवहार को आकार दिया? आर्किटेक्चर एडवाइज़र के पास किन टूल तक पहुंच है?

संरचित पहुंच के बिना, आप या तो सोर्स कोड पढ़ते रह जाते हैं या उम्मीद करते हैं कि डॉक्यूमेंटेशन अद्यतन है।

आर्किटेक्चर के रूप में प्रोग्रेसिव डिस्क्लोज़र

प्रोग्रेसिव डिस्क्लोज़र सिर्फ़ एक UI पैटर्न नहीं है। यह एक आर्किटेक्चरल सिद्धांत है: जानकारी को परतों में व्यवस्थित करें, हर एक पिछली से गहरी, ताकि उपयोगकर्ता उस स्तर पर रुक सकें जो उनके सवाल का जवाब देता है।

एजेंट सिस्टम के लिए, यह बढ़ती गहराई पर CLI कमांड में तब्दील होता है:

स्तर	कमांड	किस सवाल का जवाब मिलता है
1	`orkestra system status`	क्या सब कुछ स्वस्थ है?
2	`orkestra agents list`	कौन-से एजेंट मौजूद हैं?
3	`orkestra agents info <name>`	यह एजेंट क्या करता है?
4	`orkestra decisions search`	यह इस तरह क्यों काम करता है?
5	Maguyva MCP टूल	मुझे कोड दिखाओ।

हर स्तर एक स्वाभाविक फ़ॉलो-अप सवाल का जवाब देता है। आपको शायद ही कभी सीधे स्तर 5 तक कूदने की ज़रूरत पड़ती है।

स्तर 1: सिस्टम हेल्थ

पहला सवाल हमेशा यही होता है: क्या सब कुछ काम कर रहा है?

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

एक कमांड। चार आंकड़े। यह जानने के लिए काफ़ी कि सिस्टम कॉन्फ़िगर है और रजिस्ट्री भरी हुई हैं।

अगर एजेंट काउंट अप्रत्याशित रूप से घटे या स्किल लोड होने में फ़ेल हों, तो आप इसे यहां सबसे पहले देखते हैं। किसी लॉग में डूबने की ज़रूरत नहीं।

स्तर 2: एजेंट इन्वेंटरी

एक बार जब आप जान लें कि सिस्टम स्वस्थ है, तो अगला सवाल है: क्या उपलब्ध है?

$ orkestra agents list

यह संरचित डेटा लौटाता है — एजेंट के नाम, विवरण, मॉडल प्राथमिकताएं, डोमेन कवरेज। आउटपुट डिफ़ॉल्ट रूप से JSON है, जिससे फ़िल्टरिंग के लिए इसे jq में पाइप करना आसान हो जाता है:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

डेटाबेस वर्क संभालने वाले एजेंट चाहिए? सर्च कमांड उसे सीमित कर देता है:

$ orkestra agents search "database"

यह नाम, विवरण, और क्षमताओं को स्कैन करता है। आप 40 एजेंट परिभाषाएं पढ़े बिना सही स्पेशलिस्ट खोज लेते हैं।

स्तर 3: एजेंट डीप डाइव

कोई प्रासंगिक लगने वाला एजेंट मिल गया? info कमांड सब कुछ सामने ला देता है:

$ orkestra agents info architecture-advisor

आउटपुट में शामिल है:

मेटाडेटा: नाम, श्रेणी, मॉडल प्राथमिकता, विवरण
डोमेन: यह एजेंट किन नॉलेज क्षेत्रों को कवर करता है
Identity: कैरेक्टर ट्रेट (architect, strategist, knowledge-architect)
टूल गाइड: कॉन्टेक्स्ट में कौन-सा टूल डॉक्यूमेंटेशन इंजेक्ट किया गया है
टूल: इस एजेंट के लिए उपलब्ध MCP टूल की पूरी सूची

जो आप देखते हैं उसका एक नमूना यह रहा:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

यह आपको ठीक-ठीक बताता है कि एजेंट क्या कर सकता है। किसी सोर्स कोड की ज़रूरत नहीं।

स्तर 4: डिसीज़न आर्कियोलॉजी

एजेंट दस्तावेज़ीकृत डिसीज़न के अनुसार व्यवहार करते हैं। जब आपको यह समझने की ज़रूरत हो कि कुछ किसी ख़ास तरीक़े से क्यों काम करता है, तो डिसीज़न रजिस्ट्री ही सच्चाई का स्रोत है।

$ orkestra decisions search "agent"

यह मिलते-जुलते आर्किटेक्चरल डिसीज़न लौटाता है:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

हर डिसीज़न के स्रोत और इतिहास का पूरा रिकॉर्ड होता है — यह कब लिया गया, क्यों, किन ट्रेड-ऑफ़ पर विचार किया गया, किन कमिट ने इसे इम्प्लीमेंट किया:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

यह ऐसा आर्किटेक्चरल डॉक्यूमेंटेशन है जो अद्यतन बना रहता है क्योंकि यह कमिट से माइन किया जाता है, मैनुअली मेंटेन नहीं किया जाता।

स्तर 5: डायरेक्ट कोड इंटेलिजेंस

जब आपको असली इम्प्लीमेंटेशन देखने की ज़रूरत हो — उसके बारे में मेटाडेटा नहीं — तो Maguyva के MCP टूल डायरेक्ट एक्सेस देते हैं।

किसी एजेंट सेशन के भीतर से:

mcp__maguyva__intelligent_search
  query: "agent context loading"

यह प्रासंगिक कोड खोजने के लिए सिमेंटिक, टेक्स्ट, और AST सर्च में ख़ुद-ब-ख़ुद रूट करता है। विशिष्ट सिंबल के लिए:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

डिपेंडेंसी विश्लेषण के लिए:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

ये सिर्फ़ grep के विकल्प नहीं हैं। ये ग्राफ़-जागरूक, सिमेंटिक रूप से इंडेक्स्ड, और उसी कोड इंटेलिजेंस के साथ इंटीग्रेटेड हैं जो ख़ुद एजेंट को शक्ति देती है।

रजिस्ट्री में एकीकृत सर्च

कभी-कभी आपको नहीं पता होता कि किस रजिस्ट्री में जवाब है। एकीकृत सर्च सब कुछ कवर करता है:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

पांच रजिस्ट्री में 254 मैच। सारांश आपको बताता है कि कहां गहराई से देखना है। विस्तृत नतीजों के लिए --summary हटाएं, या आउटपुट को प्रबंधनीय रखने के लिए --limit 5 जोड़ें।

यह क्यों मायने रखता है

प्रोग्रेसिव डिस्क्लोज़र सिर्फ़ सुविधा के बारे में नहीं है। यह बदल देता है कि आप जटिल सिस्टम के साथ कैसे बातचीत करते हैं।

डीबगिंग आसान हो जाती है। जब कोई एजेंट कोई अप्रत्याशित फ़ैसला लेता है, तो आप लॉग में grep नहीं करते। आप जांचते हैं कि उसके पास किन टूल तक पहुंच है (agents info), कौन-से डिसीज़न उसके व्यवहार को आकार देते हैं (decisions search), और ज़रूरत पड़ने पर इम्प्लीमेंटेशन ट्रेस करते हैं (intelligent_search)।

ऑनबोर्डिंग तेज़ हो जाती है। नए टीम मेंबर को पूरा कोडबेस पढ़ने की ज़रूरत नहीं। वे system status से शुरू करते हैं, agents list से एक्सप्लोर करते हैं, और तभी गहराई में जाते हैं जब उन्हें कुछ ऐसा मिले जो वे समझ न पाएं।

डॉक्यूमेंटेशन अद्यतन बना रहता है। क्योंकि CLI उन्हीं रजिस्ट्री से पढ़ता है जो एजेंट को कॉन्फ़िगर करती हैं, आउटपुट हमेशा सटीक होता है। डॉक्स जो कहते हैं और सिस्टम जो करता है, उसके बीच कोई भटकाव नहीं होता।

इंटरफ़ेस के रूप में CLI

हम एक वेब डैशबोर्ड बना सकते थे। हम विस्तृत डॉक्यूमेंटेशन लिख सकते थे। इसके बजाय, हमने एक CLI बनाया जो सच्चाई के स्रोत से पढ़ता है।

CLI के फ़ायदे हैं:

कम्पोज़ेबल: jq के ज़रिए आउटपुट पाइप करें, स्क्रिप्ट के साथ इंटीग्रेट करें
स्क्रिप्टेबल: चेक ऑटोमेट करें, रिपोर्ट जनरेट करें
तेज़: कोई पेज लोड नहीं, कोई ऑथेंटिकेशन फ़्लो नहीं
सटीक: असली कॉन्फ़िगरेशन पढ़ता है, कोई कैश्ड प्रतिनिधित्व नहीं

ऐसे सिस्टम के लिए जहां सटीकता सौंदर्यशास्त्र से ज़्यादा मायने रखती है, CLI जीतता है।

अपना ख़ुद का प्रोग्रेसिव डिस्क्लोज़र बनाना

अगर आप एजेंट सिस्टम बना रहे हैं, तो सोचें कि उपयोगकर्ता उन्हें कैसे जांचेंगे:

हेल्थ चेक से शुरू करें। एक कमांड जो आपको बताए कि चीज़ें काम कर रही हैं या नहीं।
इन्वेंटरी व्यू दें। यह समझाने से पहले कि कुछ क्या करता है, यह सूचीबद्ध करें कि क्या मौजूद है।
टार्गेटेड क्वेरी सक्षम करें। बड़े पैमाने पर सर्च, ब्राउज़िंग से बेहतर है।
स्रोत और इतिहास दिखाएं। उपयोगकर्ताओं को डिसीज़न को उनके मूल तक ट्रेस करने दें।
कोड इंटेलिजेंस से जोड़ें। आख़िरकार, उपयोगकर्ताओं को इम्प्लीमेंटेशन देखने की ज़रूरत होती है।

हर लेयर एक फ़ॉलो-अप सवाल का जवाब देती है। इन्हें आवृत्ति के क्रम में बनाएं — ज़्यादातर उपयोगकर्ता लेयर 2 या 3 पर रुक जाते हैं। सिर्फ़ पावर यूज़र लेयर 5 तक पहुंचते हैं।

लक्ष्य सब कुछ एक्सपोज़ करना नहीं है। यह ठीक वही एक्सपोज़ करना है जिसकी ज़रूरत है, ठीक तभी जब उसकी ज़रूरत है। यही है एजेंट आर्किटेक्चर पर लागू प्रोग्रेसिव डिस्क्लोज़र।

ग्राउंड ट्रुथ्स: AI एजेंट्स को हक़ीक़त से जोड़ना

Tue, 13 Jan 2026 00:00:00 GMT

इस पोस्ट में दिए गए आंकड़े प्रकाशन के समय (जनवरी 2026) की सिस्टम स्थिति दर्शाते हैं। मौजूदा आंकड़ों के लिए हमारा टीम पेज देखें।

AI एजेंट असाधारण रूप से सक्षम हैं। वे तर्क कर सकते हैं, संश्लेषित कर सकते हैं, और जनरेट कर सकते हैं। लेकिन उनमें एक बुनियादी कमज़ोरी है: वे चीज़ें गढ़ लेते हैं। बदनीयती से नहीं, बल्कि पूरे भरोसे के साथ। कोई एजेंट ऐसे API पैरामीटर गढ़ सकता है जो मौजूद ही नहीं हैं, ऐसे कॉन्फ़िगरेशन का हवाला दे सकता है जो कभी परिभाषित ही नहीं हुए, या अपने ट्रेनिंग डेटा से ऐसे पैटर्न लागू कर सकता है जो आपके असली आर्किटेक्चर के विरुद्ध जाते हैं।

मानक उपाय है “एजेंट को ज़्यादा कॉन्टेक्स्ट दो।” लेकिन कॉन्टेक्स्ट भी परस्पर विरोधाभासी हो सकता है। डॉक्यूमेंटेशन इम्प्लीमेंटेशन से भटक जाता है। कमेंट झूठ बोलते हैं। यहां तक कि आशय समझे बिना पढ़ने पर कोड भी गुमराह कर सकता है।

हमें कुछ ज़्यादा स्पष्ट चाहिए था। कुछ ऐसा जिसे नज़रअंदाज़ या ग़लत तरीक़े से समझा न जा सके। कुछ ऐसा जो एजेंट को सत्यापन योग्य हक़ीक़त से जोड़े रखे।

हम इन्हें ग्राउंड ट्रुथ्स कहते हैं।

ग्राउंड ट्रुथ क्या है?

ग्राउंड ट्रुथ तथ्य का एक स्पष्ट, वर्ज़न्ड कथन है जिसका एजेंट को सम्मान करना ही होता है। यह डॉक्यूमेंटेशन नहीं है। यह कोई कमेंट नहीं है। यह सिस्टम में एक प्रथम-श्रेणी इकाई है, जिसमें शामिल है:

एक यूनीक आइडेंटिफ़ायर (जैसे GT-MAG-015 या GT-MAG-036)
एक लाइफ़साइकल स्टेटस (current, tentative, या deprecated)
एक स्कोप (प्लेटफ़ॉर्म-व्यापी, पैकेज-विशिष्ट, या डोमेन-बद्ध)
साक्ष्य (फ़ाइल पथ, URL, या रेफ़रेंस जो कथन को साबित करते हैं)
एजेंट गाइडेंस (स्पष्ट do/avoid निर्देश)

यह रहा हमारे Maguyva कोड इंटेलिजेंस प्लेटफ़ॉर्म का एक उदाहरण:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

यह गद्य नहीं है। यह एक अनुबंध है। जब कोई एजेंट इस ग्राउंड ट्रुथ का सामना करता है, तो वह जानता है:

डिफ़ॉल्ट डिटरमिनिस्टिक है (खाली परिणाम, अस्पष्ट अनुमान नहीं)
परिभाषित व्यवहार वाले विशिष्ट पैरामीटर मौजूद हैं (find_similar, exact_match)
साक्ष्य विशिष्ट फ़ाइलों में मौजूद है जिसे सत्यापित किया जा सकता है
कथन एक विशिष्ट तारीख़ को सत्यापित किया गया था

ग्राउंड ट्रुथ रजिस्ट्री की संरचना

ग्राउंड ट्रुथ ai_assets/reference/ground_truths.yaml के अंतर्गत YAML रजिस्ट्री में रहते हैं। हर पैकेज या डोमेन की अपनी रजिस्ट्री हो सकती है। संरचना यह है:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

रजिस्ट्री में कलेक्शन के बारे में मेटाडेटा, डॉक्यूमेंटेशन जनरेशन के लिए रेंडर कॉन्फ़िगरेशन, और स्वयं कथन शामिल होते हैं। हर कथन Pydantic मॉडल द्वारा वैलिडेट किए गए एक सख़्त स्कीमा का पालन करता है:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

एजेंट ग्राउंड ट्रुथ तक कैसे पहुंचते हैं

ग्राउंड ट्रुथ कई चैनल के ज़रिए एक्सपोज़ किए जाते हैं:

1. रेंडर्ड डॉक्यूमेंटेशन

orkestra sync कमांड YAML रजिस्ट्री को पढ़ने योग्य मार्कडाउन में बदल देता है:

uv run orkestra sync

यह GROUND_TRUTHS.md फ़ाइलें जनरेट करता है जो एजेंट कॉन्टेक्स्ट में शामिल होती हैं। रेंडर्ड आउटपुट कथनों को स्टेटस और श्रेणी के हिसाब से समूहित करता है:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. CLI सर्च

शेल एक्सेस वाले एजेंट ग्राउंड ट्रुथ को प्रोग्रामेटिक रूप से सर्च कर सकते हैं:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

सर्च फ़ंक्शन कई फ़ील्ड में वेटेड रेलेवेंस के साथ मैच स्कोर करता है:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. कॉन्टेक्स्ट कम्पोज़िशन

जब एजेंट YAML परिभाषाओं से रेंडर किए जाते हैं, तो उनका कॉन्टेक्स्ट ग्राउंड ट्रुथ रजिस्ट्री का हवाला दे सकता है:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

इससे यह सुनिश्चित होता है कि एजेंट के काम शुरू करने से पहले प्रासंगिक ग्राउंड ट्रुथ लोड हो चुके हों।

ग्राउंड ट्रुथ की श्रेणियां

हमारी रजिस्ट्री में देखने पर, ग्राउंड ट्रुथ कई पैटर्न में समूहित हो जाते हैं:

प्रोडक्ट सिद्धांत

यह प्रोडक्ट क्या है और क्या नहीं, इस पर सीमाएं:

“Maguyva उपयोगकर्ता रिपॉज़िटरी के संबंध में केवल-पठनीय (read-only) है; एकमात्र ऐसा एसेट जिसे दोबारा नहीं बनाया जा सकता, वह है पेड एम्बेडिंग कैश।” (GT-MAG-001)

आर्किटेक्चर सीमाएं

ज़िम्मेदारियां कहां रहती हैं और क्यों:

“पाइपलाइन और Maguyva की सीमाएं जानबूझकर बनाई गई हैं: पाइपलाइन पुनः उपयोग योग्य है, Maguyva कोड-विशिष्ट लॉजिक रखता है, और CQRS स्टेज राइट्स को सर्वर रीड्स से अलग करता है।” (GT-MAG-006)

एंटी-हैलुसिनेशन नियम

स्पष्ट अधिदेश जो टूल कॉन्ट्रैक्ट को अनुमानित के बजाय डिटरमिनिस्टिक बनाए रखते हैं:

“फ़ज़ी सिंबल मैचिंग find_similar=true के ज़रिए ऑप्ट-इन है। डिफ़ॉल्ट व्यवहार अस्तित्वहीन सिंबल के लिए खाली परिणाम लौटाता है; exact_match=true सख़्त मैचिंग लागू करता है और सभी फ़ज़ी फ़ॉलबैक बंद कर देता है।” (GT-MAG-015)

क्वालिटी गेट

ऐसे मानदंड जिन्हें बनाए रखना ज़रूरी है:

“साझा इन्फ़्रास्ट्रक्चर (post_filters.py, रिलेशनशिप एक्सट्रैक्टर, साझा हैंडलर) में बदलावों को कमिट से पहले फ़ुल मैनिफ़ेस्ट जनरेशन के ज़रिए सभी सपोर्टेड भाषाओं के विरुद्ध वैलिडेट किया जाना ज़रूरी है। साझा कोड के लिए सिर्फ़ एक भाषा में वैलिडेशन पर्याप्त नहीं है।” (GT-MAG-036)

कोड पैटर्न

इम्प्लीमेंटेशन आवश्यकताएं:

“एसिंक कॉन्टेक्स्ट में CPU-बाउंड काम के लिए asyncio.to_thread() का उपयोग करें; डिप्रीकेटेड loop.run_in_executor() पैटर्न का उपयोग नए कोड में नहीं होना चाहिए।” (GT-MAG-018)

ग्राउंड ट्रुथ का लाइफ़साइकल

ग्राउंड ट्रुथ स्थिर नहीं होते। वे एक परिभाषित लाइफ़साइकल के ज़रिए विकसित होते हैं:

Tentative (अस्थायी)

मूल्यांकन के दौर से गुज़र रहा एक प्रस्तावित सत्य। कथन दर्ज कर लिया गया है लेकिन बदल सकता है:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Current (मौजूदा)

एक सत्यापित सत्य जिसका एजेंट को सम्मान करना ज़रूरी है। साक्ष्य को वैलिडेट किया जा चुका है:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Deprecated (अप्रचलित)

एक ऐसा सत्य जो अब लागू नहीं होता। इसे ऐतिहासिक संदर्भ के लिए रखा गया है, साथ ही यह इशारा भी कि इसकी जगह क्या आया:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

सिर्फ़ डॉक्यूमेंटेशन क्यों नहीं?

डॉक्यूमेंटेशन एक अलग मक़सद पूरा करता है। यह समझाता है। यह सिखाता है। यह अस्पष्ट हो सकता है, “आमतौर पर” या “सामान्यतः” जैसे क्वालिफ़ायर का उपयोग कर सकता है।

ग्राउंड ट्रुथ अस्पष्ट नहीं हो सकते। ये दावे हैं। या तो ये लागू होते हैं या नहीं होते।

यह फ़र्क़ देखें:

डॉक्यूमेंटेशन: “जब कोई सिंबल नहीं मिलता तो API आमतौर पर खाली परिणाम लौटाता है, हालांकि कुछ कॉन्फ़िगरेशन में फ़ज़ी मैचिंग एनेबल हो सकती है।”

ग्राउंड ट्रुथ: “डिफ़ॉल्ट व्यवहार अस्तित्वहीन सिंबल के लिए खाली परिणाम लौटाता है; exact_match=true सख़्त मैचिंग लागू करता है और सभी फ़ज़ी फ़ॉलबैक बंद कर देता है।”

पहला इंसानों के लिए सिस्टम सीखने में मददगार है। दूसरा फ़ैसले लेते समय एजेंट के लिए कार्रवाई-योग्य है।

एजेंट गाइडेंस: करें और बचें

कुछ ग्राउंड ट्रुथ में स्पष्ट एजेंट गाइडेंस शामिल होती है:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

इससे अस्पष्टता ख़त्म हो जाती है। इसे पढ़ने वाला एजेंट सिर्फ़ यह नहीं जानता कि क्या सच है, बल्कि यह भी जानता है कि वह सत्य किन कार्रवाइयों का संकेत देता है।

सत्यापन और रखरखाव

ग्राउंड ट्रुथ को रखरखाव की ज़रूरत होती है। हम ट्रैक करते हैं:

last_verified: कब किसी ने पुष्टि की कि कथन अब भी लागू होता है
evidence: वे फ़ाइलें जो कथन को साबित करती हैं (अस्तित्व के लिए जांची जा सकती हैं)
source: सत्य की उत्पत्ति कहां से हुई (CLI निरीक्षण, आर्किटेक्चर समीक्षा, इंसिडेंट के बाद की सीख)

पुरानी पड़ चुकी सत्यापन तारीख़ों या टूटे साक्ष्य लिंक वाला कोई ग्राउंड ट्रुथ जांच का संकेत है। या तो सत्य अब भी वैध है और उसे दोबारा सत्यापित करने की ज़रूरत है, या हक़ीक़त बदल चुकी है और सत्य को अपडेट करने की ज़रूरत है।

प्रोडक्शन से असली उदाहरण

सुरक्षा सीमा

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

यह ग्राउंड ट्रुथ ऐसे “सुरक्षा सुधारों” की एक पूरी श्रेणी को रोकता है जो भ्रमित होकर प्रोडक्ट को तोड़ देते।

एक्सट्रैक्शन-टाइम सटीकता

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

यह एक तकलीफ़देह अनुभव से आया। एजेंट फ़ेल हो रहे लैंग्वेज पैक को सिर्फ़ वैलिडेटर-ओनली फ़िल्टर जोड़कर पैच कर देते थे, जिससे टेस्ट हार्नेस ज़्यादा ग्रीन दिखने लगता था, जबकि लाइव Maguyva एक्सट्रैक्टर अब भी ग़लत एज उत्सर्जित कर रहा होता था। यह नियम फ़िक्स को वापस असली पथ में ले जाने पर मजबूर करता है: YAML कॉन्फ़िग, क्वेरी, या हैंडलर।

मल्टी-टियर फ़िल्टरिंग

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

यह एजेंट को ग़लत जगह फ़िल्टर जोड़ने से रोकता है, एक आम ग़लती जिसने सटीकता में रिग्रेशन पैदा किया था।

ऑर्केस्ट्रेशन सिस्टम के साथ इंटीग्रेशन

ग्राउंड ट्रुथ एक व्यापक कॉन्टेक्स्ट सिस्टम की एक लेयर हैं:

आर्किटेक्चरल डिसीज़न (ADR) - दर्ज करते हैं कि हमने अप्रोच A को B पर क्यों चुना
ग्राउंड ट्रुथ - बताते हैं कि अभी निश्चित रूप से क्या सच है
डोमेन पैटर्न - बताते हैं कि चीज़ें सही तरीक़े से कैसे करें
एंटी-पैटर्न - बताते हैं कि क्या टालना चाहिए और क्यों

सिस्टम में काम करने वाले किसी एजेंट के पास चारों तक पहुंच होती है। ग्राउंड ट्रुथ तथ्यात्मक आधार देते हैं, जबकि डिसीज़न इतिहास समझाते हैं, पैटर्न इम्प्लीमेंटेशन में मार्गदर्शन करते हैं, और एंटी-पैटर्न ख़तरों के प्रति आगाह करते हैं।

प्रभाव मापना

ग्राउंड ट्रुथ लाने के बाद से, हमने देखा है:

“हैलुसिनेटेड फ़िक्स को फ़िक्स करने” के चक्र कम हुए
जब तथ्य स्पष्ट होते हैं तो एजेंट का फ़ैसला ज़्यादा भरोसेमंद होता है
बेहतर PR समीक्षाएं क्योंकि अपेक्षाएं स्पष्ट हैं
नए एजेंट (और इंसानों) के लिए घटा हुआ ऑनबोर्डिंग समय

ग्राउंड ट्रुथ को बनाए रखने में किया गया निवेश कम डीबगिंग और स्पष्ट सिस्टम सीमाओं के रूप में फल देता है।

शुरुआत कैसे करें

अपने सिस्टम में एक ग्राउंड ट्रुथ जोड़ने के लिए:

अपने पैकेज की ai_assets/reference/ डायरेक्टरी में एक ground_truths.yaml बनाएं
मेटाडेटा और रेंडर कॉन्फ़िगरेशन परिभाषित करें
स्कीमा का पालन करते हुए कथन जोड़ें
डॉक्यूमेंटेशन जनरेट करने के लिए uv run orkestra sync चलाएं
एजेंट कॉन्टेक्स्ट कम्पोज़िशन में रजिस्ट्री शामिल करें

उन तथ्यों से शुरू करें जो सबसे ज़्यादा भ्रम पैदा करते हैं, या उन सीमाओं से जिनका सबसे ज़्यादा उल्लंघन होता है। यही आपके सबसे मूल्यवान ग्राउंड ट्रुथ हैं।

निष्कर्ष

AI एजेंट हैलुसिनेट करेंगे। यह उनकी प्रकृति है। लेकिन हम ऐसे वातावरण बना सकते हैं जहां हैलुसिनेशन को सीमित किया जाए, जहां कुछ तथ्यों पर कोई समझौता न हो, जहां एजेंट अपनी धारणाओं को सत्यापित हक़ीक़त के विरुद्ध जांच सकें।

ग्राउंड ट्रुथ कोई मुकम्मल समाधान नहीं हैं। उन्हें रखरखाव की ज़रूरत होती है। वे पुराने पड़ सकते हैं। वे डेवलपमेंट प्रक्रिया में ओवरहेड जोड़ते हैं।

लेकिन वे कुछ मूल्यवान देते हैं: तथ्यों की एक साझा शब्दावली जिस पर इंसान और एजेंट, दोनों भरोसा कर सकते हैं। ऐसी दुनिया में जहां एजेंट सॉफ़्टवेयर डेवलपमेंट में बढ़ती हुई भागीदारी निभा रहे हैं, वह साझा नींव अनिवार्य हो जाती है।

विकल्प है एजेंट के पूरे भरोसे के साथ ग़लतियां करते रहने और इंसानों के उन्हें सुधारते रहने का अंतहीन चक्र। ग्राउंड ट्रुथ सुधारों को स्पष्ट और टिकाऊ बनाकर उस चक्र को तोड़ते हैं।

आपके एजेंट यह जानने के हक़दार हैं कि क्या सच है। उन्हें बताएं।

Orkestra: बड़े पैमाने पर AI एजेंट को ऑर्केस्ट्रेट करना

Tue, 06 Jan 2026 00:00:00 GMT

इस पोस्ट में दिए गए आंकड़े प्रकाशन के समय (जनवरी 2026) की सिस्टम स्थिति दर्शाते हैं। मौजूदा आंकड़ों के लिए हमारा टीम पेज देखें।

जब हमने Claude Code के साथ बनाना शुरू किया, तो हम एक ऐसी समस्या में फंस गए जिसका सामना AI कोडिंग असिस्टेंट का उपयोग करने वाली हर टीम को आख़िरकार करना पड़ता है: एक अकेला एजेंट हर चीज़ अच्छी तरह नहीं कर सकता।

आप किसी एजेंट को डेटाबेस स्पेशलिस्ट बनने के लिए प्रॉम्प्ट कर सकते हैं। या सिक्योरिटी ऑडिटर। या फ़्रंटएंड इंजीनियर। लेकिन जिस पल आप उससे एक साथ तीनों बनने के लिए कहते हैं, क्वालिटी बिगड़ जाती है। कॉन्टेक्स्ट पतला पड़ जाता है। निर्देश टकराते हैं। एजेंट एक ऐसा जनरलिस्ट बन जाता है जो हर चीज़ में औसत दर्जे का होता है।

तो हमने Orkestra बनाया।

Orkestra क्या है?

Orkestra, Claude Code और इसी तरह के AI कोडिंग टूल के लिए एक एजेंट ऑर्केस्ट्रेशन सिस्टम है। यह कई विशेषज्ञ एजेंट को समन्वित करता है, हर एक की अपनी अलग विशेषज्ञता होती है, एक ही ऑर्केस्ट्रेटर के अंतर्गत जो काम को सही स्पेशलिस्ट तक भेजता है।

इसे AI एजेंट के लिए एक स्टाफ़िंग एजेंसी की तरह सोचें। ऑर्केस्ट्रेटर एक टास्क पाता है, यह पहचानता है कि किस स्पेशलिस्ट को इसे संभालना चाहिए, और सही कॉन्टेक्स्ट के साथ डेलिगेट करता है। जब काम पूरा हो जाता है, तो नतीजों को एक साथ जोड़ने के लिए वे वापस ऑर्केस्ट्रेटर के पास आते हैं।

आंकड़े ख़ुद कहानी बताते हैं:

कॉम्पोनेंट	संख्या
स्पेशलिस्ट एजेंट	46
पुनः उपयोग योग्य स्किल	466
आइडेंटिटी आर्किटाइप	27
माइंडसेट	11
कम्युनिकेशन स्टाइल	10
नॉलेज डोमेन	21

कैरेक्टर सिस्टम: एजेंट के लिए D&D

Orkestra के पीछे मुख्य इनसाइट यह है कि एजेंट का व्यवहार तीन कम्पोज़ेबल प्रिमिटिव से उभरता है:

Identity परिभाषित करती है कि एजेंट क्या है। एक आर्किटेक्ट सिस्टम संरचनाएं डिज़ाइन करता है। एक डीबगर विफलताओं को उनके मूल कारणों तक ट्रेस करता है। एक गार्डियन अनुपालन और सुरक्षा सीमाओं को लागू करता है। हमारे पास 27 आइडेंटिटी आर्किटाइप हैं जिन्हें मिलाया जा सकता है।

Mindset परिभाषित करती है कि एजेंट कैसे सोचता है। एक विश्लेषणात्मक माइंडसेट दावों को साक्ष्य पर आधारित करता है और अनिश्चितता को मात्रात्मक बनाता है। एक संशयवादी माइंडसेट धारणाओं पर सवाल उठाता है और खंडन करने वाला साक्ष्य खोजता है। एक अन्वेषणात्मक माइंडसेट अस्पष्टता को अपनाता है और कई अप्रोच आज़माता है।

Style परिभाषित करती है कि एजेंट कैसे संवाद करता है। एक तकनीकी स्टाइल सटीक वैल्यू शामिल करती है और विशिष्ट फ़ाइलों का हवाला देती है। एक संक्षिप्त स्टाइल फ़ालतू बातें काटती है और जवाब से शुरुआत करती है। एक कूटनीतिक स्टाइल ईमानदारी को व्यवहार-कुशलता के साथ संतुलित करती है।

एक एजेंट इन प्रिमिटिव को मिलाता है:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

यह कम्पोज़िशन एक ऐसा एजेंट बनाता है जो सिस्टम डिज़ाइन करता है (architect), डोमेन में ज्ञान जोड़ता है (knowledge-architect), रणनीतिक दिशा तय करता है (strategist), साक्ष्य और डेटा में सोचता है (analytical), और बिना फ़ालतू बात के संवाद करता है (concise)।

ताक़त कॉम्बिनेटोरियल विस्फोट में है। 27 आइडेंटिटी गुणा 11 माइंडसेट गुणा 10 स्टाइल लगभग 3,000 संभावित एजेंट व्यक्तित्व पैदा करता है। लेकिन आप सिर्फ़ वही कॉम्बिनेशन परिभाषित करते हैं जो आपके काम के लिए मायने रखते हैं।

स्किल: पुनः उपयोग योग्य क्षमता मॉड्यूल

स्किल वह ज्ञान और वर्कफ़्लो हैं जिन्हें एजेंट इनवोक कर सकते हैं। ये स्कोप के आधार पर एक स्तरीय सिस्टम का पालन करते हैं:

स्तर	नाम	स्कोप	उदाहरण
K0	Foundations	सार्वभौमिक कार्यप्रणाली	Test-first discipline, साक्ष्य-आधारित पूर्णता
K1	Identities	भूमिका-आधारित वर्कफ़्लो	CLI इंटरफ़ेस मानक, परफ़ॉर्मेंस प्लेबुक
K2	Domains	डोमेन-विशिष्ट ज्ञान	डेटाबेस माइग्रेशन पैटर्न, ऑथेंटिकेशन वैलिडेशन
K3	Stacks	टेक्नोलॉजी-विशिष्ट	Cloudflare डिप्लॉयमेंट, Supabase ऑपरेशन
K4	Project	सिर्फ़ यह कोडबेस	प्रोजेक्ट-विशिष्ट वर्कफ़्लो और परंपराएं

स्किल लेज़ी-लोडेड होती हैं। एक एजेंट स्टार्टअप पर स्किल के नाम और विवरण देखता है, लेकिन पूरा स्किल कॉन्टेंट तभी लोड होता है जब वह ट्रिगर हो। यह सैकड़ों स्किल को खोजने योग्य बनाते हुए कॉन्टेक्स्ट को हल्का रखता है।

हर स्किल में शामिल है:

स्पष्ट ट्रिगर शर्तें (“डेटाबेस स्कीमा माइग्रेट करते समय उपयोग करें”)
चरण-दर-चरण मार्गदर्शन
वर्कफ़्लो के लिए अनुमत टूल
सफलता मानदंड और विफलता रिकवरी पथ

हमारी रजिस्ट्री में मौजूद 466 स्किल git worktree पृथक्करण से लेकर वेब रिसर्च वर्कफ़्लो से लेकर डिप्लॉयमेंट हेल्थ वैलिडेशन तक सब कुछ कवर करती हैं।

ऑर्केस्ट्रेशन क्यों मायने रखता है

सिंगल-एजेंट आर्किटेक्चर जल्दी दीवारों से टकरा जाते हैं:

कॉन्टेक्स्ट डायल्यूशन। 200k टोकन का कॉन्टेक्स्ट विंडो तब तक बड़ा लगता है जब तक आप डेटाबेस स्कीमा, API डॉक्स, टेस्ट फ़िक्स्चर, और डोमेन ज्ञान लोड नहीं करते। स्पेशलिस्ट टार्गेटेड कॉन्टेक्स्ट के साथ काम कर सकते हैं।

निर्देश टकराव। किसी एजेंट को “बारीकी से काम करो, लेकिन तेज़ी से” और “सब कुछ वेरिफ़ाई करो लेकिन ओवर-इंजीनियर मत करो” कहना तनाव पैदा करता है। स्पेशलिस्ट स्पष्ट स्कोप रखकर इन्हें सुलझाते हैं।

विशेषज्ञता की गहराई। एक जनरलिस्ट एजेंट हर चीज़ के बारे में थोड़ा-थोड़ा जानता है। सही identity और skills के साथ बना एक स्पेशलिस्ट एजेंट अपने डोमेन को गहराई से जानता है।

Orkestra फ़्लैट ऑर्केस्ट्रेशन लागू करता है: एक ऑर्केस्ट्रेटर कई स्पेशलिस्ट को समन्वित करता है। स्पेशलिस्ट सब-स्पेशलिस्ट स्पॉन नहीं कर सकते। यह समानांतर काम को सक्षम करते हुए जटिलता के विस्फोट को रोकता है।

ऑर्केस्ट्रेटर के पास प्रभावी क्षमता के 2.2 मिलियन टोकन तक पहुंच है: इसकी अपनी 200k विंडो, साथ ही 10 समवर्ती सबएजेंट, हर एक के पास 200k। जो काम एक अकेले एजेंट को थका देता, वह पूरे फ़्लीट में आराम से चल जाता है।

रेंडरिंग पाइपलाइन

एजेंट परिभाषाएं YAML में रहती हैं। Claude Code मार्कडाउन पढ़ता है। Orkestra एक डिटरमिनिस्टिक रेंडरिंग पाइपलाइन के साथ इस अंतर को पाटता है:

YAML Registries → Jinja Templates → .claude/agents/*.md

ऑपरेटर YAML सोर्स एडिट करते हैं। orkestra sync चलाएं। रेंडर्ड मार्कडाउन .claude/agents/ में दिखाई देता है। Claude Code बदलाव उठा लेता है।

यह अलगाव अलग-अलग ऑडियंस के काम आता है:

YAML सोर्स में टूलिंग के लिए लाइफ़साइकल मेटाडेटा, टैग, वैलिडेशन नियम, और डेप्रीकेशन नोट शामिल होते हैं
रेंडर्ड मार्कडाउन में सिर्फ़ वही शामिल होता है जिसकी मॉडल को ज़रूरत है: विवरण, टूल, स्किल, और व्यवहार संबंधी मार्गदर्शन

पाइपलाइन identity, mindset, style, और skills को एक ही सुसंगत प्रॉम्प्ट में मिला देती है। एक architect-analytical-concise एजेंट को एक debugger-skeptical-technical एजेंट से बिल्कुल अलग सिस्टम प्रॉम्प्ट मिलता है, भले ही वे कुछ अंतर्निहित स्किल साझा करते हों।

डोमेन नॉलेज: चार-फ़ाइल पैटर्न

हर नॉलेज डोमेन एक सुसंगत संरचना का पालन करता है:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

यह संरचना एजेंट कॉन्टेक्स्ट लोडिंग के काम आती है। ऑथेंटिकेशन पर काम करने वाला कोई एजेंट मार्गदर्शन के लिए authentication/patterns.md और जाने-पहचाने ख़तरों से बचने के लिए authentication/anti-patterns.md लोड करता है। फ़ाइलें कुशल कॉन्टेक्स्ट लोडिंग के लिए आकार में रखी गई हैं: उपयोगी होने लायक़ फ़ोकस्ड, आधिकारिक होने लायक़ व्यापक।

हम एनालिटिक्स, ऑथेंटिकेशन, डेटा साइंस, इन्फ़्रास्ट्रक्चर, मशीन लर्निंग, परफ़ॉर्मेंस, सिक्योरिटी, और अन्य सहित 21 टॉप-लेवल डोमेन बनाए रखते हैं। हर डोमेन में महीन ग्रैन्यूलैरिटी के लिए सब-डोमेन हो सकते हैं।

Values: ऑपरेटिंग सिस्टम

सभी एजेंट वैल्यू की एक बेस लेयर साझा करते हैं जो तय करती है कि वे कैसे ऑपरेट करते हैं:

सादगी पहले। ऐसा सबसे सरल समाधान उपयोग करें जो काम करे। जटिलता तभी जोड़ें जब वह जायज़ हो।

मूल कारण ठीक करें। विफलताओं के इर्द-गिर्द कभी पैच न लगाएं। अगर कोई पाइपलाइन फ़ेल होती है, तो पाइपलाइन डीबग करें। अगर कोई टेस्ट फ़ेल होता है, तो कोड या टेस्ट ठीक करें।

साक्ष्य-आधारित। दावों को “verified” (बेंचमार्क के साथ) या “अनुमानित” (धारणाओं के साथ) लेबल करें। पैटर्न मिलना समस्या की पुष्टि होने के बराबर नहीं है।

कॉन्टेक्स्ट इकोनॉमिक्स। MCP टूल कॉन्टेक्स्ट का 0.1% ख़र्च करते हैं। फ़ाइल रीड हर एक 2% ख़र्च करती हैं। कोड एक्सप्लोर करने से पहले डोमेन विशेषज्ञता लागू करें।

ये वैल्यू रेंडरिंग पाइपलाइन के ज़रिए हर स्पेशलिस्ट तक फैलती हैं। कोई एजेंट कम्पोज़िशन के ज़रिए इन्हें बायपास नहीं कर सकता।

CLI: कंट्रोल प्लेन

Orkestra एजेंट इकोसिस्टम को मैनेज करने के लिए एक CLI के साथ आता है:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

CLI इस बात का सच्चाई का स्रोत है कि कौन-से एजेंट मौजूद हैं, उनके पास कौन-सी स्किल हैं, और सिस्टम स्वस्थ है या नहीं। यह समस्याओं को जल्दी पकड़ने के लिए सिंक से पहले वैलिडेशन चलाता है।

ओपन सोर्स पर विचार

हमने Orkestra अपनी ही समस्या हल करने के लिए बनाया: एक जटिल कोडबेस के लिए बड़े पैमाने पर AI एजेंट को समन्वित करना। जो पैटर्न हमने खोजे, वे हमारे डोमेन तक सीमित नहीं हैं।

कैरेक्टर कम्पोज़िशन सिस्टम (identity + mindset + style) किसी भी टीम पर लागू होता है जो एजेंट व्यक्तित्व परिभाषित करती है।

स्किल टियर सिस्टम (K0-K4) स्कोप के हिसाब से पुनः उपयोग योग्य क्षमताओं को व्यवस्थित करने के लिए एक मानसिक मॉडल देता है।

रेंडरिंग पाइपलाइन पैटर्न (YAML सोर्स + टेम्पलेट + जनरेट किए गए आर्टिफ़ैक्ट) टूलिंग और मॉडल कंज़म्पशन के बीच सरोकार अलग करता है।

फ़्लैट ऑर्केस्ट्रेशन मॉडल (एक कोऑर्डिनेटर, कई स्पेशलिस्ट) समानांतरता को सक्षम करते हुए जटिलता से बचता है।

क्या Orkestra ओपन सोर्स बनता है, यह इस पर निर्भर करता है कि क्या इन पैटर्न का Claude Code के साथ बना रहे दूसरों के लिए कोई मूल्य है। अगर आप उन्हीं दीवारों से टकरा रहे हैं जिनका हमने वर्णन किया, तो यह आर्किटेक्चर मदद कर सकता है।

हमने क्या सीखा

Orkestra बनाने ने हमें सिखाया कि ऑर्केस्ट्रेशन एजेंट को ज़्यादा समझदार बनाने के बारे में नहीं है। यह उन्हें ज़्यादा केंद्रित बनाने के बारे में है।

परफ़ेक्ट निर्देशों वाला एक अकेला एजेंट भी कॉन्टेक्स्ट ख़त्म कर बैठता है। सारी स्किल वाला एक अकेला एजेंट भी उलझ जाता है कि कौन-सी लागू करे। हर चीज़ बनने की कोशिश करने वाला एक अकेला एजेंट हर जगह औसत दर्जे के नतीजे देता है।

चालीस स्पेशलिस्ट, हर एक अपने डोमेन में उत्कृष्ट, एक ऐसे ऑर्केस्ट्रेटर से समन्वित जो जानता है कि कब डेलिगेट करना है: यही वह तरीक़ा है जिससे हम शिप करते हैं।

आर्किटेक्चर से कम मायने आंकड़े रखते हैं। आपको पांच एजेंट चाहिए हो सकते हैं, या पचास। सिद्धांत वही रहता है: क्षमता के बजाय कम्पोज़िशन, हर क्षेत्र में थोड़ा-थोड़ा जानने के बजाय विशेषज्ञता, व्यक्तिगत वीरता के बजाय समन्वय।

Orkestra हमारे कोड इंटेलिजेंस प्लेटफ़ॉर्म, Maguyva के पीछे मौजूद एजेंट इकोसिस्टम को चलाता है। और जानना चाहते हैं? टीम से संपर्क करें।