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 கோப்பு. இதன் களஞ்சியம் agent0ai/dox, இது MIT உரிமம் பெற்றது, மேலும் 11 ஆகஸ்ட் 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 தேவை என்பதை அதற்கு உணர்த்துகிறது; அதாவது, ஒரு பணி முடிவடைந்ததாகக் கருதப்படுவதற்கு முன்பே ஆவணங்களைப் புதுப்பிக்கும் படிநிலை மேற்கொள்ளப்பட வேண்டும். நோக்கம், அமைப்பு, பணிப்பாய்வு (workflow), அனுமதிகள் அல்லது பயனர் விருப்பத்தேர்வுகள் மாறும்போது, அந்த மாற்றத்திற்கு நெருக்கமான ஆவணத்தை இந்தப் pass புதுப்பிக்கிறது.

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

Dox-ஐ main-க்கு பதிலாக ஒரு குறிப்பிட்ட commit-க்கு pin செய்யவும்

இந்த repository-ல் tags அல்லது releases இல்லாததால், pin செய்வதற்கு version எண் எதுவும் இல்லை. அதற்கு பதிலாக commit-ஐ pin செய்யவும். தற்போதைய AGENTS.md என்பது f34ec7ad1055d3393887e5a2670e8cb7320c9165 commit ஆகும், இதன் தேதி 1 August 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-ஐ அச்சிடும். ஒரு முழுமையற்ற கோப்பு, கோப்பு இல்லாததை விட மோசமானது, ஏனெனில் முகவர் (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-க்குள் இருக்கும் உங்கள் முகவரிடம் முதல் pass-ஐக் கேட்கவும். 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 அந்தப் புதிய தரநிலையை அமல்படுத்தத் தொடங்கிவிடும்.

உருவாக்கப்பட்ட ஆவணப்பட்டியலில் (inventory) கைப்பட எழுதப்பட்ட குறிப்புகளைத் தவிர்க்கவும்

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

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

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

இரண்டாவதாக, 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) பக்கத்தில் தெரியாது, ஆனால் ஏஜெண்ட் அவற்றைப் படிக்கும். இப்போது, அந்தத் தொகுப்பு நீக்கப்படாமல் இருப்பதைச் சரிபார்க்கவும், இதனால் அதை அழிக்கும் தானியங்கி முறை தோல்வியடையும். ஒவ்வொரு 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) என்பது காப்புப்பிரதி (backup) மட்டுமே, அது முதன்மை வழிமுறை அல்ல. rebase மூலம் நகர்த்தப்பட்ட கோப்புகள், merge-ல் நீக்கப்பட்ட package, அல்லது இப்போது இல்லாத ஒரு directory-ஐக் குறிப்பிடும் ஆவணம் என, யாரும் கவனிக்காதவற்றை வாராந்திர job கண்டறியும். இதை ஒரு சிறிய box-ல் இயக்குங்கள், run a coding agent on a VPS-க்கு நீங்கள் பயன்படுத்தும் அதே box-ல் இதை இயக்கலாம். main-க்கு push செய்வதற்குப் பதிலாக, இது ஒரு 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-ம் முக்கியமானது: tree ஏற்கனவே current-ஆக இருக்கும்போது git commit ஆனது nothing to commit, working tree clean உடன் non-zero exit-ஐக் கொடுக்கும். set -e-ன் கீழ், அது சரியாக இயங்கியதை ஒரு தோல்வியாகக் காட்டும்.

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

Monorepos: பல ஒப்பந்தங்கள், ஒரு index

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

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

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

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

Code-ஐப் போலவே diff-ஐயும் சரிபார்க்கவும்

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

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

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

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

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 செய்யவும்; இதன் மூலம் இரண்டு ஆவணங்கள் வெவ்வேறாக மாறுவதைத் தவிர்த்து ஒரே மூலத்தைப் பராமரிக்கலாம். கோப்புப் பெயர் சரியாக இருந்தும் விதிகள் புறக்கணிக்கப்பட்டால், ஆவணத்தை மீண்டும் எழுதுவதற்கு முன் ஏன் coding agents உங்கள் அறிவுறுத்தல்களைப் புறக்கணிக்கின்றன என்பதற்கான நோயறிதலை (diagnosis) இயக்கவும்.

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

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

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

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

FAQ

dox-ஐப் பயன்படுத்த நான் எதையாவது நிறுவ வேண்டுமா?

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

நான் கைமுறையாக எழுதிய விதிகளை, 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 branch-ல் commit செய்வதற்குப் பதிலாக, ஒரு pull request-ஐ உருவாக்க வேண்டும்.

Build கட்டளைகள் root AGENTS.md-ல் இருக்க வேண்டுமா அல்லது child கோப்பில் இருக்க வேண்டுமா?

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

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

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