SSD Nodes Learn Hosting plans →
మార్గదర్శకాలు Matt Connorద్వారా Matt Connor · అప్‌డేట్ చేయబడింది 2026-10-30

monorepoలో nested AGENTS.md నిర్మాణం ఎలా ఉండాలి

ఒకే root AGENTS.md పాతబడి, agent తెరవని directories కోసం context వృథా చేస్తుంది. service వారీ nested layout ఈ సమస్యను ఎలా పరిష్కరిస్తుందో తెలుసుకోండి.

monorepoలో nested AGENTS.md అంటే ఏమిటి

monorepoలో nested AGENTS.md అంటే repository root వద్ద ఒక చిన్న file, అలాగే ప్రతి service directory లోపల మరో file ఉండటం. Root fileలో అన్ని చోట్ల వర్తించే కొద్దిపాటి rules ఉంటాయి. ఇతర files ఎక్కడ ఉన్నాయో తెలిపే map కూడా అందులో ఉంటుంది. ప్రతి service fileలో ఆ directoryకి మాత్రమే సంబంధించిన commands మరియు conventions ఉంటాయి. Agent services/worker/queue.py ను edit చేస్తున్నప్పుడు root fileను, worker fileను చదువుతుంది. తాను ఎప్పుడూ మార్చని front end గురించి context‌ను వృథా చేయదు.

ఏదీ install చేయాల్సిన అవసరం లేదు. AGENTS.md ఒక convention మాత్రమే. Upstream project కూడా దీన్ని స్పష్టంగా చెబుతుంది:

AGENTS.md అనేది standard Markdown మాత్రమే. మీకు నచ్చిన headings ఏవైనా ఉపయోగించండి. Agent మీరు అందించిన text‌ను మాత్రమే parse చేస్తుంది.

అందుకే ఈ విధానాన్ని సరిగ్గా నేర్చుకోవడం విలువైనది. ఈ format మీ అనుమతి లేకుండా మారదు. సమస్యలు placement మరియు maintenance వల్లే వస్తాయి. ఈ రెండూ మీ బాధ్యత.

ఒక పెద్ద root AGENTS.md ఎందుకు పనిచేయడం మానేస్తుంది?

వెబ్ యాప్, బ్యాక్‌గ్రౌండ్ వర్కర్ మరియు Terraform డైరెక్టరీని కలిగి ఉన్న రిపోజిటరీ రూట్‌లో ఉన్న 600-లైన్ల AGENTS.md ఫైల్ నాలుగు రకాలుగా విఫలమవుతుంది.

దీనిని ఎవరూ పట్టించుకోకపోవడంతో ఇది పాతబడిపోతుంది. apps/webలో టెస్ట్ స్క్రిప్ట్‌ను రీనేమ్ చేసే ఇంజనీర్ apps/web కింద ఉన్న ఫైళ్లను ఎడిట్ చేస్తారు. రూట్ AGENTS.md ఆ diffలో ఉండదు, కాబట్టి ఏ రివ్యూయర్‌కు ఆ వ్యత్యాసం కనిపించదు. ఆరు వారాల తర్వాత, ఆ ఫైల్ ఇక లేని ఒక బిల్డ్ స్టెప్ గురించి వివరిస్తుంది, మరియు దాన్ని మార్చిన వ్యక్తి ఆ మార్పును మర్చిపోతారు.

ప్రతి పనిలో ఇది contextను వృథా చేస్తుంది. ఏజెంట్ మీరు ఏమి అడగబోతున్నారో తెలుసుకోకముందే, సెషన్ ప్రారంభంలోనే ఈ ఫైళ్లు లోడ్ అవుతాయి. Claude Code డాక్యుమెంటేషన్ దీనిపై ఒక సంఖ్యను ఇస్తుంది: "ప్రతి CLAUDE.md ఫైల్‌ను 200 లైన్ల లోపు ఉంచండి. ఎక్కువ పొడవున్న ఫైళ్లు ఎక్కువ contextను వినియోగించుకుంటాయి మరియు పనితీరును తగ్గిస్తాయి." ఇన్స్ట్రక్షన్ ఫైళ్ల మొత్తం పరిమాణం డిఫాల్ట్ project_doc_max_bytes అయిన 32 KiB కి చేరుకున్నప్పుడు Codex వాటిని మెర్జ్ చేయడం ఆపేస్తుంది. నాలుగు సర్వీసులను డాక్యుమెంట్ చేసే రూట్ ఫైల్, ప్రతి పనికి వాటిలో మూడింటి కోసం ఆ బడ్జెట్‌ను ఖర్చు చేస్తుంది.

