दर्द: AI कोडिंग एक ही जगह बार-बार क्यों फेल होती है

Cursor, Windsurf या Claude Code से प्रोजेक्ट बनाने वाले लोग एक ही तरह का फ्रस्ट्रेशन झेल चुके हैं: AI पूरा कोड ब्लॉक उगलता है, आप कॉपी-पेस्ट करके चलाते हैं — बिल्ड एरर, टेस्ट रेड, डिपेंडेंसी गलत जगह पर। मसला AI की अक्ल का नहीं, बल्कि यह है कि उसे आपके प्रोजेक्ट की “अनकही रूल्स” पता ही नहीं हैं।

AGENTS.md प्रोजेक्ट रूट में रखी जाने वाली एक Markdown फ़ाइल है, खास AI के लिए लिखी गई — बताती है कि बिल्ड कैसे करना है, टेस्ट कैसे चलाना है, कौन-से स्टैंडर्ड फॉलो करने हैं। README.md इंसानों के लिए है — प्रोजेक्ट इंट्रो, कंट्रीब्यूशन गाइड, ब्रांड स्टोरी से भरी। AI इन्हें पढ़कर ऐसे ही भटकता है जैसे कोई नया जॉइनर पहले दिन कंपनी की ब्रोशर पकड़ाकर तुरंत कोड लिखने को कह दिया जाए — उसे पता है कंपनी क्या करती है, पर बिल्ड कमांड, टेस्ट प्रोसीजर, ESLint रूल्स कुछ नहीं पता। नतीजा? हर बार चैट में बार-बार सुधारना: “pnpm चलाओ npm नहीं”, “टेस्ट packages/web में है”, “lint मत भूलना”। यही सुधार सौ बार दोहराओ, प्रोजेक्ट फिर भी गड़बड़।

फ्रीलांस सीन में नुकसान सीधा है: आपने Next.js + Prisma का क्लाइंट प्रोजेकट लिया, Cursor से स्पीड बढ़ाने लगे, AI ने npm install चला दिया, pnpm का workspace कॉन्फ़िगरेशन ध्वस्त; उसे नहीं पता डेटाबेस स्कीमा किस डायरेक्टरी में है, जेनरेट किया गया migration फ़ाइल सीधे एरर फेंकता है। क्लाइंट डेडलाइन पर चिल्ला रहा है, आप AI के कोड को debug करने में तीन घंटे खपा देते हैं — पैसा कमाने का यह तरीका बहुत तकलीफ़देह है।

AI के प्रोजेक्ट रूल्स न जानने के 3 क्लासिक फेल्योर: ① पैकेज मैनेजर गलत (प्रोजेक्ट pnpm पर है, AI डिफ़ॉल्ट npm install चलाता है), डिपेंडेंसी गलत जगह इंस्टॉल, workspace कॉन्फ़िग टूटा; ② टेस्ट एंट्री नहीं मिलती (टेस्ट packages/web में है, AI रूट में pnpm test चलाता है, “टेस्ट फ़ाइल नहीं मिली” एरर); ③ कोड स्टाइल बेमेल (ESLint + Prettier है, AI का कोड इंडेंटेशन और कोट्स गलत, CI सीधे फेल)।

मौका: AGENTS.md “इंसानी डॉक्यूमेंट” और “मशीनी डॉक्यूमेंट” को अलग करता है

GitHub पर ओपन-सोर्स प्रोजेक्ट AGENTS.md (रिपो: github.com/agentsmd/agents.md, 26 अगस्त 2026 तक लगभग 24,000 stars) इसी समस्या का समाधान है। इसकी मूल बात बेहद सीधी है: प्रोजेक्ट रूट में एक Markdown फ़ाइल रखो जो AI को बिल्ड, टेस्ट और कोड स्टाइल बताए।

यह README की जगह नहीं, बल्कि उसका साथी है। README इंसानी कंट्रीब्यूटर्स के लिए, AGENTS.md AI एजेंट्स के लिए। दोनों की भूमिका साफ, कोई टकराव नहीं।

सोर्स पोस्ट के अनुसार, AGENTS.md को हज़ारों ओपन-सोर्स प्रोजेक्ट्स अपना चुके हैं (सटीक संख्या पुष्टि बाकी), VS Code, Cursor, Windsurf, Aider, GitHub Copilot जैसे मुख्यधारा के AI कोडिंग टूल्स सपोर्ट करते हैं (सत्यापित); कम्युनिटी फ़ीडबैक के अनुसार OpenAI Codex, Google Jules भी सपोर्ट देते हैं (⚠️अपुष्ट)। अभी नहीं सीखा, तो AI से बात करने के लिए बोली नहीं सीखी।

