AGENTS.md और HUMAN.md क्या हैं? आसान गाइड

AGENTS.md क्या है

AGENTS.md repository के root में मौजूद एक साधारण markdown फ़ाइल है। यह coding agent को बताती है कि उस project पर कैसे काम करना है। आधिकारिक site इसे इस तरह बताती है: "agents के लिए एक README: आपके project पर AI coding agents को काम करने में सहायता देने वाला context और instructions देने का समर्पित, पूर्वानुमेय स्थान।" इस format का stewardship Linux Foundation के अंतर्गत Agentic AI Foundation करती है। जुलाई 2026 तक Codex, Cursor, Jules, Devin और GitHub Copilot सहित 20 से अधिक agents इसे पढ़ते हैं।

यह convention व्यावहारिक कारण से मौजूद है। आपकी team में नया व्यक्ति README पढ़ता है, build command का अनुमान लगाता है और अनुमान गलत होने पर किसी से पूछता है। Agent पूछ नहीं सकता। वह अनुमान लगाता है, npm test को pnpm test का उपयोग करने वाले project पर चलाता है, failure पढ़ता है और कुछ दूसरा आज़माता है। इन tokens में से हर एक का खर्च आपको उठाना पड़ता है। वास्तविक command को एक बार लिख देने से इस पूरी तरह की failure समाप्त हो जाती है।

कोई required field नहीं है। Site इस बारे में स्पष्ट है: "AGENTS.md केवल standard Markdown है। अपनी पसंद के headings का उपयोग करें; agent आपके दिए गए text को parse करता है।" यही पूरी specification है। इसका मूल्य format में नहीं है। इसका मूल्य इस बात में है कि यह ऐसी path पर स्थित फ़ाइल है जिसे हर tool पहले से देखता है।

फ़ाइल कहाँ रखनी है और कौन-सी फ़ाइल प्रभावी होगी

पहली फ़ाइल repository root में रखें। Monorepo में आप प्रत्येक subproject के अंदर और फ़ाइलें जोड़ सकते हैं। नियम सरल है: "agents directory tree में सबसे निकट वाली फ़ाइल को अपने-आप पढ़ते हैं, इसलिए सबसे निकट वाली फ़ाइल को प्राथमिकता मिलती है।" दो फ़ाइलों के बीच विरोध होने पर उस फ़ाइल को प्राथमिकता मिलती है जिसे संपादित किया जा रहा है। Chat में आपके द्वारा लिखा गया कोई भी निर्देश दोनों फ़ाइलों को 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 का उपयोग करना उचित है, क्योंकि किसी एक folder में सही और अगले folder में गलत नियम बताने का यही एकमात्र तरीका है। "हर endpoint अपने input को validate करता है" जैसा नियम endpoints के पास होना चाहिए। Root फ़ाइल में यह हर असंबंधित task के दौरान load होगा और इसका कोई लाभ नहीं होगा।

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

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

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

Negative rules के लिए भी स्थान रखें। "dist/ के अंतर्गत मौजूद files को कभी edit न करें; वे npm run build द्वारा generated हैं" एक विशेष गलती को रोकता है। इसमें कारण दिया गया है, इसलिए agent उस समान स्थिति का पता लगा सकता है जिसका आपने सीधे उल्लेख नहीं किया है।

इनमें कभी भी क्या नहीं होना चाहिए

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

वह जानकारी शामिल न करें जिसे agent देखकर स्वयं प्राप्त कर सकता है। Paste की गई directory listing, आपकी dependency list की copy और ऐसा architecture overview जो folder names को दोहराता है—ये सभी लिखने के अगले ही सप्ताह पुराने हो जाते हैं। इस बीच हर session में context की लागत भी बढ़ती है। Pitfalls और उनके कारण रखें। Inventory हटा दें।

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

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

यदि आपके repository में पहले से AGENTS.md है, तो उसकी दूसरी प्रति न रखें। उसे import करें और केवल Claude से संबंधित सामग्री जोड़ें:

@AGENTS.md

## Claude Code

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

यदि आपको कुछ अतिरिक्त जोड़ना नहीं है, तो symlink काम करता है:

ln -s AGENTS.md CLAUDE.md

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

