Monorepo లో nested AGENTS.md ఫైల్స్ వాడటం ఎలా?

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

Monorepo లో nested AGENTS.md అంటే రిపోజిటరీ రూట్‌లో ఒక చిన్న ఫైల్ మరియు ప్రతి సర్వీస్ డైరెక్టరీ లోపల మరొక ఫైల్ ఉండటం. రూట్ ఫైల్ అన్ని చోట్లా వర్తించే కొన్ని ప్రాథమిక నియమాలను మరియు ఇతర ఫైళ్లు ఎక్కడ ఉన్నాయో తెలిపే మ్యాప్‌ను కలిగి ఉంటుంది. ప్రతి సర్వీస్ ఫైల్ ఆ డైరెక్టరీకి మాత్రమే పరిమితమైన కమాండ్‌లను మరియు కన్వెన్షన్‌లను కలిగి ఉంటుంది. services/worker/queue.py ను ఎడిట్ చేసే ఒక ఏజెంట్, రూట్ ఫైల్‌ను మరియు వర్కర్ ఫైల్‌ను చదువుతుంది; తద్వారా అది ఎప్పటికీ తాకని ఫ్రంట్-ఎండ్ కోసం ఎటువంటి కాంటెక్స్ట్‌ను వృథా చేయదు.

దీని కోసం ఇన్‌స్టాల్ చేయాల్సినది ఏమీ లేదు. AGENTS.md అనేది ఒక కన్వెన్షన్ మాత్రమే, మరియు అప్‌స్ట్రీమ్ ప్రాజెక్ట్ దీనిని స్పష్టంగా ఇలా చెబుతోంది:

AGENTS.md అనేది కేవలం ప్రామాణిక Markdown ఫైల్ మాత్రమే. మీకు నచ్చిన హెడ్డింగ్‌లను ఉపయోగించండి; మీరు అందించిన టెక్స్ట్‌ను ఏజెంట్ సులభంగా పార్స్ చేస్తుంది.

అందుకే ఈ పద్ధతిని సరిగ్గా నేర్చుకోవడం విలువైనది. దీని ఫార్మాట్ మీకు తెలియకుండా మారదు. కేవలం ఫైల్ అమరిక మరియు నిర్వహణ మాత్రమే దెబ్బతినవచ్చు, మరియు ఆ రెండింటి బాధ్యత మీదే.

రూట్ డైరెక్టరీలో ఉండే ఒకే పెద్ద AGENTS.md ఎందుకు పనిచేయడం ఆగిపోతుంది?

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

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

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

సూచనలు ఒకదానికొకటి విరుద్ధంగా మారుతాయి. వెబ్ డైరెక్టరీకి pnpm test కావాలి. వర్కర్‌కు pytest -q కావాలి. ఒకే ఫైల్‌లో రాసినప్పుడు, ప్రతి నియమం కొన్నిసార్లు మాత్రమే సరైనదిగా ఉంటుంది, కాబట్టి ఏది వర్తిస్తుందో ఏజెంట్ ఊహించాల్సి వస్తుంది. Claude Code డాక్యుమెంటేషన్ దీని ఫలితాన్ని ఇలా వివరిస్తుంది: "రెండు నియమాలు ఒకదానికొకటి విరుద్ధంగా ఉంటే, Claude ఏదో ఒకదాన్ని యాదృచ్ఛికంగా ఎంచుకోవచ్చు." డైరెక్టరీ వారీగా ఫైల్ ఉంటే ఈ గందరగోళం ఉండదు, ఎందుకంటే ఆ సమయంలో ఒక నియమం మాత్రమే కాంటెక్స్ట్‌లో ఉంటుంది.

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

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

చాలామంది ఈ మోడల్ విషయంలో తప్పుగా అర్థం చేసుకుంటారు, కాబట్టి దీనిని సొంత మాటల్లో చెప్పడం కంటే అప్‌స్ట్రీమ్ కన్వెన్షన్‌ను ఉదహరించడం ఉత్తమం:

