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