AGENTS.md को ऑटोमैटिकली अपडेट कैसे करें

तीन सप्ताह बाद आपकी AGENTS.md गलत क्यों हो जाती है

एक AGENTS.md फाइल पुरानी हो जाती है क्योंकि इसका कोड से कोई संबंध नहीं होता। आप इसे एक बार, अपने हाथों से, उस दिन लिखते हैं जिस दिन रिपॉजिटरी एक निश्चित स्थिति में होती है। फिर टेस्ट रनर बदल जाता है, कोई पैकेज रीनेम हो जाता है, कोई सर्विस डिलीट हो जाती है, लेकिन फाइल अभी भी जून की स्थिति का वर्णन कर रही होती है। कोई भी चीज फेल नहीं होती, क्योंकि कोई भी बिल्ड स्टेप इसे पढ़ता नहीं है।

एजेंट इसे पढ़ता है और इस पर विश्वास कर लेता है। यही वह हिस्सा है जो आपको नुकसान पहुँचाता है। जिस रिपॉजिटरी में 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 एक ऐसा अनुबंध (contract) है जिसे आपका कोडिंग एजेंट पढ़ता है: आपका एजेंट ही जनरेटर है, और dox वह निर्देश सेट है जो उसे बताता है कि कब डॉक्स (docs) को पढ़ना है, कब उन्हें फिर से लिखना है, और प्रत्येक दस्तावेज़ का स्वरूप कैसा होना चाहिए।

फाइल में दस सेक्शन हैं और उनमें से दो मुख्य काम करते हैं। "Read Before Editing" एजेंट को निर्देश देता है कि वह रिपॉजिटरी रूट से उन सभी पाथ (path) तक जाए जिन्हें वह छूने की योजना बना रहा है, और वर्तमान सत्र में, मेमोरी पर निर्भर हुए बिना, प्रत्येक रूट पर मौजूद हर AGENTS.md को पढ़े। "Update After Editing" इसे बताता है कि हर सार्थक बदलाव के लिए एक DOX पास की आवश्यकता होती है, जिसका अर्थ है कि कार्य को पूरा मानने से पहले एक डॉक्यूमेंटेशन अपडेट स्टेप चलाया जाना चाहिए। जब उद्देश्य, संरचना, वर्कफ़्लो, अनुमतियाँ (permissions) या उपयोगकर्ता की प्राथमिकताएँ बदलती हैं, तो यह पास निकटतम ओनिंग डॉक्यूमेंट को अपडेट करता है।

बाकी हिस्सा केवल स्वरूप (shape) है। एक चाइल्ड AGENTS.md में सेक्शन का एक डिफ़ॉल्ट क्रम होता है: उद्देश्य (Purpose), स्वामित्व (Ownership), स्थानीय अनुबंध (Local Contracts), कार्य मार्गदर्शन (Work Guidance), सत्यापन (Verification), और चाइल्ड DOX इंडेक्स। रूट फाइल में प्रोजेक्ट-व्यापी नियम और टॉप-लेवल चाइल्ड DOX इंडेक्स होता है, जिसके माध्यम से एजेंट चाइल्ड डॉक्यूमेंट्स को खोजता है। "Closeout" वह चेकलिस्ट है जिसे एजेंट कार्य के अंत में चलाता है: चेन के विरुद्ध बदले गए पाथ को फिर से चेक करना, निकटतम ओनिंग डॉक्स को अपडेट करना, प्रत्येक प्रभावित इंडेक्स को रिफ्रेश करना, विरोधाभासों को हटाना, मौजूदा सत्यापन चलाना, और यह रिपोर्ट करना कि उसने किन डॉक्स को जानबूझकर नहीं बदला है।

Dox को main के बजाय एक commit पर पिन करें

Repository में कोई tags या releases नहीं हैं, इसलिए पिन करने के लिए कोई version number उपलब्ध नहीं है। इसके बजाय commit को पिन करें। वर्तमान 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 को 3906 प्रिंट करना चाहिए। यदि कोई अलग संख्या आती है, तो इसका मतलब है कि आपने वह file fetch नहीं की है जिसका यह guide वर्णन करती है, इसलिए उस पर भरोसा करने से पहले इसे पढ़ें। यदि आप commit hash गलत टाइप करते हैं, तो -f, curl को curl: (22) The requested URL returned error: 404 के साथ रोक देता है और कोई content नहीं लिखता है, और wc -c तब 0 प्रिंट करता है। एक अधूरी file, 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 उस repository के लिए है जिसमें अभी तक AGENTS.md नहीं है। यदि आपके पास पहले से ही एक file है, तो उसे overwrite न करें। Dox sections को अपनी मौजूदा सामग्री के ऊपर रखें, अपने नियमों को नीचे रखें, और परिणाम को एक बार ऊपर से नीचे तक पढ़ें। दो दस्तावेज़ जो एक-दूसरे का खंडन करते हैं, वे ऐसे agent को जन्म देते हैं जो उस पंक्ति का पालन करता है जिसे उसने अंत में पढ़ा है।

