vibe-coding-college-specs/chapters/09-testing-and-debugging/05-lesson-resolving-common-errors/spec.md

مشخصات درس‌نامه: دیباگ تعاملی با 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):

       git restore .
       git clean -fd
       

     • macOS (Terminal):

       git restore .
       git clean -fd
       

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