AGENTS.md फाईल स्वयंचलितपणे अपडेट कशी करावी

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

AGENTS.md फाईल जुनी (stale) होते कारण तिचा कोडशी कोणताही तांत्रिक संबंध नसतो. तुम्ही ती एकदा हाताने लिहिता, ज्या दिवशी रिपॉझिटरीची स्थिती विशिष्ट असते. त्यानंतर टेस्ट रनर बदलतो, एखाद्या पॅकेजचे नाव बदलते, एखादी सर्व्हिस डिलीट केली जाते, पण फाईलमध्ये मात्र जून महिन्याचीच माहिती राहते. कोणतीही बिल्ड स्टेप ती वाचत नसल्यामुळे कोणतीही त्रुटी (failure) येत नाही.

एजंट ती फाईल वाचतो आणि त्यावर विश्वास ठेवतो. हाच भाग तुम्हाला महागात पडतो. ज्या रिपॉझिटरीमध्ये AGENTS.md नसते, तिथे कोडिंग एजंट कृती करण्यापूर्वी आजूबाजूची स्थिती तपासून पाहतो. ज्या रिपॉझिटरीमध्ये चुकीची AGENTS.md असते, तिथे एजंट तपासणे थांबवतो, कारण त्याला आधीच उत्तर मिळालेले असते. तो तुमच्या फाईलमध्ये नमूद केलेली कमांड रन करतो, शेल Missing script: "test" असे उत्तर देते आणि मग एजंट अंदाज लावायला सुरुवात करतो. अनेकदा तो तुमच्या डॉक्युमेंटेशनने वचन दिलेल्या स्क्रिप्टला जोडण्यासाठी package.json मध्ये बदल करतो. जुनी फाईल शांतपणे निकामी ठरली नाही. तिने असा बदल घडवून आणला जो तुम्हाला नको होता.

dox हे यावर एक उत्तर आहे. हे एजंटसाठी लिहिलेल्या नियमांचा एक संच आहे, जो डॉक्युमेंटेशन अपडेट करणे हे काम पूर्ण करण्याचा एक भाग बनवतो. त्यामुळे ज्या कोडमुळे फाईल चुकीची ठरली, त्याच कमिटमध्ये फाईलमध्येही बदल होतो.

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

dox ही एकच Markdown फाईल आहे. हे रिपॉझिटरी agent0ai/dox आहे, ते MIT लायसन्स अंतर्गत उपलब्ध आहे आणि 11 ऑगस्ट 2026 पर्यंत संपूर्ण प्रकल्प 3906-बाइटची AGENTS.md, एक README, एक LICENSE आणि दोन प्रतिमांचा बनलेला आहे. यामध्ये इन्स्टॉल करण्यासाठी कोणतेही पॅकेज किंवा रनटाइम नाही.

हे महत्त्वाचे आहे, कारण 'generator' हा शब्द तुमच्या कोडचे विश्लेषण करणाऱ्या प्रोग्रामची आठवण करून देतो. येथे काहीही तुमच्या कोडचे विश्लेषण करत नाही. dox हा एक करार आहे जो तुमचा कोडिंग एजंट वाचतो: तुमचा एजंट हाच जनरेटर आहे आणि dox हा सूचनांचा संच आहे जो त्याला सांगतो की डॉक्युमेंटेशन कधी वाचायचे, ते कधी पुन्हा लिहायचे आणि प्रत्येक डॉक्युमेंटचे स्वरूप कसे असावे.

या फाईलमध्ये दहा विभाग आहेत आणि त्यापैकी दोन विभाग मुख्य काम करतात. "Read Before Editing" एजंटला रिपॉझिटरीच्या रूटपासून त्याने स्पर्श करायच्या प्रत्येक पाथपर्यंत जाण्यास सांगते आणि प्रत्येक मार्गावरील प्रत्येक AGENTS.md फाईल सध्याच्या सत्रात वाचण्यास सांगते, मेमरीवर अवलंबून न राहता. "Update After Editing" त्याला सांगते की प्रत्येक अर्थपूर्ण बदलासाठी DOX पास आवश्यक आहे, ज्याचा अर्थ असा की कार्य पूर्ण मानण्यापूर्वी डॉक्युमेंटेशन अपडेट करण्याची पायरी पूर्ण करणे आवश्यक आहे. जेव्हा उद्देश, रचना, वर्कफ्लो, परवानग्या किंवा वापरकर्त्याच्या पसंती बदलतात, तेव्हा हा पास जवळच्या मालकीच्या डॉक्युमेंटला अपडेट करतो.

