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

chapters/09-testing-and-debugging/05-lesson-resolving-common-errors/spec.md

@@ -0,0 +1,124 @@
+# مشخصات درس‌نامه: دیباگ تعاملی با Agent، ابزارهای حاشیه‌نویسی و حل خطاهای متداول
+- **شناسه در سیلابس:** `L9.6`
+- **فصل:** فصل ۹: تست و Debugging (Ch 9)
+- **نوع محتوا:** 📘 درس‌نامه متنی
+- **زمان تقریبی مطالعه:** ۱۸ دقیقه
+- **پیش‌نیازهای مستقیم:** `L9.5` (اصول دیباگ کردن خطاها و خواندن لاگ‌ها)
+
+---
+
+## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
+دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
+- [ ] **درک کند (Understand):** تفاوت دیباگ مکانیکی سنتی با «دیباگ تعاملی با ایجنت» (Interactive Agentic Debugging) چیست و چگونه می‌توان از قابلیت‌های نوین ابزارهای Cursor، Claude Code و Antigravity (نظیر ارجاع مستقیم به ترمینال و اسکرین‌شات) بیشترین بهره را برد.
+- [ ] **تحلیل/ارزیابی کند (Evaluate):** پدیده مخرب «چرخه باطل عذرخواهی و وصله‌پینه» (Apology & Patching Loop) را در ایجنت‌ها شناسایی کند و بداند چه زمانی باید گفتگو را متوقف کرده و با Git Rollback از ابتدا شروع نماید.
+- [ ] **به‌کار ببندد (Apply):** ۴ خطای پرتکرار و مرگبار در دنیای وایب کدینگ (سیاست‌های RLS سوپابیس، کلیدهای مخفی تعریف‌نشده در `.env`، تداخل کلاینت/سرور کامپوننت و تغییرات Dynamic Params در نکست‌جی‌اس) را با الگوهای تضمینی حل کند.
+- [ ] **ایجاد کند (Create):** یک پرامپت ایزوله‌سازی با تزریق لاگ‌های موقت (`console.log`) ایجاد کند تا ایجنت بتواند نقطه دقیق قطع جریان داده را بدون تغییرات غیرضروری در سایر فایل‌ها شناسایی کند.
+
+---
+
+## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
+
+### آنچه باید پوشش داده شود (In-Scope):
+1. **انقلاب در روش دیباگ: دیباگ تعاملی به جای سردرگمی در کد:**
+   * چگونه بدون خواندن هزار خط کد، مستقیماً با ایجنت دیالوگ مهندسی برقرار کنیم؟
+2. **ابزارهای پیشرفته حاشیه‌نویسی بصری و اتصال به محیط (Visual Annotation & Context):**
+   * استفاده از قابلیت بازرسی مرورگر داخلی و گرفتن اسکرین‌شات از المان معیوب.
+   * ویژگی ارجاع مستقیم به خروجی ترمینال در ابزارهای مدرن (کلید `@terminal` در Cursor یا خواندن خودکار در Claude Code).
+3. **شکستن چرخه باطل «عذرخواهی می‌کنم، الان درستش می‌کنم!» (The Apology Loop):**
+   * وقتی ایجنت به بن‌بست می‌رسد و شروع به تکرار کدهای اشتباه یا خراب کردن بخش‌های سالم می‌کند:
+     - قانون طلایی سه تلاش (Three-Strikes Rule): بعد از دو بار ناموفق بودن، فوراً `git checkout` یا `git stash` بزنید.
+     - پاک کردن Context چت و شروع یک گفتگوی تازه با پرامپت دقیق‌تر و کانتکست ایزوله.
+4. **کالبدشکافی ۴ تله فوق‌العاده رایج و راه‌حل قطعی آن‌ها:**
+   * تله ۱: خطای ۴۰۳ یا خالی بودن لیست پروژه‌ها در Supabase $\leftarrow$ فراموشی یا نقص در تعریف سیاست RLS.
+   * تله ۲: مقدار `undefined` برای متغیرهای محیطی $\leftarrow$ پیشوند اشتباه `NEXT_PUBLIC_` یا فراموشی ری‌استارت سرور.
+   * تله ۳: خطای React در هوک‌ها (`useState` / `useEffect`) $\leftarrow$ نبود دایرکتیو `'use client'` در بالای فایل.
+   * تله ۴: خطای تایپ یا اجرای Dynamic Routes در Next.js مدرن $\leftarrow$ ناهمگام بودن دسترسی به `params`.
+5. **تکنیک لاگ‌گذاری موقت (Minimal Instrumentation):**
+   * درخواست از ایجنت برای افزودن ۳ خط `console.log` برای دیدن خروجی متغیرها در ترمینال، قبل از هرگونه بازنویسی کد.
+6. **دستورات چندسکویی برای بازگشت سریع به آخرین وضعیت پایدار گیت (Rollback):**
+   * دستورات پاک کردن تغییرات تست و بازگشت به کامیت قبلی در سه سیستم‌عامل.
+7. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
+   * کال‌اوت بنفش (`<details class="violet">`): قابلیت‌های ویژه اپلیکیشن‌های دسکتاپ هوش مصنوعی در درک باگ‌های بصری.
+   * کال‌اوت سبز (`<details class="green">`): آرامش خاطر با کامیت‌های متوالی و کوچک؛ بیمه بدنه کدهای شما.
+   * کال‌اوت قرمز (`<details class="red">`): خطر تایید تغییرات در فایل‌های کانفیگ اصلی (`next.config.js`, `tsconfig.json`) توسط ایجنت در حالت سردرگمی.
+
+### آنچه نباید وارد آن شویم (Out-of-Scope):
+- تنظیمات CI/CD ابری و اکشن‌های گیت‌هاب (فصل ۱۲ و ۱۳).
+- تست‌های نفوذ و دیباگ باگ‌های امنیتی پیشرفته (فصل ۱۱).
+
+---
+
+## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
+
+| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
+| :--- | :--- | :--- |
+| Interactive Debugging | دیباگ تعاملی | فرآیند گفتگوی پیوسته و هوشمند با ایجنت برای رفع پله‌پله خطاها بر اساس شواهد |
+| Visual Annotation | حاشیه‌نویسی بصری | مشخص کردن المان معیوب رابط کاربری با کادر یا اسکرین‌شات و ارجاع مستقیم آن به ایجنت |
+| Apology Loop | چرخه باطل عذرخواهی | وضعیتی که مدل به طور پیوسته عذرخواهی کرده و راه‌حل‌های بی‌اثر را تکرار می‌کند |
+| Three-Strikes Rule | قانون سه ضربه | توقف گفتگو با ایجنت پس از دو تلاش ناموفق برای جلوگیری از خرابکاری‌های بیشتر در کد |
+| Clean Context Window | پنجره کانتکست پاک | شروع یک چت کاملاً جدید برای زدودن خطاهای قبلی و تمرکز مجدد ایجنت روی مسئله |
+| Git Rollback | بازگشت به نسخه پایدار گیت | لغو تغییرات معیوب اخیر و بازگرداندن فایل‌ها به آخرین کامیت سالم |
+
+---
+
+## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
+> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای درج شوند:
+
+1. **تصویر کاور درس:** `images/cover.png`
+   * **موضوع:** تقابل یک حلقه باطل تو در تو با یک مسیر مستقیم خروج اضطراری و دیباگ موفق با ایجنت.
+2. **قابلیت حاشیه‌نویسی المان در ادیتور:** `images/visual-element-annotation.png`
+   * **موضوع:** تصویر ابزار انتخاب المان در مرورگر یا ادیتور مدرن که کاربر دور دکمه به‌هم‌ریخته کادر کشیده و ایجنت به کد آن متصل شده است.
+3. **چرخه شکستن تله عذرخواهی ایجنت:** `images/breaking-apology-loop.png`
+   * **موضوع:** اینفوگرافیک گام‌به‌گام: خطای تکراری $\rightarrow$ توقف $\rightarrow$ بازگشت به آخرین کامیت (`git checkout`) $\rightarrow$ چت جدید با کانتکست خلوت.
+4. **جدول راهنمای ۴ خطای طلایی و راه‌حل:** `images/common-errors-matrix.png`
+   * **موضوع:** ماتریس گرافیکی ۴ خطای مشهور (RLS، Environment Variables، 'use client'، Dynamic Params) با تصویر خطای قرمز و کد حل مشکل.
+
+---
+
+## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
+
+1. **تیتر اصلی:** `# دیباگ تعاملی با Agent، ابزارهای حاشیه‌نویسی و حل خطاهای متداول`
+2. **مقدمه:** وقتی ایجنت ۵ بار پشت سر هم می‌گوید «عذرخواهی می‌کنم، این بار مطمئناً درست شد!» و پروژه خراب‌تر می‌شود، چطور ترمز دستی را بکشیم؟
+3. **جدول کاور درس**
+4. **تکنیک حاشیه‌نویسی بصری (Visual Annotation):**
+   * عکس بفرستید، نه هزار کلمه توضیح! چطور اسکرین‌شات یا المان خراب را مستقیم به خورد مدل بدهیم؟
+   * اتصال مستقیم لاگ‌های ترمینال با `@terminal`.
+5. **روان‌شناسی مدل‌های زبانی: چرا ایجنت در چرخه باطل وصله‌پینه می‌افتد؟**
+   * پدیده «لج‌بازی توکنی» وقتی تاریخچه چت پر از کدهای اشتباه قبلی است.
+   * قانون سه ضربه (Three-Strikes Rule): بعد از تلاش دوم، کلید Reset را بزنید.
+6. **جعبه ابزار خروج اضطراری: بازگشت به نقطه امن با Git:**
+   * نحوه استفاده از دکمه Discard در VS Code یا کامندهای پاک‌سازی ترمینال.
+7. **کالبدشکافی ۴ خطای پرتکرار در پروژه پورتفولیو و نسخه شفابخش آن‌ها:**
+   * خطای شماره ۱: دیتابیس Supabase پاسخ نمی‌دهد و لیست خالی برمی‌گرداند (سیاست RLS عمومی).
+   * خطای شماره ۲: کلیدهای محیطی `process.env` مقدار `undefined` دارند.
+   * خطای شماره ۳: خطای کامپوننت‌های کلاینت در استفاده از هوک‌های React.
+   * خطای شماره ۴: خطای تغییرات Next.js 15+ در دریافت پارامترهای آدرس داینامیک.
+8. **باکس نکته Quera (`<details class="violet">`):** استفاده از پرامپت «فقط ۳ خط لاگ موقت اضافه کن» برای فهمیدن اینکه داده تا کدام خط می‌آید و کجا قطع می‌شود.
+9. **دستورات چندسکویی بازگشت به وضعیت سالم قبلی در Git:**
+   * منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
+     - Windows (PowerShell):
+       ```powershell
+       git restore .
+       git clean -fd
+       ```
+     - macOS (Terminal):
+       ```bash
+       git restore .
+       git clean -fd
+       ```
+     - Linux (Bash):
+       ```bash
+       git restore .
+       git clean -fd
+       ```
+10. **باکس هشدار Quera (`<details class="red">`):** هرگز اجازه ندهید ایجنت فایل‌های `package.json` یا کانفیگ‌های اصلی فریم‌ورک را برای حل یک خطای ساده کامپوننت زیر و رو کند!
+11. **باکس انرژی‌بخش Quera (`<details class="green">`):** اکنون شما یک محصول ضدضربه و پایدار ساخته‌اید و آماده اتصال آن به شاهراه‌های دنیای واقعی در فصل ۱۰ هستید.
+12. **جمع‌بندی فصل نهم و پیش‌نمایش فصل دهم:** پایان فصل تست و دیباگ؛ ورود به فصل جذاب دهم: اتصال سرویس‌های خارجی (پیامک، ایمیل، درگاه پرداخت و هوش مصنوعی).
+
+---
+
+## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
+- [ ] تکنیک‌های دیباگ بصری و استفاده از لاگ ترمینال به شکل عملی شرح داده شود.
+- [ ] پدیده چرخه باطل عذرخواهی و قانون سه ضربه (Three-Strikes Rule) تبیین گردد.
+- [ ] ۴ خطای فوق‌متداول توسعه وب مدرن به همراه سناریوهای پروژه پورتفولیو تشریح شود.
+- [ ] دستورات ترمینالی بازگشت به وضعیت سالم در گیت برای هر سه سیستم‌عامل ارائه گردد.