AGENTS.md கோப்பை தானாகவே புதுப்பிப்பது எப்படி?

மூன்று வாரங்களுக்குப் பிறகு உங்கள் AGENTS.md ஏன் தவறாகிறது

AGENTS.md கோப்பு காலாவதியாகிறது, ஏனெனில் அதற்கும் குறியீட்டிற்கும் (code) இடையே எந்தத் தொடர்பும் இல்லை. களஞ்சியம் (repository) ஒரு குறிப்பிட்ட நிலையில் இருந்த நாளில், நீங்கள் அதை ஒருமுறை கையால் எழுதுகிறீர்கள். பின்னர் test runner மாறுகிறது, ஒரு package பெயர் மாற்றப்படுகிறது, ஒரு service நீக்கப்படுகிறது, ஆனால் அந்த கோப்பு இன்னும் ஜூன் மாத நிலையையே விவரிக்கிறது. எந்த build படியும் அதை வாசிப்பதில்லை என்பதால், எதுவும் தோல்வியடைவதில்லை.

Agent அதை வாசித்து உண்மையாக நம்புகிறது. இதுவே உங்களுக்கு இழப்பை ஏற்படுத்தும் பகுதி. AGENTS.md இல்லாத ஒரு களஞ்சியத்தில், ஒரு coding agent செயல்படுவதற்கு முன்பு சூழலைச் சுற்றிப் பார்க்கும். தவறான AGENTS.md உள்ள களஞ்சியத்தில், ஏற்கனவே விடை இருப்பதாகக் கருதி அது தேடுவதை நிறுத்திவிடும். உங்கள் கோப்பில் உள்ள கட்டளையை அது இயக்கும், shell Missing script: "test" என்று பதிலளிக்கும், இப்போது agent யூகிக்கத் தொடங்கும். பெரும்பாலும், உங்கள் ஆவணத்தில் வாக்குறுதி அளிக்கப்பட்ட script-ஐச் சேர்க்க அது package.json-ஐத் திருத்தும். காலாவதியான கோப்பு அமைதியாகத் தோல்வியடையவில்லை. அது நீங்கள் விரும்பாத ஒரு மாற்றத்தைச் செய்துவிட்டது.

இதற்கு dox ஒரு தீர்வாகும். இது agent-க்காக எழுதப்பட்ட விதிகளின் தொகுப்பாகும். இது ஆவணத்தைப் புதுப்பிப்பதை வேலையை முடிப்பதன் ஒரு பகுதியாக மாற்றுகிறது. இதனால், குறியீட்டை மாற்றிய அதே commit-ல் ஆவணக் கோப்பும் மாற்றப்படுகிறது.

dox என்றால் என்ன, அது எதைக் குறிக்காது

dox என்பது ஒரு ஒற்றை Markdown கோப்பு ஆகும். இதன் களஞ்சியம் (repository) agent0ai/dox ஆகும், இது MIT உரிமம் பெற்றது, மேலும் 11 August 2026 நிலவரப்படி, முழு திட்டமும் ஒரு 3906-byte AGENTS.md, ஒரு README, ஒரு LICENSE மற்றும் இரண்டு படங்களைக் கொண்டுள்ளது. இதில் நிறுவ வேண்டிய தொகுப்போ அல்லது இயக்க நேரமோ (runtime) இல்லை.

இது முக்கியமானது, ஏனெனில் 'generator' என்ற சொல் உங்கள் குறியீட்டைப் பகுப்பாய்வு செய்யும் ஒரு நிரலை உணர்த்துகிறது. எதுவும் உங்கள் குறியீட்டைப் பகுப்பாய்வு செய்வதில்லை. dox என்பது உங்கள் coding agent படிக்கும் ஒரு ஒப்பந்தம்: உங்கள் agent தான் generator, மேலும் dox என்பது ஆவணங்களை எப்போது படிக்க வேண்டும், எப்போது அவற்றை மீண்டும் எழுத வேண்டும், மற்றும் ஒவ்வொரு ஆவணமும் என்ன வடிவில் இருக்க வேண்டும் என்று அதற்கு அறிவுறுத்தும் தொகுப்பாகும்.