సూచనలు ఒకదానికొకటి విరుద్ధంగా మారతాయి. వెబ్ డైరెక్టరీకి pnpm test కావాలి. వర్కర్‌కు pytest -q కావాలి. ఒకే ఫైల్‌లో రాసినప్పుడు, ప్రతి నియమం కొన్నిసార్లు మాత్రమే సరైనదిగా ఉంటుంది, కాబట్టి ఏది వర్తిస్తుందో ఏజెంట్ ఊహించాల్సి వస్తుంది. Claude Code డాక్యుమెంటేషన్ ఫలితాన్ని ఇలా వివరిస్తుంది: "రెండు సూచనలు ఒకదానికొకటి విరుద్ధంగా ఉంటే, Claude ఏదో ఒకదాన్ని యాదృచ్ఛికంగా ఎంచుకోవచ్చు." ఫైల్‌ను విడగొట్టినంత మాత్రాన ఇతర నియమాలు contextలోకి రాకుండా ఉండవు. Claude Code తాను లోడ్ చేసిన ప్రతి ఇన్స్ట్రక్షన్ ఫైల్‌ను కలిపి ఉంచుతుంది (ఒకదాని స్థానంలో మరొకటి రాదు), కాబట్టి రూట్ ఫైల్ ఎప్పుడూ ఉంటుంది. ఏజెంట్ apps/web మరియు services/worker రెండింటిలోనూ ఫైళ్లను తెరిచినప్పుడు, రెండు డైరెక్టరీ ఫైళ్లు contextలో కలిసి ఉంటాయి. ప్రతి-డైరెక్టరీ ఫైల్ చేసే పని ఏమిటంటే, ప్రతి నియమాన్ని అది నియంత్రించే డైరెక్టరీకి అనుసంధానించడం. # apps/webతో కింద ఉన్న ఉదాహరణల మాదిరిగా, ఫైల్ పైన డైరెక్టరీ పేరును పేర్కొనండి. అప్పుడు అనేక ఫైళ్లు ఒకేసారి లోడ్ అయినప్పుడు కూడా, ప్రతి కమాండ్ ఎక్కడ వర్తిస్తుందో స్పష్టంగా ఉంటుంది. మీరు స్పష్టంగా రాశారని నమ్మే నియమం ఏదైనా పట్టించుకోబడకపోతే, ఒక సూచన ఎందుకు అమలు కాదో తెలుసుకోవడం నాలుగోసారి అదే విషయాన్ని తిరిగి రాయడం కంటే మెరుగైనది.

ఏజెంట్ కోడ్ నుండి చదవగలిగే వాస్తవాలతో ఇది నిండిపోతుంది. డైరెక్టరీ ట్రీ, డిపెండెన్సీ లిస్ట్, ప్రతి ప్యాకేజీ ఏమి చేస్తుందో తెలిపే సారాంశం వంటివి. Claude Code యొక్క /doctor చెక్ సరిగ్గా వీటిని తొలగించడానికి ఉంటుంది. ఇది "డైరెక్టరీ లేఅవుట్‌లు, డిపెండెన్సీ లిస్ట్‌లు మరియు ఆర్కిటెక్చర్ అవలోకనాల వంటి కోడ్‌బేస్ నుండి Claude గ్రహించగలిగే కంటెంట్‌ను తొలగిస్తుంది" మరియు "టూల్ డిఫాల్ట్‌లకు భిన్నంగా ఉండే లోపాలు, కారణాలు మరియు పద్ధతులను" ఉంచుతుంది. ఒక లైన్ ఫైల్‌లో ఉండాలా వద్దా అని నిర్ణయించడానికి ఆ వాక్యం నాకు తెలిసిన ఉత్తమ పరీక్ష.