ప్రతి ప్యాకేజీ లోపల మరొక AGENTS.md ను ఉంచండి. ఏజెంట్లు డైరెక్టరీ ట్రీలో అత్యంత సమీపంలో ఉన్న ఫైల్‌ను ఆటోమేటిక్‌గా చదువుతాయి, కాబట్టి దగ్గరి ఫైల్‌కు ప్రాధాన్యత ఉంటుంది మరియు ప్రతి సబ్‌ప్రాజెక్ట్ ప్రత్యేక సూచనలను కలిగి ఉండవచ్చు.

మరియు వైరుధ్యాలు ఏర్పడినప్పుడు:

ఎడిట్ చేస్తున్న ఫైల్‌కు అత్యంత సమీపంలో ఉన్న AGENTS.md గెలుస్తుంది; వినియోగదారు ఇచ్చే స్పష్టమైన చాట్ ప్రాంప్ట్‌లు అన్నింటికంటే ముఖ్యమైనవి.

"ప్రాధాన్యత ఉంటుంది" (Takes precedence) అనే పదాన్ని చాలామంది "root ఫైల్ విస్మరించబడుతుంది" అని అర్థం చేసుకుంటారు. అది నిజం కాదు. ఈ కన్వెన్షన్‌ను అమలు చేసే టూల్స్‌లో, రిపోజిటరీ root నుండి వర్కింగ్ డైరెక్టరీ వరకు ఉన్న మార్గంలోని ప్రతి ఫైల్ చదవబడుతుంది మరియు కలపబడుతుంది. ఒకే విషయంపై రెండు ఫైళ్లు వేర్వేరు సూచనలు ఇచ్చినప్పుడు మాత్రమే సమీపంలోని ఫైల్ నిర్ణయాత్మకం అవుతుంది.

Codex ఈ విధానం గురించి స్పష్టంగా చెబుతోంది: "Codex ఫైళ్లను root నుండి కిందికి కలుపుతుంది, వాటిని ఖాళీ లైన్లతో జత చేస్తుంది. మీ ప్రస్తుత డైరెక్టరీకి దగ్గరగా ఉన్న ఫైళ్లు మునుపటి సూచనలను అధిగమిస్తాయి." Claude Code కూడా దాని ఫైల్ పేరు కోసం ఇదే మార్గాన్ని అనుసరిస్తుంది. వర్కింగ్ డైరెక్టరీకి పైన ఉన్న డైరెక్టరీలలోని ఫైళ్లు "ప్రారంభంలోనే పూర్తిగా లోడ్ అవుతాయి", మరియు "కనుగొనబడిన అన్ని ఫైళ్లు ఒకదానికొకటి అధిగమించకుండా, కాంటెక్స్ట్‌లోకి చేర్చబడతాయి." వర్కింగ్ డైరెక్టరీకి కింద ఉన్న డైరెక్టరీలు భిన్నంగా పనిచేస్తాయి: Claude Code ఆ ఫైళ్లను అవసరమైనప్పుడు మాత్రమే లోడ్ చేస్తుంది, "Claude ఆ డైరెక్టరీలలోని ఫైళ్లను చదివినప్పుడు."

దీనివల్ల రెండు ఆచరణాత్మక పరిణామాలు ఉన్నాయి. root ఫైల్ రిపోజిటరీలోని ప్రతి సెషన్‌కు ప్రిఫిక్స్‌గా ఉంటుంది, కాబట్టి అక్కడ ఉన్న ప్రతి లైన్ కోసం మీరు వారానికి వందసార్లు చెల్లిస్తున్నారని గుర్తుంచుకోండి. ఏజెంట్ వేరే చోట పనిచేస్తున్నప్పుడు ప్రతి-డైరెక్టరీ ఫైల్ ఎటువంటి ఖర్చును కలిగించదు, అంటే అక్కడ వివరాలను చేర్చడం చౌక మరియు అవి అక్కడే ఉండాలి.

