AGENTS.md फ़ाइल कैसे लिखें ताकि कोई भी AI कोडिंग एजेंट आपके प्रोजेक्ट को समझ सके

अगर आपने कभी किसी AI कोडिंग एजेंट को ग़लत टेस्ट कमांड चलाते, आपके प्रोजेक्ट में प्रतिबंधित स्टाइल में कोड फ़ॉर्मैट करते, या पहले से मौजूद किसी हेल्पर को दोबारा बनाते देखा है, तो इसका हल आमतौर पर कोई अधिक स्मार्ट मॉडल नहीं होता — बल्कि संदर्भ (context) होता है। AGENTS.md एजेंट्स को वह संदर्भ देने का मानक तरीका है, और यह लगभग हर टूल के साथ काम करता है।

AGENTS.md असल में क्या है

AGENTS.md "एजेंट्स के लिए एक README" है: एक सादी Markdown फ़ाइल जिसे आप अपनी रिपॉज़िटरी के रूट में रखते हैं ताकि AI कोडिंग टूल्स को बता सकें कि आपका प्रोजेक्ट कैसे काम करता है (agents.md)। यह कोई नई कॉन्फ़िग भाषा नहीं है — इसमें कोई अनिवार्य फ़ील्ड नहीं और कोई विशेष सिंटैक्स नहीं है। आप जो भी Markdown हेडिंग चाहें, इस्तेमाल करें।

यह फ़ॉर्मैट इसलिए मायने रखता है क्योंकि यह वाक़ई क्रॉस-टूल है। 2026 के मध्य तक इसे OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Devin, Aider, Zed, VS Code, JetBrains Junie और दर्जनों अन्य टूल्स नेटिव रूप से पढ़ते हैं — 28+ टूल्स और 60,000+ ओपन-सोर्स रिपॉज़िटरीज़ (agents.md; Codersera)। अब इसका संरक्षण Linux Foundation के Agentic AI Foundation द्वारा किया जाता है, Anthropic के Model Context Protocol के साथ-साथ। Claude Code भी AGENTS.md पढ़ता है, हालाँकि इसका अधिक समृद्ध नेटिव फ़ॉर्मैट CLAUDE.md ही बना हुआ है (DeployHQ)।

एक फ़ाइल, और आपके ज़्यादातर टूल्स एक जैसा व्यवहार करते हैं।

चैट में बार-बार दोहराने से एक फ़ाइल बेहतर क्यों है

जब आप निर्देशों को किसी चैट संदेश में पेस्ट करते हैं, तो वे बिल्कुल एक ही बातचीत भर के लिए जीवित रहते हैं। अगला सेशन — या अगला साथी, या रात भर आपका टास्क चलाने वाला कोई क्लाउड एजेंट — शून्य से शुरू होता है। एक AGENTS.md हर रन की शुरुआत में अपने-आप लोड हो जाती है, इसलिए आपकी परंपराएँ इस बात पर निर्भर रहने के बजाय डिफ़ॉल्ट रूप से लागू होती हैं कि आपको उन्हें बताना याद रहा या नहीं। यही तो पूरी बात है: प्रोजेक्ट के ज्ञान को अपने दिमाग़ से और फेंकने योग्य चैट्स से निकालकर उस फ़ाइल में डालना जिसे टूल्स हर बार पढ़ते हैं।

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

सोचिए कि एक सक्षम नए साथी को पहले दिन क्या-क्या चाहिए होगा — एजेंट को ठीक वही चाहिए। सबसे उपयोगी सेक्शन ये हैं:

• प्रोजेक्ट अवलोकन — एक पैराग्राफ़ इस बारे में कि यह क्या है और टेक स्टैक क्या है।
• सेटअप और बिल्ड कमांड्स — इंस्टॉल, रन और बिल्ड करने के सटीक कमांड।
• टेस्टिंग — टेस्ट कैसे चलाएँ, और यह नियम कि किसी बदलाव को पूरा माने जाने से पहले टेस्ट पास होने चाहिए।
• कोड स्टाइल — फ़ॉर्मैटर, लिंटर, नामकरण परंपराएँ, प्राथमिकता देने या टालने योग्य पैटर्न।
• कमिट और PR दिशानिर्देश — संदेश का फ़ॉर्मैट, ब्रांच नियम, किसे न छुएँ।
• गोटचास (Gotchas) — कोई भी ऐसी अस्पष्ट बात जो लोगों को उलझा देती है।

ठोस रहें। "साफ़ कोड लिखो" एजेंट को कुछ नहीं बताता। "npm नहीं, pnpm इस्तेमाल करो; ख़त्म करने से पहले pnpm test चलाओ; src/generated/ में फ़ाइलें कभी एडिट न करो" — यह लागू करने योग्य है।