उर्वरित भाग हा रचनेचा आहे. चाइल्ड AGENTS.md मध्ये विभागांचा डीफॉल्ट क्रम असतो: Purpose, Ownership, Local Contracts, Work Guidance, Verification आणि Child DOX Index. रूट फाईलमध्ये संपूर्ण प्रकल्पाचे नियम आणि टॉप-लेव्हल Child DOX Index असतो, ज्याद्वारे एजंट चाइल्ड डॉक्युमेंट्स शोधतो. "Closeout" ही एक चेकलिस्ट आहे जी एजंट कार्याच्या शेवटी पूर्ण करतो: बदललेल्या पाथची साखळी तपासा, जवळची मालकीची डॉक्युमेंट्स अपडेट करा, प्रत्येक प्रभावित इंडेक्स रिफ्रेश करा, विरोधाभास काढून टाका, विद्यमान पडताळणी (verification) चालवा आणि कोणती डॉक्युमेंट्स त्याने मुद्दाम बदलली नाहीत याचा अहवाल द्या.

dox ला main ऐवजी एका विशिष्ट commit वर पिन करा

या repository मध्ये कोणतेही tags किंवा releases नाहीत, त्यामुळे पिन करण्यासाठी कोणताही version number उपलब्ध नाही. त्याऐवजी commit पिन करा. सध्याची AGENTS.md ही 1 ऑगस्ट 2026 रोजीची commit f34ec7ad1055d3393887e5a2670e8cb7320c9165 आहे.

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 curl: (22) The requested URL returned error: 404 सह थांबते आणि कोणतीही सामग्री लिहित नाही, आणि त्यानंतर wc -c हे 0 प्रिंट करते. अर्धवट फाईल असणे हे फाईल नसण्यापेक्षा जास्त धोकादायक आहे, कारण एजंटला माहिती नसताना तो अर्ध्या कराराचे पालन करतो.

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 अशा repository साठी आहे जिथे अजून AGENTS.md नाही. जर तुमच्याकडे आधीच ती फाईल असेल, तर ती ओव्हरराईट करू नका. 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 मध्ये दिसली पाहिजे. ज्या child दस्तऐवजाचा उल्लेख कोणत्याही index मध्ये नाही, तो एजंटकडून राहून जाऊ शकतो, कारण एजंट ज्या मार्गावरून चालत आहे त्यावर थेट नसलेली दस्तऐवजे शोधण्यासाठी index चा वापर केला जातो.

dox काय पाहू शकते आणि काय तिला समजू शकत नाही

तुमचे ट्री (tree) तयार करणारा एजंट रिपॉझिटरी वाचतो, त्यामुळे रिपॉझिटरीमधील कोणतीही गोष्ट इन्व्हेंटरीमध्ये जाऊ शकते: डिरेक्टरी लेआउट, पॅकेज मॅनिफेस्ट आणि लॉकफाइल्स, package.json किंवा Makefile किंवा pyproject.toml मधील स्क्रिप्ट्स, CI वर्कफ्लो फाइल्स, Dockerfiles, एंट्री पॉइंट्स आणि जर तुमच्याकडे असेल तर CODEOWNERS. अशा प्रकारे तयार केलेली इन्व्हेंटरी खऱ्या अर्थाने स्वयंचलितपणे मेंटेन होते. जेव्हा एखादे पॅकेज हलवले जाते, तेव्हा पुढच्या वेळी एजंट ते दर्शवणारी ओळ आपोआप अपडेट करतो.

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

