Monorepo में nested AGENTS.md का उपयोग कैसे करें
Monorepo में एक बड़ी root AGENTS.md फाइल पुरानी हो जाती है और अनावश्यक context का उपयोग करती है। इस गाइड में nested layout का तरीका जानें जिससे agent केवल जरूरी फाइलें पढ़ेगा।
Monorepo में nested AGENTS.md का क्या अर्थ है
Monorepo में nested AGENTS.md का अर्थ है कि एक छोटी फाइल repository के root पर होती है और एक-एक फाइल प्रत्येक service directory के अंदर होती है। Root फाइल में वे कुछ नियम होते हैं जो हर जगह लागू होते हैं, साथ ही यह जानकारी भी होती है कि अन्य फाइलें कहाँ स्थित हैं। प्रत्येक service फाइल में केवल उस directory के लिए कमांड और नियम होते हैं। जब कोई agent services/worker/queue.py को edit करता है, तो वह root फाइल और उस विशिष्ट service की फाइल को पढ़ता है। इस प्रक्रिया में वह उस front end पर कोई context खर्च नहीं करता जिसे वह कभी touch नहीं करेगा।
इसमें कुछ भी install करने की आवश्यकता नहीं है। AGENTS.md एक convention है, और upstream project इसे स्पष्ट रूप से बताता है:
AGENTS.md केवल standard Markdown है। आप अपनी पसंद की किसी भी heading का उपयोग करें; agent केवल आपके द्वारा प्रदान किए गए text को parse करता है।
यही कारण है कि इस तकनीक को सही ढंग से सीखना उपयोगी है। इसका format आपके उपयोग के दौरान नहीं बदलेगा। जो चीज खराब हो सकती है वह है placement और maintenance, और ये दोनों आपकी जिम्मेदारी हैं।
एक बड़ी root AGENTS.md फाइल काम करना क्यों बंद कर देती है?
एक repository की root में स्थित 600-लाइन की एक अकेली AGENTS.md फाइल, जिसमें एक web app, एक background worker और एक Terraform directory शामिल हो, चार अलग-अलग तरीकों से विफल हो जाती है।
यह पुरानी (stale) हो जाती है, क्योंकि इसका कोई मालिक नहीं होता। जो engineer apps/web में एक test script का नाम बदलता है, वह apps/web के अंतर्गत फाइलों को edit कर रहा होता है। root AGENTS.md उस diff में नहीं होती, इसलिए कोई भी reviewer इस विसंगति (mismatch) को नहीं देख पाता। छह सप्ताह बाद, वह फाइल एक ऐसे build step का वर्णन कर रही होती है जो अब मौजूद ही नहीं है, और जिसने इसे तोड़ा था, वह उस बदलाव को भूल चुका होता है।
यह हर task पर context की लागत बढ़ाती है। ये फाइलें session की शुरुआत में ही load हो जाती हैं, इससे पहले कि agent को पता चले कि आप क्या पूछने वाले हैं। Claude Code का documentation इस पर एक संख्या निर्धारित करता है: "प्रति CLAUDE.md फाइल 200 लाइनों से कम का लक्ष्य रखें। लंबी फाइलें अधिक context का उपभोग करती हैं और निर्देशों के पालन को कम करती हैं।" जब निर्देश फाइलों का संयुक्त आकार 32 KiB (डिफ़ॉल्ट project_doc_max_bytes) तक पहुँच जाता है, तो Codex उन्हें merge करना बंद कर देता है। चार services का वर्णन करने वाली एक root फाइल हर एक task के लिए उनमें से तीन पर वह बजट खर्च कर देती है।
निर्देश एक-दूसरे का विरोध करने लगते हैं। web directory को pnpm test की आवश्यकता होती है। worker को pytest -q की। एक ही फाइल में लिखे जाने पर, प्रत्येक नियम केवल कुछ समय के लिए ही सही होता है, इसलिए agent को यह अनुमान लगाना पड़ता है कि कौन सा नियम लागू होता है। Claude Code के docs परिणाम का वर्णन करते हैं: "यदि दो निर्देश एक-दूसरे का विरोध करते हैं, तो Claude मनमाने ढंग से किसी एक को चुन सकता है।" फाइल को विभाजित करने से दूसरा नियम context से बाहर नहीं रहता। Claude Code लोड की गई हर निर्देश फाइल को एक साथ जोड़ देता है (concatenate), बजाय इसके कि एक दूसरे की जगह ले ले। इसलिए root फाइल हमेशा मौजूद रहती है, और एक बार जब agent ने apps/web और services/worker दोनों में फाइलें खोल लीं, तो दोनों directory फाइलें एक साथ context में बैठ जाती हैं। प्रति-directory फाइल जो काम करती है, वह यह है कि प्रत्येक नियम को उस directory से जोड़ देती है जिसे वह नियंत्रित करती है। फाइल के शीर्ष पर directory का नाम लिखें, जैसा कि नीचे दिए गए उदाहरणों में # apps/web के साथ किया गया है, और जब कई फाइलें एक साथ लोड होती हैं, तब भी प्रत्येक command यह बताती है कि वह कहाँ लागू होती है। जब कोई नियम जिसे आपने स्पष्ट रूप से लिखा है, फिर भी अनदेखा कर दिया जाता है, तो निर्देश के लागू न होने के कारणों को समझना, शब्दों को चौथी बार फिर से लिखने से बेहतर है।
यह उन तथ्यों से भर जाती है जिन्हें agent code से पढ़ सकता है। एक directory tree, एक dependency list, प्रत्येक package क्या करता है इसका सारांश। Claude Code का /doctor चेक ठीक इसी को हटाने के लिए मौजूद है। यह "उन सामग्री को काट देता है जिसे Claude codebase से प्राप्त कर सकता है, जैसे directory layouts, dependency lists, और architecture overviews" और केवल "उन कमियों, तर्क, और conventions को रखता है जो tool के डिफ़ॉल्ट से भिन्न हैं।" वह वाक्य सबसे अच्छा परीक्षण है जिसे मैं जानता हूँ कि क्या कोई पंक्ति वास्तव में फाइल में होनी चाहिए।
क्या agent root file को पढ़ता है, या केवल सबसे निकट वाली को?
यहीं पर ज्यादातर लोग model को समझने में गलती करते हैं, इसलिए इसे अपने शब्दों में बताने के बजाय upstream convention को उद्धृत करना बेहतर है:
प्रत्येक package के अंदर एक और AGENTS.md रखें। Agents स्वचालित रूप से directory tree में सबसे निकट वाली file को पढ़ते हैं, इसलिए सबसे करीबी file को प्राथमिकता मिलती है और प्रत्येक subproject अपनी विशिष्ट instructions दे सकता है।
और conflicts के बारे में:
edit की गई file के सबसे करीब वाली AGENTS.md मान्य होती है; स्पष्ट user chat prompts हर चीज से ऊपर होते हैं।
"प्राथमिकता मिलती है" (takes precedence) का अर्थ कई लोग यह निकालते हैं कि "root file को अनदेखा कर दिया जाता है"। ऐसा नहीं है। जिन tools में यह convention लागू है, उनमें repository root से लेकर working directory तक के रास्ते में आने वाली हर file को पढ़ा जाता है और आपस में जोड़ दिया जाता है। सबसे निकट वाली file केवल तब प्रभावी होती है जब दो files एक ही विषय पर अलग-अलग निर्देश देती हैं।
Codex इस प्रक्रिया के बारे में स्पष्ट है: "Codex root से नीचे तक की files को जोड़ता है (concatenate करता है), उन्हें खाली लाइनों के साथ जोड़ता है। आपकी वर्तमान directory के करीब वाली files पहले के निर्देशों को override कर देती हैं।" Claude Code भी इसी रास्ते पर चलता है। session शुरू होने पर यह "आपकी working directory और उसके ऊपर की directories में मौजूद हर AGENTS.md और .claude/AGENTS.md" को पढ़ता है, और इसके docs loading model को स्पष्ट रूप से बताते हैं: "खोजे गए सभी files को एक-दूसरे को override करने के बजाय context में जोड़ दिया जाता है।" Working directory के नीचे की directories अलग तरह से व्यवहार करती हैं: Claude Code किसी subdirectory की AGENTS.md को मांग पर load करता है, "जब Claude वहां Read tool के साथ कोई file खोलता है।"
इसके दो व्यावहारिक परिणाम होते हैं। Root file repository में हर session के लिए एक prefix होती है, इसलिए वहां लिखी हर line को ऐसा मानें जिसके लिए आप सप्ताह में सौ बार भुगतान करते हैं। प्रति-directory file की कोई लागत तब तक नहीं होती जब तक agent उस directory में कोई file न खोले, जिसका अर्थ है कि वहां विस्तार से जानकारी देना सस्ता है और वहीं दी जानी चाहिए।
इस व्यवहार की पुष्टि 27 October 2026 को Codex और Claude Code के documentation के आधार पर की गई थी। Tools इस convention को थोड़ा अलग तरीके से लागू करते हैं और वे बदलते भी रहते हैं, इसलिए अपनी टीम द्वारा उपयोग किए जाने वाले agent के लिए loading rules की पुष्टि अवश्य कर लें।
तीन सेवाओं वाले रिपॉजिटरी के लिए एक कार्यशील लेआउट
repo/
AGENTS.md rules true everywhere, plus the map
apps/web/AGENTS.md TypeScript client, Vite, Vitest
services/worker/AGENTS.md Python queue consumer, pytest
infra/AGENTS.md Terraform and the deploy scriptsरूट फ़ाइल को जानबूझकर संक्षिप्त रखा गया है। यह बताती है कि कहाँ देखना है, और इसमें केवल वही नियम हैं जो हर डायरेक्टरी पर लागू होते हैं।
# AGENTS.md
This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.
- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts
## Rules for the whole repository
- The package manager is `pnpm`. `npm install` writes a second lockfile
that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
`schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
in the same commit.प्रति-डायरेक्टरी फ़ाइल में विवरण होता है, और यह उतनी लंबी हो सकती है जितनी उस डायरेक्टरी के लिए आवश्यक हो।
# apps/web
Browser client. Vite and React, TypeScript with `strict` on.
## Commands
- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.
## Conventions
- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
because the client attaches the auth header and retries on 429.
## Traps
- `pnpm build` does not type check. Vite strips the types instead of
checking them, so a broken type still produces a green build.
Run `pnpm typecheck` as a separate step.वर्कर फ़ाइल का आकार समान है लेकिन सामग्री अलग है: इंस्टॉल कमांड, pytest -q, वह कारण कि क्यों कंज्यूमर को आइडम्पोटेंट (idempotent) रहना चाहिए, और वह माइग्रेशन जिसे टेस्ट पास होने से पहले चलना आवश्यक है। इन्फ्रा फ़ाइल वह जगह है जहाँ आप वे नियम लिखते हैं जो किसी एजेंट को नुकसान पहुँचाने से रोकते हैं। कभी भी terraform apply न चलाएं। terraform plan चलाएं और वहीं रुक जाएं, और उस स्टेट बैकएंड का नाम दें जो पहले से कॉन्फ़िगर है ताकि एजेंट एक नया बैकएंड इनिशियलाइज़ करने का प्रयास न करे।
ध्यान दें कि इनमें से किसी भी फ़ाइल में क्या नहीं है: प्रत्येक सेवा किस उद्देश्य के लिए है, इसका विवरण। यह मनुष्यों के लिए है। अपस्ट्रीम भी यही रेखा खींचता है, यह कहते हुए कि "README.md फ़ाइलें मनुष्यों के लिए हैं: क्विक स्टार्ट, प्रोजेक्ट विवरण और योगदान दिशानिर्देश", जबकि AGENTS.md में "कोडिंग एजेंटों के लिए आवश्यक अतिरिक्त, कभी-कभी विस्तृत संदर्भ होता है: बिल्ड स्टेप्स, टेस्ट और कन्वेंशन।" AGENTS.md और मानव-केंद्रित README के बीच का विभाजन उस सीमा को वाक्य-दर-वाक्य स्पष्ट करता है, और एक DESIGN.md जो यह रिकॉर्ड करता है कि कोड को इस तरह क्यों बनाया गया है तीसरी फ़ाइल को कवर करता है, जो कमांड के बजाय निर्णयों की व्याख्या करती है।
कोड बदलने पर फाइल को कौन अपडेट करता है?
एक नियम है, और यह root फाइल में जाता है: जो कोई भी किसी directory में कोड बदलता है, वह उसी commit में उस directory की AGENTS.md को अपडेट करता है।
यह एक तकनीकी कारण से काम करता है, न कि सांस्कृतिक कारण से। प्रति-directory फाइल उसी diff में होती है जिसमें कोड होता है, इसलिए pull request का reviewer दोनों को एक साथ देख लेता है। एक root फाइल सबकी होती है, जिसका अर्थ है कि वह किसी की नहीं है, और वह उस diff में कभी नहीं होती जिसे कोई पहले से पढ़ रहा है।
इस नियम को pull request पर एक जांच (check) के साथ लागू करें। यह प्रत्येक बदली गई फाइल के ऊपर निकटतम AGENTS.md को ढूंढता है, और फिर रिपोर्ट करता है कि उस फाइल को touch नहीं किया गया था।
#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)
nearest_doc() {
d=$(dirname "$1")
while [ "$d" != "." ]; do
if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
d=$(dirname "$d")
done
echo "AGENTS.md"
}
printf '%s\n' "$changed" | while read -r f; do
[ -n "$f" ] || continue
case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
doc=$(nearest_doc "$f")
printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
echo "note: $f changed but $doc was not updated"
doneएक branch पर जिसने API client को फिर से तैयार किया लेकिन docs को नहीं छुआ, आउटपुट ऐसा दिखता है:
note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updatedइसे failure के बजाय एक warning बनाए रखें। एक सख्त gate लोगों को फाइल में एक खाली लाइन जोड़ने के लिए प्रेरित करता है ताकि CI green हो जाए, और एक ऐसी फाइल जिसे केवल robot को संतुष्ट करने के लिए edit किया गया हो, वह बिल्कुल भी फाइल न होने से कम मूल्यवान है। यह warning reviewer को पूछने के लिए एक सवाल देती है, और यही वह हिस्सा है जो वास्तव में काम करता है।
मैं कैसे पता लगाऊं कि AGENTS.md पुराना (stale) हो गया है?
आप आज दो जाँच कर सकते हैं, और एक लक्षण ऐसा है जो आपको सेशन के दौरान दिखाई देगा।
प्रत्येक फ़ाइल की आयु की तुलना उस कोड की आयु से करें जिसका वह वर्णन करती है। %cs कमिट की तारीख को YYYY-MM-DD के रूप में प्रिंट करता है।
for f in $(git ls-files '*AGENTS.md'); do
d=$(dirname "$f")
printf '%s doc:%s code:%s\n' "$f" \
"$(git log -1 --format=%cs -- "$f")" \
"$(git log -1 --format=%cs -- "$d")"
doneapps/web/AGENTS.md doc:2026-02-11 code:2026-08-07
services/worker/AGENTS.md doc:2026-07-29 code:2026-08-09
infra/AGENTS.md doc:2026-08-01 code:2026-08-01कोड की तारीख से छह महीने पुरानी दस्तावेज़ की तारीख यह साबित नहीं करती कि फ़ाइल गलत है। यह केवल आपको यह बताती है कि सबसे पहले कौन सी फ़ाइल पढ़नी है, और एक सेकंड में होने वाली जाँच से आपको बस इतना ही चाहिए।
उन पाथ (paths) को खोजें जो अब मौजूद नहीं हैं। दस्तावेज़ एक बहुत ही विशिष्ट तरीके से खराब होते हैं: वे ऐसे कोड का वर्णन करना जारी रखते हैं जिसे हटा दिया गया है। इन फ़ाइलों में प्रत्येक पाथ बैकटिक (backticks) में लिखा होता है, इसलिए उन्हें निकालना और टेस्ट करना आसान है।
grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
[ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
doneइसे CI में जोड़ने के बजाय आउटपुट को पढ़ें। यह src/**/*.ts जैसे ग्लोब्स (globs) और आपके द्वारा उद्धृत किसी भी URL को भी फ्लैग करता है, क्योंकि दोनों में स्लैश होता है और कोई भी डिस्क पर फ़ाइल नहीं है। Claude Code v2.1.283 या उसके बाद के वर्ज़न पर, /doctor prompt-audit आपके लिए एक समान पास चलाता है: यह "ऐसी फ़ाइलों या कमांड्स के संदर्भों को खोजता है जो मौजूद नहीं हैं" और उन फ़ाइलों को खोजता है जो एक-दूसरे का खंडन करती हैं, डिफ़ॉल्ट रूप से आपकी AGENTS.md फ़ाइलों को कवर करता है, और जब तक आप इसे प्रस्तावित बदलावों को लागू करने के लिए नहीं कहते, तब तक कुछ भी नहीं बदलता है।
सेशन के दौरान दिखने वाला लक्षण। एजेंट फ़ाइल को पढ़ता है, src/api/client.ts को खोलने की कोशिश करता है क्योंकि फ़ाइल ने उसे ऐसा करने के लिए कहा था, और टूल यह रिटर्न करता है:
No such file or directoryइसलिए यह उचित काम करता है और अपना खुद का fetch रैपर लिखता है। यही एक पुरानी फ़ाइल की वास्तविक कीमत है। एजेंट आपके दस्तावेज़ों को अनदेखा नहीं करता है। यह दस्तावेज़ों का पालन करता है, एक ऐसे पाथ पर पहुँचता है जिसे तीन महीने पहले हटा दिया गया था, और उस कोड को फिर से बनाता है जो आपके पास पहले से मौजूद है। Ponytail, जो एजेंट को सबसे छोटे काम करने वाले बदलाव तक सीमित रखता है, जैसे कौशल उस पुनर्निर्माण की प्रवृत्ति को दुर्लभ बनाते हैं, लेकिन यह उस हेल्पर को नहीं खोज सकता जिसे आपकी फ़ाइल ने गलत जगह पर पॉइंट किया है।
क्या Claude Code AGENTS.md फाइलों को पढ़ता है?
हाँ, Claude Code v2.1.277 से, और सटीक नियम मायने रखता है क्योंकि नेस्टेड लेआउट उसी पर निर्भर करता है। 27 अक्टूबर 2026 को डॉक्यूमेंटेशन के अनुसार जाँच की गई: "Claude Code आपके प्रोजेक्ट निर्देशों के रूप में AGENTS.md को पढ़ सकता है, इसलिए अन्य कोडिंग एजेंट्स के लिए पहले से सेटअप की गई रिपॉजिटरी बिना किसी CLAUDE.md, इम्पोर्ट या सेटिंग को जोड़े काम करती है।" डिफ़ॉल्ट Project instructions मान, claude-md-or-agents-md, यह पढ़ता है: "आपकी AGENTS.md फाइलें जब आपकी वर्किंग डायरेक्टरी में या उसके ऊपर कोई CLAUDE.md या CLAUDE.local.md न हो।" नेस्टेड फाइलें भी इसमें शामिल हैं: Claude किसी सबडायरेक्टरी की AGENTS.md को तब पढ़ता है "जब Claude वहां Read टूल के साथ कोई फाइल खोलता है", बशर्ते "उस सबडायरेक्टरी में अपनी खुद की तीन CLAUDE.md फाइलों में से कोई न हो।" वे तीन फाइलें CLAUDE.md, .claude/CLAUDE.md और CLAUDE.local.md हैं, इसलिए apps/web में एक व्यक्तिगत CLAUDE.local.md, apps/web/AGENTS.md को लोड होने से रोकने के लिए पर्याप्त है।
यह हर AGENTS.md के बगल में CLAUDE.md रखने की पुरानी सलाह को एक जाल में बदल देता है। आपकी वर्किंग डायरेक्टरी में या उसके ऊपर एक AGENTS.md और एक CLAUDE.md या CLAUDE.local.md होने पर, डॉक्यूमेंट्स कहते हैं कि Claude "केवल आपकी CLAUDE.md फाइलें" पढ़ता है। एक .claude/CLAUDE.md भी इसी तरह गिना जाता है। रूट पर मौजूद एक साथी फाइल जिसमें एक Claude-विशिष्ट लाइन हो, वह रास्ते में आने वाली हर AGENTS.md को छिपा देती है, और एक व्यक्तिगत CLAUDE.local.md भी ऐसा ही करता है। यदि आप एक को रखना चाहते हैं, तो /config टाइप करें और Project instructions को claude-md-and-agents-md पर सेट करें, जो दोनों को पढ़ता है, पहले प्रत्येक डायरेक्टरी की CLAUDE.md और उसके बाद उसकी AGENTS.md।
केवल एक वर्ज़न नंबर यह पुष्टि नहीं करता कि यह काम कर गया। आपको v2.1.277 या बाद के वर्ज़न की आवश्यकता है, लेकिन v2.1.281 से पहले कुछ सेशन, जैसे Amazon Bedrock पर या डिसेबल टेलीमेट्री के साथ, केवल CLAUDE.md फाइलें पढ़ते हैं, और कुछ मामलों में v2.1.276 या उससे पहले से अपग्रेड करने के बाद पहला सेशन AGENTS.md को भी छोड़ देता है: डॉक्यूमेंट्स कहते हैं "Claude आपके अगले सेशन से AGENTS.md पढ़ता है"। इसलिए सेशन की खुद जाँच करें। एक इंटरैक्टिव सेशन में Claude Code no CLAUDE.md found; AGENTS.md loaded: जैसी एक लाइन प्रिंट करता है जिसके बाद पाथ होता है, और वर्तमान वर्ज़न में /memory फाइल को लिस्ट करता है। v2.1.280 से पहले, /memory और /context उस AGENTS.md को लिस्ट नहीं करते थे जिसे Claude सीधे पढ़ता था, इसलिए उन वर्ज़न पर Claude से पूछें कि उसके प्रोजेक्ट निर्देश क्या कहते हैं।
इम्पोर्ट फॉर्म तब भी सही है जहाँ Claude सीधे AGENTS.md को नहीं पढ़ सकता: एक पुराना वर्ज़न, Amazon Bedrock पर या डिसेबल टेलीमेट्री के साथ v2.1.281 से पहले का सेशन, एक ऐसा सेशन जहाँ इसे पढ़ने वाला इन-बिल्ट प्लगइन डिसेबल हो, या एक प्रोजेक्ट जो claude-md पर सेट Project instructions के साथ एक CLAUDE.md रखता हो। इसे services/worker/CLAUDE.md में डालें:
@AGENTS.md
## Claude Code
Use plan mode for changes under `services/worker/migrations/`.सिमलिंक फॉर्म तब सही है जब टूल-विशिष्ट जोड़ने के लिए कुछ न हो।
git ls-files '*AGENTS.md' | while read -r f; do
ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.mdln सफल होने पर कुछ भी प्रिंट नहीं करता है, इसलिए लिस्टिंग की जाँच करें: apps/web/CLAUDE.md -> AGENTS.md। फिर एक सेशन शुरू करें और /context चलाएँ, जहाँ लोड की गई फाइलें Memory files के अंतर्गत दिखाई देंगी। Windows पर एक सिमलिंक के लिए एडमिनिस्ट्रेटर अधिकारों या डेवलपर मोड की आवश्यकता होती है, और Git एक कमिटेड सिमलिंक को सादे टेक्स्ट फाइल के रूप में चेक-आउट करता है जब तक कि core.symlinks इनेबल न हो, जो उस क्लोन को आपके निर्देशों की जगह एक लाइन वाली CLAUDE.md के साथ छोड़ देता है। यदि रिपॉजिटरी को क्लोन करने वाला कोई भी व्यक्ति Windows पर काम करता है, तो @AGENTS.md इम्पोर्ट का उपयोग करें। यदि आपने Claude Code द्वारा अपने आप AGENTS.md पढ़ने से पहले कोई भी वर्कअराउंड सेटअप किया है, तो आप उसे छोड़ सकते हैं: डॉक्यूमेंट्स कहते हैं कि इम्पोर्ट रखने से "Claude कभी भी AGENTS.md को दो बार नहीं पढ़ता", और एक सिमलिंक की गई CLAUDE.md को एक बार पढ़ा जाता है।
एक जाल इसके साथ जुड़ा है। /compact के बाद, प्रोजेक्ट-रूट CLAUDE.md को डिस्क से दोबारा पढ़ा जाता है, लेकिन सबडायरेक्टरीज़ में नेस्टेड फाइलें दोबारा इंजेक्ट नहीं की जाती हैं। Claude Code उन्हें मांग पर दोबारा लोड करता है, अगली बार जब एजेंट उस डायरेक्टरी में किसी फाइल के साथ काम करता है। डॉक्यूमेंटेशन CLAUDE.md फाइलों के लिए इसे स्पष्ट करता है और सीधे पढ़े गए AGENTS.md के लिए अलग से कॉम्पैक्शन का वर्णन नहीं करता है, इसलिए उम्मीद करें कि दोनों नामों की नेस्टेड फाइलें इसी तरह व्यवहार करेंगी। यदि प्रति-डायरेक्टरी नियम लंबे सेशन के बीच में लागू होना बंद हो जाए, तो आमतौर पर यही कारण होता है, और डायरेक्टरी में किसी भी फाइल को पढ़ने से वह वापस आ जाता है।
सेटिंग्स जो अन्य एजेंट्स को AGENTS.md की ओर निर्देशित करती हैं
Codex मूल रूप से AGENTS.md पढ़ता है। प्रत्येक स्तर पर यह पहले AGENTS.override.md की जाँच करता है, जो साझा फाइल को एडिट किए बिना एक डायरेक्टरी को लोकल ओवरराइड देता है। एक बार संयुक्त आकार 32 KiB तक पहुँच जाने पर यह मर्ज करना बंद कर देता है, जो डिफ़ॉल्ट project_doc_max_bytes है, और रूट फाइल को छोटा रखने का यह एक और कारण है।
Aider इसे .aider.conf.yml के माध्यम से read: AGENTS.md लाइन के साथ लेता है।
Gemini CLI इसे .gemini/settings.json के माध्यम से { "context": { "fileName": "AGENTS.md" } } के साथ लेता है।
अपस्ट्रीम उन रिपॉजिटरी के लिए बैकवर्ड-कम्पैटिबल रीनेम का दस्तावेजीकरण करता है जो अभी भी पुराने एकल नाम का उपयोग कर रही हैं: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md।
एक बहुत बड़े मोनोरिपो में, Claude Code की claudeMdExcludes सेटिंग पाथ या ग्लोब द्वारा पूर्वज फाइलों को छोड़ देती है, जो तब उपयोगी होता है जब किसी अन्य टीम की डायरेक्टरी आपकी डायरेक्टरी के ऊपर स्थित हो। इसके पैटर्न उन AGENTS.md फाइलों पर भी लागू होते हैं जिन्हें Claude Code पढ़ता है।
यह agent memory या skill से किस प्रकार भिन्न है?
ये तंत्र देखने में समान लगते हैं, लेकिन इनके विफल होने के तरीके पूरी तरह अलग हैं। इसलिए यह स्पष्ट होना आवश्यक है कि आप किस तंत्र का उपयोग करना चाहते हैं।
AGENTS.md आपके द्वारा लिखा जाता है, git में commit किया जाता है, pull request में review किया जाता है, और यह उन सभी के लिए समान होता है जो repository को clone करते हैं। Agent memory को agent द्वारा लिखा जाता है, repository के बाहर store किया जाता है, और यह एक मशीन तक सीमित होता है। Claude Code का documentation भी यही अंतर स्पष्ट करता है: CLAUDE.md में आपके द्वारा लिखे गए "निर्देश और नियम" (Instructions and rules) होते हैं, auto memory में Claude द्वारा सीखे गए "पैटर्न और सीख" (Learnings and patterns) होते हैं, और memory directory को मशीनों के बीच साझा नहीं किया जाता है। इसकी जाँच सरल है। यदि कोई तथ्य किसी सहकर्मी के लिए fresh clone पर भी सत्य होना चाहिए, तो वह memory में नहीं रह सकता। How agent memory persists between sessions इस विषय के उस पहलू को कवर करता है।
Skill तीसरी चीज है। AGENTS.md वह context है जो हर session में load होता है; skill वह प्रक्रिया है जो आवश्यकता पड़ने पर load होती है। Claude Code का documentation एक उपयोगी नियम बताता है: "यदि कोई entry बहु-चरणीय प्रक्रिया (multi-step procedure) है या केवल codebase के एक हिस्से के लिए मायने रखती है, तो उसे skill या path-scoped rule में ले जाएँ।" उस वाक्य का दूसरा भाग वही है जिसे nested AGENTS.md हल करता है। पहला भाग agent skills के लिए है, और जब एक ही प्रक्रिया की आवश्यकता एक से अधिक repository में हो, तो share the skill across repos का उपयोग करें, बजाय इसके कि एक ही पैराग्राफ को दस अलग-अलग AGENTS.md फाइलों में copy-paste करें।
Upstream का कहना है कि "इस लेख को लिखते समय मुख्य OpenAI repo में 88 AGENTS.md फाइलें थीं"। यह संख्या ही अपने आप में पूरा तर्क है। एक बड़ी repository को एक बड़ी फाइल की आवश्यकता नहीं होती है। इसे और अधिक छोटी फाइलों की आवश्यकता होती है, जिनमें से प्रत्येक उस code के बगल में स्थित हो जिसका वह वर्णन करती है, और प्रत्येक का स्वामित्व उस व्यक्ति के पास हो जिसने अंतिम बार उस code में बदलाव किया है।
FAQ
क्या nested AGENTS.md root file की जगह ले लेता है या उसमें जुड़ जाता है?
यह उसमें जुड़ जाता है। Upstream का कहना है कि "सबसे नज़दीकी फाइल प्रभावी होती है", जो यह बताती है कि conflict होने पर क्या होगा, न कि यह कि क्या लोड होगा। Codex "root से नीचे की ओर फाइलों को जोड़ता है और उन्हें खाली लाइनों से अलग करता है", और Claude Code वर्किंग डायरेक्टरी से ऊपर की ओर जाते हुए मिलने वाली हर फाइल को जोड़ता है, न कि उन्हें ओवरराइड करता है। सबसे नज़दीकी फाइल केवल तब प्रभावी होती है जब दो फाइलें एक ही विषय पर अलग-अलग निर्देश देती हैं। साझा नियमों को एक बार root में लिखें और उन्हें हर डायरेक्टरी में न दोहराएं।
root AGENTS.md कितना बड़ा होना चाहिए?
इतना छोटा कि आपको उस रिपॉजिटरी में किए जाने वाले हर अनुरोध के ऊपर इसे पेस्ट करने में कोई आपत्ति न हो, क्योंकि वास्तव में यही होता है। Claude Code का डॉक्यूमेंटेशन प्रति फाइल 200 लाइनों से कम रखने का सुझाव देता है और चेतावनी देता है कि लंबी फाइलें "अनुपालन (adherence) को कम करती हैं"। Codex डिफ़ॉल्ट रूप से 32 KiB पर निर्देश फाइलों को मर्ज करना बंद कर देता है। यदि आपकी root फाइल चार सेवाओं का वर्णन करती है, तो किसी एक कार्य के लिए इसका अधिकांश हिस्सा अनावश्यक है। विवरण को प्रति-डायरेक्टरी फाइलों में ले जाएं और पीछे एक मैप छोड़ दें।
मैं इन फाइलों को पुराना (stale) होने से कैसे रोकूँ?
root फाइल में एक नियम रखें: जो कोई भी किसी डायरेक्टरी में कोड बदलता है, वह उसी कमिट में उस डायरेक्टरी की AGENTS.md को भी अपडेट करे। फाइल को कोड के बगल में रखने से नियम का पालन सुनिश्चित होता है, क्योंकि वह बदलाव उसी पुल रिक्वेस्ट डिफ (pull request diff) में दिखाई देता है जिसे एक इंसान पहले से पढ़ रहा है। एक CI चेतावनी जोड़ें जो प्रत्येक बदले हुए पाथ को उसके ऊपर की सबसे नज़दीकी AGENTS.md से मैप करे, और समय-समय पर प्रत्येक फाइल पर git log -1 --format=%cs की तुलना उस डायरेक्टरी पर चलाए गए उसी कमांड से करें जिसका वह वर्णन करती है।
क्या Claude Code AGENTS.md फाइलों को पढ़ता है?
हाँ, v2.1.277 से। 27 October 2026 को डॉक्यूमेंटेशन के अनुसार, जब आपकी वर्किंग डायरेक्टरी या उसके ऊपर कोई CLAUDE.md या CLAUDE.local.md नहीं होता है, तो Claude Code डिफ़ॉल्ट रूप से AGENTS.md को पढ़ता है। और जब यह Read टूल के साथ किसी फाइल को खोलता है और उस सब-डायरेक्टरी में अपनी कोई CLAUDE.md, .claude/CLAUDE.md या CLAUDE.local.md नहीं होती है, तो यह उस सब-डायरेक्टरी की AGENTS.md को पढ़ता है। प्रत्येक AGENTS.md के बगल में CLAUDE.md न जोड़ें: वर्किंग डायरेक्टरी या उसके ऊपर एक फाइल होने पर, Claude केवल "Your CLAUDE.md files" पढ़ता है। यदि आपको CLAUDE.md की भी आवश्यकता है, तो /config में Project instructions को claude-md-and-agents-md पर सेट करें, या इसकी पहली लाइन पर @AGENTS.md लिखें। एक सेशन में /memory चलाएं और पुष्टि करें कि AGENTS.md पाथ सूची में दिखाई देता है।
मैं ऐसा नियम कहाँ रखूँ जो केवल कभी-कभी मायने रखता है?
AGENTS.md में नहीं। वह फाइल हर सेशन में लोड होती है, इसलिए उसकी हर लाइन आपके द्वारा टाइप किए गए वास्तविक अनुरोध के साथ ध्यान आकर्षित करने के लिए प्रतिस्पर्धा करती है। कई चरणों वाली प्रक्रिया जिसकी आवश्यकता कभी-कभी होती है, वह एक स्किल (skill) में होनी चाहिए, जो मांग पर लोड होती है। जो नियम किसी एक डायरेक्टरी पर लागू होता है, वह उस डायरेक्टरी की AGENTS.md में होना चाहिए। कोई तथ्य जिसे एजेंट सीधे कोड से पढ़ सकता है, जैसे कि डायरेक्टरी ट्री या डिपेंडेंसी लिस्ट, उसे कहीं भी रखने की आवश्यकता नहीं है।