# مشخصات درس‌نامه: کالبدشکافی و کاوش در Codebase با ایجنت‌های هوش مصنوعی
- **شناسه در سیلابس:** `L15.4`
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
- **نوع محتوا:** 📘 درس‌نامه متنی
- **زمان تقریبی مطالعه:** ۱۶ دقیقه
- **پیش‌نیازهای مستقیم:** `L15.3` (تعریف ویژگی جدید و تدوین مشخصات دقیق)

---

## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- [ ] **درک کند (Understand):** چگونه مدل‌های زبانی مجهز به پنجره‌های زمینه غول‌پیکر (Context Windows) و نمایه‌سازی برداری (Vector Indexing) به عنوان باستان‌شناسان کدهای نرم‌افزار عمل می‌کنند.
- [ ] **تحلیل/ارزیابی کند (Evaluate):** جریان داده و چرخه حیات یک رویداد کامل در سیستم (نظیر مسیر ثبت رزرو از کلیک تا پیامک) را با پرسشگری مهندسی از ایجنت ردگیری و تحلیل کند.
- [ ] **به‌کار ببندد (Apply):** قابلیت جستجوی معنایی در کل مخزن (`@codebase` در Cursor و ابزارهای تحلیلی Antigravity / Claude Code) را برای کشف فایل‌های مرتبط و تحلیل اثرگذاری تغییرات (Impact Analysis) به کار گیرد.
- [ ] **ایجاد کند (Create):** نمودارهای تعاملی و فلوچارت‌های زنده‌ی معماری پروژه را به صورت خودکار از روی کدهای واقعی با پرامپت‌نویسی استخراج کند.

---

## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)

### آنچه باید پوشش داده شود (In-Scope):
1. **معمای فراموشی کدها: «این فایل ۳ هفته پیش چطور کار می‌کرد؟»:**
   * حتی سازنده اصلی پروژه پس از چند هفته جزییات دقیق اتصالات توابع و روت‌ها را فراموش می‌کند؛ چه رسد به پیوستن به پروژه‌ای که فرد دیگری نوشته است!
2. **پشت صحنه ایندکس کردن کدهای پروژه (`@codebase` Indexing):**
   * تبدیل قطعات کد به بردارهای معنایی (Embeddings) و امکان جستجوی مفهومی؛ مثلاً جستجوی «کجا پیامک ارسال می‌شود؟» به جای جستجوی کلمه به کلمه.
3. **تکنیک پرسشگری مهندسی از ایجنت (Architectural Inquiries):**
   * پرسش ۱ (ردگیری چرخه حیات): «چرخه حیات یک رزرو مشاوره را از لحظه کلیک کاربر تا ثبت در Supabase، اتصال به زرین‌پال و ارسال پیامک کاوه‌نگار گام‌به‌گام با ذکر نام فایل‌ها و توابع توضیح بده.»
   * پرسش ۲ (تحلیل اثر تغییر - Impact Analysis): «اگر ساختار فیلد `slug` را در جدول پروژه‌ها تغییر دهم، دقیقاً کدام کامپوننت‌ها و روت‌ها در خطر شکستن هستند؟»
   * پرسش ۳ (نقشه‌برداری وابستگی‌ها): «کدام فایل‌ها از تابع `createClient` سوپابیس استفاده می‌کنند؟»
4. **تولید نمودارهای زنده از دل کدهای موجود:**
   * درخواست از ایجنت برای تولید دیاگرام توالی (Sequence Diagram) با فرمت Mermaid برای درک سریع جریان احراز هویت.
5. **جعبه پرامپت طلایی برای کاوش و درک کدهای پروژه:**
   * پرامپت جامع اسکن معماری و ایجاد سند `architecture-overview.md`.
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
   * کال‌اوت بنفش (`<details class="violet">`): مفهوم پنجره زمینه بزرگ (Large Context)؛ تفاوت توانایی پردازش همزمان صدها فایل در مدل‌های روز در مقایسه با نسل‌های اولیه.
   * کال‌اوت سبز (`<details class="green">`): توانایی شگفت‌انگیز برای ورود به هر ریپازیتوری اوپن‌سورس غریبه در گیت‌هاب و درک معماری آن در کمتر از ۱۵ دقیقه.
   * کال‌اوت قرمز (`<details class="red">`): پرهیز از سوالات کلی و مبهم مانند «کل کدها رو توضیح بده»؛ همیشه سوالات مشخص با سناریوهای کاربردی بپرسید تا پاسخ دقیق بگیرید.

### آنچه نباید وارد آن شویم (Out-of-Scope):
- مباحث ریاضیات و جبر خطی نحوه تولید بردارها در شبکه‌های عصبی (Vector Math).
- پیاده‌سازی دستی دیتابیس‌های برداری Pinecone یا Chroma از صفر.

---

## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
| :--- | :--- | :--- |
| Codebase Comprehension | درک جامع ساختار کدبیس | فرآیند شناخت ساختار معماری، وابستگی‌ها و جریان داده در یک پروژه نرم‌افزاری بزرگ |
| Impact Analysis | تحلیل اثرگذاری تغییرات | پیش‌بینی دقیق تمام فایل‌ها و ماژول‌هایی که با تغییر یک تابع یا اسکیمای دیتابیس تحت‌تاثیر قرار می‌گیرند |
| Semantic Code Search | جستجوی معنایی کد | یافتن توابع و منطق‌های برنامه بر اساس مفهوم و کارکرد آن‌ها، نه صرفاً تطابق نام کلمات |
| Context Window | پنجره کانتکست مدل | حجم داده و تعداد کدهایی که مدل زبانی می‌تواند در یک لحظه در حافظه خود نگه دارد |
| Sequence Diagram | دیاگرام توالی | نمودار زمانی نمایش‌دهنده ترتیب تبادل پیام‌ها و درخواست‌ها میان اجزای مختلف سیستم |

