تصور کنید یک برنامه‌نویس ارشد را استخدام کرده‌اید که در تمام کتابخانه‌های دنیا خبره است، اما وقتی به APIهای داخلی شرکت شما می‌رسد، با اعتمادبه‌نفس کامل کدهایی می‌نویسد که اصلاً وجود ندارند. این دقیقاً همان نقطه‌ای است که عامل‌های هوش مصنوعی شکست می‌خورند؛ آن‌ها به‌جای پذیرش جهل، شکاف‌های دانشی خود را با نزدیک‌ترین جایگزین محبوب در داده‌های آموزشی‌شان پر می‌کنند. این حالت را می‌توان «نوشتن با اطمینان برای کتابخانه‌ای که در واقع نمی‌شناسد» نامید.
به نقل از گزارش فنی منتشرشده در dev.to در ۱۳ اکتبر ۲۰۲۶، این شکست زمانی رخ می‌دهد که مدل با یک کتابخانه تخصصی، یک کلاینت API داخلی شرکت یا یک کتابخانه متن‌باز کم‌کاربرد مواجه می‌شود. چون مدل داده‌های خاص این ابزار را ندارد، به‌جای توقف، نام گزینه‌ها یا ساختار خروجی‌ها را بر اساس کتابخانه‌هایی مثل React یا Jest ابداع می‌کند. نتیجه کدی است که در ذهن مدل کاملاً درست به نظر می‌رسد و حتی در تصور مدل کامپایل می‌شود، اما در محیط عملیاتی با خطاهای کوچک اما با اعتمادبه‌نفس بالا، منجر به شکست می‌شود. این چالش با شناسایی موارد لبه‌ای فراموش‌شده در جریان کاری توسعه‌دهندگان مرتبط است که نشان می‌دهد چگونه نقاط کور در پرامپت‌نویسی منجر به خروجی‌های غیرمنتظره می‌شود.
برای حل این مشکل، نویسنده این راهنما در حین توسعه TWD — یک کتابخانه تست که اکثر مدل‌ها فعلاً آن را نادیده می‌گیرند — ابزاری را طراحی کرد که بر پایه یک اصل بنیادی است: نثر هرگز بر دترمینیسم (قطعیت) پیروز نمی‌شود. به عبارت ساده‌تر، شما نمی‌توانید صرفاً به یک مدل بگویید «هرگز X را انجام نده» و انتظار داشته باشید اطاعت کند؛ بلکه باید سیستمی بسازید که در آن خودِ محیط، عامل را اصلاح کند.
همان‌طور که در تحلیل‌های قبلی ما درباره‌ی امنیت مدل‌های بازمتن اشاره کردیم، تکیه بر دستورالعمل‌های متنی بدون لایه‌های کنترلی سخت‌افزاری یا نرم‌افزاری، ریسک توهم را بالا می‌برد. در این چارچوب، اولین گام ارائه دانش است، نه فقط قوانین. تنها منبع حقیقت برای یک عامل (Agent) — شبیه به کارآموزی که فقط به دفترچه راهنمای شما تکیه می‌کند — فایل‌هایی است که شما در اختیارش قرار می‌دهید، مانند مهارت‌ها (skills)، فایل AGENTS.md یا llms.txt.
برای اثربخشی این مستندات، باید موارد زیر رعایت شود:
- نوشتن امضاهای کامل توابع با نام دقیق گزینه‌ها (Exact option names).
- تعریف صریح ساختار خروجی‌ها (Return shapes)، به‌ویژه در نقاطی که با استانداردهای رایج و محبوب متفاوت‌اند.
- ارائه مثال‌های کامل و runnable؛ چرا که یک مثال درست، از سه پاراگراف توضیح اثرگذارتر است.
از آنجا که پنجره متنی (Context Window) — مثل میز کاری که فقط جای چند ورق کاغذ دارد و نه کل کتابخانه — گران است و عامل‌ها برای هر بایت هزینه می‌پردازند، نویسنده پیشنهاد می‌کند مستندات را لایه‌بندی کنید. برای مثال، یک مرجع هسته (Core reference) حدود ۸ کیلوبایتی برای مدیریت اکثر وظایف معمول ایجاد کنید و یک فایل ثانویه و حجیم‌تر را تنها زمانی بارگذاری کنید که وظیفه خاص مدل به آن نیاز داشته باشد. این قابلیت در Claude Code از طریق دایرکتوری references/ به‌صورت بومی پشتیبانی می‌شود. برای مدیریت بهتر این حجم از داده در پروژه‌های عظیم، استفاده از CodeGraph MCP می‌تواند کورسوزی عامل‌ها را در مخازن کد بزرگ متوقف کند و دسترسی به متادیتای دقیق‌تر را فراهم آورد.
در لایه دوم، حفاظ‌های دترمینستیک وارد می‌شوند. تایپینگ سخت‌گیرانه (Strict Typing) مؤثرترین نوع مستندسازی است، زیرا اگر کامپایلر در حال اجرا باشد، مدل نمی‌تواند آن را نادیده بگیرد. با تایپ کردن سخت‌گیرانه APIهای عمومی، یک غلط املایی در نام گزینه به‌جای تبدیل شدن به یک باگ در زمان اجرا (Runtime bug)، تبدیل به یک خطای کامپایل می‌شود. بهینه‌ترین روش این است که به عامل دستور دهید پیش از اجرا، کد خود را Type-check کند.
برای خطاهایی که تایپینگ نمی‌تواند بگیرد — مانند فراموش کردن کلمه کلیدی await یا ایمپورت کردن توابع از کتابخانه اشتباه — یک Linter متمرکز لازم است. یک لینتر مناسب برای عامل‌ها باید سه ویژگی داشته باشد:
۱. پیکربندی صفر: باید با یک دستور واحد و بدون نیاز به هیچ تنظیماتی اجرا شود.
۲. قابلیت اصلاح خودکار (Autofix): اصلاحات ایمن باید به‌طور خودکار اعمال شوند.
۳. پیام‌های عملیاتی: خطاها باید علت و راه حل را در یک جمله بیان کنند تا عامل دقیقاً بداند گام بعدی‌اش چیست.
در بخش خروجی، ابزارهای CLI اکنون باید برای دو خواننده طراحی شوند: انسان و برنامه. در حالی که انسان‌ها گزارش‌های زیبا و بصری می‌خواهند، عامل‌ها به داده‌های ساختاریافته نیاز دارند. افزودن پرچم --format json به هر دستور به عامل اجازه می‌دهد بدون اشتباه در شمارش خطوط کنسول یا تحلیل متون نامنظم، نتایج و تشخیص‌ها (Diagnostics) را استخراج کند.
برای جلوگیری از پس‌رفت دستورالعمل‌ها (Instruction regression)، استفاده از «ارزیابی‌ها» (Evals) توصیه می‌شود؛ یعنی پروژه‌های کوچکی با وظایفی مشخص و درجه‌بندی‌های تعریف‌شده. در Claude Code، این کار از طریق claude plugin eval انجام می‌شود. این ارزیابی‌ها باید از درجه‌بندی‌های دترمینستیک استفاده کنند، مثلاً استفاده از الگوهای Regex برای بررسی ایمپورت‌های درست یا بررسی لاگ‌های استفاده از ابزار (Tool-use logs) برای تأیید اینکه آیا لینتر اجرا شده است یا خیر. این رویکرد مشابه نقشه‌راه اجرای کد است که دستیاران هوش مصنوعی را از حدس‌های تصادفی را نجات می‌دهد و آن‌ها را به سمت تحلیل ساختاری سوق می‌دهد.
یک مورد خاص در این ارزیابی‌ها، «کاشتن» چهار خطای عمدی در یک فایل است تا تأیید شود عامل واقعاً لینتر را اجرا کرده و فایل را پاکسازی می‌کند. اگرچه این ارزیابی‌ها هزینه‌بر هستند (حدود ۱.۸۰ دلار برای ۵ مورد)، اما شکاف‌های بحرانی را می‌یابند که تست‌های دستی هرگز آن‌ها را شناسایی نمی‌کنند.
در نهایت، برای جلوگیری از «رانش دستورالعمل‌ها» (Instruction Drift) که زمانی رخ می‌دهد که کتابخانه تکامل می‌یابد اما دستورالعمل‌های عامل ایستا می‌مانند، باید از یادداشت‌های نسخه‌ای مثل «در نسخه ۱.۸ اصلاح شد» پرهیز کرد، زیرا مدل‌ها اغلب نسخه فعلی را نمی‌دانند. به‌جای آن، رفتار فعلی را توصیف کنید و تمام ادعاها را با کد منبع تطبیق دهید، نه با حافظه مدل.
این تغییر رویکرد، بارِ دقت را از داده‌های آموزشی مدل به زیرساخت‌های توسعه‌دهنده منتقل می‌کند. با تبدیل دستورالعمل‌های عامل به «کد» — همراه با تایپ‌ها، لینترها و تست‌های واحد — توسعه‌دهندگان می‌توانند عامل‌ها را با اطمینان بالا روی استک‌های اختصاصی خود مستقر کنند.
گام بعدی شما
- فایل
llms.txtرا به ریشه پروژه‌های خود اضافه کنید و امضاهای دقیق APIهای داخلی را در آن بنویسید. - برای هر ابزار CLI داخلی، خروجی JSON را پیاده‌سازی کنید تا عامل‌ها بتوانند بدون توهم، نتایج را تحلیل کنند.
- یک مجموعه Eval کوچک شامل خطاهای عمدی بسازید تا نرخ موفقیت عامل خود در اصلاح کد را بسنجید.
اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.
گفتگو