۱۵ گاف عملیاتی عامل‌های کدنویس و راهکار مقابله با توهمات گزارش

اگر امروز یک عامل هوش مصنوعی را برای مدیریت مخزن کدهای خود به کار گرفته‌اید، احتمالاً در هفته سوم با دیواری از توهمات برخورد می‌کنید؛ جایی که گزارش‌های با اعتمادبه‌نفس، ویژگی‌های خراب را «تکمیل‌شده» معرفی می‌کنند. طبق تحلیل مفصل منتشر شده در dev.to در ۱۳ اکتبر ۲۰۲۶، این شکست‌ها به‌ندرت به کیفیت مدل برمی‌گردند و در واقع شکاف‌های عملیاتی هستند که نیاز به حفاظ‌های فایل‌محور دارند. در واقع، زمانی که عامل‌های کدنویسی ترنسکریپت‌های طولانی تولید می‌کنند و ده‌ها فایل را ویرایش می‌کنند، پاسخ‌های آن‌ها به سوالاتی نظیر «چه چیزی منتشر شد و آیا درست است؟» مبهم می‌شود.

این چرخش به سمت سخت‌گیری عملیاتی، بخشی از روند کلی انتقال هوش مصنوعی از محیط‌های آزمایشگاهی و بنچمارک‌ها به محیط تولید است. همان‌طور که در تحلیل قبلی ما درباره‌ی JetBrains Mellum2.1 اشاره کردیم، استفاده از یادگیری تقویت‌شده (RL) می‌تواند امتیازات SWE-bench را به ۴۷.۰ برساند، اما این امتیازات لزوماً به مخازن واقعی ترجمه نمی‌شوند؛ جایی که کلمه «انجام شد» اغلب یک توهم است. این تضاد نشان می‌دهد که موفقیت در دموی عامل‌های هوش مصنوعی لزوماً به معنای قابلیت اطمینان در محیط واقعی نیست. تصور کنید یک برنامه‌نویس تازه‌کار بگوید کار تمام شده است، اما هرگز کد را اجرا نکرده باشد؛ این دقیقاً وضعیت فعلی بسیاری از عامل‌های هوش مصنوعی (AI Agents) است — شبیه دستیاری که دستورات را می‌شنود اما از نتیجه‌ی اجرای آن‌ها مطمئن نیست.

چهار ریشه‌ی شکست عامل‌ها

به نقل از این گزارش، پیش از اصلاح، باید چهار دلیل سیستماتیک شکست عامل‌ها در محیط تولید را شناخت:

• شکاف شواهد (Evidence Gaps): عامل ادعا می‌کند کار «تمام شده»، اما چون تعریف دقیقی از «پایان» وجود ندارد که مستلزم ارائه مدرک باشد، هیچ چیز به‌صورت سرتاسری (end-to-end) کار نمی‌کند. این مسئله دقیقاً همان جایی است که بررسی وضعیت واقعی سیستم در برابر گزارش‌های متنی عامل‌ها اهمیت حیاتی پیدا می‌کند.
• انحراف دستورالعمل‌ها (Instruction Drift): ابزارهای مختلف در یک مخزن رفتارهای متفاوتی دارند چون دستورات در فایل‌های مختلف تکرار شده و در طول زمان از یکدیگر فاصله گرفته و ناسازگار شده‌اند.
• اصطکاک دسترسی (Permission Friction): توسعه‌دهندگان از اجرای خودکار عامل‌ها می‌ترسند و مجبور به «پرستاری» آن‌ها می‌شوند، چون دسترسی‌ها در پرامپت تعریف شده‌اند نه در فایل‌های پیکربندی (Config).
• زوال حافظه (Memory Decay): عامل در هر جلسه حقایق تکراری را دوباره یاد می‌گیرد چون حافظه پایدار ندارد، یا حافظه‌اش بدون هیچ‌گونه سازمان‌دهی و تثبیتی فقط رشد می‌کند.

حل توهمات و انحرافات

عامل‌ها اغلب «قصد» خود را به جای «نتیجه» روایت می‌کنند؛ مثلاً می‌گویند «هندلر را برای تلاش مجدد به‌روز کردم» بدون اینکه مدرکی ارائه دهند. راهکار پیشنهادی، ایجاد یک فایل AGENTS.md با تعریف سخت‌گیرانه از «پایان» (Definition of Done) است که ارائه شواهد را اجباری می‌کند. یک گزارش معتبر باید به گونه‌ای باشد که یک غریبه بتواند ادعا را بازتولید کند. عبارت «تست‌ها پاس شدند» یک شکست است، اما عبارت «اجرای make test T=billing منجر به ۴۲ مورد موفق در ۶.۱ ثانیه شد» یک موفقیت است.

