پذیرش گستردهٔ AGENTS.md در برابر پافشاری Cline بر ساختار اختصاصی

تصور کنید یک فایل متنی ساده در ریشه پروژه شما، رفتار بیش از ۳۰ دستیار کدنویسی مختلف را دیکته کند. این وعدهٔ AGENTS.md است؛ سیستمی که «تغییر تدریجی دستورات» (Instruction Drift) را حذف می‌کند تا توسعه‌دهندگان دیگر مجبور نباشند برای هر ابزار، فایل قوانین جداگانه و گاه متضاد بنویسند. این مشکل زمانی رخ می‌دهد که برنامه‌نویس باید برای GitHub Copilot، Cursor و Aider دستورالعمل‌های مجزا را نگهداری کند که در نهایت منجر به تضاد در راهنمایی‌های یک کدبیس واحد می‌شود.

این استاندارد برای حل بحران پراکندگی در اکوسیستم ابزارهای کدنویسی آمد. پیش از این، یک تیم مجبور بود هم‌زمان فایل copilot-instructions.md برای GitHub Copilot، پوشه .cursorrules/ برای Cursor و فایل .clinerules/ برای Cline را مدیریت کند. اگر پروژه از Codex CLI برای یکپارچه‌سازی مداوم (CI) استفاده می‌کرد، یک فایل دیگر نیز مورد نیاز بود. هر زمان که یک قرارداد پروژه تغییر می‌کرد — مثلاً جایگزینی npm با pnpm — برنامه‌نویس باید تمام این فایل‌ها را به‌صورت دستی به‌روز می‌کرد یا با این ریسک مواجه می‌شد که هوش مصنوعی کدهایی قدیمی و منسوخ تولید کند. این چالش با پدیده‌ای شناخته می‌شود که به دلیل منسوخ شدن سریع تنظیمات دستیارها، منجر به «پوسیدگی متنی» در پروژه‌ها می‌گردد. پس از شش ماه پیش‌برد پروژه، رایج بود که پنج فایل دستورالعمل تقریباً یکسان وجود داشته باشد که دیگر با هم هم‌خوانی نداشتند. این چرخه تکراری به‌روزرسانی پنج نقطه برای یک قرارداد واحد، دقیقاً همان چیزی است که AGENTS.md برای حل آن ساخته شد.

همان‌طور که در تحلیل‌های پیشین ما درباره‌ی مدیریت زمینه در مدل‌های زبانی اشاره کردیم، حجم زیاد داده‌های متناقض در پنجره متنی، نرخ خطای مدل را بالا می‌برد. AGENTS.md که در اوت ۲۰۲۵ توسط OpenAI منتشر شد و اکنون تحت نظارت Agentic AI Foundation (زیرمجموعه بنیاد لینوکس) است، یک فایل Markdown ساده است که به هیچ اسکیما (Schema)، فرانت‌متر YAML یا سینتکس پیچیده‌ای نیاز ندارد. تا اواسط ۲۰۲۶، این استاندارد پذیرشی سریع داشت و در بیش از ۶۰ هزار مخزن متن‌باز ظاهر شد تا شکاف بین راهنمایهای انسان‌محور (README) و دستورالعمل‌های عامل‌محور (Agent-centric) را پر کند.

طبق اعلام منابع رسمی، اکثر ابزارهای مدرن اکنون AGENTS.md را به‌صورت بومی از ریشه مخزن می‌خوانند بدون اینکه نیاز به تنظیمات اضافی باشد. این لیست شامل موارد زیر است:

• GitHub Copilot: خواندن مستقیم از ریشه مخزن.
• Kilo Code: پشتیبانی پیش‌فرض فعال است.
• Cursor، Aider، Devin Desktop، Amp، OpenCode، Gemini CLI و Codex CLI.
• بیش از ۳۰ ابزار دیگر که در سایت رسمی لیست شده‌اند.

اما Cline استثنای اصلی است. فرمت بومی قوانین Cline، پوشه .clinerules/ و ساختار فایل داخلی خودش است. فایل AGENTS.md در ریشه پروژه در Cline به‌گونه‌ای که در سایر ابزارها هست، به‌طور خودکار شناسایی نمی‌شود. اگرچه Cline می‌تواند یک فایل سراسری در مسیر ~/.agents/AGENTS.md را بخواند، اما این موضوع با فایل‌های اختصاصی هر پروژه تفاوت دارد. این اتفاق یک باگ نیست، بلکه یک انتخاب طراحی خاص است که توسعه‌دهندگان باید برای جلوگیری از این تصور که «یک فایل تمام ابزارها را پوشش می‌دهد»، آن را در نظر بگیرند.

برای اثرگذاری حداکثری، این فایل باید در بلوک‌های عملکردی خاص تقسیم شود. برای مثال در یک پروژه واقعی Next.js، باید جزئیات مربوط به یک فروشگاه الکترونیکی با Next.js 16، دیتابیس Postgres، استفاده از App Router، TypeScript، Tailwind CSS، shadcn/ui، Prisma ORM و استقرار روی Vercel ذکر شود.