ఏజెంట్ root ఫైల్‌ను చదువుతుందా, లేక సమీపంలోని ఫైల్‌ను మాత్రమే చదువుతుందా?

చాలా మంది ఇక్కడే model ను తప్పుగా అర్థం చేసుకుంటారు. అందువల్ల దీన్ని paraphrase చేయడం కంటే upstream convention ను నేరుగా ఉటంకించడం ఉపయోగకరం:

ప్రతి package లో మరో AGENTS.md ఫైల్‌ను ఉంచండి. Agents directory tree లోని సమీప ఫైల్‌ను స్వయంచాలకంగా చదువుతాయి. అందువల్ల అత్యంత సమీపంలోని ఫైల్‌కు ప్రాధాన్యం ఉంటుంది. ప్రతి subproject తనకు అనుగుణమైన instructions ను అందించగలదు.

Conflicts గురించి:

సవరించే file కు అత్యంత సమీపంలోని AGENTS.md ఫైల్‌కు ప్రాధాన్యం ఉంటుంది. Explicit user chat prompts అన్నింటినీ override చేస్తాయి.

"Takes precedence" అనే మాటను చాలామంది "root file విస్మరించబడుతుంది" అని అర్థం చేసుకుంటారు. అది సరైనది కాదు. ఈ convention ను అమలు చేసే tools లో repository root నుంచి working directory వరకు path లో ఉన్న ప్రతి file చదివి, వాటిని కలిపి ఉపయోగిస్తారు. రెండు files ఒకే అంశంపై భిన్నమైన సూచనలు ఇచ్చినప్పుడు మాత్రమే సమీపంలోని file కు ప్రాధాన్యం ఉంటుంది.

Codex ఈ mechanism ను స్పష్టంగా వివరిస్తుంది: "Codex root నుంచి files ను concatenate చేసి, వాటి మధ్య blank lines ఉంచుతుంది. మీ ప్రస్తుత directory కు దగ్గరగా ఉన్న files, ముందుగా వచ్చిన guidance ను override చేస్తాయి." Claude Code కూడా ఇదే path ను traverse చేస్తుంది. Session ప్రారంభంలో అది మీ working directory మరియు దాని పై directory లలోని "ప్రతి AGENTS.md మరియు .claude/AGENTS.md" ను చదువుతుంది. Loading model ను దాని documentation స్పష్టంగా వివరిస్తుంది: "కనుగొనబడిన అన్ని files ఒకదానిని మరొకటి override చేయకుండా context లో concatenate అవుతాయి." Working directory కంటే దిగువన ఉన్న directories మాత్రం భిన్నంగా పనిచేస్తాయి. Claude Code subdirectory లోని AGENTS.md ను అవసరమైనప్పుడు మాత్రమే load చేస్తుంది; అంటే "Claude Read tool తో అక్కడి file ను తెరిచినప్పుడు."

దీని వల్ల రెండు ఆచరణాత్మక విషయాలు స్పష్టమవుతాయి. Repository లో ప్రతి session కు root file ఒక prefix గా ఉంటుంది. అందువల్ల అక్కడి ప్రతి line ను వారానికి వందసార్లు చెల్లించే ఖర్చుగా పరిగణించండి. Per-directory file కు ఆ directory లోని file ను agent తెరిచే వరకు ఎటువంటి ఖర్చు ఉండదు. కాబట్టి వివరమైన సూచనలు అక్కడ ఉంచడం సముచితం, వాటి నిర్వహణ తక్కువ ఖర్చుతో ఉంటుంది.

ఈ ప్రవర్తనను 27 October 2026న Codex మరియు Claude Code documentation ఆధారంగా తనిఖీ చేశారు. Tools ఈ convention ను కొద్దిగా భిన్నంగా అమలు చేస్తాయి, అలాగే వాటి ప్రవర్తన మారవచ్చు. అందువల్ల మీ team ఉపయోగించే agent కు loading rules ఏమిటో నిర్ధారించుకోండి.

