به‌روزرسانی خودکار فایل AGENTS.md با ابزار dox

چرا فایل AGENTS.md شما پس از سه هفته اشتباه است

یک فایل AGENTS.md به این دلیل قدیمی می‌شود که هیچ پیوندی بین آن و کد وجود ندارد. شما آن را یک‌بار و به‌صورت دستی در روزی که مخزن وضعیت خاصی دارد می‌نویسید. سپس ابزار اجرای تست تغییر می‌کند، نام یک بسته عوض می‌شود، یک سرویس حذف می‌گردد، اما فایل همچنان وضعیت ماه ژوئن را توصیف می‌کند. هیچ‌چیز با شکست مواجه نمی‌شود، زیرا هیچ مرحله‌ای از build آن را نمی‌خواند.

عامل (agent) آن را می‌خواند و به آن اعتماد می‌کند. این همان بخشی است که برای شما هزینه دارد. مخزنی که فاقد AGENTS.md باشد، باعث می‌شود عامل کدنویسی پیش از اقدام، محیط را بررسی کند. مخزنی که یک AGENTS.md اشتباه دارد، باعث می‌شود عامل از بررسی دست بکشد، زیرا از قبل پاسخ را در اختیار دارد. عامل دستوری که در فایل شما نام برده شده را اجرا می‌کند، شل پاسخ Missing script: "test" را برمی‌گرداند و حالا عامل شروع به حدس‌زدن می‌کند. اغلب اوقات، عامل فایل package.json را ویرایش می‌کند تا اسکریپتی که در مستندات وعده داده شده بود را اضافه کند. فایل قدیمی به‌آرامی شکست نخورد؛ بلکه باعث ویرایشی شد که شما نمی‌خواستید.

dox یکی از پاسخ‌ها به این مشکل است. این ابزار مجموعه‌ای از قوانین است که برای عامل نوشته شده و به‌روزرسانی مستندات را به بخشی از تکمیل کار تبدیل می‌کند، به‌طوری که فایل در همان commit تغییر می‌کند که کدِ تغییردهندهٔ آن تغییر کرده است.

dox چیست و چه چیزی نیست

dox یک فایل Markdown واحد است. مخزن آن agent0ai/dox است، تحت مجوز MIT منتشر شده و تا تاریخ 11 August 2026، کل پروژه شامل یک فایل AGENTS.md با حجم 3906 بایت، یک فایل README، یک فایل LICENSE و دو تصویر است. هیچ بسته‌ای برای نصب و هیچ runtimeای وجود ندارد.

این موضوع اهمیت دارد، زیرا کلمه generator ممکن است برنامه‌ای را تداعی کند که کد شما را تجزیه (parse) می‌کند. هیچ چیزی کد شما را تجزیه نمی‌کند. dox قراردادی است که agent کدنویسی شما آن را می‌خواند: agent شما همان generator است و dox مجموعه‌دستورالعملی است که به آن می‌گوید چه زمانی مستندات را بخواند، چه زمانی آن‌ها را بازنویسی کند و هر سند چه ساختاری داشته باشد.

این فایل ده بخش دارد که دو بخش آن کار اصلی را انجام می‌دهند. بخش "Read Before Editing" به agent دستور می‌دهد که از ریشه مخزن تا هر مسیری که قصد تغییر در آن را دارد حرکت کند و در جلسه جاری، بدون تکیه بر حافظه، تمام فایل‌های AGENTS.md را در طول مسیر بخواند. بخش "Update After Editing" به آن می‌گوید که هر تغییر معنادار نیازمند یک مرحله DOX است؛ به این معنی که یک مرحله به‌روزرسانی مستندات باید پیش از آنکه کار تمام‌شده تلقی شود، اجرا گردد. این مرحله، نزدیک‌ترین سند مالک را در صورتی که هدف، ساختار، گردش کار، مجوزها یا ترجیحات کاربر تغییر کرده باشد، به‌روز می‌کند.