ఈ ప్రవర్తనను ఆగస్టు 2026లో Codex మరియు Claude Code డాక్యుమెంటేషన్‌తో సరిచూడడం జరిగింది. టూల్స్ ఈ కన్వెన్షన్‌ను కొద్దిగా భిన్నంగా అమలు చేస్తాయి మరియు అవి మారుతూ ఉంటాయి, కాబట్టి మీ టీమ్ ఉపయోగించే ఏజెంట్ కోసం లోడింగ్ నియమాలను నిర్ధారించుకోండి.

మూడు సర్వీసులతో కూడిన రిపోజిటరీ కోసం ఒక పని చేసే లేఅవుట్

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 ఫైల్‌లో ఉంటుంది: ఒక డైరెక్టరీలో కోడ్‌ను మార్చిన వ్యక్తి, అదే commitలో ఆ డైరెక్టరీకి సంబంధించిన AGENTS.md ఫైల్‌ను కూడా అప్‌డేట్ చేయాలి.

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

pull requestపై ఒక తనిఖీని ఉంచడం ద్వారా ఈ నియమాన్ని అమలు చేయండి. ఇది మార్చబడిన ప్రతి ఫైల్‌కు పైన ఉన్న సమీప 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

డాక్యుమెంటేషన్‌ను మార్చకుండా API clientను రీవర్క్ చేసిన బ్రాంచ్‌లో, అవుట్‌పుట్ ఇలా కనిపిస్తుంది:

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

దీనిని failureగా కాకుండా హెచ్చరికగా (warning) ఉంచండి. కఠినమైన నిబంధన ఉంటే, CI గ్రీన్ అవ్వడం కోసం ప్రజలు ఫైల్‌లో ఖాళీ లైన్‌ను జోడిస్తారు; రోబోను సంతృప్తి పరచడానికి ఎడిట్ చేసిన ఫైల్, అసలు ఫైల్ లేకపోవడం కంటే తక్కువ విలువైనది. ఈ హెచ్చరిక సమీక్షకుడికి అడగడానికి ఒక ప్రశ్నను ఇస్తుంది, అదే నిజంగా పనిచేసే విధానం.

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

కోడ్ తేదీ కంటే డాక్యుమెంట్ తేదీ ఆరు నెలలు వెనుకబడి ఉంటే, ఆ ఫైల్ తప్పు అని అది నిరూపించదు. ఏ ఫైల్‌ను ముందుగా చదవాలో అది మీకు చెబుతుంది, ఒక సెకనులో పూర్తయ్యే తనిఖీ నుంచి మీకు కావలసింది ఇదే.

ఇక లేని పాత్‌ల కోసం వెతకండి. డాక్యుమెంటేషన్ ఒక నిర్దిష్ట పద్ధతిలో పాడవుతుంది: తొలగించబడిన కోడ్‌ను అది వివరిస్తూనే ఉంటుంది. ఈ ఫైళ్లలోని ప్రతి పాత్ బ్యాక్‌టిక్స్‌లో రాయబడి ఉంటుంది, కాబట్టి వాటిని సులభంగా బయటకు తీసి పరీక్షించవచ్చు.

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 వంటి గ్లోబ్స్‌ను మరియు మీరు కోట్ చేసిన ఏదైనా URLను కూడా ఫ్లాగ్ చేస్తుంది, ఎందుకంటే రెండింటిలోనూ స్లాష్ ఉంటుంది మరియు ఏదీ డిస్క్‌పై ఉన్న ఫైల్ కాదు.

సెషన్‌లో కనిపించే లక్షణం. ఏజెంట్ ఫైల్‌ను చదువుతుంది, ఫైల్ చెప్పినట్లుగా src/api/client.tsని తెరవడానికి ప్రయత్నిస్తుంది, అప్పుడు టూల్ ఇలా రిటర్న్ చేస్తుంది:

No such file or directory

