مدیریت فایلهای AGENTS.md در ساختار Monorepo
استفاده از یک فایل AGENTS.md در ریشه پروژه باعث هدر رفتن Context مدل میشود. با پیادهسازی ساختار تو در تو، دستورالعملها را به تفکیک هر دایرکتوری مدیریت کنید.
معنای فایلهای AGENTS.md تو در تو در یک monorepo
وجود فایلهای AGENTS.md تو در تو در یک monorepo به این معناست که یک فایل کوچک در ریشه مخزن و یک فایل دیگر در داخل هر دایرکتوری سرویس قرار دارد. فایل ریشه شامل چند قانونی است که در همه جا صدق میکنند، به علاوه نقشهای از اینکه فایلهای دیگر کجا قرار دارند. هر فایل سرویس، دستورات و قراردادهای مربوط به همان دایرکتوری را در خود جای میدهد. عاملی که در حال ویرایش services/worker/queue.py است، فایل ریشه و فایل کاری را میخواند و هیچ بخشی از حافظه (context) خود را صرف فرانتاند (front end) که هرگز با آن کاری نخواهد داشت، نمیکند.
هیچ چیزی برای نصب وجود ندارد. AGENTS.md یک قرارداد است و پروژه بالادستی (upstream) این موضوع را به صراحت بیان میکند:
AGENTS.md صرفاً یک فایل Markdown استاندارد است. از هر عنوانی که میخواهید استفاده کنید؛ عامل (agent) به سادگی متنی که ارائه میدهید را تحلیل میکند.
به همین دلیل است که یادگیری صحیح این تکنیک ارزشمند است. فرمت آن تغییر نخواهد کرد. آنچه ممکن است دچار مشکل شود، محل قرارگیری و نگهداری فایلهاست که هر دوی آنها وظیفه شما هستند.
چرا یک فایل AGENTS.md بزرگ در ریشه پروژه از کار میافتد؟
یک فایل AGENTS.md با 600 خط در ریشه مخزنی که شامل یک وباپلیکیشن، یک worker پسزمینه و یک دایرکتوری Terraform است، به چهار دلیل مجزا شکست میخورد.
فایل قدیمی میشود، چون هیچکس مالک آن نیست. مهندسی که یک اسکریپت تست را در apps/web تغییر نام میدهد، فایلهای زیرمجموعه apps/web را ویرایش میکند. فایل AGENTS.md ریشه در آن diff نیست، بنابراین هیچ بازبینیکنندهای متوجه عدم تطابق نمیشود. شش هفته بعد، فایل مرحلهای از build را توصیف میکند که دیگر وجود ندارد و کسی که آن را خراب کرده، تغییرات را فراموش کرده است.
در هر تسک، هزینه context میپردازد. این فایلها در ابتدای نشست (session) بارگذاری میشوند، پیش از آنکه agent بداند شما چه چیزی خواهید پرسید. مستندات Claude Code عددی برای آن تعیین کرده است: "هدف کمتر از 200 خط در هر فایل CLAUDE.md باشد. فایلهای طولانیتر context بیشتری مصرف کرده و میزان پایبندی را کاهش میدهند." Codex زمانی که اندازه ترکیبی فایلهای دستورالعمل به 32 KiB برسد، یعنی project_doc_max_bytes پیشفرض، ادغام آنها را متوقف میکند. یک فایل ریشه که چهار سرویس را مستند میکند، این بودجه را برای هر تسک، صرف سه سرویس دیگر میکند.
دستورالعملها شروع به تناقض با یکدیگر میکنند. دایرکتوری وب pnpm test را میخواهد. worker به pytest -q نیاز دارد. وقتی این قوانین در یک فایل نوشته میشوند، هر قانون فقط گاهی درست است، بنابراین agent باید حدس بزند کدامیک اعمال میشود. مستندات Claude Code نتیجه را اینگونه توصیف میکند: "اگر دو دستورالعمل با هم تناقض داشته باشند، Claude ممکن است یکی را به دلخواه انتخاب کند." تقسیم کردن فایل، قانون دیگر را از context خارج نمیکند. Claude Code تمام فایلهای دستورالعملی که بارگذاری کرده را به هم میچسباند، نه اینکه یکی را جایگزین دیگری کند؛ بنابراین فایل ریشه همیشه حضور دارد و وقتی agent فایلهایی را در هر دو مسیر apps/web و services/worker باز میکند، هر دو فایل دایرکتوری در کنار هم در context قرار میگیرند. کاری که یک فایل مخصوص دایرکتوری انجام میدهد، پیوند دادن هر قانون به دایرکتوری مربوط به آن است. نام دایرکتوری را در بالای فایل بنویسید، همانطور که در مثالهای زیر با # apps/web انجام شده است؛ به این ترتیب، وقتی چندین فایل همزمان بارگذاری میشوند، هر دستور مشخص میکند که در کجا معتبر است. وقتی قانونی که مطمئن هستید واضح نوشتهاید نادیده گرفته میشود، بررسی دلایلی که یک دستورالعمل هرگز اعمال نمیشود بهتر از بازنویسی متن برای بار چهارم است.
فایل با حقایقی پر میشود که agent میتوانست از کد بخواند. درخت دایرکتوری، لیست وابستگیها، خلاصهای از عملکرد هر پکیج. بررسی /doctor در Claude Code دقیقاً برای حذف همین موارد وجود دارد. این قابلیت "محتوایی که Claude میتواند از codebase استخراج کند، مانند ساختار دایرکتوریها، لیست وابستگیها و نمای کلی معماری را حذف میکند" و "چالشها، منطق و قراردادهایی که با پیشفرضهای ابزار متفاوت هستند" را حفظ میکند. آن جمله بهترین آزمونی است که میشناسم تا بفهمم آیا یک خط اصلاً باید در فایل باشد یا خیر.
آیا ایجنت فایل ریشه را میخواند یا فقط نزدیکترین فایل را؟
اینجاست که اکثر افراد مدل را اشتباه متوجه میشوند، بنابراین ارزش دارد که به جای بازنویسی، از قرارداد بالادستی نقلقول کنیم:
یک AGENTS.md دیگر در هر بسته قرار دهید. ایجنتها بهطور خودکار نزدیکترین فایل را در درخت دایرکتوری میخوانند، بنابراین نزدیکترین فایل اولویت دارد و هر زیرپروژه میتواند دستورالعملهای اختصاصی خود را ارائه دهد.
و در مورد تداخلها:
نزدیکترین AGENTS.md به فایل ویرایششده برنده است؛ پرامپتهای صریح کاربر در چت، همه چیز را نادیده میگیرند.
عبارت "اولویت دارد" برای بسیاری از افراد به معنای "فایل ریشه نادیده گرفته میشود" است. اینطور نیست. در ابزارهایی که این قرارداد را پیادهسازی میکنند، تمام فایلهای موجود در مسیر از ریشه مخزن تا دایرکتوری کاری خوانده و با هم ترکیب میشوند. نزدیکترین فایل تنها زمانی برنده است که دو فایل در مورد یک موضوع واحد، مطالب متفاوتی بیان کنند.
Codex در مورد این مکانیزم صریح است: "Codex فایلها را از ریشه به پایین به هم متصل میکند و آنها را با خطوط خالی به هم میپیوندد. فایلهای نزدیکتر به دایرکتوری فعلی شما، راهنماییهای قبلی را نادیده میگیرند." Claude Code نیز همین مسیر را طی میکند. در شروع نشست، این ابزار "هر AGENTS.md و .claude/AGENTS.md در دایرکتوری کاری شما و دایرکتوریهای بالاتر از آن" را میخواند و مستندات آن مدل بارگذاری را بهوضوح بیان میکند: "تمام فایلهای کشفشده بهجای نادیده گرفتن یکدیگر، در متن (context) ادغام میشوند." دایرکتوریهای پایینتر از دایرکتوری کاری رفتار متفاوتی دارند: Claude Code فایل AGENTS.md یک زیردایرکتوری را در صورت نیاز بارگذاری میکند، "زمانی که Claude فایلی را در آنجا با ابزار Read باز کند."
دو نتیجه عملی از این موضوع حاصل میشود. فایل ریشه پیشوندی برای هر نشست در مخزن است، بنابراین با هر خط در آنجا طوری رفتار کنید که گویی هزینهای است که صد بار در هفته پرداخت میکنید. یک فایل در هر دایرکتوری تا زمانی که ایجنت فایلی را در آن دایرکتوری باز نکند، هزینهای ندارد؛ این یعنی جزئیات در آنجا ارزان هستند و جایگاهشان همانجاست.
این رفتار در تاریخ 27 اکتبر 2026 بر اساس مستندات Codex و Claude Code بررسی شد. ابزارها این قرارداد را کمی متفاوت پیادهسازی میکنند و تغییر هم میدهند، بنابراین قوانین بارگذاری را برای هر ایجنتی که تیم شما اجرا میکند، تأیید کنید.
چیدمان عملی برای یک مخزن با سه سرویس
repo/
AGENTS.md rules true everywhere, plus the map
apps/web/AGENTS.md TypeScript client, Vite, Vitest
services/worker/AGENTS.md Python queue consumer, pytest
infra/AGENTS.md Terraform and the deploy scriptsفایل ریشه (root) عمداً کوتاه نگه داشته شده است. این فایل مشخص میکند که کجا باید جستجو کرد و فقط قوانینی را در بر دارد که در تمام دایرکتوریها معتبر هستند.
# AGENTS.md
This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.
- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts
## Rules for the whole repository
- The package manager is `pnpm`. `npm install` writes a second lockfile
that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
`schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
in the same commit.فایل مخصوص هر دایرکتوری، جایی است که جزئیات در آن قرار میگیرند و میتواند به اندازه نیاز آن دایرکتوری طولانی باشد.
# apps/web
Browser client. Vite and React, TypeScript with `strict` on.
## Commands
- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.
## Conventions
- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
because the client attaches the auth header and retries on 429.
## Traps
- `pnpm build` does not type check. Vite strips the types instead of
checking them, so a broken type still produces a green build.
Run `pnpm typecheck` as a separate step.فایل worker همان ساختار را دارد اما محتوای آن متفاوت است: دستور نصب، pytest -q، دلیلی که مصرفکننده باید idempotent باقی بماند، و migration که باید پیش از موفقیت تستها اجرا شود. فایل infra جایی است که قوانینی را مینویسید که مانع از آسیبرسانی یک agent میشود. هرگز terraform apply را اجرا نکنید. terraform plan را اجرا کرده و در همانجا متوقف شوید، و backend وضعیت (state backend) که از قبل پیکربندی شده است را نام ببرید تا agent سعی نکند یک مورد جدید را مقداردهی اولیه کند.
دقت کنید که چه چیزی در هیچکدام از این فایلها وجود ندارد: توصیفی از اینکه هر سرویس برای چه کاری است. این موضوع مربوط به انسانهاست. Upstream نیز همین مرز را ترسیم میکند و میگوید «فایلهای README.md برای انسانها هستند: شروع سریع، توصیف پروژه و دستورالعملهای مشارکت»، در حالی که AGENTS.md «زمینه اضافی و گاهی دقیق مورد نیاز برای coding agents: مراحل ساخت، تستها و قراردادها» را حمل میکند. تفکیک بین AGENTS.md و یک README برای انسان جمله به جمله این مرز را بررسی میکند، و یک فایل DESIGN.md که ثبت میکند چرا کد به این شکل طراحی شده است سومین فایل را پوشش میدهد؛ فایلی که به جای دستورات، تصمیمات را توضیح میدهد.
چه کسی هنگام تغییر کد، فایل را بهروزرسانی میکند؟
یک قانون کلی وجود دارد که در فایل ریشه (root) اعمال میشود: هر کسی که کدی را در یک دایرکتوری تغییر میدهد، باید فایل AGENTS.md همان دایرکتوری را در همان commit بهروزرسانی کند.
این روش به دلایل فنی مؤثر است، نه دلایل فرهنگی. فایل موجود در هر دایرکتوری در همان diff کد قرار دارد، بنابراین بازبین (reviewer) در pull request هر دو را همزمان مشاهده میکند. فایل ریشه متعلق به همه است، که در عمل یعنی متعلق به هیچکس نیست و هرگز در diff که کسی در حال مطالعه آن است، دیده نمیشود.
این قانون را با یک بررسی (check) در pull request پشتیبانی کنید. این بررسی نزدیکترین فایل AGENTS.md را در بالای هر فایل تغییریافته پیدا میکند و در صورتی که آن فایل ویرایش نشده باشد، گزارش میدهد.
#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)
nearest_doc() {
d=$(dirname "$1")
while [ "$d" != "." ]; do
if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
d=$(dirname "$d")
done
echo "AGENTS.md"
}
printf '%s\n' "$changed" | while read -r f; do
[ -n "$f" ] || continue
case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
doc=$(nearest_doc "$f")
printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
echo "note: $f changed but $doc was not updated"
doneدر شاخهای که API client را بدون تغییر در مستندات بازنویسی کرده است، خروجی به این صورت خواهد بود:
note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updatedآن را به عنوان یک هشدار (warning) نگه دارید، نه یک خطای منجر به شکست (failure). یک مانع سخت باعث میشود افراد فقط یک خط خالی به فایل اضافه کنند تا CI سبز شود؛ فایلی که صرفاً برای راضی کردن یک ربات ویرایش شده باشد، ارزشی کمتر از نبودِ فایل دارد. هشدار باعث میشود بازبین سؤالی را مطرح کند، و این همان بخشی است که در عمل کارایی دارد.
چگونه متوجه شوم فایل AGENTS.md قدیمی شده است؟
امروز میتوانید دو بررسی انجام دهید و یک نشانه نیز در طول نشست (session) مشاهده خواهید کرد.
سن هر فایل را با سن کدی که توصیف میکند مقایسه کنید. دستور %cs تاریخ آخرین commit را با فرمت YYYY-MM-DD چاپ میکند.
for f in $(git ls-files '*AGENTS.md'); do
d=$(dirname "$f")
printf '%s doc:%s code:%s\n' "$f" \
"$(git log -1 --format=%cs -- "$f")" \
"$(git log -1 --format=%cs -- "$d")"
doneapps/web/AGENTS.md doc:2026-02-11 code:2026-08-07
services/worker/AGENTS.md doc:2026-07-29 code:2026-08-09
infra/AGENTS.md doc:2026-08-01 code:2026-08-01اگر تاریخ مستندات شش ماه عقبتر از تاریخ کد باشد، لزوماً به این معنی نیست که فایل اشتباه است. این فقط به شما میگوید که کدام فایل را باید زودتر مطالعه کنید؛ این تمام چیزی است که از یک بررسی یکثانیهای انتظار میرود.
به دنبال مسیرهایی بگردید که دیگر وجود ندارند. مستندات به یک روش بسیار خاص دچار فرسودگی میشوند: توصیف کدی که حذف شده است را ادامه میدهند. تمام مسیرها در این فایلها داخل backtick نوشته شدهاند، بنابراین استخراج و تست کردن آنها آسان است.
grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
[ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
doneبه جای خودکارسازی این مورد در CI، خروجی را شخصاً بررسی کنید. این دستور الگوهای glob مانند src/**/*.ts و هر URL که نقلقول کردهاید را نیز علامت میزند، زیرا هر دو شامل اسلش هستند و هیچکدام فایل روی دیسک نیستند. در نسخه Claude Code v2.1.283 یا بالاتر، دستور /doctor prompt-audit یک بررسی مشابه برای شما انجام میدهد: این دستور به دنبال «ارجاع به فایلها یا دستوراتی که وجود ندارند» و فایلهایی که با هم تناقض دارند میگردد، فایلهای AGENTS.md شما را بهصورت پیشفرض پوشش میدهد و تا زمانی که از آن نخواهید تغییرات پیشنهادی را اعمال کند، هیچ تغییری ایجاد نمیکند.
نشانه در طول نشست. عامل (agent) فایل را میخواند، سعی میکند src/api/client.ts را باز کند زیرا فایل به او گفته است، و ابزار این پاسخ را برمیگرداند:
No such file or directoryبنابراین عامل کار منطقی را انجام میدهد و یک wrapper برای fetch خودش مینویسد. این هزینه واقعی یک فایل قدیمی است. عامل مستندات شما را نادیده نمیگیرد. او از مستندات پیروی میکند، به مسیری میرسد که سه ماه پیش حذف شده است و کدی که از قبل دارید را دوباره میسازد. مهارتی مانند Ponytail، که عامل را به کوچکترین تغییرِ کارآمد محدود میکند، باعث میشود این غریزه بازسازی کد کمتر شود، اما نمیتواند کمکی را که فایل شما به مسیر اشتباه اشاره کرده است، پیدا کند.
آیا Claude Code فایلهای AGENTS.md را میخواند؟
بله، از نسخه v2.1.277 به بعد، Claude Code این فایلها را میخواند و رعایت دقیق قوانین آن اهمیت دارد، زیرا ساختار تو در تو به آن وابسته است. طبق مستندات در تاریخ 27 اکتبر 2026: "Claude Code میتواند AGENTS.md را به عنوان دستورالعملهای پروژه شما بخواند، بنابراین مخزنی که از قبل برای سایر ایجنتهای کدنویسی تنظیم شده است، بدون نیاز به افزودن CLAUDE.md، import یا تنظیمات اضافی کار میکند." مقدار پیشفرض Project instructions یعنی claude-md-or-agents-md، "فایلهای AGENTS.md شما را زمانی که هیچ CLAUDE.md یا CLAUDE.local.md در دایرکتوری کاری یا بالاتر از آن ندارید" میخواند. فایلهای تو در تو نیز پوشش داده میشوند: Claude فایل AGENTS.md یک زیردایرکتوری را "هنگامی که فایلی را در آنجا با ابزار Read باز میکند" میخواند، به شرطی که "آن زیردایرکتوری هیچکدام از سه فایل CLAUDE.md را نداشته باشد". آن سه فایل عبارتند از CLAUDE.md، .claude/CLAUDE.md و CLAUDE.local.md، بنابراین یک CLAUDE.local.md شخصی در apps/web برای متوقف کردن بارگذاری apps/web/AGENTS.md کافی است.
این موضوع توصیه قدیمی مبنی بر قرار دادن یک CLAUDE.md در کنار هر AGENTS.md را به یک تله تبدیل میکند. با وجود یک AGENTS.md و یک CLAUDE.md یا CLAUDE.local.md در دایرکتوری کاری یا بالاتر از آن، مستندات میگویند Claude "فقط فایلهای CLAUDE.md شما" را میخواند. یک .claude/CLAUDE.md نیز به همین صورت محاسبه میشود. یک فایل همراه در ریشه که حاوی یک خط خاص برای Claude باشد، تمام AGENTS.md موجود در مسیر را مخفی میکند و یک CLAUDE.local.md شخصی نیز همین کار را انجام میدهد. اگر میخواهید یکی را نگه دارید، /config را تایپ کرده و Project instructions را روی claude-md-and-agents-md تنظیم کنید که هر دو را میخواند؛ ابتدا CLAUDE.md هر دایرکتوری و سپس AGENTS.md آن.
شماره نسخه به تنهایی تأیید نمیکند که این کار انجام شده است. شما به v2.1.277 یا بالاتر نیاز دارید، اما پیش از v2.1.281 برخی نشستها، مانند نشستهای روی Amazon Bedrock یا نشستهایی که telemetry در آنها غیرفعال است، فقط فایلهای CLAUDE.md را میخوانند و در برخی موارد، اولین نشست پس از ارتقا از v2.1.276 یا قدیمیتر، AGENTS.md را نیز نادیده میگیرد: مستندات میگویند "Claude فایل AGENTS.md را از نشست بعدی شما میخواند". بنابراین خود نشست را بررسی کنید. در یک نشست تعاملی، Claude Code خطی مانند no CLAUDE.md found; AGENTS.md loaded: را به همراه مسیر چاپ میکند و در نسخههای فعلی، /memory فایل را لیست میکند. پیش از v2.1.280، /memory و /context فایلی مانند AGENTS.md که Claude مستقیماً میخواند را لیست نمیکردند، بنابراین در آن نسخهها از Claude بپرسید که دستورالعملهای پروژهاش چیست.
فرم import همچنان در جایی که Claude نمیتواند AGENTS.md را مستقیماً بخواند، صحیح است: یک نسخه قدیمیتر، نشستی پیش از v2.1.281 روی Amazon Bedrock یا با telemetry غیرفعال، نشستی که پلاگین داخلی خواننده آن غیرفعال است، یا پروژهای که یک CLAUDE.md با تنظیم Project instructions روی claude-md دارد. این را در services/worker/CLAUDE.md قرار دهید:
@AGENTS.md
## Claude Code
Use plan mode for changes under `services/worker/migrations/`.فرم symlink زمانی صحیح است که هیچ چیز خاصی برای افزودن به ابزار وجود نداشته باشد.
git ls-files '*AGENTS.md' | while read -r f; do
ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.mdln هنگام موفقیت چیزی چاپ نمیکند، بنابراین لیست را بررسی کنید: apps/web/CLAUDE.md -> AGENTS.md. سپس یک نشست را شروع کرده و /context را اجرا کنید، جایی که فایلهای بارگذاری شده در بخش Memory files ظاهر میشوند. در ویندوز، symlink نیاز به دسترسی Administrator یا Developer Mode دارد و Git یک symlink کامیت شده را به عنوان یک فایل متنی ساده checkout میکند مگر اینکه core.symlinks فعال باشد، که در غیر این صورت آن clone با یک CLAUDE.md تکخطی به جای دستورالعملهای شما باقی میماند. اگر هر کسی که مخزن را clone میکند روی ویندوز کار میکند، از import نوع @AGENTS.md استفاده کنید. اگر هر یک از این راهکارها را پیش از آنکه Claude Code بتواند AGENTS.md را به تنهایی بخواند تنظیم کردهاید، میتوانید آن را رها کنید: مستندات میگویند نگه داشتن import "هرگز باعث نمیشود Claude فایل AGENTS.md را دو بار بخواند" و یک CLAUDE.md که symlink شده است، یک بار خوانده میشود.
یک تله در این مورد وجود دارد. پس از /compact، فایل CLAUDE.md در ریشه پروژه دوباره از دیسک خوانده میشود، اما فایلهای تو در تو در زیردایرکتوریها دوباره تزریق نمیشوند. Claude Code آنها را در صورت نیاز، دفعه بعد که ایجنت با فایلی در آن دایرکتوری کار میکند، دوباره بارگذاری میکند. مستندات این موضوع را برای فایلهای CLAUDE.md توضیح دادهاند و compaction را به طور جداگانه برای AGENTS.md که مستقیماً خوانده میشود توصیف نکردهاند، بنابراین انتظار داشته باشید فایلهای تو در توی هر دو نام به همین صورت رفتار کنند. اگر به نظر میرسد یک قانون مربوط به هر دایرکتوری در اواسط یک نشست طولانی اعمال نمیشود، معمولاً دلیل آن همین است و خواندن هر فایلی در آن دایرکتوری، آن را دوباره فعال میکند.
تنظیماتی که سایر ایجنتها را به AGENTS.md هدایت میکنند
Codex فایل AGENTS.md را به صورت بومی میخواند. در هر سطح، ابتدا AGENTS.override.md را بررسی میکند که به یک دایرکتوری اجازه میدهد بدون ویرایش فایل مشترک، یک override محلی داشته باشد. هنگامی که حجم ترکیبی به 32 KiB یعنی project_doc_max_bytes پیشفرض میرسد، ادغام متوقف میشود، که این یکی دیگر از دلایل کوچک نگه داشتن فایل ریشه است.
Aider آن را از طریق .aider.conf.yml با خط read: AGENTS.md دریافت میکند.
Gemini CLI آن را از طریق .gemini/settings.json با { "context": { "fileName": "AGENTS.md" } } دریافت میکند.
مستندات بالادستی یک تغییر نام سازگار با عقب برای مخازنی که هنوز از نام قدیمی و مفرد استفاده میکنند ارائه میدهند: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.
در یک monorepo بسیار بزرگ، تنظیم claudeMdExcludes در Claude Code فایلهای والد را بر اساس مسیر یا glob نادیده میگیرد، که وقتی دایرکتوری تیم دیگری بالاتر از دایرکتوری شما قرار دارد، مفید است. الگوهای آن برای فایلهای AGENTS.md که Claude Code میخواند نیز اعمال میشود.
تفاوت این موضوع با حافظه عامل (agent memory) یا مهارت (skill) چیست؟
این مکانیزمها مشابه به نظر میرسند اما به شیوههای کاملاً متفاوتی دچار خطا میشوند؛ بنابراین ارزش دارد که دقیقاً بدانید به دنبال کدامیک هستید.
فایل AGENTS.md توسط شما نوشته میشود، در git کامیت میشود، در یک pull request بازبینی میشود و برای هر کسی که مخزن را clone کند، یکسان است. حافظه عامل توسط خود عامل نوشته میشود، خارج از مخزن ذخیره میشود و مختص یک ماشین خاص است. مستندات Claude Code نیز همین مرز را ترسیم میکنند: CLAUDE.md شامل «دستورالعملها و قوانین» است که شما مینویسید، حافظه خودکار شامل «آموختهها و الگوها» است که Claude مینویسد و دایرکتوری حافظه بین ماشینهای مختلف به اشتراک گذاشته نمیشود. آزمون ساده است: اگر یک واقعیت باید برای همکار شما در یک clone تازه صادق باشد، نمیتواند در حافظه قرار بگیرد. نحوه ماندگاری حافظه عامل بین نشستها نیمی از این تصویر را پوشش میدهد.
مهارت (skill) مورد سوم است. AGENTS.md زمینهای است که در هر نشست بارگذاری میشود؛ مهارت رویهای است که هنگام نیاز بارگذاری میشود. مستندات Claude Code یک قاعده کاربردی ارائه میدهند: «اگر یک ورودی یک رویه چندمرحلهای است یا فقط برای بخشی از کد منبع اهمیت دارد، آن را به یک مهارت یا یک قانون با دامنه محدود به مسیر (path-scoped) منتقل کنید.» نیمه دوم آن جمله دقیقاً همان چیزی است که AGENTS.md تو در تو حل میکند. نیمه اول همان چیزی است که مهارتهای عامل برای آن هستند و زمانی که یک رویه مشابه در بیش از یک مخزن مورد نیاز است، بهجای کپی کردن پاراگرافهای یکسان در ده فایل AGENTS.md مختلف، مهارت را بین مخازن به اشتراک بگذارید.
منابع بالادستی اشاره میکنند که «در زمان نگارش این متن، مخزن اصلی OpenAI دارای 88 فایل AGENTS.md است». همین عدد، کل استدلال است. یک مخزن بزرگ به یک فایل بزرگتر نیاز ندارد. به فایلهای کوچکتر بیشتری نیاز دارد که هر کدام در کنار کدی که توصیف میکنند قرار گرفته و مالکیت هر کدام با کسی باشد که آخرین بار آن کد را تغییر داده است.
FAQ
آیا فایل AGENTS.md تو در تو، جایگزین فایل ریشه میشود یا به آن اضافه میگردد؟
به آن اضافه میشود. مستندات بالادستی میگویند «نزدیکترین فایل اولویت دارد»، که این توصیفکننده رفتار در زمان تداخل است، نه آنچه بارگذاری میشود. Codex «فایلها را از ریشه به پایین به هم میچسباند و آنها را با خطوط خالی جدا میکند»، و Claude Code تمام فایلهایی را که هنگام حرکت از دایرکتوری کاری به سمت بالا پیدا میکند، به جای جایگزینی، با هم ترکیب میکند. نزدیکترین فایل تنها زمانی برنده است که دو فایل دستورالعملهای متفاوتی درباره یک موضوع واحد ارائه دهند. قوانین مشترک را یک بار در ریشه بنویسید و آنها را در هر دایرکتوری تکرار نکنید.
فایل AGENTS.md ریشه چقدر باید بزرگ باشد؟
آنقدر کوچک که برایتان مهم نباشد در ابتدای هر درخواستی که در آن مخزن ارسال میکنید، الصاق شود؛ چرا که دقیقاً همین اتفاق میافتد. مستندات Claude Code پیشنهاد میکنند که حجم هر فایل زیر 200 خط باشد و هشدار میدهد که فایلهای طولانیتر «میزان پایبندی را کاهش میدهند». Codex بهطور پیشفرض ادغام فایلهای دستورالعمل را در مجموع 32 KiB متوقف میکند. اگر فایل ریشه شما چهار سرویس را مستند کرده باشد، بخش بزرگی از آن برای هر وظیفه خاص، سربار اضافی است. جزئیات را به فایلهای هر دایرکتوری منتقل کنید و در ریشه فقط یک نقشه کلی باقی بگذارید.
چگونه از قدیمی شدن این فایلها جلوگیری کنم؟
یک قانون در فایل ریشه قرار دهید: هر کسی که کدی را در یک دایرکتوری تغییر میدهد، باید AGENTS.md همان دایرکتوری را نیز در همان commit بهروزرسانی کند. قرار دادن فایل در کنار کد باعث میشود این قانون رعایت شود، زیرا تغییرات در همان pull request قرار میگیرد که انسان در حال بررسی آن است. یک هشدار CI اضافه کنید که هر مسیر تغییریافته را به نزدیکترین AGENTS.md در بالادست آن نگاشت کند، و هر چند وقت یکبار git log -1 --format=%cs را در هر فایل با همان دستور اجرا شده روی دایرکتوری که مستند میکند، مقایسه کنید.
آیا Claude Code فایلهای AGENTS.md را میخواند؟
بله، از نسخه v2.1.277. طبق مستندات در تاریخ 27 اکتبر 2026، Claude Code بهطور پیشفرض AGENTS.md را میخواند، زمانی که شما هیچ CLAUDE.md یا CLAUDE.local.md در دایرکتوری کاری خود یا بالاتر از آن ندارید. همچنین زمانی که فایلی را در یک زیردایرکتوری با ابزار Read باز میکند و آن زیردایرکتوری خودش فاقد CLAUDE.md، .claude/CLAUDE.md یا CLAUDE.local.md باشد، AGENTS.md آن زیردایرکتوری را میخواند. در کنار هر AGENTS.md، یک CLAUDE.md اضافه نکنید: با داشتن یکی در دایرکتوری کاری یا بالاتر از آن، Claude فقط «فایلهای CLAUDE.md شما» را میخواند. اگر به یک CLAUDE.md هم نیاز دارید، Project instructions را در /config روی claude-md-and-agents-md تنظیم کنید، یا @AGENTS.md را در خط اول آن قرار دهید. دستور /memory را در یک نشست اجرا کنید و تأیید کنید که مسیر AGENTS.md در لیست ظاهر میشود.
قانونی که فقط گاهی اهمیت دارد را کجا قرار دهم؟
در AGENTS.md قرار ندهید. آن فایل در هر نشست بارگذاری میشود، بنابراین هر خط آن برای جلب توجه با درخواستی که واقعاً تایپ کردهاید، رقابت میکند. رویهای با چندین مرحله که گهگاه مورد نیاز است، متعلق به یک skill است که در صورت تقاضا بارگذاری میشود. قانونی که فقط برای یک دایرکتوری اعمال میشود، متعلق به AGENTS.md همان دایرکتوری است. حقیقتی که عامل میتواند مستقیماً از کد بخواند، مانند درخت دایرکتوری یا لیست وابستگیها، متعلق به هیچکدام نیست.