SSD Nodes Learn Hosting plans →
मार्गदर्शक Matt Connorद्वारे Matt Connor · अपडेटेड 2026-10-30

monorepo साठी nested AGENTS.md रचना कशी करावी

एकच root AGENTS.md कालबाह्य होऊन agent ने न उघडलेल्या directory चा context वाया घालवते. nested रचनेत root आणि service-विशिष्ट नियम वेगळे ठेवा.

monorepo मध्ये nested AGENTS.md याचा अर्थ

monorepo मधील nested AGENTS.md म्हणजे repository root मध्ये एक लहान फाइल आणि प्रत्येक service directory मध्ये आणखी एक फाइल. Root फाइलमध्ये सर्व ठिकाणी लागू होणारे मोजके नियम आणि इतर फाइल्स कुठे आहेत याचा नकाशा असतो. प्रत्येक service फाइलमध्ये फक्त त्या directory साठीचे commands आणि conventions असतात. एखादा agent services/worker/queue.py संपादित करताना root फाइल आणि worker फाइल वाचतो. त्यामुळे तो कधीही न बदलणाऱ्या front end संदर्भात context वापरत नाही.

काहीही install करण्याची गरज नाही. AGENTS.md ही एक convention आहे. Upstream project हे स्पष्टपणे सांगतो:

AGENTS.md हा फक्त standard Markdown आहे. तुम्हाला आवडतील ती headings वापरा; तुम्ही दिलेला मजकूर agent फक्त parse करतो.

म्हणूनच हे तंत्र योग्य पद्धतीने शिकणे उपयुक्त आहे. Format तुमच्या वापरात बदलणार नाही. अडचण placement आणि maintenance मुळे निर्माण होते. या दोन्हींची जबाबदारी तुमची आहे.

एकाच मोठ्या root AGENTS.md फाईलचे काम करणे का थांबते?

एका वेब ॲप, बॅकग्राउंड वर्कर आणि Terraform डिरेक्टरी असलेल्या रिपॉझिटरीच्या रूटवर असलेली 600 ओळींची एकच AGENTS.md फाईल चार वेगवेगळ्या कारणांमुळे अपयशी ठरते.

ती कालबाह्य होते, कारण तिचा कोणीही मालक नसतो. जो इंजिनिअर apps/web मधील टेस्ट स्क्रिप्टचे नाव बदलतो, तो apps/web अंतर्गत असलेल्या फाईल्समध्ये बदल करत असतो. रूटवरील AGENTS.md त्या diff मध्ये नसल्यामुळे, कोणत्याही रिव्ह्यूअरला त्यातील विसंगती दिसत नाही. सहा आठवड्यांनंतर, ती फाईल अशा बिल्ड स्टेपचे वर्णन करते जी आता अस्तित्वातच नाही आणि ज्याने ती बदलली होती, तो व्यक्ती तो बदल विसरून गेलेला असतो.

प्रत्येक कामासाठी ती संदर्भाचा (context) खर्च वाढवते. ही फाईल सेशनच्या सुरुवातीलाच लोड होते, म्हणजे एजंटला तुम्ही काय विचारणार आहात हे माहीत असण्याआधीच ती लोड झालेली असते. Claude Code चे डॉक्युमेंटेशन यावर स्पष्ट सांगते: "प्रत्येक CLAUDE.md फाईल 200 ओळींच्या आत ठेवा. मोठ्या फाईल्स जास्त कॉन्टेक्स्ट वापरतात आणि सूचनांचे पालन कमी करतात." जेव्हा इन्स्ट्रक्शन फाईल्सचा एकत्रित आकार 32 KiB (डिफॉल्ट project_doc_max_bytes) पर्यंत पोहोचतो, तेव्हा Codex त्यांना मर्ज करणे थांबवते. चार सेवांचे दस्तऐवजीकरण करणारी रूट फाईल प्रत्येक कामासाठी त्यातील तीन सेवांचा कोटा विनाकारण वापरते.

