AGENTS.md और HUMAN.md फ़ाइल का उपयोग कैसे करें

AGENTS.md क्या है

AGENTS.md रिपॉजिटरी के रूट पर स्थित एक साधारण markdown फ़ाइल है, जो कोडिंग एजेंट को यह बताती है कि किसी प्रोजेक्ट पर कैसे काम करना है। आधिकारिक साइट इसे "एजेंटों के लिए एक README: AI कोडिंग एजेंटों को आपके प्रोजेक्ट पर काम करने में मदद करने के लिए संदर्भ और निर्देश प्रदान करने हेतु एक समर्पित, पूर्वानुमानित स्थान" के रूप में वर्णित करती है। इस प्रारूप का प्रबंधन Linux Foundation के अंतर्गत Agentic AI Foundation द्वारा किया जाता है, और जुलाई 2026 तक Codex, Cursor, Jules, Devin और GitHub Copilot सहित बीस से अधिक एजेंट इसे पढ़ते हैं।

यह कन्वेंशन व्यावहारिक कारणों से मौजूद है। आपकी टीम में शामिल कोई नया व्यक्ति README पढ़ता है, build कमांड का अनुमान लगाता है, और गलत होने पर किसी से पूछता है। एक एजेंट पूछ नहीं सकता। वह अनुमान लगाता है, npm test को ऐसे प्रोजेक्ट पर चलाता है जो pnpm test का उपयोग करता है, विफलता को पढ़ता है, और कुछ और प्रयास करता है। आप उन सभी टोकन के लिए भुगतान करते हैं। वास्तविक कमांड को एक बार लिख देने से इस प्रकार की पूरी विफलता समाप्त हो जाती है।

इसमें कोई अनिवार्य फ़ील्ड नहीं हैं। साइट इस बारे में स्पष्ट है: "AGENTS.md केवल मानक Markdown है। आप अपनी पसंद की किसी भी हेडिंग का उपयोग करें; एजेंट केवल आपके द्वारा प्रदान किए गए टेक्स्ट को पार्स करता है।" यही पूरी विशिष्टता है। इसका मूल्य प्रारूप में नहीं है। इसका मूल्य उस फ़ाइल में है जो ऐसे पथ पर स्थित है जिसे हर टूल पहले से ही देखता है।

फाइल कहाँ रखें और कौन सी फाइल मान्य होगी

पहली फाइल को रिपॉजिटरी के रूट (root) में रखें। एक monorepo में आप प्रत्येक सब-प्रोजेक्ट के अंदर और भी फाइलें जोड़ सकते हैं, और नियम सरल है: "एजेंट्स निर्देशिका ट्री (directory tree) में सबसे नजदीकी फाइल को स्वचालित रूप से पढ़ते हैं, इसलिए जो फाइल सबसे करीब होती है, वही मान्य होती है।" दो फाइलों के बीच का टकराव उस फाइल के पक्ष में हल होता है जिसे एडिट किया जा रहा है, और चैट में आप जो कुछ भी टाइप करते हैं, वह दोनों फाइलों के निर्देशों को ओवरराइड (override) कर देता है।

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

नेस्टिंग (nesting) का उपयोग करना फायदेमंद है, क्योंकि किसी ऐसी बात को कहने का यही एकमात्र तरीका है जो एक फोल्डर में सही है और दूसरे में गलत। "प्रत्येक एंडपॉइंट अपने इनपुट को वैलिडेट करता है" जैसा नियम एंडपॉइंट्स के साथ ही होना चाहिए। रूट फाइल में यह हर असंबंधित कार्य पर लोड होता है और इसका कोई लाभ नहीं मिलता। यदि आपकी रूट फाइल पहले ही प्रति-सर्विस एक सेक्शन तक बढ़ चुकी है, तो इसे नेस्टेड लेआउट में विभाजित करना ही सही समाधान है, और यह तय करता है कि कौन से नियम नीचे ले जाने हैं और कौन से शीर्ष पर रहने चाहिए।

AGENTS.md में क्या शामिल होना चाहिए

वह जानकारी लिखें जिसे एक agent केवल code पढ़कर नहीं समझ सकता। सटीक build, test और lint commands सबसे पहले लिखें, उसी रूप में जिसे आप terminal में paste करेंगे। एक test चलाने के लिए command भी जोड़ें, क्योंकि जो agent केवल पूरी suite चलाना जानता है, वह उसे चालीस बार चलाएगा। उन conventions का नाम लिखें जो tool के default से अलग हैं, क्योंकि agent default को पहले से जानता है और उसे केवल आपके विचलन (deviation) के बारे में जानने की आवश्यकता है। यदि आपके पास commit message का प्रारूप और pull request के नियम हैं, तो उन्हें जोड़ें।

