/init से AGENTS.md अपने-आप मत बनाइए — इससे उल्टा सिर्फ़ 20% ज़्यादा लागत बढ़ती है

मुख्य दावे

• AI coding agent के लिए context file (AGENTS.md) को /init कमांड से auto-generate करने पर agent की performance उल्टा गिरती है और लागत 20% से अधिक बढ़ती है
• असली समस्या यह है कि agent खुद जिन जानकारियों को ढूंढ सकता है, वही उसे दोबारा दी जाती हैं
• AGENTS.md में सिर्फ़ वही जानकारी होनी चाहिए जो agent code पढ़कर नहीं जान सकता

शोध के नतीजे: AGENTS.md मददगार है या नुकसानदेह

• Lulla et al. (ICSE JAWs 2026): GitHub PR के 124 मामलों पर paired experiment किया गया, जिसमें सिर्फ़ AGENTS.md की मौजूदगी/अनुपस्थिति बदली गई
  • AGENTS.md होने पर execution time 28.64% कम हुआ, output token 16.58% कम हुए
  • इस अध्ययन में इस्तेमाल की गई file को developers वास्तव में maintain कर रहे थे, और उसमें project-specific knowledge शामिल थी
• ETH Zurich शोध: 4 agents को SWE-bench आदि पर test किया गया, और LLM द्वारा auto-generated file तथा developer द्वारा लिखी गई file में फ़र्क रखा गया
  • LLM द्वारा auto-generated context: task success rate 2~3% घटी, लागत 20%+ बढ़ी
    • README जैसी मौजूदा docs पूरी तरह हटा दी गई environment में LLM-generated file ने उल्टा performance 2.7% बढ़ाई
  • Developer द्वारा सीधे लिखी गई file: success rate लगभग 4% बढ़ी, लागत अधिकतम 19% बढ़ी
• निष्कर्ष: auto-generated content का बुरा होना समस्या नहीं, duplication ही असली समस्या है
  • वही जानकारी दो बार देने से सिर्फ़ noise बढ़ता है, और developer द्वारा दी गई ऐसी knowledge जो agent खुद discover नहीं कर सकता वही वास्तव में मदद करती है

auto-generation नुकसानदायक क्यों है

• auto-generated AGENTS.md में अधिकतर वही जानकारी होती है जिसे agent पहले से खुद खोज लेता है
  • codebase overview (Sonnet 4.5 output के 100%, GPT-5.2 output के 99% में यह शामिल था)
  • directory structure, tech stack, module description
• जो जानकारी पहले से पता है, उसे दोबारा देने से सिर्फ़ token खर्च होते हैं और कोई value नहीं मिलती
• Anchoring effect: अगर legacy pattern का ज़िक्र कर दिया जाए, तो बेहतर विकल्प मौजूद होने पर भी agent उसी pattern में अटक सकता है
  • यह "Lost in the Middle" शोध (Liu et al., 2024) से मेल खाता है — लंबा context attention बिखेरता है और performance घटाता है

AGENTS.md में क्या होना चाहिए और क्या नहीं

• क्या होना चाहिए (ऐसी जानकारी जो agent discover नहीं कर सकता)
  • tool specification: "package management के लिए uv इस्तेमाल करें"
  • non-intuitive rule: "tests हमेशा --no-cache के साथ चलाएँ, नहीं तो fixture false positive देगा"
  • system constraint: "auth module custom middleware पर चलता है, इसे standard Express में refactor न करें"
  • अगर किसी tool का docs में ज़िक्र हो, तो agent उसे प्रति task 1.6~2.5 बार इस्तेमाल करता है; undocumented होने पर यह 0.05 बार से भी कम रह जाता है
• क्या नहीं होना चाहिए (जिसे agent खुद discover कर सकता है)
  • directory structure, monorepo layout
  • tech stack overview, standard architecture pattern

static file की संरचनात्मक सीमाएँ

• अच्छी तरह लिखी गई AGENTS.md में भी एक बुनियादी कमजोरी है — file static है, लेकिन task dynamic है
• एक single file के निर्देश task type के हिसाब से conditional branching नहीं कर सकते
  • documentation edit task पर भी "commit से पहले पूरे tests चलाओ" जैसा निर्देश लागू हो जाता है, जिससे token और समय बर्बाद होते हैं
  • CSS refactoring में DB migration warning लोड हो जाती है, और security fix के साथ performance optimization hint जुड़ जाती है