सूचना एकमेकांशी विसंगत ठरू लागतात. वेब डिरेक्टरीला pnpm test ची गरज असते. वर्करला pytest -q ची गरज असते. एकाच फाईलमध्ये लिहिल्यामुळे, प्रत्येक नियम फक्त काही वेळाच योग्य ठरतो, त्यामुळे एजंटला कोणता नियम लागू होतो याचा अंदाज घ्यावा लागतो. Claude Code चे डॉक्स याचा परिणाम स्पष्ट करतात: "जर दोन सूचना एकमेकांशी विसंगत असतील, तर Claude कोणतीही एक मनमानी पद्धतीने निवडू शकतो." फाईल विभागल्यामुळे दुसरा नियम कॉन्टेक्स्टच्या बाहेर राहत नाही. Claude Code लोड केलेल्या सर्व इन्स्ट्रक्शन फाईल्स एकत्र करते, त्यामुळे रूट फाईल नेहमीच तिथे असते. एकदा का एजंटने apps/web आणि services/worker दोन्हीमधील फाईल्स उघडल्या की, दोन्ही डिरेक्टरी फाईल्स एकाच वेळी कॉन्टेक्स्टमध्ये येतात. प्रत्येक डिरेक्टरीसाठी स्वतंत्र फाईल ठेवल्याने प्रत्येक नियम त्या डिरेक्टरीशी जोडला जातो. फाईलच्या सुरुवातीला डिरेक्टरीचे नाव लिहा, जसे खालील उदाहरणांमध्ये # apps/web सह दिले आहे. यामुळे जेव्हा अनेक फाईल्स एकाच वेळी लोड होतात, तेव्हा प्रत्येक कमांड कुठे लागू होते हे स्पष्ट राहते. जेव्हा तुम्ही स्पष्टपणे लिहिलेला नियम दुर्लक्षित केला जातो, तेव्हा सूचना का अमलात येत नाही याची कारणे शोधणे, हे पुन्हा पुन्हा शब्द बदलण्यापेक्षा जास्त प्रभावी ठरते.

ती अशा माहितीने भरते जी एजंट कोड वाचूनही मिळवू शकतो. डिरेक्टरी ट्री, डिपेंडन्सी लिस्ट, प्रत्येक पॅकेज काय करते याचा सारांश. Claude Code चे /doctor चेक नेमके हेच काढून टाकण्यासाठी असते. ते "Claude कोडबेसमधून जी माहिती मिळवू शकतो, जसे की डिरेक्टरी लेआउट, डिपेंडन्सी लिस्ट आणि आर्किटेक्चर ओव्हरव्ह्यू, ते काढून टाकते" आणि "केवळ अशा त्रुटी, तर्क आणि कन्व्हेन्शन्स ठेवते जे टूलच्या डिफॉल्टपेक्षा वेगळे आहेत." एखादी ओळ फाईलमध्ये असावी की नाही, हे तपासण्यासाठी हे वाक्य सर्वोत्तम निकष आहे.

एजंट रूट फाईल वाचतो की फक्त जवळची फाईल?

येथेच बहुतेक लोक मॉडेलबद्दल चुकीचा समज करून घेतात, त्यामुळे त्याचे स्पष्टीकरण स्वतःच्या शब्दांत देण्याऐवजी अपस्ट्रीम कन्व्हेन्शन (upstream convention) उद्धृत करणे योग्य ठरेल:

प्रत्येक पॅकेजमध्ये एक वेगळी AGENTS.md फाईल ठेवा. एजंट आपोआप डिरेक्टरी ट्री मधील सर्वात जवळची फाईल वाचतात, त्यामुळे जवळची फाईल प्राधान्य (precedence) घेते आणि प्रत्येक सबप्रोजेक्ट स्वतःच्या गरजेनुसार सूचना देऊ शकतो.

आणि कॉन्फ्लिक्ट्स (conflicts) बद्दल:

एडिट केलेल्या फाईलच्या सर्वात जवळ असलेली AGENTS.md फाईल प्रभावी ठरते; युजरने चॅटमध्ये दिलेल्या स्पष्ट सूचना इतर सर्व गोष्टींवर मात करतात.

"प्राधान्य घेते" (takes precedence) याचा अर्थ अनेकांना "रूट फाईल दुर्लक्षित केली जाते" असा होतो. तसे नाही. हे कन्व्हेन्शन राबवणाऱ्या टूल्समध्ये, रिपॉझिटरी रूटपासून ते वर्किंग डिरेक्टरीपर्यंतच्या मार्गावरील प्रत्येक फाईल वाचली जाते आणि एकत्र केली जाते. जेव्हा दोन फाईल्स एकाच विषयावर भिन्न सूचना देतात, तेव्हाच सर्वात जवळची फाईल प्रभावी ठरते.

