# مشخصات درس‌نامه: چرا 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 توضیح داده شوند.
- [ ] راهکارهای عملی (قانون سه شکست و پاکسازی بافت) به عنوان مهارت‌های محوری ارائه گردند.
- [ ] اهمیت اعتبارسنجی مستقل انسان در برابر چاپلوسی مدل مورد تاکید صریح قرار گیرد.