dox سے AGENTS.md خودکار طور پر اپ ڈیٹ کریں

تین ہفتے بعد آپ کی AGENTS.md غلط کیوں ہو جاتی ہے

AGENTS.md فائل اس لیے پرانی ہو جاتی ہے کہ اسے code کے ساتھ مربوط نہیں کیا جاتا۔ آپ اسے ایک مرتبہ، دستی طور پر، اس دن لکھتے ہیں جب repository کی حالت مخصوص ہوتی ہے۔ پھر test runner تبدیل ہو جاتا ہے، کسی package کا نام بدل دیا جاتا ہے، کوئی service حذف ہو جاتی ہے، لیکن فائل اب بھی جون کی حالت بیان کر رہی ہوتی ہے۔ کچھ ناکام نہیں ہوتا، کیونکہ build کا کوئی مرحلہ اسے پڑھتا ہی نہیں۔

agent اسے پڑھتا ہے اور اس پر یقین کر لیتا ہے۔ اصل نقصان یہی ہے۔ AGENTS.md کے بغیر repository coding agent کو کارروائی سے پہلے جائزہ لینے پر مجبور کرتی ہے۔ غلط AGENTS.md والی repository اسے جائزہ لینے سے روک دیتی ہے، کیونکہ اسے پہلے ہی ایک جواب معلوم ہوتا ہے۔ وہ آپ کی فائل میں دیا گیا command چلاتا ہے، shell Missing script: "test" کا جواب دیتا ہے، اور اب agent اندازے لگانا شروع کر دیتا ہے۔ اکثر وہ package.json میں ترمیم کرکے وہ script شامل کر دیتا ہے جس کا وعدہ آپ کی documentation نے کیا تھا۔ پرانی فائل خاموشی سے ناکام نہیں ہوئی۔ اس نے ایسی ترمیم کروا دی جو آپ نہیں چاہتے تھے۔

dox اس مسئلے کا ایک حل ہے۔ یہ agent کے لیے لکھی گئی rules کا مجموعہ ہے، جو documentation کو update کرنا کام مکمل کرنے کا حصہ بناتا ہے۔ اس طرح فائل اسی commit میں تبدیل ہوتی ہے جس میں وہ code شامل ہوتا ہے جس نے اسے غلط بنایا۔

dox کیا ہے، اور کیا نہیں ہے

dox ایک واحد Markdown فائل ہے۔ repository agent0ai/dox ہے، اس کا لائسنس MIT ہے، اور 11 August 2026 تک پورا project ایک 3906-byte AGENTS.md، ایک README، ایک LICENSE اور دو images پر مشتمل ہے۔ install کرنے کے لیے کوئی package نہیں ہے اور نہ ہی کوئی runtime ہے۔

یہ بات اہم ہے، کیونکہ generator کا لفظ ایسا program ظاہر کرتا ہے جو آپ کے code کو parse کرتا ہو۔ آپ کے code کو کچھ بھی parse نہیں کرتا۔ dox ایک contract ہے جسے آپ کا coding agent پڑھتا ہے: generator آپ کا agent ہے، جبکہ dox وہ instruction set ہے جو اسے بتاتا ہے کہ docs کب پڑھنے ہیں، انہیں کب دوبارہ لکھنا ہے، اور ہر document کی structure کیا ہونی چاہیے۔

فائل میں دس sections ہیں، اور ان میں سے دو اصل کام کرتے ہیں۔ "Read Before Editing" agent کو ہدایت دیتا ہے کہ repository root سے شروع کرکے ہر اس path تک جائے جسے وہ تبدیل کرنے کا ارادہ رکھتا ہے، اور موجودہ session میں ہر route پر آنے والی تمام AGENTS.md فائلیں پڑھے، memory پر انحصار نہ کرے۔ "Update After Editing" اسے بتاتا ہے کہ ہر معنی خیز تبدیلی کے لیے DOX pass ضروری ہے۔ اس سے مراد documentation update step ہے، جو task کو مکمل شمار کرنے سے پہلے چلایا جاتا ہے۔ یہ pass اس وقت قریب ترین owning document کو update کرتا ہے جب purpose، structure، workflow، permissions یا user preferences تبدیل ہوئی ہوں۔

