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

---

## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- [ ] **درک کند (Understand):** تفاوت بنیادین میان «مشخصات پروژه از صفر» (Greenfield Spec) با «مشخصات تغییر روی پروژه زنده» (Delta Spec / Feature Spec) را شرح دهد و بداند چرا اضافه کردن فیچر به کدبیس فعال، نیازمند قیود منفی سخت‌گیرانه است.
- [ ] **تحلیل/ارزیابی کند (Evaluate):** خطرات یک پرامپت مبهم یک‌خطی (مانند «تگ‌ها را به پروژه‌ها اضافه کن») را در مقایسه با یک سند مهندسی مشخصات فیچر (شامل داستان کاربر، مرزها، تغییرات دیتابیس و شروط پذیرش) ارزیابی نماید.
- [ ] **به‌کار ببندد (Apply):** ساختار استاندارد ۶ بخشی سند مشخصات فیچر (User Story, Boundaries, DB Migrations, UI States, Acceptance Criteria, Negative Constraints) را برای قابلیت «فیلتر پروژه‌ها بر اساس تگ‌های مهارتی» تدوین کند.
- [ ] **ایجاد کند (Create):** فایل مشخصات را در پوشه `.specs/` پروژه ذخیره کرده و با استفاده از دستورات ارجاع هوشمند (`@specs/...`) ایجنت را برای پیاده‌سازی گام‌به‌گام هدایت نماید.

---

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

### آنچه باید پوشش داده شود (In-Scope):
1. **چرا اضافه کردن فیچر به محصول زنده خطرناک‌تر از ساخت اولیه است؟**
   * خطر شکستن دیتابیس، پاک شدن تصادفی کدهای قبلی توسط ایجنت، یا ایجاد ناسازگاری در کامپوننت‌های سالم.
2. **کالبدشکافی سند مشخصات دلتا (The Delta Feature Spec):**
   * بخش ۱: داستان کاربر (User Story): «به عنوان یک کارفرما، می‌خواهم پروژه‌ها را بر اساس تگ‌های مهارتی فیلتر کنم تا سریعاً نمونه‌کارهای مرتبط با نیاز شرکتم را ببینم».
   * بخش ۲: محدوده دقیق ورود و خروج (In-Scope vs Out-of-Scope).
   * بخش ۳: تغییرات پایگاه داده (Schema Migration): افزودن ستون آرایه‌ای `tags text[]` به جدول `projects` در Supabase بدون دست زدن به سایر ستون‌ها.
   * بخش ۴: تغییرات رابط کاربری (UI Component Specs): طراحی چیپ‌های تگ فیلتر (Chips) با حالت‌های فعال و غیرفعال بالای گرید پروژه‌ها.
   * بخش ۵: معیارهای پذیرش شفاف (Given-When-Then): «هنگامی که روی تگ Next.js کلیک شد، تنها پروژه‌های دارای این تگ نمایش داده شوند و دکمه ریست ظاهر شود».
   * بخش ۶: قیود منفی نجات‌بخش (Negative Constraints): «به هیچ وجه چیدمان پنل ادمین را تغییر نده؛ هیچ تغییری در روت‌های داینامیک ایجاد نکن».
3. **سازماندهی پوشه `.specs/` در ریشه پروژه:**
   * مستندسازی تمام تغییرات آینده برای اینکه تاریخچه تکامل محصول برای ایجنت شفاف بماند.
4. **جعبه پرامپت طلایی: تغذیه سند مشخصات به کامپوزر ادیتور:**
   * نحوه فراخوانی `@specs/feature-tags-filter.md` و دستور اجرای مرحله‌ای.
5. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
   * کال‌اوت بنفش (`<details class="violet">`): مفهوم قیود منفی (Negative Constraints)؛ قدرتمندترین سلاح شما برای جلوگیری از خرابکاری ایجنت در بخش‌های سالم کد.
   * کال‌اوت سبز (`<details class="green">`): پیاده‌سازی بی‌نقص فیچر در اولین تلاش وقتی ایجنت یک سند مشخصات شفاف در دست دارد.
   * کال‌اوت قرمز (`<details class="red">`): تله دستورات شفاهی کوتاه در چت؛ هرگز بدون نوشتن سند مشخصات وارد تغییرات ساختاری در دیتابیس نشوید.

### آنچه نباید وارد آن شویم (Out-of-Scope):
- بازنویسی کامل ساختار معماری (در درس ۱۵.۵ ریفکتورینگ بررسی می‌شود).
- تعریف مستندات نیازمندی‌های پروژه‌های شرکتی صد صفحه‌ای (BRD سازمانی).

---

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

| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
| :--- | :--- | :--- |
| Feature Specification | مشخصات فنی ویژگی | سند ساختاریافته تشریح‌کننده هدف، رفتار، تغییرات دیتابیس و شروط پذیرش یک قابلیت جدید |
| Delta Spec | مشخصات تغییرات دلتا | سندی که تنها تغییرات، تفاوت‌ها و افزونه‌ها را نسبت به کدبیس موجود توصیف می‌کند |
| Negative Constraints | قیود و شروط منفی | دستورات بازدارنده‌ای که به ایجنت صراحتاً دیکته می‌کنند به کدام بخش‌های کد نباید دست بزند |
| Greenfield vs Brownfield | پروژه نوساز در برابر بازسازی | تمایز میان توسعه از نقطه صفر با توسعه و افزودن فیچر به کدهای از پیش موجود و فعال |
| Schema Migration | مهاجرت اسکیمای داده | ایجاد تغییرات ایمن و برگشت‌پذیر در جداول دیتابیس بدون از دست رفتن داده‌های قبلی |

