راهنمای کامل فایل AGENTS.md و نحوه استفاده از آن

فایل AGENTS.md چیست

فایل AGENTS.md یک فایل Markdown ساده در ریشهٔ مخزن است که به یک عامل کدنویسی (coding agent) می‌گوید چگونه روی آن پروژه کار کند. سایت رسمی آن را این‌گونه توصیف می‌کند: «یک README برای عامل‌ها: مکانی اختصاصی و قابل پیش‌بینی برای ارائهٔ زمینه و دستورالعمل‌هایی که به عامل‌های کدنویسی هوش مصنوعی کمک می‌کند تا روی پروژهٔ شما کار کنند.» این قالب توسط بنیاد Agentic AI تحت نظارت Linux Foundation مدیریت می‌شود و بیش از 20 عامل، از جمله Codex، Cursor، Jules، Devin و GitHub Copilot (تا ژوئیه 2026)، آن را می‌خوانند.

دلیل وجود این قرارداد، کاربردی است. فرد جدیدی که به تیم شما می‌پیوندد، فایل README را می‌خواند، دستور ساخت (build) را حدس می‌زند و اگر حدسش اشتباه بود، از کسی می‌پرسد. یک عامل نمی‌تواند سؤال بپرسد. عامل حدس می‌زند، دستور npm test را روی پروژه‌ای که از pnpm test استفاده می‌کند اجرا می‌کند، خطا را می‌خواند و چیز دیگری را امتحان می‌کند. شما برای تک‌تک آن توکن‌ها هزینه پرداخت می‌کنید. نوشتن دستور صحیح برای یک بار، کل این دسته از خطاها را حذف می‌کند.

هیچ فیلد الزامی وجود ندارد. سایت در این مورد صریح است: «AGENTS.md فقط یک Markdown استاندارد است. از هر سرتیتری که دوست دارید استفاده کنید؛ عامل به‌سادگی متنی که ارائه می‌دهید را تجزیه (parse) می‌کند.» این تمام مشخصات فنی است. ارزش این فایل در قالب آن نیست، بلکه در این است که فایلی در مسیری قرار دارد که همهٔ ابزارها از قبل آن را بررسی می‌کنند.

محل قرارگیری فایل و اولویت‌بندی آن

اولین فایل را در ریشه (root) مخزن قرار دهید. در یک monorepo می‌توانید فایل‌های بیشتری در هر زیرپروژه اضافه کنید؛ قاعده ساده است: «عامل‌ها (agents) به‌طور خودکار نزدیک‌ترین فایل در درخت دایرکتوری را می‌خوانند، بنابراین نزدیک‌ترین فایل اولویت دارد.» تضاد بین دو فایل به نفع فایلی که در حال ویرایش آن هستید حل می‌شود و هر چیزی که در چت تایپ کنید، هر دو فایل را نادیده می‌گیرد (override می‌کند).

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

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

چه مواردی باید در AGENTS.md قرار بگیرند

مواردی را بنویسید که یک عامل (agent) نمی‌تواند با خواندن کد متوجه آن‌ها شود. دستورات دقیق build، تست و lint باید در ابتدا و به شکلی که در ترمینال وارد می‌کنید، آورده شوند. دستور اجرای یک تست واحد را نیز اضافه کنید، زیرا عاملی که فقط نحوه اجرای کل مجموعه تست را می‌داند، آن را چهل بار اجرا خواهد کرد. قراردادهایی که با پیش‌فرض‌های ابزار متفاوت هستند را نام ببرید، زیرا عامل از پیش‌فرض‌ها آگاه است و فقط باید درباره انحراف شما از آن‌ها بداند. ساختار پیام commit و قوانین pull request را در صورت وجود اضافه کنید.

