vibe-coding-college-specs/chapters/15-product-evolution/04-lesson-refactoring-and-code-improvement/spec.md

مشخصات درس‌نامه: بهبود ساختار کد، پاک‌سازی و ری‌فکتورینگ امن (Safe Refactoring) با هوش مصنوعی

• شناسه در سیلابس: L15.5
• فصل: فصل ۱۵: تکامل محصول با AI (Ch 15)
• نوع محتوا: 📘 درس‌نامه متنی
• زمان تقریبی مطالعه: ۱۸ دقیقه
• پیش‌نیازهای مستقیم: L15.4 (کالبدشکافی و کاوش در Codebase با ایجنت‌ها)

---

۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)

دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:

• درک کند (Understand): مفهوم ری‌فکتورینگ (Refactoring: اصلاح ساختار درونی بدون تغییر در رفتار بیرونی سیستم) را شرح دهد و بداند چرا کدهای شتاب‌زده MVP نیازمند بازطراحی و پاک‌سازی هستند.
• تحلیل/ارزیابی کند (Evaluate): نشانه‌های بدبویی کد (Code Smells: کامپوننت‌های غول‌پیکر چندصدخطی، کدهای کپی-پیست تکراری، و تایپ‌های مجهول any) را در پروژه شناسایی و ارزیابی کند.
• به‌کار ببندد (Apply): پروتکل ۴ مرحله‌ای ری‌فکتورینگ امن (سپر تست قبلی \rightarrow پرامپت ایزوله اتمیک \rightarrow بازبینی Diff \rightarrow بیلد مجدد) را برای شکستن کامپوننت‌های بزرگ به ماژول‌های تمیز پیاده کند.
• ایجاد کند (Create): یک کامپوننت ۳۰۰ خطی پنل مدیریت پورتفولیو را با هدایت ایجنت به ۴ ساب‌کامپوننت خوانا، ماژولار و تست‌پذیر تفکیک نماید.

---

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

آنچه باید پوشش داده شود (In-Scope):

1. استعاره تمیزکاری و مرتب‌سازی ابزارهای کارگاه:
   • در هنگام ساخت اولیه میخ‌ها و اره‌ها کف کارگاه می‌ریزند؛ پس از ساخت، ابزارها را روی دیوار می‌چینید تا در کارهای بعدی مانع پای شما نشوند.
2. شکار «بوی بد کد» (Code Smells) در پروژه‌های ساخته‌شده با AI:
   • بوی بد ۱: کامپوننت‌های خدای‌گونه (God Components)؛ یک فایل ۴۰۰ خطی که هم دیتابیس می‌خواند، هم فرم رندر می‌کند، هم مودال باز می‌کند و هم انیمیشن دارد!
   • بوی بد ۲: منطق تکراری کپی-پیست‌شده (Duplicate Queries)؛ نوشتن کوئری‌های یکسان سوپابیس در ۵ صفحه مختلف به جای یک تابع واحد.
   • بوی بد ۳: اعدام تایپ‌اسکریپت با کلمه any؛ تنبلی در تعریف تایپ داده‌ها که امنیت کد را از بین می‌برد.
3. پروتکل ۴ مرحله‌ای ری‌فکتورینگ ایمن با ایجنت:
   • مرحله ۱ (سپر دفاعی): اطمینان از پاس شدن تست‌های Vitest/Playwright و اجرای بیلد سالم قبل از هرگونه تغییر.
   • مرحله ۲ (پرامپت اتمیک ایزوله): درخواست جراحی محدود: «فقط این فایل را بشکن؛ به هیچ فایل دیگری دست نزن و نام Props را تغییر نده».
   • مرحله ۳ (بازبینی خط‌به‌خط Git Diff): بررسی اینکه آیا منطق یا استایلی ناخواسته حذف یا مفقود شده است یا خیر.
   • مرحله ۴ (تست تایید سلامت): اجرای مجدد تست‌ها و بیلد نهایی برای اطمینان از صفر بودن خطای پس‌رفتی.