फिर, repository के भीतर अपने agent से पहला pass करने के लिए कहें। README में सटीक wording दी गई है:

Initialize DOX tree for this project now.

यह child AGENTS.md files और उन्हें point करने वाले indexes बनाता है। उस पर भरोसा करने से पहले जाँचें कि उसने क्या किया है:

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

उस find output की प्रत्येक file को उसके ऊपर कहीं न कहीं एक Child DOX Index में दिखाई देना चाहिए। एक child दस्तावेज़ जिसका कोई index उल्लेख नहीं करता है, वह ऐसा दस्तावेज़ है जिसे agent छोड़ सकता है, क्योंकि index ही वह माध्यम है जिससे वह उन दस्तावेज़ों को ढूँढता है जो सीधे उस path पर नहीं हैं जिस पर वह चल रहा है।

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 move होता है, तो अगला pass उस line को move कर देता है जो उसका वर्णन करती है।

नीचे दी गई हर बात आपको बतानी होगी, क्योंकि यह पढ़ने के लिए repository में मौजूद नहीं है:

• कोई rule क्यों मौजूद है, जो agent को इसे अनावश्यक जटिलता मानकर हटाने से रोकता है
• दो working paths में से कौन सा supported है, और कौन सा delete होने की प्रतीक्षा कर रहा है
• repository के बाहर की कोई भी चीज़, जैसे staging environment या वह कारण कि क्यों किसी dependency को दो version पीछे pin किया गया है
• आप अगले सप्ताह क्या करने की योजना बना रहे हैं, जो कि एक current file और एक useful file के बीच का अंतर है

dox अपने बारे में यह जानता है। इसके अपने rules कहते हैं कि Work Guidance को project के वर्तमान मानकों या user के निर्देशों को दर्शाना चाहिए, और यदि अभी तक कोई नहीं है तो आप उस section को खाली छोड़ दें। Verification को किसी मौजूदा check को दर्शाना चाहिए, इसलिए repo में test framework न होने पर वह section तब तक खाली रहता है जब तक कि कोई framework न हो। एक मानक बनाने वाली generated file, खाली section से भी बदतर है, क्योंकि agent फिर उस मनगढ़ंत मानक को लागू करने लगेगा।

हाथ से लिखे गए आशय को जनरेट की गई इन्वेंट्री से बाहर रखें

यह वह विफलता है जिसके कारण लोग जनरेट किए गए दस्तावेज़ों का उपयोग करना छोड़ देते हैं। आप एक पैराग्राफ लिखते हैं जिसमें बताया गया है कि jobs queue को single consumer ही रहना चाहिए। तीन सप्ताह बाद, एक पास (pass) फाइल को फिर से लिखता है और आपका पैराग्राफ गायब हो जाता है, जो चालीस लाइनों के उस diff के भीतर दब जाता है जिसमें मुख्य रूप से फाइल के नाम बदले गए हैं, और किसी का ध्यान इस पर नहीं जाता।

दो तंत्र हैं, और आप दोनों चाहते हैं।

पहला, स्थायी आशय (durable intent) को एक अलग फाइल में ले जाएं। डिज़ाइन संबंधी निर्णय और उनके पीछे का तर्क agent के लिए लिखे गए DESIGN.md में होना चाहिए, और जो नोट्स लोगों के लिए हैं, उन्हें वहां होना चाहिए जहां आप HUMAN.md को AGENTS.md से अलग करते हैं। AGENTS.md में फिर इन्वेंट्री और local contracts होते हैं, जो बिल्कुल वही हिस्सा है जिसे कोड बदलने पर बदलना चाहिए।

दूसरा, उस आशय को सुरक्षित (fence) करें जिसे 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 -->