இந்தக் கோப்பில் பத்து பிரிவுகள் உள்ளன, அவற்றில் இரண்டு பிரிவுகள் முக்கியப் பணிகளைச் செய்கின்றன. "Read Before Editing" என்பது, களஞ்சியத்தின் root-லிருந்து அது மாற்றங்களைச் செய்யத் திட்டமிடும் ஒவ்வொரு பாதைக்கும் (path) சென்று, அந்தப் பாதையில் உள்ள ஒவ்வொரு AGENTS.md கோப்பையும் தற்போதைய அமர்வில், நினைவகத்தை மட்டும் நம்பியிருக்காமல் படிக்க வேண்டும் என்று agent-க்குக் கட்டளையிடுகிறது. "Update After Editing" என்பது, ஒவ்வொரு அர்த்தமுள்ள மாற்றத்திற்கும் ஒரு DOX pass தேவை என்பதை அதற்கு உணர்த்துகிறது; அதாவது, ஒரு பணி முடிவடைந்ததாகக் கருதப்படுவதற்கு முன்பே ஆவணத்தைப் புதுப்பிக்கும் படிநிலை மேற்கொள்ளப்பட வேண்டும். நோக்கம், அமைப்பு, பணிப்பாய்வு, அனுமதிகள் அல்லது பயனர் விருப்பத்தேர்வுகள் மாறும்போது, அந்த மாற்றத்திற்குரிய மிக நெருக்கமான ஆவணத்தை இந்தப் pass புதுப்பிக்கிறது.

மீதமுள்ளவை வடிவமைப்பு சார்ந்தவை. ஒரு child AGENTS.md கோப்பு இயல்புநிலை வரிசையைக் கொண்டுள்ளது: நோக்கம் (Purpose), உரிமை (Ownership), உள்ளூர் ஒப்பந்தங்கள் (Local Contracts), பணி வழிகாட்டுதல் (Work Guidance), சரிபார்ப்பு (Verification), மற்றும் Child DOX Index. root கோப்பு திட்டத்தின் ஒட்டுமொத்த விதிகள் மற்றும் உயர்மட்ட Child DOX Index-ஐக் கொண்டுள்ளது; இதன் மூலமே ஒரு agent குழந்தை ஆவணங்களைக் கண்டறிகிறது. "Closeout" என்பது ஒரு பணியின் முடிவில் agent மேற்கொள்ளும் சரிபார்ப்புப் பட்டியல் (checklist) ஆகும்: மாற்றப்பட்ட பாதைகளைச் சங்கிலித் தொடருடன் மீண்டும் சரிபார்த்தல், அருகிலுள்ள ஆவணங்களைப் புதுப்பித்தல், பாதிக்கப்பட்ட ஒவ்வொரு குறியீட்டையும் (index) புதுப்பித்தல், முரண்பாடுகளை நீக்குதல், ஏற்கனவே உள்ள சரிபார்ப்புகளை இயக்குதல், மற்றும் அது வேண்டுமென்றே மாற்றாமல் விட்ட ஆவணங்கள் எவை என்பதை அறிக்கையிடுதல் ஆகியவை இதில் அடங்கும்.

AGENTS.md கோப்பை main branch-க்கு பதிலாக ஒரு குறிப்பிட்ட commit-க்கு Pin செய்யவும்

இந்த repository-ல் tags அல்லது releases எதுவும் இல்லை, எனவே pin செய்வதற்கு பதிப்பு எண் (version number) இல்லை. அதற்கு பதிலாக commit-ஐ pin செய்யவும். தற்போதைய AGENTS.md கோப்பு f34ec7ad1055d3393887e5a2670e8cb7320c9165 என்ற commit-ஐச் சார்ந்தது, இதன் தேதி 1 ஆகஸ்ட் 2026.

mkdir -p .agent
curl -fsSL -o .agent/dox-f34ec7a.md \
  https://raw.githubusercontent.com/agent0ai/dox/f34ec7ad1055d3393887e5a2670e8cb7320c9165/AGENTS.md
wc -c .agent/dox-f34ec7a.md

wc -c கட்டளை 3906 என்பதை அச்சிட வேண்டும். வேறு எண் வந்தால், இந்த வழிகாட்டி குறிப்பிடும் கோப்பை நீங்கள் பெறவில்லை என்று அர்த்தம்; எனவே அதை நம்புவதற்கு முன் மீண்டும் படிக்கவும். நீங்கள் commit hash-ஐத் தவறாகத் தட்டச்சு செய்தால், -f கட்டளையானது curl: (22) The requested URL returned error: 404 பிழையுடன் curl-ஐ நிறுத்திவிடும் மற்றும் எந்த உள்ளடக்கத்தையும் எழுதாது, அதன் பிறகு wc -c கட்டளை 0 என்பதை அச்சிடும். ஒரு முழுமையற்ற கோப்பு (truncated file), கோப்பே இல்லாததை விட மோசமானது, ஏனெனில் முகவர் (agent) ஒரு ஒப்பந்தத்தின் பாதியை மட்டும் படித்துவிட்டு, மீதியை அறியாமல் செயல்படும்.

