dox ने AGENTS.md आपोआप अद्ययावत कशी ठेवावी

तीन आठवड्यांनंतर तुमची AGENTS.md चुकीची का ठरते

AGENTS.md फाइल कोडशी जोडलेली नसल्यामुळे कालबाह्य होते. Repository ज्या स्थितीत आहे त्या दिवसासाठी तुम्ही ती एकदाच हाताने लिहिता. त्यानंतर test runner बदलतो, एखाद्या package चे नाव बदलते, एखादी service हटवली जाते; पण फाइलमध्ये अजूनही June महिन्याचे वर्णन असते. काहीही fail होत नाही, कारण कोणतीही build step ती फाइल वाचत नाही.

Agent ती फाइल वाचतो आणि तिच्यावर विश्वास ठेवतो. हाच भाग तुमच्यासाठी खर्चिक ठरतो. AGENTS.md नसलेल्या repository मध्ये coding agent कृती करण्यापूर्वी परिस्थिती तपासतो. चुकीची AGENTS.md असलेल्या repository मध्ये तो तपासणे थांबवतो, कारण त्याच्याकडे आधीच उत्तर असते. तो तुमच्या फाइलमध्ये दिलेली command चालवतो, shell Missing script: "test" उत्तर देते आणि आता agent अंदाज बांधू लागतो. अनेकदा तुमच्या documentation मध्ये वचन दिलेली script जोडण्यासाठी तो package.json संपादित करतो. कालबाह्य फाइल शांतपणे fail झाली नाही. तिच्यामुळे तुम्हाला नको असलेला edit झाला.

dox हा त्यावरील एक उपाय आहे. हे agent साठी लिहिलेल्या rules चा संच आहे. काम पूर्ण करण्याचा भाग म्हणून documentation update करणे त्यात आवश्यक केलेले आहे. त्यामुळे फाइल चुकीची ठरवणाऱ्या code सोबतच त्याच commit मध्ये ती फाइलही बदलते.

dox म्हणजे काय आणि ते काय नाही

dox ही एकच Markdown फाइल आहे. 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 हा instruction set आहे. तो agent ला docs कधी वाचायचे, ती कधी पुन्हा लिहायची आणि प्रत्येक document ची रचना कशी असावी हे सांगतो.

या file मध्ये दहा sections आहेत आणि त्यांपैकी दोन sections प्रत्यक्ष काम करतात. "Editing करण्यापूर्वी वाचा" हा section agent ला repository root पासून तो बदलणार असलेल्या प्रत्येक path पर्यंत जाण्यास आणि प्रत्येक मार्गावरील AGENTS.md वाचण्यास सांगतो. हे त्याने सध्याच्या session मध्ये करायचे असते आणि memory वर अवलंबून राहायचे नसते. "Editing नंतर update करा" हा section सांगतो की प्रत्येक अर्थपूर्ण बदलासाठी DOX pass आवश्यक आहे. म्हणजे task पूर्ण मानण्यापूर्वी documentation update step चालवायची असते. Purpose, structure, workflow, permissions किंवा user preferences मध्ये बदल झाल्यास हा pass सर्वात जवळच्या owning document चे update करतो.

उर्वरित भाग रचनेशी संबंधित आहे. 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 असतो. याच index द्वारे agent ला child documents सापडतात. "Closeout" ही task च्या शेवटी agent चालवणारी checklist आहे: बदललेल्या paths ची chain शी पुन्हा पडताळणी करणे, सर्वात जवळच्या owning docs चे update करणे, प्रभावित प्रत्येक index refresh करणे, contradictions हटवणे, उपलब्ध verification चालवणे आणि कोणते docs जाणीवपूर्वक तसेच ठेवले हे report करणे.

dox ला main ऐवजी एका commit ला pin करा

Repository मध्ये tags किंवा releases नाहीत. त्यामुळे pin करण्यासाठी version number उपलब्ध नाही. त्याऐवजी 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 दाखवले पाहिजे. वेगळी संख्या दिसल्यास, या मार्गदर्शकात वर्णन केलेली file fetch झालेली नाही. त्यामुळे तिच्यावर विश्वास ठेवण्यापूर्वी ती वाचा. Commit hash चुकीचा टाइप केल्यास, -f curl ला curl: (22) The requested URL returned error: 404 सह थांबवते आणि कोणताही content लिहित नाही. त्यानंतर wc -c 0 दाखवते. File अपूर्ण असणे हे 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 साठी आहे. तुमच्याकडे आधीच एक file असल्यास, ती overwrite करू नका. तुमच्या विद्यमान content च्या वर dox sections ठेवा आणि तुमचे स्वतःचे rules खाली ठेवा. त्यानंतर संपूर्ण result सुरुवातीपासून शेवटपर्यंत एकदा वाचा. परस्परविरोधी दोन documents असल्यास, agent शेवटी वाचलेल्या ओळीचे पालन करू शकतो.

