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