• ACE framework (ICLR 2026): static file के बजाय generator/reflector/curator pipeline से context को dynamically evolve करने वाला Agentic Context Engineering, static तरीकों की तुलना में 12.3% बेहतर performance दिखाता है

बेहतर संरचना, जो अभी बनी नहीं है

• AGENTS.md को लेकर कई लोग अलग-अलग होकर भी एक ही निष्कर्ष पर पहुँचे
  • single file नहीं, बल्कि routing layer + ज़रूरत पड़ने पर load होने वाला focused context सही संरचना है
• Layer 1 - protocol file: codebase overview या style guide नहीं, बल्कि routing document
  • उपलब्ध persona और उन्हें कब बुलाना है, skill और task type, MCP connection और उसके उपयोग को define करे
  • इसमें सिर्फ़ repo के वही न्यूनतम तथ्य हों जिन्हें agent discover नहीं कर सकता; इसके अलावा कुछ नहीं
• Layer 2 - persona/skill file: task type के अनुसार selectively load हो
  • UX agent और backend agent अलग context load करें, और एक-दूसरे का context load न करें
• Layer 3 - maintenance sub-agent: protocol file की accuracy बनाए रखने वाला dedicated agent
  • documents सड़ते हैं — ETH Zurich के शोध में बिल्कुल नई बनी files पर भी performance में गिरावट दिखी
  • अगर 6 महीने से untouched AGENTS.md ऐसे dependency या directory structure का वर्णन कर रही हो जो पहले ही बदल चुके हों, तो स्थिति और गंभीर होगी
• अभी किसी बड़े coding agent में ऐसे lifecycle hooks नहीं हैं जिनसे इस architecture को आसानी से लागू किया जा सके — sub-agent और scoped context से इसका approximation किया जा सकता है, लेकिन यह tool gap अभी भी भरा नहीं गया है

automatic optimization

• Arize AI CLAUDE.md instructions को हाथ से लिखने के बजाय automatic optimization loop का इस्तेमाल करता है
  • agent को training tasks पर चलाना → result evaluate करना → failure cause पर LLM feedback बनाना → meta-prompting से instructions सुधारना → फिर दोहराना
  • cross-repo test में +5.19%, in-repo test में +10.87% accuracy improvement
• optimizer ने एक असहज सच उजागर किया: जो चीज़ इंसानों को codebase समझने में मदद करती है, वह ज़रूरी नहीं कि LLM को navigation में मदद करे
  • "यह service repository pattern इस्तेमाल करती है" जैसी जानकारी developer को स्वाभाविक रूप से उपयोगी लग सकती है, लेकिन model के लिए noise हो सकती है
  • उल्टा, model को जिन चीज़ों की सच में ज़रूरत होती है (जैसे specific import path का फ़र्क, non-intuitive file naming rule), वे developer अक्सर पहले से internalize कर चुका होता है और लिखने का सोचता भी नहीं
• AGENTS.md को manually लिखना यह मानकर चलता है कि developer जानता है कि agent को क्या चाहिए
  • अनुभवजन्य सबूत बताते हैं कि शायद ऐसा नहीं है
  • optimizer "जो महत्वपूर्ण लगता है" और "जो वास्तव में परिणाम बदलता है" के बीच का फ़र्क पकड़ लेता है
• इसका मतलब यह नहीं कि लिखना छोड़ दें — 5% improvement मायने रखती है, लेकिन यह transformative नहीं है। intuition पर ढीली पकड़ रखें और सच में test करें

AGENTS.md को देखने का सही mindset

• AGENTS.md को ऐसी प्रक्रिया का रिकॉर्ड मानें जिसे अभी तक ठीक नहीं किया गया है
• आप जो भी नई line जोड़ते हैं, वह इस बात का संकेत है कि codebase में कहीं न कहीं इतनी अस्पष्टता है कि AI agent भ्रमित हो सकता है — और संभव है कि नए human contributors भी उसी में उलझें
• सही जवाब context file को बड़ा करना नहीं, बल्कि root cause को ठीक करना है
  • agent utility को गलत directory में रख देता है → मतलब directory structure ही confusing है, उसे reorganize करें
  • agent बार-बार deprecated dependency इस्तेमाल करता है → मतलब import structure उसे ऐसा करने के लिए बहुत आसान बना रही है, उसे ठीक करें
  • agent type check छोड़ देता है → instructions पर निर्भर न रहें, उसे build pipeline में अपने-आप enforce करें