त्यानंतर repository च्या आत तुमच्या agent ला first 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 मध्ये दिसली पाहिजे. ज्या child document चा कोणत्याही index मध्ये उल्लेख नाही ते 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 मध्ये त्याचे वर्णन करणारी ओळही हलवली जाते.

खालील सर्व गोष्टी तुम्हालाच नमूद कराव्या लागतात, कारण त्या repository मध्ये वाचण्यासाठी उपलब्ध नसतात:

• एखादा rule का अस्तित्वात आहे. यामुळे agent तो अनावश्यक गुंतागुंत म्हणून काढून टाकत नाही.
• दोन कार्यरत paths पैकी कोणता supported आहे आणि कोणता हटवण्याच्या प्रतीक्षेत आहे.
• repository बाहेरील कोणतीही माहिती, जसे staging environment किंवा dependency दोन versions मागे pin करण्याचे कारण.
• पुढील आठवड्यात तुम्ही काय करणार आहात. यावरून एखादी file current आहे की useful आहे, हे ठरते.

dox ला स्वतःबद्दल ही मर्यादा माहीत आहे. त्याच्या स्वतःच्या rules नुसार Work Guidance मध्ये project चे current standards किंवा user च्या instructions प्रतिबिंबित झाले पाहिजेत. अद्याप अशी कोणतीही माहिती नसल्यास हा section रिकामा ठेवावा. Verification मध्ये अस्तित्वात असलेली check प्रतिबिंबित झाली पाहिजे. त्यामुळे repository मध्ये test framework नसल्यास तो section उपलब्ध होईपर्यंत रिकामाच राहतो. एखादा standard स्वतःहून तयार करणारी generated file रिकाम्या section पेक्षा वाईट असते, कारण त्यानंतर agent त्या बनावट standard ची अंमलबजावणी करेल.

व्यक्तींनी लिहिलेला हेतू निर्माण केलेल्या inventory पासून वेगळा ठेवा

Generated documentation मुळे लोकांचा विश्वास का बसत नाही, याचे हे मुख्य कारण आहे. Jobs queue ने single consumer ठेवला पाहिजे, हे स्पष्ट करणारा परिच्छेद तुम्ही लिहिता. तीन आठवड्यांनंतर एखादा pass ती file पुन्हा लिहितो आणि तुमचा परिच्छेद नाहीसा होतो. चाळीस ओळींच्या diff मध्ये file names ची मुख्यतः फेरमांडणी झालेली असते, त्यामुळे ही बाब कुणाच्याही लक्षात येत नाही.

यासाठी दोन पद्धती वापरा. दोन्ही आवश्यक आहेत.

पहिली, दीर्घकाळ टिकणारा हेतू वेगळ्या file मध्ये ठेवा. Design decisions आणि त्यामागील reasoning agent साठी लिहिलेल्या DESIGN.md मध्ये असावेत. लोकांसाठी असलेल्या notes तुम्ही AGENTS.md मधून HUMAN.md वेगळी करून जिथे ठेवता, तिथे असाव्यात. त्यानंतर AGENTS.md मध्ये inventory आणि स्थानिक 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 पृष्ठावर render होत नाहीत, पण agent ते वाचतो. आता या block चे अस्तित्व तपासता येईल असे करा, जेणेकरून तो block हटवणारा pass स्पष्टपणे fail होईल. प्रत्येक 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 काहीही print करत नाही आणि 0 exit code देतो. कोणतेही output आल्यास pass ने मानवी मालकीच्या text मध्ये पुन्हा लेखन केले आहे. त्यामुळे एखादी व्यक्ती त्यास approve करते किंवा revert करते. कुणालाही ही तपासणी लक्षात ठेवण्याची गरज नसतानाही ती कार्यरत राहते.

पुल रिक्वेस्टवर पुन्हा तयार करा, टाइमरवर नाही

दस्तऐवज अद्ययावत करण्याची सर्वोत्तम वेळ म्हणजे तो चुकीचा करणारा commit. संरचनेतील बदल ज्या pull request मध्ये आहे, त्याच 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 वरच अपयशी ठरते. तेथे दुरुस्ती स्वस्त असते. तसेच reviewer कृती करू शकेल अशा कारणामुळे ती अपयशी ठरते.

