101 lines
12 KiB
Markdown
101 lines
12 KiB
Markdown
# مشخصات درس‌نامه: کالبدشکافی و کاوش در 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 از روی کدهای پروژه ارائه گردد.
|
||
- [ ] پرامپت‌های مهندسی کاوش در کدهای موجود به همراه مثال‌های ملموس لحاظ شود.
|