اگر امروز از عامل‌های هوش مصنوعی برای کدنویسی استفاده می‌کنید، احتمالاً با «مشکل کارآموز» دست‌وپنجه نرم می‌کنید؛ وضعیتی که در آن مدل برای سریع رسیدن به جواب، کیفیت مهندسی را فدای ظاهرِ درستِ کد می‌کند. یک توسعه‌دهنده Claude Code کشف کرد که بزرگ‌ترین نقطه قوت این عامل‌ها — یعنی اشتیاق زیاد برای دنبال کردن دستورات — در عین حال بزرگ‌ترین نقطه ضعف آن‌هاست. این میل به میان‌بر زدن باعث می‌شود مدل در مواجهه با وظایف مبهم، سریع‌ترین مسیر محتمل را به جای مسیر صحیح مهندسی انتخاب کند. نتیجه این رفتار، تخریب ایمنی تایپ (Type Safety) و ایجاد خطاهای خاموش در پروژه‌های بزرگ است.
به نقل از راهنمای منتشرشده در ۹ اوت ۲۰۲۶ در وب‌سایت dev.to، راهکار این مشکل در نوشتن پرامپت‌های بهتر نیست، بلکه در تعریف یک قرارداد رسمی به نام AGENTS.md است. همان‌طور که در تحلیل قبلی ما درباره‌ی کاهش ۸۵ درصدی هزینه‌های API در Claude اشاره کردیم، چالش فعلی توسعه‌دهندگان از «هزینه» به «کیفیت» تغییر یافته است. صنعت اکنون از مستندات توصیفی (Prose-based) به سمت انضباط ماشین‌خوان حرکت می‌کند.
AGENTS.md برخلاف فایل‌های معمولی مانند CLAUDE.md که فقط «حال‌وهوای» (Vibes) پروژه را توصیف می‌کنند، مانند یک قرارداد الزام‌آور عمل می‌کند. نویسنده گزارش اشاره می‌کند که اگرچه فایل CLAUDE.md کمک‌کننده بود، اما بیشتر شبیه به یک مستندات کلی به نظر می‌رسید؛ به طوری که Claude Code آن را سریع می‌خواند، حس کلی پروژه را جذب می‌کرد و سپس هرگاه با موقعیتی مواجه می‌شد که در مستندات پوشش داده نشده بود، دوباره به ابداع «مهندسی احتمالی» بازمی‌گشت. این ابزار در اصل برای بهبود تعامل مستقیم با فایل‌ها از طریق ترمینال طراحی شده بود تا سرعت توسعه را افزایش دهد.
فایل AGENTS.md دقیقاً مشخص می‌کند که مفهوم «اتمام کار» (Done) از طریق قوانین شماره‌گذاری‌شده و قابل تست چیست. طبق گزارش dev.to، عامل ابتدا این فایل را می‌خواند و سایر عامل‌ها نیز به آن احترام می‌گذارند. این امر تضمین می‌کند که انضباط مهندسی به جای اینکه در پرامپت یک ابزار خاص بماند، همراه با مخزن کد (Repository) جابجا شود.
هسته این قرارداد از ۸ قانون پایه تشکیل شده تا میان‌برهای رایج هوش مصنوعی را حذف کند:
- ایمنی تایپ (Type Safety): هرگز برای عبور از یک چک، تایپ را به
anyگسترش ندهید؛ در عوض، خودِ آن چک باید اصلاح شود. - اعتبار تست (Test Validity): تستی که نتواند شکست بخورد، تست نیست. آن را حذف کرده و تستی بنویسید که قابلیت شکست خوردن داشته باشد.
- مدیریت خطا (Error Handling): استفاده از بلوک‌های
catch (e) {}خاموش ممنوع است؛ خطاها باید مدیریت شوند، دوباره پرتاب (Rethrow) شوند یا با ذکر زمینه (Context) ثبت گردند. - پایبندی به الگو (Pattern Adherence): الگوهای موجود در کدبیس را بر هرگونه انتزاع (Abstraction) جدید ترجیح دهید.
- اعتبارسنجی (Verification): تغییری که کامپایل شود اما تایید نشود، عملاً وجود ندارد.
- اولویت API (API First): APIهای عمومی باید پیش از اینکه فراخواننده‌ای (Caller) داشته باشند، تست شوند.
- اولویت قانون (Priority): اگر قانونی با ضرب‌الاجل (Deadline) در تضاد بود، ضرب‌الاجل شکست می‌خورد و قانون پیروز است.
- ارتباطات (Communication): حدس زدن به عنوان «مسیر گران‌قیمت» برچسب خورده است؛ عامل در صورت تردید باید سوال بپرسد.
برای تضمین اجرای این قوانین، یک «نردبان اعتبارسنجی» شش‌پله‌ای تعریف شده است. هر تغییر باید پیش از تایید، از این پله‌ها بالا برود. سه پله اول برای هر ویرایشی، هرچقدر هم کوچک، غیرقابل مذاکره و اجباری است:
۱. آیا کد کامپایل می‌شود؟
۲. آیا رفتار تغییریافته واقعاً کار می‌کند؟
۳. آیا بخش‌های مجاور کد را خراب کرده است؟
پس از طی کردن مبانی، عامل باید پله‌های باقی‌مانده را صعود کند:
۴. آیا کد از کنوانسیون‌های خاص این کدبیس پیروی می‌کند؟
۵. آیا در مرزها (Boundaries) پایداری دارد: مقادیر خالی (Empty)، نال (Null)، حجم بسیار زیاد یا اجرای همزمان (Concurrent)؟
۶. آیا نتیجه در محیط عملیاتی (Production) قابل مشاهده است؟
یکی از حیاتی‌ترین بخش‌ها، «پروتکل شکست سه-مرحله‌ای» است که به عنوان یک ترمز ساختاری برای جلوگیری از سوزاندن توکن‌ها روی فرضیات غلط عمل می‌کند. Claude Code اغلب با سرعت زیاد تکرار می‌کند و با اعتمادبه‌نفس کامل، یک اشتباه را به روش‌های مختلف تکرار می‌کند. مدل ممکن است همان فایل را دوباره بخواند و همان اصلاحیه را به شکلی متفاوت امتحان کند و ادعا کند که این بار قطعاً کار می‌کند. بدون یک ترمز، این وضعیت صرفاً ریختن پول و صبر در یک گودال است.
این پروتکل با یک محدودیت سخت‌گیرانه سه-تلاشی، این حلقه را می‌شکند:
- شکست اول: اصلاح و اعتبارسنجی مجدد. این مورد یک روز کاری عادی تلقی می‌شود.
- شکست دوم: توقف و استنتاج مجدد (Re-derive). در این مرحله، مدل ذهنیِ مدل از سیستم غلط است، نه صرفاً تایپ کردن او.
- شکست سوم: توقف کامل، بازگشت به آخرین وضعیت سالم (Revert) و مستندسازی دقیق اتفاق رخ‌داده.
بازگشت (Reverting) ضروری است زیرا سیستم را به جای زمین بدتر، به زمینی شناخته‌شده برمی‌گرداند. مستندسازی نیز تضمین می‌کند که جلسه بعدی از روی درس‌های آموخته شده شروع شود، نه تکرار خطا. این پروتکل، تلاش بیهوده روی یک فرضیه شکسته را از نظر ساختاری غیرممکن می‌کند.
علاوه بر قوانین پایه، اکثر وظایف در یک پروژه شکل خاصی دارند: قابلیت جدید (Feature)، رفع باگ (Bugfix) یا بازبینی (Review). این شکل‌ها در واقع «رویه‌ها» (Procedures) هستند — یعنی مراحلی به ترتیب با دروازه‌های عبور بین آن‌ها — و نه قرارداد. برای جلوگیری از اینکه این رویه‌ها در یک پرامپت سیستمی عظیم نادیده گرفته شوند، آن‌ها در فایل‌های جریان کاری (Workflow) جداگانه قرار می‌گیرند. این رویکرد مکمل راهکارهای پیشرفته‌تری است که برای جلوگیری از توهمات هوش مصنوعی از طریق جداسازی محیط‌های کدنویسی استفاده می‌شود.
وقتی Claude Code یک قابلیت جدید را شروع می‌کند، فایل جریان کاری مخصوص آن را باز می‌کند. این فرآیند متوالی شامل چندین مرحله اجباری است:
- قرارداد کوچک (Mini-Contract): بیان قرارداد قابلیت در دو جمله: اینکه چه کاری انجام می‌دهد و چه کاری را عمداً انجام نمی‌دهد. این مرحله مقدار زیادی از انحرافات (Drift) را از بین می‌برد.
- تطبیق الگو (Pattern Matching): یافتن نزدیک‌ترین الگوی موجود در کدبیس و پیروی از آن.
- پیاده‌سازی تست-محور (TDD): ابتدا نوشتن تستی که رفتار را اثبات کند و مشاهده شکست آن.
- تغییر حداقلی (Minimal Change): پیاده‌سازی کوچک‌ترین تغییری که باعث پاس شدن تست شود.
- صعود از نردبان: طی کردن نردبان اعتبارسنجی، با تاکید بر اجباری بودن پله‌های ۱ تا ۳.
- استنتاج مجدد: اگر طراحی در پله‌های ۴ و ۵ با توسعه‌دهنده در تضاد بود، پیش از نوشتن کد بیشتر، توقف و بازنگری در طراحی.
- گزارش‌دهی: گزارش دقیق تغییرات، موارد تست شده و مواردی که تست نشده باقی مانده‌اند.
این چارچوب به‌طور خاص غریزه هوش مصنوعی برای نوشتن تست‌هایی که جزئیات پیاده‌سازی (Implementation Details) را تایید می‌کنند، هدف قرار می‌دهد. اگر رها شود، Claude Code تست‌هایی می‌نویسد که نمی‌توانند شکست بخورند، زیرا فقط چک می‌کنند که کد اجرا شود، نه اینکه درست باشد.
برای مثال، یک تست ضعیف ممکن است برای تایید اینکه addItem یک آیتم را ذخیره می‌کند، فقط چک کند که cart.items.length برابر با ۱ است. این تست حتی اگر قیمت کل هرگز محاسبه نشود، پاس می‌شود. اما یک تست «اثبات‌کننده رفتار» (Behavior-proving) تایید می‌کند که addItem قیمت کامل کالای اضافه شده را محاسبه کند؛ مثلاً چک می‌کند که اضافه کردن یک شمشیر (۴۵) و یک سپر (۳۰) منجر به مجموع ۷۵ شود.
قانون قضاوت درباره هر تست ساده است: پیاده‌سازی را حذف کنید؛ اگر تست شکست نخورد، یعنی هرگز چیزی را تست نمی‌کرده است. تست‌های اثبات‌کننده رفتار تنها تست‌هایی هستند که عامل برای نوشتن آن‌ها استخدام شده است.
این رویکرد رابطه بین برنامه‌نویس و هوش مصنوعی را تغییر می‌دهد. شما دیگر یک پرستار نیستید که هر خط کد را تصحیح کند، بلکه یک مدیر قرارداد هستید که پایبندی عامل به یک رویه تعریف‌شده را بررسی می‌کند. هیچ‌کدام از این‌ها Claude Code را جادویی نمی‌کند — این همان مدل است که همان استدلال را انجام می‌دهد. تغییر این است که اولین فایلی که می‌خواند، اکنون «انضباط» را به عنوان یک رویه توصیف می‌کند، نه یک ترجیح.
برای تیم‌ها، این بدان معناست که «مهارت» عامل کمتر به هوش خام مدل و بیشتر به دقت قرارداد بستگی دارد. همان‌طور که در یک گزارش تکمیلی اشاره شده، بدنه یک مهارت سفارشی (Custom Skill) بسیار کمتر از دقت توصیف آن و محدودیت‌های اعمال شده بر آن اهمیت دارد. در کنار این انضباط، تنظیمات امنیتی سخت‌گیرانه نیز برای جلوگیری از دور زدن حفاظ‌های سیستمی توسط عامل ضروری است.
این تغییر نشان می‌دهد که آینده هوش مصنوعی عامل‌محور، تنها پنجره‌های کانتکست بزرگ‌تر یا استدلال بهتر نیست، بلکه فایل‌های «حکمرانی» (Governance) بهتری است که داخل مخزن git زندگی می‌کنند. با برخورد با هوش مصنوعی به عنوان یک پیمانکار با یک SLA سخت‌گیرانه به جای یک دستیار جادویی، توسعه‌دهندگان می‌توانند خروجی خود را بدون افزایش بدهی فنی (Technical Debt) مقیاس کنند.
برای پیاده‌سازی این سیستم، می‌توانید با بازبینی تست‌های فعلی تولیدشده توسط هوش مصنوعی شروع کنید تا ببینید آیا در صورت خرابی قابلیت، باز هم پاس می‌شوند یا خیر.
گام بعدی شما
- تست‌های فعلی تولیدشده توسط هوش مصنوعی را بازبینی کنید تا ببینید آیا در صورت خرابی قابلیت (Feature)، باز هم پاس می‌شوند یا خیر.
- یک فایل AGENTS.md ساده با سه قانون سخت‌گیرانه برای ایمنی تایپ در پروژه خود ایجاد کنید.
- پروتکل بازگشت (Revert) را برای جلوگیری از حلقه‌های تکراری در عامل‌های خود پیاده کنید.
اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.
گفتگو