تصور کنید هر بار که یک جلسه جدید با هوش مصنوعی شروع می‌کنید، باید تمام معماری پروژه و استانداردهای کدنویسی‌تان را از اول توضیح دهید. این فرسایش ذهنی اکنون با معرفی AGENTS.md به پایان می‌رسد؛ فایلی که به عنوان «منبع حقیقت» در مخزن کد قرار می‌گیرد و به عامل (Agent) — شبیه به یک دستیار متخصص که دفترچه راهنمای شرکت را همیشه در دست دارد — می‌گوید دقیقاً کجا را ویرایش کند و چه دستوراتی را برای تأیید اجرا نماید. این فایل به عامل می‌گوید از کدام دایرکتوری‌ها برای ویرایش استفاده کند و برای اعتبارسنجی چه دستوراتی را اجرا نماید.
این فایل که با فرمت Markdown نوشته می‌شود، مشخص می‌کند کدها کجا هستند، چه دستوراتی باید اجرا شوند و کدام تصمیمات باید حتماً توسط انسان گرفته شوند. از آنجا که این یک فرمت باز است، هیچ ساختار اجباری یا طرح سخت‌گیرانه‌ای (Schema) ندارد.
سال‌هاست که توسعه‌دهندگان با پدیده‌ای به نام «انحراف زمینه» (Context Drift) دست‌وپنجه نرم می‌کنند. فرض کنید دوشنبه به یک عامل می‌گویید یک صفحه جدید اضافه کند. شما رنگ‌های پروژه، محل قرارگیری سورس کد و دلیل ثابت ماندن ساختار ناوبری (Navigation) را توضیح می‌دهید. جمعه، یک مشارکت‌کننده دیگر با ابزاری متفاوت روی همان کد کار می‌کند. عامل او چون به تاریخچه چت دوشنبه دسترسی ندارد، یک طرح رنگی جدید پیشنهاد می‌دهد و ساختار ناوبری را بازسازماندهی می‌کند. تصمیمات هنوز در گفتگوی دوشنبه وجود دارند، اما هرگز وارد مخزن کد نشدند. این شکاف به این دلیل رخ می‌دهد که دستورالعمل‌ها معمولاً در تاریخچه چت‌ها می‌مانند، نه در خودِ کد.
همان‌طور که در تحلیل‌های پیشین ما درباره‌ی مدیریت زمینه در مدل‌های زبانی اشاره کردیم، انتقال دانش از لایه گفتگو به لایه ذخیره‌سازی، کلید پایداری در پروژه‌های بزرگ است. این رویکرد در واقع بخشی از یک روند گسترده‌تر است که در آن الگوهای مهندسی جایگزین روش‌های غیرساختاریافته در کدنویسی خودکار می‌شوند تا دقت خروجی‌ها افزایش یابد. به همین دلیل، بنیاد لینوکس (Linux Foundation) در اوت ۲۰۲۵ فرمت AGENTS.md را منتشر کرد. طبق گزارش‌ها، نام‌گذاری این فایل حاصل همکاری بین Amp و OpenAI بود. Amp ابتدا از نام مفرد AGENT.md استفاده می‌کرد، اما وقتی OpenAI دامنه متناظر با حالت جمع را ثبت کرد، Amp موافقت کرد که به نسخه جمع تغییر نام دهد. در ۲۰ اوت ۲۰۲۵، Amp این تغییر را رسماً اعلام کرد و اولویت را به یک استاندارد مشترک داد تا نام فایل اصلی خود.
تا ۹ دسامبر ۲۰۲۵، بنیاد هوش مصنوعی عامل‌محور (Agentic AI Foundation) گزارش داد که بیش از ۶۰ هزار پروژه متن‌باز و چارچوب‌های مختلف، این قرارداد نام‌گذاری را پذیرفته‌اند. این اتفاق باعث می‌شود یک برنامه‌نویس از Codex و دیگری از Cursor استفاده کند، اما هر دو ابزار دستورالعمل‌های یکسانی را از یک فایل بخوانند و نیازی به کپی‌های جداگانه از دستورالعمل‌های بیلد (Build) نباشد.
کالبدشکافی یک فایل AGENTS.md کارآمد
یک فایل دستورالعمل باکیفیت از عبارات مبهمی مثل «از بهترین روش‌ها پیروی کن» پرهیز می‌کند و دستورات concrete (عینی) می‌دهد. برای مثال، به‌جای عبارت «بهترین روش‌ها»، یک فایل مفید می‌نویسد: «فایل‌های منبع را در پوشه site/ ویرایش کن و به فایل‌های تولیدشده در site/build/ دست نزن». به همین ترتیب، به‌جای عبارت مبهم «بررسی‌ها را اجرا کن»، توسعه‌دهنده باید نام دقیق دستورات و دایرکتوری کاری آن‌ها را ذکر کند تا دستورالعمل قابل استفاده باشد.
به نقل از راهنمای dev.to، یک فایل مفید باید به چهار پرسش اساسی پاسخ دهد: از کجا شروع کنم؟ چه چیزی را اجرا کنم؟ چه بخش‌هایی را حفظ کنم؟ و تغییرات را چگونه تأیید کنم؟ ساختار پیشنهادی شامل این چهار بخش است:
- پروژه و چیدمان: توضیح کوتاه درباره هدف پروژه و پوشه‌های حیاتی که عامل باید درک کند.
- راه‌اندازی و تأیید: دستورات دقیق (مثلاً
npm run build)، محل اجرای آن‌ها و هرگونه پیش‌نیاز. - قراردادها و مرزها: الگوهای موجودی که باید تکرار شوند، فایل‌هایی که نباید دست بخورند و اقداماتی که نیاز به تأیید انسان دارند.
- اتمام کار: شواهدی که عامل باید گزارش دهد (مثل خلاصه تغییرات و تست‌های پاس‌شده) و نحوه توصیف مواردی که تست نشده‌اند.
برای اکثر مخازن کوچک، بودجه‌ای بین ۳۰ تا ۶۰ خط متن کوتاه کافی است. این یک «بودجه ویرایشی» است و نه یک محدودیت فرمتی؛ اگر ده خط تمام تصمیمات مهم را پوشش می‌دهد، توسعه‌دهنده باید همان‌جا متوقف شود. هدف این است که اشتباهات تکراری ثبت شوند تا دوباره رخ ندهند، نه اینکه یک دفترچه راهنمای جامع و خسته‌کننده نوشته شود.
مثال عملی: آکادمی Few-Shot
برای درک بهتر، نگاهی به نسخه کوتاه شده AGENTS.md وب‌سایت Few-Shot Academy بیندازیم. در اینجا اهداف مبهم به قوانین اجرایی تبدیل شده‌اند:
# دستورالعمل‌های پروژه
آکادمی Few-Shot یک برنامه آموزشی رایگان برای هوش مصنوعی زاینده (Generative AI) است. برای خوانندگانی بنویسید که هیچ پیش‌زمینه برنامه‌نویسی یا AI ندارند.
## چیدمان پروژه
site/docs/: صفحات آموزشی.site/blog/: مقالات تخصصی برای متخصصان.site/src/: اجزا و استایل‌های مشترک.site/build/: خروجی‌های تولیدشده؛ به‌جای این‌ها، منبع را ویرایش کن.
## راه‌اندازی و بررسی‌ها
- از Node.js ۲۲ یا جدیدتر استفاده کن.
- در پوشه
site/دستورnpm ciرا برای نصب وابستگی‌ها اجرا کن. - بعد از تغییرات سایت، این دستورات را در
site/اجرا کن:npm run typecheckوnpm run build. - برای تغییرات بصری، چیدمان موبایل، ناوبری کیبورد و هر دو تم روشن و تاریک را چک کن.
## قوانین کاری
- قبل از ویرایش، صفحه مربوطه و مثال‌های اطراف را بخوان.
- از توکن‌های طراحی در
site/src/css/custom.cssاستفاده کن. - URLهای منتشرشده را حفظ کن.
- ادعاهای واقعی را با منابع اصلی تطبیق بده.
- تغییرات را متمرکز نگه دار و کارهای غیرمرتبط را حفظ کن.
- قبل از Push، Merge یا Deploy حتماً بپرس.
## قبل از پایان
- تغییرات و تست‌های پاس‌شده را خلاصه کن.
- مواردی را که نتوانستی تأیید کنی و دلیلش را بنویس.
باید به خاطر داشت که این‌ها همچنان دستوراتی هستند که یک مدل دریافت می‌کند، بنابراین نظارت انسانی ضروری است. در حالی که دستور «دیپلوی نکن» راهنمای مفیدی است، اما دسترسی واقعی به دیپلوی باید از طریق مجوزها و کنترل‌های تأیید مدیریت شود. مستندات Anthropic صراحتاً اشاره می‌کند که این فایل‌ها با تنظیمات اجباری (Enforced Configuration) متفاوت هستند و صرفاً راهنما محسوب می‌شوند.
سازگاری ابزارها و راه‌اندازی
تا ۸ سپتامبر ۲۰۲۶، اکثر ابزارهای بزرگ کدنویسی AI این فایل را می‌شناسند. اما توسعه‌دهندگان نباید فرض کنند که یک افزونه ادیتور، یک عامل خط فرمان (CLI) و یک عامل Pull-Request میزبانی‌شده، دستورات را یکسان بارگذاری می‌کنند، حتی اگر نام محصول یکسان باشد.
بسیاری از ابزارها شناسایی در سطح ریشه (Root) را به‌صورت خودکار انجام می‌دهند:
- Codex: خودکار. راهنمایی‌ها را در مسیر ریشه تا دایرکتوری کاری ترکیب می‌کند. فایل
AGENTS.override.mdاولویت بیشتری نسبت بهAGENTS.mdدر همان دایرکتوری دارد. - Cursor Agent: خودکار. فایل‌های تو در تو را به دایرکتوری مربوطه و فرزندان آن اعمال می‌کند؛ دستورات خاص‌تر اولویت دارند.
- GitHub Copilot (در VS Code): خودکار. بارگذاری ریشه به‌طور پیش‌فرض فعال است، اما شناسایی تو در تو یک گزینه آزمایشی جداگانه است.
- Cascade (Windsurf/Devin Desktop): خودکار. دستورات ریشه همیشه فعال هستند و فایل‌های زیرپوشه فقط برای آن بخش خاص از پروژه اعمال می‌شوند.
- Amp: خودکار. دستورات را در دایرکتوری کاری، والدین و زیرپوشه‌های مرتبط شناسایی می‌کند.
- Cline: خودکار. فایل را می‌شناسد و کاربران می‌توانند در پنل Rules بررسی کنند که آیا قانون شناسایی‌شده فعال است یا خیر.
برخی ابزارها به یک پل ارتباطی نیاز دارند تا به استاندارد مشترک متصل شوند:
- Claude Code: به‌طور پیش‌فرض
CLAUDE.mdرا می‌خواند. برای استفاده از استاندارد مشترک، عبارت@AGENTS.mdرا در فایلCLAUDE.mdریشه قرار دهید. این کار دستورات مشترک را در شروع جلسه وارد (Import) می‌کند. متناوباً در macOS یا Linux، می‌توان با دستورln -s AGENTS.md CLAUDE.mdیک symlink ساخت (اگر فایل CLAUDE.md وجود نداشته باشد). متد Import برای کاربران ویندوز ترجیح داده می‌شود تا نیاز به دسترسی‌های خاص برای symlink نباشد. - Gemini CLI: پیش‌فرض آن
GEMINI.mdاست. کاربران باید کد زیر را در.gemini/settings.jsonادغام کنند:{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }. این کار اجازه می‌دهد راهنمایی‌های خاص Gemini بدون تکرار قوانین مشترک، قابل شناسایی باقی بمانند.
مدیریت زمینه و مقیاس
توسعه‌دهندگان باید بین جزئیات و پنجره متنی (Context Window) — شبیه به میز کاری که فقط جای چند ورق کاغذ دارد و نمی‌توان کل کتابخانه را روی آن پهن کرد — تعادل ایجاد کنند. در حالی که تقسیم دستورات به چندین فایل پشتیبانی می‌شود، وارد کردن تعداد زیادی فایل حجیم می‌تواند زمینه شروع (Startup Context) را متورم کند. برای مثال، Codex محدودیتی در حدود ۳۲ کیلوبایت برای مجموع دستورالعمل‌های پروژه دارد.
برای حفظ کارایی، رویکرد لایه‌ای پیشنهاد می‌شود:
۱. AGENTS.md ریشه: کوتاه و برای دستورات روزمره (مثلاً «از این رنگ‌ها استفاده کن»).
۲. مستندات پروژه: فایل‌های جداگانه برای معماری بلندمدت و دلیل تصمیمات طراحی (مثلاً «چرا این پالت رنگی را حفظ کردیم»). این کار از ایجاد پنج خلاصه متداخل که به‌روزرسانی آن‌ها فراموش شود، جلوگیری می‌کند.
۳. یادداشت‌های تحویل (Handoff): فایل‌های موقت برای ثبت وضعیت کارهای ناتمام، سوالات حل‌نشده و گام‌های بعدی بین جلسات. Anthropic استفاده از فایل‌های پیشرفت (Progress files) را در کنار تاریخچه Git برای این منظور توصیف می‌کند.
این تفکیک باعث می‌شود عامل هنگام یک اصلاح ساده در CSS، توکن‌های خود را برای خواندن یادداشت‌های معماری هدر ندهد. برای کوچک نگه داشتن زمینه شروع، راهنمای ریشه باید کوتاه باشد و به عامل دستور دهد که مستندات پشتیبان را فقط زمانی بخواند که تسک مربوط به آن باشد. یک پرامپت «این پروژه را ادامه بده» می‌تواند به عامل بگوید یادداشت تحویل را بخواند، اما نمی‌تواند جزئیاتی را بازیابی کند که هرگز ذخیره نشده‌اند.
تحلیل تحریریه
این تغییر نشان‌دهنده گذار از «مهندسی پرامپت» (Prompt Engineering) به «مهندسی مخزن» (Repository Engineering) است. با تبدیل دستورالعمل‌های عامل به مصنوعات کد (Code Artifacts)، صنعت پذیرفته است که عوامل AI اکنون اعضای دائمی چرخه حیات توسعه هستند و به همان کنترل نسخه و استانداردی نیاز دارند که خودِ سورس کد دارد. این تحول در واقع تبدیل دستورالعمل‌های عامل‌های هوش مصنوعی به کد نسخه‌مند در مخزن است که مدیریت تغییرات را برای تیم‌های بزرگ تسهیل می‌کند.
برای توسعه‌دهنده فردی، این کار بار شناختیِ آماده‌سازی AI را کاهش می‌دهد. به‌جای نگهداری کتابخانه‌ای از پرامپت‌های سیستمی پیچیده در یک اپلیکیشن یادداشت، پروژه برای هر عاملی که وارد مخزن می‌شود، خود-مستند (Self-documenting) می‌شود. برنده واقعی در اینجا نگهدارندگان پروژه‌های متن‌باز هستند که اکنون می‌توانند مشارکت‌های سازگاری را در اکوسیستم پراکنده ابزارهای AI تضمین کنند. برای درک عمیق‌تر از نحوه پیاده‌سازی این ساختار، می‌توان به سازوکار AGENTS.md برای هدایت سلسله‌مراتبی عامل‌ها اشاره کرد که نحوه مدیریت دستورات در سطوح مختلف پروژه را بررسی می‌کند.
برای اجرای این مورد امروز، یک فایل AGENTS.md در ریشه پروژه خود بسازید و سه مورد از رایج‌ترین قوانین «این کار را نکنید» (Don'ts) را در آن بنویسید. برای تست، یک جلسه جدید شروع کنید و یک ویرایش کوچک در صفحه امتحان کنید. بررسی کنید آیا عامل منبع را پیدا کرد، از طراحی موجود استفاده کرد، تست‌های درست را اجرا کرد و مواردی را که نتوانست تأیید کند گزارش داد یا خیر. اگر قانونی را نادیده گرفت، بررسی کنید کدام فایل‌ها بارگذاری شده‌اند و آیا دستورات متضاد هستند یا خیر، سپس متن را اضافه کنید. هدف این است که از توضیح مجدد تصمیمات یکسان جلوگیری شود در حالی که دسترسی به آن‌ها آسان و نگهداری‌شان ساده باشد.
اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.
گفتگو