Codex या यंत्रणेबद्दल स्पष्ट आहे: "Codex रूटपासून खालपर्यंतच्या फाईल्सना एकत्र करते (concatenate) आणि त्यांना रिकाम्या ओळींनी जोडते. तुमच्या सध्याच्या डिरेक्टरीच्या जवळ असलेल्या फाईल्स आधीच्या मार्गदर्शक सूचनांना ओव्हरराइड करतात." Claude Code देखील याच मार्गाचा अवलंब करते. सेशन सुरू होताना ते "तुमच्या वर्किंग डिरेक्टरीमधील आणि त्यावरील डिरेक्टरीजमधील प्रत्येक AGENTS.md आणि .claude/AGENTS.md" वाचते आणि त्याचे डॉक्युमेंटेशन लोडिंग मॉडेल स्पष्टपणे सांगते: "सर्व सापडलेल्या फाईल्स एकमेकांना ओव्हरराइड करण्याऐवजी कॉन्टेक्स्टमध्ये एकत्र केल्या जातात." वर्किंग डिरेक्टरीच्या खालील डिरेक्टरीज वेगळ्या प्रकारे वागतात: Claude Code सबडिरेक्टरीची AGENTS.md फाईल गरजेनुसार लोड करते, "जेव्हा Claude तिथे Read टूल वापरून फाईल उघडते."

याचे दोन व्यावहारिक परिणाम होतात. रूट फाईल ही रिपॉझिटरीमधील प्रत्येक सेशनसाठी एक प्रीफिक्स (prefix) असते, त्यामुळे तिथे लिहिलेली प्रत्येक ओळ ही अशी ओळ आहे ज्यासाठी तुम्ही आठवड्यातून शंभर वेळा किंमत मोजता. प्रति-डिरेक्टरी फाईलचा खर्च शून्य असतो जोपर्यंत एजंट त्या डिरेक्टरीमधील फाईल उघडत नाही, याचा अर्थ तिथे तपशील देणे स्वस्त आहे आणि ते तिथेच असावे.

हे वर्तन 27 ऑक्टोबर 2026 रोजी Codex आणि Claude Code च्या डॉक्युमेंटेशननुसार तपासले गेले आहे. टूल्स हे कन्व्हेन्शन थोड्या वेगळ्या पद्धतीने राबवतात आणि त्यात बदलही होऊ शकतात, त्यामुळे तुमची टीम जो एजंट वापरते त्याच्या लोडिंग नियमांची खात्री करा.

सेवांसह repository ची कार्यरत रचना

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

Root file मुद्दाम लहान ठेवलेली आहे. ती कुठे पाहायचे ते सांगते आणि प्रत्येक directory मध्ये लागू होणारे नियमच त्यात असतात.

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

प्रत्येक directory मधील file मध्ये तपशील असतो. त्या directory च्या गरजेनुसार ती कितीही मोठी असू शकते.

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

Worker file ची रचनाही अशीच असते, पण त्यातील मजकूर वेगळा असतो: install command, pytest -q, consumer ने idempotent का राहिले पाहिजे याचे कारण आणि tests यशस्वी होण्यापूर्वी चालवावे लागणारे migration. Agent कडून होणारी हानी थांबवणारे नियम infra file मध्ये लिहा. terraform apply कधीही चालवू नका. terraform plan चालवून तिथेच थांबा. तसेच आधीच configured असलेला state backend नमूद करा, जेणेकरून agent नवीन backend initialise करण्याचा प्रयत्न करणार नाही.

या files पैकी कोणत्याही file मध्ये प्रत्येक service कशासाठी आहे याचे वर्णन नाही, हे लक्षात घ्या. ते humans साठी असते. Upstream देखील हीच सीमा स्पष्ट करते: "README.md files are for humans: quick starts, project descriptions, and contribution guidelines", तर AGENTS.md मध्ये "the extra, sometimes detailed context coding agents need: build steps, tests, and conventions." असते. AGENTS.md आणि humans साठी असलेल्या README मधील विभागणी ही सीमा वाक्यागणिक स्पष्ट करते. तसेच code ची रचना अशी का आहे हे नोंदवणारी DESIGN.md ही तिसऱ्या file चे स्पष्टीकरण देते; त्या file मध्ये commands ऐवजी निर्णयांची कारणे नोंदवली जातात.