Schedule हा backup आहे; मुख्य यंत्रणा नाही. Branch वर कोणाच्या लक्षात न आलेले बदल weekly job पकडते: rebase मुळे हलवलेल्या files, merge मध्ये delete केलेले package किंवा आता अस्तित्वात नसलेल्या directory चे नाव देणारा दस्तऐवज. हे एखाद्या छोट्या box वर चालवा. त्याच box वर तुम्ही VPS वर coding agent चालवू शकता. तसेच 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 शी जुळत नसलेली web page वरून copy केलेली command cron मध्ये चालवल्यास, error पाहणारे कोणीही नसते आणि प्रक्रिया अपयशी ठरते. ती command पूर्ण करा आणि schedule करण्यापूर्वी script एकदा हाताने चालवा. || exit 0 देखील महत्त्वाचे आहे: tree आधीच current असल्यास git commit, nothing to commit, working tree clean सह non-zero exit करते. set -e अंतर्गत त्यामुळे यशस्वी run अपयशी म्हणून नोंदवला जाईल.

प्रत्येक pass साठी tokens लागतात, कारण "Read Before Editing" मुळे agent ला प्रत्येक task वेळी संपूर्ण chain वाचावी लागते. हीच तडजोड आहे. तुम्ही आधीच तुमच्या agent च्या runs साठी किती खर्च येतो हे मोजत असाल, तर त्यावर लक्ष ठेवणे उपयुक्त ठरते.

मोनोरेपो: अनेक करार, एक अनुक्रमणिका

चाळीस पॅकेज असलेल्या repository मध्ये एकच root AGENTS.md ठेवल्यास असा regeneration diff तयार होतो, जो कोणीही वाचत नाही. तसेच agent सध्या करत असलेल्या कामाशी त्यातील बहुतांश मजकूर संबंधित नसतो. dox यासाठी Child DOX Index वापरते: root मध्ये संपूर्ण repository साठीचे नियम असतात आणि तो आपल्या child files कडे निर्देश करतो; प्रत्येक स्थिर boundary ची स्वतःची file असते. हा tree कसा मांडायचा आणि nested files कोणती tools वाचतात, याचे वर्णन मोनोरेपोसाठी nested AGENTS.md files मध्ये केले आहे.

dox मुळे review surface बदलतो. packages/api ला स्पर्श करणाऱ्या pull request मुळे packages/api मध्ये आणि इतरत्र कुठेही documentation diff तयार झाला पाहिजे:

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

एका पॅकेजमधील बदलासाठी त्या command ने सहा files दाखवल्या, तर tree चुकीचा आहे. Boundaries खूप मोठ्या आहेत किंवा root मध्ये असलेला rule प्रत्येक child मध्ये कॉपी केला आहे. dox यावरील उपाय थेट सांगते: व्यापक नियम parent docs मध्ये ठेवा आणि ठोस तपशील child docs मध्ये ठेवा. Duplicated rules मुळे नियमित pass मध्ये सर्वकाही पुन्हा लिहावे लागते. वेगवेगळ्या repositories वर तेच rules खरोखर लागू होत असतील, तर ती वेगळी समस्या आहे; त्यासाठी repositories मध्ये agent skills शेअर करणे हे अधिक योग्य tool आहे.

कोडप्रमाणे diff चे पुनरावलोकन करा

वाचल्याशिवाय generated documentation diff मंजूर करणे सोपे असते. त्यामुळे चुकीची फाइल release होऊ शकते. Generated code तपासताना जशी शंका ठेवता, तशीच शंका येथेही ठेवा आणि चार गोष्टी शोधा.

• फाइलमध्ये आता नमूद केलेली अशी command, जी merge करण्यापूर्वी तुम्ही स्वतः चालवली पाहिजे. चुकीच्या 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 तपासणीमुळे हटवलेल्या ओळी दिसतात. git restore --source=origin/main AGENTS.md वापरून branch point वरील फाइल पुनर्संचयित करा. त्यानंतर pass पुन्हा चालवा आणि कोणते sections बदलता येतील हे स्पष्टपणे सांगणारी अधिक मर्यादित instruction द्या.

दोन्ही branches ने पुन्हा निर्मिती केली. फाइलमध्ये CONFLICT (content): Merge conflict in AGENTS.md आणि conflict markers <<<<<<< HEAD दिसतात. Markers हाताने संपादित करू नका. ही फाइल generated आहे. त्यामुळे merged tree वर नवीन pass चालवणे हाच योग्य resolution आहे.

Agent फाइलकडे पूर्णपणे दुर्लक्ष करतो. तुमचे tool प्रत्यक्षात कोणते filename वाचते ते तपासा. ते वेगळी फाइल वाचत असल्यास ln -s AGENTS.md CLAUDE.md वापरून त्याला समान content कडे निर्देशित करा आणि symlink commit करा. त्यामुळे परस्परांपासून वेगळे होणारे दोन documents ठेवण्याऐवजी एकच source राहतो.

Tree मध्ये कोणाच्याही index मध्ये नसलेली children तयार झाली. find . -name AGENTS.md output ची तुलना parent documents मधील index entries शी करा. ज्या child चा उल्लेख कोणत्याही index मध्ये नाही, त्या child कडे agent थेट दुर्लक्ष करू शकतो.