• एखादा नियम का अस्तित्वात आहे, जे एजंटला तो अनावश्यक गुंतागुंत समजून काढून टाकण्यापासून रोखते.
• दोन कार्यरत मार्गांपैकी (working paths) कोणता मार्ग समर्थित आहे आणि कोणता हटवण्याच्या प्रतीक्षेत आहे.
• रिपॉझिटरीच्या बाहेरील कोणतीही गोष्ट, जसे की स्टेजिंग एन्व्हायर्नमेंट किंवा एखादी डिपेंडन्सी दोन आवृत्त्या मागे का पिन केली आहे याचे कारण.
• पुढच्या आठवड्यात तुम्ही काय करणार आहात, जो सध्याची फाईल आणि उपयुक्त फाईल यातील मुख्य फरक आहे.

dox ला स्वतःबद्दल हे माहित आहे. तिचे स्वतःचे नियम असे सांगतात की, 'Work Guidance' ने प्रकल्पाचे सध्याचे मानक किंवा वापरकर्त्याच्या सूचना प्रतिबिंबित केल्या पाहिजेत आणि जर अजून काहीही नसेल तर तो विभाग रिकामा ठेवावा. 'Verification' ने अस्तित्वात असलेली चाचणी (check) प्रतिबिंबित केली पाहिजे, त्यामुळे रिपॉझिटरीमध्ये टेस्ट फ्रेमवर्क नसल्यास, जोपर्यंत ते उपलब्ध होत नाही तोपर्यंत तो विभाग रिकामा राहतो. एखादे मानक स्वतःहून तयार करणारी जनरेटेड फाईल ही रिकाम्या विभागापेक्षा वाईट असते, कारण एजंट नंतर त्या कल्पित मानकाची सक्ती करू लागतो.

मॅन्युअल हेतू (intent) जनरेट केलेल्या इन्व्हेंटरीमधून बाहेर ठेवा

ही ती त्रुटी आहे ज्यामुळे लोक जनरेट केलेल्या डॉक्युमेंटेशनचा वापर करणे सोडून देतात. तुम्ही एक परिच्छेद लिहिता की जॉब्स क्यू (jobs queue) सिंगल-कन्झ्युमरच राहिली पाहिजे. तीन आठवड्यांनंतर, एक ऑटोमेटेड पास फाईल पुन्हा लिहितो आणि तुमचा परिच्छेद गायब होतो. हा बदल चाळीस ओळींच्या डिफ (diff) मध्ये असतो, ज्यात प्रामुख्याने फाईलची नावे बदललेली असतात आणि कोणाचेही त्याकडे लक्ष जात नाही.

दोन यंत्रणा आहेत आणि तुम्हाला दोन्हीची गरज आहे.

प्रथम, टिकाऊ हेतू (durable intent) एका वेगळ्या फाईलमध्ये हलवा. डिझाइनचे निर्णय आणि त्यामागचे तर्क एजंटसाठी लिहिलेल्या DESIGN.md मध्ये असावेत आणि लोकांसाठी असलेल्या नोट्स अशा ठिकाणी असाव्यात जिथे तुम्ही HUMAN.md ला AGENTS.md पासून वेगळे करता. AGENTS.md मध्ये मग इन्व्हेंटरी आणि स्थानिक करार (local contracts) राहतात, जो कोड बदलल्यावर बदलला जाणारा नेमका भाग आहे.

दुसरे, AGENTS.md मध्ये राहणारा हेतू सुरक्षित करा. त्याला मार्कर्समध्ये गुंडाळा आणि तो ब्लॉक मानवी मालकीचा (human owned) आहे असे समजा:

## 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 -->

मार्कडाउन कमेंट्स पेजवर दिसत नाहीत, पण एजंट त्या वाचू शकतो. आता या ब्लॉकचे अस्तित्व तपासण्यायोग्य बनवा, जेणेकरून तो ब्लॉक पुसून टाकणारा पास मोठ्या आवाजात अपयशी ठरेल. प्रत्येक पुल रिक्वेस्टवर 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 एक्झिट कोड देतो. कोणताही आउटपुट येणे म्हणजे पासने मानवी मालकीचा मजकूर पुन्हा लिहिला आहे, त्यामुळे एखाद्या व्यक्तीने त्याला मंजुरी दिली पाहिजे किंवा तो बदल मागे (revert) घेतला पाहिजे. कोणालाही हे लक्षात ठेवण्याची गरज न पडता ही तपासणी कायम राहते.

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

