doxతో AGENTS.mdని స్వయంచాలకంగా తాజాగా ఉంచడం

మూడు వారాల తర్వాత మీ AGENTS.md ఎందుకు తప్పుగా మారుతుంది

AGENTS.md ఫైల్ codeతో అనుసంధానించబడి ఉండకపోవడం వల్ల కాలక్రమేణా పాతబడుతుంది. Repository ఒక నిర్దిష్ట స్థితిలో ఉన్న రోజున దాన్ని చేతితో ఒకసారి రాస్తారు. తరువాత test runner మారుతుంది, package పేరు మార్చబడుతుంది, service తొలగించబడుతుంది. కానీ ఆ ఫైల్ మాత్రం June నెలలో ఉన్న స్థితినే వివరిస్తుంది. ఏ build step కూడా దాన్ని చదవదు కాబట్టి ఎలాంటి వైఫల్యం కనిపించదు.

Agent దాన్ని చదివి నిజమని నమ్ముతుంది. సమస్యకు కారణమయ్యేది ఇదే. AGENTS.md లేని repositoryలో coding agent చర్య తీసుకునే ముందు పరిసరాలను పరిశీలిస్తుంది. తప్పుగా ఉన్న AGENTS.md ఉన్న repositoryలో అది పరిశీలించడం ఆపేస్తుంది, ఎందుకంటే సమాధానం ఇప్పటికే తన వద్ద ఉందని భావిస్తుంది. మీ ఫైల్‌లో పేర్కొన్న command ను అది నడుపుతుంది. Shell Missing script: "test" అని సమాధానం ఇస్తుంది. అప్పుడు agent ఊహాగానాలు చేయడం ప్రారంభిస్తుంది. మీ documentation వాగ్దానం చేసిన script ను జోడించడానికి అది తరచుగా package.json ను సవరిస్తుంది. పాతబడిన ఫైల్ నిశ్శబ్దంగా విఫలం కాలేదు. మీరు కోరని మార్పుకు అది కారణమైంది.

దానికి dox ఒక పరిష్కారం. ఇది agent కోసం రాసిన నియమాల సమాహారం. పని పూర్తిచేయడంలో documentation నవీకరణను కూడా భాగంగా చేస్తుంది. అందువల్ల ఫైల్‌ను తప్పుగా మార్చిన code చేసిన commit లోనే documentation మార్పు కూడా జరుగుతుంది.

dox అంటే ఏమిటి, ఏమి కాదు

dox ఒకే Markdown file. Repository agent0ai/dox, దానికి MIT license ఉంది. 11 August 2026 నాటికి మొత్తం project లో ఒక 3906-byte AGENTS.md, ఒక README, ఒక LICENSE మరియు రెండు images మాత్రమే ఉన్నాయి. Install చేయాల్సిన package లేదు. Runtime కూడా లేదు.

ఇది ముఖ్యమైన విషయం. ఎందుకంటే generator అనే పదం మీ code ను parse చేసే program ను సూచిస్తుంది. కానీ మీ code ను ఏదీ parse చేయదు. dox అనేది మీ coding agent చదివే contract. మీ agent generator. dox దానికి docs ఎప్పుడు చదవాలి, వాటిని ఎప్పుడు తిరిగి రాయాలి, ప్రతి document ఏ రూపంలో ఉండాలి అనే instruction set ను అందిస్తుంది.

ఈ file లో పది sections ఉన్నాయి. వాటిలో రెండు ప్రధానంగా పని చేస్తాయి. "Read Before Editing" agent కు repository root నుంచి తాను మార్చబోయే ప్రతి path వరకు వెళ్లి, ప్రతి మార్గంలో కనిపించే AGENTS.md ను ప్రస్తుత session లోనే చదవమని చెబుతుంది. Memory పై ఆధారపడకూడదని కూడా చెబుతుంది. "Update After Editing" ప్రకారం ప్రతి meaningful change కు DOX pass తప్పనిసరి. అంటే task పూర్తయిందిగా పరిగణించే ముందు documentation update step ను run చేయాలి. Purpose, structure, workflow, permissions లేదా user preferences మారితే, ఈ pass సమీపంలోని owning document ను update చేస్తుంది.

