AGENTS.md ने एजेंट मूल्यांकन में skills की तुलना में बेहतर प्रदर्शन दिखाया

• Next.js 16 API पर किए गए मूल्यांकन में, प्रोजेक्ट रूट में शामिल AGENTS.md document index ने skills-आधारित approach की तुलना में अधिक accuracy दर्ज की
• skills एक domain knowledge package के रूप में काम करते हैं, जिसे एजेंट ज़रूरत पड़ने पर call करता है, लेकिन call की अस्थिरता के कारण default setting में pass rate सिर्फ 53% रहा
• इसके विपरीत, 8KB में compressed AGENTS.md index ने सभी tests (Build, Lint, Test) में 100% pass rate हासिल किया
• यह तरीका decision points हटाने, हमेशा उपलब्ध रहने, और ordering issues खत्म करने की वजह से proactive calling की तुलना में अधिक stable परिणाम दिखाता है
• framework maintainers version-matched document index को AGENTS.md में शामिल करके code generation accuracy बढ़ा सकते हैं

---

समस्या की पृष्ठभूमि

• AI coding agents की एक सीमा यह है कि training data अक्सर पुराने API versions पर आधारित होता है, इसलिए वे latest framework को ठीक से handle नहीं कर पाते
  • Next.js 16 के 'use cache', connection(), forbidden() जैसे फीचर्स मौजूदा model training data में मौजूद नहीं हैं
• दूसरी ओर, पुराने version वाले projects में model ऐसे नए API सुझा देता है जो वास्तव में मौजूद नहीं होते
• इस समस्या को हल करने के लिए version-matched documentation access approach का प्रयोग किया गया

दो तरीके

• Skills: prompts, tools और documents को जोड़ने वाला open standard package, जिसे एजेंट ज़रूरत पड़ने पर call करके इस्तेमाल करता है
• AGENTS.md: project root में रखा गया persistent context file, जिसे हर conversation turn में हमेशा refer किया जा सकता है
• एक ही Next.js documentation के आधार पर दोनों तरीकों का तुलनात्मक मूल्यांकन किया गया

Skills approach की सीमाएँ

• मूल्यांकन में पाया गया कि 56% tests में skill call ही नहीं हुआ, और baseline pass rate 53% ही रहा, यानी कोई सुधार नहीं
• कुछ मामलों में तो score baseline से भी कम रहा (जैसे test 58% vs 63%)
• इसे इस बात की सीमा के रूप में देखा गया कि मौजूदा models tool use को स्थिर रूप से execute नहीं कर पाते

explicit instruction जोड़ने का प्रयोग

• जब AGENTS.md में यह explicit instruction जोड़ा गया कि “code लिखने से पहले skill call करो”, तो pass rate 79% तक बढ़ गया
• लेकिन instruction की wording में छोटे अंतर ने परिणामों पर बड़ा असर डाला
  • “पहले skill call करो” → documentation pattern पर अटक गया, project context छूट गया
  • “project explore करने के बाद skill call करो” → बेहतर परिणाम
• इस तरह की linguistic fragility की वजह से real-world use में reliability कम मानी गई

भरोसेमंद evaluation बनाना

• शुरुआती tests में vague prompts और duplicate verification issues के कारण reliability कम थी
• इसे सुधारकर behavior-based verification और Next.js 16 के untrained APIs पर केंद्रित tests तैयार किए गए
• प्रमुख test APIs: connection(), 'use cache', cacheLife(), forbidden(), proxy.ts, cookies(), headers(), after(), refresh() आदि

AGENTS.md approach का प्रयोग

• एजेंट की selection process को हटाकर document index को सीधे AGENTS.md में insert किया गया
• index में पूरी documentation नहीं, बल्कि version-specific document paths की सूची शामिल थी
• अतिरिक्त instruction:
  IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.
  • इससे model को existing training data के बजाय documentation-based reasoning को प्राथमिकता देने के लिए प्रेरित किया गया

मूल्यांकन परिणाम

• AGENTS.md index insert करने पर 100% pass rate हासिल हुआ
  • Build, Lint, Test तीनों में perfect result
• तुलना के आँकड़े:
  • Baseline 53%, Skill default 53%, Skill+instruction 79%, AGENTS.md 100%
• passive context approach, active calling से बेहतर क्यों रही
  1. कोई decision point नहीं — जानकारी हमेशा मौजूद रहती है
  2. consistent availability — हर turn में system prompt का हिस्सा
  3. ordering issue खत्म — documentation exploration order पर निर्भरता नहीं

context capacity समस्या का समाधान

• शुरुआती index 40KB का था, लेकिन compression के बाद यह 8KB रह गया (80% कमी)
• pipe(|) separated structure के जरिए document paths और filenames को न्यूनतम जगह में store किया गया
• एजेंट .next-docs/ directory से ज़रूरत की files पढ़कर सही version information का उपयोग करता है

इसे लागू करने का तरीका

• एक line command से setup किया जा सकता है

  npx @next/codemod@canary agents-md
  

• यह command:
  1. Next.js version detect करती है
  2. उस version की documentation को .next-docs/ में download करती है
  3. compressed index को AGENTS.md में insert करती है
• Cursor जैसे AGENTS.md को पहचानने वाले agents में भी यह समान रूप से काम करता है

framework developers के लिए संकेत

• Skills अब भी उपयोगी हैं, लेकिन सामान्य code generation accuracy सुधारने में AGENTS.md approach अधिक प्रभावी दिखी
• Skills, “version upgrade”, “App Router migration” जैसे specific task-centric workflows के लिए अधिक उपयुक्त हैं
• सुझाव:
  • skills के बेहतर होने का इंतज़ार न करें, तुरंत AGENTS.md का उपयोग करें
  • context को छोटा रखने के लिए सिर्फ document index शामिल करें
  • training data में न होने वाले APIs पर केंद्रित evaluation से validate करें
  • documents को fine-grained retrieval structure के साथ design करें
• लक्ष्य है pre-training-centric reasoning से retrieval-based reasoning की ओर बदलाव, और
  AGENTS.md इसे सबसे स्थिर तरीके से लागू करने का माध्यम है