Monorepo-வில் nested AGENTS.md கோப்புகளை அமைப்பது எப்படி?

Monorepo-வில் nested AGENTS.md என்பதன் பொருள்

Monorepo-வில் nested AGENTS.md என்பது, repository-ன் root-ல் ஒரு சிறிய கோப்பும், ஒவ்வொரு service directory-க்குள்ளும் ஒரு கோப்பும் இருப்பதைக் குறிக்கிறது. Root கோப்பில் அனைத்து இடங்களுக்கும் பொதுவான சில விதிகள் மற்றும் பிற கோப்புகள் எங்கு அமைந்துள்ளன என்பதற்கான வரைபடம் இருக்கும். ஒவ்வொரு service கோப்பிலும் அந்த directory-க்கு மட்டும் உரிய கட்டளைகள் மற்றும் மரபுகள் (conventions) இருக்கும். ஒரு agent services/worker/queue.py-ஐத் திருத்தும்போது, அது root கோப்பையும், அந்த குறிப்பிட்ட worker கோப்பையும் மட்டுமே வாசிக்கும். இதனால், அந்த agent தொடவே போகாத front-end தொடர்பான எந்தத் தகவலும் அதற்குத் தேவையில்லை.

இதை நிறுவ எதுவும் தேவையில்லை. AGENTS.md என்பது ஒரு மரபு மட்டுமே. Upstream project இதைத் தெளிவாகக் குறிப்பிடுகிறது:

AGENTS.md என்பது ஒரு சாதாரண Markdown கோப்பு. நீங்கள் விரும்பும் தலைப்புகளைப் பயன்படுத்தலாம்; நீங்கள் வழங்கும் உரையை அந்த agent அப்படியே பகுப்பாய்வு (parse) செய்துகொள்ளும்.

இதனால்தான் இந்த நுட்பத்தை முறையாகக் கற்றுக்கொள்வது அவசியமாகிறது. இதன் வடிவம் மாறாது. இதில் ஏற்படும் சிக்கல்கள் அனைத்தும் கோப்புகளை வைக்கும் இடம் மற்றும் அவற்றைப் பராமரிப்பதில் மட்டுமே வரும்; இவை இரண்டையும் கவனித்துக்கொள்வது உங்கள் பொறுப்பு.

ஏன் ஒரு பெரிய 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 ஏதேனும் ஒன்றை தன்னிச்சையாகத் தேர்ந்தெடுக்கலாம்." directory-க்கு ஒரு கோப்பு என்ற முறை இந்த யூகத்தை நீக்குகிறது, ஏனெனில் அந்த இரண்டு விதிகளில் ஒன்று மட்டுமே எப்போதும் context-ல் இருக்கும்.

agent-ஆல் code-லிருந்து படிக்கக்கூடிய தகவல்களால் இது நிரம்புகிறது. ஒரு directory tree, dependency பட்டியல், ஒவ்வொரு package-ன் சுருக்கம் போன்றவை. Claude Code-ன் /doctor சரிபார்ப்பு இதற்காகவே உள்ளது. இது "directory அமைப்புகள், dependency பட்டியல்கள் மற்றும் architecture மேலோட்டங்கள் போன்ற, codebase-லிருந்து Claude-ஆல் பெறக்கூடிய உள்ளடக்கங்களை நீக்குகிறது" மற்றும் "கருவி இயல்புநிலைகளிலிருந்து மாறுபட்ட சிக்கல்கள், காரணங்கள் மற்றும் மரபுகளை" மட்டும் வைத்திருக்கிறது. ஒரு வரி இந்தக் கோப்பில் இருக்க வேண்டுமா என்பதைத் தீர்மானிக்க, அந்த வாக்கியமே எனக்குத் தெரிந்த சிறந்த சோதனை ஆகும்.

Agent root கோப்பை மட்டும் படிக்கிறதா அல்லது அருகிலுள்ள கோப்பை மட்டுமா?

பெரும்பாலானோர் இந்த மாதிரியைப் புரிந்துகொள்வதில் தவறு செய்கிறார்கள். எனவே, சொந்தமாக விளக்குவதற்குப் பதிலாக, upstream மரபுகளை அப்படியே மேற்கோள் காட்டுவது சிறந்தது:

ஒவ்வொரு package-க்குள்ளும் மற்றொரு AGENTS.md கோப்பை வைக்கவும். Agents தானாகவே directory tree-ல் அருகிலுள்ள கோப்பைப் படிக்கும். எனவே, மிக அருகில் உள்ள கோப்பு முன்னுரிமை பெறும், மேலும் ஒவ்வொரு subproject-ம் அதற்கேற்ற அறிவுறுத்தல்களை வழங்க முடியும்.