4. کارگاه عملی: جراحی و ماژولار کردن جدول مدیریت پروژه‌ها:
   • تبدیل فایل متورم AdminProjectsTable.tsx به:
     • ProjectRow.tsx (رندر هر سطر)
     • DeleteProjectDialog.tsx (مودال حذف)
     • ProjectStatusBadge.tsx (بج وضعیت)
     • hooks/useProjects.ts (هوک اختصاصی مدیریت استیت‌ها).
5. جعبه پرامپت طلایی برای ری‌فکتورینگ تمیز:
   • پرامپت تخصصی بازنویسی با شرط حفظ ۱۰۰٪ رفتار قبلی.
6. کال‌اوت‌های آموزشی و هشدار کوئرا:
   • کال‌اوت بنفش (<details class="violet">): قانون طلایی مارتین فاولر؛ ری‌فکتورینگ نباید یک پروژه ۶ ماهه جداگانه باشد، بلکه عادتی پیوسته در حین اضافه کردن هر فیچر جدید است.
   • کال‌اوت سبز (<details class="green">): لذت دیدن کدهای تمیز، خوانا و کوتاه که هر برنامه‌نویس ارشدی از دیدن آن شگفت‌زده می‌شود.
   • کال‌اوت قرمز (<details class="red">): اشتباه فاجعه‌بار؛ هرگز به ایجنت نگویید: «کل پروژه را ریفکتور کن!»؛ این پرامپت به توهمات گسترده و شکستن کل برنامه‌ منجر می‌شود.

آنچه نباید وارد آن شویم (Out-of-Scope):

• مهاجرت از فریم‌ورکی به فریم‌ورک دیگر (مثلاً Next.js به Remix یا Vue).
• بازطراحی کل اسکیمای دیتابیس که نیازمند از دست رفتن داده‌های پروداکشن باشد.

---

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

اصطلاح انگلیسی	معادل فارسی مصوب	توضیح یک‌خطی ساده
Refactoring	بازنویسی و بهسازی ساختار	بهبود خوانایی، سادگی و نگهداری‌پذیری کدها بدون تغییر در عملکرد ظاهری آن‌ها
Code Smell	نشانه‌های بدبویی کد	ساختارها و الگوهای نامناسب در کد که نشان‌دهنده نقص در طراحی یا پتانسیل بروز باگ در آینده هستند
God Component	کامپوننت همه‌کاره غول‌پیکر	کامپوننتی تک‌افتاده که وظایف بیش از حد متعددی را بر عهده گرفته و فهم و نگهداری آن کابوس است
Single Responsibility (SRP)	اصل تک‌مسئولیتی	اصل بنیادین مهندسی که می‌گوید هر ماژول یا کامپوننت فقط و فقط باید یک وظیفه مشخص داشته باشد
Atomic Refactoring	بازنویسی اتمیک و دانه‌دانه	اصلاح پله‌پله و ایزوله بخش‌های کوچک کد برای پیشگیری از بروز خطاهای آبشاری در پروژه

---

۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)

راهنمای ایجنت نویسنده: تمام تصاویر باید در پوشهٔ images/ ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:

1. تصویر کاور درس: images/cover.png
   • موضوع: سیم‌پیچی‌های آشفته و گره‌خورده دیجیتال که توسط بازوهای نوری ایجنت باز شده و به کابل‌های مرتب و موازی درخشان تبدیل می‌شوند.
2. شکستن یک کامپوننت غول‌پیکر به ماژول‌های تمیز: images/god-component-decomposition.png
   • موضوع: دیاگرام ساختاری: فایل ۴۰۰ خطی بزرگ در چپ \rightarrow فلش بازطراحی \rightarrow تفکیک به ۴ فایل کوچک، هوک و کامپوننت مستقل در راست.
3. چرخه ۴ مرحله‌ای ری‌فکتورینگ امن: images/safe-refactoring-loop.png
   • موضوع: فلوچارت محافظتی: تست سبز قبلی \rightarrow پرامپت ایزوله \rightarrow بررسی Git Diff \rightarrow راستی‌آزمایی با بیلد موفق.