cp .agent/dox-f34ec7a.md AGENTS.md
git add AGENTS.md .agent/dox-f34ec7a.md
git commit -m "Add DOX rules (agent0ai/dox @ f34ec7a)"

அந்த cp கட்டளை AGENTS.md இல்லாத ஒரு repository-க்காக உருவாக்கப்பட்டது. உங்களிடம் ஏற்கனவே ஒரு கோப்பு இருந்தால், அதை மேலெழுத (overwrite) வேண்டாம். உங்கள் தற்போதைய உள்ளடக்கத்திற்கு மேலே இந்த dox பகுதிகளைச் சேர்க்கவும், உங்கள் சொந்த விதிகளை அதன் கீழே வைத்திருக்கவும், பின்னர் முடிவை மேலிருந்து கீழ் வரை ஒருமுறை படிக்கவும். ஒன்றுக்கொன்று முரணான இரண்டு ஆவணங்கள் இருந்தால், முகவர் கடைசியாகப் படித்த வரியையே பின்பற்றும்.

பிறகு, repository-க்குள் இருக்கும் உங்கள் முகவரிடம் முதல் கட்டச் செயல்பாட்டிற்காகக் கேட்கவும். README-ல் அதற்கான சரியான வாசகம் கொடுக்கப்பட்டுள்ளது:

Initialize DOX tree for this project now.

இது child AGENTS.md கோப்புகளையும், அவற்றைச் சுட்டிக்காட்டும் indexes-களையும் உருவாக்கும். அது செய்த மாற்றங்களை நம்புவதற்கு முன் சரிபார்க்கவும்:

git status --short
find . -name AGENTS.md -not -path './.git/*' | sort

find வெளியீட்டில் உள்ள ஒவ்வொரு கோப்பும், அதற்கு மேலே உள்ள ஏதேனும் ஒரு Child DOX Index-ல் இடம்பெற வேண்டும். எந்த index-லும் குறிப்பிடப்படாத ஒரு child ஆவணத்தை முகவர் கவனிக்கத் தவறிவிடலாம், ஏனெனில் முகவர் தான் செல்லும் பாதையில் நேரடியாக இல்லாத ஆவணங்களைக் கண்டறிய index-ஐயே பயன்படுத்துகிறது.

dox எவற்றைப் பார்க்க முடியும், எவற்றை அறிய முடியாது

உங்கள் tree-ஐ உருவாக்கும் agent, repository-ஐ வாசிக்கும். எனவே, repository-ல் உள்ள எதையும் inventory-ல் சேர்க்க முடியும்: directory அமைப்பு, package manifests மற்றும் lockfiles, package.json அல்லது Makefile அல்லது pyproject.toml-ல் உள்ள scripts, CI workflow கோப்புகள், Dockerfiles, entry points மற்றும் உங்களிடம் இருந்தால் CODEOWNERS. இவற்றிலிருந்து உருவாக்கப்பட்ட inventory தானாகவே பராமரிக்கப்படும். ஒரு package இடம் மாறும்போது, அடுத்த pass-ல் அதைக் குறிக்கும் வரியும் தானாகவே நகரும்.

கீழே உள்ளவற்றை நீங்கள் தான் குறிப்பிட வேண்டும், ஏனெனில் அவை வாசிப்பதற்கு repository-ல் இருக்காது:

• ஒரு விதி ஏன் உள்ளது என்பது; இதுதான் தேவையற்ற சிக்கல் என்று கருதி agent அதை நீக்குவதைத் தடுக்கும்.
• செயல்பாட்டில் உள்ள இரண்டு பாதைகளில் எது ஆதரிக்கப்படுகிறது, எது நீக்கப்பட வேண்டியது என்பது.
• staging environment அல்லது ஒரு dependency ஏன் இரண்டு பதிப்புகளுக்கு முன்னதாகவே முடக்கப்பட்டுள்ளது (pinned) என்பதற்கான காரணம் போன்ற, repository-க்கு வெளியே உள்ள தகவல்கள்.
• அடுத்த வாரம் நீங்கள் என்ன செய்யத் திட்டமிட்டுள்ளீர்கள் என்பது; இதுதான் தற்போதைய கோப்பிற்கும், பயனுள்ள கோப்பிற்கும் உள்ள வித்தியாசம்.