एक ठोस उदाहरण

यहाँ एक सामान्य वेब ऐप के लिए एक संक्षिप्त AGENTS.md है:

# AGENTS.md

## Project
Next.js 15 + TypeScript storefront. Package manager is pnpm.

## Setup & commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`

## Testing
- Run all tests: `pnpm test`
- All tests must pass before a task is considered done.

## Code style
- TypeScript strict mode; no `any`.
- Format with Prettier (`pnpm format`) — do not hand-format.
- Prefer named exports. Reuse helpers in `src/lib/` before writing new ones.

## Do not touch
- `src/generated/**` is auto-generated. Never edit by hand.
- Never commit `.env` files.

इसे Claude Code, Cursor या Copilot को दे दें और हर एक वही नियम अपना लेगा।

मोनोरिपो: नेस्टेड फ़ाइलें इस्तेमाल करें

एक मोनोरिपो में आप रूट पर एक AGENTS.md रखने के साथ-साथ हर पैकेज में भी एक रख सकते हैं। जब कोई एजेंट किसी सबडायरेक्टरी के भीतर काम करता है, तो सबसे नज़दीकी फ़ाइल की जीत होती है (agents.md)। साझा परंपराओं को रूट पर और पैकेज-विशिष्ट कमांड्स को नेस्टेड फ़ाइलों में रखें, ताकि packages/api/ को एडिट करने वाले एजेंट को उस पैकेज के बिल्ड और टेस्ट कमांड अपने-आप मिल जाएँ।

AGENTS.md बनाम CLAUDE.md बनाम Cursor rules

हो सकता है आपके पास पहले से CLAUDE.md या .cursor/rules जैसी टूल-विशिष्ट फ़ाइलें हों। आपको उन्हें फेंकने की ज़रूरत नहीं है। व्यवहार में, टीमें साझा, टूल-अज्ञेय (tool-agnostic) परंपराएँ AGENTS.md में डालती हैं — वह सामान जो हर एजेंट को चाहिए — और टूल-विशिष्ट अतिरिक्त चीज़ों को उस टूल की नेटिव फ़ाइल में रखती हैं जो अधिक समृद्ध फ़ीचर सपोर्ट करता है (DeployHQ)। उदाहरण के लिए, Claude Code दोनों पढ़ता है, जिसमें CLAUDE.md इसका अधिक अभिव्यक्तिपूर्ण फ़ॉर्मैट है। एक आम पैटर्न यह है कि एक कैननिकल AGENTS.md रखी जाए और, जहाँ किसी टूल को अपनी फ़ाइल चाहिए, उस फ़ाइल को AGENTS.md की ओर इंगित कर दिया जाए ताकि सत्य का एक ही स्रोत रहे। AGENTS.md से शुरुआत करें; टूल-विशिष्ट फ़ाइल की ओर तभी बढ़ें जब आपको कोई ऐसा फ़ीचर चाहिए जो केवल वही सपोर्ट करता हो।

इसे छोटा और विशिष्ट रखें

ज़्यादा का मतलब बेहतर नहीं होता। एक विशालकाय AGENTS.md जो आपकी पूरी स्टाइल गाइड को दोहराती है, मॉडल के ध्यान के लिए होड़ करती है और उन नियमों को दबा देती है जो असल में मायने रखते हैं। उन गिनी-चुनी चीज़ों पर लक्ष्य रखें जिन्हें एजेंट मार्गदर्शन के बिना ग़लत करेगा — वह अस्पष्ट कमांड, वह डायरेक्टरी जिसे नहीं छूना, वह पैटर्न जिसे आपका कोडबेस पसंद करता है। अगर कोई नियम पहले से ही कोड से स्पष्ट है, तो शायद आपको उसे लिखने की ज़रूरत नहीं है।

इसे उपयोगी कैसे बनाए रखें

एक AGENTS.md तभी अपनी क़ीमत वसूल करती है जब वह सही बनी रहे। इसे कोड की तरह समझें: जब कोई कमांड या परंपरा बदले, तो फ़ाइल को उसी कमिट में अपडेट करें। और जब कोई एजेंट वही ग़लती दो बार करे, तो उसे सिर्फ़ चैट में सुधारकर न छोड़ें — नियम लिख दें। यही एक आदत हर चूक को स्थायी सुधार में बदल देती है, और यह आपके प्रोजेक्ट पर AI एजेंट्स को भरोसेमंद बनाने के लिए किया जाने वाला सबसे अधिक प्रभावशाली काम है।