یک فایل AGENTS.md می‌تواند از نظر نگارشی بی‌نقص باشد اما در عمل کاملاً اشتباه عمل کند. تصور کنید پروژه‌تان به pnpm مهاجرت کرده است، اما یک عامل (Agent) — مانند دستیاری هوشمند که وظیفه دارد کدهایی را به‌صورت خودکار اجرا کند — همچنان با اطمینان کامل دستور npm test را اجرا می‌کند، در حالی که برنامه‌نویس انسانی یاد می‌گیرد که دیگر به README اعتماد نکند. عامل‌های کدنویسی دقیقاً به همین دلیل شکست می‌خورند؛ آن‌ها مستندات کهنه را حقیقت مطلق می‌پندارند و با اطمینان کامل مسیرهای منسوخ را دنبال می‌کنند. این اتفاق زمانی رخ می‌دهد که فایل ادعا می‌کند تست‌ها در پوشه test/ هستند، در حالی که در واقعیت آن‌ها به packages/api/spec/ منتقل شده‌اند، یا زمانی که فایل درباره ویرایش فایل‌های تولید شده (generated files) هشدار می‌دهد، در حالی که ابزار تولیدکننده آن فایل‌ها ماه‌ها پیش از پروژه حذف شده است. این چالش‌ها نشان می‌دهند که چگونه خطاهای کوچک در درک عامل از کد می‌تواند منجر به باگ‌های جدی شود، مشابه آنچه در بررسی تحلیل diff در برابر سامانه‌های CI برای شکار باگ‌های ساکت مورد بحث قرار گرفت.
این اصطکاک، نشانه اصلی «پدیده رانش مخزن» (Repository Drift) است. همان‌طور که پروژه‌ها تکامل می‌یابند، فاصله میان متن توصیفی در یک فایل AGENTS.md و وضعیت واقعی کد منبع افزایش می‌یابد. طبق یک راهنمای منتشر شده در dev.to در ۱۲ ژوئیه ۲۰۲۶، راهکار این مشکل، نوشتن پرامپت‌های طولانی‌تر یا دستورات متنی بهتر نیست، بلکه گذار به سمت «قراردادهای اجرایی» است. این رویکرد در سایر پلتفرم‌ها نیز دیده می‌شود؛ برای مثال تلاش مایکروسافت در اکوسیستم Azure برای تبدیل مستندات به گاردریل‌های اجرایی گامی در همین جهت است.
تفکیک انواع اطلاعات
برای حل این مشکل، توسعه‌دهندگان تشویق می‌شوند که قضاوت انسانی را از ناپایدارهای فنی جدا کنند. اکثر دستورات یک مخزن شامل سه نوع اطلاعات متمایز است:
- قضاوت: راهنمایی‌هایی مانند «ترجیحاً کوچک‌ترین تغییری را ایجاد کنید که API عمومی را حفظ کند»؛ این موارد ماهیت تحلیلی دارند و باید توسط انسان بررسی شوند.
- واقعیت: ادعاهایی مانند «تست‌های یکپارچه‌سازی در مسیر
test/integrationهستند» که می‌توان صحت آن‌ها را صرفاً با بررسی وجود یا عدم وجود آن مسیر در سیستم فایل تایید کرد. - رویه: دستوراتی مثل «قبل از ارسال،
npm run checkرا اجرا کنید» که می‌توان آن را در محیط CI یا در تولید بازیابی‌افزا (RAG) — شبیه دانش‌آموزی که قبل از جواب دادن، اول کتاب درسی را باز می‌کند تا دقیقاً بداند چه چیزی را باید اجرا کند — بررسی کرد.
هدف این است که از تبدیل شدن «قضاوت‌ها» به قوانین شکننده جلوگیری شود، اما در عوض هر ادعای واقع‌گرایانه یا رویه‌ای به یک بررسی قابل تایید (Verifiable Check) تبدیل شود.
سازوکار قرارداد مخزن
مکانیزم پیشنهادی شامل درج یک بلوک JSON محصور (fenced) در فایل AGENTS.md است. این بلوک با نام agent-contract سه دسته حیاتی از تاییدها را تعریف می‌کند:
{
"requiredPaths": ["src", "test", "package.json"],
"checks": [
{ "name": "tests", "argv": ["npm", "test", "--", "--runInBand"] },
{ "name": "types", "argv": ["npm", "run", "typecheck"] }
],
"reviewAfter": "2026-10-01"
}
- مسیرهای مورد نیاز (Required Paths): فهرستی از پوشه‌ها یا فایل‌ها (مانند
srcیاpackage.json) که برای اینکه عامل بتواند به‌درستی عمل کند، حتماً باید وجود داشته باشند. - بررسی‌ها (Checks): آرایه‌ای از دستورات (مانند
npm run typecheck) که باید با موفقیت اجرا شوند. دستورات به‌جای رشته‌های متنی ساده، به‌صورت آرایه‌ای از آرگومان‌ها ذخیره می‌شوند تا از تفسیرهای ناخواسته پوسته (Interpolation) جلوگیری شود. - تاریخ بازبینی (Review Dates): یک برچسب زمانی
reviewAfter(مثلاً ۲۰۲۶-۱۰-۰۱) که پس از رسیدن به آن تاریخ، باعث شکست تست می‌شود تا نویسنده متوجه شود که متن مستندات احتمالاً به یک «سند باستانی» تبدیل شده و نیاز به بازبینی دارد.
پیاده‌سازی بازرس (Auditor)
برای اجرای این قوانین، نویسنده یک اسکریپت Node.js به نام check-agent-contract.mjs ارائه داده است که فایل مارک‌داون را بازرسی می‌کند. این اسکریپت که با Node.js 22.22.3 تست شده است، تضمین می‌کند که اگر یک مسیر موجود باشد و دستور node --version اجرا شود، خروجی ۰ (موفق) برگردد، در حالی که مسیرهای مفقود یا اجراکننده‌های تایید نشده منجر به خروجی ۱ (شکست) شوند.
نکته حیاتی این است که بازرس از تنظیم shell: false و یک لیست سفید از اجراکننده‌ها (محدود به npm, pnpm, yarn, bun و node) استفاده می‌کند. این کار مانع از آن می‌شود که یک Pull Request، یک رشته متنی ساده در مستندات را به یک حمله تزریق پوسته (Shell Injection) خطرناک تبدیل کند. اگر مستندات مستقیماً به exec() یا spawn(..., { shell: true }) پاس داده شوند، ممکن است دستوری مانند npm test && curl ... کدهای ناخواسته را اجرا کند. استفاده از آرایه‌های آرگومان و غیرفعال کردن پوسته، تمامی عملگرهای پوسته، جایگزینی‌ها و تغییر مسیرها (Redirections) را حذف می‌کند. این تمرکز بر امنیت در لایه اجرا، یادآور ضرورت جایگزینی اتصال‌دهنده‌های ساده با قراردادهای عملیاتی برای تامین امنیت عامل‌های AI است.
یکپارچه‌سازی با CI و امنیت
این بازرس برای محیط‌های عملیاتی به‌گونه‌ای طراحی شده که مستقیماً در گردش کار GitHub Actions قرار گیرد. با استفاده از یک Job به نام verify-agent-guidance روی ubuntu-latest-، این گردش کار اسکریپت را روی فایل AGENTS.md اجرا می‌کند. هرگاه توسعه‌دهنده‌ای پوشه‌ای را حذف کند یا نام اسکریپتی را در یک Pull Request تغییر دهد، این Job شکست می‌خورد و نویسنده مجبور می‌شود دستورات عامل و پیاده‌سازی کد را در یک Commit اتمیک و هم‌زمان به‌روز کند.
برای امنیت حداکثری در محیط‌های تولید، نویسندگان باید اکشن‌های شخص ثالث را به جای تگ‌های تغییرپذیر (Mutable Tags)، به SHAهای کامل کامیت متصل (Pin) کنند. همچنین، از آنجایی که دستورات مجاز مانند npm test همچنان کدهای کنترل‌شده توسط مخزن را اجرا می‌کنند، این بازرس باید با همان سطح ایزولاسیون، اعتبارنامه‌ها (Credentials) و سیاست‌های شبکه‌ای اجرا شود که برای CIهای استاندارد Pull Request اعمال می‌گردد.
محدوده و کاربرد
قرارداد را کوچک نگه دارید. هدف این نیست که یک مدیریت بسته (Package Manager) دوم یا یک زبان سیاست‌گذاری دست‌ساز بسازید.
- کاندیداهای مناسب: مسیرهایی که عامل حتماً باید بازرسی کند؛ دستورات موجود برای فرمت‌بندی (Format)، بررسی تایپ‌ها (Type) و ساخت (Build)؛ و تاریخ بازبینی برای متون.
- کاندیداهای نامناسب: توصیه‌های مربوط به استایل کدنویسی که نیاز به زمینه دارند؛ رمزهای سری (Secrets) یا URLهای خاص محیطی؛ دستورات تخریبی استقرار (Deployment)؛ یا دستورات بررسی‌نشده‌ای که از Issueهای شخص ثالث گرفته شده‌اند.
این رویکرد به‌ویژه برای پروژه‌هایی مثل MonkeyCode کاربرد دارد که مدیریت وظایف پیچیده AI، نیازمندی‌های پروژه و استقرار خصوصی را بر عهده دارند. در چنین اکوسیستم‌هایی، دستورات باید فارغ از اینکه کدام فضای کاری (Workspace) یا مدل خاص وظیفه را اجرا می‌کند، حقیقت داشته باشند. لازم به ذکر است که نویسنده این مطلب در پروژه MonkeyCode مشارکت دارد.
در نهایت، یک قرارداد ده خطی که به‌موقع و به‌درستی شکست بخورد، بسیار برتر از یک طرح صد خطی است که هیچ‌کس آن را نگهداری نمی‌کند. هدف این نیست که یک ابزار مدیریت بسته بسازیم، بلکه هدف این است که تضمین کنیم «نقشهٔ» عامل با «قلمرو واقعی» کد مطابقت داشته باشد.
گام بعدی شما
- فایل AGENTS.md خود را بررسی کنید و تمام مسیرهای ذکر شده را با واقعیت مخزن تطبیق دهید.
- برای هر دستور اجرایی تکرار شونده در مستندات، یک تست ساده در CI بنویسید تا از صحت آن مطمئن شوید.
- یک تاریخ بازبینی (Review Date) برای مستندات AI خود تعیین کنید تا از کهنگی آن‌ها جلوگیری کنید.
اما برای مدیریت این قراردادها در مقیاس بزرگ، پروتکل‌های جدیدتری در راه است — به تحلیل ما درباره‌ی Model Context Protocol (MCP) مراجعه کنید.
گفتگو