पाथ 1: मिनिमल यूज़ेबल AGENTS.md खुद लिखो

लागत बेहद कम। नई फ़ाइल बनाओ, तीन पैराग्राफ काफ़ी हैं।

पूर्व-ज्ञान: उदाहरण pnpm (npm से डिस्क-फ्रेंडली, monorepo workspace सपोर्ट), turbo (monorepo टास्क ऑर्केस्ट्रेशन टूल), --filter पैरामीटर (सिर्फ़ एक सब-पैकेज पर काम करता है, पूरे रिपो को प्रभावित नहीं करता) पर आधारित हैं।

पहला पैराग्राफ “Dev environment tips”: AI को बताओ कौन-सा पैकेज मैनेजर, सब-पैकेज में कैसे जाएँ, नया मॉड्यूल कैसे बनाएँ। ऑफ़िशियल उदाहरण:

• pnpm dlx turbo run where <project_name> — सीधे सब-पैकेज डायरेक्टरी में पहुँचो, ls से एक-एक करके ढूँढ़ने की ज़रूरत नहीं
• pnpm install --filter <project_name> — सिर्फ़ एक सब-पैकेज की डिपेंडेंसी इंस्टॉल करो, पूरे monorepo को छुओ मत
• pnpm create vite@latest <project_name> -- --template react-ts — TypeScript चेक के साथ नया React + Vite सब-पैकेज बनाओ

ये कमांड्स AI खुद नहीं अंदाज़ा लगा सकता, लिख दो तो मान जाता है।

दूसरा पैराग्राफ “Testing instructions”: AI को बताओ टेस्ट कैसे चलाना है, CI पाइपलाइन कहाँ है, कमिट से पहले कौन-से चेक ज़रूरी हैं। ऑफ़िशियल उदाहरण:

• pnpm turbo run test --filter <project_name> — सब-पैकेज के सारे चेक चलाओ
• pnpm vitest run -t "<test name>" — सिर्फ़ नाम से मैच होने वाला एक टेस्ट चलाओ
• “Fix any test or type errors until the whole suite is green” — पूरा ग्रीन न होने तक रुको मत
• “Add or update tests for the code you change, even if nobody asked” — यह लाइन क्रिटिकल है, न लिखो तो AI टेस्ट लिखने में आलस करता है

तीसरा पैराग्राफ “PR instructions”: कमिट टाइटल फ़ॉर्मेट, lint और test ज़रूरी। ऑफ़िशियल उदाहरण: Title format: [<project_name>] <Title>, और “Always run pnpm lint and pnpm test before committing”।

तीनों मिलकर 50 लाइन से कम, पर AI के कोड की फ़र्स्ट-पास सक्सेस रेट काफ़ी बढ़ जाती है (कम्युनिटी फ़ीडबैक, सटीक आँकड़े पुष्टि बाकी)।

पाथ 2: बड़े monorepo में नेस्टेड इस्तेमाल

अगर आपने एंटरप्राइज़-लेवल प्रोजेक्ट लिया है जहाँ कोडबेस monorepo स्ट्रक्चर में है (एक ही Git रिपो में कई रिलेटेड प्रोजेक्ट्स — फ़्रंटएंड, बैकएंड, शेयर्ड कोड अलग-अलग सब-डायरेक्टरी में), तो एक AGENTS.md काफ़ी नहीं। AGENTS.md नेस्टिंग सपोर्ट करता है: हर सब-डायरेक्टरी में अपनी AGENTS.md रखो, AI अपने-आप “सबसे नज़दीकी वाली” पढ़ लेता है।

अमली तरीका: रूट AGENTS.md में ग्लोबल रूल्स (पैकेज मैनेजर, CI फ़्लो, सिक्योरिटी नोट्स), फिर packages/web/, packages/api/, packages/shared/ में अलग-अलग फ़ाइलें — हर सब-पैकेज के खास बिल्ड कमांड, टेस्ट एंट्री, स्पेशल डिपेंडेंसी। जैसे फ़्रंटएंड पैकेज में लिखो “कंपोनेंट लाइब्रेरी shadcn, स्टाइलिंग Tailwind, आइकन्स lucide-react”; बैकएंड में लिखो “डेटाबेस migration Prisma से, API रूट्स src/routes में, ऑथ JWT से”।

AI जब सब-डायरेक्टरी में काम करता है, अपने-आप नज़दीकी AGENTS.md लोड करता है, रूट वाले से प्रायोरिटी हायर। यानी एक ही प्रोजेक्ट में फ़्रंटएंड AI असिस्टेंट और बैकएंड AI असिस्टेंट को पूरी तरह अलग-अलग निर्देश मिलते हैं, कोई क्रॉस-कंटैमिनेशन नहीं।