• AGENTS.md permanent setting नहीं, diagnostic tool है — एक line जोड़ें, जाँचें कि agent यह गलती बार-बार क्यों कर रहा है, root cause ठीक करें, फिर वह line हटा दें
• एक उपयोगी तरीका: लगभग खाली AGENTS.md से शुरू करें और सिर्फ़ यह instruction दें — "अगर इस project में कुछ surprising या confusing मिले, तो comment छोड़ो"। agent जिन additions का सुझाव देगा, उनमें से अधिकतर permanent रखने के लिए नहीं, बल्कि codebase की अस्पष्ट जगहों के संकेत होंगे

व्यावहारिक सिफ़ारिशें

• /init चलाना बंद करें — जब तक repo में docs बिल्कुल न हों, auto-generated output मौजूदा docs की duplication ही होगा
• AGENTS.md में एक line जोड़ने से पहले खुद से पूछें: "क्या agent यह code पढ़कर जान सकता है?" अगर हाँ, तो उसे मत लिखिए
• अगर agent बार-बार fail हो रहा है, तो context file बढ़ाने से पहले पहले codebase को ठीक करें
  • code structure सुधारें, linter rule जोड़ें, test coverage बढ़ाएँ — और फिर भी काम न बने, तभी AGENTS.md को छुएँ
• अगर आप CI/CD या automatic review pipeline में बड़े पैमाने पर agents चला रहे हैं, तो समझें कि 15~20% cost overhead हज़ारों runs में compound होकर जमा होता है
• agent को नए employee की तरह onboard करने की प्रवृत्ति (office tour, org chart, architecture समझाना) स्वाभाविक है, लेकिन coding agent नया employee नहीं है — वह prompt पूरा टाइप होने से पहले ही पूरे codebase पर grep चला सकता है। agent को नक्शे की नहीं, बारूदी सुरंगों की लोकेशन की ज़रूरत है

[lloydkwon]

आखिरकार बात context की लड़ाई ही है, ऐसा कहते थे...
मुझे लगता है कि agent के लिए md और user के लिए md अलग-अलग बनवाना चाहिए, है न?

[lukeio]

मैं पूरी तरह सहमत हूँ। इंसानों के लिए पढ़ने में आसान संरचना (README) और LLM के लिए parse करने में आसान संरचना (AGENTS.md) पूरी तरह अलग होती हैं। बिना सोचे-समझे पूरा context अपने-आप generate करके दे देने से सिर्फ API token cost बर्बाद होती है, और उल्टा hallucination की समस्या ही ज़्यादा बढ़ती है—ऐसा मैंने अक्सर अनुभव किया है। आखिरकार, भले ही यह झंझट वाला लगे, agent के लिए निर्देश-पत्र को इंसान द्वारा सीधे compress और refine करना ही सबसे efficient लगता है।

[sonnet]

आदि में README था, और agents के लिए बनाया गया README ही AGENTS.md है।

[jaehar16]

लेकिन उसके लिए पहले से ही README नहीं है क्या?

[armila]

लेकिन मॉडल खुद कुछ ही महीनों में बदल जाता है
और मॉडल के हिसाब से agents को भी संशोधित करना पड़ता है...
क्या सही agents संरचना बनाने में लगने वाले समय से भी ज़्यादा तेज़ मॉडल का बदलाव नहीं हो रहा है?
यानी इंसान के किसी टूल का अभ्यस्त होने से पहले ही वह टूल बदल जाता है...

[jjw9512151]

आख़िरकार लगता है कि सबसे ज़रूरी बात context को साफ़-सुथरा और कम tokens में बनाए रखना है.. इस नज़रिए से देखें तो Chinese characters काफ़ी उपयोगी लगते हैं. हाहा

[aliveornot]

मॉडल के लिए अंग्रेज़ी तो पहले ही लगभग ऐसी है कि 1 शब्द = 1 अक्षर (token), तो क्या वह व्यावहारिक रूप से hanja जैसी नहीं है?

[eususu]

ओह, मैंने इस तरह का तरीका नहीं सोचा था, लेकिन इसमें वाजिब बात लगती है!

[t7vonn]

ओ ..