முரண்பாடுகள் குறித்து:

திருத்தப்படும் கோப்பிற்கு மிக அருகில் உள்ள AGENTS.md வெற்றி பெறும்; பயனர் நேரடியாகக் கொடுக்கும் chat prompts அனைத்தையும் விட மேலானவை.

"முன்னுரிமை பெறுகிறது" (Takes precedence) என்பதைப் பலர் "root கோப்பு புறக்கணிக்கப்படுகிறது" என்று தவறாகப் புரிந்துகொள்கிறார்கள். அது உண்மையல்ல. இந்த மரபைச் செயல்படுத்தும் கருவிகளில், repository root-லிருந்து working directory வரை உள்ள பாதையில் உள்ள அனைத்துக் கோப்புகளும் படிக்கப்பட்டு ஒன்றாக இணைக்கப்படுகின்றன. ஒரே விஷயத்தைப் பற்றி இரண்டு கோப்புகள் வெவ்வேறு கருத்துகளைக் கூறும்போது மட்டுமே, அருகிலுள்ள கோப்பு வெற்றி பெறுகிறது.

Codex இந்தச் செயல்பாட்டைத் தெளிவாகக் கூறுகிறது: "Codex root-லிருந்து கீழாகக் கோப்புகளை ஒன்றிணைக்கிறது, அவற்றை வெற்று வரிகளால் பிரிக்கிறது. உங்கள் தற்போதைய directory-க்கு அருகில் உள்ள கோப்புகள் முந்தைய வழிகாட்டுதல்களை மீறிச் செயல்படும்." Claude Code அதன் சொந்தக் கோப்புப் பெயருக்கும் இதே பாதையைப் பின்பற்றுகிறது. working directory-க்கு மேலே உள்ள directory hierarchy-ல் உள்ள கோப்புகள் "தொடக்கத்திலேயே முழுமையாக ஏற்றப்படுகின்றன", மேலும் "கண்டறியப்பட்ட அனைத்துக் கோப்புகளும் ஒன்றையொன்று மீறாமல் context-ல் இணைக்கப்படுகின்றன." working directory-க்கு கீழே உள்ள directories வித்தியாசமாகச் செயல்படுகின்றன: Claude Code அந்தக் கோப்புகளைத் தேவைப்படும்போது மட்டுமே ஏற்றுகிறது, "Claude அந்தக் கோப்புகளைப் படிக்கும்போது" அவை ஏற்றப்படுகின்றன.

இதன் விளைவாக இரண்டு நடைமுறை உண்மைகள் உள்ளன. root கோப்பு என்பது repository-ல் உள்ள ஒவ்வொரு session-க்கும் ஒரு முன்னொட்டாக (prefix) அமைகிறது. எனவே, அங்குள்ள ஒவ்வொரு வரியையும் நீங்கள் வாரத்திற்கு நூறு முறை கட்டணம் செலுத்திப் பயன்படுத்துவதாகக் கருதி கவனமாகக் கையாளவும். ஒரு directory-க்கு உரிய கோப்பு, agent வேறு இடத்தில் வேலை செய்யும்போது எந்தச் செலவையும் ஏற்படுத்தாது. எனவே, விரிவான தகவல்களை அங்கு வைப்பது மலிவானது மற்றும் அதுவே சரியான இடமும் ஆகும்.

இந்தச் செயல்பாடு ஆகஸ்ட் 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 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 கோப்பில் அமையும்: ஒரு கோப்பகத்தில் (directory) குறியீட்டை மாற்றும் எவரும், அதே 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-ஐ மறுசீரமைப்பு செய்த ஒரு 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")"
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

குறியீட்டின் தேதியை விட ஆவணத்தின் தேதி ஆறு மாதங்கள் பின்தங்கியிருப்பது, அந்தக் கோப்பு தவறானது என்று அர்த்தமல்ல. எந்தக் கோப்பை முதலில் படிக்க வேண்டும் என்பதை இது உங்களுக்கு உணர்த்துகிறது; ஒரு நொடியில் செய்யக்கூடிய இந்தச் சோதனைக்கு இதுவே போதுமானது.

