vibe-coding-college-specs/chapters/15-product-evolution/03-lesson-codebase-analysis-with-agents/spec.md

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