Markdown टिप्पणियाँ पेज पर रेंडर नहीं होती हैं, और agent अभी भी उन्हें पढ़ता है। अब ब्लॉक के अस्तित्व की जांच को संभव बनाएं, ताकि इसे हटाने वाला पास जोर से विफल (fail loudly) हो। इसे हर 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 के साथ exit होता है जब ब्लॉक को नहीं छेड़ा जाता है। किसी भी आउटपुट का मतलब है कि पास ने मानव-स्वामित्व वाले टेक्स्ट को फिर से लिखा है, इसलिए कोई व्यक्ति इसे approve करे या 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) को अपनी रिपॉजिटरी के अनुसार एडजस्ट करें। इसका लाभ यह है कि यह ब्रांच पर ही फेल हो जाता है, जहाँ सुधार करना सस्ता है, और यह ऐसे कारण से फेल होता है जिस पर रिव्युअर कार्रवाई कर सकता है।

शेड्यूल केवल एक बैकअप है, मुख्य मैकेनिज्म नहीं। एक साप्ताहिक जॉब उन चीजों को पकड़ती है जिन्हें किसी ने ब्रांच पर नोटिस नहीं किया: रीबेस (rebase) द्वारा मूव की गई फाइलें, मर्ज में डिलीट हुआ पैकेज, या ऐसा दस्तावेज़ जो ऐसी डायरेक्टरी का नाम ले रहा है जो अब मौजूद नहीं है। इसे एक छोटे बॉक्स पर चलाएं, उसी पर जिसे आप VPS पर कोडिंग एजेंट चलाने के लिए उपयोग कर सकते हैं, और इसे main पर पुश करने के बजाय एक पुल रिक्वेस्ट खोलने के लिए कहें।

#!/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 (कमांड लाइन इंटरफेस) और अपना नॉन-इंटरैक्टिव फ्लैग होता है, और वेब पेज से कॉपी की गई कमांड जो आपके वर्ज़न से मेल नहीं खाती, वह cron के अंदर फेल हो जाती है जहाँ किसी को एरर नहीं दिखता। इसे भरें और शेड्यूल करने से पहले स्क्रिप्ट को एक बार मैन्युअल रूप से चलाएं। || exit 0 भी मायने रखता है: git commit तब nothing to commit, working tree clean के साथ नॉन-जीरो एग्जिट करता है जब ट्री पहले से ही करंट होता है, और set -e के तहत यह एक सफल रन को फेलियर के रूप में रिपोर्ट करेगा।

हर पास में टोकन खर्च होते हैं, क्योंकि "Read Before Editing" एजेंट को हर टास्क पर पूरी चेन पढ़ने के लिए मजबूर करता है। यह एक समझौता है, और यदि आप पहले से ही अपने एजेंट के रन की लागत गिन रहे हैं तो इस पर नज़र रखना उचित है।

Monorepos: कई कॉन्ट्रैक्ट्स, एक इंडेक्स

एक रिपॉजिटरी जिसमें चालीस पैकेज हों, उसमें एक ही रूट AGENTS.md फाइल रखने से ऐसा रीजेनरेशन डिफ (diff) बनता है जिसे कोई नहीं पढ़ता, और एक ऐसा डॉक्यूमेंट तैयार होता है जो उस समय एजेंट द्वारा किए जा रहे काम के लिए अधिकतर अप्रासंगिक होता है। Dox का समाधान Child DOX Index है: रूट में रिपो-वाइड नियम होते हैं और यह अपने चाइल्ड्स की ओर इशारा करता है, और प्रत्येक ड्यूरेबल बाउंड्री की अपनी फाइल होती है। उस ट्री को कैसे व्यवस्थित करें, और कौन से टूल्स नेस्टेड फाइल्स को पढ़ते हैं, यह monorepos के लिए नेस्टेड AGENTS.md फाइल्स में कवर किया गया है।

Dox जिस चीज को बदलता है वह है रिव्यू सरफेस। packages/api को प्रभावित करने वाले पुल रिक्वेस्ट से केवल packages/api के अंदर ही डॉक्यूमेंटेशन डिफ (diff) उत्पन्न होना चाहिए, कहीं और नहीं:

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

यदि वह कमांड एक-पैकेज वाले बदलाव के लिए छह फाइल्स की सूची दिखाती है, तो ट्री गलत है। या तो बाउंड्रीज बहुत बड़ी हैं, या फिर कोई ऐसा नियम जो रूट में होना चाहिए था, उसे हर चाइल्ड में कॉपी कर दिया गया है। Dox इसका समाधान सीधे बताता है: व्यापक नियम पैरेंट डॉक्स में रखें, और ठोस विवरण चाइल्ड डॉक्स में। डुप्लिकेट नियम ही वह कारण हैं जिनसे एक रूटीन पास सब कुछ फिर से लिख देता है। यदि वही नियम वास्तव में अलग-अलग रिपॉजिटरीज पर लागू होते हैं, तो यह एक अलग समस्या है, और रिपॉजिटरीज के बीच एजेंट स्किल्स साझा करना इसके लिए बेहतर टूल है।