இனி இல்லாத பாதைகளைத் (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 உள்ளது, மேலும் இவை வட்டில் உள்ள கோப்புகள் அல்ல.

ஒரு session-ல் ஏற்படும் அறிகுறி. முகவர் (agent) கோப்பைப் படிக்கிறது, கோப்பு சொன்னதால் src/api/client.ts-ஐத் திறக்க முயல்கிறது, அப்போது கருவி (tool) பின்வருவனவற்றைத் திருப்பி அளிக்கிறது:

No such file or directory

எனவே, அது தர்க்கரீதியாகச் செயல்பட்டு, தனக்கென ஒரு fetch wrapper-ஐ உருவாக்குகிறது. இதுவே காலாவதியான கோப்பினால் ஏற்படும் உண்மையான இழப்பு. முகவர் உங்கள் ஆவணங்களைப் புறக்கணிப்பதில்லை. அது ஆவணத்தைப் பின்பற்றி, மூன்று மாதங்களுக்கு முன்பு நீக்கப்பட்ட ஒரு பாதைக்குச் சென்று, உங்களிடம் ஏற்கனவே உள்ள குறியீட்டை மீண்டும் உருவாக்குகிறது. Ponytail, இது ஒரு முகவரைச் செயல்படும் மிகச்சிறிய மாற்றத்திற்குள் கட்டுப்படுத்துகிறது போன்ற ஒரு திறன், இந்த மீண்டும் உருவாக்கும் இயல்பைக் குறைக்கலாம், ஆனால் உங்கள் கோப்பு தவறான இடத்தைச் சுட்டிக்காட்டியிருக்கும் ஒரு உதவியாளரை (helper) அதனால் கண்டறிய முடியாது.

Claude Code, AGENTS.md கோப்புகளை வாசிக்குமா?

இல்லை, இதைத் தெளிவாகக் குறிப்பிடுவது அவசியம், ஏனெனில் நெஸ்டட் (nested) அமைப்பு இதையே சார்ந்துள்ளது. ஆகஸ்ட் 2026 நிலவரப்படி, ஆவணங்கள் இவ்வாறு கூறுகின்றன: "Claude Code CLAUDE.md-ஐ வாசிக்கும், AGENTS.md-ஐ அல்ல." இந்த முறை இன்னும் செயல்படுகிறது, நீங்கள் ஒவ்வொரு AGENTS.md-க்கும் அருகில் ஒரு CLAUDE.md-ஐ வைத்திருக்க வேண்டும்.

பகிரப்பட்ட வரிகளுக்கு மேல் கருவி சார்ந்த (tool-specific) வரிகள் தேவைப்படும்போது, 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. பிறகு ஒரு session-ஐத் தொடங்கி /context-ஐ இயக்கவும், அங்கு ஏற்றப்பட்ட கோப்புகள் Memory files என்பதன் கீழ் தோன்றும். Windows-ல் ஒரு symlink-க்கு Administrator உரிமைகள் அல்லது Developer Mode தேவை, எனவே அங்கு @AGENTS.md import-ஐப் பயன்படுத்தவும்.

இதில் ஒரு சிக்கல் உள்ளது. /compact-க்கு பிறகு, root கோப்பு வட்டில் (disk) இருந்து மீண்டும் வாசிக்கப்படும், ஆனால் சப்-டைரக்டரிகளில் உள்ள நெஸ்டட் கோப்புகள் மீண்டும் உள்ளே செலுத்தப்படாது (re-injected). அந்த டைரக்டரியில் உள்ள ஒரு கோப்பை ஏஜென்ட் அடுத்த முறை வாசிக்கும்போது அவை மீண்டும் வரும். ஒரு நீண்ட session-ன் பாதியில் டைரக்டரி சார்ந்த விதி செயல்படாமல் போனால், பொதுவாக இதுவே காரணமாக இருக்கும்; அந்த டைரக்டரியில் உள்ள ஏதேனும் ஒரு கோப்பைத் தொடுவதன் (touching) மூலம் அதை மீண்டும் கொண்டு வரலாம்.

இது 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-லும் ஏற்றப்படும் context ஆகும்; skill என்பது தேவைப்படும்போது மட்டும் ஏற்றப்படும் ஒரு செயல்முறை (procedure) ஆகும். Claude Code ஆவணங்கள் ஒரு பயனுள்ள விதியை வழங்குகின்றன: "ஒரு பதிவு பல படிகளைக் கொண்ட செயல்முறையாக இருந்தால் அல்லது codebase-ன் ஒரு பகுதிக்கு மட்டும் முக்கியமானது என்றால், அதை ஒரு skill-ஆகவோ அல்லது path-scoped விதியாகவோ மாற்றவும்." அந்த வாக்கியத்தின் இரண்டாம் பகுதி எதைச் சொல்கிறதோ, அதைத்தான் 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-ல் நீங்கள் செய்யும் ஒவ்வொரு request-ன் மேலேயும் அது ஒட்டப்பட்டால் உங்களுக்குப் பாதிப்பு ஏற்படாத அளவுக்குச் சிறியதாக இருக்க வேண்டும், ஏனெனில் அதுதான் நடக்கும். Claude Code ஆவணங்கள், ஒரு கோப்புக்கு 200 வரிகளுக்குக் குறைவாக வைத்திருக்கப் பரிந்துரைக்கின்றன; நீண்ட கோப்புகள் "கவனத்தை ஈர்க்கும் திறனைக் குறைக்கும்" என்று எச்சரிக்கின்றன. Codex, instruction கோப்புகளை ஒன்றிணைக்கும்போது மொத்தம் 32 KiB வரை மட்டுமே எடுத்துக்கொள்ளும். உங்கள் root கோப்பு நான்கு service-களை விவரித்தால், ஏதேனும் ஒரு குறிப்பிட்ட பணிக்கு அதன் பெரும்பகுதி தேவையற்ற சுமையாக இருக்கும். விவரங்களை அந்தந்த directory-க்குரிய கோப்புகளுக்கு மாற்றிவிட்டு, ஒரு வரைபடத்தை மட்டும் விட்டுச் செல்லுங்கள்.

இந்தக் கோப்புகள் காலாவதியாவதை எப்படித் தடுப்பது?

root கோப்பில் ஒரு விதியைச் சேர்க்கவும்: ஒரு directory-யில் குறியீட்டை (code) மாற்றும் எவரும், அதே commit-ல் அந்த directory-யின் AGENTS.md கோப்பையும் புதுப்பிக்க வேண்டும். குறியீட்டிற்கு அருகிலேயே கோப்பை வைப்பதுதான் அந்த விதியை நிலைக்கச் செய்யும், ஏனெனில் அந்த மாற்றம் ஒரு மனிதர் ஏற்கனவே வாசித்துக்கொண்டிருக்கும் pull request diff-ல் இடம்பெறும். மாற்றப்பட்ட ஒவ்வொரு path-க்கும் மேலே உள்ள மிக அருகிலுள்ள AGENTS.md கோப்பைச் சுட்டிக்காட்டும் CI எச்சரிக்கையைச் சேர்க்கவும். அவ்வப்போது, ஒவ்வொரு கோப்பிலும் git log -1 --format=%cs கட்டளையை இயக்கி, அது விவரிக்கும் directory-யில் அதே கட்டளையை இயக்கி ஒப்பிட்டுப் பார்க்கவும்.

Claude Code, AGENTS.md கோப்புகளை வாசிக்குமா?

இல்லை. ஆகஸ்ட் 2026 நிலவரப்படி, ஆவணங்கள் "Claude Code CLAUDE.md கோப்பை வாசிக்கும், AGENTS.md கோப்பை அல்ல" என்று குறிப்பிடுகின்றன. அதே directory-யில் ஒரு CLAUDE.md கோப்பை உருவாக்கி, அதன் முதல் வரியில் @AGENTS.md என்று குறிப்பிடவும். இது பகிரப்பட்ட கோப்பை ஏற்றி, அதற்குக்கீழே Claude-க்குரிய குறிப்பிட்ட அறிவுறுத்தல்களைச் சேர்க்க உங்களை அனுமதிக்கும். கூடுதல் அறிவுறுத்தல்கள் ஏதுமில்லாதபோது ln -s AGENTS.md CLAUDE.md மூலம் உருவாக்கப்பட்ட symlink வேலை செய்யும், இருப்பினும் Windows-ல் இதற்கு Administrator உரிமைகள் அல்லது Developer Mode தேவைப்படும். ஒரு session-ல் /context கட்டளையை இயக்கி, Memory files-ன் கீழ் கோப்பு தோன்றுகிறதா என்பதை உறுதிப்படுத்தவும்.

எப்போதாவது மட்டும் தேவைப்படும் விதியை எங்கே வைப்பது?

AGENTS.md கோப்பில் வைக்கக்கூடாது. அந்த கோப்பு ஒவ்வொரு session-லும் ஏற்றப்படும், எனவே அதில் உள்ள ஒவ்வொரு வரியும் நீங்கள் தட்டச்சு செய்யும் request-உடன் கவனத்திற்காகப் போட்டியிடும். எப்போதாவது தேவைப்படும் பல படிகளைக் கொண்ட ஒரு செயல்முறை, தேவைப்படும்போது மட்டும் ஏற்றப்படும் ஒரு skill-ல் இருக்க வேண்டும். ஒரு directory-க்கு மட்டும் பொருந்தும் விதி, அந்த directory-யின் AGENTS.md கோப்பில் இருக்க வேண்டும். directory tree அல்லது dependency பட்டியல் போன்ற, குறியீட்டிலிருந்தே நேரடியாக வாசிக்கக்கூடிய தகவல்களை எதிலும் வைக்க வேண்டியதில்லை.