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

(vercel.com)

15 पॉइंट द्वारा GN⁺ 2026-01-31 | 4 टिप्पणियां | WhatsApp पर शेयर करें

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 इसे सबसे स्थिर तरीके से लागू करने का माध्यम है

4 टिप्पणियां

channprj 2026-01-31

AI कोडिंग एजेंट्स की एक सीमा यह है कि उनका training data पुराने API versions पर आधारित होता है, इसलिए वे नए frameworks को ठीक से handle नहीं कर पाते।

Context7 का इस्तेमाल करने पर ऊपर की समस्या कुछ हद तक हल हो जाती है।

https://context7.com

slowandsnow 2026-02-04

context7 अक्षम है, इसलिए ऊपर बताए गए दो तरीकों का इस्तेमाल किया जाता है...

channprj 2026-02-05

मैं समझता हूँ कि आप क्या कहना चाहते हैं, लेकिन फिर भी हर बार AGENTS.md या Skills में इस समय इस्तेमाल हो रहे सभी framework/library के latest documentation links को एक-एक करके व्यवस्थित करके जोड़ने से बेहतर, context7 को सहायक रूप में इस्तेमाल करना इतना बुरा विकल्प नहीं लगता।

साथ ही, GeekNews और Vercel दोनों के मूल लेख में context7 का कोई उल्लेख नहीं है। मुझे लगा कि आपने सामग्री का अर्थ लगभग आधा कदम आगे बढ़ाकर निकाला है, इसलिए यह जवाब छोड़ रहा हूँ।

(संदर्भ के लिए कहूँ तो, अच्छी तरह लिखे गए Skills और AGENTS.md से token की बचत हो सकती है, यह एक अच्छी तरह से ज्ञात तथ्य है, और मैं भी इसे अच्छी तरह जानता हूँ.)

GN⁺ 2026-01-31

Hacker News टिप्पणियाँ

मॉडल AGI नहीं है। यह सिर्फ एक text generator है, जिसे file editing या tool calling जैसे प्रभाव पैदा करने के लिए train किया गया है
मॉडल यूज़र के skills को “समझकर” इस्तेमाल नहीं करता, बल्कि इंसानों द्वारा बनाए गए उदाहरणों और usage logs पर आधारित reinforcement learning (RL) की वजह से ऐसा टेक्स्ट जनरेट करता है
skills को हमेशा इस्तेमाल न करने की वजह यह है कि ऐसे cases पर अभी पर्याप्त training नहीं हुई है। RL से इसे ज़बरदस्ती लागू करने पर मॉडल उल्टा और बेवकूफ हो सकता है
अभी हम skill usage logs जमा कर रहे हैं ताकि future models यह बेहतर सीख सकें कि skills कब इस्तेमाल करने चाहिए
AGENTS.md बस context है। मॉडल को शुरू से ही context follow करने के लिए train किया गया है
- AGENTS.md और skills के बीच का फ़र्क आखिरकार इस बात का है कि उन्हें context में कैसे inject किया जाता है
  skills का frontmatter भी आख़िरकार context में शामिल होता है, इसलिए अगर AGENTS.md बेहतर काम करता है तो वजह skill information को extract और inject करने के तरीके का फ़र्क है
  कुछ agents छोटे models (जैसे Haiku) का इस्तेमाल करके यह तय कर सकते हैं कि कौन-सी skill information बड़े models (जैसे Sonnet, Opus) तक पहुँचाई जाए
  आख़िरकार मुख्य बात यह है कि “raw prompt” में कौन-सी जानकारी जाती है
- AGI कहना सही नहीं है। यह असल में बेहतर किया गया autocomplete भर है
  उपयोगी है, लेकिन परफेक्ट नहीं। GPT तकनीक खुद शायद पहले ही performance plateau में पहुँच चुकी है
  आगे सुधार skills जैसे सहायक systems में होगा। लेकिन मौजूदा skill implementation, AGENTS.md को सीधे इस्तेमाल करने से कमज़ोर है