जनरेटरचा वापर अनावश्यक ठरण्याची वेळ

एकच package, एकच test command आणि repository ची माहिती असलेले दोन लोक असतील, तर वीस ओळी हाताने लिहा. वीस ओळींच्या AGENTS.md मध्ये बदल होण्याचा वेग इतका जास्त नसतो की त्यासाठी tree, index, CI check आणि साप्ताहिक job आवश्यक ठरतील. Build बदलताना ते पुन्हा वाचा. देखभालीचा संपूर्ण खर्च एवढाच आहे आणि त्याभोवतीची यंत्रणा उभारण्याच्या खर्चापेक्षा तो कमी आहे.

Repository मध्ये कोणत्याही एका व्यक्तीच्या पूर्ण लक्षात न राहणाऱ्या boundaries असतील, तेव्हा dox साठी वेळ आणि संसाधने देणे योग्य ठरते: वेगवेगळे नियम असलेली अनेक packages किंवा पूर्वपार्श्वभूमीची माहिती नसलेले contributors. याचे मूल्य generated text मध्ये नाही. Documentation अशी गोष्ट बनते की pull request तिच्या आधारे fail होऊ शकतो; repository मधील कोणतीही file current राहण्याचे हेच एकमेव कारण आहे.

FAQ

dox वापरण्यासाठी मला काही स्थापित करावे लागेल का?

नाही. dox ही MIT परवानाधारक एकच Markdown फाइल आहे. 11 August 2026 रोजी repository मध्ये कोणतेही package किंवा releases उपलब्ध नाहीत. तिचा मजकूर तुमच्या project च्या AGENTS.md मध्ये कॉपी करा. त्यानंतर तुमचा coding agent तेथील नियमांचे पालन करेल. कॉपी केलेला commit, म्हणजे लेखनाच्या वेळी f34ec7ad1055d3393887e5a2670e8cb7320c9165, निश्चित करा आणि तो तुमच्या commit message मध्ये नमूद करा. त्यामुळे तुमची tree नियमांच्या कोणत्या आवृत्तीखाली तयार झाली हे नंतर समजू शकते.

regeneration मुळे माझे स्वतः लिहिलेले नियम हटू नयेत यासाठी काय करावे?

उद्देश आणि inventory वेगळे ठेवा. दीर्घकाळ लागू राहणारे reasoning स्वतंत्र document मध्ये ठेवा. AGENTS.md मध्येच राहणे आवश्यक असलेली सामग्री marked block मध्ये ठेवा. त्यानंतर CI मध्ये त्या block ची तपासणी करा: तो branch मधून आणि origin/main मधून sed वापरून काढा, दोन्ही diff वापरून तुलना करा आणि कोणताही फरक आढळल्यास build अयशस्वी करा. त्यामुळे मोठ्या diff मध्ये बदल नकळत जाऊ देण्याऐवजी एखादी व्यक्ती तो बदल मंजूर किंवा पूर्ववत करू शकते.

AGENTS.md किती वेळाने पुन्हा तयार करावे?

ज्या pull request मुळे ते चुकीचे होते, त्याच pull request मध्ये. संरचनात्मक बदल आणि त्याचे documentation एकाच diff मध्ये असावे. दोन्हींचे पुनरावलोकन करण्यासाठी संदर्भ उपलब्ध असलेला हा एकमेव योग्य क्षण असतो. branch मधून सुटलेल्या drift साठी साप्ताहिक scheduled pass हा backup आहे. त्याने main वर थेट commit न करता pull request उघडला पाहिजे.

build commands root AGENTS.md मध्ये ठेवावेत की child मध्ये?

ज्या जवळच्या document कडे त्या commands ची जबाबदारी आहे, तेथे ठेवा. संपूर्ण repository साठीचे नियम आणि child index root मध्ये असतात. एका package ला लागू होणारा command त्या package च्या AGENTS.md मध्ये असतो. dox अंतरानुसार conflicts सोडवते: जवळचे document स्थानिक तपशील नियंत्रित करते आणि कोणतेही child parent rule कमकुवत करू शकत नाही. प्रत्येक child मध्ये तोच command कॉपी केल्यामुळे routine pass संपूर्ण tree पुन्हा लिहितो.

लहान repository साठी dox उपयुक्त आहे का?

साधारणपणे नाही. एक package, एक test command आणि वीस ओळींचे AGENTS.md हळूहळू कालबाह्य होते. ते लक्षात आल्यानंतर एका मिनिटात दुरुस्त करता येते. Repository मध्ये वेगवेगळ्या नियमांच्या अनेक boundaries असतील किंवा contributors कडे आवश्यक पार्श्वभूमी नसेल, तेव्हा dox चा खर्च योग्य ठरतो. अशा वेळी documents ची chain असे काम करते जे एकटी व्यक्ती करू शकत नाही.