మూడు services ఉన్న repository కోసం ఒక నమూనా layout

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 లో వర్తించే rules మాత్రమే అందులో ఉంటాయి.

# 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 కూడా ఇదే ఆకృతిలో ఉంటుంది, కానీ content వేరుగా ఉంటుంది: install command, pytest -q, consumer idempotent గా ఉండాల్సిన కారణం, tests pass కావడానికి ముందు అమలు చేయాల్సిన migration. Agent నష్టం కలిగించే చర్యలు చేయకుండా ఆపే rules ను infra file లో రాయాలి. terraform apply ను ఎప్పుడూ run చేయకూడదు. terraform plan ను run చేసి అక్కడితో ఆపాలి. ఇప్పటికే configured గా ఉన్న state backend పేరును కూడా పేర్కొనాలి. అప్పుడు agent కొత్తదాన్ని initialise చేయడానికి ప్రయత్నించదు.

ఈ files లో ఏదిలోనూ లేనిది గమనించండి: ప్రతి service ఏ పని కోసం ఉందో చెప్పే description. అది 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 మధ్య విభజన ఈ boundary ను sentence by sentence వివరిస్తుంది. అలాగే code ఇలా ఎందుకు రూపొందించబడిందో నమోదు చేసే DESIGN.md మూడో file గురించి వివరిస్తుంది. ఇది commands కు బదులుగా decisions ను వివరిస్తుంది.

కోడ్ మారినప్పుడు ఆ ఫైల్‌ను ఎవరు నవీకరిస్తారు?

ఒక నియమాన్ని root ఫైల్‌లో ఉంచండి: ఒక directoryలో కోడ్‌ను మార్చిన వ్యక్తి, అదే commitలో ఆ directoryకి చెందిన AGENTS.mdని కూడా నవీకరించాలి.

ఇది సాంస్కృతిక కారణం వల్ల కాదు; యాంత్రిక కారణం వల్ల పనిచేస్తుంది. ప్రతి directoryకి చెందిన ఫైల్, కోడ్‌తో పాటు అదే diffలో ఉంటుంది. అందువల్ల pull requestను సమీక్షించే వ్యక్తి రెండింటినీ ఒకేసారి చూస్తారు. root ఫైల్ అందరికీ చెందుతుంది. అందువల్ల అది ఎవరికీ ప్రత్యేకంగా చెందదు. ఇప్పటికే ఎవరైనా చదువుతున్న diffలో అది సాధారణంగా ఉండదు.

ఈ నియమానికి pull requestలో ఒక checkను జోడించండి. ప్రతి మారిన ఫైల్‌కు పైభాగంలో ఉన్న అత్యంత సమీప 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 greenగా మారేందుకు వ్యక్తులు ఫైల్‌లో ఖాళీ lineను జోడించడం నేర్చుకుంటారు. ఒక 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 నుంచి పనిచేస్తుంది. Nested layout ఈ నియమంపై ఆధారపడుతుంది కాబట్టి ఖచ్చితమైన నియమం ముఖ్యం. 27 October 2026న documentation ను పరిశీలించాం: "Claude Code AGENTS.md ను మీ project instructions గా చదవగలదు. అందువల్ల ఇతర coding agents కోసం ఇప్పటికే సిద్ధం చేసిన repository కి CLAUDE.md, import లేదా setting జోడించాల్సిన అవసరం ఉండదు." Default Project instructions విలువ, claude-md-or-agents-md, "మీ working directory లో లేదా దాని పైస్థాయిలలో CLAUDE.md లేదా CLAUDE.local.md ఏదీ లేనప్పుడు మీ AGENTS.md files" ను చదువుతుంది. Nested files కూడా ఇందులో ఉంటాయి: "Claude Read tool తో ఒక subdirectory లోని file ను తెరిచినప్పుడు" ఆ subdirectory లో స్వంతంగా ఆ మూడు CLAUDE.md files ఏవీ లేకపోతే, Claude ఆ subdirectory లోని AGENTS.md ను కూడా చదువుతుంది. ఆ మూడు files CLAUDE.md, .claude/CLAUDE.md మరియు CLAUDE.local.md. అందువల్ల apps/web లోని వ్యక్తిగత CLAUDE.local.md file ఉంటే apps/web/AGENTS.md loading ఆగిపోతుంది.