بر اساس مستندات فنی، جزئیات بخش‌های کلیدی عبارتند از:

• دستورات (Commands): این بخش بالاترین ارزش را دارد. لیست کردن دستورات صریح (مثلاً pnpm install ،pnpm dev ،pnpm test ،pnpm lint && pnpm tsc --noEmit و pnpm build) مانع می‌شود عامل اشتباهات رایجی مرتکب شود؛ مانند استفاده از npm در حالی که پروژه به pnpm نیاز دارد، یا اجرای pytest به‌جای vitest. هر ابزاری باید دقیقاً بداند چگونه پروژه را نصب، اجرا، تست و بیلد کند.
• معماری (Architecture): ساختار مخزن را به‌وضوح ترسیم کنید تا از خطاهای ناوبری جلوگیری شود. برای مثال:
  • /app/ — صفحات و لایوت‌های App Router در Next.js
  • /components/ — کامپوننت‌های UI مشترک، فقط با Named exports
  • /app/api/ — مسیرهای REST API
  • /lib/ — ابزارهای کمکی، کلاینت دیتابیس، کمک‌های احراز هویت
  • /db/ — اسکیمای Drizzle و مایگریشن‌ها
• قراردادها (Conventions): این موارد باید عملیاتی باشند، نه مبهم. عبارت «از کامپوننت‌های تابعی استفاده کن» یک قرارداد نیست چون هیچ چک‌لیست عملیاتی ارائه نمی‌دهد. در عوض از قوانین خاص استفاده کنید: «فقط Named exports، هیچ Default export در کامپوننت‌ها نباشد»، «تمام اعتبارسنجی فرم‌ها از Zod استفاده کند»، «حالت Strict در TypeScript — هرگز از any استفاده نکنید، برای داده‌های خارجی unknown را ترجیح دهید»، یا «استفاده از importهای مطلق از طریق alias @/ و هرگز از مسیرهای نسبی بین ماژول‌ها استفاده نکنید».
• محدودیت‌های سخت (Hard Constraints): از کلمه «هرگز» (Never) استفاده کنید. عوامل (Agents) به منفی‌های صریح وزن بیشتری نسبت به ترجیحات می‌دهند. این تفکیک بین ترجیحات نرم و محدودیت‌های سخت، بخشی از یک استراتژی جدید در حاکمیت AI است تا توازن بهتری میان آگاهی مدل و رعایت قوانین ایجاد شود. «فقط Named exports» یک ترجیح است، اما «هرگز از Default exports استفاده نکن» یک سیگنال قوی‌تر است. مثال‌های دیگر شامل این موارد است:
  • «هرگز فایل‌های /db/migrations/ را بدون تایید صریح تغییر نده»
  • «هرگز .env یا .env.local را کامیت نکن»
  • «هرگز از useEffect برای واکشی داده‌ها استفاده نکن — از Server Components یا TanStack Query استفاده کن»
  • «اندپوینت‌های API بدون احراز هویت باید صراحتاً در یک کامنت به عنوان public علامت‌گذاری شوند».

البته هر فایلی مفید نیست. طبق مطالعه‌ای که در فوریه ۲۰۲۶ توسط ETH Zurich (توسط Gloaguen و همکاران) روی ۱۳۸ تسک واقعی در گیت‌هاب انجام شد، مشخص شد که فایل‌های زمینه‌ای به‌طور کلی اغلب موفقیت در تسک‌ها را نسبت به زمانی که هیچ فایلی وجود نداشت، کاهش می‌دهند.

فایل‌های دست‌نویس استثنا بودند و به‌طور متوسط بهبود اندک ۴٪ ایجاد کردند. با این حال، این دستاورد هزینه‌بر بود: تسک‌ها تا ۱۹٪ به مراحل بیشتر نیاز داشتند و هزینه توکن‌ها بالا رفت، زیرا عامل پیش از اقدام، تحلیل‌های بیشتری انجام می‌داد. علاوه بر این، فایل‌های تولید شده به‌صورت خودکار از /init در اکثر تنظیمات تست‌شده، عملکرد بدتری نسبت به «هیچ» داشتند. نتیجه این است که فایل را خودتان بنویسید، آن را کوتاه نگه دارید و فقط مواردی را اضافه کنید که عامل نمی‌تواند با خواندن کد کشف کند.

به همین دلیل، Claude Code از شرکت Anthropic برای جلوگیری از «خستگی قوانین» (Rule Fatigue)، توصیه می‌کند طول فایل CLAUDE.md (و به تبع آن AGENTS.md) زیر ۲۰۰ خط باشد. هنگامی که فایلی از این طول فراتر رود، قوانین انتهای فایل وزن کمتری دریافت می‌کنند. اگر محتوا زیاد شد، باید به یک فایل مهارت (Skill) یا دستورالعمل‌های محدود به دامنه (Scoped) منتقل شود.

