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

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 ఎందుకు పనిచేయడం ఆపుతుంది?

Web app, background worker, Terraform directory ఉన్న repository root లో ఒకే 600-line AGENTS.md ఉంచితే అది నాలుగు వేర్వేరు విధాలుగా విఫలమవుతుంది.

దాన్ని ఎవరూ నిర్వహించరు కాబట్టి అది పాతబడుతుంది. apps/web లోని test script పేరును మార్చే engineer, apps/web కింద ఉన్న files ను edit చేస్తున్నాడు. ఆ మార్పులలో root AGENTS.md ఉండదు. అందువల్ల mismatch ను reviewer ఎవరూ చూడరు. ఆరు వారాల తర్వాత, ఉనికిలో లేని build step ను ఆ file వివరిస్తూనే ఉంటుంది. దాన్ని విరిగేలా చేసిన వ్యక్తికి కూడా ఆ మార్పు గుర్తుండదు.

ప్రతి task కు ఇది context ఖర్చు చేస్తుంది. మీరు ఏమి అడగబోతున్నారో agent కు తెలియకముందే, session ప్రారంభంలో ఈ files load అవుతాయి. Claude Code documentation ఒక పరిమితిని చెబుతుంది: "ప్రతి CLAUDE.md file కు 200 lines కంటే తక్కువగా ఉంచండి. పొడవైన files ఎక్కువ context ను వినియోగించి adherence ను తగ్గిస్తాయి." Combined size 32 KiB కు చేరిన తర్వాత Codex instruction files ను merge చేయడం ఆపుతుంది. ఇదే default project_doc_max_bytes. నాలుగు services ను వివరించే root file, ప్రతి task కోసం ఆ budget లో మూడు services కు సంబంధించిన భాగాన్ని కూడా వినియోగిస్తుంది.

Instructions పరస్పరం విరుద్ధంగా మారతాయి. Web directory కు pnpm test కావాలి. Worker కు pytest -q కావాలి. ఇవన్నీ ఒకే file లో రాస్తే, ప్రతి rule కొంత సమయంలో మాత్రమే సరైనదిగా ఉంటుంది. అందువల్ల ఏది వర్తిస్తుందో agent ఊహించాల్సి వస్తుంది. Claude Code documentation ఫలితాన్ని ఇలా వివరిస్తుంది: "రెండు rules పరస్పరం విరుద్ధంగా ఉంటే, Claude వాటిలో ఒకదాన్ని యాదృచ్ఛికంగా ఎంచుకోవచ్చు." Per-directory file ఈ ఊహాగానాన్ని తొలగిస్తుంది. ఎందుకంటే రెండు rules లో ఒకటి మాత్రమే ఎప్పుడైనా context లో ఉంటుంది. మీరు స్పష్టంగా రాశానని ఖచ్చితంగా తెలిసిన rule అయినా అమలు కాకపోతే, wording ను నాలుగోసారి మార్చడం కంటే instruction ఎప్పుడూ అమలుకాకపోవడానికి గల కారణాలను పరిశీలించడం మెరుగైనది.

Agent code నుంచే చదవగలిగే విషయాలతో అది నిండిపోతుంది. Directory tree, dependency list, ప్రతి package ఏమి చేస్తుందో తెలిపే summary వంటి విషయాలు ఇందులో చేరతాయి. Claude Code యొక్క /doctor check ఇలాంటి విషయాలనే తొలగించడానికి ఉద్దేశించబడింది. ఇది "directory layouts, dependency lists, architecture overviews వంటి codebase నుంచే Claude గుర్తించగల content ను తొలగించి", "tool defaults కు భిన్నంగా ఉండే pitfalls, rationale, conventions" ను ఉంచుతుంది. ఏ line file లో ఉండాలా లేదా అనే విషయాన్ని పరీక్షించడానికి నాకు తెలిసిన ఉత్తమ ప్రమాణం ఇదే.

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

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

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

Conflicts విషయంలో:

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

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

Codex ఈ విధానాన్ని స్పష్టంగా వివరిస్తుంది: "Codex files ను root నుంచి దిగువకు concatenate చేసి, వాటి మధ్య blank lines జతచేస్తుంది. మీ ప్రస్తుత directory కు దగ్గరగా ఉన్న files ముందున్న guidance ను override చేస్తాయి." Claude Code కూడా తన file name కోసం ఇదే path ను పరిశీలిస్తుంది. Working directory పైనున్న directory hierarchy లోని files "launch సమయంలో పూర్తిగా load అవుతాయి", అలాగే "కనుగొనబడిన అన్ని files ఒకదానికొకటి override కాకుండా context లో concatenate అవుతాయి." Working directory క్రింద ఉన్న directories మాత్రం భిన్నంగా పనిచేస్తాయి: Claude Code ఆ files ను "Claude ఆ directories లోని files చదివినప్పుడు" అవసరానుసారం load చేస్తుంది.

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

ఈ ప్రవర్తనను August 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 ను ఎలా గుర్తించాలి?

ఈరోజే అమలు చేయగల రెండు తనిఖీలు ఉన్నాయి. ఒక session లో కనిపించే ఒక లక్షణం కూడా ఉంది.