కాబట్టి అది సహేతుకమైన పనిని చేసి, దాని స్వంత fetch వ్రాపర్‌ను రాసుకుంటుంది. పాతబడిన ఫైల్ వల్ల కలిగే అసలైన నష్టం ఇదే. ఏజెంట్ మీ డాక్యుమెంటేషన్‌ను విస్మరించదు. అది డాక్యుమెంటేషన్‌ను అనుసరిస్తుంది, మూడు నెలల క్రితం తొలగించబడిన పాత్‌కు చేరుకుంటుంది, మరియు మీ వద్ద ఇప్పటికే ఉన్న కోడ్‌ను మళ్లీ నిర్మిస్తుంది. Ponytail, ఇది ఏజెంట్‌ను పనిచేసే అతి చిన్న మార్పుకు పరిమితం చేస్తుంది వంటి నైపుణ్యం, ఆ పునర్నిర్మాణ ప్రవృత్తిని తగ్గిస్తుంది, కానీ మీ ఫైల్ తప్పుగా చూపిన హెల్పర్‌ను అది కనుగొనలేదు.

Claude Code, AGENTS.md ఫైళ్లను చదువుతుందా?

లేదు, మరియు దీనిపై స్పష్టత ఉండటం అవసరం ఎందుకంటే నెస్టెడ్ లేఅవుట్ దీనిపైనే ఆధారపడి ఉంటుంది. ఆగస్టు 2026 నాటికి డాక్యుమెంటేషన్ ఇలా పేర్కొంది: "Claude Code, CLAUDE.md ను చదువుతుంది, AGENTS.md ను కాదు." ఈ పద్ధతి ఇప్పటికీ పనిచేస్తుంది, మీరు ప్రతి AGENTS.md పక్కన ఒక CLAUDE.md ను ఉంచాలి.

షేర్డ్ లైన్ల పైన టూల్-నిర్దిష్ట లైన్లు కావాలనుకున్నప్పుడు import ఫారమ్ సరైనది. దీన్ని 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 లో symlink కోసం Administrator హక్కులు లేదా Developer Mode అవసరం, కాబట్టి అక్కడ @AGENTS.md import ను ఉపయోగించండి.

దీనితో ఒక సమస్య ఉంది. /compact తర్వాత, రూట్ ఫైల్ డిస్క్ నుండి మళ్ళీ చదవబడుతుంది, కానీ సబ్-డైరెక్టరీలలోని నెస్టెడ్ ఫైళ్లు మళ్ళీ ఇంజెక్ట్ చేయబడవు. ఆ డైరెక్టరీలో ఏజెంట్ ఒక ఫైల్‌ను చదివిన తదుపరిసారి అవి తిరిగి వస్తాయి. ఒకవేళ డైరెక్టరీ-నిర్దిష్ట నియమం సుదీర్ఘ సెషన్ మధ్యలో పనిచేయడం ఆగిపోయినట్లు అనిపిస్తే, సాధారణంగా ఇదే కారణం అవుతుంది, ఆ డైరెక్టరీలోని ఏదైనా ఫైల్‌ను touch చేయడం ద్వారా అది మళ్ళీ పనిచేస్తుంది.

ఇది ఏజెంట్ మెమరీ లేదా స్కిల్ (skill) నుండి ఎలా భిన్నంగా ఉంటుంది?

ఈ యంత్రాంగాలు ఒకేలా కనిపిస్తాయి, కానీ విఫలమయ్యే విధానాలు పూర్తిగా భిన్నంగా ఉంటాయి. కాబట్టి మీరు దేనిని ఉపయోగిస్తున్నారో స్పష్టంగా తెలుసుకోవడం ముఖ్యం.

AGENTS.md ఫైల్‌ను మీరు రాస్తారు, gitలో కమిట్ చేస్తారు, పుల్ రిక్వెస్ట్ ద్వారా రివ్యూ చేస్తారు. రిపోజిటరీని క్లోన్ చేసుకునే ప్రతి ఒక్కరికీ ఇది ఒకేలా ఉంటుంది. ఏజెంట్ మెమరీని ఏజెంట్ స్వయంగా రాస్తుంది, ఇది రిపోజిటరీ వెలుపల నిల్వ చేయబడుతుంది మరియు ఒకే మెషీన్‌కు మాత్రమే పరిమితం అవుతుంది. Claude Code డాక్యుమెంటేషన్ కూడా ఇదే విషయాన్ని స్పష్టం చేస్తుంది: CLAUDE.md లో మీరు రాసే "సూచనలు మరియు నియమాలు" (Instructions and rules) ఉంటాయి, ఆటో మెమరీలో క్లాడ్ రాసే "నేర్చుకున్న విషయాలు మరియు నమూనాలు" (Learnings and patterns) ఉంటాయి, మరియు మెమరీ డైరెక్టరీ మెషీన్ల మధ్య షేర్ చేయబడదు. దీనిని పరీక్షించడం సులభం: ఒక విషయం కొత్తగా క్లోన్ చేసుకున్న సహోద్యోగికి కూడా వర్తించాలంటే, అది మెమరీలో ఉండకూడదు. ఏజెంట్ మెమరీ సెషన్ల మధ్య ఎలా నిలిచి ఉంటుంది అనే విభాగం ఈ అంశాన్ని వివరిస్తుంది.