باقی حصہ structure سے متعلق ہے۔ child AGENTS.md میں sections کی default ترتیب یہ ہے: Purpose، Ownership، Local Contracts، Work Guidance، Verification، اور Child DOX Index۔ root file میں project-wide rules کے ساتھ top-level Child DOX Index ہوتا ہے۔ اسی کے ذریعے agent child documents دریافت کرتا ہے۔ "Closeout" وہ checklist ہے جسے agent task کے اختتام پر چلاتا ہے: تبدیل شدہ paths کو chain کے مقابلے میں دوبارہ چیک کرنا، nearest owning docs کو update کرنا، ہر متاثرہ index کو refresh کرنا، متضاد ہدایات حذف کرنا، موجودہ verification چلانا، اور یہ report کرنا کہ اس نے کن docs کو جان بوجھ کر تبدیل نہیں کیا۔

DOX کو main کے بجائے ایک commit تک محدود کریں

Repository میں کوئی tags یا releases موجود نہیں، اس لیے pin کرنے کے لیے version number نہیں ہے۔ اس کے بجائے commit کو pin کریں۔ موجودہ AGENTS.md، 1 August 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 دکھانا چاہیے۔ مختلف number کا مطلب ہے کہ آپ نے وہ 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 موجود نہیں۔ اگر آپ کے پاس پہلے سے ایک موجود ہے تو اسے overwrite نہ کریں۔ dox sections کو اپنے موجودہ content کے اوپر رکھیں، اپنے rules نیچے برقرار رکھیں، اور نتیجہ شروع سے آخر تک ایک بار پڑھیں۔ ایک دوسرے سے متصادم دو documents ایسا agent پیدا کرتے ہیں جو آخر میں پڑھی گئی line پر عمل کرتا ہے۔

اس کے بعد 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 نظرانداز کر سکتا ہے، کیونکہ index ہی وہ طریقہ ہے جس سے agent ان documents کو تلاش کرتا ہے جو اس 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 منتقل ہوتا ہے تو اگلا pass اس کی وضاحت کرنے والی سطر بھی منتقل کر دیتا ہے۔

ذیل کی ہر بات آپ کو خود درج کرنی ہوگی، کیونکہ یہ repository میں موجود نہیں ہوتی کہ اسے پڑھا جا سکے:

• کوئی rule کیوں موجود ہے؛ یہی بات agent کو اسے غیر ضروری پیچیدگی سمجھ کر حذف کرنے سے روکتی ہے
• دو کام کرنے والے طریقوں میں سے کون سا supported ہے، اور کون سا حذف کیے جانے کا منتظر ہے
• repository سے باہر کی کوئی بھی چیز، مثلاً staging environment یا یہ وجہ کہ کسی dependency کو دو versions پیچھے کیوں pin کیا گیا ہے
• آپ اگلے ہفتے کیا کرنے کا ارادہ رکھتے ہیں؛ یہی current file اور useful file کے درمیان فرق ہے

dox اپنے بارے میں یہ بات جانتا ہے۔ اس کے اپنے rules کے مطابق Work Guidance کو project کے موجودہ standards یا user کی ہدایات کی عکاسی کرنی چاہیے، اور اگر ابھی کوئی standards موجود نہ ہوں تو section خالی چھوڑنا چاہیے۔ Verification کو کسی موجودہ check کی عکاسی کرنی چاہیے؛ اس لیے repository میں test framework نہ ہو تو یہ section اس وقت تک خالی رہتا ہے جب تک ایسا framework موجود نہ ہو۔ ایسا generated file جو خود سے کوئی standard گھڑ لے، خالی section سے بدتر ہے، کیونکہ agent پھر اس گھڑے ہوئے standard کو نافذ کرے گا۔

تخلیق کردہ inventory میں ہاتھ سے لکھی گئی نیت شامل نہ ہونے دیں

یہ وہ خرابی ہے جس کی وجہ سے لوگ تخلیق کردہ دستاویزات سے دستبردار ہو جاتے ہیں۔ آپ ایک پیراگراف لکھتے ہیں جس میں وضاحت ہوتی ہے کہ jobs queue میں صرف ایک consumer رہنا چاہیے۔ تین ہفتے بعد ایک pass فائل کو دوبارہ لکھتا ہے، اور آپ کا پیراگراف چالیس سطروں کے ایسے diff کے اندر غائب ہو جاتا ہے جس میں زیادہ تر file names کی ترتیب بدلی ہوتی ہے۔ کسی کو اس کا پتا نہیں چلتا۔

آپ کو 2 mechanisms درکار ہیں، اور دونوں استعمال کریں۔