प्रत्येक फ़ाइल को लगभग 200 lines से कम रखें। लंबी फ़ाइलें window का अधिक भाग लेती हैं और निर्देशों का पालन कम हो जाता है। यदि आप देखना चाहते हैं कि उस स्थान के लिए और क्या प्रतिस्पर्धा करता है, तो agent के context window को वास्तव में क्या भरता है इसका विवरण देता है।

एक बात पर विशेष ध्यान दें। AGENTS.md मार्गदर्शन है, permission system नहीं। इसकी सामग्री सामान्य context के रूप में आती है, इसलिए model इसे पढ़ता है और आमतौर पर इसका पालन करता है, लेकिन इसके विपरीत action को कोई चीज़ रोकती नहीं है। ऐसे नियम के लिए जिसे हर बार लागू होना आवश्यक है, जैसे "main पर कभी push न करें", hook या permission setting का उपयोग करें, क्योंकि वे code के रूप में चलते हैं और model के पालन का निर्णय लेने पर निर्भर नहीं होते।

ये फ़ाइलें आपके लिए लिखने वाले टूल

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

agent0ai/dox (July 2026 तक 1,368 stars) AGENTS.md फ़ाइलों के tree को अद्यतन रखने का framework है। यह कोई package या runtime प्रदान नहीं करता। आप इसकी AGENTS.md की सामग्री को अपनी root AGENTS.md में copy करते हैं, और यही installation है। पहले से मौजूद प्रोजेक्ट के लिए आप अपने agent को यह बताते हैं:

Initialize DOX tree for this project now.

इसके बाद agent child AGENTS.md फ़ाइलें और उनके indexes बनाता है, किसी भी चीज़ को edit करने से पहले उस tree को देखता है, और change लागू होने के बाद प्रभावित documentation को update करता है। इसके पीछे यह धारणा है कि agent अपने काम के side effect के रूप में maintain की गई documentation सही रहती है, जबकि व्यक्ति द्वारा manually update की गई documentation सही नहीं रहती।

HUMAN.md, वही युक्ति आपके लिए

Intuition-Lab/personal-model (July 2026 तक 1,260 stars) इस पैटर्न को repository के बजाय किसी व्यक्ति पर लागू करता है। यह project आपके HUMAN.md को आपके द्वारा लिखी गई file के बजाय system के output के रूप में प्रस्तुत करता है: “यह इस बात का जीवंत model है कि अभी क्या महत्वपूर्ण है, आप सामान्यतः निर्णय कैसे लेते हैं और आपका ध्यान किस दिशा में जा रहा है।” यह macOS 13 या उसके बाद के versions पर local रूप से चलता है, macOS की permission देने के बाद activity capture करता है और MCP (model context protocol) के माध्यम से agents को परिणाम उपलब्ध कराता है। संक्षिप्त installation path:

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

अधिकांश लाभ पाने के लिए आपको इनमें से किसी चीज़ की आवश्यकता नहीं है। हाथ से लिखा गया HUMAN.md लगभग 20 lines का होता है: आपकी भूमिका, आपका timezone, वह stack जिसे आप वास्तव में उपयोग करते हैं, वे decisions जिन्हें आप पहले ही ले चुके हैं और दोबारा नहीं खोलना चाहते, तथा आपको वापस कितनी explanation चाहिए। यह project file की तरह बार-बार समझाने की आवश्यकता बचाता है, लेकिन एक स्तर ऊपर।

एक सावधानी रखें। HUMAN.md किसी व्यक्ति की profile होती है, इसलिए यह स्वभावतः sensitive होती है। इसे public repository से बाहर रखें। इसे ~/.claude/CLAUDE.md में रखें, या project root में मौजूद gitignored CLAUDE.local.md में रखें। यह committed file के साथ load होती है और उसी तरह treat की जाती है।

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

यह जानबूझकर छोटा रखा गया है। जो अनुभाग लागू नहीं होते, उन्हें हटा दें। जिन अनुभागों को वर्तमान नहीं रख सकते, उन्हें जोड़ने से बचें।

# 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.

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

FAQ

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

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

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

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

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

हाँ, project से संबंधित हर स्थायी जानकारी के लिए इसे commit करें: build commands, layout और conventions। यही फ़ाइल का उद्देश्य है। इससे आपके teammates के agents उसी context से शुरू होते हैं जिससे आपका agent शुरू होता है। व्यक्तिगत या किसी एक machine से संबंधित जानकारी अलग gitignored फ़ाइल में रखें। Credentials को इनमें से किसी में भी न रखें।

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

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