कोड बदलल्यावर फाइल कोण अपडेट करतो?

एक नियम ठेवा आणि तो root फाइलमध्ये लिहा: एखाद्या directory मधील कोड बदलणारी व्यक्ती त्याच commit मध्ये त्या directory मधील AGENTS.md देखील अपडेट करेल.

हे सांस्कृतिक कारणामुळे नव्हे, तर यांत्रिक कारणामुळे प्रभावी ठरते. प्रत्येक directory मधील फाइल कोडसोबतच त्याच diff मध्ये असते. त्यामुळे pull request चे reviewer दोन्ही एकाच वेळी पाहतो. root फाइल सर्वांची असते. त्यामुळे ती प्रत्यक्षात कोणाचीच राहत नाही आणि कोणी आधीपासून पाहत असलेल्या diff मध्ये ती कधीच दिसत नाही.

pull request वर तपासणी लावून या नियमाला आधार द्या. ही तपासणी बदललेल्या प्रत्येक फाइलच्या वरच्या स्तरांमध्ये असलेली सर्वात जवळची AGENTS.md शोधते. त्यानंतर ती AGENTS.md बदललेली नसेल, तर त्याची नोंद करते.

#!/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

docs मध्ये बदल न करता API client ची पुनर्रचना केलेल्या branch वर output असा दिसतो:

note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updated

ही तपासणी failure न करता warning म्हणून ठेवा. कठोर gate ठेवल्यास लोक CI हिरवा करण्यासाठी फाइलमध्ये रिकामी ओळ जोडतील. एखाद्या robot ला संतुष्ट करण्यासाठी संपादित केलेली फाइल ही फाइल नसण्यापेक्षा कमी उपयुक्त असते. warning मुळे reviewer ला विचारण्यासाठी एक प्रश्न मिळतो. प्रत्यक्षात प्रभावी ठरणारा भाग हाच आहे.

AGENTS.md जुने झाले आहे हे कसे ओळखावे?

तुम्ही आज दोन तपासण्या करू शकता आणि सत्रादरम्यान तुम्हाला एक लक्षण दिसून येईल.

प्रत्येक फाईलच्या वयाची तुलना ती ज्या कोडचे वर्णन करते त्या कोडच्या वयाशी करा. %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")"
done
apps/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

कोडच्या तारखेपेक्षा सहा महिने जुनी असलेली डॉक्युमेंटेशन तारीख म्हणजे ती फाईल चुकीची आहे असे सिद्ध होत नाही. ती तुम्हाला कोणती फाईल आधी वाचायची आहे हे सांगते आणि एका सेकंदात होणाऱ्या तपासणीकडून तुम्हाला एवढीच अपेक्षा असते.

