Monorepo-வில் nested AGENTS.md கோப்புகளை அமைப்பது எப்படி?
Monorepo-வில் ஒரே ஒரு root AGENTS.md கோப்பு காலாவதியாவதைத் தவிர்க்கவும். ஒவ்வொரு directory-க்கும் தனித்தனி கோப்புகளைப் பயன்படுத்தி AI agent-ன் context துல்லியத்தை மேம்படுத்தும் முறை.
Monorepo-வில் nested AGENTS.md என்பதன் பொருள்
Monorepo-வில் nested AGENTS.md என்பது, repository-ன் root-ல் ஒரு சிறிய கோப்பும், ஒவ்வொரு service directory-க்குள்ளும் ஒரு கோப்பும் இருப்பதைக் குறிக்கிறது. Root கோப்பில் அனைத்து இடங்களுக்கும் பொதுவான சில விதிகள் மற்றும் பிற கோப்புகள் எங்கு உள்ளன என்பதற்கான வரைபடம் (map) இருக்கும். ஒவ்வொரு service கோப்பிலும் அந்த directory-க்கு மட்டும் உரிய கட்டளைகள் மற்றும் மரபுகள் (conventions) இருக்கும். ஒரு agent services/worker/queue.py-ஐத் திருத்தும்போது, அது root கோப்பையும் அந்த குறிப்பிட்ட worker கோப்பையும் மட்டுமே வாசிக்கும்; அது தொடவே போகாத front end-க்கான context-ஐ வீணாக்காது.
இதில் நிறுவுவதற்கு எதுவுமில்லை. AGENTS.md என்பது ஒரு மரபு மட்டுமே, upstream project இதைத் தெளிவாகக் கூறுகிறது:
AGENTS.md என்பது ஒரு சாதாரண Markdown கோப்பு. நீங்கள் விரும்பும் தலைப்புகளைப் பயன்படுத்தலாம்; நீங்கள் வழங்கும் உரையை agent எளிமையாகப் புரிந்துகொள்ளும்.
இதனால்தான் இந்த நுட்பத்தை முறையாகக் கற்றுக்கொள்வது அவசியம். இதன் வடிவம் மாறாது. இதில் ஏற்படும் சிக்கல்கள் அனைத்தும் கோப்புகளை வைக்கும் இடம் மற்றும் அவற்றைப் பராமரிப்பதில் மட்டுமே வரும்; இவை இரண்டையும் கவனித்துக்கொள்வது உங்கள் பொறுப்பு.
ஏன் ஒரு பெரிய root AGENTS.md கோப்பு வேலை செய்வதை நிறுத்துகிறது?
ஒரு web app, background worker மற்றும் Terraform directory ஆகியவற்றைக் கொண்ட repository-ன் root-ல் உள்ள 600 வரிகள் கொண்ட ஒரே AGENTS.md கோப்பு, நான்கு வெவ்வேறு வழிகளில் தோல்வியடைகிறது.
யாரும் இதைப் பராமரிக்காததால், இது காலாவதியாகிறது. apps/web-ல் உள்ள ஒரு test script-ஐ மறுபெயரிடும் பொறியாளர், apps/web-க்கு உட்பட்ட கோப்புகளை மட்டுமே திருத்துகிறார். root AGENTS.md அந்த diff-ல் இல்லாததால், எந்த reviewer-ம் அந்த முரண்பாட்டைக் கவனிப்பதில்லை. ஆறு வாரங்களுக்குப் பிறகு, அந்தக் கோப்பு ஏற்கனவே இல்லாத ஒரு build step-ஐ விவரிக்கிறது, அதை மாற்றிய நபரும் அந்த மாற்றத்தை மறந்துவிடுகிறார்.
ஒவ்வொரு பணியின் போதும் இது context-ஐ வீணாக்குகிறது. நீங்கள் என்ன கேட்கப் போகிறீர்கள் என்று agent-க்குத் தெரிவதற்கு முன்பே, session-ன் தொடக்கத்தில் இந்தக் கோப்புகள் load ஆகிவிடும். Claude Code-ன் ஆவணங்கள் இதைப் பற்றி குறிப்பிடுகின்றன: "ஒவ்வொரு CLAUDE.md கோப்பையும் 200 வரிகளுக்குக் கீழ் வைத்திருக்கவும். நீண்ட கோப்புகள் அதிக context-ஐ எடுத்துக்கொண்டு, அறிவுறுத்தல்களைப் பின்பற்றும் திறனைக் குறைக்கின்றன." instruction கோப்புகளின் மொத்த அளவு 32 KiB-ஐ (இயல்புநிலை project_doc_max_bytes) எட்டும்போது, Codex அவற்றை இணைப்பதை நிறுத்திவிடும். நான்கு service-களை விவரிக்கும் ஒரு root கோப்பு, ஒவ்வொரு பணியின் போதும் அவற்றில் மூன்றிற்கான budget-ஐ வீணாக்குகிறது.
அறிவுறுத்தல்கள் ஒன்றுக்கொன்று முரண்படத் தொடங்குகின்றன. web directory-க்கு pnpm test தேவைப்படுகிறது. worker-க்கு pytest -q தேவைப்படுகிறது. ஒரே கோப்பில் எழுதப்படும்போது, ஒவ்வொரு விதியும் சில நேரங்களில் மட்டுமே சரியாக இருக்கும், எனவே எது பொருந்தும் என்று agent யூகிக்க வேண்டிய கட்டாயம் ஏற்படுகிறது. Claude Code-ன் ஆவணங்கள் இதன் விளைவை விவரிக்கின்றன: "இரண்டு அறிவுறுத்தல்கள் முரண்பட்டால், Claude ஏதேனும் ஒன்றை தன்னிச்சையாகத் தேர்ந்தெடுக்கலாம்." கோப்பைப் பிரிப்பதன் மூலம் மற்ற விதியை context-லிருந்து நீக்கிவிட முடியாது. Claude Code தான் load செய்த அனைத்து instruction கோப்புகளையும் ஒன்றிணைக்கிறது, எனவே root கோப்பு எப்போதும் அங்கேயே இருக்கும். agent apps/web மற்றும் services/worker ஆகிய இரண்டிலும் கோப்புகளைத் திறந்தவுடன், இரண்டு directory கோப்புகளும் ஒரே நேரத்தில் context-ல் இருக்கும். ஒரு directory-க்குரிய கோப்பு என்ன செய்கிறது என்றால், ஒவ்வொரு விதியையும் அது நிர்வகிக்கும் directory-யுடன் இணைக்கிறது. கீழே உள்ள # apps/web உதாரணங்களைப் போல, கோப்பின் தொடக்கத்தில் directory-ன் பெயரை குறிப்பிடவும். பல கோப்புகள் ஒரே நேரத்தில் load செய்யப்படும்போது, ஒவ்வொரு கட்டளையும் அது எங்கு பொருந்தும் என்பதைத் தெளிவுபடுத்தும். நீங்கள் தெளிவாக எழுதிய ஒரு விதி புறக்கணிக்கப்படும்போது, அதை நான்காவது முறையாக மாற்றி எழுதுவதை விட, ஒரு அறிவுறுத்தல் ஏன் செயல்படவில்லை என்பதற்கான காரணங்களை ஆராய்வது சிறந்தது.
agent குறியீட்டிலிருந்தே படித்துக்கொள்ளக்கூடிய தகவல்களால் இது நிரம்புகிறது. ஒரு directory tree, dependency பட்டியல், ஒவ்வொரு package-ம் என்ன செய்கிறது என்பதன் சுருக்கம் போன்றவை. Claude Code-ன் /doctor சரிபார்ப்பு இதற்காகவே உள்ளது. இது "directory அமைப்புகள், dependency பட்டியல்கள் மற்றும் architecture மேலோட்டங்கள் போன்ற, குறியீட்டிலிருந்து Claude-ஆல் பெறக்கூடிய உள்ளடக்கங்களை நீக்குகிறது" மற்றும் "கருவிகளின் இயல்புநிலைகளிலிருந்து மாறுபடும் சிக்கல்கள், காரணங்கள் மற்றும் மரபுகளை" மட்டும் வைத்திருக்கிறது. ஒரு வரி இந்தக் கோப்பில் இருக்க வேண்டுமா என்பதைத் தீர்மானிக்க, அந்த வாக்கியமே எனக்குத் தெரிந்த சிறந்த சோதனை ஆகும்.
Agent root கோப்பை மட்டும் வாசிக்கிறதா அல்லது அருகிலுள்ள கோப்பை மட்டும் வாசிக்கிறதா?
இங்குதான் பெரும்பாலானோர் இந்த மாதிரியைத் தவறாகப் புரிந்துகொள்கிறார்கள், எனவே இதைச் சுருக்கிக் கூறுவதை விட, மூல ஆவணத்தில் உள்ள மரபையே மேற்கோள் காட்டுவது சிறந்தது:
ஒவ்வொரு package-க்குள்ளும் மற்றொரு AGENTS.md கோப்பை வைக்கவும். Agent-கள் தானாகவே directory tree-ல் அருகிலுள்ள கோப்பை வாசிக்கும், எனவே மிக அருகில் உள்ள கோப்பிற்கு முன்னுரிமை அளிக்கப்படும், மேலும் ஒவ்வொரு subproject-ம் அதற்கேற்ற அறிவுறுத்தல்களை வழங்க முடியும்.
மற்றும் முரண்பாடுகள் குறித்து:
திருத்தப்படும் கோப்பிற்கு மிக அருகில் உள்ள AGENTS.md வெற்றி பெறும்; பயனர் நேரடியாகத் தரும் chat prompts மற்ற அனைத்தையும் விட மேலானவை.
"முன்னுரிமை அளிக்கப்படும்" (Takes precedence) என்பதைப் பலர் "root கோப்பு புறக்கணிக்கப்படுகிறது" என்று தவறாகப் புரிந்துகொள்கிறார்கள். அது உண்மையல்ல. இந்த மரபைச் செயல்படுத்தும் கருவிகளில், repository root-லிருந்து working directory வரை உள்ள பாதையில் உள்ள அனைத்துக் கோப்புகளும் வாசிக்கப்பட்டு ஒன்றாக இணைக்கப்படுகின்றன. ஒரே விஷயத்தைப் பற்றி இரண்டு கோப்புகள் வெவ்வேறு கருத்துகளைக் கூறும்போது மட்டுமே அருகிலுள்ள கோப்பு வெற்றி பெறுகிறது.
Codex இந்தச் செயல்பாட்டைத் தெளிவாகக் கூறுகிறது: "Codex root-லிருந்து கீழாகக் கோப்புகளை ஒன்றிணைத்து, அவற்றுக்கிடையே காலி வரிகளைச் சேர்க்கிறது. உங்கள் தற்போதைய directory-க்கு அருகில் உள்ள கோப்புகள் முந்தைய வழிகாட்டுதல்களை விட மேலானவை." Claude Code-ம் இதே பாதையைப் பின்பற்றுகிறது. அமர்வின் தொடக்கத்தில், அது "உங்கள் working directory மற்றும் அதற்கு மேல் உள்ள directories-ல் உள்ள ஒவ்வொரு AGENTS.md மற்றும் .claude/AGENTS.md கோப்பையும்" வாசிக்கிறது. அதன் ஆவணங்கள் இந்த loading மாதிரியைத் தெளிவாக விளக்குகின்றன: "கண்டறியப்பட்ட அனைத்துக் கோப்புகளும் ஒன்றையொன்று மேவிச் செல்வதற்குப் பதிலாக, context-ல் ஒன்றாக இணைக்கப்படுகின்றன." Working directory-க்கு கீழே உள்ள directories வித்தியாசமாகச் செயல்படுகின்றன: Claude Code ஒரு subdirectory-ன் AGENTS.md கோப்பைத் தேவைப்படும்போது மட்டுமே, அதாவது "Claude அங்குள்ள ஒரு கோப்பை Read கருவி மூலம் திறக்கும்போது" ஏற்றுகிறது.
இதன் விளைவாக இரண்டு நடைமுறை மாற்றங்கள் ஏற்படுகின்றன. Root கோப்பு என்பது repository-ல் உள்ள ஒவ்வொரு அமர்விற்கும் ஒரு முன்னொட்டாக (prefix) அமைகிறது, எனவே அங்குள்ள ஒவ்வொரு வரியையும் நீங்கள் வாரத்திற்கு நூறு முறை பயன்படுத்துகிறீர்கள் என்பதை நினைவில் கொள்ளுங்கள். ஒரு directory-க்கு உட்பட்ட கோப்பு, அந்த directory-ல் உள்ள கோப்பை agent திறக்கும் வரை எந்தச் செலவையும் ஏற்படுத்தாது. எனவே, விரிவான தகவல்களை அங்கு வைப்பது சிக்கனமானது மற்றும் பொருத்தமானது.
இந்தச் செயல்பாடு 27 October 2026 அன்று Codex மற்றும் Claude Code ஆவணங்களுடன் சரிபார்க்கப்பட்டது. கருவிகள் இந்த மரபைச் சற்று வித்தியாசமாகச் செயல்படுத்தலாம் மற்றும் அவை மாறக்கூடும், எனவே உங்கள் குழு பயன்படுத்தும் எந்த agent-க்கும் loading விதிகளை உறுதிப்படுத்திக் கொள்ளுங்கள்.
மூன்று சேவைகளைக் கொண்ட ஒரு களஞ்சியத்திற்கான வேலை செய்யும் கட்டமைப்பு
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 scriptsroot கோப்பு வேண்டுமென்றே சுருக்கமாக வைக்கப்பட்டுள்ளது. இது எங்கு தேட வேண்டும் என்பதைக் குறிப்பிடுகிறது, மேலும் அனைத்து கோப்பகங்களிலும் பொருந்தக்கூடிய விதிகளை மட்டுமே கொண்டுள்ளது.
# 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.கோப்பகத்திற்குரிய (per-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 கோப்பும் அதே அமைப்பைக் கொண்டது, ஆனால் உள்ளடக்கங்கள் வேறுபட்டவை: நிறுவல் கட்டளை (install command), pytest -q, நுகர்வோர் (consumer) ஏன் idempotent-ஆக இருக்க வேண்டும் என்பதற்கான காரணம், மற்றும் சோதனைகள் வெற்றிபெற இயங்க வேண்டிய migration. infra கோப்பில்தான் ஒரு agent சேதம் விளைவிப்பதைத் தடுக்கும் விதிகளை எழுத வேண்டும். terraform apply-ஐ ஒருபோதும் இயக்க வேண்டாம். terraform plan-ஐ இயக்கி அங்கேயே நிறுத்தவும், மேலும் ஏற்கனவே கட்டமைக்கப்பட்ட state backend-ஐக் குறிப்பிடவும், அப்போதுதான் agent புதிய ஒன்றை உருவாக்க முயற்சிக்காது.
இந்தக் கோப்புகளில் எதுவுமே இல்லை என்பதைக் கவனியுங்கள்: ஒவ்வொரு சேவையும் எதற்காக என்பது பற்றிய விளக்கம். அது மனிதர்களுக்கு உரியது. Upstream-ம் இதே கோட்டை வரைகிறது, "README.md கோப்புகள் மனிதர்களுக்கானவை: விரைவான தொடக்கம் (quick starts), திட்ட விளக்கங்கள் மற்றும் பங்களிப்பு வழிகாட்டுதல்கள்", அதே சமயம் AGENTS.md-ல் "கோடிங் ஏஜெண்டுகளுக்குத் தேவையான கூடுதல், சில நேரங்களில் விரிவான சூழல்: build படிகள், சோதனைகள் மற்றும் மரபுகள்" இடம்பெறுகின்றன. AGENTS.md மற்றும் மனிதர்களுக்கான README ஆகியவற்றுக்கு இடையேயான பிரிப்பு அந்த எல்லையை வாக்கியம் வாரியாக விளக்குகிறது, மேலும் குறியீடு ஏன் அந்த வடிவில் உள்ளது என்பதைப் பதிவு செய்யும் DESIGN.md மூன்றாவது கோப்பை உள்ளடக்கியது, இது கட்டளைகளை விட முடிவுகளுக்கான காரணங்களை விளக்குகிறது.
குறியீடு மாறும்போது கோப்பை யார் புதுப்பிப்பது?
ஒரு விதி உள்ளது, அது root கோப்பில் அமையும்: ஒரு கோப்பகத்தில் (directory) குறியீட்டை மாற்றும் எவரும், அதே commit-ல் அந்த கோப்பகத்தின் AGENTS.md கோப்பையும் புதுப்பிக்க வேண்டும்.
இது கலாச்சார ரீதியான காரணம் அல்ல, இயந்திர ரீதியான காரணத்திற்காகச் செயல்படுகிறது. கோப்பகத்திற்குரிய கோப்பு, குறியீடு இருக்கும் அதே diff-ல் இருப்பதால், pull request-ஐ மதிப்பாய்வு செய்பவர் இரண்டையும் ஒரே நேரத்தில் பார்க்க முடியும். root கோப்பு அனைவருக்கும் சொந்தமானது, அதாவது அது யாருக்கும் சொந்தமில்லை; மேலும் அது எவரும் வாசிக்கும் diff-ல் இருப்பதில்லை.
pull request-ல் ஒரு சரிபார்ப்பு (check) மூலம் இந்த விதியை உறுதிப்படுத்தவும். இது மாற்றப்பட்ட ஒவ்வொரு கோப்பிற்கும் மேலே உள்ள அருகிலுள்ள 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-ஐ மறுசீரமைப்பு செய்த ஒரு branch-ல், வெளியீடு இவ்வாறு இருக்கும்:
note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updatedஇதை ஒரு தோல்வியாகக் கருதாமல், எச்சரிக்கையாக (warning) மட்டும் வைக்கவும். ஒரு கடுமையான கட்டுப்பாடு இருந்தால், CI பச்சை நிறத்திற்கு மாற வேண்டும் என்பதற்காக மக்கள் கோப்பில் ஒரு வெற்று வரியைச் சேர்ப்பார்கள். ஒரு ரோபோவைத் திருப்திப்படுத்த மாற்றப்பட்ட கோப்பு, கோப்பே இல்லாததை விட மோசமானது. இந்த எச்சரிக்கை மதிப்பாய்வு செய்பவரிடம் ஒரு கேள்வியைக் கேட்கத் தூண்டும்; அதுவே உண்மையில் பயனுள்ள பகுதியாகும்.
AGENTS.md காலாவதியாகிவிட்டதை எப்படிக் கண்டறிவது?
இன்று நீங்கள் செய்யக்கூடிய இரண்டு சோதனைகளும், ஒரு session-க்குள் நீங்கள் காணக்கூடிய ஒரு அறிகுறியும் கீழே கொடுக்கப்பட்டுள்ளன.
ஒவ்வொரு கோப்பின் வயதையும் அது விவரிக்கும் குறியீட்டின் (code) வயதையும் ஒப்பிட்டுப் பாருங்கள். %cs என்பது commit தேதியை 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-ஐயும் பிழையாகக் காட்டும், ஏனெனில் இவை இரண்டிலும் slash உள்ளது, மேலும் இவை வட்டில் (disk) உள்ள கோப்புகள் அல்ல. Claude Code v2.1.283 அல்லது அதற்குப் பிந்தைய பதிப்புகளில், /doctor prompt-audit உங்களுக்காக இதே போன்ற ஒரு சோதனையைச் செய்கிறது: இது "இல்லாத கோப்புகள் அல்லது கட்டளைகளுக்கான குறிப்புகளை" மற்றும் ஒன்றுக்கொன்று முரணான கோப்புகளைத் தேடுகிறது, உங்கள் AGENTS.md கோப்புகளை இயல்பாகவே உள்ளடக்குகிறது, மேலும் நீங்கள் மாற்றங்களைச் செய்யச் சொல்லும் வரை எதையும் மாற்றாது.
ஒரு session-ல் ஏற்படும் அறிகுறி. முகவர் (agent) கோப்பைப் படிக்கிறது, கோப்பு சொன்னதால் src/api/client.ts-ஐத் திறக்க முயல்கிறது, ஆனால் கருவி (tool) பின்வருவனவற்றைத் தருகிறது:
No such file or directoryஎனவே, அது தர்க்கரீதியாகச் செயல்பட்டு தனது சொந்த fetch wrapper-ஐ உருவாக்குகிறது. இதுவே காலாவதியான கோப்பினால் ஏற்படும் உண்மையான இழப்பு. முகவர் உங்கள் ஆவணங்களைப் புறக்கணிப்பதில்லை. அது ஆவணத்தைப் பின்பற்றி, மூன்று மாதங்களுக்கு முன்பு நீக்கப்பட்ட ஒரு பாதைக்குச் சென்று, உங்களிடம் ஏற்கனவே உள்ள குறியீட்டை மீண்டும் உருவாக்குகிறது. Ponytail, இது ஒரு முகவரைச் செயல்படும் மிகச்சிறிய மாற்றத்திற்குள் வைத்திருக்கிறது போன்ற ஒரு திறன், இந்த மீண்டும் உருவாக்கும் பழக்கத்தைக் குறைக்கும், ஆனால் உங்கள் கோப்பு தவறான இடத்தைச் சுட்டிக்காட்டும் ஒரு உதவியாளரை அதனால் கண்டறிய முடியாது.
Claude Code, AGENTS.md கோப்புகளை வாசிக்குமா?
ஆம், Claude Code v2.1.277 பதிப்பிலிருந்து இது சாத்தியம். கோப்பு முறைமை (nested layout) இதைச் சார்ந்திருப்பதால், துல்லியமான விதிகள் முக்கியம். அக்டோபர் 27, 2026 அன்று ஆவணப்படுத்தப்பட்ட தகவலின்படி: "Claude Code உங்கள் திட்ட அறிவுறுத்தல்களாக AGENTS.md-ஐ வாசிக்க முடியும். எனவே, பிற கோடிங் ஏஜெண்டுகளுக்காக ஏற்கனவே அமைக்கப்பட்ட களஞ்சியத்தில் (repository) புதிய CLAUDE.md, இறக்குமதி (import) அல்லது அமைப்புகளைச் சேர்க்க வேண்டிய அவசியமில்லை." இயல்பான Project instructions மதிப்பு, claude-md-or-agents-md, "உங்கள் பணி அடைவு (working directory) அல்லது அதற்கு மேல் CLAUDE.md அல்லது CLAUDE.local.md இல்லாதபோது உங்கள் AGENTS.md கோப்புகளை" வாசிக்கும் என்று குறிப்பிடுகிறது. உள்ளமைக்கப்பட்ட (nested) கோப்புகளும் இதில் அடங்கும்: "அந்த உட்பிரிவில் (subdirectory) சொந்தமாக மூன்று CLAUDE.md கோப்புகள் இல்லாதவரை", Claude அங்குள்ள ஒரு கோப்பை Read கருவி மூலம் திறக்கும்போது அதன் AGENTS.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 அல்லது telemetry முடக்கப்பட்ட நிலையில்), CLAUDE.md கோப்புகள் மட்டுமே வாசிக்கப்படும். v2.1.276 அல்லது அதற்கு முந்தைய பதிப்பிலிருந்து மேம்படுத்திய பிறகு முதல் அமர்வில் AGENTS.md-ம் தவிர்க்கப்படலாம்: "அடுத்த அமர்விலிருந்து Claude AGENTS.md-ஐ வாசிக்கும்" என்று ஆவணங்கள் கூறுகின்றன. எனவே அமர்வைச் சரிபார்க்கவும். ஒரு ஊடாடும் அமர்வில் (interactive session), Claude Code no CLAUDE.md found; AGENTS.md loaded: போன்ற ஒரு வரியை பாதையுடன் அச்சிடும். தற்போதைய பதிப்புகளில் /memory அந்த கோப்பை பட்டியலிடும். v2.1.280-க்கு முன்பு, /memory மற்றும் /context ஆகியவை Claude நேரடியாக வாசித்த AGENTS.md-ஐ பட்டியலிடவில்லை. எனவே அந்த பதிப்புகளில், திட்ட அறிவுறுத்தல்கள் என்ன சொல்கின்றன என்று Claude-இடமே கேட்கவும்.
Claude நேரடியாக AGENTS.md-ஐ வாசிக்க முடியாத இடங்களில் இறக்குமதி முறை (import form) இன்னும் சரியாகச் செயல்படும்: பழைய பதிப்பு, Amazon Bedrock-ல் v2.1.281-க்கு முந்தைய அமர்வு, telemetry முடக்கப்பட்ட நிலை, அதை வாசிக்கும் உள்ளமைக்கப்பட்ட பிளகின் முடக்கப்பட்ட நிலை, அல்லது 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.mdln வெற்றிகரமாகச் செயல்படும்போது எதையும் அச்சிடாது, எனவே பட்டியலைச் சரிபார்க்கவும்: apps/web/CLAUDE.md -> AGENTS.md. பிறகு ஒரு அமர்வைத் தொடங்கி /context-ஐ இயக்கவும்; அங்கு ஏற்றப்பட்ட கோப்புகள் Memory files என்பதன் கீழ் தோன்றும். Windows-ல் ஒரு symlink-க்கு Administrator உரிமைகள் அல்லது Developer Mode தேவை. Git ஒரு committed symlink-ஐ சாதாரண உரை கோப்பாகவே (plain text file) கையாளும், core.symlinks இயக்கப்பட்டிருந்தால் ஒழிய. இல்லையெனில், அந்த clone-ல் உங்கள் அறிவுறுத்தல்களுக்குப் பதிலாக ஒரு வரி கொண்ட CLAUDE.md மட்டுமே இருக்கும். களஞ்சியத்தை clone செய்யும் எவராவது Windows-ல் பணிபுரிந்தால், @AGENTS.md இறக்குமதி முறையைப் பயன்படுத்தவும். Claude Code தானாகவே AGENTS.md-ஐ வாசிப்பதற்கு முன்பு நீங்கள் ஏதேனும் ஒரு தீர்வை அமைத்திருந்தால், அதை அப்படியே விடலாம்: "இறக்குமதி முறை Claude-ஐ AGENTS.md-ஐ இருமுறை வாசிக்கச் செய்யாது" என்றும், symlink செய்யப்பட்ட CLAUDE.md ஒருமுறை மட்டுமே வாசிக்கப்படும் என்றும் ஆவணங்கள் கூறுகின்றன.
இதில் ஒரு சிக்கல் உள்ளது. /compact-க்குப் பிறகு, திட்டத்தின் ரூட் அடைவில் உள்ள CLAUDE.md வட்டில் இருந்து மீண்டும் வாசிக்கப்படும், ஆனால் உட்பிரிவுகளில் உள்ள கோப்புகள் மீண்டும் செலுத்தப்படாது (re-injected). அந்த அடைவில் உள்ள கோப்புடன் ஏஜெண்ட் அடுத்த முறை பணிபுரியும்போது, Claude Code அவற்றை தேவைக்கேற்ப மீண்டும் ஏற்றும். CLAUDE.md கோப்புகளுக்கு ஆவணங்கள் இதைத் தெளிவாகக் கூறுகின்றன, நேரடியாக வாசிக்கப்படும் AGENTS.md-க்கு தனிப்பட்ட சுருக்கத்தை (compaction) விவரிக்கவில்லை. எனவே, இரண்டு பெயர்களில் உள்ள உள்ளமைக்கப்பட்ட கோப்புகளும் இதேபோல் செயல்படும் என்று எதிர்பார்க்கலாம். ஒரு நீண்ட அமர்வின் பாதியில் ஒரு அடைவுக்கான விதி செயல்படவில்லை என்றால், அதற்கு இதுவே காரணமாக இருக்கும். அந்த அடைவில் உள்ள ஏதேனும் ஒரு கோப்பை வாசிப்பது அந்த விதியை மீண்டும் செயல்படுத்தும்.
பிற ஏஜெண்டுகளை AGENTS.md-க்கு வழிநடத்தும் அமைப்புகள்
Codex AGENTS.md-ஐ இயல்பாகவே வாசிக்கும். ஒவ்வொரு நிலையிலும் முதலில் AGENTS.override.md உள்ளதா என்று சரிபார்க்கும்; இது பகிரப்பட்ட கோப்பைத் திருத்தாமல் ஒரு அடைவுக்கு மட்டும் உள்ளூர் மாற்றத்தை (local override) வழங்குகிறது. ஒருங்கிணைந்த அளவு 32 KiB-ஐ (இயல்புநிலை project_doc_max_bytes) எட்டியதும் அது இணைப்பதை நிறுத்திவிடும். ரூட் கோப்பைச் சிறியதாக வைத்திருக்க இதுவே கூடுதல் காரணம்.
Aider இதை .aider.conf.yml மூலம் read: AGENTS.md என்ற வரியுடன் எடுத்துக்கொள்ளும்.
Gemini CLI இதை .gemini/settings.json மூலம் { "context": { "fileName": "AGENTS.md" } }-டன் எடுத்துக்கொள்ளும்.
பழைய ஒற்றைப் பெயரைப் பயன்படுத்தும் களஞ்சியங்களுக்காக, பின்தங்கிய இணக்கத்தன்மை கொண்ட (backward-compatible) மறுபெயரிடலை ஆவணங்கள் குறிப்பிடுகின்றன: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.
மிகப்பெரிய monorepo-வில், Claude Code-ன் claudeMdExcludes அமைப்பு பாதை அல்லது glob மூலம் முன்னோடி கோப்புகளைத் தவிர்க்கிறது. மற்றொரு குழுவின் அடைவு உங்கள் அடைவுக்கு மேலே இருக்கும்போது இது பயனுள்ளதாக இருக்கும். இதன் வடிவங்கள் (patterns) Claude Code வாசிக்கும் AGENTS.md கோப்புகளுக்கும் பொருந்தும்.
இது agent memory அல்லது skill-லிருந்து எவ்வாறு வேறுபடுகிறது?
இந்த வழிமுறைகள் பார்ப்பதற்கு ஒரே மாதிரியாகத் தெரிந்தாலும், அவை முற்றிலும் மாறுபட்ட வழிகளில் தோல்வியடைகின்றன. எனவே, நீங்கள் எதைப் பயன்படுத்தப் போகிறீர்கள் என்பதில் துல்லியமாக இருப்பது அவசியம்.
AGENTS.md கோப்பை நீங்கள் உருவாக்குகிறீர்கள், git-ல் commit செய்கிறீர்கள், pull request மூலம் ஆய்வு செய்கிறீர்கள். இந்த repository-ஐ clone செய்யும் அனைவருக்கும் இது ஒரே மாதிரியாகவே இருக்கும். Agent memory என்பது agent-ஆல் எழுதப்பட்டு, repository-க்கு வெளியே சேமிக்கப்பட்டு, ஒரு குறிப்பிட்ட machine-க்கு மட்டுமே உரியதாக இருக்கும். Claude Code-ன் ஆவணங்களும் இதே வேறுபாட்டைத்தான் குறிப்பிடுகின்றன: CLAUDE.md என்பது நீங்கள் எழுதும் "Instructions and rules"-ஐக் கொண்டுள்ளது; auto memory என்பது Claude எழுதும் "Learnings and patterns"-ஐக் கொண்டுள்ளது; மேலும் memory directory என்பது பல்வேறு machine-களுக்கு இடையே பகிரப்படுவதில்லை. இதற்கான சோதனை எளிதானது: ஒரு தகவல் புதிய clone-ல் இருக்கும் சக ஊழியருக்கும் உண்மையாக இருக்க வேண்டும் என்றால், அது memory-ல் இருக்க முடியாது. How agent memory persists between sessions என்பது அந்தப் பகுதியைப் பற்றி விளக்குகிறது.
Skill என்பது மூன்றாவது வகை. AGENTS.md என்பது ஒவ்வொரு session-லும் load ஆகும் context; skill என்பது தேவைப்படும்போது மட்டும் load ஆகும் ஒரு செயல்முறை (procedure). Claude Code ஆவணங்கள் ஒரு பயனுள்ள விதியை வழங்குகின்றன: "ஒரு entry என்பது பல படிகளைக் கொண்ட செயல்முறையாக இருந்தாலோ அல்லது codebase-ன் ஒரு பகுதிக்கு மட்டும் முக்கியமானதாக இருந்தாலோ, அதை ஒரு skill-ஆகவோ அல்லது path-scoped rule-ஆகவோ மாற்றவும்." அந்த வாக்கியத்தின் இரண்டாம் பகுதிதான் nested AGENTS.md மூலம் தீர்க்கப்படுகிறது. முதல் பகுதி agent skills-க்கானது. ஒரே செயல்முறை ஒன்றுக்கும் மேற்பட்ட repository-களில் தேவைப்படும்போது, பத்து வெவ்வேறு AGENTS.md கோப்புகளில் அதே பத்திகளை நகலெடுப்பதற்குப் பதிலாக, share the skill across repos என்பதைப் பயன்படுத்தவும்.
"இந்தக் கட்டுரையை எழுதும் நேரத்தில், முதன்மையான OpenAI repo-வில் 88 AGENTS.md கோப்புகள் உள்ளன" என்று Upstream குறிப்பிடுகிறது. அந்த எண்ணிக்கையே இதற்கான முழுமையான வாதமாகும். ஒரு பெரிய repository-க்கு பெரிய கோப்பு தேவையில்லை. அதற்குப் பல சிறிய கோப்புகள் தேவை; ஒவ்வொன்றும் அது விவரிக்கும் code-க்கு அருகிலேயே இருக்க வேண்டும், மேலும் கடைசியாக அந்தக் code-ஐ மாற்றியவர் அதன் உரிமையாளராக இருக்க வேண்டும்.
FAQ
ஒரு nested AGENTS.md கோப்பு, root கோப்பை மாற்றீடு செய்யுமா அல்லது அதனுடன் சேருமா?
அது அதனுடன் சேரும். "அருகில் உள்ள கோப்பிற்கு முன்னுரிமை அளிக்கப்படும்" என்று Upstream கூறுகிறது; இது மோதல் ஏற்படும்போது என்ன நடக்கும் என்பதைக் குறிக்கிறதே தவிர, எவை ஏற்றப்படும் என்பதைக் குறிக்கவில்லை. Codex "root-லிருந்து கீழாக கோப்புகளை ஒன்றிணைத்து, அவற்றுக்கிடையே காலியான வரிகளைச் சேர்க்கிறது". Claude Code, working directory-யிலிருந்து மேலாகச் சென்று கண்டறியும் அனைத்து கோப்புகளையும் ஒன்றிணைக்கிறது, அவற்றை மாற்றீடு செய்வதில்லை. ஒரே விஷயத்தைப் பற்றி இரண்டு கோப்புகள் வெவ்வேறு அறிவுறுத்தல்களைக் கொடுக்கும்போது மட்டுமே அருகில் உள்ள கோப்பு வெற்றிபெறும். பகிரப்பட்ட விதிகளை root-ல் ஒருமுறை எழுதுங்கள், அவற்றை ஒவ்வொரு directory-யிலும் மீண்டும் எழுத வேண்டாம்.
root AGENTS.md எவ்வளவு பெரியதாக இருக்க வேண்டும்?
அந்த repository-ல் நீங்கள் செய்யும் ஒவ்வொரு கோரிக்கையின் மேலேயும் அது ஒட்டப்பட்டால் உங்களுக்கு ஆட்சேபனை இருக்காத அளவிற்குச் சிறியதாக இருக்க வேண்டும், ஏனெனில் அதுதான் நடக்கும். Claude Code ஆவணங்கள், ஒரு கோப்பிற்கு 200 வரிகளுக்குக் குறைவாக வைத்திருக்கப் பரிந்துரைக்கின்றன; நீண்ட கோப்புகள் "அறிவுறுத்தல்களைப் பின்பற்றும் திறனைக் குறைக்கும்" என்று எச்சரிக்கின்றன. Codex இயல்பாகவே 32 KiB அளவிற்கு மேல் அறிவுறுத்தல் கோப்புகளை ஒன்றிணைப்பதை நிறுத்திவிடும். உங்கள் root கோப்பு நான்கு சேவைகளைப் பற்றி விவரித்தால், ஏதேனும் ஒரு குறிப்பிட்ட பணிக்கு அதில் உள்ள பெரும்பாலானவை தேவையற்ற சுமையாக இருக்கும். விவரங்களை அந்தந்த directory-களுக்குக் கீழே நகர்த்திவிட்டு, ஒரு வரைபடத்தை மட்டும் விட்டுச் செல்லுங்கள்.
இந்தக் கோப்புகள் காலாவதியாவதை நான் எப்படித் தடுப்பது?
root கோப்பில் ஒரு விதியைச் சேர்க்கவும்: ஒரு directory-யில் குறியீட்டை (code) மாற்றும் எவரும், அதே commit-ல் அந்த directory-யின் AGENTS.md கோப்பையும் புதுப்பிக்க வேண்டும். கோப்பை குறியீட்டிற்கு அருகிலேயே வைப்பதுதான் அந்த விதியை நிலைக்கச் செய்யும், ஏனெனில் அந்த மாற்றம் மனிதர்கள் ஏற்கனவே வாசிக்கும் pull request diff-ல் இடம்பெறும். மாற்றப்பட்ட ஒவ்வொரு பாதையையும் அதற்கு மேலே உள்ள அருகிலுள்ள AGENTS.md உடன் இணைக்கும் ஒரு CI எச்சரிக்கையைச் சேர்க்கவும். அவ்வப்போது, ஒவ்வொரு கோப்பிலும் git log -1 --format=%cs கட்டளையை இயக்கி, அது ஆவணப்படுத்தும் directory-யில் அதே கட்டளையை இயக்கி ஒப்பிட்டுப் பார்க்கவும்.
Claude Code, AGENTS.md கோப்புகளை வாசிக்குமா?
ஆம், v2.1.277 முதல். 27 October 2026 அன்று ஆவணங்களுடன் சரிபார்க்கப்பட்டதன்படி, உங்கள் working directory-யிலோ அல்லது அதற்கு மேலோ CLAUDE.md அல்லது CLAUDE.local.md இல்லாதபோது, Claude Code இயல்பாகவே AGENTS.md-ஐ வாசிக்கும். மேலும், ஒரு subdirectory-யில் உள்ள கோப்பை Read கருவி மூலம் திறக்கும்போது, அந்த subdirectory-யில் சொந்தமாக CLAUDE.md, .claude/CLAUDE.md அல்லது CLAUDE.local.md இல்லை என்றால், அது அந்த subdirectory-யின் AGENTS.md-ஐ வாசிக்கும். ஒவ்வொரு AGENTS.md-க்கு அருகிலும் CLAUDE.md-ஐச் சேர்க்க வேண்டாம்: working directory-யிலோ அல்லது அதற்கு மேலோ ஒன்று இருந்தால், Claude "உங்கள் CLAUDE.md கோப்புகளை மட்டும்" வாசிக்கும். உங்களுக்கு CLAUDE.md தேவைப்பட்டால், Project instructions என்பதை /config-ல் claude-md-and-agents-md என அமைக்கவும், அல்லது அதன் முதல் வரியில் @AGENTS.md என்பதைச் சேர்க்கவும். ஒரு session-ல் /memory கட்டளையை இயக்கி, AGENTS.md பாதை பட்டியலில் தோன்றுவதை உறுதிப்படுத்தவும்.
எப்போதாவது மட்டும் தேவைப்படும் ஒரு விதியை நான் எங்கே வைப்பது?
AGENTS.md-ல் வைக்கக்கூடாது. அந்தக் கோப்பு ஒவ்வொரு session-லும் ஏற்றப்படும், எனவே அதில் உள்ள ஒவ்வொரு வரியும் நீங்கள் தட்டச்சு செய்யும் கோரிக்கையுடன் கவனத்தைப் பெறப் போட்டியிடும். எப்போதாவது தேவைப்படும் பல படிகளைக் கொண்ட ஒரு செயல்முறை, தேவைப்படும்போது மட்டும் ஏற்றப்படும் ஒரு skill-ல் இருக்க வேண்டும். ஒரு directory-க்கு மட்டும் பொருந்தும் விதி, அந்த directory-யின் AGENTS.md-ல் இருக்க வேண்டும். directory tree அல்லது dependency பட்டியல் போன்ற, குறியீட்டிலிருந்தே முகவர் (agent) நேரடியாக வாசிக்கக்கூடிய உண்மைகளை எதிலும் வைக்க வேண்டியதில்லை.