بقیه بخش‌ها مربوط به ساختار هستند. یک فایل AGENTS.md فرزند، ترتیب بخش‌های پیش‌فرض دارد: هدف (Purpose)، مالکیت (Ownership)، قراردادهای محلی (Local Contracts)، راهنمای کار (Work Guidance)، تایید (Verification) و فهرست DOX فرزند (Child DOX Index). فایل ریشه شامل قوانین کل پروژه به همراه فهرست DOX فرزند در سطح بالا است که از طریق آن، agent اسناد فرزند را کشف می‌کند. "Closeout" چک‌لیستی است که agent در پایان هر کار اجرا می‌کند: بررسی مجدد مسیرهای تغییریافته در زنجیره، به‌روزرسانی نزدیک‌ترین اسناد مالک، تازه‌سازی تمام فهرست‌های تحت تأثیر، حذف تناقضات، اجرای تاییدهای موجود و گزارش اینکه کدام اسناد را عمداً تغییر نداده است.

پین کردن مستندات به یک commit خاص، نه به main

این مخزن هیچ تگ یا release ندارد، بنابراین شماره نسخه‌ای برای پین کردن وجود ندارد. در عوض، 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 را چاپ کند. عددی متفاوت به این معنی است که شما فایلی که این راهنما توصیف می‌کند را دریافت نکرده‌اید، پس پیش از اعتماد به آن، راهنما را مطالعه کنید. اگر هش commit را اشتباه تایپ کنید، -f باعث می‌شود curl با خطای curl: (22) The requested URL returned error: 404 متوقف شود و هیچ محتوایی ننویسد، و سپس wc -c مقدار 0 را چاپ می‌کند. یک فایل ناقص (truncated) از نبود فایل بدتر است، زیرا عامل (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 ندارد. اگر از قبل فایلی دارید، آن را بازنویسی نکنید. بخش‌های مستندات (dox) را بالای محتوای موجود خود قرار دهید، قوانین خود را در زیر نگه دارید و نتیجه را یک بار از ابتدا تا انتها بخوانید. دو سند که با یکدیگر تناقض دارند، عاملی تولید می‌کنند که از آخرین خطی که خوانده است پیروی می‌کند.

سپس از عامل خود در داخل مخزن، برای اولین مرحله (first pass) سوال کنید. فایل README عبارت دقیق را ارائه می‌دهد:

Initialize DOX tree for this project now.

این دستور فایل‌های AGENTS.md فرزند و نمایه‌هایی (indexes) که به آن‌ها اشاره می‌کنند را ایجاد می‌کند. پیش از اعتماد به نتیجه، بررسی کنید که چه کاری انجام داده است:

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

هر فایل در خروجی find باید در یک نمایه مستندات فرزند (Child DOX Index) در جایی بالاتر از آن ظاهر شود. سند فرزندی که هیچ نمایه‌ای به آن اشاره نمی‌کند، سندی است که عامل ممکن است آن را نادیده بگیرد، زیرا نمایه روشی است که عامل از طریق آن اسنادی را که مستقیماً در مسیر پیمایش او قرار ندارند، پیدا می‌کند.

آنچه dox می‌بیند و آنچه نمی‌تواند بداند

عاملی که درخت شما را می‌سازد، مخزن را می‌خواند؛ بنابراین هر چیزی در مخزن می‌تواند وارد فهرست موجودی شود: ساختار دایرکتوری‌ها، مانیفست‌های بسته و فایل‌های lockfile، اسکریپت‌های موجود در package.json یا Makefile یا pyproject.toml، فایل‌های گردش‌کار CI، فایل‌های Dockerfile، نقاط ورود (entry points) و CODEOWNERS اگر یکی داشته باشید. فهرست موجودی که از این موارد ساخته شود، به‌طور واقعی خودنگهدار است. وقتی بسته‌ای جابه‌جا می‌شود، در اجرای بعدی، خطی که آن را توصیف می‌کند نیز جابه‌جا می‌شود.

همه موارد زیر بر عهده شماست که بیان کنید، زیرا در مخزن وجود ندارند تا خوانده شوند:

• دلیل وجود یک قانون، که همان چیزی است که مانع از حذف آن توسط عامل به عنوان پیچیدگی غیرضروری می‌شود.
• اینکه کدام‌یک از دو مسیر کاری پشتیبانی می‌شود و کدام‌یک در انتظار حذف است.
• هر چیزی خارج از مخزن، مانند محیط staging یا دلیلی که یک وابستگی (dependency) دو نسخه عقب‌تر پین شده است.
• آنچه قصد دارید هفته آینده انجام دهید، که تفاوت بین فایلی است که به‌روز است و فایلی که مفید است.

dox این موضوع را درباره خودش می‌داند. قوانین خودِ آن می‌گویند که Work Guidance باید منعکس‌کننده استانداردهای فعلی پروژه یا دستورالعمل‌های کاربر باشد و اگر هنوز موردی وجود ندارد، باید آن بخش را خالی بگذارید. Verification باید منعکس‌کننده یک بررسی موجود باشد، بنابراین اگر چارچوب تستی در مخزن نباشد، آن بخش تا زمانی که چارچوبی ایجاد نشود، خالی می‌ماند. فایلی که تولید می‌شود و استانداردی را از خود می‌سازد، بدتر از یک بخش خالی است، زیرا عامل پس از آن، همان استاندارد ابداعی را اعمال خواهد کرد.

حفظ قصد و نیت دست‌نویس خارج از فهرست تولیدشده

این همان شکستی است که باعث می‌شود افراد از مستندات تولیدشده ناامید شوند. شما پاراگرافی می‌نویسید که توضیح می‌دهد صف کارها باید تک‌مصرف‌کننده باقی بماند. سه هفته بعد، یک پردازش فایل را بازنویسی می‌کند و پاراگراف شما از بین می‌رود، آن هم در میان یک diff چهل خطی که عمدتاً نام فایل‌ها را جابه‌جا کرده است و هیچ‌کس متوجه آن نمی‌شود.

دو مکانیزم وجود دارد و شما به هر دو نیاز دارید.

نخست، نیت‌های پایدار را به فایلی متفاوت منتقل کنید. تصمیمات طراحی و استدلال‌های پشت آن‌ها متعلق به یک فایل DESIGN.md نوشته‌شده برای عامل هستند و یادداشت‌هایی که برای انسان‌ها وجود دارند، متعلق به جایی هستند که شما فایل HUMAN.md را از AGENTS.md جدا می‌کنید. در نتیجه، AGENTS.md فهرست و قراردادهای محلی را نگه می‌دارد که دقیقاً همان بخشی است که با تغییر کد باید تغییر کند.

دوم، نیتی که باید داخل AGENTS.md باقی بماند را محصور کنید. آن را در نشانگرها بپیچید و با آن بلوک به عنوان محتوای تحت مالکیت انسان رفتار کنید:

## 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 در صفحه نمایش داده نمی‌شوند و عامل همچنان آن‌ها را می‌خواند. حالا قابلیت بررسی بقای بلوک را ایجاد کنید تا پردازشی که آن را حذف می‌کند، با صدای بلند شکست بخورد. این دستور را در CI (یکپارچه‌سازی مداوم) در هر pull request اجرا کنید:

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 خارج می‌شود. هرگونه خروجی به این معنی است که پردازش، متن تحت مالکیت انسان را بازنویسی کرده است، بنابراین یک شخص باید آن را تأیید یا به حالت قبل بازگرداند. این بررسی بدون نیاز به اینکه کسی آن را به خاطر بسپارد، برقرار می‌ماند.

بازسازی در زمان Pull Request، نه بر اساس زمان‌بندی

بهترین زمان برای به‌روزرسانی یک سند، همان لحظه ثبت commit است که باعث قدیمی شدن آن شده است. عملیات DOX را در همان 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

مسیرها را متناسب با مخزن (repository) خود تنظیم کنید. ارزش این کار در این است که بررسی در همان شاخه (branch) شکست می‌خورد، جایی که اصلاح آن کم‌هزینه است و دلیل شکست برای بازبین (reviewer) کاملاً مشخص است.

زمان‌بندی (schedule) نقش پشتیبان را دارد، نه مکانیزم اصلی. یک وظیفه هفتگی (weekly job) مواردی را پیدا می‌کند که در شاخه از چشم افتاده‌اند: فایل‌هایی که با rebase جابه‌جا شده‌اند، بسته‌ای که در یک merge حذف شده، یا سندی که به دایرکتوری اشاره می‌کند که دیگر وجود ندارد. این کار را روی یک سرور کوچک اجرا کنید، همان سروری که ممکن است برای اجرای یک coding agent روی VPS استفاده کنید، و به جای push مستقیم به main، آن را وادار کنید یک 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

آن کامنت عمداً به عنوان یک جای‌نگهدار (placeholder) قرار داده شده است. هر agent دارای CLI (رابط خط فرمان) و flag غیرتعاملی (non-interactive) خاص خود است و دستوری که از یک صفحه وب کپی شده و با نسخه شما مطابقت ندارد، در cron شکست می‌خورد بدون اینکه کسی متوجه خطا شود. آن را تکمیل کنید و پیش از زمان‌بندی، یک بار اسکریپت را به‌صورت دستی اجرا کنید. مقدار || exit 0 نیز اهمیت دارد: git commit در صورتی که درخت (tree) از قبل به‌روز باشد با کد nothing to commit, working tree clean خارج می‌شود و تحت set -e، این وضعیت ممکن است یک اجرای موفق را به عنوان شکست گزارش کند.

هر بار اجرا هزینه توکن دارد، زیرا "خواندن پیش از ویرایش" باعث می‌شود agent در هر وظیفه کل زنجیره را بخواند. این یک بده‌بستان (trade-off) است و اگر در حال حاضر هزینه‌های اجرای agent خود را محاسبه می‌کنید، ارزش بررسی دارد.

مونوریپوها: قراردادهای متعدد، یک ایندکس

وجود یک فایل AGENTS.md در ریشهٔ مخزنی با 40 بسته، منجر به تولید یک diff برای بازسازی می‌شود که هیچ‌کس آن را نمی‌خواند و سندی ایجاد می‌کند که در لحظهٔ فعالیت هر agent، عمدتاً بی‌ارتباط است. پاسخ dox در اینجا استفاده از Child DOX Index است: ریشه شامل قوانین سراسری مخزن است و به فرزندان خود اشاره می‌کند، و هر مرز پایدار، فایل اختصاصی خود را دارد. نحوهٔ چیدمان این درخت و ابزارهایی که از فایل‌های تو در تو پشتیبانی می‌کنند، در فایل‌های AGENTS.md تو در تو برای مونوریپوها پوشش داده شده است.

آنچه dox تغییر می‌دهد، سطح بازبینی است. یک pull request که packages/api را تغییر می‌دهد، باید فقط یک diff مستندات در packages/api ایجاد کند و نه جای دیگر:

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

اگر این دستور برای تغییری در یک بسته، 6 فایل را فهرست می‌کند، ساختار درخت اشتباه است. یا مرزها بیش از حد کلی هستند، یا قانونی که متعلق به ریشه است در تمام فرزندان کپی شده است. dox راه حل را مستقیماً بیان می‌کند: قوانین کلی در مستندات والد و جزئیات دقیق در مستندات فرزند قرار می‌گیرند. قوانین تکراری همان چیزی هستند که باعث می‌شوند یک بازنویسی روتین، همه چیز را تغییر دهد. اگر قوانین یکسانی واقعاً در مخازن جداگانه اعمال می‌شوند، این یک مسئله متفاوت است و به‌اشتراک‌گذاری مهارت‌های agent بین مخازن ابزار مناسب‌تری برای آن است.

بازبینی تفاوت‌ها (diff) مانند کد

تأیید کردن تفاوت‌های ایجاد شده در مستندات بدون مطالعهٔ دقیق آن‌ها آسان است، و همین موضوع باعث می‌شود فایل‌های اشتباه منتشر شوند. تفاوت‌ها را با همان بدبینی که نسبت به کدهای تولیدشده دارید بخوانید و به چهار مورد زیر توجه کنید:

• دستوری که فایل اکنون نام می‌برد؛ پیش از ادغام (merge)، باید خودتان آن را اجرا کنید. دستورالعمل‌های ساخت (build) ابداعی، رایج‌ترین عامل شکست هستند.
• خط حذف‌شده‌ای که حاوی یک هدف یا قصد خاص بوده است. افزودن محتوا کم‌هزینه است، اما حذف محتوا جایی است که اطلاعات از دست می‌روند.
• مسیر مطلق (absolute path)، نام میزبان (hostname)، آدرس URL داخلی یا هر چیزی که شبیه به اعتبارنامه (credential) باشد.
• ورودی موجودی (inventory) برای چیزی که دیگر وجود ندارد؛ موردی که ls در یک لحظه آن را حل‌وفصل می‌کند.

سپس حجم فایل را با wc -l AGENTS.md بررسی کنید. یک فایل root با بیش از 200 خط، نشانه‌ای برای تقسیم کردن آن است، زیرا ارزش کل این زنجیره در این است که عامل (agent) به جای خواندن همه چیز، بخش کوچک و مرتبط را مطالعه کند.

هنگام بروز خطا

بلوک هدف شما توسط pass حذف شده است. بررسی diff در بالا، خطوط حذف‌شده را نمایش می‌دهد. فایل را از نقطه انشعاب با استفاده از git restore --source=origin/main AGENTS.md بازیابی کنید، سپس pass را با دستوری محدودتر که بخش‌های مجاز برای تغییر را نام می‌برد، دوباره اجرا کنید.

هر دو شاخه بازتولید شده‌اند. شما CONFLICT (content): Merge conflict in AGENTS.md و نشانگرهای تداخل <<<<<<< HEAD را درون فایل دریافت می‌کنید. نشانگرها را به‌صورت دستی ویرایش نکنید. از آنجا که فایل تولیدشده است، راه حل صحیح، اجرای مجدد pass روی درخت ادغام‌شده است.

عامل (agent) فایل را کاملاً نادیده می‌گیرد. بررسی کنید ابزار شما در واقع کدام نام فایل را می‌خواند. اگر فایل متفاوتی را می‌خواند، آن را با ln -s AGENTS.md CLAUDE.md به همان محتوا ارجاع دهید و symlink را commit کنید تا به‌جای دو سند که به‌مرور با هم اختلاف پیدا می‌کنند، یک منبع واحد داشته باشید. اگر نام فایل صحیح است و قوانین همچنان نادیده گرفته می‌شوند، پیش از بازنویسی مجدد سند، عیب‌یابی مربوط به چرا عوامل کدنویسی دستورالعمل‌های شما را نادیده می‌گیرند را اجرا کنید.

درخت، فرزندانی ایجاد کرده که کسی آن‌ها را نمایه‌سازی نکرده است. خروجی find . -name AGENTS.md را با ورودی‌های فهرست در اسناد والد مقایسه کنید. فرزندی که در هیچ فهرستی ذکر نشده، فرزندی است که عامل می‌تواند به‌سادگی از کنار آن عبور کند.

چه زمانی استفاده از generator زیاده‌روی است

یک پکیج، یک دستور تست، و دو نفر که هر دو مخزن را می‌شناسند: بیست خط کد را دستی بنویسید. یک فایل AGENTS.md بیست‌خطی آن‌قدر سریع تغییر نمی‌کند که نیاز به ساختار درختی، ایندکس، بررسی CI و اجرای وظایف هفتگی داشته باشد. هر زمان که build را تغییر دادید، آن را دوباره بخوانید. این کل هزینهٔ نگهداری است و از هزینهٔ ابزارهای جانبی برای مدیریت آن کمتر است.

استفاده از dox زمانی ارزشمند است که مخزن دارای مرزهایی باشد که هیچ‌کس به‌تنهایی قادر به درک کامل آن نیست: چندین پکیج با قوانین متفاوت، یا مشارکت‌کنندگانی که بدون پیش‌زمینه وارد پروژه می‌شوند. ارزش کار در متن تولیدشده نیست؛ بلکه در این است که مستندات به چیزی تبدیل می‌شوند که یک pull request می‌تواند به دلیل نقص در آن رد شود، و این تنها دلیلی است که باعث می‌شود هر فایلی در یک مخزن به‌روز باقی بماند.

FAQ

آیا برای استفاده از dox نیاز به نصب چیزی دارم؟

خیر. dox یک فایل Markdown واحد با مجوز MIT است و تا تاریخ 11 August 2026، این مخزن هیچ پکیجی ارائه نمی‌دهد و هیچ نسخه‌ای (release) منتشر نکرده است. شما محتوای آن را در فایل AGENTS.md پروژه خود کپی می‌کنید و coding agent شما از قوانین موجود در آن پیروی می‌کند. commit کپی‌شده را که در زمان نگارش این متن f34ec7ad1055d3393887e5a2670e8cb7320c9165 است، پین کنید و نام آن را در پیام commit خود ذکر کنید تا بعداً بتوانید تشخیص دهید که درخت پروژه شما تحت کدام نسخه از قوانین ساخته شده است.

چگونه از حذف قوانین دست‌نویس خود در هنگام بازتولید (regeneration) جلوگیری کنم؟

قصد (intent) و موجودی (inventory) را از هم جدا نگه دارید. استدلال‌های پایدار را در یک سند جداگانه قرار دهید و هر چیزی که باید حتماً داخل AGENTS.md باقی بماند را درون یک بلوک نشانه‌گذاری‌شده قرار دهید. سپس آن بلوک را در CI بررسی کنید: آن را از شاخه (branch) و از origin/main با استفاده از sed استخراج کنید، این دو را با diff مقایسه کنید و در صورت وجود هرگونه تفاوت، build را با خطا مواجه کنید. بدین ترتیب، یک شخص تغییر را تأیید یا رد می‌کند، به‌جای اینکه تغییر به‌صورت ناخواسته در میان یک diff بزرگ نادیده گرفته شود.

هر چند وقت یک‌بار باید AGENTS.md را بازتولید کنم؟

در همان pull request که باعث نادرست شدن آن شده است. یک تغییر ساختاری و مستندات مربوط به آن باید در یک diff واحد باشند، زیرا این تنها لحظه‌ای است که شخصی زمینه (context) کافی برای بررسی هر دو را دارد. یک اجرای زمان‌بندی‌شده هفتگی، پشتیبانی برای انحرافاتی است که از چشم شاخه‌ها دور مانده‌اند و این کار باید به‌جای commit مستقیم روی main، یک pull request جدید ایجاد کند.

آیا دستورات build باید در AGENTS.md ریشه باشند یا در یک فایل فرزند؟

در نزدیک‌ترین سندی که مالک آن‌هاست. قوانین کل مخزن و فهرست فرزندان در ریشه قرار می‌گیرند. دستوری که برای یک پکیج خاص اعمال می‌شود، در فایل AGENTS.md همان پکیج قرار می‌گیرد. dox تداخل‌ها را بر اساس فاصله حل می‌کند: سند نزدیک‌تر جزئیات محلی را کنترل می‌کند و هیچ فرزندی نمی‌تواند قانون والد را تضعیف کند. کپی کردن یک دستور مشابه در تمام فرزندان، همان چیزی است که باعث می‌شود یک اجرای روتین، کل درخت را بازنویسی کند.

آیا dox برای یک مخزن کوچک ارزش استفاده دارد؟

معمولاً خیر. یک پکیج با یک دستور تست و یک فایل AGENTS.md بیست‌خطی به‌کندی دچار فرسایش می‌شود و می‌توانید آن را در همان دقیقه‌ای که متوجه شدید، اصلاح کنید. dox زمانی هزینه خود را جبران می‌کند که مخزن دارای چندین مرز با قوانین متفاوت باشد، یا مشارکت‌کنندگانی داشته باشد که پیش‌زمینه کافی ندارند؛ زیرا در این صورت، زنجیره اسناد کاری را انجام می‌دهد که هیچ فرد واحدی قادر به انجام آن نیست.