به‌اندازه کافی دقیق باشید تا بتوان ادعایی را بررسی کرد. «از تورفتگی 2-space استفاده کنید» یک دستورالعمل قابل‌استفاده است، زیرا یا انجام شده یا نشده است. «کد را به‌درستی فرمت کنید» چنین نیست، زیرا هیچ‌چیز در آن قابل‌تایید نیست. همین موضوع در مورد مکان‌ها صدق می‌کند: «هندلرهای API در src/api/handlers/ قرار دارند» بهتر از «فایل‌ها را سازمان‌دهی کنید» است.

قوانین منفی نیز ارزش ذکر کردن دارند. «هرگز فایل‌های موجود در dist/ را ویرایش نکنید، آن‌ها توسط npm run build تولید می‌شوند» از یک اشتباه خاص جلوگیری می‌کند و چون علت را بیان می‌کند، عامل می‌تواند موارد مشابهی که شما ننوشته‌اید را تشخیص دهد. قانونی درباره دامنه تغییرات (scope) نیز باید در اینجا قرار گیرد، زیرا عاملی که به قضاوت خودش واگذار شود، بیش از آنچه خواسته‌اید را بازنویسی می‌کند: یک مهارت پرکاربرد فقط بر اعمال کوچک‌ترین تغییرِ کارآمد تأکید دارد.

چه مواردی نباید در این فایل‌ها قرار گیرند

هرگز هیچ‌گونه اطلاعات محرمانه‌ای را در این فایل‌ها قرار ندهید. این فایل در git ثبت (commit) می‌شود، در ابتدای هر نشست (session) در context بارگذاری شده و در هر درخواست برای ارائه‌دهنده مدل ارسال می‌گردد. یک API key در فایل AGENTS.md به معنای وجود آن در تاریخچه مخزن (repository) و لاگ‌های شخص ثالث است. به‌جای درج مستقیم، به آن اشاره کنید: «رمز عبور پایگاه داده در .env قرار دارد که در gitignore لحاظ شده است؛ پیش از خواندن آن، اجازه بگیرید.» اصول کلی‌تر این موضوع در دور نگه داشتن اعتبارنامه‌ها از دسترس عامل پوشش داده شده است.

هر چیزی را که عامل می‌تواند با مشاهده مستقیم استخراج کند، حذف کنید. لیست دایرکتوری‌ها، کپی لیست وابستگی‌ها (dependencies) یا نمای کلی معماری که صرفاً نام پوشه‌ها را تکرار می‌کند؛ همگی یک هفته پس از نوشتن قدیمی می‌شوند و در این فاصله، در هر نشست بخشی از context را اشغال می‌کنند. روی دام‌ها و دلایل تمرکز کنید و از فهرست‌برداری بپرهیزید. تفکیک دلایل اهمیت دارد، زیرا عاملی که دلیل وجود یک ساختار غیرمعمول را نداند، ممکن است بی‌سروصدا آن را بازنویسی (refactor) کند؛ به همین دلیل است که نگهداری یک فایل DESIGN.md در کنار این فایل توصیه می‌شود.

CLAUDE.md نمونه‌ای از همین ایده در Claude Code است

ابزار Claude Code فایل CLAUDE.md را می‌خواند و به‌طور خودکار AGENTS.md را نمی‌خواند. فایل پروژه در ./CLAUDE.md یا ./.claude/CLAUDE.md قرار دارد، ترجیحات شخصی برای هر پروژه در ~/.claude/CLAUDE.md ذخیره می‌شود و یک سازمان می‌تواند فایلی در سطح ماشین را در /etc/claude-code/CLAUDE.md روی لینوکس قرار دهد. فایل‌های کشف‌شده از ریشه سیستم فایل تا دایرکتوری کاری شما به هم متصل می‌شوند، بنابراین فایلی که به محل اجرای نشست شما نزدیک‌تر است، در آخرین مرحله خوانده می‌شود. هر نشستی که در آن دایرکتوری شروع می‌کنید، همان پشته (stack) را بارگذاری می‌کند؛ این همان چیزی است که اجرای دو نشست همزمان روی یک ماشین را ممکن می‌سازد و آن نشست‌ها می‌توانند در حین اجرا، کارها را به یکدیگر محول کنند.