dox இதைப் பற்றி அறிந்திருக்கிறது. அதன் சொந்த விதிகளின்படி, Work Guidance என்பது திட்டத்தின் தற்போதைய தரநிலைகளையோ அல்லது பயனரின் அறிவுறுத்தல்களையோ பிரதிபலிக்க வேண்டும். இதுவரை எதுவும் இல்லை என்றால், அந்தப் பகுதியை காலியாக விட வேண்டும். சரிபார்ப்பு (Verification) என்பது ஏற்கனவே உள்ள ஒரு சோதனையைப் பிரதிபலிக்க வேண்டும். எனவே, repository-ல் test framework எதுவும் இல்லை என்றால், அது உருவாகும் வரை அந்தப் பகுதி காலியாகவே இருக்கும். ஒரு தரநிலையைத் தானாகவே உருவாக்கும் ஒரு கோப்பு, காலியான பகுதியை விட மோசமானது; ஏனெனில் agent அந்தப் போலியான தரநிலையை அமல்படுத்தத் தொடங்கிவிடும்.

உருவாக்கப்பட்ட ஆவணப்பட்டியலில் இருந்து கையால் எழுதப்பட்ட நோக்கத்தை நீக்குதல்

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

இதற்கு இரண்டு வழிமுறைகள் உள்ளன, இவை இரண்டையும் நீங்கள் பயன்படுத்த வேண்டும்.

முதலாவதாக, நீடித்திருக்கும் நோக்கத்தை (durable intent) வேறொரு கோப்பிற்கு மாற்றவும். வடிவமைப்பு முடிவுகள் மற்றும் அதற்கான காரணங்கள் agent-க்காக எழுதப்பட்ட DESIGN.md-ல் இருக்க வேண்டும். மனிதர்களுக்கான குறிப்புகள் HUMAN.md-ஐ AGENTS.md-லிருந்து பிரிக்கும் இடத்தில் இருக்க வேண்டும். AGENTS.md கோப்பு, ஆவணப்பட்டியல் மற்றும் உள்ளூர் ஒப்பந்தங்களை (local contracts) வைத்திருக்க வேண்டும்; குறியீடு மாறும்போது இவைதான் மாற வேண்டியவை.

இரண்டாவதாக, AGENTS.md-க்குள் இருக்க வேண்டிய நோக்கத்தை வேலியிட்டுப் பாதுகாக்கவும். அதை markers-க்குள் வைத்து, அந்தப் பகுதியை மனிதர்கள் நிர்வகிக்கும் பகுதியாகக் கருதவும்:

## User Preferences

<!-- dox:keep start -->
The jobs queue stays single consumer. Ordering is the reason this service exists.
Deploys ship on Tuesday. A Friday deploy is a human decision, not an agent decision.
<!-- dox:keep end -->

Markdown comments பக்கத்தில் தெரியாது, ஆனால் agent அவற்றை வாசிக்கும். இப்போது அந்தத் தொகுதி நீக்கப்படாமல் இருப்பதைச் சரிபார்க்கவும்; அதை அழிக்கும் செயல்முறை தோல்வியடைய வேண்டும். ஒவ்வொரு pull request-லும் CI (continuous integration)-ல் இதை இயக்கவும்:

git fetch -q origin main
sed -n '/dox:keep start/,/dox:keep end/p' AGENTS.md > /tmp/keep.head
git show origin/main:AGENTS.md | sed -n '/dox:keep start/,/dox:keep end/p' > /tmp/keep.base
diff -u /tmp/keep.base /tmp/keep.head

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

டைமரை அடிப்படையாகக் கொள்ளாமல், pull request-ல் புதுப்பிக்கவும்

ஒரு ஆவணத்தைப் புதுப்பிப்பதற்குச் சரியான தருணம், அது தவறாகும் மாற்றத்தைச் செய்யும் commit-ல் தான் உள்ளது. DOX செயல்பாட்டை அதே pull request-ல் சேர்த்தால், diff சிறியதாக இருக்கும், அதை எளிதாக வாசிக்க முடியும்.

இதை உறுதிப்படுத்தும் ஒரு blocking check இதோ:

#!/usr/bin/env bash
set -euo pipefail
git fetch -q origin main
base=$(git merge-base origin/main HEAD)
changed=$(git diff --name-only "$base" HEAD)
if grep -qE '^(src|apps|packages)/' <<<"$changed" && ! grep -q 'AGENTS\.md$' <<<"$changed"; then
  echo "Code changed but no AGENTS.md was touched. Run a DOX pass, or say why not."
  exit 1
