AI कोडिंग एजेंट्स को इंसानों से अलग निर्देश पुस्तिका की आवश्यकता क्यों है

कल्पना करें कि आप किसी को कोडबेस सौंपते हैं और कहते हैं: "डॉक्स अपडेट करें, लेकिन कुछ भी न तोड़ें।" एक इंसान डेवलपर README पढ़ता है, इधर-उधर देखता है, और नियमों का पता लगाता है। एक AI कोडिंग एजेंट? उसे अनुमान लगाना पड़ता है।

आज 6 जुलाई 2026 है, और AI एजेंट्स कोड लिखने में बेहतर हो रहे हैं—लेकिन वे अभी भी एक आवर्ती समस्या का सामना कर रहे हैं। उन्हें एक कार्य और एक README मिलता है, फिर उन्हें उन सवालों के जवाब खोजने पड़ते हैं जो उन्हें पूछने ही नहीं चाहिए: यह प्रोजेक्ट किस पैकेज मैनेजर का उपयोग करता है? क्या उन जनरेट की गई फ़ाइलों में बदलाव करना सुरक्षित है? "done" किसे माना जाता है? यहीं पर AGENTS.md काम आता है, और यह आश्चर्यजनक रूप से व्यावहारिक है।

README और एजेंट निर्देशों के बीच का अंतर

एक README इस सवाल का जवाब देता है कि "यह प्रोजेक्ट क्या है?" यह इंसानों के लिए लिखा गया है: आप सीखते हैं कि कोड क्या करता है, इसे स्थानीय रूप से कैसे चलाना है, और बाकी डॉक्स कहां मिलेंगे।

लेकिन कोडिंग एजेंट्स को कुछ अलग चाहिए। उन्हें यह जवाब चाहिए कि "इस रेपो में बदलाव करने से पहले मुझे क्या पता होना चाहिए?" यहीं AGENTS.md कदम रखता है।

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

वास्तव में क्या गलत होता है

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

इसका विशिष्ट समाधान? आप लंबे, अधिक विस्तृत प्रॉम्प्ट लिखते हैं:

"डॉक्स अपडेट करें, लेकिन जनरेट की गई फ़ाइलों को न छुएं, pnpm का उपयोग करें, लिंट और टेस्ट कमांड चलाएं, PR को छोटा रखें, और मुझे बताएं कि आप क्या सत्यापित नहीं कर पाए।"

AGENTS.md के साथ, वह प्रॉम्प्ट छोटा होकर रह जाता है:

"नए कॉन्फ़िग फ़्लैग के लिए क्विकस्टार्ट डॉक्स अपडेट करें।"

एजेंट बाकी सब फ़ाइल से पहले ही जानता है।

Goose (और अन्य एजेंट्स) इसका उपयोग कैसे करते हैं

यह केवल सैद्धांतिक नहीं है। Goose नामक एक टूल—डेस्कटॉप ऐप, CLI, API, MCP एक्सटेंशन और कौशल वाला एक ओपन-सोर्स AI एजेंट—दिखाता है कि यह व्यवहार में क्यों मायने रखता है। AGENTS.md के बिना, प्रत्येक कार्य के लिए एजेंट को आपसे बुनियादी बातों के बारे में पूछने (या अनुमान लगाने) की आवश्यकता होती है। रेपो में AGENTS.md होने पर, Goose एक बार स्थायी नियम पढ़ सकता है और उन्हें हर कार्य पर लागू कर सकता है।

यह पैटर्न एक टूल से आगे तक फैला हुआ है। कोई भी कोडिंग एजेंट जो फ़ाइल पढ़ने के लिए पर्याप्त स्मार्ट है, वह स्पष्ट निर्देशों का पालन कर सकता है यदि वे लिखे गए हों।

एक स्पष्ट विभाजन: AGENTS.md और कौशल (Skills)

एक महत्वपूर्ण सीमा: AGENTS.md को स्थायी नियमों पर केंद्रित रहना चाहिए—वे चीज़ें जो रेपो में लगभग हर कार्य पर लागू होती हैं। लेकिन हर टीम के पास दोहराने योग्य वर्कफ़्लो भी होते हैं। उन्हें AGENTS.md को एक कबाड़खाने में नहीं बदलना चाहिए।

अधिक साफ दृष्टिकोण: AGENTS.md छोटा रहता है और कौशल (skills) की ओर इशारा करता है—विशिष्ट प्रकार के काम के लिए पुन: प्रयोज्य निर्देश सेट। बैकएंड सेवा के लिए, AGENTS.md डेटाबेस माइग्रेशन, API परिवर्तन, और रिलीज़ को अलग-अलग कौशलों में निर्देशित कर सकता है। फ़ाइल पढ़ने योग्य रहती है, और विस्तृत कार्य दिनचर्या कहीं उचित स्थान पर रहती है।

अंतर सरल है: यदि कोई नियम लगभग हर कार्य पर लागू होना चाहिए, तो उसे AGENTS.md में रखें। यदि यह एक प्रकार के काम के लिए एक वर्कफ़्लो है, तो इसे एक कौशल बनाएं।

वास्तव में AGENTS.md में क्या रखना है

यहाँ एक व्यावहारिक प्रारंभिक बिंदु है:

प्रोजेक्ट मैप (Project Map)

एजेंट को बताएं कि क्या कहां रहता है:

• src/ एप्लिकेशन कोड शामिल है।
• tests/ टेस्ट शामिल हैं।
• docs/ उपयोगकर्ता के लिए डॉक्स शामिल हैं।
• generated/ टूलिंग द्वारा निर्मित है; इसे मैन्युअल रूप से संपादित न करें।

कमांड (Commands)

काम करने के सही तरीके की सूची बनाएं:

• इंस्टॉल (Install): pnpm install
• टेस्ट (Test): pnpm test
• लिंट (Lint): pnpm lint
• टाइपचेक (Typecheck): pnpm typecheck

काम के नियम (Working Rules)

सीमाएँ निर्धारित करें:

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

पूर्णता (Completion)

परिभाषित करें कि "done" कैसा दिखता है:

• प्रासंगिक जाँच चलाएँ या समझाएँ कि उन्हें क्यों नहीं चलाया गया।
• बदले हुए व्यवहार का सारांश दें।
• शेष जोखिम या अनुवर्ती (follow-up) की सूची बनाएं।

कौशल (Skills)

कार्य-विशिष्ट वर्कफ़्लो की ओर निर्देशित करें:

• डेटाबेस माइग्रेशन के लिए, migration review कौशल का उपयोग करें।
• API परिवर्तनों के लिए, contract-checking कौशल का उपयोग करें।
• रिलीज़ से पहले, release-notes कौशल का उपयोग करें।

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

कैसे पता करें कि यह काम कर रहा है

इसे एक कम-जोखिम वाले रेपो पर आज़माएं जहाँ आप पहले से ही एक एजेंट के साथ काम करते हैं:

चरण 1: बिना AGENTS.md के एक कार्य चलाएँ

एजेंट को एक सरल काम दें—जैसे, "नए कॉन्फ़िग फ़्लैग के लिए एक उदाहरण जोड़ें।" देखें कि आपको अपने प्रॉम्प्ट में क्या समझाना पड़ता है।

चरण 2: एक AGENTS.md फ़ाइल बनाएँ

उपरोक्त टेम्पलेट का उपयोग करें। इसे पाँच अनुभागों तक रखें। छोटा और कार्रवाई योग्य।

चरण 3: वही कार्य फिर से चलाएँ

एजेंट को अपने प्रॉम्प्ट में केवल मुख्य कार्य के साथ वही काम दें।

चरण 4: इन तीन चीज़ों की जाँच करें

क्या एजेंट ने सही जाँच चलाई? क्या इसने जनरेट की गई फ़ाइलों से परहेज किया? क्या आपका प्रॉम्प्ट छोटा हो गया?

यदि तीनों हाँ हैं, तो रेपो कम अस्पष्ट हो गया है। यदि नहीं, तो फ़ाइल को शायद अधिक विशिष्ट या सरल होने की आवश्यकता है।

निष्कर्ष

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

गुण (Merits)

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

दोष (Demerits)

• जैसे-जैसे प्रोजेक्ट विकसित होता है, फ़ाइल को अप-टू-डेट रखने के लिए अनुशासन की आवश्यकता होती है।
• जो टीमें पहले से ही विस्तृत प्रॉम्प्ट का उपयोग कर रही हैं, उन्हें तत्काल लाभ नहीं दिख सकता है।
• एजेंट की विश्वसनीयता की सभी समस्याओं का समाधान नहीं करता है—बस अनावश्यक अनुमान को कम करता है।
• बहुत छोटे प्रोजेक्ट्स या थ्रोअवे कोड के लिए बहुत अधिक (Overkill) है।
• इसके लिए ऐसे एजेंट टूल्स की आवश्यकता होती है जो वास्तव में फ़ाइल प्रारूप को पढ़ते और उसका सम्मान करते हैं।

सावधानी (Caution)

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

अक्सर पूछे जाने वाले प्रश्न (Frequently asked questions)

• AGENTS.md और एक नियमित README फ़ाइल के बीच क्या अंतर है?
• क्या मैं किसी भी कोडिंग एजेंट के साथ AGENTS.md का उपयोग कर सकता हूँ, या यह टूल-विशिष्ट है?
• मुझे कैसे पता चलेगा कि मेरी AGENTS.md फ़ाइल किसी एजेंट के अनुसरण करने के लिए पर्याप्त स्पष्ट है?
• क्या AGENTS.md में सुरक्षा नीतियां और एक्सेस नियंत्रण शामिल होने चाहिए?
• अगर मेरी AGENTS.md फ़ाइल बहुत लंबी हो जाए तो मुझे क्या करना चाहिए?
• क्या AGENTS.md कोड टिप्पणियों और इनलाइन दस्तावेज़ीकरण को बदल सकता है?
• जैसे-जैसे प्रोजेक्ट विकसित होता है, मुझे कितनी बार AGENTS.md को अपडेट करना चाहिए?
• क्या होता है अगर किसी एजेंट को AGENTS.md में कोई ऐसा निर्देश मिलता है जो उसे समझ नहीं आता?

टैग (Tags)

#AIAgents #CodingAutomation #Documentation #SoftwareDevelopment #DeveloperTools #CodingEfficiency #InstructionDesign