vibe-coding-college-specs/chapters/15-product-evolution/02-lesson-specifying-new-features-for-agents/spec.md

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