दस्तऐवज रिफ्रेश करण्यासाठी सर्वात योग्य क्षण म्हणजे तो कमिट, ज्यामुळे दस्तऐवजात त्रुटी निर्माण होते. DOX पास त्याच पुल रिक्वेस्टमध्ये समाविष्ट करा ज्यामध्ये स्ट्रक्चरल बदल केले आहेत, जेणेकरून diff इतका लहान राहील की तो वाचणे शक्य होईल.

हे अनिवार्य करणारी एक ब्लॉकिंग चेक खालीलप्रमाणे आहे:

#!/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

तुमच्या रिपॉझिटरीनुसार पाथ (paths) ॲडजस्ट करा. याचा फायदा असा की, हे ब्रँचवरच अपयशी ठरते, जिथे दुरुस्ती करणे स्वस्त असते आणि ते अशा कारणास्तव अपयशी ठरते ज्यावर रिव्ह्यूअर कारवाई करू शकतो.

शेड्युल हा बॅकअप आहे, मुख्य यंत्रणा नाही. साप्ताहिक जॉब अशा गोष्टी पकडतो ज्या ब्रँचवर कोणाच्याही लक्षात आल्या नाहीत: उदा. रीबेसमुळे हलवलेल्या फाइल्स, मर्जमध्ये डिलीट झालेले पॅकेज, किंवा अस्तित्वात नसलेल्या डिरेक्टरीचा उल्लेख असलेला दस्तऐवज. हे एका लहान सर्व्हरवर चालवा, जो तुम्ही run a coding agent on a VPS साठी वापरू शकता आणि मुख्य ब्रँचवर पुश करण्याऐवजी पुल रिक्वेस्ट उघडण्यासाठी याचा वापर करा.

#!/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

ती कमेंट मुद्दाम एक प्लेसहोल्डर म्हणून ठेवली आहे. प्रत्येक एजंटचा स्वतःचा CLI (command line interface) आणि स्वतःचा non-interactive फ्लॅग असतो. वेब पेजवरून कॉपी केलेली कमांड, जी तुमच्या व्हर्जनशी जुळत नाही, ती cron मध्ये अपयशी ठरते आणि तिथे त्रुटी कोणालाही दिसत नाही. ती पूर्ण भरा आणि शेड्युल करण्यापूर्वी एकदा स्वतः स्क्रिप्ट रन करून पहा. || exit 0 देखील महत्त्वाचे आहे: जेव्हा ट्री आधीच अपडेटेड असते, तेव्हा git commit हे nothing to commit, working tree clean सह नॉन-झिरो एक्झिट कोड देते आणि set -e अंतर्गत ते यशस्वी रनला अपयश म्हणून दर्शवेल.

प्रत्येक पाससाठी टोकन्स खर्च होतात, कारण "Read Before Editing" मुळे एजंटला प्रत्येक टास्कवर संपूर्ण चेन वाचावी लागते. हा एक व्यवहार आहे आणि जर तुम्ही आधीच counting what your agent runs cost करत असाल, तर याकडे लक्ष देणे फायदेशीर ठरते.

Monorepos: अनेक कॉन्ट्रॅक्ट्स, एक इंडेक्स