మిగిలినది document shape కు సంబంధించినది. Child AGENTS.md కు default section order ఉంటుంది: Purpose, Ownership, Local Contracts, Work Guidance, Verification మరియు Child DOX Index. Root file లో project-wide rules తో పాటు top-level Child DOX Index ఉంటుంది. దీని ద్వారా agent child documents ను కనుగొంటుంది. "Closeout" అనేది task చివర agent run చేసే checklist: మార్చిన paths ను chain తో మళ్లీ సరిపోల్చడం, సమీపంలోని owning docs ను update చేయడం, ప్రభావితమైన ప్రతి index ను refresh చేయడం, contradictions తొలగించడం, ఇప్పటికే ఉన్న verification ను run చేయడం, అలాగే ఉద్దేశపూర్వకంగా మార్చకుండా వదిలిన docs ఏవో report చేయడం.

ఒకే commit కు pin చేయండి, main కు కాదు

Repositoryలో tags లేదా releases ఏవీ లేవు. అందువల్ల pin చేయడానికి version number లేదు. దానికి బదులుగా commit ను pin చేయండి. ప్రస్తుత AGENTS.md commit f34ec7ad1055d3393887e5a2670e8cb7320c9165, తేదీ 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 యొక్క output 3906 గా ఉండాలి. వేరే సంఖ్య కనిపిస్తే, ఈ guide వివరించే file ను మీరు fetch చేయలేదు. అందువల్ల దాన్ని నమ్మే ముందు చదవండి. Commit hash ను తప్పుగా నమోదు చేస్తే, -f curl ను curl: (22) The requested URL returned error: 404 తో ఆపి ఎలాంటి content ను రాయదు. తరువాత wc -c, 0 ను print చేస్తుంది. File లేకపోవడం కంటే truncated file ప్రమాదకరం. ఎందుకంటే agent సగం contract ను మాత్రమే అనుసరిస్తుంది, అది అసంపూర్ణమని తెలియకపోవచ్చు.

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 చేయవద్దు. మీ existing content పైన dox sections ను ఉంచండి. మీ స్వంత rules ను దిగువన ఉంచండి. తరువాత మొత్తం ఫలితాన్ని పై నుంచి కింద వరకు ఒకసారి చదవండి. పరస్పరం విరుద్ధమైన రెండు documents ఉంటే, agent చివరగా చదివిన line ను అనుసరిస్తుంది.

తరువాత repository లోపల మీ agent ను మొదటి pass కోసం అడగండి. READMEలో ఖచ్చితమైన wording ఉంది:

Initialize DOX tree for this project now.

ఇది child AGENTS.md files మరియు వాటిని సూచించే indexes ను సృష్టిస్తుంది. దాని పని పూర్తయిందని నమ్మే ముందు పరిశీలించండి:

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

ఆ find output లోని ప్రతి file, పైభాగంలో ఎక్కడో ఒక Child DOX Index లో కనిపించాలి. ఏ index కూడా ప్రస్తావించని child document ను agent మిస్ చేయవచ్చు. ఎందుకంటే తాను నడుస్తున్న path పై నేరుగా లేని documents ను కనుగొనడానికి index నే ఉపయోగిస్తుంది.

dox చూడగలిగేది, తెలుసుకోలేనిది

మీ tree ను నిర్మించే agent repository ను చదువుతుంది. అందువల్ల repository లో ఉన్న ఏదైనా inventory లోకి వెళ్లవచ్చు: directory layout, package manifests మరియు lockfiles, package.json లేదా Makefile లేదా pyproject.toml లోని scripts, CI workflow files, Dockerfiles, entry points, అలాగే మీ వద్ద ఉంటే CODEOWNERS. వీటి ఆధారంగా నిర్మించిన inventory నిజంగా self-maintaining గా ఉంటుంది. ఏదైనా package స్థానం మారితే, తదుపరి pass దాన్ని వివరించే line ను కూడా మార్చుతుంది.

కిందివి repository లో చదవడానికి అందుబాటులో ఉండవు. అందువల్ల వాటిని మీరు స్వయంగా పేర్కొనాలి:

• ఒక rule ఎందుకు ఉందో. ఇది unnecessary complexity గా భావించి agent దాన్ని తొలగించకుండా ఆపుతుంది
• పనిచేస్తున్న రెండు మార్గాల్లో ఏది supported మార్గమో, ఏది తొలగించడానికి వేచి ఉందో
• repository వెలుపల ఉన్న ఏదైనా విషయం, ఉదాహరణకు staging environment లేదా dependency ను రెండు versions వెనుక pin చేసి ఉంచడానికి కారణం
• వచ్చే వారం మీరు ఏమి చేయాలనుకుంటున్నారో. ఇదే ఒక file ప్రస్తుతానికి సరిపోతుందా, ఉపయోగకరంగా ఉందా అనే తేడా

dox కు తన గురించి ఈ విషయం తెలుసు. ప్రాజెక్ట్‌ యొక్క ప్రస్తుత standards లేదా user instructions ను Work Guidance ప్రతిబింబించాలి అని దాని స్వంత rules చెబుతున్నాయి. ఇంకా అలాంటివి లేకపోతే ఆ section ను ఖాళీగా ఉంచాలి. Verification ఇప్పటికే ఉన్న check ను ప్రతిబింబించాలి. అందువల్ల repository లో test framework లేకపోతే, అది ఏర్పడే వరకు ఆ section ఖాళీగానే ఉండాలి. ఒక standard ను కల్పించే generated file, ఖాళీ section కంటే అధ్వాన్నం. ఎందుకంటే agent ఆ కల్పిత standard ను అమలు చేయడం ప్రారంభిస్తుంది.

రూపొందించిన inventory లో చేతితో రాసిన ఉద్దేశ్యాన్ని ఉంచవద్దు

Generated docs పై నమ్మకం కోల్పోయేలా చేసే వైఫల్యం ఇదే. Jobs queue ఒకే consumer గా ఉండాలని వివరిస్తూ మీరు ఒక paragraph రాస్తారు. మూడు వారాల తర్వాత ఒక pass ఆ file ను మళ్లీ రాస్తుంది. మీ paragraph నలభై lines ఉన్న diff లో కనిపించకుండా పోతుంది. ఆ diff లో ఎక్కువ భాగం file names ను కేవలం క్రమం మార్చడమే అయినా, దాన్ని ఎవరూ గుర్తించరు.

రెండు విధానాలను ఉపయోగించాలి. రెండూ అవసరం.

మొదట, ఎక్కువకాలం నిలవాల్సిన ఉద్దేశ్యాన్ని వేరే file లో ఉంచండి. Design decisions మరియు వాటి వెనుక ఉన్న కారణాలను agent కోసం రాసిన DESIGN.md లో ఉంచాలి. వ్యక్తుల కోసం ఉన్న notes ను AGENTS.md నుంచి HUMAN.md గా వేరు చేయాలి. AGENTS.md లో inventory మరియు local contracts మాత్రమే ఉండాలి. Code మారినప్పుడు మారాల్సిన భాగం అదే.

రెండవది, AGENTS.md లోనే ఉండాల్సిన ఉద్దేశ్యాన్ని ప్రత్యేకంగా రక్షించండి. దాన్ని markers మధ్య ఉంచి, ఆ block ను మనుషులు నిర్వహించే భాగంగా పరిగణించండి:

## 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 page పై render కావు. అయినా agent వాటిని చదువుతుంది. ఇప్పుడు ఆ block అలాగే మిగిలిందో తనిఖీ చేయగలిగేలా చేయండి. దాన్ని తొలగించే pass విఫలమైనప్పుడు స్పష్టంగా కనిపించాలి. ప్రతి 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

Block మారకుండా ఉంటే diff ఎలాంటి output ఇవ్వదు మరియు 0 తో exit అవుతుంది. ఏదైనా output వస్తే, pass మనుషులు నిర్వహించే text ను మళ్లీ రాసిందని అర్థం. అప్పుడు ఒక వ్యక్తి దాన్ని approve చేయాలి లేదా revert చేయాలి. దీన్ని గుర్తుంచుకోవడానికి ఎవరిపైనా ఆధారపడాల్సిన అవసరం లేకుండానే ఈ check పనిచేస్తుంది.

pull request సమయంలోనే Regenerate చేయండి, timer పై కాదు