برای پروژه‌های بزرگ، استاندارد AGENTS.md اجازه استفاده از فایل‌های تودرتو را می‌دهد؛ به این معنا که فایلی که به دایرکتوری مورد ویرایش نزدیک‌تر است، اولویت دارد («نزدیک‌ترین برنده است»). فایل ریشه به عنوان پشتیبان سراسری عمل می‌کند.

برای مثال، مخزن OpenAI Codex دارای ۸۸ فایل مجزای AGENTS.md در سراسر درخت پروژه است. این به توسعه‌دهنده اجازه می‌دهد قوانین کلی را در ریشه قرار دهد اما آن‌ها را در یک زیرپوشه خاص بازنویسی (Override) کند. ساختار معمولی می‌تواند اینگونه باشد:

• my-project/AGENTS.md (قوانین کلی: استک، دستورات، قراردادها)
• my-project/packages/legacy-service/AGENTS.md (بازنویسی: «اینجا از yarn استفاده کن، نه pnpm»)

توسعه‌دهندگان برای کاهش توهم (Hallucination) و اتلاف توکن‌ها می‌توانند الگوهای خاصی را پیاده کنند:

۱. بودجه زمینه (Context Budget): عوامل نمی‌دانند چه زمانی خواندن را متوقف کنند و ممکن است تمام فایل‌های ثابت یا اسکیمای بزرگ را باز کنند و زمینه را بسوزانند. یک بخش بودجه با دستوراتی چون این‌ها اضافه کنید:
- «قبل از باز کردن کامل یک فایل، نماد یا مسیر مربوطه را جست‌وجو کن»
- «فایلی که چیزی را تعریف می‌کند قبل از فایل‌هایی که فقط از آن استفاده می‌کنند بخوان»
- «فایل‌هایی که قبلاً در زمینه بوده‌اند را دوباره نخوان مگر اینکه تغییر کرده باشند»
- «از بارگذاری کامل فایل‌های بزرگ تولید شده یا اسکیمایی خودداری کن مگر اینکه تسک به آن نیاز داشته باشد».
۲. نقشه مسیریابی سریع (Fast Routing Map): استفاده از یک جدول برای متصل کردن تسک‌ها به مسیرها تا دسته‌بندی کاملی از توهمات مسیر فایل حذف شود. برای مثال:

در مورد Codex CLI، فایلی به نام AGENTS.override.md وجود دارد که اولویت مطلق نسبت به AGENTS.md معمولی در همان سطح دایرکتوری دارد. این برای وضعیت‌های موقت، مانند زمان freeze کردن ریلیزها، بدون تغییر در فایل قوانین اصلی مفید است. همچنین Codex CLI بارگذاری زمینه را به‌طور پیش‌فرض روی ۳۲ کیلوبایت محدود کرده است؛ اگر مجموع از این سقف فراتر رود، نزدیک‌ترین فایل به دایرکتوری جاری برنده می‌شود. این رفتارها منحصر به Codex CLI است و در Copilot یا Claude Code دیده نمی‌شود.

در نهایت، چون AGENTS.md اغلب در مخازن عمومی کامیت می‌شود، باید به عنوان داده عمومی تلقی شود. هرگز فرمت‌های واقعی کلید API، توکن‌های نمونه که واقعی به نظر می‌رسند یا اسرار داخلی احراز هویت را قرار ندهید. فقط مستند کنید که اسرار کجا هستند (مثلاً: «در .env.local، هرگز کامیت نشود») و به همان بسنده کنید.

برای تضمین کیفیت، یک بخش «تعریف پایان» (Definition of Done) اضافه کنید تا عامل مجبور شود کار خود را تأیید کند. یک بخش معمولی ممکن است عامل را مجبور کند این موارد را به ترتیب اجرا کند:

1. pnpm tsc --noEmit
2. pnpm lint
3. pnpm test

دستورالعمل زیر را اضافه کنید: «تمام خطاها را رفع کن. اگر هر دستوری با خروجی غیرصفر (non-zero) بسته شد، کار را تمام‌شده اعلام نکن». اگرچه این یک توصیه است و عامل ممکن است هنوز یک بررسی را غیرضروری تشخیص دهد، اما قابلیت اطمینان را به‌طور قابل‌توجهی افزایش می‌دهد.

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

گام بعدی شما

• اگر از چندین ابزار AI Code Editor استفاده می‌کنید، تمام قوانین پراکنده را در یک فایل AGENTS.md در ریشه پروژه جمع کنید.
• دستورات «هرگز» (Never) را جایگزین توصیه‌های کلی کنید تا نرخ خطای عامل کاهش یابد.
• طول فایل خود را زیر ۲۰۰ خط نگه دارید تا وزن دستورات در مدل‌های مختلف حفظ شود.

اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.