एका रिपॉझिटरीमध्ये चाळीस पॅकेजेस असताना एकच मुख्य AGENTS.md फाईल ठेवल्यास, प्रत्येक बदलावेळी एक मोठा 'रीजनरेशन डिफ' तयार होतो जो कोणीही वाचत नाही. तसेच, त्यातील माहिती सध्याच्या एजंटच्या कार्याशी संबंधित नसते. याचे उत्तर 'Child DOX Index' मध्ये आहे: रूट फाईलमध्ये संपूर्ण रिपॉझिटरीसाठीचे नियम असतात आणि ती तिच्या अंतर्गत असलेल्या फाईल्सकडे निर्देश करते, तर प्रत्येक स्वतंत्र बाउंड्रीची स्वतःची फाईल असते. हे ट्री स्ट्रक्चर कसे तयार करावे आणि कोणत्या टूल्सद्वारे नेस्टेड फाईल्स वाचल्या जातात, हे nested AGENTS.md files for monorepos मध्ये दिले आहे.

dox मुळे रिव्ह्यू करण्याची पद्धत बदलते. जर एखादी पुल रिक्वेस्ट packages/api मध्ये बदल करत असेल, तर डॉक्युमेंटेशनमधील बदल फक्त packages/api मध्येच दिसले पाहिजेत, इतरत्र कुठेही नाही:

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

जर या कमांडद्वारे एका पॅकेजच्या बदलासाठी सहा फाईल्सची यादी येत असेल, तर ट्री स्ट्रक्चर चुकीचे आहे. एकतर बाउंड्रीज खूप मोठ्या आहेत, किंवा रूटमध्ये असायला हवा असा नियम प्रत्येक चाइल्ड फाईलमध्ये कॉपी केला गेला आहे. dox थेट उपाय सुचवते: व्यापक नियम पॅरेंट डॉक्समध्ये ठेवा आणि ठोस तपशील चाइल्ड डॉक्समध्ये ठेवा. नियमांची पुनरावृत्ती झाल्यामुळेच साध्या बदलावेळी सर्व काही पुन्हा लिहावे लागते. जर समान नियम खरोखरच वेगवेगळ्या रिपॉझिटरीजवर लागू होत असतील, तर तो एक वेगळा प्रश्न आहे आणि त्यासाठी sharing agent skills across repositories हे अधिक योग्य साधन आहे.

कोडप्रमाणे diff तपासा

तयार केलेले डॉक्युमेंटेशन diff न वाचता मंजूर करणे सोपे असते, आणि याच कारणामुळे चुकीची फाईल रिलीज (ship) होते. तयार केलेल्या कोडकडे ज्या संशयाने पाहता, त्याच नजरेने हे diff वाचा आणि खालील चार गोष्टी तपासा.

• फाईलमध्ये नमूद केलेली कमांड, जी तुम्ही मर्ज करण्यापूर्वी स्वतः रन करून पाहिली पाहिजे. चुकीच्या बिल्ड सूचना असणे ही सर्वात सामान्य त्रुटी आहे.
• एखादी डिलीट केलेली ओळ जिचा काही विशिष्ट हेतू होता. नवीन ओळी जोडणे सोपे असते, पण माहिती डिलीट केल्यामुळे नुकसान होऊ शकते.
• एखादा absolute path, hostname, internal URL किंवा क्रेडेंशियलसारखी दिसणारी कोणतीही गोष्ट.
• अस्तित्वात नसलेल्या गोष्टीची inventory entry, जी ls काही सेकंदात निकाली काढते.

त्यानंतर wc -l AGENTS.md वापरून फाईलचा आकार तपासा. जर root फाईल दोनशे ओळींपेक्षा मोठी असेल, तर ती विभागणे आवश्यक आहे. कारण या साखळीचे मुख्य मूल्य हेच आहे की, एजंटने सर्व काही वाचण्याऐवजी फक्त संबंधित छोटा भाग वाचावा.

जेव्हा सिस्टिममध्ये बिघाड होतो

पासने तुमचा इंटेंट ब्लॉक हटवला आहे. वरील diff चेक हटवलेल्या ओळी दर्शवते. git restore --source=origin/main AGENTS.md वापरून फाईल ब्रांच पॉईंटवरून रिस्टोर करा, त्यानंतर ज्या विभागांवर परिणाम होऊ शकतो त्यांची नावे देऊन अधिक मर्यादित सूचनांसह पास पुन्हा चालवा.