इतने स्पष्ट रहें कि किसी दावे की जाँच की जा सके। "2-space indentation का उपयोग करें" एक उपयोगी निर्देश है क्योंकि या तो यह हुआ है या नहीं। "Code को ठीक से format करें" उपयोगी नहीं है, क्योंकि इसमें कुछ भी verify नहीं किया जा सकता। यही बात locations पर भी लागू होती है: "API handlers src/api/handlers/ में रहते हैं" कहना "files को व्यवस्थित रखें" से बेहतर है।

Negative rules भी महत्वपूर्ण हैं। "dist/ के अंतर्गत files को कभी edit न करें, वे npm run build द्वारा generate की जाती हैं" एक विशिष्ट गलती को रोकता है, और क्योंकि यह कारण बताता है, agent उस समान स्थिति को समझ सकता है जिसे आपने नहीं लिखा है। scope के बारे में एक नियम भी यहाँ होना चाहिए, क्योंकि यदि agent को उसके अपने निर्णय पर छोड़ दिया जाए, तो वह आपके द्वारा मांगे गए से अधिक rewrite कर देगा: एक व्यापक रूप से copy किया गया कौशल केवल सबसे छोटे संभव बदलाव पर जोर देता है जो काम करता है।

ऐसी फाइलों में क्या नहीं होना चाहिए

इनमें से किसी भी फाइल में कभी भी कोई secret न रखें। यह फाइल git में commit हो जाती है, हर session की शुरुआत में context में load होती है, और हर request पर model provider को भेजी जाती है। AGENTS.md में मौजूद API key का मतलब है कि वह आपके repository history और किसी तीसरे पक्ष के logs में भी मौजूद है। इसे paste करने के बजाय secret की ओर इशारा करें: "database password .env में है, जिसे gitignore किया गया है; इसे पढ़ने से पहले पूछें।" इस व्यापक अनुशासन के बारे में credentials को agent की पहुँच से दूर रखना में बताया गया है।

ऐसी कोई भी जानकारी न दें जिसे agent देखकर खुद समझ सकता है। paste की गई directory listing, dependency list की copy, या folder names को दोहराने वाला architecture overview: ये सब आपके लिखने के एक हफ्ते बाद ही पुराने हो जाते हैं, और इस बीच हर session में context की जगह घेरते हैं। केवल pitfalls और उनके कारणों को रखें। inventory को हटा दें। कारणों को अलग रखना जरूरी है, क्योंकि जो agent यह नहीं देख पाएगा कि कोई असामान्य संरचना क्यों मौजूद है, वह चुपचाप उसे refactor कर देगा। यही कारण है कि इसके साथ एक DESIGN.md रखना महत्वपूर्ण है।

CLAUDE.md उसी विचार का Claude Code इंस्टेंस है

Claude Code CLAUDE.md को पढ़ता है और अपने आप AGENTS.md को नहीं पढ़ता। एक प्रोजेक्ट फाइल ./CLAUDE.md या ./.claude/CLAUDE.md पर रहती है, हर प्रोजेक्ट के लिए व्यक्तिगत प्राथमिकताएं ~/.claude/CLAUDE.md में जाती हैं, और एक संगठन Linux पर /etc/claude-code/CLAUDE.md पर मशीन-व्यापी फाइल पुश कर सकता है। खोजी गई फाइलें फाइलसिस्टम रूट से आपके वर्किंग डायरेक्टरी तक संयोजित (concatenate) की जाती हैं, इसलिए जिस स्थान से आपने सेशन शुरू किया है, उसके सबसे करीब वाली फाइल अंत में पढ़ी जाती है। उस डायरेक्टरी में शुरू किया गया हर सेशन एक ही स्टैक लोड करता है, जो इसे एक ही मशीन पर दो सेशन साथ-साथ चलाने के लिए व्यावहारिक बनाता है, और वे सेशन चलते समय एक-दूसरे को काम सौंप सकते हैं।

यदि आपके रिपॉजिटरी में पहले से ही AGENTS.md है, तो दूसरी कॉपी न रखें। इसे इम्पोर्ट करें, फिर केवल वही जोड़ें जो Claude के लिए विशिष्ट है:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

जब आपके पास जोड़ने के लिए कुछ अतिरिक्त न हो, तो एक symlink काम करता है:

ln -s AGENTS.md CLAUDE.md