స్కిల్ (skill) అనేది మూడవ రకం. AGENTS.md అనేది ప్రతి సెషన్‌లో లోడ్ అయ్యే సందర్భం (context); స్కిల్ అనేది అవసరమైనప్పుడు మాత్రమే లోడ్ అయ్యే ఒక ప్రక్రియ (procedure). క్లాడ్ కోడ్ డాక్యుమెంటేషన్ ఒక ఉపయోగకరమైన నియమాన్ని ఇస్తుంది: "ఒక ఎంట్రీ బహుళ దశల ప్రక్రియ అయితే లేదా కోడ్‌బేస్‌లో ఒక భాగానికి మాత్రమే సంబంధించి ఉంటే, దానిని స్కిల్‌కు లేదా పాత్-స్కోప్డ్ (path-scoped) నియమానికి మార్చండి." ఆ వాక్యంలో రెండవ సగం చేసే పనిని నెస్టెడ్ AGENTS.md పరిష్కరిస్తుంది. మొదటి సగం కోసం ఏజెంట్ స్కిల్స్ ఉపయోగపడతాయి. ఒకే ప్రక్రియ ఒకటి కంటే ఎక్కువ రిపోజిటరీలలో అవసరమైనప్పుడు, పది వేర్వేరు AGENTS.md ఫైళ్లలో ఒకే పేరాగ్రాఫ్‌లను కాపీ-పేస్ట్ చేసే బదులు, రిపోజిటరీల మధ్య స్కిల్‌ను షేర్ చేయండి.

"ఈ డాక్యుమెంట్ రాసే సమయానికి ప్రధాన OpenAI రిపోజిటరీలో 88 AGENTS.md ఫైళ్లు ఉన్నాయి" అని అప్‌స్ట్రీమ్ పేర్కొంది. ఆ సంఖ్యే దీనికి బలమైన నిదర్శనం. పెద్ద రిపోజిటరీకి పెద్ద ఫైల్ అవసరం లేదు. దానికి మరిన్ని చిన్న ఫైళ్లు అవసరం. ప్రతి ఫైల్ అది వివరించే కోడ్ పక్కనే ఉండాలి మరియు ఆ కోడ్‌ను చివరిగా మార్చిన వ్యక్తి దాని బాధ్యతను కలిగి ఉండాలి.

FAQ

Nested AGENTS.md ఫైల్ రూట్ ఫైల్‌ను భర్తీ చేస్తుందా లేదా దానికి అదనంగా చేరుస్తుందా?

ఇది దానికి అదనంగా చేరుస్తుంది. "అత్యంత దగ్గరగా ఉన్న ఫైల్ ప్రాధాన్యతను కలిగి ఉంటుంది" అని అప్‌స్ట్రీమ్ పేర్కొంది; ఇది వైరుధ్యం ఏర్పడినప్పుడు ఏమి జరుగుతుందో వివరిస్తుంది కానీ, ఏది లోడ్ అవుతుందో చెప్పదు. Codex "రూట్ నుండి కిందికి ఫైళ్లను ఖాళీ లైన్లతో కలుపుతూ concatenate చేస్తుంది", మరియు Claude Code పని చేస్తున్న డైరెక్టరీ నుండి పైకి వెళ్తూ కనుగొన్న ప్రతి ఫైల్‌ను concatenate చేస్తుంది, వాటిని ఓవర్‌రైడ్ చేయదు. ఒకే అంశంపై రెండు ఫైళ్లు వేర్వేరు సూచనలు ఇచ్చినప్పుడు మాత్రమే దగ్గరగా ఉన్న ఫైల్ నిర్ణయం చెల్లుతుంది. కాబట్టి, ఉమ్మడి నియమాలను రూట్ డైరెక్టరీలో ఒక్కసారి మాత్రమే రాయండి, ప్రతి డైరెక్టరీలో వాటిని పునరావృతం చేయకండి.

