CLAUDE.md और AGENTS.md: ये क्या हैं, इनमें क्या लिखें और एजेंट नियम क्यों नज़रअंदाज़ करता है

CLAUDE.md और AGENTS.md क्या हैं

ये रिपॉज़िटरी की जड़ में रखी सामान्य Markdown फ़ाइलें हैं, जिन्हें एजेंट सत्र की शुरुआत में अपने-आप context में लोड कर लेता है। इनके ज़रिए आप एजेंट को वह बताते हैं जो वह कोड से ख़ुद नहीं जान सकता: वातावरण कैसे चलाएँ, किन कमांड से काम जाँचें, कौन-से प्रोजेक्ट नियम अटल हैं और विस्तृत दस्तावेज़ कहाँ हैं।

CLAUDE.md वह फ़ाइल है जिसे Claude Code पढ़ता है। AGENTS.md एक खुला फ़ॉर्मेट है, जिसका विचार वही है और जिसे कई coding एजेंट समर्थन देते हैं। अगर टीम अलग-अलग एजेंट इस्तेमाल करती है, तो मुख्य सामग्री AGENTS.md में रखें और CLAUDE.md में उसका हवाला दें। Claude Code @ से दूसरी फ़ाइल जोड़ना सपोर्ट करता है:

# CLAUDE.md
@AGENTS.md

इससे नियम एक ही जगह रहते हैं और दोनों फ़ाइलों में अलग-अलग नहीं होते।

एजेंट इन फ़ाइलों को कैसे पढ़ता है

निर्देश फ़ाइल की सामग्री सिस्टम prompt के साथ मॉडल की context window में जाती है और पूरे सत्र भर वहीं रहती है। इससे तीन महत्वपूर्ण बातें निकलती हैं।

• हर पंक्ति context में जगह लेती है। फ़ाइल हर शुरुआत पर पूरी पढ़ी जाती है, भले ही मौजूदा काम के लिए उसका दसवाँ हिस्सा ही चाहिए।
• ये लागू होने वाले नियम नहीं, टेक्स्ट हैं। मॉडल इसे बाक़ी context के साथ ध्यान में रखता है, और सौ प्रतिशत पालन की गारंटी नहीं। सख़्त रोक को जाँच, hooks या पहुँच-अधिकारों से सहारा देना पड़ता है।
• फ़ाइलें नेस्ट की जा सकती हैं। Claude Code प्रोजेक्ट की जड़ और ~/.claude/ से CLAUDE.md लोड करता है, और नेस्टेड डायरेक्टरी की फ़ाइलें तब, जब एजेंट उन डायरेक्टरी की फ़ाइलों के साथ काम करता है। इससे मॉड्यूल के नियम उसी मॉड्यूल के पास रखे जा सकते हैं।

CLAUDE.md और AGENTS.md में क्या लिखें

अच्छी निर्देश फ़ाइल नक्शा है, पाठ्यपुस्तक नहीं। वह वे सवाल जवाब देती है जो एजेंट किसी अनुभवी साथी से पहले दिन पूछता।

1. प्रोजेक्ट कैसे बनाएँ और जाँचें

यह सबसे क़ीमती हिस्सा है। ठोस कमांड, जो एजेंट को "तैयार" कहने से पहले चलानी ही हैं: टेस्ट, linter, type checking, वातावरण चलाना। इनके बिना एजेंट अपना काम "अंदाज़े" से जाँचता है।

2. सख़्त सीमाएँ

छोटी सूची, जिसे किसी भी हाल में नहीं तोड़ना है: सुरक्षा और डेटा के invariants। इन्हें implementation निर्देश की तरह नहीं, invariant की तरह लिखें: "सभी SQL queries parameterized हों", न कि "इस फ़ाइल में इस फ़ंक्शन का उपयोग करो"।

3. प्रोजेक्ट का नक्शा

