feat: add chapter 09-testing-and-debugging specs

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

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