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

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

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

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

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

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

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

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

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

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

இதன் விளைவாக இரண்டு நடைமுறை உண்மைகள் உள்ளன. 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

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

# 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 காலாவதியாகிவிட்டதை எப்படிக் கண்டறிவது?

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

ஒவ்வொரு கோப்பின் வயதையும், அது விவரிக்கும் குறியீட்டின் (code) வயதையும் ஒப்பிட்டுப் பாருங்கள். %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

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

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

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

No such file or directory

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

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

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

பகிரப்பட்ட வரிகளுக்கு மேல் tool-க்குரிய வரிகளைச் சேர்க்க விரும்பும்போது, import முறை சரியானது. இதை services/worker/CLAUDE.md-ல் சேர்க்கவும்:

@AGENTS.md

## Claude Code

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

tool-க்குரிய கூடுதல் வரிகள் ஏதுமில்லாதபோது, 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 கோப்பு வட்டில் இருந்து மீண்டும் வாசிக்கப்படும், ஆனால் subdirectory-களில் உள்ள nested கோப்புகள் மீண்டும் உள்ளே செலுத்தப்படாது. அந்த directory-ல் உள்ள ஒரு கோப்பை agent மீண்டும் வாசிக்கும்போது அவை திரும்ப வரும். ஒரு directory-க்கான விதி நீண்ட session-ன் பாதியில் செயல்படாமல் போவது போல் தோன்றினால், பொதுவாக இதுவே காரணமாக இருக்கும்; அந்த directory-ல் ஏதேனும் ஒரு கோப்பைத் தொடுவதன் (touch) மூலம் அதை மீண்டும் கொண்டு வரலாம்.

இது 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 கோப்புகளை வாசிக்குமா?

இல்லை. ஆகஸ்ட் 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-லும் ஏற்றப்படும், எனவே அதில் உள்ள ஒவ்வொரு வரியும் நீங்கள் தட்டச்சு செய்த கோரிக்கையுடன் கவனத்திற்காகப் போட்டியிடும். எப்போதாவது தேவைப்படும் பல படிகளைக் கொண்ட ஒரு செயல்முறை, தேவைப்படும்போது மட்டும் ஏற்றப்படும் ஒரு skill-க்கு உரியது. ஒரு directory-க்கு மட்டும் பொருந்தும் விதி, அந்த directory-யின் AGENTS.md கோப்பிற்கு உரியது. directory tree அல்லது dependency list போன்ற, குறியீட்டிலிருந்தே நேரடியாக வாசிக்கக்கூடிய உண்மைகளை எதிலும் வைக்க வேண்டியதில்லை.