ప్రతి file వయస్సును, అది వివరించే code వయస్సుతో పోల్చండి. %cs commit date ను 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

Code date కంటే doc date ఆరు నెలలు వెనుకబడి ఉండటం వల్ల file తప్పు అని నిర్ధారించలేం. కానీ ముందుగా ఏ file చదవాలో అది చెబుతుంది. ఒక సెకను పట్టే తనిఖీ నుంచి మీకు కావలసింది అంతే.

ఇక లేని paths కోసం చూడండి. Documentation ఒక నిర్దిష్ట విధంగా పాతబడుతుంది: తొలగించిన code ను ఇంకా వివరిస్తూనే ఉంటుంది. ఈ files లోని ప్రతి path 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

ఈ output ను చదవండి. దీన్ని CI లో చేర్చకండి. ఇది src/**/*.ts వంటి globs ను, మీరు quote చేసిన ఏ URL ను అయినా flag చేస్తుంది. రెండింటిలోనూ slash ఉంటుంది. కానీ వాటిలో ఏదీ disk పై ఉన్న file కాదు.

ఒక session లో కనిపించే లక్షణం. Agent ఆ file ను చదివి, file చెప్పినందుకు src/api/client.ts ను తెరవడానికి ప్రయత్నిస్తుంది. Tool ఇలా తిరిగి ఇస్తుంది:

No such file or directory

అప్పుడు అది సహజంగానే తన స్వంత fetch wrapper ను రాస్తుంది. పాతబడిన file వల్ల కలిగే అసలు ఖర్చు ఇదే. Agent మీ documentation ను విస్మరించదు. అది documentation ను అనుసరిస్తుంది, మూడు నెలల క్రితం తొలగించిన path వద్దకు చేరుతుంది, ఇప్పటికే మీ వద్ద ఉన్న code ను మళ్లీ నిర్మిస్తుంది. పనిచేసే అతి చిన్న మార్పుకే agent ను పరిమితం చేసే Ponytail వంటి skill ఈ పునర్నిర్మాణ ధోరణిని తగ్గిస్తుంది. కానీ మీ file తప్పు స్థానాన్ని సూచించినప్పుడు, ఆ helper ను అది కనుగొనలేదు.

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

లేదు. Nested layout దీనిపై ఆధారపడుతుంది కాబట్టి ఈ విషయాన్ని స్పష్టంగా చెప్పాలి. August 2026 నాటికి documentation ఇలా చెబుతోంది: "Claude Code reads CLAUDE.md, not AGENTS.md." ఈ విధానం ఇప్పటికీ పనిచేస్తుంది. ప్రతి AGENTS.md పక్కన ఒక CLAUDE.md ఉంచాలి.

Shared lines కు అదనంగా tool-specific lines కావాలనుకుంటే import విధానం సరైనది. దీన్ని 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 ను చూపించదు. కాబట్టి listing ను తనిఖీ చేయండి: apps/web/CLAUDE.md -> AGENTS.md. తరువాత ఒక session ప్రారంభించి /context ను అమలు చేయండి. Loaded files Memory files కింద కనిపిస్తాయి. Windows లో symlink కోసం Administrator హక్కులు లేదా Developer Mode అవసరం. అందువల్ల అక్కడ @AGENTS.md import ను ఉపయోగించండి.

ఇందులో ఒక ముఖ్యమైన జాగ్రత్త ఉంది. /compact తరువాత root file డిస్క్ నుంచి మళ్లీ చదవబడుతుంది. కానీ subdirectories లోని nested files మళ్లీ inject కావు. ఆ directory లో agent తదుపరి సారి ఏదైనా file చదివినప్పుడు అవి తిరిగి వస్తాయి. ఎక్కువసేపు నడిచే session మధ్యలో per-directory rule అమలు కావడం ఆగినట్లు కనిపిస్తే సాధారణంగా కారణం ఇదే. ఆ directory లోని ఏదైనా file ను touch చేస్తే అవి తిరిగి వస్తాయి.

ఇది 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 file ను భర్తీ చేస్తుందా, లేక దానికి జత అవుతుందా?

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

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

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

ఈ files పాతబడకుండా ఎలా చూడాలి?

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

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

లేదు. August 2026 నాటికి documentation “Claude Code CLAUDE.md ను చదువుతుంది, AGENTS.md ను కాదు” అని చెబుతుంది. అదే directory లో CLAUDE.md ను సృష్టించి, మొదటి line లో @AGENTS.md ఉంచండి. ఇది shared file ను load చేస్తుంది. ఆ తరువాత Claude-specific instructions ను జోడించవచ్చు. అదనంగా ఏదీ జోడించాల్సిన అవసరం లేకపోతే ln -s AGENTS.md CLAUDE.md తో సృష్టించిన symlink పనిచేస్తుంది. అయితే Windows లో దీనికి Administrator rights లేదా Developer Mode అవసరం. ఒక session లో /context ను run చేసి, Memory files కింద ఆ file కనిపిస్తుందో నిర్ధారించండి.

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

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