दोन शाखांचे (branches) एकाच वेळी पुनर्जनन (regeneration) झाले. तुम्हाला फाईलमध्ये CONFLICT (content): Merge conflict in AGENTS.md आणि कॉन्फ्लिक्ट मार्कर्स <<<<<<< HEAD मिळतील. मार्कर्समध्ये स्वतःहून बदल करू नका. ही फाईल जनरेट केलेली असल्याने, योग्य उपाय म्हणजे मर्ज केलेल्या ट्रीवर पुन्हा एकदा पास चालवणे.

एजंट फाईलकडे पूर्णपणे दुर्लक्ष करतो. तुमचे टूल प्रत्यक्षात कोणती फाईल वाचते आहे ते तपासा. जर ते वेगळी फाईल वाचत असेल, तर ln -s AGENTS.md CLAUDE.md वापरून त्याला त्याच मजकुराकडे निर्देशित करा आणि सिमलिन (symlink) कमिट करा, जेणेकरून दोन वेगवेगळ्या दस्तऐवजांऐवजी एकच स्रोत राहील. जर फाईलचे नाव आधीच बरोबर असेल आणि तरीही नियमांकडे दुर्लक्ष होत असेल, तर दस्तऐवज पुन्हा लिहिण्यापूर्वी कोडिंग एजंट तुमच्या सूचनांकडे का दुर्लक्ष करतात याचे निदान करा.

ट्रीमध्ये अशी मुले (children) तयार झाली आहेत ज्यांची नोंदणी केलेली नाही. find . -name AGENTS.md आउटपुटची तुलना मूळ दस्तऐवजांमधील इंडेक्स एन्ट्रींशी करा. ज्या मुलाचा इंडेक्समध्ये उल्लेख नाही, त्या मुलाकडे एजंट दुर्लक्ष करून पुढे जाऊ शकतो.

जेव्हा जनरेटरची गरज नसते

एक पॅकेज, एक टेस्ट कमांड आणि रिपॉझिटरीची माहिती असलेले दोन लोक असतील, तर वीस ओळी हाताने लिहा. वीस ओळींच्या AGENTS.md फाईलसाठी ट्री, इंडेक्स, CI चेक आणि साप्ताहिक जॉबची गरज नसते, कारण ती फाईल लवकर जुनी होत नाही. जेव्हा तुम्ही बिल्डमध्ये बदल करता, तेव्हा ती पुन्हा वाचा. हाच संपूर्ण मेंटेनन्स खर्च आहे आणि तो त्याभोवती उभारलेल्या यंत्रणेच्या खर्चापेक्षा कमी आहे.

जेव्हा रिपॉझिटरीच्या सीमा एका व्यक्तीच्या लक्षात राहण्यापलीकडे जातात, तेव्हाच dox वापरणे फायदेशीर ठरते: जसे की, वेगवेगळ्या नियमांची अनेक पॅकेजेस किंवा पार्श्वभूमी नसलेले नवीन योगदानकर्ते. याचे मूल्य जनरेट केलेल्या मजकुरात नसते. याचे खरे मूल्य हे आहे की, डॉक्युमेंटेशन अशी गोष्ट बनते ज्यावर पुल रिक्वेस्ट (pull request) अपयशी ठरू शकते. रिपॉझिटरीमधील कोणतीही फाईल अद्ययावत राहण्याचे हेच एकमेव कारण आहे.

FAQ

dox वापरण्यासाठी मला काही इन्स्टॉल करण्याची गरज आहे का?

नाही. dox ही एक Markdown फाईल आहे, जी MIT लायसन्स अंतर्गत उपलब्ध आहे. 11 ऑगस्ट 2026 पर्यंत, या रिपॉझिटरीमध्ये कोणतेही पॅकेज किंवा releases उपलब्ध नाहीत. तुम्ही त्यातील मजकूर तुमच्या प्रोजेक्टच्या AGENTS.md मध्ये कॉपी करा आणि तुमचा कोडिंग एजंट तिथून नियमांचे पालन करेल. तुम्ही कॉपी केलेल्या कमिटला पिन करा (लेखनाच्या वेळी f34ec7ad1055d3393887e5a2670e8cb7320c9165), आणि तुमच्या कमिट मेसेजमध्ये त्याचा उल्लेख करा, जेणेकरून नंतर तुमच्या लक्षात येईल की कोणत्या आवृत्तीच्या नियमांनुसार तुमची ट्री तयार केली गेली होती.