अस्तित्वात नसलेले पाथ शोधा. डॉक्युमेंटेशन एका विशिष्ट पद्धतीने खराब होते: ते अशा कोडचे वर्णन करत राहते जो डिलीट केला गेला आहे. या फाईल्समधील प्रत्येक पाथ बॅकटिक्समध्ये (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, अशी आहे: "जेव्हा तुमच्या वर्किंग डिरेक्टरीमध्ये किंवा त्यावरील कोणत्याही डिरेक्टरीमध्ये CLAUDE.md किंवा CLAUDE.local.md नसतात, तेव्हा तुमच्या AGENTS.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 थेट AGENTS.md वाचू शकत नाही: जुने व्हर्जन, Amazon Bedrock वरील v2.1.281 पूर्वीचे सेशन किंवा टेलिमेट्री बंद असलेले सेशन, जिथे ती वाचणारे इन-बिल्ट प्लगइन बंद आहे, किंवा असा प्रोजेक्ट ज्यामध्ये Project instructions ला claude-md वर सेट करून CLAUDE.md ठेवले आहे. हे services/worker/CLAUDE.md मध्ये टाका:

@AGENTS.md

## Claude Code

Use plan mode for changes under `services/worker/migrations/`.

जेव्हा टूल-विशिष्ट काहीही जोडायचे नसते, तेव्हा सिमलिन (symlink) फॉर्म योग्य असतो.

git ls-files '*AGENTS.md' | while read -r f; do
  ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.md

ln यशस्वी झाल्यावर काहीही प्रिंट करत नाही, त्यामुळे लिस्टिंग तपासा: apps/web/CLAUDE.md -> AGENTS.md. त्यानंतर सेशन सुरू करा आणि /context रन करा, जिथे लोड केलेल्या फाइल्स Memory files अंतर्गत दिसतील. Windows वर सिमलिनसाठी Administrator अधिकार किंवा Developer Mode आवश्यक असतो, आणि 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 सेटिंग पाथ किंवा ग्लोबद्वारे पूर्वज फाइल्स वगळते, जे तेव्हा उपयुक्त ठरते जेव्हा दुसऱ्या टीमची डिरेक्टरी तुमच्या डिरेक्टरीच्या वर असते. त्याचे पॅटर्न Claude Code वाचत असलेल्या AGENTS.md फाइल्सना देखील लागू होतात.

हे agent memory किंवा skill यांपेक्षा कसे वेगळे आहे?

या यंत्रणा वरवर सारख्या दिसतात; परंतु त्या पूर्णपणे वेगवेगळ्या प्रकारे अपयशी ठरतात. त्यामुळे तुम्हाला नेमकी कोणती यंत्रणा वापरायची आहे हे स्पष्टपणे ठरवणे महत्त्वाचे आहे.

AGENTS.md तुम्ही लिहिता, ते git मध्ये commit केले जाते, pull request मध्ये त्याचे पुनरावलोकन केले जाते आणि repository clone करणाऱ्या प्रत्येकासाठी ते एकसारखे असते. Agent memory agent लिहितो, ते repositoryच्या बाहेर साठवले जाते आणि एका मशीनपुरते मर्यादित असते. Claude Codeच्या documentation मध्येही हीच विभागणी केली आहे: CLAUDE.md मध्ये तुम्ही लिहिलेल्या "Instructions and rules" असतात; auto memory मध्ये Claude ने लिहिलेली "Learnings and patterns" असतात; आणि memory directory वेगवेगळ्या मशीनमध्ये share केली जात नाही. याची साधी चाचणी अशी आहे: fresh clone करणाऱ्या सहकाऱ्यासाठी एखादी बाब सत्य असणे आवश्यक असेल, तर ती memory मध्ये ठेवता येणार नाही. सत्रांदरम्यान agent memory कशी टिकते या विषयाच्या अर्ध्या भागाचे स्पष्टीकरण देते.

Skill ही तिसरी गोष्ट आहे. AGENTS.md प्रत्येक sessionमध्ये load होणारा context आहे; skill ही आवश्यकतेनुसार load होणारी procedure आहे. Claude Codeच्या documentation मध्ये वापरता येईल असा नियम दिला आहे: "If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead." या वाक्याचा दुसरा भाग nested AGENTS.md ने नेमका सोडवला जातो. पहिला भाग agent skills साठी आहे. तीच procedure एकापेक्षा जास्त repositoryमध्ये आवश्यक असेल, तर तीच paragraphs दहा वेगवेगळ्या AGENTS.md filesमध्ये paste करण्याऐवजी reposमध्ये skill share करा.

Upstream मध्ये नमूद केले आहे की "at time of writing the main OpenAI repo has 88 AGENTS.md files". हा आकडा संपूर्ण मुद्दा स्पष्ट करतो. मोठ्या repositoryला मोठी file आवश्यक नसते. त्याऐवजी अधिक छोट्या files आवश्यक असतात. प्रत्येक fileने ती ज्या codeचे वर्णन करते त्याच्या शेजारी असावे आणि तो code शेवटचा बदलणाऱ्या व्यक्तीच्या मालकीचे असावे.

FAQ

नेस्टेड AGENTS.md फाईल रूट फाईलची जागा घेते की त्यात भर घालते?

ती त्यात भर घालते. अपस्ट्रीमच्या म्हणण्यानुसार "सर्वात जवळची फाईल प्राधान्य घेते", जे संघर्षाच्या वेळी काय घडते हे दर्शवते, काय लोड होते हे नाही. Codex "रूटपासून खाली फाईल्स एकत्र करते आणि त्यांना रिकाम्या ओळींनी जोडते", आणि Claude Code वर्किंग डिरेक्टरीपासून वर जाताना सापडलेल्या प्रत्येक फाईलला एकत्र करते, त्यांना ओव्हरराईड करत नाही. जेव्हा दोन फाईल्स एकाच विषयावर भिन्न सूचना देतात, तेव्हाच सर्वात जवळची फाईल प्रभावी ठरते. सामायिक नियम एकदाच रूटवर लिहा आणि प्रत्येक डिरेक्टरीमध्ये त्यांची पुनरावृत्ती करू नका.

रूट AGENTS.md किती मोठी असावी?

ती इतकी लहान असावी की ती त्या रिपॉझिटरीमध्ये तुम्ही केलेल्या प्रत्येक विनंतीच्या वर पेस्ट केली तरी तुम्हाला हरकत नसावी, कारण प्रत्यक्षात तेच घडते. Claude Code चे डॉक्युमेंटेशन प्रत्येक फाईलसाठी 200 ओळींपेक्षा कमी ठेवण्याचा सल्ला देते आणि इशारा देते की लांब फाईल्समुळे "सूचनांचे पालन कमी होते". Codex डीफॉल्टनुसार 32 KiB पर्यंतच्या सूचना फाईल्स एकत्र करणे थांबवते. जर तुमची रूट फाईल चार सेवांचे दस्तऐवजीकरण करत असेल, तर त्यातील बहुतेक माहिती कोणत्याही एका कार्यासाठी अनावश्यक असते. तपशील डिरेक्टरी-निहाय फाईल्समध्ये हलवा आणि रूटवर फक्त एक नकाशा (map) ठेवा.

या फाईल्स जुन्या (stale) होऊ नयेत म्हणून मी काय करू?

रूट फाईलमध्ये एक नियम ठेवा: जो कोणी डिरेक्टरीमधील कोड बदलतो, त्याने त्याच कमिटमध्ये त्या डिरेक्टरीची AGENTS.md फाईल अपडेट करावी. फाईल कोडच्या शेजारी ठेवल्यामुळे नियम पाळला जाण्याची शक्यता वाढते, कारण तो बदल मानवाला वाचता येणाऱ्या त्याच पुल रिक्वेस्ट डिफ (pull request diff) मध्ये येतो. एक CI वॉर्निंग जोडा जी प्रत्येक बदललेल्या पाथला त्याच्या वरील सर्वात जवळच्या AGENTS.md शी मॅप करेल, आणि अधूनमधून प्रत्येक फाईलवरील git log -1 --format=%cs ची तुलना त्या डिरेक्टरीवर चालवलेल्या त्याच कमांडशी करा.

Claude Code AGENTS.md फाईल्स वाचते का?

हो, v2.1.277 पासून. 27 ऑक्टोबर 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 फक्त "तुमच्या CLAUDE.md फाईल्स" वाचते. जर तुम्हाला CLAUDE.md ची देखील गरज असेल, तर Project instructions ला /config मध्ये claude-md-and-agents-md वर सेट करा, किंवा त्याच्या पहिल्या ओळीवर @AGENTS.md लिहा. सेशनमध्ये /memory चालवा आणि AGENTS.md पाथ लिस्टमध्ये दिसत असल्याची खात्री करा.

एखादा नियम जो फक्त कधीकधी महत्त्वाचा असतो, तो कुठे ठेवावा?

AGENTS.md मध्ये नको. ती फाईल प्रत्येक सेशनमध्ये लोड होते, त्यामुळे त्यातील प्रत्येक ओळ तुम्ही टाइप केलेल्या प्रत्यक्ष विनंतीशी स्पर्धेत असते. अनेक पायऱ्या असलेली प्रक्रिया जी अधूनमधून आवश्यक असते, ती 'स्किल' (skill) मध्ये असावी, जी मागणीनुसार लोड होते. एखादा नियम जो एका डिरेक्टरीला लागू होतो, तो त्या डिरेक्टरीच्या AGENTS.md मध्ये असावा. एखादी वस्तुस्थिती जी एजंट थेट कोडमधून वाचू शकतो, जसे की डिरेक्टरी ट्री किंवा डिपेंडन्सी लिस्ट, ती यापैकी कशातही नसावी.

हा लेख उपयुक्त होता का?