پہلے، مستقل نیت کو ایک مختلف فائل میں منتقل کریں۔ Design decisions اور ان کے پیچھے موجود reasoning agent کے لیے لکھی گئی DESIGN.md میں ہونی چاہیے، جبکہ لوگوں کے لیے موجود notes وہاں رکھیں جہاں آپ AGENTS.md سے HUMAN.md الگ کرتے ہیں۔ AGENTS.md میں پھر inventory اور local contracts رہیں۔ یہی وہ حصہ ہے جو code تبدیل ہونے پر تبدیل ہونا چاہیے۔

دوسرے، اس نیت کو fence کریں جسے AGENTS.md کے اندر رہنا ضروری ہے۔ اسے markers میں لپیٹیں اور block کو 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 comments صفحے پر render نہیں ہوتے، لیکن agent انہیں پڑھ لیتا ہے۔ اب block کے برقرار رہنے کی جانچ ممکن بنائیں، تاکہ اسے حذف کرنے والا pass واضح failure پیدا کرے۔ اسے ہر 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 اس وقت کچھ بھی print نہیں کرتا اور 0 کے ساتھ exit کرتا ہے جب block میں کوئی تبدیلی نہ ہوئی ہو۔ کوئی بھی output اس بات کی نشاندہی کرتا ہے کہ pass نے human-owned text کو دوبارہ لکھا ہے۔ اس صورت میں کوئی شخص اسے approve کرے یا revert کر دے۔ یہ check اس بات کے بغیر بھی قائم رہتا ہے کہ کسی کو اسے یاد رکھنا پڑے۔

pull request پر دوبارہ generate کریں، timer پر نہیں

کسی document کو refresh کرنے کا بہترین وقت وہ commit ہے جو اسے غلط بناتا ہے۔ DOX pass کو structural change والی اسی 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

paths کو اپنی repository کے مطابق تبدیل کریں۔ فائدہ یہ ہے کہ check branch پر ہی fail ہو جاتا ہے، جہاں fix کرنا آسان ہوتا ہے، اور failure کی وجہ ایسی ہوتی ہے جس پر reviewer کارروائی کر سکتا ہے۔

schedule backup ہے، mechanism نہیں۔ weekly job branch پر موجود ان چیزوں کو پکڑ لیتی ہے جن پر کسی کی نظر نہیں پڑی: rebase کے ذریعے منتقل کی گئی files، merge میں delete کیا گیا package، یا ایسا document جو اب موجود نہ ہونے والی 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 ہوتا ہے۔ web page سے copy کیا گیا ایسا command جو آپ کے version سے مطابقت نہ رکھتا ہو، cron کے اندر fail ہو جاتا ہے، جہاں کوئی error نہیں دیکھتا۔ اسے مکمل کریں اور schedule کرنے سے پہلے script کو ایک بار خود چلائیں۔ || exit 0 بھی اہم ہے: tree پہلے ہی current ہونے پر git commit، nothing to commit, working tree clean کے ساتھ non-zero exit کرتا ہے، اور set -e کے تحت اسے healthy run کو failure کے طور پر report کرنا پڑے گا۔

ہر pass میں tokens خرچ ہوتے ہیں، کیونکہ "Read Before Editing" agent کو ہر task پر پوری chain پڑھنے پر مجبور کرتا ہے۔ یہ trade-off ہے، اور اگر آپ پہلے ہی یہ شمار کر رہے ہیں کہ آپ کے agent کے runs کی لاگت کتنی ہے تو اس پر نظر رکھنا مفید ہے۔

Monorepo: متعدد contracts، ایک index

چالیس packages والی repository میں ایک ہی root AGENTS.md رکھنے سے ایسی regeneration diff بنتی ہے جسے کوئی نہیں پڑھتا، اور ایسا document تیار ہوتا ہے جو agent کے موجودہ کام سے زیادہ تر غیر متعلق ہوتا ہے۔ dox اس کا جواب Child DOX Index کی صورت میں دیتا ہے: root میں پوری repository کے rules رکھے جاتے ہیں اور child files کی طرف اشارہ کیا جاتا ہے، جبکہ ہر مستقل boundary اپنی file کی مالک ہوتی ہے۔ اس tree کو کیسے ترتیب دینا ہے، اور کون سے tools nested files پڑھتے ہیں، اس کی وضاحت 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 میں رکھیں، اور مخصوص details child docs میں۔ duplicated rules ہی routine pass کے دوران ہر چیز کو دوبارہ لکھنے کا سبب بنتے ہیں۔ اگر یہی rules واقعی الگ repositories پر یکساں طور پر لاگو ہوتے ہیں تو یہ مختلف مسئلہ ہے، اور repositories کے درمیان agent skills شیئر کرنا اس کے لیے بہتر tool ہے۔

