vibe-coding-college-specs/chapters/09-testing-and-debugging/01-lesson-why-agents-make-mistakes/spec.md

مشخصات درس‌نامه: چرا Agent اشتباه می‌کند؟ (Why AI Coding Agents Make Mistakes)

• شناسه در سیلابس: L9.2
• فصل: فصل ۹: تست و Debugging (Ch 9)
• نوع محتوا: 📘 درس‌نامه متنی
• زمان تقریبی مطالعه: ۱۲ دقیقه
• پیش‌نیازهای مستقیم: L9.1 (اهداف فصل نهم)

---

۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)

دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:

• درک کند (Understand): چرا ایجنت‌های هوش مصنوعی مهندس واقعی نیستند، بلکه سیستم‌های پیش‌بینی احتمالاتی هستند و خطاهای آن‌ها ریشه‌های علمی و ساختاری مشخصی دارد.
• تحلیل/ارزیابی کند (Evaluate): پنج ریشه بنیادین خطاهای هوش مصنوعی شامل: فرسودگی کانتکست (Context Bloat)، توهم توابع و پکیج‌ها (Hallucination)، نابینایی نسبت به اثرات جانبی (Cascade Effects)، ابهام در پرامپت کاربر، و چاپلوسی مدل (Sycophancy) را شناسایی و تحلیل کند.
• تحلیل/ارزیابی کند (Evaluate): خطای اختلاط نسخه‌های قدیمی (مانند کدهای منسوخ Next.js 12) با نسخه‌های مدرن (Next.js App Router) توسط ایجنت را تشخیص دهد.
• به‌کار ببندد (Apply): راهکارهای دفاعی پیشگیرانه (بهداشت سشن، مشخص کردن دقیق شماره نسخه استک در پرامپت، و ارجاع صریح به فایل‌ها با @filename) را اجرا کند.
• به‌کار ببندد (Apply): اصل طلایی عدم اعتماد کلامی به ادعای ایجنت («من مشکل را حل کردم!») و راستی‌آزمایی مستقل در ترمینال و مرورگر را نهادینه سازد.

---

۲. محدوده و مرزهای محتوا (Scope & Boundaries)

آنچه باید پوشش داده شود (In-Scope):

1. رمزگشایی از ذهن ایجنت‌های کدنویسی:
   • هوش مصنوعی با شما دشمنی ندارد و خنگ نیست؛ مدل‌ها تابع فیزیک محاسباتی و توزیع احتمالات هستند. شناخت این نقاط ضعف، شما را به یک راهنمای مقتدر تبدیل می‌کند.
2. کالبدشکافی ۵ ریشه اصلی خطاهای ایجنت:
   • ریشه ۱: فرسودگی پنجره بافت و پدیده گم‌شدگی در میانه (Lost in the Middle):
     • در چت‌های طولانی، توجه مدل به پیام‌های میانی به شدت افت می‌کند و شروط اولیه (مثل «از تایپ‌اسکریپت استفاده کن») را از یاد می‌برد.
   • ریشه ۲: توهم و استفاده از کدهای منسوخ (Hallucinated & Outdated APIs):
     • مدل‌های زبانی روی داده‌های گذشته اینترنت آموزش دیده‌اند؛ بنابراین ممکن است ناخودآگاه کدهای قدیمی Next.js Pages Router (مانند getServerSideProps) را وارد پروژه App Router مدرن شما کنند یا متدهایی خیالی در Supabase بسازند.
   • ریشه ۳: نابینایی نسبت به اثرات جانبی (Scope Blindness & Cascade Bugs):
     • ایجنت یک باگ را در کامپوننت ProjectCard.tsx درست می‌کند، اما نمی‌بیند که این تغییر باعث شکسته شدن ورودی‌ها در ProjectsGrid.tsx شده است.
   • ریشه ۴: پرامپت‌های مبهم و کلی کاربر:
     • گفتن «دکمه لاگین کار نمی‌کند» به جای ارسال متن دقیق خطای قرمز کنسول.
   • ریشه ۵: پدیده چاپلوسی و اعتمادبه‌نفس کاذب (AI Sycophancy):
     • مدل‌ها به گونه‌ای آموزش دیده‌اند که شما را خوشحال کنند؛ به همین دلیل با لحنی کاملاً شاداب می‌گویند: «مشکل با موفقیت حل شد!» حتی اگر کد اصلاً کامپایل نشود!
3. پادزهرهای عملی برای مهار لغزش ایجنت‌ها:
   • قانون سه شکست: اگر ایجنت در ۳ پرامپت متوالی نتوانست باگ را حل کند، ادامه دادن چت فایده‌ای ندارد؛ پنجره را ببندید و در یک سشن تازه مسئله را به صورت ایزوله شرح دهید.
   • تزریق صریح نسخه در پرامپت: قید کردن عبارت «استفاده از Next.js 15 App Router و Supabase v2».
   • ارجاع متمرکز: استفاده از نشانه @ در ادیتور Cursor برای اضافه کردن فقط فایل‌های درگیر به بافت چت.
4. کال‌اوت‌های Quera:
   • <details class="violet">: پدیده چاپلوسی هوش مصنوعی؛ چرا تأییدیه کلامی مدل ارزش فنی ندارد و تنها سند معتبر، خروجی بدون خطای کامپایلر است؟
   • <details class="red">: تله اصرار در چت آلوده؛ هرگز وقت و توکن‌های خود را با جدال بی‌پایان در یک پنجره پر از خطا تلف نکنید.

