एक ऐसी AGENTS.md कैसे लिखें जो वास्तव में आपके AI कोडिंग एजेंट की मदद करे

अगर आपने किसी असली प्रोजेक्ट पर किसी AI कोडिंग एजेंट का उपयोग किया है, तो आपने शायद वह पल अनुभव किया होगा जहाँ यह गलत test कमांड चलाता है, आपके formatter को अनदेखा करता है, या आपके पास पहले से मौजूद किसी helper को फिर से ईजाद करता है। इसका इलाज आम तौर पर कोई होशियार मॉडल नहीं है — यह एजेंट को प्रोजेक्ट-विशिष्ट कॉन्टेक्स्ट देना है जिसका वह अनुमान नहीं लगा सकता। यही वह है जिसके लिए एक AGENTS.md फ़ाइल है।

AGENTS.md क्या है

AGENTS.md एक सरल, खुला Markdown फ़ॉर्मैट है जो कोडिंग एजेंटों को प्रोजेक्ट कॉन्टेक्स्ट और निर्देश खोजने के लिए एक पूर्वानुमेय जगह देता है। यह OpenAI Codex, Amp, Google Jules, Cursor, और Factory के बीच एक सहयोग के रूप में शुरू हुआ, और अब Linux Foundation के तहत Agentic AI Foundation द्वारा संचालित है। 25 से अधिक टूल इसे पढ़ते हैं — जिनमें Codex, Cursor, VS Code, GitHub Copilot, Aider, Windsurf, JetBrains Junie, Zed, और goose शामिल हैं — और यह 60,000 से अधिक ओपन-सोर्स रिपॉज़िटरीज़ में दिखाई देता है।

इसे एक README के रूप में सोचें जो किसी इंसान के बजाय एजेंट के लिए लिखा गया हो: README आपके प्रोजेक्ट को किसी नए योगदानकर्ता को समझाता है; AGENTS.md एजेंट को वे चीज़ें बताता है जिनका वह अन्यथा गलत अनुमान लगाता। (Claude Code उपयोगकर्ता CLAUDE.md को समतुल्य के रूप में पहचानेंगे; कई टीमें दोनों रखती हैं, या एक को दूसरे से symlink कर देती हैं।)

यह कहाँ जाती है

AGENTS.md को रिपॉज़िटरी रूट पर रखें। एक monorepo में, हर package के अंदर nested फ़ाइलें जोड़ें — एजेंट डायरेक्टरी ट्री में निकटतम फ़ाइल पढ़ते हैं, इसलिए जब एजेंट उस फ़ोल्डर में काम कर रहा हो तो एक packages/api/AGENTS.md रूट वाली पर प्राथमिकता पाती है। यह एक Python सेवा और एक TypeScript frontend को अनुरूप निर्देश पाने देता है।

इसमें क्या डालें

फ़ॉर्मैट बस Markdown है — जो भी headings आप पसंद करें उपयोग करें। आम तौर पर उपयोगी सेक्शनों में शामिल हैं:

• Build और test कमांड — सटीक कमांड, न कि अनुमान
• Code style — formatter, linter, और कोई परंपराएँ जो linter नहीं पकड़ेगा
• Testing निर्देश — एक अकेला test कैसे चलाएँ, किसी बदलाव के पूरा होने से पहले क्या पास होना चाहिए
• Security विचार — फ़ाइलें या ऑपरेशन जिन्हें कभी न छुएँ
• Commit / PR परंपराएँ — संदेश फ़ॉर्मैट, branch naming
• Deployment चरण — सिर्फ़ अगर एजेंट से उन्हें छूने की अपेक्षा हो

यहाँ एक न्यूनतम, उच्च-संकेत उदाहरण है:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (do NOT run in CI)
- Test a single file: `pnpm vitest run path/to/file.test.ts`
- Lint + typecheck before any commit: `pnpm check`

## Conventions
- Use the existing `db()` helper in `src/lib/db.ts`; never open a raw client.
- Dates are stored as UTC ISO strings. Never use `Date.now()` in tests.

## Do not touch
- `src/generated/**` is codegen output. Edit the schema, then run `pnpm gen`.

ध्यान दें कि वहाँ क्या नहीं है: कोई आर्किटेक्चर का व्याख्यान नहीं, फ़ोल्डर संरचना का कोई पुनः-कथन नहीं, कोई "यह सर्वोत्तम प्रथाओं के साथ बना एक आधुनिक वेब ऐप है" नहीं। यह जान-बूझकर है।

छोटा आम तौर पर बेहतर है

एजेंट से अपने लिए एक विशाल AGENTS.md जनरेट करवाने का लालच होता है। इसका विरोध करें। InfoQ द्वारा रिपोर्ट किए गए एक 2026 ETH Zurich अध्ययन ने इन फ़ाइलों के असली प्रभाव को मापा और पाया कि असर मामूली और मिश्रित है। LLM-जनरेट किए गए कॉन्टेक्स्ट फ़ाइलों ने वास्तव में task success rates को औसतन लगभग 3% घटा दिया जबकि inference लागत 20% से अधिक बढ़ा दी। इंसान-लिखित फ़ाइलों ने मामूली मदद की — सफलता में लगभग 4% वृद्धि — लेकिन फिर भी एजेंटों को अधिक कदम लेने पर धकेला, लागत ~19% तक बढ़ाते हुए।

तंत्र शिक्षाप्रद है: एजेंट कर्तव्यनिष्ठता से वही करते हैं जो फ़ाइल कहती है, इसलिए एक फैला हुआ दस्तावेज़ उन्हें अतिरिक्त test चलाने, अधिक फ़ाइलें पढ़ने, और हाथ के काम के लिए अनावश्यक गुणवत्ता जाँच करने को कहता है। शोधकर्ताओं की सिफ़ारिश: स्वतः-जनरेट किए गए कॉन्टेक्स्ट फ़ाइलों को पूरी तरह छोड़ें, और इंसान-लिखित निर्देशों को गैर-अनुमेय विवरणों तक सीमित करें — विशिष्ट टूलिंग और कस्टम कमांड जिन्हें एजेंट सचमुच अपने-आप खोज नहीं सकता।

दूसरे शब्दों में, हर लाइन को एक ठोस गलती को रोककर अपनी जगह अर्जित करनी चाहिए जो आपने वास्तव में एजेंट को करते देखी है।

एक वर्कफ़्लो जो काम करता है

1. खाली से शुरू करें। AGENTS.md तब तक न लिखें जब तक आपने एजेंट को कुछ गलत करते न देख लिया हो।
2. सिद्धांत नहीं, सुधार जोड़ें। जब यह गलत test कमांड चलाए, तो सही जोड़ें। जब यह किसी फ़ाइल को अपने तरीके से फिर से फ़ॉर्मैट करे और linter शिकायत करे, तो नियम जोड़ें।
3. इसे कसा रखें। अगर कोई लाइन बस वही दोहराती है जो एजेंट package.json या फ़ोल्डर नामों से पढ़ सकता है, तो उसे हटा दें।
4. monorepos के लिए nesting का उपयोग करें ताकि हर package की फ़ाइल छोटी रहे।
5. इसे मासिक रूप से फिर से पढ़ें। बासी निर्देश कोई न होने से बदतर हैं — एक एजेंट जो एक पुरानी build कमांड का पालन करता है आत्मविश्वास से फेल होता है।

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