---

## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:

1. **تصویر کاور درس:** `images/cover.png`
   * **موضوع:** ذره‌بین اشعه ایکس دیجیتال نئونی که لایه‌های تو در توی کدهای یک پروژه نرم‌افزاری را روشن و شفاف می‌کند.
2. **پشت صحنه ایندکس معنایی کدهای پروژه:** `images/codebase-indexing-architecture.png`
   * **موضوع:** دیاگرام فرآیند: فایل‌های پروژه $\rightarrow$ تولید بردارها $\rightarrow$ دیتابیس برداری محلی ادیتور $\rightarrow$ پاسخگویی فوق‌سریع به پرامپت `@codebase`.
3. **نمودار توالی جریان داده رزرو در پورتفولیو:** `images/booking-sequence-diagram.png`
   * **موضوع:** دیاگرام توالی Mermaid رندرشده: کاربر $\rightarrow$ فرم رزرو $\rightarrow$ Server Action $\rightarrow$ Supabase $\rightarrow$ زرین‌پال $\rightarrow$ کاوه‌نگار.
4. **نمایش پاسخ تحلیلی ایجنت به سوال اثرگذاری تغییر:** `images/ai-impact-analysis-chat.png`
   * **موضوع:** اسکرین‌شات از چت‌باکس Cursor که لیست فایل‌های در معرض خطر تغییر ستون دیتابیس را با نشانه‌گذاری قرمز و سبز ردیف کرده است.

---

## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)

1. **تیتر اصلی:** `# کالبدشکافی و کاوش در Codebase با ایجنت‌های هوش مصنوعی`
2. **مقدمه:** چگونه در پروژه‌ای با ده‌ها پوشه و هزاران خط کد، در عرض ۲ دقیقه بفهمیم هر قطعه دقیقاً چه وظیفه‌ای دارد؟
3. **جدول کاور درس**
4. **استعاره استخدام یک راهنمای محلی در شهری ناشناخته:**
   * به جای سرگردانی در کوچه‌ها، از راهنمایی که تمام نقشه شهر را از حفظ است آدرس دقیق را بپرسید.
5. **قدرت جادویی نمایه برداری و جستجوی معنایی (`@codebase`):**
   * چطور ادیتور بدون کپی کردن دستی فایل‌ها، تمام پروژه شما را می‌فهمد.
6. **هنر مصاحبه معمارانه با ایجنت:**
   * ۳ فرمول پرامپت طلایی: ردگیری جریان داده، تحلیل اثر تغییر، و کشف منطق‌های پنهان.
7. **مطالعه موردی: استخراج چرخه کامل پرداخت و پیامک در پورتفولیو:**
   * مشاهده خروجی گام‌به‌گام ایجنت و راستی‌آزمایی آن با فایل‌های واقعی.
8. **رسم خودکار دیاگرام‌های توالی با Mermaid:**
   * دستور به ایجنت برای تبدیل منطق پنهان کدها به نقشه گرافیکی خوانا.
9. **جعبه پرامپت طلایی: تحلیل اثرگذاری تغییرات قبل از دستکاری کد:**
   * پرامپت دقیق:
     > «من می‌خواهم فیلد `price` را در جدول جلسات مشاوره به `amount_toman` تغییر نام دهم. لطفاً کل `@codebase` را تحلیل کن و ۱) تمام فایل‌ها، کامپوننت‌ها، تایپ‌ها و روت‌هایی که تحت‌تاثیر این تغییر قرار می‌گیرند را لیست کن، ۲) خطرات احتمالی در فرانت‌اند و درگاه پرداخت را شرح بده، و ۳) ترتیب امن اعمال این تغییر را مرحله‌بندی نما.»
10. **باکس نکته Quera (`<details class="violet">`):** کلید میانبر `@docs` برای اضافه کردن مستندات فریم‌ورک‌های خارجی در کنار `@codebase` خودی.
11. **باکس هشدار Quera (`<details class="red">`):** ایجنت‌ها ممکن است در پروژه‌های بسیار بزرگ فایل‌هایی با ایمپورت‌های داینامیک را از قلم بیندازند؛ همیشه از ابزار جستجوی سراسری متنی (Grep) به عنوان مکمل استفاده کنید.
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** احساس تسلط مطلق بر کل پروژه؛ انگار که خودتان تک‌تک خطوط را از حفظ هستید.
13. **جمع‌بندی درس‌نامه:** تسلط بر تحلیل کدهای موجود؛ ورود به حوزه حساس و حیاتی بازنویسی و ری‌فکتورینگ امن (Safe Refactoring) در درس بعدی.

---

## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- [ ] نحوه کارکرد ایندکس معنایی کدهای پروژه (`@codebase`) تشریح شود.
- [ ] تکنیک‌های تحلیل چرخه حیات داده و تحلیل اثرگذاری تغییرات (Impact Analysis) آموزش داده شود.
- [ ] شیوه تولید خودکار دیاگرام‌های معماری با Mermaid از روی کدهای پروژه ارائه گردد.
- [ ] پرامپت‌های مهندسی کاوش در کدهای موجود به همراه مثال‌های ملموس لحاظ شود.