దీంతో ప్రతి AGENTS.md పక్కన CLAUDE.md ఉంచాలనే పాత సూచన సమస్యగా మారుతుంది. మీ working directory లో లేదా దాని పైస్థాయిలలో AGENTS.md మరియు CLAUDE.md లేదా CLAUDE.local.md ఉంటే, documentation ప్రకారం Claude "మీ CLAUDE.md files మాత్రమే" చదువుతుంది. .claude/CLAUDE.md కూడా ఇదే విధంగా పరిగణించబడుతుంది. Root వద్ద Claude-specific ఒక్క line ఉన్న ఒక companion file ఉంటే path లోని ప్రతి AGENTS.md దాగిపోతుంది. వ్యక్తిగత CLAUDE.local.md కూడా ఇదే పని చేస్తుంది. ఒకదాన్ని ఉంచాలనుకుంటే /config ను type చేసి, Project instructions ను claude-md-and-agents-md కు set చేయండి. అప్పుడు రెండింటినీ చదువుతుంది; ప్రతి directory లో ముందుగా దాని CLAUDE.md, తరువాత దాని AGENTS.md చదువుతుంది.

Version number ఒక్కటే పనిచేసిందని నిర్ధారించదు. మీకు v2.1.277 లేదా తరువాతి version అవసరం. అయితే v2.1.281కు ముందు కొన్ని sessions, ఉదాహరణకు Amazon Bedrock పై నడిచేవి లేదా telemetry disabled గా ఉన్నవి, CLAUDE.md files మాత్రమే చదివేవి. అలాగే v2.1.276 లేదా అంతకంటే పాత version నుంచి upgrade చేసిన తర్వాత కొన్ని సందర్భాల్లో మొదటి session AGENTS.md ను కూడా skip చేస్తుంది: documentation ప్రకారం "మీ తదుపరి session నుంచి Claude AGENTS.md ను చదువుతుంది." అందువల్ల session ను స్వయంగా తనిఖీ చేయండి. Interactive session లో Claude Code no CLAUDE.md found; AGENTS.md loaded: వంటి line ను path తరువాత print చేస్తుంది. ప్రస్తుత versions లో /memory file list ను చూపుతుంది. v2.1.280కు ముందు /memory మరియు /context, Claude నేరుగా చదివిన AGENTS.md ను list చేయలేదు. అందువల్ల ఆ versions లో Claude ను దాని project instructions ఏమిటో అడగండి.

Claude AGENTS.md ను నేరుగా చదవలేని సందర్భాల్లో import రూపం ఇప్పటికీ సరైనదే: పాత version, Amazon Bedrock పై లేదా telemetry disabled గా ఉన్న v2.1.281కు ముందు session, దాన్ని చదివే built-in plugin disabled గా ఉన్న session, లేదా Project instructions ను claude-md కు set చేసిన CLAUDE.md ను ఉంచుకున్న project. దీన్ని services/worker/CLAUDE.md లో ఉంచండి:

@AGENTS.md

## Claude Code

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