कोड की तरह diff की समीक्षा करें

Generated documentation के diff को बिना पढ़े approve करना आसान होता है, और इसी कारण गलत फाइल release हो जाती है। इसे उसी संदेह के साथ पढ़ें जैसे आप generated code को पढ़ते हैं, और इन चार चीजों पर ध्यान दें:

• फाइल में दिया गया कोई भी command, जिसे merge करने से पहले आपको स्वयं चलाकर देखना चाहिए। मनगढ़ंत build instructions विफलता का सबसे सामान्य कारण हैं।
• कोई हटाई गई लाइन जिसमें कोई उद्देश्य (intent) निहित था। नई चीजें जोड़ना आसान है, लेकिन हटाने से ही जानकारी का नुकसान होता है।
• कोई absolute path, hostname, internal URL, या credential जैसा दिखने वाला कोई भी विवरण।
• किसी ऐसी चीज की inventory entry जो अब मौजूद नहीं है, जिसे ls एक सेकंड में ठीक कर देता है।

इसके बाद wc -l AGENTS.md का उपयोग करके आकार की जाँच करें। यदि root फाइल दो सौ लाइनों से अधिक की है, तो उसे विभाजित करना आवश्यक है, क्योंकि इस पूरी प्रक्रिया का मुख्य लाभ यह है कि agent सब कुछ पढ़ने के बजाय केवल छोटा और प्रासंगिक हिस्सा ही पढ़ता है।

जब यह काम करना बंद कर दे

पास ने आपके intent block को हटा दिया है। ऊपर दिया गया diff चेक हटाई गई लाइनों को प्रिंट करता है। git restore --source=origin/main AGENTS.md का उपयोग करके फाइल को ब्रांच पॉइंट से रिस्टोर करें, फिर उन सेक्शन का नाम बताते हुए पास को दोबारा चलाएं जिन्हें यह प्रभावित कर सकता है।

दोनों ब्रांच दोबारा जनरेट हो गई हैं। आपको फाइल के अंदर CONFLICT (content): Merge conflict in AGENTS.md और कॉन्फ्लिक्ट मार्कर्स <<<<<<< HEAD मिलते हैं। मार्कर्स को हाथ से एडिट न करें। फाइल जनरेट की गई है, इसलिए सही समाधान मर्ज की गई ट्री पर एक नया पास चलाना है।

एजेंट फाइल को पूरी तरह से अनदेखा कर देता है। जांचें कि आपका टूल वास्तव में किस फाइलनाम को पढ़ता है। यदि यह किसी अलग फाइल को पढ़ता है, तो उसे ln -s AGENTS.md CLAUDE.md के साथ उसी कंटेंट पर पॉइंट करें और सिमलिंक (symlink) को कमिट करें, ताकि आपके पास दो अलग-अलग डॉक्यूमेंट्स के बजाय एक ही सोर्स रहे जो आपस में अलग न हों।

ट्री में ऐसे चाइल्ड जुड़ गए हैं जिन्हें किसी ने इंडेक्स नहीं किया है। find . -name AGENTS.md आउटपुट की तुलना पैरेंट डॉक्यूमेंट्स में मौजूद इंडेक्स एंट्रीज से करें। जिस चाइल्ड का उल्लेख किसी इंडेक्स में नहीं है, एजेंट उसे अनदेखा कर आगे बढ़ सकता है।

जब जनरेटर का उपयोग अनावश्यक हो

एक पैकेज, एक टेस्ट कमांड, और दो लोग जो रिपॉजिटरी को अच्छी तरह जानते हैं: ऐसी स्थिति में बीस लाइनें हाथ से लिखना बेहतर है। बीस लाइन की AGENTS.md फाइल इतनी जल्दी पुरानी नहीं होती कि उसके लिए ट्री, इंडेक्स, CI चेक और साप्ताहिक जॉब की आवश्यकता पड़े। जब आप बिल्ड में बदलाव करें, तो इसे दोबारा पढ़ लें। यही इसका पूरा रखरखाव खर्च है, और यह इसके इर्द-गिर्द बनाए गए तंत्र की लागत से कम है।

