102 lines
12 KiB
Markdown
102 lines
12 KiB
Markdown
# مشخصات درس‌نامه: تعریف ویژگی جدید و تدوین مشخصات دقیق (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) تبیین شود.
|
||
- [ ] پرامپت ارجاع سند مشخصات به کامپوزر در متن درس گنجانده شود.
|