Tool-specific మార్పు ఏదీ జోడించాల్సిన అవసరం లేనప్పుడు 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 ఏ output ను print చేయదు. అందువల్ల listing ను తనిఖీ చేయండి: apps/web/CLAUDE.md -> AGENTS.md. తరువాత session ప్రారంభించి /context ను run చేయండి. Loaded files Memory files కింద కనిపిస్తాయి. Windows లో symlink కు Administrator rights లేదా Developer Mode అవసరం. అలాగే core.symlinks enabled చేయకపోతే, Git committed symlink ను plain text file గా checkout చేస్తుంది. అప్పుడు ఆ clone లో మీ instructions స్థానంలో ఒక line ఉన్న CLAUDE.md ఉంటుంది. Repository ను clone చేసే ఎవరైనా Windows లో పనిచేస్తే @AGENTS.md import ను ఉపయోగించండి. Claude Code స్వయంగా AGENTS.md ను చదవకముందే ఈ రెండు workarounds లో ఏదైనా ఏర్పాటు చేసి ఉంటే, దాన్ని అలాగే ఉంచవచ్చు. Documentation ప్రకారం import ను ఉంచడం వల్ల "Claude AGENTS.md ను రెండుసార్లు చదవదు". Symlink చేసిన CLAUDE.md కూడా ఒక్కసారి మాత్రమే చదవబడుతుంది.

ఇదికి సంబంధించిన మరో సమస్య ఉంది. /compact తర్వాత project-root లోని CLAUDE.md disk నుంచి మళ్లీ చదవబడుతుంది. కానీ subdirectories లోని nested files మళ్లీ context లోకి చేర్చబడవు. ఆ directory లోని file తో agent తదుపరి సారి పనిచేసినప్పుడు Claude Code వాటిని అవసరమైన సమయంలో మళ్లీ load చేస్తుంది. Documentation ఈ విషయాన్ని CLAUDE.md files కోసం స్పష్టంగా చెబుతుంది. నేరుగా చదివిన AGENTS.md కోసం compaction ను ప్రత్యేకంగా వివరించదు. కాబట్టి రెండు పేర్లలో ఏదైనా ఉన్న nested files కూడా ఇదే విధంగా పనిచేస్తాయని భావించండి. దీర్ఘమైన session మధ్యలో directory-specific rule అమలులో లేకపోయినట్లు కనిపిస్తే, సాధారణంగా కారణం ఇదే. ఆ directory లోని ఏదైనా file ను చదివితే rule మళ్లీ అందుబాటులోకి వస్తుంది.

ఇతర agents ను AGENTS.md వైపు చూపించే Settings

Codex AGENTS.md ను native గా చదువుతుంది. ప్రతి level వద్ద ముందుగా AGENTS.override.md కోసం తనిఖీ చేస్తుంది. దీనివల్ల shared file ను మార్చకుండా ఒక directory కి local override ఇవ్వవచ్చు. Combined size 32 KiB కు చేరుకున్నప్పుడు merging ఆపివేస్తుంది. ఇది default project_doc_max_bytes. అందువల్ల root file ను చిన్నగా ఉంచడానికి ఇదొక కారణం.

Aider దీనిని .aider.conf.yml ద్వారా తీసుకుంటుంది. దానికి read: AGENTS.md line ను ఉపయోగించండి.

Gemini CLI దీనిని .gemini/settings.json ద్వారా తీసుకుంటుంది. దానికి { "context": { "fileName": "AGENTS.md" } } ను ఉపయోగించండి.

పాత singular name ను ఇంకా ఉపయోగిస్తున్న repositories కోసం upstream documentation backward-compatible rename ను అందిస్తుంది: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.

చాలా పెద్ద monorepo లో, Claude Code యొక్క claudeMdExcludes setting ancestor files ను path లేదా glob ఆధారంగా skip చేస్తుంది. మీ directory పైన మరో team directory ఉన్నప్పుడు ఇది ఉపయోగకరం. Claude Code చదివే AGENTS.md files కు కూడా ఈ patterns వర్తిస్తాయి.

ఇది agent memory లేదా skill కంటే ఎలా భిన్నంగా ఉంటుంది?

ఈ విధానాలు ఒకేలా కనిపించినా, విఫలమయ్యే విధానం పూర్తిగా భిన్నంగా ఉంటుంది. అందువల్ల మీరు ఏదిని ఉపయోగించాలనుకుంటున్నారో ఖచ్చితంగా నిర్ణయించడం ముఖ్యం.