کوڈ کی طرح diff کا جائزہ لیں

Generated documentation کا diff بغیر پڑھے approve کرنا آسان ہے، اور اسی طرح غلط file release ہو جاتی ہے۔ اسے اسی شک کے ساتھ پڑھیں جو آپ generated code کے لیے رکھتے ہیں، اور چار چیزیں تلاش کریں۔

• file میں اب درج کوئی command، جسے merge کرنے سے پہلے خود چلانا چاہیے۔ فرضی build instructions سب سے عام failure ہیں۔
• حذف کی گئی کوئی line جس میں مقصد یا context موجود تھا۔ اضافے سستے ہوتے ہیں۔ اصل نقصان deletions میں ہوتا ہے۔
• کوئی absolute path، hostname، internal URL، یا credential جیسی کوئی بھی چیز
• کسی ایسی چیز کی inventory entry جو اب موجود نہیں، جسے ls ایک سیکنڈ میں حل کر دیتا ہے

پھر wc -l AGENTS.md سے size چیک کریں۔ دو سو lines سے بڑی root file اس بات کا اشارہ ہے کہ اسے تقسیم کرنا چاہیے، کیونکہ اس chain کی پوری افادیت یہ ہے کہ agent ہر چیز کے بجائے متعلقہ چھوٹا حصہ پڑھتا ہے۔

جب یہ عمل ناکام ہو جائے

عمل نے آپ کا intent block حذف کر دیا۔ diff چیک اوپر حذف کی گئی سطریں دکھاتا ہے۔ git restore --source=origin/main AGENTS.md کے ذریعے branch point سے فائل بحال کریں، پھر ایسی مختصر ہدایت کے ساتھ عمل دوبارہ چلائیں جس میں ان sections کے نام درج ہوں جنہیں تبدیل کرنے کی اجازت ہے۔

دونوں branches نے دوبارہ مواد تیار کر دیا۔ آپ کو CONFLICT (content): Merge conflict in AGENTS.md اور فائل کے اندر conflict markers <<<<<<< HEAD نظر آئیں گے۔ markers کو دستی طور پر edit نہ کریں۔ فائل generated ہے، اس لیے درست حل یہ ہے کہ merged tree پر نیا عمل چلایا جائے۔

agent فائل کو مکمل طور پر نظرانداز کر دیتا ہے۔ معلوم کریں کہ آپ کا tool حقیقت میں کون سا filename پڑھتا ہے۔ اگر وہ کوئی دوسری فائل پڑھتا ہے تو ln -s AGENTS.md CLAUDE.md کے ذریعے اسے اسی content کی طرف متوجہ کریں اور symlink commit کریں، تاکہ دو ایسی documents کے بجائے ایک ہی source برقرار رہے جو وقت کے ساتھ مختلف ہو جائیں۔ اگر filename پہلے ہی درست ہے اور rules پھر بھی نظرانداز ہو رہے ہیں تو document دوبارہ لکھنے سے پہلے coding agents آپ کی ہدایات کیوں نظرانداز کرتے ہیں کے لیے diagnosis چلائیں۔

tree میں ایسی children شامل ہو گئیں جنہیں کسی نے index نہیں کیا۔ find . -name AGENTS.md کے output کا parent documents میں موجود index entries سے موازنہ کریں۔ جس child کا کسی index میں ذکر نہ ہو، agent اسے براہ راست نظرانداز کر سکتا ہے۔

جب generator حد سے زیادہ ہو

ایک package، ایک test command، اور repository سے واقف دو افراد ہوں تو بیس سطریں خود لکھ دیں۔ بیس سطروں پر مشتمل AGENTS.md اتنی تیزی سے فرسودہ نہیں ہوتی کہ اس کے لیے tree، index، CI check اور weekly job کا جواز بنے۔ build تبدیل کرتے وقت اسے دوبارہ پڑھ لیں۔ یہی مکمل maintenance cost ہے، اور یہ اس کے گرد موجود machinery کی لاگت سے کم ہے۔