कौन-सी चीज़ कहाँ है: डायरेक्टरी की संरचना के बारे में कुछ पंक्तियाँ और यह कि विवरण कहाँ मिलेंगे। हर बड़े विषय के लिए अलग दस्तावेज़ का लिंक, जिसे एजेंट तभी खोलेगा जब वह उस विषय पर काम करेगा।

4. काम की स्थिति कहाँ रहती है

पिछला सत्र जहाँ रुका था, वहाँ से आगे बढ़ने के लिए कहाँ देखें: योजना की फ़ाइल, प्रगति का लॉग, backlog। इससे एजेंट की सत्रों के बीच की "भूलने की" समस्या हल होती है।

क्या नहीं लिखना चाहिए

• वह जो एजेंट कोड से जान लेता है। निर्भरताओं की सूची package.json या pyproject.toml में है, classes की संरचना कोड में।
• सामान्य सलाह। "साफ़ कोड लिखो", "ध्यान से काम करो" व्यवहार नहीं बदलते, केवल जगह घेरते हैं।
• प्रोजेक्ट का इतिहास और एक बार की टिप्पणियाँ। "मार्च में हम MySQL 5.7 से शिफ़्ट हुए" मौजूदा काम में मदद नहीं करता।
• दुर्लभ कामों के विस्तृत निर्देश। Deploy या डेटा migration की प्रक्रिया हफ़्ते में एक बार चाहिए, उसे अलग दस्तावेज़ या skill में रखें।
• Secrets। फ़ाइल रिपॉज़िटरी में रहती है और पूरी मॉडल तक जाती है। टोकन और पासवर्ड केवल environment variables में रखें।

एजेंट फ़ाइल में लिखा नियम क्यों नज़रअंदाज़ करता है

आम कहानी: एजेंट ने गलती की, फ़ाइल में एक नियम जोड़ा गया। फिर एक और गलती, एक और नियम। कुछ महीनों में फ़ाइल सैकड़ों पंक्तियों की हो जाती है, और एक ज़रूरी सुरक्षा नियम एजेंट ऐसे तोड़ता है मानो वह हो ही नहीं। इसके आम तौर पर चार कारण होते हैं, और चारों एक साथ काम करते हैं।

फूली हुई फ़ाइल

600 पंक्तियों की फ़ाइल लगभग 10 से 20 हज़ार tokens होती है। Context window बड़ी लगती है, पर उसमें कोड, कमांड का आउटपुट और बातचीत का इतिहास भी होता है। निर्देश जितनी जगह लेते हैं, हर नियम को उतना कम ध्यान मिलता है और असली काम के लिए जगह कम बचती है।

नियम बीच में दबा हुआ

भाषा मॉडल लंबे टेक्स्ट के बीच की जानकारी का उपयोग शुरू और अंत की तुलना में कमज़ोर करते हैं। छह सौ में से तीन सौवीं पंक्ति का नियम सबसे कमज़ोर जगह पर होता है।

प्राथमिकता नहीं

अटल प्रतिबंध और स्टाइल की एक छोटी टिप्पणी एक ही तरह सूची में एक पंक्ति के रूप में लिखे होते हैं। एजेंट के पास यह जानने का कोई तरीक़ा नहीं कि कौन ज़्यादा ज़रूरी है। और अगर फ़ाइल में तीन आपस में टकराने वाले स्टाइल नियम हों, तो व्यवहार हर रन पर अलग हो जाता है।

सड़न

नियम जोड़ना मुफ़्त है, हटाना डरावना: "कहीं कुछ उस पर टिका न हो?" इसलिए फ़ाइल लगातार बढ़ती है और उपयोगी पंक्तियों का अनुपात घटता है। इसे signal-to-noise के रूप में मापना उपयोगी है: किसी आम काम के लिए वास्तव में कितनी पंक्तियाँ चाहिए, और कितनी बेकार हैं।

समाधान: पोथे के बजाय रूटर