fi

உங்கள் repository-க்கு ஏற்ப பாதைகளை (paths) மாற்றிக்கொள்ளவும். இதன் பயன் என்னவென்றால், இது branch-ல் இருக்கும்போதே தோல்வியடையும், அங்கு பிழையைத் திருத்துவது எளிது; மேலும், ஒரு reviewer நடவடிக்கை எடுக்கக்கூடிய காரணத்தோடு இது தோல்வியடையும்.

ஒரு கால அட்டவணை (schedule) என்பது ஒரு காப்பு ஏற்பாடு மட்டுமே, அது முதன்மைச் செயல்பாட்டு முறை அல்ல. ஒரு வாராந்திர வேலை (weekly job), branch-ல் யாரும் கவனிக்காதவற்றைச் சரிபார்க்கும்: rebase-ஆல் நகர்த்தப்பட்ட கோப்புகள், merge-ல் நீக்கப்பட்ட package, அல்லது இப்போது இல்லாத ஒரு directory-ஐக் குறிப்பிடும் ஆவணம் போன்றவை. இதை ஒரு சிறிய server-ல் இயக்கவும், நீங்கள் run a coding agent on a VPS-க்கு பயன்படுத்தும் அதே server-ல் இயக்கி, main branch-க்கு நேரடியாகப் பதிவேற்றுவதற்குப் பதிலாக, ஒரு pull request-ஐ உருவாக்கவும்.

#!/usr/bin/env bash
set -euo pipefail
cd /srv/src/myapp
git fetch -q origin
git switch -c "dox/refresh-$(date +%Y%m%d)" origin/main
# Your agent CLI goes on the next line, in whatever non-interactive mode it offers.
# Prompt: "Run a DOX pass over this repository. Change AGENTS.md files only."
git add '*AGENTS.md'
git commit -m "dox: refresh AGENTS.md tree" || { echo "nothing to refresh"; exit 0; }
git push -q -u origin HEAD
gh pr create --fill

அந்தக் கருத்து (comment) வேண்டுமென்றே ஒரு placeholder-ஆக வைக்கப்பட்டுள்ளது. ஒவ்வொரு agent-க்கும் தனித்தனி CLI (command line interface) மற்றும் non-interactive flag இருக்கும். இணையதளத்திலிருந்து நகலெடுக்கப்பட்ட ஒரு கட்டளை உங்கள் பதிப்போடு (version) பொருந்தவில்லை என்றால், cron-ல் அது தோல்வியடையும், அதை யாரும் கவனிக்க மாட்டார்கள். அதைச் சரியாக நிரப்பி, கால அட்டவணையில் சேர்ப்பதற்கு முன் ஒருமுறை கைமுறையாக இயக்கிப் பார்க்கவும். || exit 0 என்பதும் முக்கியமானது: git commit என்பது ஏற்கனவே கோப்புகள் சரியாக இருக்கும்போது nothing to commit, working tree clean என்ற non-zero exit code-ஐத் தரும், set -e-ன் கீழ் இது சரியாக இயங்கும் ஒரு வேலையைத் தோல்வியாகக் காட்டும்.

ஒவ்வொரு செயல்பாடும் tokens-ஐச் செலவழிக்கும், ஏனெனில் "Read Before Editing" என்பது ஒவ்வொரு பணியின் போதும் agent முழுச் சங்கிலியையும் வாசிக்கச் செய்யும். இது ஒரு சமரசம், நீங்கள் ஏற்கனவே counting what your agent runs cost என்பதைச் செய்து கொண்டிருந்தால், இதைக் கவனிப்பது அவசியம்.

Monorepos: பல ஒப்பந்தங்கள், ஒரு குறியீடு

நாற்பது தொகுப்புகளைக் கொண்ட ஒரு களஞ்சியத்தில் (repository) ஒரே ஒரு root AGENTS.md கோப்பு இருந்தால், அது யாரும் வாசிக்காத ஒரு பெரிய regeneration diff-ஐ உருவாக்குகிறது. மேலும், அந்த ஆவணம் தற்போது அந்த agent செய்யும் பணிக்குத் தொடர்பில்லாத தகவல்களையே அதிகம் கொண்டிருக்கும். இதற்கான தீர்வு Child DOX Index ஆகும்: root கோப்பு களஞ்சியம் முழுமைக்குமான விதிகளைக் கொண்டிருக்கும் மற்றும் அதன் கீழ் உள்ள கோப்புகளைச் சுட்டிக்காட்டும்; ஒவ்வொரு நிலையான எல்லையும் (durable boundary) தனக்கென ஒரு கோப்பைக் கொண்டிருக்கும். இந்த மர அமைப்பை எப்படி உருவாக்குவது மற்றும் எந்தெந்த கருவிகள் nested கோப்புகளை வாசிக்கும் என்பது nested AGENTS.md files for monorepos பகுதியில் விளக்கப்பட்டுள்ளது.