اگر مخزن شما از قبل دارای یک فایل AGENTS.md است، نسخه دومی از آن نگهداری نکنید. آن را وارد (import) کرده و سپس فقط موارد مختص Claude را به آن اضافه کنید:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

وقتی چیز اضافه‌ای برای افزودن ندارید، یک symlink کارساز است:

ln -s AGENTS.md CLAUDE.md

این دستور در صورت موفقیت، خروجی خاصی نمایش نمی‌دهد. در نشست بعدی خود، دستور /context را اجرا کنید و تأیید کنید که CLAUDE.md در بخش Memory files ظاهر می‌شود. اگر این فایل در آن لیست وجود ندارد، یعنی هرگز بارگذاری نشده و هیچ‌یک از محتویات آن اعمال نشده است. برای تولید پیش‌نویس اولیه به‌جای نوشتن دستی، دستور /init را اجرا کنید: این دستور کدبیس را می‌خواند و یک فایل اولیه تولید می‌کند؛ همچنین اگر فایل CLAUDE.md از قبل وجود داشته باشد، به‌جای بازنویسی، پیشنهاداتی برای بهبود آن ارائه می‌دهد.

هر فایل را زیر حدود 200 خط نگه دارید. فایل‌های طولانی‌تر بخش بیشتری از پنجره زمینه (context window) را اشغال می‌کنند و میزان پایبندی مدل کاهش می‌یابد. اگر می‌خواهید بدانید چه موارد دیگری برای آن فضا رقابت می‌کنند، آنچه واقعاً پنجره زمینه یک عامل را پر می‌کند این موضوع را تحلیل کرده است.

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

ابزارهایی که این فایل‌ها را برای شما می‌نویسند

دو پروژه در لیست ترندهای GitHub در تاریخ 30 July 2026 نشان می‌دهند که این قرارداد به کدام سمت حرکت می‌کند.

agent0ai/dox (با 1,368 ستاره تا جولای 2026) چارچوبی برای به‌روز نگه داشتن درختی از فایل‌های AGENTS.md است. این پروژه هیچ پکیج یا runtimeای ارائه نمی‌دهد. شما محتوای فایل AGENTS.md آن را در فایل AGENTS.md ریشه خود کپی می‌کنید و نصب به همین سادگی انجام می‌شود. برای پروژه‌ای که از قبل وجود دارد، به agent خود می‌گویید:

Initialize DOX tree for this project now.

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

فایل HUMAN.md، همان ترفند برای شما

Intuition-Lab/personal-model (با 1,260 ستاره تا ژوئیه 2026) همین الگو را به‌جای مخزن، روی یک شخص پیاده می‌کند. این پروژه فایل HUMAN.md شما را نه به‌عنوان فایلی که تایپ می‌کنید، بلکه به‌عنوان خروجی سیستم تعریف می‌کند: «مدلی زنده از آنچه اکنون اهمیت دارد، نحوه تصمیم‌گیری شما و مسیری که توجه‌تان به آن معطوف است.» این ابزار به‌صورت محلی روی macOS 13 یا نسخه‌های جدیدتر اجرا می‌شود، پس از دریافت مجوز از macOS فعالیت‌ها را ثبت می‌کند و نتیجه را از طریق MCP (پروتکل زمینه مدل) در اختیار عامل‌ها قرار می‌دهد. مسیر نصب کوتاه آن:

uv tool install personal-model
persome onboard
persome model open --after 30

برای بهره‌مندی از اکثر مزایای این روش، به هیچ‌کدام از این موارد نیاز ندارید. یک فایل HUMAN.md دست‌نویس حدود 20 خط است: نقش شما، منطقه زمانی، پشته (stack) فنی که واقعاً استفاده می‌کنید، تصمیماتی که قبلاً گرفته‌اید و نمی‌خواهید دوباره باز شوند، و میزان توضیحی که انتظار دارید دریافت کنید. این کار همان صرفه‌جویی در توضیحات تکراری را انجام می‌دهد که یک فایل پروژه انجام می‌دهد، با این تفاوت که یک لایه بالاتر قرار دارد.