AGENTS.md ను మీరు రాస్తారు, git కు commit చేస్తారు, pull request లో review చేస్తారు. Repository ను clone చేసే ప్రతి ఒక్కరికీ అది ఒకేలా ఉంటుంది. Agent memory ను agent రాస్తుంది. అది repository వెలుపల నిల్వ చేయబడుతుంది. ఒకే machine కు మాత్రమే పరిమితమవుతుంది. Claude Code documentation కూడా ఇదే తేడాను చూపిస్తుంది: మీరు రాసే "Instructions and rules" ను CLAUDE.md ఉంచుతుంది; Claude రాసే "Learnings and patterns" ను auto memory ఉంచుతుంది. Memory directory machines మధ్య share చేయబడదు. పరీక్ష సులభం. Fresh clone తీసుకున్న సహచరుడికి కూడా ఒక వాస్తవం నిజంగా ఉండాలి అనుకుంటే, అది memory లో ఉండకూడదు. sessions మధ్య agent memory ఎలా కొనసాగుతుంది ఈ అంశంలోని ఆ భాగాన్ని వివరిస్తుంది.

Skill మూడవ అంశం. AGENTS.md ప్రతి session లో load అయ్యే context. Skill అవసరమైనప్పుడు load అయ్యే procedure. Claude Code documentation లో ఉపయోగకరమైన నియమం ఉంది: "ఒక entry అనేక దశల procedure అయితే లేదా codebase లోని ఒక భాగానికి మాత్రమే అవసరమైతే, దాన్ని skill లేదా path-scoped rule కు మార్చండి." ఈ వాక్యంలోని రెండవ భాగాన్ని nested AGENTS.md పరిష్కరిస్తుంది. మొదటి భాగం agent skills కోసం ఉద్దేశించబడింది. అదే procedure ఒకటి కంటే ఎక్కువ repositoryలలో అవసరమైతే, అదే paragraphs ను పది వేర్వేరు AGENTS.md files లో paste చేయకుండా repositories మధ్య skill ను share చేయండి.

Upstream ప్రకారం, "రాస్తున్న సమయానికి ప్రధాన OpenAI repo లో 88 AGENTS.md files ఉన్నాయి". ఆ సంఖ్యే మొత్తం వాదనను స్పష్టం చేస్తుంది. పెద్ద repositoryకి మరింత పెద్ద file అవసరం లేదు. దానికి బదులుగా మరిన్ని చిన్న files అవసరం. ప్రతి file అది వివరించే code పక్కనే ఉండాలి. ఆ code ను చివరిగా మార్చిన వ్యక్తి దాని owner అయి ఉండాలి.

FAQ

Nested AGENTS.md ఉంటే root ఫైల్‌ను భర్తీ చేస్తుందా, లేక దానికి జత అవుతుందా?

అది root ఫైల్‌కు జత అవుతుంది. Upstream లో “అత్యంత సమీపంలోని ఫైల్‌కు ప్రాధాన్యత ఉంటుంది” అని చెబుతుంది. ఇది conflict వచ్చినప్పుడు ఏమి జరుగుతుందో వివరిస్తుంది, ఏ ఫైళ్లు load అవుతాయో కాదు. Codex root నుంచి కిందికి ఉన్న ఫైళ్లను ఖాళీ పంక్తులతో కలుపుతూ “concatenates files” చేస్తుంది. Claude Code కూడా వాటిని override చేయకుండా working directory నుంచి పైకి వెళ్తూ కనిపించే ప్రతి ఫైల్‌ను కలుపుతుంది. రెండు ఫైళ్లు ఒకే విషయం గురించి భిన్న సూచనలు ఇచ్చినప్పుడు మాత్రమే సమీపంలోని ఫైల్ గెలుస్తుంది. భాగస్వామ్య నియమాలను root లో ఒకసారి రాయండి. వాటిని ప్రతి directory లో మళ్లీ రాయకండి.

root AGENTS.md ఎంత పెద్దదిగా ఉండాలి?