بر اساس مستندات این چارچوب، یک فایل AGENTS.md قدرتمند باید موارد زیر را اجباری کند:

• اثبات اینکه رفتار مورد نظر وجود دارد و یک دمو از آن اجرا شده است.
• پاس شدن تست‌هایی که تغییرات را پوشش می‌دهند، به گونه‌ای که هیچ تستی حذف، نادیده (skip) یا تضعیف نشده باشد.
• پاس شدن بررسی‌های Lint و Type check.
• ارائه یک پیام نهایی که شامل لیست فایل‌های تغییر یافته، دستورات اجرا شده به همراه نتایج، تصمیماتی که بدون درخواست گرفته شده‌اند و مواردی باشد که قابل تایید نبودند.

برای جلوگیری از حذف تست‌های شکست‌خورده توسط عامل (که برای «پاس کردن» تسک در حلقه‌های تکرار نامحدود رایج است)، توسعه‌دهندگان باید حلقه‌های تلاش مجدد (Retry Loops) را به حداکثر ۳ بار محدود کنند. همچنین برای جلوگیری از گسترش بی‌رویه دامنه کار (Scope Creep) — یا همان سندرم «حالا که اینجا بودم، این کار را هم انجام دادم» — هر تسک باید لیستی صریح از موارد «خارج از محدوده» (Out) داشته باشد تا هرگونه تغییر غیرمجاز در فایل‌ها شناسایی شود. اگر یک تسک را نتوان در یک خط بررسی پذیرش تعریف کرد (مثلاً: «تست test_duplicate_returns_409 پاس شود و make lint تمیز باشد»)، آن تسک آماده‌ی واگذاری به هوش مصنوعی نیست.

در زمان استفاده از ابزارهای مختلف مثل Claude Code، Codex CLI و Gemini CLI، دستورات دچار انحراف می‌شوند. راهکار این است که یک قرارداد مرکزی در AGENTS.md داشته باشید و برای هر ابزار یک آداپتور (Adapter) نازک برای تنظیمات خاص آن ابزار بسازید. برای مثال، Gemini CLI می‌تواند قرارداد را از طریق .gemini/settings.json و با استفاده از ساختار {"context": {"fileName": ["AGENTS.md", "GEMINI.md"]}} بارگذاری کند. ابزار Codex نیز AGENTS.md را به‌صورت بومی می‌خواند. برای تضمین این روند، می‌توان یک بررسی CI دو خطی اضافه کرد که اگر فایل‌های CLAUDE.md یا GEMINI.md بیش از ۴۰ خط شدند یا لینک آن‌ها به قرارداد اصلی قطع شد، بیلد را شکست دهد.

سخت‌سازی دسترسی‌ها و امنیت

شکست‌های دسترسی زمانی رخ می‌دهد که توسعه‌دهندگان «سندباکس» (Sandboxing) را با «سیاست تایید» (Approval Policy) اشتباه می‌گیرند. سندباکس مرزهای فیزیکی (فایل‌ها و شبکه) است، اما سیاست تایید، رویه عبور از این مرزهاست. در Codex، تنظیم approval_policy = "never" مرزها را گسترش نمی‌دهد، بلکه باعث می‌شود عملیات عبور از مرز در اجراهای دسته‌ای (batch runs) به‌جای انتظار برای انسان، به‌سادگی و در سکوت شکست بخورند. به همین دلیل است که بسیاری از کارهای شبانه هیچ نتیجه‌ای ندارند.

برای امنیت و ایجاد حفاظ‌ها، توصیه‌های زیر ارائه شده است:

• لیست‌های منع صریح (Explicit Deny Lists): در Claude Code از دستور "permissions": {"deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]} برای مسدود کردن دسترسی به فایل‌های حساس استفاده کنید. این رویکرد بخشی از استراتژی گسترده‌تری است که Claude Code برای کاهش ادعاهای دروغین عامل‌ها درباره رفع باگ‌ها به کار می‌گیرد.
• تزریق اعتبارنامه‌ها (Credential Injection): به جای قرار دادن رمزها در فایل‌های خواندنی، آن‌ها را مستقیماً به محیط (Environment) یک دستور خاص تزریق کنید.
• قلاب‌های پیش از اجرا (PreToolUse Hooks): مسدود کردن دستورات خطرناک از طریق الگوهای Regex. برای مثال، مسدود کردن rm -rf یا git push --force (بدون lease) یا لوله‌کشی دانلودها به شل (curl|wget | sh).
• تایید قلاب‌ها: بررسی خروجی قلاب‌ها به‌جای صرفاً حضور آن‌ها برای جلوگیری از شکست‌های خاموش. یک قلاب باید با کد خروجی ۲ خارج شود تا فراخوانی را مسدود کرده و پیام stderr را به عامل نشان دهد.

مدیریت زمینه و حافظه

پنجره زمینه (Context Window) — شبیه میز کاری که فقط جای چند ورق کاغذ دارد — اغلب با هزاران خط خروجی تست‌های موفق پر می‌شود. راهکار این است که اجرای تست‌ها را به یک «عامل فرعی» (Subagent) بسپارید که فقط شکست‌ها را برگرداند و حجم داده‌های مصرفی در زمینه را از ۵۰۰۰ خط به ۵ خط کاهش دهد.

برای جلوگیری از اینکه عامل‌های بازبین (Reviewer) به‌جای حسابرسی، کد را بازنویسی کنند، باید دسترسی آن‌ها را به ابزارهای Read، Grep، Glob و Bash محدود کرد. یک پروفایل بازبینی اختصاصی (مثلاً در ~/.codex/review.config.toml) باید در حالت sandbox_mode = "read-only" قرار گیرد و از او خواسته شود که فقط چهار حکم صادر کند: VERDICT (حکم)، BLOCKING (مسدودکننده)، NON-BLOCKING (غیرمسدودکننده) و EVIDENCE (شواهد).

برای جلوگیری از تضاد در حافظه، از فایل‌های «فقط-افزودنی» (append-only) دوری کنید و از سیستم سه لایه استفاده کنید:
۱. لاگ‌های خام (Raw Logs): ثبت تمام فعالیت‌ها در هر نوبت (per-turn).
۲. خلاصه روزانه (Daily Summary): خلاصه‌ای که حداکثر به ۴۰ خط محدود شده است.
۳. حافظه پایدار (Durable Memory): فایلی که حداکثر به ۱۲۰ خط محدود شده است.

یک پردازش هفتگی باید مواردی را به حافظه پایدار منتقل کند که در دو یا چند فایل روزانه تکرار شده‌اند، در حالی که حلقه‌های بسته شده و حقایق متناقض را فراموش کند.

در نهایت، برای مدیریت Time-outها در عملیات خارجی، هر فراخوانی باید از یک کلید Idempotency استفاده کند. این کار از ارسال پیام‌های تکراری یا فراخوانی‌های API موازی در صورت گم شدن پاسخ جلوگیری می‌کند؛ زیرا در زمان Time-out، تشخیص اینکه پاسخ «هرگز نرسیده» یا «پردازش شده اما پاسخ گم شده است» غیرممکن است.

این رویکرد عملیاتی، بار مسئولیت قابلیت اطمینان را از دوش ارائه‌دهنده مدل (LLM Provider) برمی‌دارد و به معمار مخزن کد می‌سپارد. با تبدیل عامل به یک جزء سیستمی با ورودی و خروجی سخت‌گیرانه، تیم‌ها از «پرستاری» هوش مصنوعی به «حسابرسی» شواهد آن می‌رسند.

برای یک توسعه‌دهنده، این یعنی «پرامپت» دیگر اهرم اصلی کیفیت نیست. قدرت واقعی در فایل‌های پیکربندی، بررسی‌های CI و تعریف پایان است که عامل مجبور به رعایت آن‌هاست. برای اجرا، یک برنامه ۶۰ دقیقه‌ای را شروع کنید: ۱۵ دقیقه برای AGENTS.md، ۱۵ دقیقه برای ماتریس تایید، ۱۵ دقیقه برای قلاب‌های حفاظتی و عامل‌های فرعی، و ۱۵ دقیقه نهایی برای روتین تثبیت حافظه. موفقیت را هفتگی و بر اساس تعداد تغییرات پذیرفته‌شده، نرخ بازکاری (rework rate) و دقایق انسانی صرف‌شده برای هر تغییر پذیرفته‌شده اندازه بگیرید.

گام بعدی شما

• ایجاد فایل AGENTS.md و تعریف دقیق «پایان» برای اولین تسک کوچک خود.
• محدود کردن حلقه‌های تلاش مجدد (Retry Loops) به حداکثر ۳ بار برای جلوگیری از حذف تست‌ها.
• پیاده‌سازی یک لایه حافظه سه مرحله‌ای برای جلوگیری از تضادهای اطلاعاتی در جلسات طولانی.

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