آنچه نباید وارد آن شویم (Out-of-Scope):

• آموزش انواع تست‌های خودکار (درس بعدی ۹.۳).
• ابزارهای گرافیکی مانیتورینگ کارایی سرور (فصل ۱۳).

---

۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

اصطلاح انگلیسی	معادل فارسی مصوب	توضیح یک‌خطی ساده
Lost in the Middle	گم‌شدگی در میانه	پدیده کاهش تمرکز مدل‌های زبانی بر اطلاعات واقع در میانه مکالمات طولانی
AI Sycophancy	چاپلوسی / تاییدطلبی مدل	تمایل هوش مصنوعی به تایید مثبت فرضیات کاربر حتی در صورت نادرست بودن کدها
Cascade Failure	شکست زنجیره‌ای	خطایی که در اثر اصلاح یک بخش، به طور دومینووار سایر بخش‌های سالم برنامه را تخریب می‌کند
Deprecated Syntax	سینتکس منسوخ	دستورات و کدهای قدیمی فریم‌ورک‌ها که در نسخه‌های جدید پشتیبانی نمی‌شوند
Context Cleansing	پاکسازی و تصفیه بافت	بستن چت‌های شلوغ و باز کردن یک سشن تمیز با ارجاع به فایل‌های ضروری

---

۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)

راهنمای ایجنت نویسنده: تمام تصاویر باید در پوشهٔ images/ قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:

1. تصویر کاور درس: images/cover.png
   • موضوع: کاور مدرن با تم تیره که مغز شیشه‌ای هوش مصنوعی را با مدارهای جرقه‌زننده و چراغ‌های هشدار زرد نئونی در حال تحلیل خطا نشان می‌دهد.
2. پنج ریشه بنیادین خطاهای ایجنت: images/ai-failure-modes-diagram.png
   • موضوع: اینفوگرافیک ۵ پرچم قرمز: فرسودگی کانتکست، توهم کد، نابینایی اثرات جانبی، پرامپت گنگ، و تایید کاذب.
3. نمودار پدیده Lost in the Middle: images/lost-in-the-middle-curve.png
   • موضوع: نمودار U شکل که نشان می‌دهد توجه مدل در ابتدا و انتهای چت ۱۰۰٪ است اما در وسط مکالمه به شدت افت می‌کند.
4. مقایسه کدهای منسوخ با کدهای مدرن: images/deprecated-vs-modern-code.png
   • موضوع: تصویر مقایسه‌ای: کدهای قدیمی Pages Router در برابر کدهای استاندارد App Router با علامت ضربدر قرمز و تیک سبز.
5. قانون سه‌گانه ریست سشن: images/three-strikes-reset-rule.png
   • موضوع: فلوچارت تصمیم‌گیری: تلاش ۱ \rightarrow تلاش ۲ \rightarrow تلاش ۳ \rightarrow توقف فوری و باز کردن چت تمیز جدید.

---

۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (README.md)

1. تیتر اصلی: # چرا Agent اشتباه می‌کند؟ رمزگشایی از نقاط کور هوش مصنوعی
2. مقدمه: چرا خونسردترین توسعه‌دهندگان، آن‌هایی هستند که طرز کار و اشتباهات هوش مصنوعی را پیش‌بینی می‌کنند؟
3. جدول کاور درس
4. هوش مصنوعی مهندس نیست؛ ماشین احتمالات است: درک واقعیت پردازش توکن‌ها.
5. پنج دلیل اصلی که ایجنت‌ها را به بیراهه می‌برد:
   • فرسودگی بافت و پدیده فراموشی در میانه (Lost in the Middle).
   • توهم و استفاده تصادفی از کدهای دوره‌افتاده و منسوخ.
   • نابینایی نسبت به اثرات زنجیره‌ای در سایر فایل‌ها.
   • ابهام در ورودی‌های ما (Garbage In, Garbage Out).
   • چاپلوسی مدل: چرا AI همیشه می‌گوید همه چیز عالی است؟!
6. باکس نکته Quera (<details class="violet">): روان‌شناسی ایجنت‌ها؛ چرا نباید به جملات امیدوارکننده مدل بدون تست در مرورگر اعتماد کرد؟
7. استراتژی‌های دفاعی برای وایب کدرهای برنده:
   • قانون طلایی سه شکست (Three Strikes Rule).
   • تزریق قیدهای صریح نسخه فریم‌ورک در پرامپت.
   • ارجاع لیزری به فایل‌ها با استفاده از کاراکتر @.
8. باکس هشدار Quera (<details class="red">): هرگز در چت‌های پر از خطا نجنگید؛ سشن تمیز معجزه می‌کند.
9. جمع‌بندی درس‌نامه: تسلط بر روان‌شناسی خطاهای ایجنت و آماده‌سازی برای آشنایی با انواع تست‌های نرم‌افزاری در درس بعد.

---

۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)

• ریشه‌های ۵ گانه خطاهای ایجنت‌های هوش مصنوعی با استدلال‌های فنی و روان تحلیل شده باشند.
• پدیده‌های Lost in the Middle و کدهای منسوخ با مثال‌های واقعی Next.js توضیح داده شوند.
• راهکارهای عملی (قانون سه شکست و پاکسازی بافت) به عنوان مهارت‌های محوری ارائه گردند.
• اهمیت اعتبارسنجی مستقل انسان در برابر چاپلوسی مدل مورد تاکید صریح قرار گیرد.