रीजनरेशनमुळे माझे स्वतः लिहिलेले नियम डिलीट होऊ नयेत म्हणून मी काय करावे?

तुमचा हेतू (intent) आणि इन्व्हेंटरी (inventory) वेगळे ठेवा. टिकाऊ तर्क (durable reasoning) एका स्वतंत्र दस्तऐवजात ठेवा आणि ज्या गोष्टी AGENTS.md मध्ये राहणे आवश्यक आहे, त्या एका चिन्हांकित ब्लॉकमध्ये ठेवा. त्यानंतर CI मध्ये त्या ब्लॉकची तपासणी करा: त्याला ब्रांचमधून आणि origin/main मधून sed वापरून एक्सट्रॅक्ट करा, diff वापरून त्या दोघांची तुलना करा आणि काही तफावत आढळल्यास बिल्ड फेल करा. मोठ्या डिफ (diff) मध्ये बदल दुर्लक्षित राहण्याऐवजी, एखादी व्यक्ती त्या बदलाला मंजुरी देईल किंवा तो बदल मागे घेईल.

AGENTS.md किती वेळा रीजनरेट करावे?

ज्या पुल रिक्वेस्टमुळे ते चुकीचे ठरते, त्याच वेळी ते रीजनरेट करावे. स्ट्रक्चरल बदल आणि त्याचे डॉक्युमेंटेशन एकाच डिफमध्ये असणे आवश्यक आहे, कारण त्याच वेळी कोणाकडेही दोन्ही गोष्टींचे पुनरावलोकन करण्यासाठी आवश्यक संदर्भ असतो. साप्ताहिक नियोजित पास हा ब्रांचमधून निसटलेल्या बदलांसाठी बॅकअप म्हणून असावा आणि त्याने main ब्रांचवर कमिट करण्याऐवजी पुल रिक्वेस्ट उघडली पाहिजे.

बिल्ड कमांड्स रूट AGENTS.md मध्ये असाव्यात की चाइल्ड फाईलमध्ये?

ज्या दस्तऐवजाशी त्या संबंधित आहेत, तिथेच त्या असाव्यात. संपूर्ण रिपॉझिटरीसाठीचे नियम आणि चाइल्ड इंडेक्स रूटवर असावेत. एखादी कमांड जी फक्त एका पॅकेजला लागू होते, ती त्या पॅकेजच्या AGENTS.md मध्ये असावी. dox अंतराच्या आधारावर संघर्ष सोडवते: जवळचा दस्तऐवज स्थानिक तपशीलांवर नियंत्रण ठेवतो आणि कोणताही चाइल्ड दस्तऐवज पॅरेंट नियमाला कमकुवत करू शकत नाही. प्रत्येक चाइल्डमध्ये तीच कमांड कॉपी केल्यामुळेच रूटीन पास संपूर्ण ट्री पुन्हा लिहितो.

लहान रिपॉझिटरीसाठी dox वापरणे फायदेशीर आहे का?

सहसा नाही. एक टेस्ट कमांड आणि वीस ओळींचे AGENTS.md असलेले एक पॅकेज हळूहळू जुने होते, आणि ते तुमच्या लक्षात आल्यावर तुम्ही एका मिनिटात दुरुस्त करू शकता. जेव्हा रिपॉझिटरीमध्ये वेगवेगळ्या नियमांच्या अनेक सीमा असतात किंवा योगदानकर्त्यांकडे आवश्यक पार्श्वभूमी नसते, तेव्हा dox त्याच्या खर्चाचे सार्थक करते, कारण अशा वेळी दस्तऐवजांची साखळी असे काम करते जे कोणतीही एक व्यक्ती करत नसते.