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

معنای فایل‌های AGENTS.md تو در تو در یک monorepo

وجود فایل‌های AGENTS.md تو در تو در یک monorepo به این معناست که یک فایل کوچک در ریشه مخزن و یک فایل دیگر در داخل هر دایرکتوری سرویس قرار دارد. فایل ریشه شامل چند قانون کلی است که در همه جا صدق می‌کنند، به همراه نقشه‌ای که نشان می‌دهد سایر فایل‌ها کجا قرار دارند. هر فایل سرویس، دستورات و قراردادهای مربوط به همان دایرکتوری را در خود جای می‌دهد. بنابراین، عاملی (agent) که در حال ویرایش services/worker/queue.py است، فایل ریشه و فایل کاری مربوطه را می‌خواند و هیچ بخشی از حافظه (context) خود را صرف بخش front end که هرگز با آن سر و کار نخواهد داشت، نمی‌کند.

هیچ چیزی برای نصب وجود ندارد. AGENTS.md یک قرارداد است و پروژه بالادستی (upstream) این موضوع را به صراحت بیان می‌کند:

AGENTS.md صرفاً یک Markdown استاندارد است. از هر سرتیتری که می‌خواهید استفاده کنید؛ عامل به سادگی متنی را که ارائه می‌دهید، تجزیه (parse) می‌کند.

به همین دلیل است که یادگیری اصولی این تکنیک ارزشمند است. فرمت آن تغییر نخواهد کرد. آنچه ممکن است دچار مشکل شود، مکان قرارگیری و نگهداری فایل‌هاست که هر دوی این‌ها وظیفه شما هستند.

چرا یک فایل 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) برسد، از ادغام آن‌ها خودداری می‌کند. فایلی در ریشه که چهار سرویس را مستند می‌کند، برای هر تسک، بودجه context را صرف سه سرویس دیگر می‌کند.

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

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

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

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

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

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

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

عبارت "اولویت دارد" (takes precedence) برای بسیاری از افراد به این معنی است که "فایل root نادیده گرفته می‌شود". این‌طور نیست. در ابزارهایی که این قرارداد را پیاده‌سازی می‌کنند، هر فایلی که در مسیر از root مخزن تا دایرکتوری کاری قرار دارد، خوانده و با هم ترکیب می‌شود. نزدیک‌ترین فایل تنها زمانی برنده است که دو فایل درباره یک موضوع واحد، موارد متفاوتی را بیان کنند.

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

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

این رفتار در آگوست 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 را اجرا کرده و در همان‌جا متوقف شوید، و state backend که از قبل پیکربندی شده است را نام ببرید تا agent سعی نکند یک مورد جدید را مقداردهی اولیه کند.

به آنچه در هیچ‌یک از این فایل‌ها وجود ندارد دقت کنید: توصیفی از اینکه هر سرویس برای چه کاری است. این موضوع مربوط به انسان‌هاست. Upstream نیز همین مرز را ترسیم می‌کند و می‌گوید «فایل‌های README.md برای انسان‌ها هستند: شروع سریع، توصیف پروژه و دستورالعمل‌های مشارکت»، در حالی که AGENTS.md شامل «زمینه اضافی و گاهی دقیق مورد نیاز برای agentهای کدنویسی است: مراحل ساخت، تست‌ها و قراردادها». تفکیک بین 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 را بازنویسی کرده اما مستندات را تغییر نداده است، خروجی به این شکل خواهد بود:

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

مهارت (skill) مورد سوم است. فایل AGENTS.md زمینه‌ای است که در هر نشست بارگذاری می‌شود؛ مهارت رویه‌ای است که هنگام نیاز بارگذاری می‌شود. مستندات Claude Code یک قاعده کاربردی ارائه می‌دهد: «اگر یک ورودی یک رویه چندمرحله‌ای است یا فقط برای بخشی از کد منبع اهمیت دارد، آن را به یک مهارت یا یک قانون با دامنه مسیر (path-scoped) منتقل کنید.» نیمه دوم آن جمله دقیقاً همان چیزی است که یک AGENTS.md تو در تو حل می‌کند. نیمه اول همان چیزی است که مهارت‌های عامل برای آن هستند، و هنگامی که همان رویه در بیش از یک مخزن مورد نیاز است، مهارت را بین مخازن به اشتراک بگذارید تا اینکه همان پاراگراف‌ها را در ده فایل مختلف AGENTS.md کپی کنید.

Upstream اشاره می‌کند که «در زمان نگارش، مخزن اصلی 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 را می‌خواند؟

خیر. تا اوت 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 همان دایرکتوری است. حقیقتی که عامل (agent) می‌تواند مستقیماً از کد بخواند، مانند ساختار درختی دایرکتوری یا لیست وابستگی‌ها، متعلق به هیچ‌کدام نیست.