dox மாற்றும் விஷயம் என்னவென்றால், அது ஆய்வு செய்யப்படும் பரப்பளவு (review surface) ஆகும். packages/api-ஐ மாற்றும் ஒரு pull request, packages/api-க்குள் மட்டுமே ஆவண மாற்றத்தை (documentation diff) உருவாக்க வேண்டும், வேறு எங்கும் அல்ல:

git diff --stat -- '*AGENTS.md'

அந்தக் கட்டளை ஒரு தொகுப்பு மாற்றத்திற்கு ஆறு கோப்புகளைப் பட்டியலிட்டால், அந்த மரம் தவறாக உள்ளது என்று அர்த்தம். ஒன்று, எல்லைகள் மிக விரிவாக உள்ளன, அல்லது root-ல் இருக்க வேண்டிய ஒரு விதி ஒவ்வொரு child கோப்பிலும் நகலெடுக்கப்பட்டுள்ளது. இதற்கான தீர்வை dox நேரடியாகக் கூறுகிறது: பொதுவான விதிகள் parent ஆவணங்களிலும், குறிப்பிட்ட விவரங்கள் child ஆவணங்களிலும் இருக்க வேண்டும். விதிகள் நகலெடுக்கப்படுவதால்தான் ஒரு சாதாரண மாற்றத்திற்குக்கூட அனைத்தையும் மீண்டும் எழுத வேண்டியுள்ளது. ஒரே விதிகள் வெவ்வேறு களஞ்சியங்களில் உண்மையாகவே பொருந்தினால், அது வேறு ஒரு சிக்கல்; அதற்கு sharing agent skills across repositories சிறந்த கருவியாகும்.

Code diff-ஐ ஆய்வு செய்தல்

உருவாக்கப்பட்ட ஆவணங்களின் diff-ஐ வாசிக்காமல் அங்கீகரிப்பது எளிது, இதுவே தவறான கோப்பு வெளியாவதற்குக் காரணமாகிறது. உருவாக்கப்பட்ட code-ஐ எவ்வாறு அணுகுவீர்களோ, அதே சந்தேகத்துடன் இதையும் வாசிக்கவும். பின்வரும் நான்கு விஷயங்களைக் கவனிக்கவும்:

• கோப்பில் குறிப்பிடப்பட்டுள்ள ஒரு command-ஐ, merge செய்வதற்கு முன்பு நீங்களே இயக்கிப் பார்க்கவும். தவறான build வழிமுறைகளே பெரும்பாலும் தோல்விக்குக் காரணமாகின்றன.
• நீக்கப்பட்ட வரியில் ஏதேனும் முக்கிய நோக்கம் இருந்ததா என்று பார்க்கவும். புதிய வரிகளைச் சேர்ப்பது எளிது, ஆனால் நீக்கப்படும் வரிகளிலேயே தரவு இழப்பு ஏற்படுகிறது.
• absolute path, hostname, internal URL அல்லது credential போன்ற அமைப்பில் உள்ள ஏதேனும் தகவல்கள் உள்ளனவா என்று பார்க்கவும்.
• தற்போது பயன்பாட்டில் இல்லாத ஒன்றிற்கான inventory entry உள்ளதா என்று பார்க்கவும், இதை ls நொடியில் சரிசெய்துவிடும்.

பிறகு wc -l AGENTS.md மூலம் கோப்பின் அளவைச் சரிபார்க்கவும். ஒரு root கோப்பு 200 வரிகளுக்கு மேல் இருந்தால், அதை இரண்டாகப் பிரிப்பது நல்லது. முழு ஆவணத்தையும் வாசிப்பதற்குப் பதிலாக, தேவையான சிறிய பகுதியை மட்டும் agent வாசிப்பதே இந்தச் சங்கிலித் தொடரின் முக்கியப் பயன்.

செயல்பாடு முறியும்போது