یک هشدار: فایل HUMAN.md پروفایل یک شخص است، بنابراین ذاتاً حساس محسوب می‌شود. آن را در مخزن عمومی قرار ندهید. آن را در ~/.claude/CLAUDE.md یا در یک فایل CLAUDE.local.md که در gitignore قرار گرفته و در ریشه پروژه است بگذارید؛ این فایل در کنار فایل commit شده بارگذاری می‌شود و با آن به یک شکل رفتار خواهد شد.

یک قالب اولیه که می‌توانید کپی کنید

این متن به‌عمد کوتاه نگه داشته شده است. بخش‌هایی که کاربرد ندارند را حذف کنید و در برابر افزودن مواردی که نمی‌توانید به‌روز نگه دارید، مقاومت کنید.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

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

FAQ

آیا AGENTS.md همان فایل CLAUDE.md است؟

این دو فایل در واقع یک مفهوم واحد با دو نام متفاوت هستند. Claude Code فایل CLAUDE.md را می‌خواند و تا زمانی که آن‌ها را به هم متصل نکنید، AGENTS.md را نادیده می‌گیرد. یکی از فایل‌ها را به عنوان منبع اصلی در نظر بگیرید و دیگری را به آن لینک کنید؛ این کار را می‌توانید با قرار دادن خط @AGENTS.md در ابتدای فایل CLAUDE.md یا با استفاده از ln -s AGENTS.md CLAUDE.md انجام دهید. اگر دو نسخه کامل را به‌صورت جداگانه نگهداری کنید، پس از یک ماه محتوای آن‌ها با هم تداخل پیدا خواهد کرد.

آیا نوشتن AGENTS.md تضمین می‌کند که عامل (agent) از آن پیروی کند؟

خیر. محتوای این فایل به عنوان زمینه (context) ارائه می‌شود، بنابراین مدل آن را می‌خواند و معمولاً رعایت می‌کند، اما هیچ مکانیزمی مانع از انجام عملی که با آن در تضاد باشد، نمی‌شود. دستورالعمل‌های مبهم با کمترین قابلیت اطمینان اجرا می‌شوند و اگر دو فایل دستورات متناقضی داشته باشند، عامل به‌صورت تصادفی یکی را انتخاب می‌کند. برای قوانینی که باید همیشه رعایت شوند، از hook یا قوانین دسترسی (permission rule) استفاده کنید؛ این موارد توسط کلاینت اعمال می‌شوند و مستقل از تصمیم مدل هستند.

آیا AGENTS.md باید در git کامیت شود؟

بله، برای هر چیزی که در مورد پروژه صادق است: دستورات ساخت (build)، ساختار فایل‌ها و قراردادها. هدف اصلی فایل همین است، زیرا با این کار، عامل‌های هم‌تیمی‌های شما نیز با همان زمینه‌ای شروع به کار می‌کنند که شما دارید. هر مورد شخصی یا مختص به یک ماشین خاص باید در فایلی جداگانه قرار گیرد که در gitignore لحاظ شده باشد، و اعتبارنامه‌ها (credentials) نباید در هیچ‌کدام از این فایل‌ها باشند.

فایل HUMAN.md چیست و آیا به آن نیاز دارم؟

فایل HUMAN.md یک پروفایل ماشین‌خوان از یک شخص است، نه یک پروژه. این فایل نقش شما، محدودیت‌های شما و تصمیماتی که قبلاً اتخاذ کرده‌اید را در خود نگه می‌دارد تا در هر نشست (session) نیاز به بازنگری آن‌ها نباشد. برای شروع به هیچ ابزاری نیاز ندارید: بیست خط دست‌نویس در فایل دستورالعمل‌های سطح کاربر، بخش عمده‌ای از ارزش آن را برای شما فراهم می‌کند. با این فایل به عنوان داده‌های شخصی رفتار کنید و آن را در هیچ مخزنی (repository) که push می‌کنید، قرار ندهید.