dox का उपयोग तब सार्थक होता है जब रिपॉजिटरी की सीमाएं इतनी विस्तृत हों कि कोई एक व्यक्ति उन्हें पूरी तरह याद न रख सके: जैसे अलग-अलग नियमों वाले कई पैकेज, या ऐसे योगदानकर्ता जो बिना पूर्व जानकारी के जुड़ते हैं। इसका मूल्य जनरेट किए गए टेक्स्ट में नहीं है। इसका असली मूल्य यह है कि डॉक्यूमेंटेशन एक ऐसी चीज बन जाती है जिस पर पुल रिक्वेस्ट फेल हो सकती है, और यही एकमात्र कारण है कि रिपॉजिटरी की कोई भी फाइल अपडेटेड रहती है।

FAQ

क्या dox का उपयोग करने के लिए मुझे कुछ भी install करने की आवश्यकता है?

नहीं। dox एक Markdown फ़ाइल है, जो MIT लाइसेंस के अंतर्गत आती है, और 11 August 2026 तक रिपॉजिटरी कोई पैकेज या releases शिप नहीं करती है। आप इसकी सामग्री को अपने प्रोजेक्ट की AGENTS.md फ़ाइल में कॉपी करते हैं और आपका कोडिंग एजेंट वहाँ से नियमों का पालन करता है। जिस commit को आपने कॉपी किया है, उसे पिन करें (लिखते समय f34ec7ad1055d3393887e5a2670e8cb7320c9165), और अपने commit संदेश में उसका नाम लिखें ताकि आप बाद में बता सकें कि आपका ट्री किस वर्ज़न के नियमों के तहत बनाया गया था।

मैं यह कैसे सुनिश्चित करूँ कि regeneration मेरे द्वारा लिखे गए नियमों को न हटा दे?

Intent और inventory को अलग रखें। स्थायी तर्क (durable reasoning) एक अलग दस्तावेज़ में रखें, और जो कुछ भी AGENTS.md के अंदर रहना चाहिए, उसे एक चिह्नित ब्लॉक (marked block) के अंदर रखें। फिर CI में उस ब्लॉक की जाँच करें: इसे ब्रांच से और origin/main से sed के साथ निकालें, diff के साथ दोनों की तुलना करें, और किसी भी अंतर पर बिल्ड को विफल (fail) कर दें। इसके बाद कोई व्यक्ति बदलाव को मंजूरी देता है या उसे वापस लेता है, बजाय इसके कि वह एक बड़े diff के अंदर बिना किसी के ध्यान में आए पास हो जाए।

मुझे AGENTS.md को कितनी बार regenerate करना चाहिए?

उस pull request पर जो इसे गलत बनाता है। एक संरचनात्मक बदलाव और उसका दस्तावेज़ीकरण एक ही diff में होने चाहिए, क्योंकि केवल उसी समय किसी के पास दोनों की समीक्षा करने का संदर्भ (context) होता है। साप्ताहिक निर्धारित पास (weekly scheduled pass) उस drift के लिए बैकअप है जो ब्रांच से छूट गया हो, और इसे main ब्रांच में commit करने के बजाय एक pull request खोलना चाहिए।

क्या बिल्ड कमांड्स को रूट AGENTS.md में होना चाहिए या चाइल्ड में?

उस निकटतम दस्तावेज़ में जो उनका स्वामी है। रिपॉजिटरी-व्यापी नियम और चाइल्ड इंडेक्स रूट पर रहते हैं। एक कमांड जो किसी एक पैकेज पर लागू होती है, वह उस पैकेज की AGENTS.md में रहती है। dox दूरी के आधार पर संघर्षों (conflicts) को हल करता है: निकटतम दस्तावेज़ स्थानीय विवरणों को नियंत्रित करता है, और कोई भी चाइल्ड किसी पैरेंट नियम को कमजोर नहीं कर सकता है। हर चाइल्ड में एक ही कमांड को कॉपी करना ही वह कारण है जिससे एक रूटीन पास पूरे ट्री को फिर से लिखता है।

क्या एक छोटी रिपॉजिटरी के लिए dox का उपयोग करना सार्थक है?

आमतौर पर नहीं। एक टेस्ट कमांड और बीस-लाइन वाली AGENTS.md के साथ एक पैकेज धीरे-धीरे खराब होता है, और आप इसे ध्यान में आने के बाद एक मिनट में ठीक कर सकते हैं। dox अपनी लागत तब वसूल करता है जब रिपॉजिटरी में अलग-अलग नियमों वाली कई सीमाएँ हों, या ऐसे योगदानकर्ता हों जिनके पास पृष्ठभूमि की जानकारी न हो, क्योंकि तब दस्तावेज़ों की श्रृंखला वह काम कर रही होती है जो कोई एक व्यक्ति नहीं कर रहा है।