Pass உங்கள் intent block-ஐ நீக்கிவிட்டது. மேலே உள்ள diff சரிபார்ப்பு, நீக்கப்பட்ட வரிகளை அச்சிடும். git restore --source=origin/main AGENTS.md-ஐப் பயன்படுத்தி branch point-லிருந்து கோப்பை மீட்டெடுக்கவும். பின்னர், எந்தெந்த பகுதிகளை மாற்றலாம் என்று குறிப்பிட்டு, குறுகிய அறிவுறுத்தலுடன் pass-ஐ மீண்டும் இயக்கவும்.

இரண்டு கிளைகளும் (branches) மீண்டும் உருவாக்கப்பட்டன. கோப்பிற்குள் CONFLICT (content): Merge conflict in AGENTS.md மற்றும் conflict markers <<<<<<< HEAD ஆகியவற்றை நீங்கள் காண்பீர்கள். அந்த markers-ஐ நீங்களே திருத்த வேண்டாம். இது தானாக உருவாக்கப்பட்ட கோப்பு என்பதால், merged tree-ன் மீது புதிய pass-ஐ இயக்குவதே சரியான தீர்வாகும்.

Agent கோப்பை முற்றிலும் புறக்கணிக்கிறது. உங்கள் கருவி உண்மையில் எந்தக் கோப்புப் பெயரைப் படிக்கிறது என்பதைச் சரிபார்க்கவும். அது வேறொரு கோப்பைப் படிக்கிறது என்றால், ln -s AGENTS.md CLAUDE.md மூலம் அதை அதே உள்ளடக்கத்திற்குச் சுட்டிக்காட்டவும். இரண்டு ஆவணங்களும் வெவ்வேறாக மாறுவதைத் தவிர்க்க, அந்த symlink-ஐ commit செய்யவும்.

Tree-ல் யாரும் குறியீட்டு எண் (index) வழங்காத child-கள் உருவாகியுள்ளன. find . -name AGENTS.md வெளியீட்டை, தாய் ஆவணங்களில் உள்ள index பதிவுகளுடன் ஒப்பிடவும். எந்த index-லும் குறிப்பிடப்படாத ஒரு child-ஐ, agent கவனிக்காமல் கடந்து செல்லும்.

எப்போது generator தேவையற்றது

ஒரு package, ஒரு test command, repository-ஐ நன்கு அறிந்த இருவர் எனில், இருபது வரிகளை நீங்களே கைப்பட எழுதுங்கள். இருபது வரிகள் கொண்ட AGENTS.md கோப்பு, ஒரு tree, index, CI check மற்றும் வாராந்திர job ஆகியவற்றை நியாயப்படுத்தும் அளவுக்கு விரைவாகப் பழுதடைவதில்லை. build-ஐ மாற்றும்போது அதை மீண்டும் படியுங்கள். இதுவே அதன் முழு பராமரிப்புச் செலவு; இது அதைச் சுற்றியுள்ள கட்டமைப்பின் செலவை விடக் குறைவானது.

repository-ல் ஒருவரால் மட்டும் நினைவில் கொள்ள முடியாத எல்லைகள் இருக்கும்போது dox-க்கு செலவு செய்வது பயனுள்ளது: வெவ்வேறு விதிகளைக் கொண்ட பல packages அல்லது பின்னணி அறிவு இல்லாத பங்களிப்பாளர்கள் இருக்கும்போது இது தேவை. இதன் மதிப்பு உருவாக்கப்பட்ட உரையில் இல்லை. மாறாக, documentation என்பது ஒரு pull request-ஐத் தோல்வியடையச் செய்யும் ஒரு காரணியாக மாறுவதில்தான் உள்ளது; repository-ல் உள்ள எந்தவொரு கோப்பும் தற்போதைய நிலையில் இருப்பதற்கு இதுவே ஒரே காரணம்.

FAQ

dox-ஐப் பயன்படுத்த நான் எதையாவது install செய்ய வேண்டுமா?

இல்லை. dox என்பது ஒரே ஒரு Markdown கோப்பு மட்டுமே. இது MIT உரிமம் பெற்றது. 11 August 2026 நிலவரப்படி, இந்த repository எந்த package-ஐயும் அல்லது releases-ஐயும் கொண்டிருக்கவில்லை. நீங்கள் அதன் உள்ளடக்கத்தை உங்கள் project-ன் AGENTS.md கோப்பில் நகலெடுத்துக்கொள்ள வேண்டும். உங்கள் coding agent அங்கிருந்து விதிகளைப் பின்பற்றும். நீங்கள் நகலெடுத்த commit-ஐ, எழுதும் நேரத்தில் f34ec7ad1055d3393887e5a2670e8cb7320c9165-ஆக உள்ளதை, pin செய்து வைத்துக்கொள்ளுங்கள். உங்கள் commit message-ல் அதைக் குறிப்பிடுங்கள்; அப்போதுதான் உங்கள் tree எந்த version விதிகளின் கீழ் உருவாக்கப்பட்டது என்பதைப் பிற்காலத்தில் உங்களால் கண்டறிய முடியும்.