4. تفاوت Git Diff یک ری‌فکتور موفق: images/refactored-git-diff-view.png
   • موضوع: اسکرین‌شات از نمایش خطوط پاک‌شده اضافه و جایگزینی با ایمپورت‌های ماژولار و بسیار کوتاه.

---

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

1. تیتر اصلی: # بهبود ساختار کد، پاک‌سازی و ری‌فکتورینگ امن (Safe Refactoring) با هوش مصنوعی
2. مقدمه: کدهایتان کار می‌کند، اما شبیه یک کمد لباس به هم ریخته است که هر بار درش را باز می‌کنید چیزی روی سرتان می‌افتد؟ وقت یک خانه‌تکانی لذت‌بخش مهندسی است!
3. جدول کاور درس
4. تعریف ری‌فکتورینگ: تغییر لباس بدون تغییر ماهیت:
   • چرا کاربر نباید هیچ تفاوتی در ظاهر حس کند، اما شما در توسعه آینده ۱۰ برابر سریع‌تر می‌شوید.
5. شکار ۳ بوی بد رایج در پروژه‌های وایب کدینگ:
   • کامپوننت‌های همه‌کاره (God Components)، کدهای تکراری، و فرار از تایپ‌های دقیق.
6. پروتکل ۴ مرحله‌ای جراحی امن کد:
   • تست سلامت \rightarrow پرامپت اتمیک \rightarrow کنترل گیت‌دیف \rightarrow تایید نهایی با بیلد.
7. مطالعه موردی: جراحی جدول ۴۰۰ خطی پنل مدیریت پورتفولیو:
   • تفکیک عملی به ساب‌کامپوننت‌های ProjectRow, DeleteDialog و ساخت هوک useProjects.
8. جعبه پرامپت طلایی: ری‌فکتورینگ اتمیک با ایجنت هوش مصنوعی:
   • پرامپت دقیق:

     «من می‌خواهم فایل AdminProjectsTable.tsx را ری‌فکتور کنم. بدون تغییر در هیچ‌یک از قابلیت‌های فعلی و بدون تغییر نام Props، ۱) این فایل را به ۳ کامپوننت تک‌مسئولیتی در پوشه components/admin/ تقسیم کن، ۲) منطق مدیریت وضعیت‌ها را به یک کاستوم هوک در hooks/useProjects.ts منتقل کن، و ۳) تایپ‌های دقیق تایپ‌اسکریپت بدون استفاده از any برای آن بنویس.»

9. باکس نکته Quera (<details class="violet">): استفاده از تکنیک Boy Scout Rule: «کدبیس را همیشه تمیزتر از آنچه تحویل گرفته‌اید تحویل دهید».
10. باکس هشدار Quera (<details class="red">): هرگز فیچر جدید را همزمان با ریفکتورینگ کد قبلی ننویسید! این دو کار باید در دو کامیت کاملاً مجزا انجام شوند تا در صورت بروز باگ، تفکیک امکان‌پذیر باشد.
11. باکس رضایت‌بخش Quera (<details class="green">): باز کردن فایل اصلی پروژه و دیدن کاهش حجم کد از ۴۰۰ خط به ۵۰ خط بسیار تمیز و سازمان‌یافته.
12. جمع‌بندی درس‌نامه: مجهز شدن به سلاح پاک‌سازی کد؛ ورود به جهان هیجان‌انگیز قابلیت‌های پیشرفته هوش مصنوعی (Semantic Search و خلاصه‌سازها) در درس بعدی.

---

۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)

• مفهوم ری‌فکتورینگ و چرایی اهمیت آن در پروژه‌های فعال تبیین شود.
• نشانه‌های بدبویی کد (Code Smells) با مثال‌های ملموس پورتفولیو شرح داده شوند.
• پروتکل ۴ مرحله‌ای ری‌فکتورینگ امن به همراه پرامپت‌های اتمیک ارائه گردد.
• کارگاه عملی شکستن کامپوننت بزرگ به کامپوننت‌های ماژولار در متن درس گنجانده شود.