مدیریت فایل‌های AGENTS.md تو در تو در Monorepo

معنای فایل‌های 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) دارد. این فایل‌ها در ابتدای نشست بارگذاری می‌شوند، پیش از آنکه ایجنت بداند شما چه چیزی خواهید پرسید. مستندات Claude Code عددی را برای آن مشخص کرده است: «هدف را زیر 200 خط در هر فایل CLAUDE.md نگه دارید. فایل‌های طولانی‌تر کانتکست بیشتری مصرف کرده و میزان پایبندی را کاهش می‌دهند.» Codex زمانی که اندازه فایل‌های دستورالعمل به 32 کیلوبایت برسد، یعنی مقدار پیش‌فرض project_doc_max_bytes، دیگر آن‌ها را ادغام نمی‌کند. فایلی در ریشه که چهار سرویس را مستند می‌کند، این بودجه را برای هر تسک، صرف سه سرویس دیگر می‌کند.

دستورالعمل‌ها شروع به نقض یکدیگر می‌کنند. دایرکتوری وب به pnpm test نیاز دارد. worker به pytest -q نیاز دارد. وقتی این قوانین در یک فایل نوشته می‌شوند، هر قانون فقط گاهی درست است، بنابراین ایجنت باید حدس بزند کدام‌یک اعمال می‌شود. مستندات Claude Code نتیجه را این‌گونه توصیف می‌کند: «اگر دو قانون با هم در تضاد باشند، Claude ممکن است یکی را به دلخواه انتخاب کند.» یک فایل در هر دایرکتوری، حدس زدن را حذف می‌کند، زیرا تنها یکی از آن دو قانون در کانتکست قرار دارد. وقتی قانونی که مطمئن هستید به‌وضوح نوشته‌اید نادیده گرفته می‌شود، بررسی دلایلی که یک دستورالعمل هرگز اعمال نمی‌شود بهتر از بازنویسی متن برای بار چهارم است.

این فایل با حقایقی پر می‌شود که ایجنت می‌تواند از کد بخواند. درختی از دایرکتوری‌ها، لیستی از وابستگی‌ها، خلاصه‌ای از کاری که هر پکیج انجام می‌دهد. بررسی /doctor در Claude Code دقیقاً برای حذف همین موارد وجود دارد. این بررسی «محتوایی که Claude می‌تواند از codebase استخراج کند، مانند ساختار دایرکتوری‌ها، لیست وابستگی‌ها و نمای کلی معماری را حذف می‌کند» و «دام‌ها، منطق‌ها و قراردادهایی که با تنظیمات پیش‌فرض ابزارها متفاوت هستند» را حفظ می‌کند. آن جمله بهترین آزمونی است که می‌شناسم تا مشخص شود آیا یک خط اصلاً به آن فایل تعلق دارد یا خیر.

آیا ایجنت فایل ریشه را می‌خواند یا فقط نزدیک‌ترین فایل را؟

این بخشی است که اکثر افراد مدل آن را اشتباه متوجه می‌شوند، بنابراین ارزش دارد که به جای بازنویسی، مستقیماً به قرارداد بالادستی (upstream) استناد کنیم:

یک فایل AGENTS.md دیگر درون هر بسته قرار دهید. ایجنت‌ها به‌طور خودکار نزدیک‌ترین فایل را در درخت دایرکتوری می‌خوانند، بنابراین نزدیک‌ترین فایل اولویت دارد و هر زیرپروژه می‌تواند دستورالعمل‌های اختصاصی خود را ارائه دهد.

و در مورد تداخل‌ها:

نزدیک‌ترین فایل AGENTS.md به فایلی که ویرایش می‌شود، اولویت دارد؛ دستورات صریح کاربر در چت، همه چیز را نادیده می‌گیرند.

عبارت «اولویت دارد» برای بسیاری از افراد به این معنی است که «فایل ریشه نادیده گرفته می‌شود». این‌طور نیست. در ابزارهایی که این قرارداد را پیاده‌سازی می‌کنند، تمام فایل‌های موجود در مسیر از ریشه مخزن تا دایرکتوری کاری خوانده و با هم ترکیب می‌شوند. نزدیک‌ترین فایل تنها زمانی اولویت پیدا می‌کند که دو فایل در مورد یک موضوع واحد، دستورات متفاوتی داشته باشند.

Codex در مورد این مکانیزم صریح است: «Codex فایل‌ها را از ریشه به پایین به هم متصل می‌کند و آن‌ها را با خطوط خالی به هم می‌چسباند. فایل‌هایی که به دایرکتوری فعلی شما نزدیک‌تر هستند، بر راهنمایی‌های قبلی ارجحیت دارند.» Claude Code نیز برای نام فایل مخصوص خود همین مسیر را طی می‌کند. فایل‌های موجود در سلسله‌مراتب دایرکتوری بالاتر از دایرکتوری کاری، «در هنگام راه‌اندازی به‌طور کامل بارگذاری می‌شوند» و «تمام فایل‌های کشف‌شده به جای جایگزینی یکدیگر، در متن (context) ترکیب می‌شوند.» دایرکتوری‌های پایین‌تر از دایرکتوری کاری رفتار متفاوتی دارند: Claude Code آن فایل‌ها را در صورت نیاز بارگذاری می‌کند، «زمانی که Claude فایل‌های موجود در آن دایرکتوری‌ها را می‌خواند.»

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