पाथ 3: इसे फ्रीलांस USP में बदलो

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

अमली रणनीति: प्रोजेक्ट मिलने पर पहले 30 मिनट क्लाइंट की प्रोजेक्ट स्ट्रक्चर समझो, फिर कस्टम AGENTS.md लिखो। यह डॉक्यूमेंट खुद डिलीवरेबल का हिस्सा है — क्लाइंट आगे खुद AI से कोड मेंटेन करेगा तो भी आसानी होगी।

AGENTS.md कॉन्फ़िगरेशन सर्विस अलग प्राइस करो (लोकल मार्केट के हिसाब से एडजस्ट करें): बेसिक पैकेज ₹5,000 (सिंगल फ़ाइल कॉन्फ़िग + README गाइड), एंटरप्राइज़ पैकेज ₹25,000 (monorepo नेस्टिंग + सिक्योरिटी रूल्स + टीम ट्रेनिंग)। डिलीवरी लिस्ट: ① कस्टम AGENTS.md फ़ाइल ② 30 दिन WhatsApp सपोर्ट ③ 10 मिनट की स्क्रीन-रिकॉर्डिंग ट्रेनिंग। कब काम आता है: क्लाइंट के पास पहले से Cursor/Windsurf सब्सक्रिप्शन है पर रिज़ल्ट नहीं आ रहा। कब नहीं: क्लाइंट अभी भी पूरी तरह मैन्युअल डेवलपमेंट कर रहा है, AI टूल अभी अडॉप्ट नहीं किया।

केस स्टडी: AGENTS.md की कम्पैटिबिलिटी मोहरे

AGENTS.md MIT लाइसेंस पर है (सोर्स पुष्ट), कम्युनिटी द्वारा मेंटेन (गवर्नेंस स्ट्रक्चर पुष्टि बाकी), ऑफ़िशियल साइट agents.md।

कम्पैटिबिलिटी ही इसका सबसे बड़ा मोहरा है: सत्यापित — VS Code, Cursor, Windsurf, Aider, GitHub Copilot सब AGENTS.md पढ़ते हैं; कम्युनिटी फ़ीडबैक के अनुसार OpenAI Codex, Claude Code, Gemini CLI, Google Jules भी सपोर्ट करते हैं (⚠️अपुष्ट)। एक फ़ाइल लिखो, मुख्यधारा के सारे AI असिस्टेंट काम करें — हर टूल के लिए अलग कॉन्फ़िग लिखने की ज़रूरत नहीं।

दूसरे ऑप्शन्स से तुलना: Cursor का .cursorrules सिर्फ़ Cursor पर काम करता है, Windsurf पर बेकार; Claude Code का CLAUDE.md सिर्फ़ Claude के लिए; GitHub Copilot का इंस्ट्रक्शन सिस्टम फिर अलग। AGENTS.md का “एक बार लिखो, हर जगह चलाओ” फ़ीचर ही इसकी तेज़ी से अपनाने की असली वजह है।

टूल माइग्रेशन की लागत ज़ीरो। आज Cursor इस्तेमाल करो, कल Windsurf पर शिफ़्ट हो जाओ, AGENTS.md सीधा रीयूज़, रूल्स फिर से लिखने की झंझट नहीं।

कॉल-टू-एक्शन: आज रात अपने प्रोजेक्ट में मशीन मैनुअल जोड़ो

5 मिनट का एक्शन प्लान: ① प्रोजेक्ट रूट खोलो ② AGENTS.md नई फ़ाइल बनाओ ③ ऑफ़िशियल टेम्पलेट कॉपी करो (github.com/agentsmd/agents.md) ④ तीन कमांड्स भरो (बिल्ड, टेस्ट, lint) ⑤ अगली बार AI से कोड लिखवाते समय रिज़ल्ट देखो।

अगर monoreपो इस्तेमाल कर रहे हो, तो आज रात 20 मिनट और निकालकर हर सब-पैकेज में नेस्टेड कॉन्फ़िग जोड़ो। कल सुबह काम शुरू करोगे तो AI का जेनरेट किया कोड बार-बार सुधारने की ज़रूरत नहीं पड़ेगी।

AGENTS.md अभी AI कोडिंग कॉन्फ़िगरेशन का सबसे ज़्यादा ROI देने वाला काम है — 30 मिनट की मेहनत, हर महीने कई घंटे की debug टाइम की बचत।