Claude Code के सब-एजेंट: संदर्भ का अलगाव, ऑर्केस्ट्रेटर और रिव्यूअर, और ये कब जरूरी नहीं
Claude Code के सब-एजेंट अलग एजेंट इंस्टेंस हैं, जिनकी अपनी संदर्भ-विंडो, अपना सिस्टम प्रॉम्प्ट और अपने टूल होते हैं: मुख्य एजेंट उन्हें कोई कार्य सौंपता है और वापस केवल अंतिम उत्तर पाता है। ये इसलिए उपयोगी हैं कि खोज और लॉग से मुख्य संदर्भ गंदा न हो, जाँच को क्रियान्वयन से अलग रखा जा सके और स्वतंत्र काम समानांतर चले; इन्हें .claude/agents फ़ोल्डर में Markdown फ़ाइलों से परिभाषित किया जाता है।
Claude Code के सब-एजेंट क्या हैं
सब-एजेंट एजेंट का एक और इंस्टेंस है, जिसे मुख्य एजेंट किसी अलग कार्य के लिए चलाता है। उसकी अपनी संदर्भ-विंडो है, अपना सिस्टम प्रॉम्प्ट है और अनुमत टूलों की अपनी सूची है। मुख्य एजेंट उसे कार्य का विवरण देता है, सब-एजेंट खुद काम करता है (फ़ाइलें पढ़ता है, कमांड चलाता है), और वापस केवल अंतिम संदेश भेजता है।
मुख्य शब्द यहाँ अलगाव (isolation) है। सब-एजेंट ने रास्ते में जो कुछ पढ़ा, दर्जनों फ़ाइलें, टेस्ट का लंबा आउटपुट, गलत चली परिकल्पनाएँ, वह सब उसी के संदर्भ में रहता है और मुख्य सत्र के संदर्भ में नहीं जाता। मुख्य एजेंट को छोटा परिणाम दिखता है: «गड़बड़ी फ़ंक्शन X में है, कारण यह है, प्रभावित जगहें ये तीन हैं»।
Claude Code के सब-एजेंट मल्टी-एजेंट सिस्टम के सामान्य विचार का एक रूप हैं: «सोचो — करो — जाँचो» के एक चक्र की जगह कई नोड्स का ग्राफ़ आता है, हर एक की अपनी भूमिका और जिम्मेदारी के साथ।
संदर्भ के अलगाव की जरूरत क्यों है
संदर्भ-विंडो एजेंट का मुख्य संसाधन है। उसमें एक साथ CLAUDE.md के निर्देश, संवाद का इतिहास, पढ़ा गया कोड और कमांड का आउटपुट रहते हैं। जब एजेंट बग का कारण आधे घंटे तक ढूँढता है, तो संदर्भ ऐसी फ़ाइलों से भर जाता है जो कारण नहीं थीं, और ऐसे लॉग से जिनमें काम की बस एक पंक्ति थी।
इसके नतीजे उन सबको पता हैं, जो एजेंट के साथ लंबे समय से काम करते हैं: मॉडल प्रोजेक्ट के नियम कम ध्यान में रखता है, विवरण आपस में मिला देता है, और स्वचालित संक्षेपण में वह खो देता है जो जरूरी था। सब-एजेंट इसे संरचना से हल करता है: गंदा काम एक अलग संदर्भ में होता है, जो उत्तर के बाद फेंक दिया जाता है।
- खोज और अन्वेषण। «वे सारी जगहें ढूँढो जहाँ भुगतान वाला फ़ंक्शन बुलाया जाता है, और बताओ वे कैसे बनी हैं» — सब-एजेंट के लिए यह ठीक कार्य है।
- शोरगुल वाली जाँचें। टेस्ट चलाना और गिरे हुए टेस्टों का विश्लेषण सब-एजेंट को दें, और कारणों की सूची लें।
- बड़े दस्तावेज़ पढ़ना। सैकड़ों पन्नों की विशिष्टता की जरूरत कुछ तथ्यों के लिए होती है, सब-एजेंट उन्हें निकाले।
सब-एजेंट कैसे सेट करें: .claude/agents फ़ोल्डर
अपना सब-एजेंट YAML हेडर वाली Markdown फ़ाइल से परिभाषित होता है। प्रोजेक्ट की फ़ाइलें रिपॉज़िटरी में .claude/agents/ में रहती हैं और git के जरिए पूरी टीम को मिलती हैं; निजी फ़ाइलें ~/.claude/agents/ में रहती हैं और आपके सभी प्रोजेक्टों में चलती हैं। सब-एजेंट को Claude Code में /agents कमांड से इंटरैक्टिव रूप से भी बनाया और संपादित किया जा सकता है।
---
name: code-reviewer
description: कोड में बदलावों की गलतियों और प्रोजेक्ट के नियमों के उल्लंघन की जाँच करता है। कार्य पूरा होने के बाद, कमिट से पहले इस्तेमाल करें।
tools: Read, Grep, Glob, Bash
---
तुम कोड रिव्यूअर हो। तुम्हें कुछ भी ठीक करने की जरूरत नहीं।
1. बदलाव देखो: git diff।
2. हर बदलाव की तर्क-त्रुटियों, त्रुटि-प्रबंधन,
सुरक्षा (SQL, आउटपुट का एस्केपिंग, सीक्रेट) के लिए जाँच करो।
3. AGENTS.md के नियमों से मिलाओ।
4. टिप्पणियों की सूची लौटाओ: फ़ाइल, पंक्ति, समस्या, यह क्यों मायने रखती है।
अगर कोई टिप्पणी नहीं है, तो यही लिखो।फ़ील्ड का अर्थ:
| फ़ील्ड | उद्देश्य |
|---|---|
name | सब-एजेंट का नाम, जिससे उसे बुलाया जाता है |
description | उसे कब इस्तेमाल करना है। इसी विवरण से मुख्य एजेंट तय करता है कि कार्य किसे दे, इसलिए ठोस लिखें |
tools | अनुमत टूल। अगर यह फ़ील्ड न हो, तो सब-एजेंट मुख्य सत्र के टूल विरासत में लेता है |
model | वैकल्पिक: इस सब-एजेंट के लिए कौन सा मॉडल इस्तेमाल हो |
फ़ाइल का मुख्य भाग सब-एजेंट का सिस्टम प्रॉम्प्ट है। उसे आपके संवाद का इतिहास नहीं दिखता, इसलिए उसकी भूमिका और उत्तर का प्रारूप प्रॉम्प्ट में या उस कार्य में होना चाहिए जो मुख्य एजेंट देता है।
सब-एजेंट को कैसे बुलाएँ
मुख्य एजेंट खुद सब-एजेंट चुन सकता है, अगर कार्य उसके description से मेल खाता हो। पर साफ़ कहना ज़्यादा भरोसेमंद है: «code-reviewer सब-एजेंट का उपयोग करके बदलावों की जाँच करो»। विवरण में «सक्रिय रूप से उपयोग करो» जैसे वाक्य सब-एजेंट को बिना याद दिलाए बुलाए जाने की संभावना बढ़ाते हैं, पर गारंटी नहीं देते।
खोज करने वाला सब-एजेंट
एक दूसरी फ़ाइल जो लगभग हर प्रोजेक्ट में बनाने लायक है, वह है केवल-पढ़ने वाला खोजी। वह कोड के बारे में सवालों का जवाब देता है और कुछ नहीं बदलता।
---
name: explorer
description: कोडबेस में खोजता है कि कोई चीज़ कहाँ और कैसे बनी है। जब बहुत सारी फ़ाइलें पढ़कर छोटा उत्तर चाहिए, तब इस्तेमाल करें।
tools: Read, Grep, Glob
---
तुम कोड की खोज करते हो और कुछ नहीं बदलते।
लौटाओ: सवाल का संक्षिप्त उत्तर, उन फ़ाइलों की सूची जिन पर वह टिका है (पंक्तियों के साथ),
और वह जो जाँचा नहीं जा सका।यह सब-एजेंट कार्य की शुरुआत में खास उपयोगी है: मुख्य एजेंट को ज़रूरी जगहों का नक्शा मिल जाता है, बिना संदर्भ खर्च किए सब कुछ पढ़े, और आगे वह ठोस फ़ाइलों के साथ काम करता है।
«ऑर्केस्ट्रेटर और वर्कर» योजना
सबसे आम मल्टी-एजेंट योजना: एक ऑर्केस्ट्रेटर एजेंट योजना और बड़ी तस्वीर अपने पास रखता है, और ठोस चरण वर्करों को बाँटता है। ऑर्केस्ट्रेटर पूरा कोड खुद नहीं पढ़ता; वह कार्य तैयार करता है, परिणाम स्वीकार करता है और तय करता है कि आगे क्या करना है।
- ऑर्केस्ट्रेटर कार्य को स्वतंत्र हिस्सों में बाँटता है और हर हिस्से के लिए स्वयं-पूर्ण निर्देश लिखता है: लक्ष्य, कहाँ खोजना है, क्या तैयार माना जाएगा, उत्तर किस रूप में लौटाना है।
- वर्कर अपने-अपने संदर्भ में निर्देश पूरे करते हैं।
- ऑर्केस्ट्रेटर उत्तर इकट्ठा करता है, जाँचता है कि हिस्से आपस में मिलते हैं, और अगला चरण चलाता है या पिछले चरण पर लौटता है।
इस योजना की कमज़ोर कड़ी है कार्य का हस्तांतरण। सब-एजेंट को वही पता है जो उसे लिखा गया है। «वह बग ठीक करो जिस पर हमने चर्चा की थी» उसके लिए खाली निर्देश है: उसने चर्चा देखी ही नहीं। अच्छा निर्देश उस नए सहकर्मी के कार्य जैसा पढ़ा जाना चाहिए, जिसने पहली बार रिपॉज़िटरी खोली है।
वर्कर को क्या लौटाना चाहिए
उत्तर का प्रारूप पहले से तय करें: फ़ाइलों की सूची, आउटपुट, मिले कारण, और क्या जाँचा नहीं जा सका। छोटा और संरचित उत्तर ऑर्केस्ट्रेटर का संदर्भ बचाता है, और «क्या नहीं जाँचा» वाला बिंदु झूठे भरोसे से बचाता है: वर्कर भी, किसी भी एजेंट की तरह, सफलता की रिपोर्ट देने की ओर झुकता है।
अलग रिव्यूअर: जज को कार्यकर्ता से क्यों अलग रखें
जब वही एजेंट कोड लिखता है और खुद उसकी जाँच भी करता है, तो जज और आरोपी एक ही दिमाग़ हैं। एजेंट को याद रहता है कि उसने क्या करना चाहा था, और वह कोड में अपनी मंशा देखता है, न कि वह जो लिखा है। साथ ही वह पूरा करने को उत्सुक होता है, इसलिए जाँच औपचारिकता बन जाती है।
अलग संदर्भ वाला रिव्यूअर इन समस्याओं से मुक्त होता है। उसे निर्णयों का इतिहास नहीं दिखता, वह केवल diff और प्रोजेक्ट के नियम देखता है, और परिणाम को ताज़ी नज़र से आँकता है। यह वही सिद्धांत है जो किसी जीवित टीम में है: लेखक अपने ही pull request को स्वीकार नहीं करता।
- रिव्यूअर को केवल पढ़ने और जाँच चलाने के टूल दें, फ़ाइलें संपादित करने का अधिकार नहीं। तब वह समस्या बताने के बजाय चुपचाप «ठीक» करना शुरू नहीं करेगा।
- जाँच के मानदंड साफ़ लिखें: क्या गलती माना जाएगा, कौन से प्रोजेक्ट-नियम अनिवार्य हैं।
- टिप्पणियों का क्या करना है, यह फ़ैसला ऑर्केस्ट्रेटर या इंसान पर छोड़ें। रिव्यूअर ढूँढता है, वर्कर सुधारता है।
रिव्यूअर यांत्रिक जाँचों की जगह नहीं लेता। टेस्ट, लिंटर और टाइप-जाँच नियतात्मक नोड्स हैं, वे किसी भी मॉडल से भरोसेमंद हैं। रिव्यूअर वह पकड़ता है जो मशीनरी नहीं देख सकती: गलत तर्क, समझौतों का उल्लंघन, अनावश्यक जटिलता।
सब-एजेंट का समानांतर चलना
Claude Code एक साथ कई सब-एजेंट चला सकता है। जब कार्य के हिस्से सचमुच स्वतंत्र हों, तो इससे गति बढ़ती है: तीन मॉड्यूल का अध्ययन, किसी बदलाव की तीन दिशाओं से जाँच (सुरक्षा, प्रदर्शन, टेस्ट), या कई स्रोतों से जानकारी इकट्ठा करना।
समानांतरता पढ़ने पर अच्छी चलती है और लिखने पर खराब। अगर दो वर्कर एक साथ एक ही फ़ाइलें बदलें, तो वे एक-दूसरे के बदलाव मिटा देते हैं, और कोई भी इसे नहीं जानता। ग्राफ़ की भाषा में यह बिना मर्ज-नियम के साझा अवस्था है। व्यावहारिक नियम:
- समानांतर में खोज, विश्लेषण और रिव्यू। एक-दूसरे को छूने वाली फ़ाइलों में बदलाव क्रमिक रूप से।
- अगर वर्कर फिर भी समानांतर लिखें, तो क्षेत्र बाँटें: हर एक केवल अपनी फ़ाइलों में काम करे, या अपनी प्रति में (जैसे अलग git worktree में)।
- परिणाम एक ही नोड समेटे: ऑर्केस्ट्रेटर, वर्कर आपस में नहीं।
सब-एजेंट कब जरूरी नहीं हैं
मल्टी-एजेंट योजना की एक कीमत है: ज़्यादा टोकन, ज़्यादा समय, और ज़्यादा जगहें जहाँ हस्तांतरण में जानकारी खोती है। Claude Code के सब-एजेंट हमेशा लाभदायक नहीं होते।
| स्थिति | क्या चुनें |
|---|---|
| दो फ़ाइलों में छोटा संपादन | एक एजेंट: कार्य सौंपने की लागत खुद कार्य से महँगी है |
| चरण एक-दूसरे पर और चर्चा पर बहुत निर्भर हैं | एक एजेंट: सब-एजेंट को संवाद का संदर्भ नहीं दिखता |
| बड़े कोड में कुछ खोजना है | खोजी सब-एजेंट |
| परिणाम की स्वतंत्र जाँच चाहिए | बिना लिखने के अधिकार वाला रिव्यूअर सब-एजेंट |
| कई स्वतंत्र हिस्से | समानांतर सब-एजेंट, संपादन अलग क्षेत्रों में |
| निर्देश के अनुसार दोहराई जाने वाली प्रक्रिया | Skill: निर्देश मुख्य संदर्भ में लोड होता है, अलग एजेंट नहीं चाहिए |
एजेंटों का ग्राफ़ बनाने से पहले ये सरल सवाल पूछें: साझा लक्ष्य का मालिक कौन है, परिवर्तन पर वीटो और रोलबैक कौन कर सकता है, सफलता किन मेट्रिक्स से मापी जाएगी। अगर इनके जवाब नहीं हैं, तो कई एजेंट एक की भ्रम-स्थिति को ही बढ़ाएँगे।
सब-एजेंट की आम गलतियाँ
धुंधला विवरण
«कोड का सहायक» जैसा विवरण मुख्य एजेंट को यह तय करने में मदद नहीं करता कि उसे कब बुलाए। ट्रिगर लिखें: «api/ फ़ोल्डर में बदलावों के बाद, कमिट से पहले»।
संदर्भ के बिना निर्देश
सब-एजेंट को बिना रास्तों, बिना तैयार होने के मानदंडों और बिना सीमाओं के कार्य मिलता है, और वह आधा समय यह अंदाज़ा लगाने में लगाता है कि उससे क्या चाहिए। इसका इलाज निर्देश का ढाँचा है: लक्ष्य, इनपुट, सीमाएँ, उत्तर का प्रारूप।
बहुत चौड़े अधिकार
खोजी और रिव्यूअर को फ़ाइलें संपादित करने का अधिकार नहीं चाहिए। tools की सीमा भूमिका को प्रॉम्प्ट में माँगी गई बात के बजाय यांत्रिक नियम बना देती है, और यह सस्ता तरीका है।
बिना जाँच के रिपोर्ट पर भरोसा
सब-एजेंट के उत्तर में «सारे टेस्ट पास» एक दावा है, तथ्य नहीं। ऑर्केस्ट्रेटर उस पर भरोसा करे जो जाँचा जा सके: कमांड का आउटपुट, रिटर्न कोड, ठोस पंक्तियाँ।
संक्षेप में
Claude Code के सब-एजेंट तीन काम के लिए हैं: मुख्य संदर्भ साफ़ रखना, जाँच को क्रियान्वयन से अलग करना, और स्वतंत्र काम को समानांतर चलाना। इन्हें .claude/agents/ में छोटी Markdown फ़ाइलों से परिभाषित किया जाता है, और इनकी गुणवत्ता लगभग पूरी तरह भूमिका के विवरण, टूल की सीमा और निर्देश की आत्मनिर्भरता पर टिकी है। जहाँ कार्य छोटा है या संवाद से गहराई से जुड़ा है, वहाँ एक एजेंट अब भी बेहतर है। एक चक्र से नोड्स, किनारों और साझा अवस्था की व्यवस्था तक का सफ़र कोर्स में व्यवहार में समझाया गया है।
अक्सर पूछे जाने वाले प्रश्न
क्या सब-एजेंट मेरे Claude Code संवाद का इतिहास देखता है?
नहीं। सब-एजेंट को अपना सिस्टम प्रॉम्प्ट और मुख्य एजेंट का कार्य-निर्देश मिलता है। उसे जो कुछ जानना है, वह इसी निर्देश में होना चाहिए।
क्या सब-एजेंट दूसरा सब-एजेंट चला सकता है?
नहीं, Claude Code में सब-एजेंट अपने सब-एजेंट नहीं बनाते। कार्य को बाँटने का काम मुख्य ऑर्केस्ट्रेटर एजेंट का है।
सब-एजेंट और skill में क्या फ़र्क है?
Skill एक निर्देश है, जो ज़रूरत पड़ने पर मौजूदा एजेंट के संदर्भ में लोड होता है। सब-एजेंट एक अलग एजेंट है, जिसका अपना संदर्भ है और जो केवल परिणाम लौटाता है।
क्या सब-एजेंट ज़्यादा टोकन खर्च करते हैं?
आमतौर पर हाँ: हर सब-एजेंट अपने संदर्भ में जरूरी फ़ाइलें फिर से पढ़ता है। पर मुख्य संदर्भ कॉम्पैक्ट रहता है, और लंबे कार्यों पर यह अक्सर फ़ायदेमंद होता है।
सब-एजेंट कहाँ रखें, ताकि पूरी टीम उनका उपयोग करे?
प्रोजेक्ट की रिपॉज़िटरी में .claude/agents/ फ़ोल्डर में: फ़ाइलें git में जाती हैं और सभी सदस्यों के लिए एक जैसी चलती हैं।
यह विषय “Harness Engineering: инженерия надёжности AI-агентов” कोर्स में अभ्यास के साथ विस्तार से समझाया गया है।
कोर्स पर जाएँ