این رفتار در آگوست 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")"
done

apps/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 قرار ندهید. این دستور همچنین الگوهایی مانند src/**/*.ts و هر URL که نقل‌قول کرده‌اید را علامت‌گذاری می‌کند، زیرا هر دو شامل اسلش هستند و هیچ‌کدام فایل موجود روی دیسک نیستند.

نشانه در طول یک نشست. عامل (agent) فایل را می‌خواند، تلاش می‌کند src/api/client.ts را باز کند زیرا فایل به او چنین دستوری داده است، و ابزار این پاسخ را برمی‌گرداند:

No such file or directory

بنابراین عامل کار منطقی را انجام می‌دهد و wrapper مخصوص به خود یعنی fetch را می‌نویسد. این هزینه واقعی یک فایل قدیمی است. عامل مستندات شما را نادیده نمی‌گیرد. او از مستندات پیروی می‌کند، به مسیری می‌رسد که سه ماه پیش حذف شده است، و کدی را که از قبل دارید دوباره بازسازی می‌کند. مهارتی مانند Ponytail که عامل را به کوچک‌ترین تغییرِ کارآمد محدود می‌کند، این غریزه بازسازی را نادرتر می‌کند، اما نمی‌تواند کمکی را که فایل شما به اشتباه به جای دیگری اشاره کرده است، پیدا کند.

آیا Claude Code فایل‌های AGENTS.md را می‌خواند؟

خیر، و ارزشش را دارد که این موضوع را صریح بیان کنیم، زیرا ساختار تو در تو به آن وابسته است. تا اوت 2026، مستندات بیان می‌کنند: "Claude Code فایل CLAUDE.md را می‌خواند، نه AGENTS.md." این الگو همچنان کار می‌کند، فقط کافی است یک CLAUDE.md در کنار هر AGENTS.md داشته باشید.

فرم import زمانی مناسب است که می‌خواهید خطوط اختصاصی ابزار را به خطوط مشترک اضافه کنید. این مورد را در 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.md

دستور ln در صورت موفقیت چیزی چاپ نمی‌کند، بنابراین لیست را بررسی کنید: apps/web/CLAUDE.md -> AGENTS.md. سپس یک نشست (session) را شروع کرده و /context را اجرا کنید، که در آن فایل‌های بارگذاری‌شده در بخش Memory files ظاهر می‌شوند. در ویندوز، symlink نیاز به دسترسی Administrator یا حالت Developer Mode دارد، بنابراین در آنجا از import نوع @AGENTS.md استفاده کنید.

یک تله در این مورد وجود دارد. پس از /compact، فایل ریشه دوباره از دیسک خوانده می‌شود، اما فایل‌های تو در تو در زیرپوشه‌ها دوباره تزریق نمی‌شوند. آن‌ها دفعه بعد که عامل (agent) فایلی را در آن پوشه بخواند، بازمی‌گردند. اگر به نظر می‌رسد یک قانونِ مختصِ پوشه در اواسط یک نشست طولانی اعمال نمی‌شود، معمولاً دلیلش همین است و با دست زدن (touch) به هر فایلی در آن پوشه، قانون دوباره فعال می‌شود.

تفاوت این موضوع با حافظه عامل (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 diff که انسان در حال مطالعه آن است، ظاهر می‌شود. یک هشدار CI اضافه کنید که هر مسیر تغییریافته را به نزدیک‌ترین AGENTS.md در بالای آن نگاشت کند، و هر چند وقت یک‌بار خروجی git log -1 --format=%cs را در هر فایل با همان دستور اجرا شده روی دایرکتوری که مستند می‌کند، مقایسه کنید.

آیا Claude Code فایل‌های AGENTS.md را می‌خواند؟

خیر. تا اوت 2026 مستندات بیان می‌کنند که «Claude Code فایل CLAUDE.md را می‌خواند، نه AGENTS.md.» یک فایل CLAUDE.md در همان دایرکتوری ایجاد کنید که در خط اول آن @AGENTS.md قرار دارد؛ این کار فایل مشترک را بارگذاری کرده و به شما اجازه می‌دهد دستورالعمل‌های خاص Claude را در زیر آن اضافه کنید. یک symlink که با ln -s AGENTS.md CLAUDE.md ایجاد شده باشد، زمانی که مورد اضافه‌ای برای افزودن وجود ندارد کار می‌کند، هرچند در ویندوز به دسترسی Administrator یا Developer Mode نیاز دارد. دستور /context را در یک نشست اجرا کنید و تأیید کنید که فایل در بخش Memory files ظاهر می‌شود.

قانونی که فقط گاهی اهمیت دارد را کجا قرار دهم؟

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