AGENTS.md - AI coding agents के लिए open format
(agents.md)- AGENTS.md README की पूरक भूमिका निभाता है और यह एक dedicated file है जिसमें AI coding agents के लिए प्रोजेक्ट पर काम करते समय ज़रूरी context और instructions रखे जाते हैं
- 20,000 से अधिक open source projects में इसका उपयोग हो रहा है, जहाँ build/test/code style जैसी ऐसी जानकारी व्यवस्थित की जाती है जो इंसानों के लिए अनावश्यक हो सकती है, लेकिन agents के लिए महत्वपूर्ण होती है
- स्पष्ट और अनुमानित location पर agent-specific instructions देकर README को संक्षिप्त रखा जा सकता है और साथ ही collaboration efficiency भी बढ़ती है
- एक ही AGENTS.md कई agents और tools के साथ compatible है, और बड़े monorepo में subproject-वार अलग AGENTS.md का उपयोग किया जा सकता है
- OpenAI Codex, Cursor, Google Jules आदि कई ecosystems के सहयोग से बना एक open standard
Why AGENTS.md?
- README.md इंसानों के लिए documentation है, जो quick start, project description और contribution guidelines देता है
- AGENTS.md agents के लिए एक सहायक document है, जो build/test/code rules जैसे detailed context को रखता है ताकि README जटिल न बने
- इसे अलग file में रखने के कारण
- agents के संदर्भ के लिए instructions का एक predictable location देना
- README को human contributors-केंद्रित और संक्षिप्त बनाए रखना
- मौजूदा documentation को पूरक करने वाली precise agent-specific instructions देना
- proprietary format की जगह ऐसा open standard नाम अपनाया गया है जिसे कोई भी उपयोग कर सके
- एक AGENTS.md के साथ कई AI coding agents और tools के साथ compatibility संभव है
How to use AGENTS.md?
- 1. AGENTS.md file बनाएं
- इसे repository root में रखें (कई agents auto-generation को support करते हैं)
- 2. मुख्य sections लिखें
- project overview
- build और test commands
- code style guidelines
- testing method
- security considerations
- 3. अतिरिक्त instructions शामिल करें
- commit/PR rules, security precautions, large datasets, deployment steps आदि, यानी वे बातें जो टीम सदस्यों तक पहुँचानी हों
- 4. monorepo support
- हर package के लिए अलग AGENTS.md रखा जा सकता है
- agents सबसे नज़दीकी file पढ़ते हैं और उसी subproject के अनुसार instructions का पालन करते हैं
- उदाहरण: OpenAI repository में 88 AGENTS.md मौजूद हैं
FAQ
- ज़रूरी sections: कोई नहीं, सामान्य Markdown format में स्वतंत्र रूप से लिखा जा सकता है
- conflict होने पर: सबसे नज़दीकी AGENTS.md को प्राथमिकता मिलती है, और user का explicit prompt अंतिम रूप से लागू होता है
- auto-execution: file में दिए गए test commands को agent चला सकता है और errors ठीक करने की कोशिश कर सकता है
- update की संभावना: इसे कभी भी बदला जा सकता है, इसलिए इसे living document की तरह manage किया जाता है
- मौजूदा documents का migration: filename बदलने के बाद symbolic link से compatibility बनाए रखी जा सकती है
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
1 टिप्पणियां
Hacker News की राय
छोटे प्रोजेक्ट्स के लिए एक
.mdफ़ाइल ही काफ़ी होती है, लेकिन जटिल प्रोजेक्ट्स में hierarchical folder structure औरindex.mdकहीं ज़्यादा प्रभावी साबित होते हैंindex.mdऔर उसके नीचेauth.md,performance.mdजैसी फ़ाइलों वाला ढाँचा maintain करना भी आसान होता है, और LLM या agent बिना बेकार token खर्च किए सिर्फ़ relevant context निकाल सकते हैं.docsफ़ाइलें इंसानों और LLM दोनों के लिए उपयुक्त बन जाती हैं, औरindex.mdमें हर फ़ाइल के लिए छोटा-सा मार्गदर्शन और organization guide भी शामिल किया जा सकता हैलेकिन
".agents"नाम की जगह".codebots"या".context"जैसे अधिक intuitive नाम बेहतर लगते हैंमुझे नहीं लगता कि महत्वपूर्ण फ़ाइलों और directories को बेवजह छिपाने की ज़रूरत है
ख़ासकर documentation को छिपाने से वह और opaque हो जाती है; शायद परंपरा की वजह से ऐसा होता है, लेकिन यह अच्छा pattern नहीं है
robot_docsजैसा नाम कैसा रहेगा, इस पर सोच रहा हूँअसल में ऐसी जानकारी contributors के सवालों से काफ़ी मेल खाती है, इसलिए मुझे लगता है कि इसे मूल रूप से
CONTRIBUTING.mdमें होना चाहिएयह structure इंसानों और robots दोनों के लिए software design/coding style guide documentation जैसा लगता है
मैं ऐसी
.mdफ़ाइलों कोdocs/folder में रखता हूँ, और Claude Code इन्हें सीधे लिखता हैAGENTS.mdऔरCLAUDE.mdसिर्फ़ robots के लिए होने चाहिए, और चाहे एक बड़ी फ़ाइल मेंh2headers से sections बाँटें या कई फ़ाइलों में विभाजित करें, दोनों के अपने फायदे-नुकसान हैंArc42 जैसा architecture documentation format भी है जो दोनों को support करता है
बड़ी Markdown फ़ाइल में किसी section को refer करने से अलग फ़ाइल बनाकर
@-mention करना आसान है और गलती भी कम होती हैजब किसी खास हिस्से पर focus चाहिए हो, तब छोटे फ़ाइलों में बाँटना code agent के लिए भी बेहतर होता है
छोटी फ़ाइलें
diff/PR review के समय भी ज़्यादा सुविधाजनक होती हैंcodebase के अंदर कई
AGENTS.mdफ़ाइलें भी रखी जा सकती हैंअगर tooling current directory और root directory दोनों की
AGENTS.mdपढ़े, तो जानकारी code के पास ही रह सकती है, इसलिए यह मनचाहे तरीके के साथ-साथ चल सकता हैमैं भी मिलती-जुलती structure इस्तेमाल कर रहा हूँ, और
index.mdमें हर फ़ाइल के लिए छोटा guide जोड़कर काफ़ी अच्छे नतीजे मिले हैंrules.mdजैसे directory-specific behavior rules फ़ाइल रखने के तरीके पर भी प्रयोग कर रहा हूँउदाहरण के लिए,
realtime-service.tsऔरqueue-service.tsजैसी अलग-अलग services वाले directory में उसके बगल मेंrules.mdरखा जा सकता हैprompt में इस rules फ़ाइल को specify करके नई चीज़ें आसानी से बनवाई जा सकती हैं, बस नाम पर अभी और सोचना है
अभी हम एक transitional phase में हैं, जहाँ agent को codebase समझाने के लिए इंसानों की ज़रूरत से भी ज़्यादा अतिरिक्त guides लिखनी पड़ रही हैं
मुझे लगता है जल्द ही इसकी ज़रूरत नहीं रहेगी
अगर हमारे project docs शुरू से ही काफ़ी अच्छे और पर्याप्त हों, तो
AGENTS.mdकी सारी बातें भी उनमें शामिल हो सकती हैंहमें हमेशा documentation इंसानों के लिए लिखनी चाहिए, और LLM की ताकत यही है कि वह इंसानों द्वारा लिखी बात पढ़ सकता है
मुझे लगता है कि design भी इसी नज़रिए से होना चाहिए
यह सिर्फ़ codebase समझने तक सीमित नहीं है, बल्कि किसी खास style को define करने में भी बहुत काम का है, जैसे किस assert library से tests लिखने हैं, comments नहीं करने, structured logging इस्तेमाल करनी है, वगैरह
बल्कि यह लगभग बिना code वाले नए project में और ज़्यादा उपयोगी हो सकता है
मुझे लगता है machine-readable rules समाज के कई हिस्सों में और ज़्यादा आएँगे
उदाहरण के लिए autonomous driving और traffic laws को लें; ऐसे signs जिन्हें इंसान भी context के बिना मुश्किल से समझते हैं, जैसे
"लाल बत्ती पर दाएँ मुड़ना मना, school days 7~9 बजे", मशीनों के लिए और भी कठिन हैंआख़िरकार प्रशासनिक संस्थाओं को ऐसे संकेत बनाने होंगे जिनमें कम context चाहिए, या जिनमें machine readability हो, जैसे QR codes
अगर ऐसा बदलाव नहीं हुआ, तो machines नियम और ज़्यादा तोड़ेंगी
business logic जैसे क्षेत्रों में मुझे लगता है कि आगे भी agents के लिए खास मार्गदर्शन ज़रूरी रहेगा
क्या बनाया जा रहा है, उसका इरादा क्या है, project का अंतिम उद्देश्य क्या है—ये सब मशीन खुद नहीं समझ सकती जब तक इंसान साफ़ तौर पर न बताए
architecture जैसी चीज़ों में भी हर व्यक्ति के मानदंड अलग होते हैं, और दिमाग़ में एक स्पष्ट संरचना हो तो असली बदलावों को समझने में मदद मिलती है; आख़िरकार असली bottleneck यही हिस्सा है
कुल मिलाकर मैं सहमत हूँ, लेकिन कुछ जानकारी ऐसी होती है जिसे हर बार context में ज़रूर शामिल करवाने का मन करता है, इसलिए उसे अलग फ़ाइल में force-include करने की इच्छा भी होती है
जिन नियमों और assumptions को हम implicit मान लेते हैं, LLM उन्हें नहीं जान सकता
वह code से कुछ infer कर सकता है, लेकिन 100% नहीं, इसलिए requirements को साफ़-साफ़ लिखकर रखना ज़रूरी है
AGENTS.mdअसल मेंREADME.mdजैसा ही काम करता है, लेकिन hype की वजह से लोग उसमें सचमुच content भर रहे हैं—यह बात दिलचस्प लगती हैलोग दूसरे इंसानों के लिए documentation लिखने में आलस करते हैं, लेकिन robots के लिए बड़े मन से लिख रहे हैं, यह काफ़ी रोचक है
यह कुछ वैसा है जैसे किसी minority के लिए ergonomic design बनाया जाए, और अंत में वह सभी के लिए बेहतर handle design साबित हो
बल्कि उल्टा देखें तो, लोग docs पढ़ते ही नहीं थे, इसलिए किसी के पास उन्हें लिखने की motivation ही नहीं थी
agent के लिए
CLAUDE.mdएक बार लिख दो, तो उसे 1000 agents जल्द ही पढ़ लेंगे—तब लिखने का मन बनता हैक्या
README.mdमें बस minimum बातें लिख देना काफ़ी नहीं होना चाहिए?असलियत में तो agents भी अक्सर यह document नहीं पढ़ते, या दो-तीन अतिरिक्त निर्देश मिलने पर सब भूल जाते हैं
मौजूदा हालात में लोग मानव developers (खुद को भी शामिल करके) को development process से सक्रिय रूप से हटाने की कोशिश कर रहे हैं, और इसी वजह से agents के पास सही guidance होना ज़रूरी बन गया है
क्योंकि human involvement को software development से लगभग हटाने की इच्छा बढ़ गई है
मज़ाक में कहा जाए तो आजकल माहौल ही vibe coding का है
ऐसा भी लगता है कि bots के लिए docs लिखना, आखिरकार अच्छी documentation लिखने से अलग नहीं है—शायद पहले भी ऐसी राय आई थी
अंत में एहसास यही होता है कि बस
"AGENTS.md फ़ाइल बनाइए और उसमें जादू भर दीजिए"लिख दिया गया है, और फिर किसी वेबसाइट की लिंक दे दी जाती हैमेरे मामले में, मैं 5,000 से ज़्यादा repositories manage करने वाले coding agent पर काम कर रहा हूँ
agent की state hidden
.agentdirectory में store होती है, जिसमें हर agent role के लिए config folders और साफ़ role-specific instructions शामिल होते हैंproject folder में
agentsनाम का folder रखा जाता है, और कई फ़ाइलों को role के हिसाब से बाँटकर<Role> <instruction>शैली में manage किया जाता हैagent सिर्फ़ वही फ़ाइलें पढ़ता है जिनमें role define हो, और state
dot<coding agent name>folder में रखी जाती हैinitialization
/initसे होती है, और पूरे repo code को सिर्फ़ index करने के बजाय यह पूरे architecture और logic का high-level summary बनाता हैयह summary editor के अंदर toggle होने वाले
"ghost comments"के रूप में दी जाती है, और यह असली code में commit नहीं होने वाला metadata हैएक sophisticated mapping system के ज़रिए हर summary को code lines से सटीक रूप से जोड़ा जाता है
शुरुआत में जब मैंने सीधे code पर RAG इस्तेमाल किया, तो मनचाहे नतीजे नहीं मिले, इसलिए यह structure अपनाई
अब मैं AST-based तेज़ syntactic search और summaries पर आधारित semantic exploration (RAG) को मिलाकर hybrid search model इस्तेमाल करता हूँ
उदाहरण के लिए, अगर पूछा जाए
"इस app का authentication कैसे काम करता है?", तो syntactic search सिर्फ़loginजैसे शब्द वाले functions खोजेगी, लेकिन semantic search summaries के ज़रिए पूरे authentication flow को narrative की तरह समझकर अलग-अलग फ़ाइलों में फैली बातों को जोड़ देती है—और यह लगभग जादू जैसा काम करता हैइसके ऊपर summaries की hierarchical structure भी बनाई जा सकती है, B-tree या सामान्य tree के रूप में
यानी method/class/module स्तर पर summary हो, और हर स्तर नीचे वाले स्तर की ओर इशारा करे
RAG semantic query के हिसाब से जितनी ज़रूरत हो उतनी depth तक जा सकता है, और हर चरण नीचे की सामग्री को summarize करके information कम करता है, लेकिन आवश्यक अर्थ बनाए रखता है
यह तरीका खास तौर पर तब प्रभावी होता है जब code की abstraction अच्छी तरह की गई हो
उदाहरण के लिए,
add(n1, n2)जैसे function में नाम से ही अर्थ स्पष्ट हो जाता है, इसलिए implementation देखना ज़रूरी नहीं; लेकिन वास्तविक दुनिया के functions अक्सर logging, cache जैसी कई भूमिकाएँ निभाते हैं, इसलिए संदर्भ के अनुसार असली code भी context में लाना पड़ सकता हैइसके बारे में और विस्तार से सुनना चाहूँगा
ऐसा लगता है कि इंसानों को धीरे-धीरे proper project documentation लिखने के लिए धकेला जा रहा है
मज़ाक है, लेकिन मैं सच में अपनी टीम से यही बात कहता हूँ
भले ही LLM वास्तव में productivity को बहुत ज़्यादा न बढ़ाए, इसका एक असर यह ज़रूर है कि documentation कहीं बेहतर हो जाती है
"Mission. Fucking. Accomplished."xkcd 810मुझे अभी भी यक़ीन नहीं है कि
README.mdऔरAGENTS.mdको अलग रखना वाकई ज़रूरी हैइस संबंधित लेख के मुताबिक,
अलग रखने के कारण हैं
अलग न रखने का कारण है
README.mdअब कुछ हद तक marketing/landing page जैसा लगता है, जबकिAGENTS.mdऔरCLAUDE.mdवह जगह हैं जहाँ code, architecture और usage की असली जानकारी मिलती हैउदाहरण पढ़ते समय मेरे मन में भी यही बात आई; क्या एक अच्छी
README.mdमें सब कुछ होना काफ़ी नहीं होना चाहिए?READMEइंसानों के लिए है,AGENTS.mdवगैरह LLM के लिएusage/install instructions readme में, और compile/test methods, architecture decisions, coding standards, repo structure जैसी चीज़ें agent docs में रखी जाती हैं
LLM के context capacity issue पर भी ध्यान देना पड़ता है
README.mdकाफ़ी लंबा हो सकता है, इसलिए उसे पूरा context में डालना मुश्किल हैAGENT.mdमें सिर्फ़ वही ज़रूरी चीज़ें, जैसे test और build commands, संक्षेप में रखी जाती हैं जो LLM के लिए आवश्यक होंहो सकता है README से कुछ overlap हो, लेकिन हम नहीं चाहेंगे कि बेकार की चीज़ें बार-बार context में भेजी जाएँ
क्या AI का वादा यही नहीं था कि हमें किसी exact format पर ज़ोर देने की ज़रूरत नहीं होगी, और हम जैसे चाहें लिखेंगे, मशीन खुद समझ जाएगी?
असल में सही चुनाव यही था कि सिर्फ़ filename standardize किया जाए, content format को नहीं; कोई भी अपनी पसंद के हिसाब से लिख सके
AGENTS.mdstandard Markdown है, इसलिए आप जो heading चाहें इस्तेमाल कर सकते हैं, और agent text को parse कर लेता हैफिर भी कुछ हद तक structure और format की अहमियत रहती है
भले ही वह exact code syntax जितनी सख़्त न हो
अंत में निष्कर्ष यही है कि content को स्पष्ट लिखना ज़रूरी है
जैसे-जैसे document लंबा होता है, structured approach इंसानों के लिए maintenance में ज़्यादा फायदेमंद हो जाती है
हर इस्तेमाल होने वाले agent (
Claude Code,Gemini,Aider) का filename अलग हैअगर standardization हो जाए तो अच्छा होगा, लेकिन अभी मैं
rulerसे कई formats auto-generate करने की मेहनत कर रहा हूँख़ासकर क्योंकि हर agent MCP config files को consume करने का तरीका भी अलग रखता है, इसलिए मुझे नहीं लगता कि standardization अभी तुरंत होगी
rulerथोड़ा cynical नज़रिए से देखें तो यह vendor lock-in बनाने की कोशिश भी लगती है
standardization का मतलब commoditization भी हो सकता है, और शायद कंपनियाँ इसी वजह से इससे बचती हैं
Jules
AGENTS.mdका इस्तेमाल करता है, जिससे दिखता है कि Google इस standard में शामिल हो रहा हैअगर
Gemini Code Assistबना रहता है, तो शायद वह भीAGENTS.mdsupport करेगाAiderdocs में मुझे कोई specific filename नहीं दिखा; अगर कोई लिंक हो तो जानना चाहूँगालगता है Anthropic ही एकमात्र कंपनी है जो अभी तक standard filename support नहीं करती
यह थोड़ा अफ़सोस की बात है कि
rulerजैसे tool की सचमुच ज़रूरत पड़ती हैयह वेबसाइट कुछ अजीब लगती है
क्या यह OpenAI ने traffic खींचने और marketing positioning के लिए बनाई है?
असलियत में इसमें format कुछ नहीं, सिर्फ़ filename तय है
Anthropic/Claude का ग़ैरमौजूद होना भी ध्यान खींचता है; हालांकि symbolic link के ज़रिए
CLAUDE.mdकोAGENTS.mdसे जोड़ना संभव हैअसल में इसे sourcegraph ने बनाया था, और यह मई से मौजूद है
पहले यह
agent.mdथा, अबagents.mdपर 301 redirect होता हैपुराना लिंक देखें
आधिकारिक घोषणा भी है
लगता है हाल ही में OpenAI के साथ partnership हुई है
दिलचस्प बात यह है कि शुरुआत में
agent.mdथा, लेकिन अबagents.mdहो गया हैClaude के list में न होने की वजह यही है कि अभी सिर्फ़ Claude standard filename convention support नहीं करता