- मैंने भी ऐसा ही experiment किया है। system prompt में related skills को पहले से load कराया, और user prompt में ज़रूरत पड़ने पर load कराया — इसी तरह test कर रहा हूँ
- RL क्या है, इस पर भी सवाल आया था
- “मॉडल AGI नहीं है” वाली बात पर GNU/Linux naming controversy का उदाहरण देकर मज़ाकिया टिप्पणी भी थी
eval में यह नतीजा आया कि 56% मामलों में skills एक बार भी call नहीं हुए। यानी दस्तावेज़ मौजूद थे, लेकिन इस्तेमाल नहीं हुए। साथ में मज़ाक था: “ट्यूरिंग टेस्ट तो पास कर लिया…”
- इस पर चुटीला जवाब था: “AI भी RTFM (manual नहीं पढ़ता)”
- मुझे भी हँसी आई, लेकिन गंभीरता से कहें तो इंसान भी अक्सर भरोसेमंद नहीं होते
  फ़र्क बस इतना है कि AI बिना ego के correction instructions मान लेता है
  अभी senior developer स्तर का नहीं है, लेकिन junior से बेहतर तरीके से निर्देश मान लेता है
मुख्य खोज यह थी कि document pointers की compression असरदार है
इंसानों के लिए पढ़ना मुश्किल है, लेकिन LLM के लिए यह ज़्यादा direct और efficient reference structure है
आगे चलकर agents.md/claude.md/skills.md जैसी heuristics की जगह, हमेशा load होने वाला compressed index format standard बन सकता है
API test suites को LLM code performance validation में दोबारा इस्तेमाल किया जा सकता है
जैसे-जैसे LLM adoption बढ़ेगा, libraries और APIs को भी उसी हिसाब से evolve होना पड़ेगा
- एक और सबक यह था कि “पहले project explore करो, फिर skills call करो” तरीका, “हर हालत में skills इस्तेमाल करो” से बेहतर है
  Antigravity (=GEMINI.md आधारित) में AGENTS.md rules follow करने को कहा गया था, लेकिन उसे नज़रअंदाज़ कर दिया गया
  इसके बजाय “जाँचो कि project में AGENTS.md है या नहीं” वाला prompt हर बार काम करता था
  यह कुछ वैसा ही दिलचस्प phenomenon है जैसा पहले “let’s think step by step” chain of thought trigger करता था
- किसी ने कहा कि इसे “compression” कहना ज़्यादा है, यह तो लगभग minify जैसा ही है
- यह राय भी थी कि pipe की जगह line breaks इस्तेमाल किए जाते तो पढ़ना आसान होता
AGENTS.md को system prompt में सीधे शामिल कर दिया जाए तो वह हमेशा context में रहेगा
लेकिन हर बार सारे skills शामिल करना फिजूलखर्ची है। इसलिए Anthropic के advanced tool use जैसी approach चाहिए, जो ज़रूरत पड़ने पर ही उन्हें लाए
आख़िरकार यह context और cost के balance का सवाल है। जगह हो तो AGENTS.md में compress करके डालना efficient है
- skills भी आख़िरकार context के अंदर ही declare होते हैं। लगता है कि उन्हें AGENTS.md में compress करके डालना बेहतर काम करता है
- लगता है Vercel ने skills और context settings को गड़बड़ा दिया। दोनों के उद्देश्य बिल्कुल अलग हैं, इसलिए दोनों को साथ इस्तेमाल करना चाहिए
- RLM approach के अच्छी तरह काम करने की वजह भी यही है। ज़रूरी जानकारी context में रखो, बाकी environment में रहने दो
  ऐसे self-context-managing agents इस साल काफ़ी आगे बढ़ सकते हैं