రూట్ AGENTS.md ఎంత పరిమాణంలో ఉండాలి?

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

ఈ ఫైళ్లు పాతబడకుండా (stale) ఎలా చూడాలి?

రూట్ ఫైల్‌లో ఒక నియమాన్ని చేర్చండి: ఒక డైరెక్టరీలో కోడ్‌ను మార్చిన వ్యక్తి, అదే కమిట్‌లో ఆ డైరెక్టరీకి సంబంధించిన AGENTS.md ఫైల్‌ను కూడా అప్‌డేట్ చేయాలి. కోడ్ పక్కనే ఫైల్‌ను ఉంచడం వల్ల ఈ నియమం అమలులో ఉంటుంది, ఎందుకంటే ఆ మార్పులు మనిషి పరిశీలిస్తున్న అదే pull request diff లో కనిపిస్తాయి. ప్రతి మార్పు చెందిన పాత్‌ను దానికి పైన ఉన్న సమీప AGENTS.md ఫైల్‌కు మ్యాప్ చేసే CI హెచ్చరికను జోడించండి. అప్పుడప్పుడు ప్రతి ఫైల్‌పై git log -1 --format=%cs రన్ చేసి, అది డాక్యుమెంట్ చేసే డైరెక్టరీలో అదే కమాండ్ ఫలితాలతో సరిపోల్చండి.

Claude Code, AGENTS.md ఫైళ్లను చదువుతుందా?

లేదు. ఆగస్టు 2026 నాటి డాక్యుమెంటేషన్ ప్రకారం "Claude Code, AGENTS.md ను కాకుండా CLAUDE.md ను మాత్రమే చదువుతుంది." అదే డైరెక్టరీలో @AGENTS.md మొదటి లైన్‌లో ఉండేలా ఒక CLAUDE.md ను సృష్టించండి. ఇది షేర్డ్ ఫైల్‌ను లోడ్ చేస్తుంది మరియు దాని కింద మీరు Claude-నిర్దిష్ట సూచనలను జోడించడానికి అనుమతిస్తుంది. అదనంగా ఏమీ జోడించాల్సిన అవసరం లేనప్పుడు ln -s AGENTS.md CLAUDE.md తో సృష్టించిన symlink పనిచేస్తుంది, అయితే Windows లో దీనికి Administrator హక్కులు లేదా Developer Mode అవసరం. సెషన్‌లో /context రన్ చేసి, Memory files కింద ఆ ఫైల్ కనిపిస్తుందో లేదో నిర్ధారించుకోండి.

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

వాటిని AGENTS.md లో ఉంచకూడదు. ఆ ఫైల్ ప్రతి సెషన్‌లో లోడ్ అవుతుంది, కాబట్టి అందులోని ప్రతి లైన్ మీరు టైప్ చేసిన అభ్యర్థనతో పోటీ పడుతుంది. అప్పుడప్పుడు మాత్రమే అవసరమయ్యే బహుళ దశల ప్రక్రియను ఒక skill లో ఉంచాలి, అది అవసరమైనప్పుడు మాత్రమే లోడ్ అవుతుంది. ఒక డైరెక్టరీకి మాత్రమే వర్తించే నియమం ఆ డైరెక్టరీలోని AGENTS.md లో ఉండాలి. డైరెక్టరీ ట్రీ లేదా డిపెండెన్సీ లిస్ట్ వంటి, కోడ్ నుండి నేరుగా చదవగలిగే సమాచారాన్ని వీటిలో దేనిలోనూ ఉంచాల్సిన అవసరం లేదు.