ఒక document ను refresh చేయడానికి సరైన సమయం, అది తప్పుగా మారే commit సమయంలోనే. Structural change ఉన్న అదే pull request లో DOX pass ను చేర్చండి. అప్పుడు 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 పై ఉండగానే ఇది విఫలమవుతుంది. ఆ సమయంలో fix చేయడం సులభం. అలాగే reviewer చర్య తీసుకోగల కారణంతోనే ఇది విఫలమవుతుంది.

Schedule అనేది backup మాత్రమే, ప్రధాన mechanism కాదు. Branch పై ఎవరూ గమనించని మార్పులను weekly job గుర్తిస్తుంది: rebase ద్వారా files తరలిపోవడం, merge లో package తొలగిపోవడం, ఇక లేని directory ను document సూచించడం వంటివి. దీన్ని చిన్న box పై run చేయండి. VPS పై coding agent ను run చేయడానికి మీరు ఉపయోగించే అదే box కావచ్చు. ఇది main కు push చేయకుండా pull request open చేసేలా రూపొందించండి.

#!/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 కు సరిపోని web page నుంచి copy చేసిన command cron లో run అయినప్పుడు విఫలమవుతుంది. ఆ error ను ఎవరూ చూడకపోవచ్చు. Schedule చేయడానికి ముందు దాన్ని పూరించి, script ను ఒకసారి చేతితో run చేయండి. || exit 0 కూడా ముఖ్యమే: tree ఇప్పటికే current గా ఉంటే git commit, nothing to commit, working tree clean తో non-zero exit చేస్తుంది. set -e లో అది ఆరోగ్యంగా పూర్తైన run ను failure గా నివేదిస్తుంది.

ప్రతి pass కు tokens ఖర్చవుతాయి. "Read Before Editing" కారణంగా agent ప్రతి task సమయంలో మొత్తం chain ను చదవాలి. ఇదే trade-off. మీరు ఇప్పటికే మీ agent run లకు అయ్యే ఖర్చును లెక్కిస్తున్నట్లయితే దీన్ని గమనించడం విలువైనది.

Monorepos: అనేక contracts, ఒకే index

నలభై packages ఉన్న repository లో ఒకే root AGENTS.md ఉంచితే, ఎవరూ చదవని regeneration diff తయారవుతుంది. ప్రస్తుతం agent చేస్తున్న పనికి ఎక్కువ భాగం సంబంధం లేని document కూడా తయారవుతుంది. dox దీనికి Child DOX Index ను అందిస్తుంది: root లో repository మొత్తం వర్తించే rules ఉంటాయి మరియు అది తన child files ను సూచిస్తుంది. ప్రతి స్థిరమైన boundary కు దాని స్వంత file ఉంటుంది. ఈ tree ను ఎలా అమర్చాలి, nested files ను ఏ tools చదువుతాయి అనేది monorepos కోసం nested AGENTS.md files లో వివరించబడింది.

dox మార్చేది review surface. packages/api ను తాకే pull request లో documentation diff packages/api లో మాత్రమే ఉండాలి; మరెక్కడా ఉండకూడదు:

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

ఒక package మార్పుకు ఆ command ఆరు files ను చూపిస్తే, tree నిర్మాణం తప్పుగా ఉంది. Boundaries చాలా విస్తృతంగా ఉండవచ్చు, లేదా root లో ఉండాల్సిన rule ప్రతి child లోనూ copy అయి ఉండవచ్చు. dox పరిష్కారాన్ని నేరుగా చెబుతుంది: విస్తృత rules ను parent docs లో ఉంచాలి, నిర్దిష్ట వివరాలను child docs లో ఉంచాలి. Duplicated rules వల్ల సాధారణ pass ప్రతి document ను మళ్లీ రాయాల్సి వస్తుంది. వేర్వేరు repositories అంతటా అదే rules నిజంగా వర్తిస్తే, అది వేరే సమస్య. దానికి repositories అంతటా agent skills పంచుకోవడం మరింత సరైన tool.

కోడ్‌లా diff ను సమీక్షించండి