கைமுறையாக எழுதிய விதிகளை regeneration செயல்முறை நீக்காமல் தடுப்பது எப்படி?

Intent மற்றும் inventory-ஐத் தனித்தனியாக வைத்திருங்கள். நீடித்திருக்கும் காரணங்கள் (durable reasoning) தனி ஆவணத்தில் இருக்க வேண்டும். AGENTS.md-க்குள் கட்டாயம் இருக்க வேண்டியவை ஒரு குறிப்பிட்ட block-க்குள் இருக்க வேண்டும். பிறகு CI-ல் அந்த block-ஐச் சரிபார்க்கவும்: அதை branch-லிருந்தும் origin/main-லிருந்தும் sed மூலம் பிரித்தெடுத்து, diff கொண்டு இரண்டையும் ஒப்பிடவும். ஏதேனும் மாற்றம் இருந்தால் build-ஐத் தோல்வியடையச் செய்யவும். ஒரு பெரிய diff-க்குள் கவனிக்கப்படாமல் மாறுவதற்குப் பதிலாக, ஒரு நபர் அந்த மாற்றத்தை அங்கீகரிக்க வேண்டும் அல்லது நிராகரிக்க வேண்டும்.

AGENTS.md-ஐ எவ்வளவு அடிக்கடி regenerate செய்ய வேண்டும்?

அது தவறாக மாறும் pull request-ன் போது செய்ய வேண்டும். ஒரு கட்டமைப்பு மாற்றமும் அதன் ஆவணமும் ஒரே diff-ல் இருக்க வேண்டும், ஏனெனில் அப்போதுதான் இரண்டையும் ஆய்வு செய்வதற்கான சூழல் ஒருவருக்கு இருக்கும். வாராந்திர scheduled pass என்பது branch-ல் கவனிக்கப்படாமல் போன மாற்றங்களுக்கான காப்பு (backup) ஆகும். இது main-ல் commit செய்வதற்குப் பதிலாக ஒரு pull request-ஐ உருவாக்க வேண்டும்.

Build commands root AGENTS.md-ல் இருக்க வேண்டுமா அல்லது child-ல் இருக்க வேண்டுமா?

அவற்றுக்குச் சொந்தமான அருகிலுள்ள ஆவணத்தில் இருக்க வேண்டும். Repo முழுமைக்குமான விதிகள் மற்றும் child index ஆகியவை root-ல் இருக்க வேண்டும். ஒரு package-க்கு மட்டும் பொருந்தும் command அந்த package-ன் AGENTS.md-ல் இருக்க வேண்டும். dox முரண்பாடுகளைத் தூரத்தின் அடிப்படையில் தீர்க்கிறது: அருகிலுள்ள ஆவணம் local விவரங்களைக் கட்டுப்படுத்தும், எந்தவொரு child-ம் parent விதியைத் தளர்த்தக்கூடாது. ஒவ்வொரு child-லும் ஒரே command-ஐ நகலெடுப்பதுதான், ஒரு routine pass முழு tree-யையும் மீண்டும் எழுதக் காரணமாகிறது.

சிறிய repository-க்கு dox பயனுள்ளதா?

பொதுவாக இல்லை. ஒரு test command மற்றும் இருபது வரிகள் கொண்ட AGENTS.md-ஐக் கொண்ட ஒரு package மெதுவாகவே சிதையும், அதை நீங்கள் கவனித்த ஒரு நிமிடத்தில் சரிசெய்துவிடலாம். repository-ல் வெவ்வேறு விதிகளைக் கொண்ட பல எல்லைகள் இருக்கும்போதோ, அல்லது பின்னணி அறிவு இல்லாத பங்களிப்பாளர்கள் இருக்கும்போதோ dox அதன் மதிப்பை உணர்த்துகிறது. ஏனெனில், அப்போது ஆவணங்களின் சங்கிலித் தொடர், எந்தவொரு தனிநபரும் செய்யாத வேலையைச் செய்கிறது.