एक कारण ठीक करने से कुछ नहीं होगा: अगर फ़ाइल छोटी कर दी, पर उसकी संरचना नहीं सुधारी, तो नियम अब भी आपस में मिले रहेंगे। काम करने वाली तरकीब कई उपायों का मेल है।

1. प्रवेश फ़ाइल को रूटर बनाएँ। 50 से 150 पंक्तियाँ: जाँच की कमांड, सख़्त नियम, प्रोजेक्ट का नक्शा और विषयगत दस्तावेज़ों के लिंक।
2. विषय अलग फ़ाइलों में रखें। जैसे docs/agents/deploy.md, docs/agents/database.md। एजेंट इन्हें ज़रूरत पर खोलता है। Claude Code में दोहराए जाने वाले कामों के लिए skills उपयोगी हैं, जो तभी लोड होते हैं जब उनकी ज़रूरत हो।
3. ज़रूरी नियम ऊपर रखें। सख़्त नियम फ़ाइल की शुरुआत में, MUST चिह्न के साथ एक छोटे ब्लॉक में।
4. विरोधाभास हटाएँ। हर विषय पर एक ही नियम। अपवाद हो तो उसे नियम के ठीक बगल में लिखें।
5. नियम को तंत्र से सहारा दें। अगर उल्लंघन अस्वीकार्य है, तो केवल टेक्स्ट पर्याप्त नहीं। ऐसी जाँच चाहिए जो उसे पकड़े: linter, टेस्ट, pre-commit hook, या एजेंट का hook, या पहुँच-अधिकारों पर रोक।
6. नियमित समीक्षा करें। फ़ाइल की पंक्तियों की सीमा तय करें और हर नई बात जोड़ते समय पूछें कि क्या हटाया या बाहर ले जाया जा सकता है।

नियम या जाँच?

संक्षिप्त AGENTS.md का उदाहरण

# AGENTS.md — payment backend (FastAPI, PostgreSQL)

## MUST — ये नहीं टूटने चाहिए
- पैसों की राशि int में, पैसों (paise/cents) में, कभी float नहीं
- SQL केवल parameterized, f-strings नहीं
- लागू migrations न बदलें, केवल नई जोड़ें
- Secrets — केवल environment variables से

## "तैयार" कहने से पहले जाँच
docker compose up -d     # वातावरण
make lint                # ruff + mypy
make test                # pytest
make e2e                 # order flow परिदृश्य
हरे unit tests बिना e2e के — "तैयार" नहीं।

## नक्शा
- app/payments/   — राशि की गणना, छूट, provider webhooks
- app/api/        — HTTP handlers
- tests/e2e/      — उपयोगकर्ता के परिदृश्य
विवरण: docs/agents/architecture.md, docs/agents/database.md

## काम की स्थिति
- PLAN.md      — वर्तमान लक्ष्य, तैयार होने की शर्तें, अगला कदम
- PROGRESS.md  — क्या किया गया और कैसे जाँचा, बंद रास्ते
- BACKLOG.md   — रास्ते में दिखी बातें: यहाँ लिखें, अभी न सुधारें

सत्र के अंत में PROGRESS.md और PLAN.md में अगला कदम अपडेट करें।

ध्यान दें कि यहाँ क्या नहीं है: लाइब्रेरी की सूची, स्टाइल की सलाह, प्रोजेक्ट का इतिहास। यह सब या तो कोड में दिख जाता है, या जाँचों में तय है, या विषयगत दस्तावेज़ों में है।

सत्रों के बीच की भूल: निर्देश फ़ाइल के साथ योजना की फ़ाइल

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

दोनों फ़ाइलों को मिलाएँ नहीं। निर्देश कम बदलते हैं और सभी कामों पर लागू होते हैं। योजना हर सत्र में बदलती है और केवल मौजूदा काम पर लागू होती है। अगर दोनों मिल जाएँ, तो निर्देश फ़ाइल पुरानी टिप्पणियों से जल्दी फूल जाती है।

जाँचें कि फ़ाइल काम करती है

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

निष्कर्ष

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