చదవకుండానే రూపొందించిన documentation diff ను ఆమోదించడం సులభం. అందుకే తప్పు file విడుదల అవుతుంది. రూపొందించిన code ను పరిశీలించేంత జాగ్రత్తతో దీన్ని చదవండి. ఈ నాలుగు విషయాలను చూడండి.

• file ఇప్పుడు పేర్కొంటున్న command ను merge చేయడానికి ముందు మీరే run చేయాలి. కల్పిత build instructions అత్యంత సాధారణ వైఫల్యం.
• ఉద్దేశాన్ని తెలిపిన deleted line. Additions సులభంగా జోడించవచ్చు. నష్టం జరిగేది deletions లోనే.
• absolute path, hostname, internal URL లేదా credential లా కనిపించే ఏదైనా
• ఇక లేని దానికి సంబంధించిన inventory entry. దాన్ని ls ఒక్క సెకనులో గుర్తిస్తుంది.

తర్వాత wc -l AGENTS.md తో పరిమాణాన్ని తనిఖీ చేయండి. root file రెండు వందల lines ను దాటితే దాన్ని విభజించాలి. ఎందుకంటే ఈ chain మొత్తం విలువ ఏమిటంటే, agent ప్రతిదీ కాకుండా అవసరమైన చిన్న భాగాన్ని మాత్రమే చదవడం.

పనిచేయడం ఆగిపోయినప్పుడు

pass మీ intent block ను తొలగించింది. పైన ఉన్న diff check తొలగించబడిన lines ను చూపిస్తుంది. git restore --source=origin/main AGENTS.md తో branch point నుంచి file ను పునరుద్ధరించండి. తరువాత మార్పులు చేయగల sections పేర్లను స్పష్టంగా పేర్కొనే మరింత పరిమిత instruction తో pass ను మళ్లీ అమలు చేయండి.

రెండు branches రెండూ మళ్లీ generate చేశాయి. మీకు file లో CONFLICT (content): Merge conflict in AGENTS.md మరియు conflict markers <<<<<<< HEAD కనిపిస్తాయి. Markers ను చేతితో సవరించవద్దు. ఈ file generate చేయబడుతుంది. కాబట్టి merged tree పై fresh pass అమలు చేయడమే సరైన resolution.

agent file ను పూర్తిగా పట్టించుకోదు. మీ tool వాస్తవంగా ఏ filename ను చదువుతుందో తనిఖీ చేయండి. అది వేరే file ను చదువుతుంటే, ln -s AGENTS.md CLAUDE.md తో అదే content వైపు దాన్ని point చేసి symlink ను commit చేయండి. ఇలా చేస్తే పరస్పరం మారిపోయే రెండు documents బదులు ఒకే source ఉంటుంది.

tree లో ఎవరూ index చేయని children చేరాయి. find . -name AGENTS.md output ను parent documents లోని index entries తో పోల్చండి. ఏ index కూడా ప్రస్తావించని child ను agent నేరుగా దాటి వెళ్లవచ్చు.

Generator అధికమైనప్పుడు

ఒక package, ఒక test command, repository గురించి పూర్తి పరిజ్ఞానం ఉన్న ఇద్దరు వ్యక్తులు మాత్రమే ఉంటే, ఆ ఇరవై పంక్తులను చేతితో రాయండి. ఇరవై పంక్తుల AGENTS.md పాతబడటానికి tree, index, CI check, weekly job అవసరమయ్యేంత వేగంగా మారదు. Build ను మార్చినప్పుడు దాన్ని మళ్లీ చదవండి. నిర్వహణకు అవసరమైన మొత్తం పని అంతే. దాని చుట్టూ ఉన్న machinery నిర్వహణ ఖర్చుకంటే ఇది తక్కువ.

Repository లోని boundaries ఏ ఒక్కరి మదిలోనూ పూర్తిగా లేకపోతే dox ఉపయోగించడం సముచితం. ఉదాహరణకు, వేర్వేరు rules ఉన్న అనేక packages ఉన్నప్పుడు లేదా అవసరమైన నేపథ్య పరిజ్ఞానం లేకుండా contributors చేరినప్పుడు ఇది ఉపయోగకరం. విలువ generated text లో లేదు. Documentation గా మారిన అంశంపై pull request విఫలమయ్యేలా చేయగలగడంలో ఉంది. Repository లోని ఏ file అయినా ప్రస్తుత స్థితిలో ఉండటానికి ఇదే ఏకైక కారణం.