सफलता मिलने पर यह कमांड कुछ भी प्रिंट नहीं करती है। अपने अगले सेशन में /context चलाएं और पुष्टि करें कि Memory files के अंतर्गत CLAUDE.md दिखाई देता है। यदि यह उस सूची से गायब है, तो फाइल कभी लोड नहीं हुई, इसलिए इसमें मौजूद कोई भी निर्देश लागू नहीं हुआ। लिखने के बजाय पहला ड्राफ्ट तैयार करने के लिए, /init चलाएं: यह कोडबेस को पढ़ता है और एक शुरुआती फाइल बनाता है, और जब CLAUDE.md पहले से मौजूद होता है, तो यह उसे ओवरराइट करने के बजाय सुधार का सुझाव देता है।

प्रत्येक फाइल को लगभग 200 लाइनों से कम रखें। लंबी फाइलें विंडो का अधिक हिस्सा लेती हैं और अनुपालन (adherence) कम हो जाता है। यदि आप देखना चाहते हैं कि उस स्थान के लिए और क्या प्रतिस्पर्धा करता है, तो एजेंट की कॉन्टेक्स्ट विंडो को वास्तव में क्या भरता है इसका विवरण देता है।

एक बिंदु पर जोर देना आवश्यक है। AGENTS.md मार्गदर्शन है, अनुमति प्रणाली नहीं। सामग्री सामान्य कॉन्टेक्स्ट के रूप में आती है, इसलिए मॉडल इसे पढ़ता है और आमतौर पर पालन करता है, लेकिन इसके विपरीत किसी भी क्रिया को कुछ भी नहीं रोकता है। जब आपके द्वारा लिखा गया कोई नियम चुपचाप छोड़ दिया जाता है और आप कारण नहीं बता पाते हैं, तो तीसरी बार शब्दों को फिर से लिखने से पहले निर्देश के छूटने के कारणों पर काम करें। ऐसे नियम के लिए जिसे हर बार लागू होना चाहिए, जैसे "never push to main", एक हुक या अनुमति सेटिंग का उपयोग करें, क्योंकि वे कोड के रूप में चलते हैं और मॉडल के निर्णय लेने पर निर्भर नहीं करते हैं।

इन फाइलों को आपके लिए लिखने वाले टूल्स

30 July 2026 को GitHub trending सूची में मौजूद दो प्रोजेक्ट्स यह दर्शाते हैं कि यह चलन किस दिशा में आगे बढ़ रहा है।

agent0ai/dox (July 2026 तक 1,368 stars) AGENTS.md फाइलों के एक ट्री को अपडेट रखने के लिए एक फ्रेमवर्क है। यह कोई पैकेज या runtime शिप नहीं करता है। आप इसके AGENTS.md की सामग्री को अपने रूट AGENTS.md में कॉपी करते हैं, और यही इसका इंस्टॉलेशन है। पहले से मौजूद किसी प्रोजेक्ट के लिए, आप अपने एजेंट को यह निर्देश देते हैं:

Initialize DOX tree for this project now.

इसके बाद एजेंट child AGENTS.md फाइलें और उनके इंडेक्स बनाता है, किसी भी बदलाव से पहले उस ट्री को स्कैन करता है, और बदलाव लागू होने के बाद संबंधित डॉक्यूमेंटेशन को अपडेट कर देता है। इसके पीछे यह धारणा है कि जो डॉक्यूमेंटेशन कोई एजेंट अपने काम के साइड इफेक्ट के रूप में मेंटेन करता है, वह सटीक रहता है, जबकि जिसे कोई व्यक्ति हाथ से अपडेट करता है, वह अक्सर सटीक नहीं रहता।

HUMAN.md, वही तरीका जो आप पर लागू होता है

Intuition-Lab/personal-model (जुलाई 2026 तक 1,260 stars) इसी पैटर्न को रिपॉजिटरी के बजाय किसी व्यक्ति पर लागू करता है। यह प्रोजेक्ट आपके HUMAN.md को आपके द्वारा टाइप की गई फाइल के बजाय सिस्टम के आउटपुट के रूप में देखता है: "यह इस बात का एक जीवंत मॉडल है कि अभी क्या महत्वपूर्ण है, आप निर्णय कैसे लेते हैं, और आपका ध्यान किस ओर जा रहा है।" यह macOS 13 या उसके बाद के वर्ज़न पर स्थानीय रूप से चलता है, macOS की अनुमति मिलने के बाद आपकी गतिविधि को कैप्चर करता है, और MCP (model context protocol) के माध्यम से परिणाम को एजेंट्स के लिए उपलब्ध कराता है। इसका संक्षिप्त इंस्टॉलेशन पाथ यह है:

uv tool install personal-model
persome onboard
persome model open --after 30