---

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

1. **تصویر کاور درس:** `images/cover.png`
   * **موضوع:** نقشه مهندسی دیجیتال نئونی که پیوست شدن یک بال جدید و مدرن به یک ساختمان مستحکم موجود را بدون تخریب دیوارها نشان می‌دهد.
2. **آناتومی ۶ ستون سند مشخصات دلتا (Delta Spec):** `images/delta-spec-anatomy.png`
   * **موضوع:** اینفوگرافیک ۶ بخشی: داستان کاربر، محدوده، تغییر دیتابیس، طراحی UI، شروط تایید و قیود منفی.
3. **خطای پرامپت مبهم در برابر موفقیت سند مشخصات:** `images/vague-prompt-vs-feature-spec.png`
   * **موضوع:** کاریکاتور مقایسه‌ای: پرامپت یک‌خطی که صفحه اصلی را به هم می‌ریزد در برابر سند مشخصات که با جراحی تمیز فقط کامپوننت فیلتر را اضافه می‌کند.
4. **پیش‌نمایش قابلیت فیلتر تگ‌ها در صفحه پروژه‌ها:** `images/project-tags-filter-ui-preview.png`
   * **موضوع:** اسکرین‌شات از بالای گرید پورتفولیو با چیپ‌های بنفش رنگ Next.js, Supabase, Tailwind و نمایش پروژه‌های فیلترشده.

---

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

1. **تیتر اصلی:** `# تعریف ویژگی جدید و تدوین مشخصات دقیق (Feature Spec) برای ایجنت`
2. **مقدمه:** چگونه بدون اینکه کدهای قبلی پروژه به هم بریزد، یک فیچر جدید را مثل یک جراح ماهر به قلب محصول اضافه کنیم؟
3. **جدول کاور درس**
4. **استعاره بازسازی آپارتمان مسکونی در برابر ساخت زمین خالی:**
   * خانواده داخل خانه زندگی می‌کنند؛ نباید لوله اصلی آب را قطع کنید یا دیوارهای حامل را تخریب نمایید!
5. **ارکان ۶ گانه سند مشخصات ویژگی (Feature Spec) در وایب کدینگ:**
   * شرح گام‌به‌گام هر بخش با مثال ملموس پورتفولیو.
6. **مطالعه موردی: افزودن فیلتر تگ‌های مهارتی به پورتفولیو:**
   * نوشتن کامل فایل `.specs/feature-project-tags.md`.
7. **جادوی قیود منفی (Negative Constraints):**
   * چطور جلوی دستکاری ناخواسته فایل‌های حساس توسط ایجنت را با ۲ خط متن بگیریم.
8. **اجرای گام‌به‌گام با ارجاع به سند در ادیتور:**
   * استفاده از `@specs` در کامپوزر Cursor یا Claude Code.
9. **جعبه پرامپت طلایی: پیاده‌سازی امن فیچر با استناد به سند مشخصات:**
   * پرامپت دقیق:
     > «من سند مشخصات فیچر جدید را در `@specs/feature-project-tags.md` نوشته‌ام. لطفاً ابتدا این سند را به دقت بخوان و ۱) فقط تغییرات دیتابیس را پیشنهاد بده، ۲) پس از تایید من، کامپوننت فیلتر را بر اساس دیزاین سیستم بساز و ۳) تمام قیود منفی ذکر شده را به شدت رعایت کن.»
10. **باکس نکته Quera (`<details class="violet">`):** استفاده از اسکریپت‌های SQL اضافه کردن ستون به صورت `ADD COLUMN IF NOT EXISTS` برای جلوگیری از خطای اجرای مجدد.
11. **باکس هشدار Quera (`<details class="red">`):** هرگز از کلمات کلی مثل «یه فیلتر خوشگل برای پروژه‌ها درست کن» استفاده نکنید؛ هرچه توصیف مبهم‌تر باشد، احتمال باگ‌های پس‌رفتی بیشتر است.
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** مشاهده کارکرد بی‌نقص فیلتر تگ‌ها در سایت بدون اینکه حتی یک باگ کوچک در سایر بخش‌ها ایجاد شده باشد.
13. **جمع‌بندی درس‌نامه:** تسلط بر تدوین مشخصات افزونه‌ها؛ ورود به تکنیک‌های کاوش و درک کدهای موجود توسط ایجنت در درس بعدی.

---

## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- [ ] تمایز میان Greenfield Spec و Brownfield Delta Spec به روشنی بیان شود.
- [ ] ساختار ۶ بخشی سند مشخصات فیچر به همراه مثال کاربردی فیلتر تگ‌ها ارائه گردد.
- [ ] مفهوم و اهمیت حیاتی قیود منفی (Negative Constraints) تبیین شود.
- [ ] پرامپت ارجاع سند مشخصات به کامپوزر در متن درس گنجانده شود.