FAQ

dox ఉపయోగించడానికి ఏదైనా ఇన్‌స్టాల్ చేయాలా?

లేదు. dox ఒకే Markdown ఫైల్, దీనికి MIT లైసెన్స్ ఉంది. 11 August 2026 నాటికి repositoryలో package లేదా releases లేవు. దాని కంటెంట్‌ను మీ projectలోని AGENTS.mdలోకి copy చేస్తే, మీ coding agent అక్కడి rulesను అనుసరిస్తుంది. మీరు copy చేసిన commitను, ప్రస్తుత రచనా సమయానికి f34ec7ad1055d3393887e5a2670e8cb7320c9165, స్థిరంగా నిర్దేశించండి. మీ tree ఏ rules version ఆధారంగా రూపొందించబడిందో తరువాత తెలుసుకునేందుకు దాని పేరును commit messageలో నమోదు చేయండి.

మళ్లీ రూపొందించే ప్రక్రియ నేను స్వయంగా రాసిన rulesను తొలగించకుండా ఎలా ఆపాలి?

ఉద్దేశ్యం మరియు inventoryని వేర్వేరుగా ఉంచండి. మారకుండా ఉండాల్సిన reasoningను ప్రత్యేక documentలో ఉంచండి. AGENTS.mdలో తప్పనిసరిగా ఉండాల్సినదాన్ని marked blockలో ఉంచండి. తరువాత ఆ blockను CIలో తనిఖీ చేయండి: దాన్ని branch నుంచి మరియు origin/main నుంచి sedతో extract చేసి, రెండింటినీ diffతో compare చేయండి. ఏ తేడా ఉన్నా buildను fail చేయండి. పెద్ద diffలో మార్పు గుర్తించబడకుండా pass కావడానికి బదులుగా, ఒక వ్యక్తి దాన్ని approve చేయాలి లేదా revert చేయాలి.

AGENTS.mdను ఎంత తరచుగా మళ్లీ రూపొందించాలి?

అది తప్పుగా మారే pull requestలోనే మళ్లీ రూపొందించాలి. Structural change మరియు దాని documentation ఒకే diffలో ఉండాలి. రెండింటినీ review చేయడానికి అవసరమైన context ఎవరికైనా ఉండే ఏకైక సమయం అదే. Branchలో గుర్తించకుండా మిగిలిపోయిన drift కోసం వారానికి ఒకసారి scheduled pass backupగా ఉండాలి. అది mainలో నేరుగా commit చేయకుండా pull requestను open చేయాలి.

Build commandsను root AGENTS.mdలో ఉంచాలా, childలో ఉంచాలా?

వాటికి సంబంధించిన ownership ఉన్న అత్యంత సమీప documentలో ఉంచాలి. Repo-wide rules మరియు child index rootలో ఉంటాయి. ఒక packageకు మాత్రమే వర్తించే command ఆ packageలోని AGENTS.mdలో ఉండాలి. dox conflictsను distance ఆధారంగా resolve చేస్తుంది: సమీప document local detailsను నియంత్రిస్తుంది, కానీ ఏ child కూడా parent ruleను బలహీనపరచకూడదు. ప్రతి childలో ఒకే commandను copy చేయడం వల్ల సాధారణ pass మొత్తం treeను మళ్లీ రాస్తుంది.

చిన్న repositoryకి dox ఉపయోగకరమా?

సాధారణంగా కాదు. ఒక test commandతో కూడిన ఒక package మరియు ఇరవై పంక్తుల AGENTS.md నెమ్మదిగా మాత్రమే పాతబడతాయి. సమస్యను గమనించిన వెంటనే ఒక నిమిషంలో దాన్ని సరిచేయవచ్చు. Repositoryలో వేర్వేరు rules ఉన్న అనేక boundaries ఉన్నప్పుడు, లేదా background knowledge లేని contributors ఉన్నప్పుడు dox ఖర్చుకు తగిన ప్రయోజనం ఇస్తుంది. అప్పుడు documents chain, ఏ ఒక్క వ్యక్తి చేయని నిర్వహణ పనిని చేస్తుంది.