- आख़िरकार दोनों चाहिए। कुछ चीज़ें ज़बरदस्ती context में डालनी होंगी (index/sparknotes), और कुछ को exploration/search के आधार पर dynamically जोड़ना होगा
- व्यक्तिगत उपयोगकर्ता सिर्फ system prompt बदलकर काम चला सकते हैं, लेकिन टीम स्तर पर code style जैसी standards के लिए skills चाहिए
  Claude की skill compliance कम है
मैं भी इसी तरह के क्षेत्र में काम कर रहा हूँ। मैं यह evaluate करना चाहता हूँ कि project scaffolding structure Claude Code/Opencode के results को कैसे प्रभावित करता है
लेकिन Vercel की testing method साफ़ नहीं है, इसलिए तुलना मुश्किल है
AGENTS.md skills से पूरी तरह अलग चीज़ नहीं है, बल्कि skills का simplified form है
मुख्य बात skill design quality है — यानी AI को सही जानकारी मिलने तक जिन steps से गुजरना पड़ता है, उनकी संख्या कम से कम हो
steps जितने कम होंगे, error accumulation उतना कम होगा
- मैं भी इसे दो हिस्सों में manage करता हूँ
  1. जो rules के आधार पर system prompt में force-insert होते हैं
  2. जिन्हें agent ज़रूरत पड़ने पर explore करता है
    और token waste कम करने के लिए, बड़ी files को system prompt में सिर्फ एक बार डालता हूँ
ब्लॉग में जब भी prompt engineering की तुलना की जाती है, मुझे हमेशा यह जिज्ञासा होती है कि इसे एक बार चलाया गया था या कई बार दोहराया गया था
LLM एक ही input पर भी हमेशा एक जैसा result नहीं देता
- ऐसे non-deterministic results को science की तरह पेश करना परेशान करता है
  ज़्यादातर यह anecdotal data को science की तरह पैक करने जैसा लगता है
- मैं भी हमेशा कई बार runs दोहराकर confidence interval निकालता हूँ
  लेकिन अगर benchmark ईमानदारी से किया जाए तो views कम मिलते हैं, और अगर बस ऊपर-ऊपर से किया जाए तो blog traffic 9 गुना बढ़ जाता है
  distorted incentive structure ही समस्या है
AGENTS.md से भी बेहतर एक तरीका हो सकता है
.context folder बनाइए, उसमें project-related documents (README, dependency docs आदि) को symbolic links के ज़रिए रखिए, और उन्हें हमेशा context में load होने दीजिए
इससे LLM के पास शुरू से ही ज़रूरी जानकारी रहेगी, और performance improvement व cost reduction दोनों मिल सकते हैं
- लेकिन dependency docs बड़ा फ़र्क नहीं लाते। इसके बजाय source code खुद को _vendor folder में रखना कहीं ज़्यादा उपयोगी है
  LLM सीधे code analyze करके behavior समझ सकता है
- हर बार सारे documents load करना inefficient है। इसके बजाय Claude.md या Agents.md में सिर्फ location लिख दी जाए और ज़रूरत पर पढ़ा जाए, ऐसा मत भी था
- context को बेवजह फुलाना नहीं चाहिए। इसके बजाय सिर्फ document index को compress करके डालना ज़्यादा efficient है
- बड़ी files हर बार डालना token waste है। Claude Code blog में भी यही चेतावनी थी
यह मेरा custom agent बनाते समय का अनुभव है
1. मैंने Claude Code की extraction instructions को reference किया
2. AGENTS.md को table of contents और summary (sparknotes) के लिए auto-load कराया
3. topic-wise Markdown files को skills की तरह manage किया
4. MCP और skills conceptually मिलते-जुलते हैं, इसलिए अच्छे tools बनाना ही मुख्य बात है
5. मैं लगातार experiment कर रहा हूँ, मज़े ले रहा हूँ, और सुधार कर रहा हूँ
  read/write_file को state में डालकर system prompt में दिखाया तो यह बहुत बेहतर काम करने लगा
  अब मैं इसे quantitative evals से साबित करने की कोशिश कर रहा हूँ। अनुभव के आधार पर performance बहुत अच्छी लग रही है