इसका अधिकांश लाभ उठाने के लिए आपको इनमें से किसी की भी आवश्यकता नहीं है। हाथ से लिखा गया HUMAN.md लगभग बीस लाइनों का होता है: आपकी भूमिका, आपका टाइमज़ोन, वह स्टैक जिसका आप वास्तव में उपयोग करते हैं, वे निर्णय जो आप पहले ही ले चुके हैं और जिन्हें आप दोबारा नहीं खोलना चाहते, और आप कितनी व्याख्या वापस चाहते हैं। यह उसी तरह की बार-बार की जाने वाली व्याख्या को बचाता है जो एक प्रोजेक्ट फाइल बचाती है, बस एक स्तर ऊपर।

एक सावधानी। HUMAN.md एक व्यक्ति का प्रोफाइल है, इसलिए यह परिभाषा के अनुसार संवेदनशील है। इसे किसी पब्लिक रिपॉजिटरी से दूर रखें। इसे ~/.claude/CLAUDE.md में रखें, या प्रोजेक्ट रूट पर एक gitignored CLAUDE.local.md में रखें, जो कमिट की गई फाइल के साथ लोड होता है और उसी तरह ट्रीट किया जाता है।

एक स्टार्टर टेम्प्लेट जिसे आप कॉपी कर सकते हैं

इसे जानबूझकर संक्षिप्त रखा गया है। जो सेक्शन लागू नहीं होते उन्हें हटा दें, और ऐसे सेक्शन जोड़ने से बचें जिन्हें आप अपडेट नहीं रख सकते।

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

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

FAQ

क्या AGENTS.md और CLAUDE.md एक ही फाइल हैं?

ये दोनों फाइलें एक ही विचार को दो अलग-अलग नामों से दर्शाती हैं। Claude Code CLAUDE.md को पढ़ता है और AGENTS.md को तब तक अनदेखा करता है जब तक आप उन्हें आपस में जोड़ते नहीं हैं। किसी एक फाइल को 'source of truth' के रूप में रखें और दूसरी को उससे लिंक कर दें; इसके लिए या तो अपनी CLAUDE.md की पहली पंक्ति में @AGENTS.md लिखें या फिर ln -s AGENTS.md CLAUDE.md का उपयोग करें। यदि आप दो पूर्ण प्रतियाँ अलग-अलग बनाए रखेंगे, तो एक महीने के भीतर उनमें विरोधाभास पैदा हो जाएगा।

क्या AGENTS.md लिखने से यह सुनिश्चित होता है कि एजेंट उसका पालन करेगा?

नहीं। इसकी सामग्री को context के रूप में प्रदान किया जाता है, इसलिए मॉडल इसे पढ़ता है और आमतौर पर इसका पालन करता है, लेकिन ऐसी किसी क्रिया को कुछ भी नहीं रोकता जो इसके विपरीत हो। अस्पष्ट निर्देशों का पालन सबसे कम विश्वसनीय तरीके से किया जाता है, और यदि दो फाइलें परस्पर विरोधी मार्गदर्शन देती हैं, तो एजेंट मनमाने ढंग से किसी एक को चुन लेता है। ऐसे नियम के लिए जिसे हर बार लागू होना चाहिए, एक hook या permission rule का उपयोग करें, जिन्हें मॉडल के निर्णय की परवाह किए बिना client द्वारा लागू किया जाता है।

क्या AGENTS.md को git में commit करना चाहिए?

हाँ, प्रोजेक्ट से जुड़ी किसी भी सत्य जानकारी के लिए: जैसे build commands, layout, और conventions। फाइल का उद्देश्य ही यही है, क्योंकि इससे आपके टीम के साथियों के एजेंट भी उसी context के साथ शुरू होते हैं जिसके साथ आपका एजेंट शुरू होता है। कोई भी व्यक्तिगत जानकारी या किसी एक मशीन के लिए विशिष्ट जानकारी को अलग gitignored फाइल में रखें, और credentials को इनमें से किसी में भी न रखें।

HUMAN.md क्या है और क्या मुझे इसकी आवश्यकता है?

HUMAN.md किसी प्रोजेक्ट के बजाय किसी व्यक्ति की machine-readable profile है। इसमें आपकी भूमिका, आपकी सीमाएं और वे निर्णय होते हैं जो आप पहले ही ले चुके हैं, ताकि हर session में उन पर दोबारा चर्चा न करनी पड़े। इसे शुरू करने के लिए आपको किसी टूलिंग की आवश्यकता नहीं है: अपनी user-level instructions फाइल में बीस हाथ से लिखी हुई पंक्तियाँ आपको अधिकांश लाभ प्रदान कर देंगी। इसे व्यक्तिगत डेटा मानें और इसे किसी भी ऐसे repository से दूर रखें जिसे आप push करते हैं।