dox کے لیے وقت اور وسائل صرف کرنا اس وقت مفید ہے جب repository میں ایسی boundaries ہوں جنہیں کوئی ایک شخص مکمل طور پر ذہن میں نہ رکھتا ہو: مختلف rules والے کئی packages، یا ایسے contributors جو پس منظر کی معلومات کے بغیر شامل ہوں۔ قدر generated text میں نہیں ہے۔ اصل فائدہ یہ ہے کہ documentation ایسی چیز بن جاتی ہے جس کی خلاف ورزی پر pull request fail ہو سکتی ہے؛ repository کی کسی file کے current رہنے کی یہی واحد مؤثر وجہ ہے۔

FAQ

dox استعمال کرنے کے لیے کیا مجھے کوئی چیز انسٹال کرنی ہوگی؟

نہیں۔ dox ایک ہی Markdown فائل ہے، MIT لائسنس کے تحت ہے، اور 11 August 2026 تک repository میں کوئی package یا releases موجود نہیں ہیں۔ آپ اس کے مواد کو اپنے project کی AGENTS.md میں copy کرتے ہیں، اور آپ کا coding agent وہیں سے rules پر عمل کرتا ہے۔ جو commit آپ نے copy کیا ہے اسے pin کریں، تحریر کے وقت f34ec7ad1055d3393887e5a2670e8cb7320c9165، اور اسے اپنے commit message میں درج کریں تاکہ بعد میں معلوم ہو سکے کہ آپ کا tree rules کے کس version کے تحت تیار ہوا تھا۔

میں regeneration کو اپنی لکھی ہوئی rules حذف کرنے سے کیسے روکوں؟

intent اور inventory کو الگ رکھیں۔ پائیدار reasoning ایک الگ document میں رکھیں، اور جو کچھ AGENTS.md کے اندر رہنا ضروری ہو اسے ایک marked block کے اندر رکھیں۔ پھر اس block کو CI میں check کریں: اسے branch اور origin/main سے sed کے ذریعے extract کریں، دونوں کا diff کے ذریعے موازنہ کریں، اور کسی بھی فرق کی صورت میں build ناکام کریں۔ اس طرح تبدیلی بڑے diff کے اندر خاموشی سے منظور ہونے کے بجائے کوئی شخص اسے approve یا revert کرتا ہے۔

مجھے AGENTS.md کتنی بار regenerate کرنی چاہیے؟

جس pull request میں یہ غلط ہو، اسی میں۔ structural change اور اس کی documentation ایک ہی diff میں ہونی چاہیے، کیونکہ دونوں کا جائزہ لینے کے لیے context صرف اسی وقت دستیاب ہوتا ہے۔ ہفتہ وار scheduled pass اس drift کے لیے backup ہے جو branch سے گزر گیا ہو، اور اسے main میں commit کرنے کے بجائے pull request کھولنی چاہیے۔

build commands کو root AGENTS.md میں رکھنا چاہیے یا child میں؟

اس nearest document میں جو ان commands کا مالک ہو۔ repo-wide rules اور child index root میں رہتے ہیں۔ جو command صرف ایک package پر لاگو ہو، وہ اسی package کی AGENTS.md میں رہتی ہے۔ dox فاصلے کے مطابق conflicts resolve کرتا ہے: زیادہ قریب document مقامی details کو control کرتا ہے، اور کوئی child parent rule کو کمزور نہیں کر سکتا۔ ہر child میں ایک ہی command copy کرنا ہی وہ وجہ ہے جس سے ایک routine pass پورے tree کو دوبارہ لکھ دیتا ہے۔

کیا ایک چھوٹی repository کے لیے dox مفید ہے؟

عموماً نہیں۔ ایک package، ایک test command اور بیس سطروں پر مشتمل AGENTS.md آہستہ خراب ہوتی ہے، اور اس خرابی کا پتا چلنے کے فوراً بعد آپ اسے ایک منٹ میں درست کر سکتے ہیں۔ dox کی لاگت اس وقت فائدہ مند ہوتی ہے جب repository میں مختلف rules والی کئی boundaries ہوں، یا ایسے contributors ہوں جن کے پاس پس منظر کی معلومات نہ ہوں، کیونکہ اس صورت میں documents کی chain وہ کام انجام دے رہی ہوتی ہے جو کوئی ایک شخص اکیلا نہیں کر رہا ہوتا۔