ఆ repository లో మీరు చేసే ప్రతి request పై దాన్ని ఉంచినా ఇబ్బంది అనిపించనంత చిన్నదిగా ఉండాలి. ఎందుకంటే అదే జరుగుతుంది. Claude Code documentation ప్రతి ఫైల్‌ను 200 lines కంటే తక్కువగా ఉంచాలని సూచిస్తుంది. పొడవైన ఫైళ్లు “adherence తగ్గిస్తాయి” అని అది హెచ్చరిస్తుంది. Codex default గా కలిపిన instruction files 32 KiB వద్ద merge చేయడం ఆపుతుంది. మీ root ఫైల్ నాలుగు services ను document చేస్తే, ఏ ఒక్క task కైనా దానిలో ఎక్కువ భాగం అవసరం లేని అదనపు సమాచారం అవుతుంది. వివరాలను per-directory files లోకి తరలించి, అక్కడ ఒక map ఉంచండి.

ఈ ఫైళ్లు పాతబడకుండా ఎలా ఆపాలి?

root ఫైల్‌లో ఒక నియమం ఉంచండి: ఏ directory లో code మార్చిన వ్యక్తి అదే commit లో ఆ directory యొక్క AGENTS.md ను కూడా update చేయాలి. ఫైల్‌ను code పక్కనే ఉంచడం వల్ల ఈ నియమం అమలులో ఉంటుంది. మార్పు ఇప్పటికే మనిషి పరిశీలిస్తున్న అదే pull request diff లో చేరుతుంది. మారిన ప్రతి path ను దాని పైన ఉన్న సమీప AGENTS.md కు map చేసే CI warning ను జోడించండి. కొంతకాలానికి ప్రతి ఫైల్‌లోని git log -1 --format=%cs ను అది document చేసే directory పై అదే command నడిపి పొందిన ఫలితంతో పోల్చండి.

Claude Code AGENTS.md files ను చదువుతుందా?

అవును, v2.1.277 నుంచి చదువుతుంది. 27 October 2026 నాటి documentation ఆధారంగా పరిశీలించినప్పుడు, working directory లో లేదా దాని పైన CLAUDE.md లేదా CLAUDE.local.md ఏదీ లేకపోతే Claude Code default గా AGENTS.md ను చదువుతుంది. ఆ subdirectory కి స్వంతంగా CLAUDE.md, .claude/CLAUDE.md లేదా CLAUDE.local.md ఏదీ లేకపోతే, Read tool తో ఆ subdirectory లోని file ను తెరిచినప్పుడు అది ఆ subdirectory యొక్క AGENTS.md ను చదువుతుంది. ప్రతి AGENTS.md పక్కన CLAUDE.md ను జోడించకండి. working directory లో లేదా దాని పైన ఒకటి ఉంటే, Claude “Your CLAUDE.md files only” అని చదువుతుంది. మీకు CLAUDE.md కూడా అవసరమైతే, /config లోని Project instructions ను claude-md-and-agents-md కు set చేయండి, లేదా దాని మొదటి line లో @AGENTS.md ఉంచండి. ఒక session లో /memory ను run చేసి, జాబితాలో AGENTS.md path కనిపిస్తుందో నిర్ధారించండి.

అప్పుడప్పుడు మాత్రమే అవసరమయ్యే నియమాన్ని ఎక్కడ ఉంచాలి?

AGENTS.md లో ఉంచకండి. ఆ ఫైల్ ప్రతి session లో load అవుతుంది. అందువల్ల దానిలోని ప్రతి line మీరు నిజంగా type చేసిన request తో attention కోసం పోటీ పడుతుంది. అప్పుడప్పుడు అవసరమయ్యే అనేక steps ఉన్న procedure ను skill లో ఉంచాలి. అది అవసరమైనప్పుడు మాత్రమే load అవుతుంది. ఒక directory కి మాత్రమే వర్తించే నియమాన్ని ఆ directory యొక్క AGENTS.md లో ఉంచాలి. directory tree లేదా dependency list వంటి agent code నుంచే నేరుగా చదవగల facts ఏదీ ఇక్కడ ఉంచకూడదు.

ఈ వ్యాసం ఉపయోగకరంగా ఉందా?