توسعه مبتنی بر مشخصات (SDD) چیست؟ چرا قبل از کد باید مشخصات بنویسی

وقتی ایجنت در چند دقیقه یک فیچر کامل میسازد، گرانترین اشتباه این است که اشتباه ساخته شود. در این درس میبینیم چطور با نوشتن و بازبینی مشخصات، پیش از اولین خط کد، فرمان کار را دست خودمان نگه داریم.
نقشهای که هیچوقت کشیده نشد
بسیاری از ما در خانوادهمان کسی را داشتهایم که یک روز تصمیم گرفت طبقه دوم خانه پدری را بسازد، آن هم بدون مهندس و فقط با یک اوستای بنای قدیمی و باتجربه. اوستا کارش را بلد بود. دیوار را صاف میچید، ملات را درست درست میکرد و از صبح تا غروب یکنفس کار میکرد. نقشهای هم در کار نبود، چون به قول صاحبخانه «اوستا خودش میدونه». هر روز عصر کسی از خانواده سر میزد و چیزی میگفت: «این اتاق رو یه کم بزرگتر بگیر»، «پنجره رو بیار اینور که آفتابگیر باشه»، «حموم رو ببر اون گوشه».
نتیجه را هم احتمالا دیدهاید. حمامی که لوله فاضلابش باید از وسط اتاق خواب رد میشد، پنجرهای که درست روبهروی پنجره همسایه درآمد و پلهای که آنقدر تند شد که مادربزرگ هیچوقت از آن بالا نرفت. اوستا کار بدی نکرده بود. هر چیزی را که هر روز گفته بودند، درست ساخته بود. فقط هیچکس قبل از اولین آجر ننشسته بود تا بنویسد این طبقه قرار است چه باشد.
ایجنت کدنویسی همان اوستای خستگیناپذیر است، فقط هزار برابر سریعتر. و این سرعت دو طرف دارد: اگر نقشه درست باشد، ساختمان در یک روز بالا میرود. اگر نقشه نباشد، حمام وسط اتاق خواب هم در یک روز بالا میرود.
توسعه مبتنی بر مشخصات یعنی چه؟
توسعه مبتنی بر مشخصات (Spec-Driven Development یا SDD) یعنی پیش از اینکه ایجنت کدی بنویسد، رفتار مورد نظر به شکل نیازمندیها، طراحی و فهرست کارها نوشته و بازبینی شود، و همین سندها مرجع پیادهسازی و تست شوند.
فرقش با چیزی که تا حالا دیدیم ساده است. در وایب کدینگ، گفتوگو مرجع کار است: هر چه در پیامها گفته شد، همان ساخته میشود و هر چه گفته نشد، ایجنت حدس میزند. در SDD، یک سند مرجع کار است. ایجنت از روی آن کد مینویسد، تستها از روی آن ساخته میشوند و اگر وسط کار سؤالی پیش آمد، جوابش اول در همان سند جستوجو میشود، نه در حافظه یک گفتوگوی شلوغ.
البته اگر کمی سابقه برنامهنویسی داشته باشید، احتمالا میگویید این که همان «اول تحلیل، بعد کد» قدیمی است. راست میگویید. فرق امروز این است که نوشتن پیشنویس این سندها دیگر یک هفته وقت نمیگیرد. ایجنت در چند دقیقه یک پیشنویس کامل میدهد و کار شما خواندن و اصلاحش است. یعنی مهمترین مرحله کار، همانی که قبلا به خاطر وقتگیر بودنش حذف میشد، حالا ارزان شده است. یادتان باشد در درس اول هم گفتیم امید برای فروشگاه زعفران باید پیش از هر چیز یک فایل مشخصات کوتاه مینوشت. این درس همان قدم را جدی میگیرد.
چرا ایجنت با مشخصات روشن کمتر خطا میکند؟
دلیل اول همان است که در درس دوم دیدیم: مدل جاهای خالی را با رایجترین حالت پر میکند. سند مشخصات جایی است که جاهای خالی پیش از ساخته شدن پیدا میشوند. اینکه «از یک شماره در هر ساعت چند کد پیامکی قبول کنیم» اگر در سند نباشد، در کد هم نخواهد بود، همان اتفاقی که دو میلیون تومان شارژ پنل امید را خالی کرد.
دلیل دوم حافظه است. در درس قبل گفتیم وقتی گیر کردید، یک گفتوگوی تازه باز کنید. اما گفتوگوی تازه همه تصمیمهای قبلی را فراموش کرده است. سند مشخصات در فایل میماند و هر گفتوگوی تازهای میتواند از اول بخواندش. برای همین با SDD، شروع دوباره دیگر یعنی شروع از صفر نیست.
دلیل سوم این است که «تمام شد» معنی پیدا میکند. وقتی در سند نوشتهاید کد تخفیف منقضی باید رد شود، ایجنت برایش تست مینویسد و تا وقتی تست سبز نشده، کار را تمامشده اعلام نمیکند. این همان الگوی معیار تمام شدن درس دوم است، فقط این بار یک بار نوشته میشود و برای همه تسکها کار میکند.
سه مرحله مشترک: نیازمندی، طراحی، تسکها
اسم ابزارهای SDD با هم فرق دارد، دستورهایشان هم، اما تقریبا همهشان کار را در سه مرحله جلو میبرند. این سه را با یک مثال میرویم.
بعد از ماجرای پنل پیامک، صاحب مغازه زعفرانفروشی هنوز با امید کار میکند (آدمها بیشتر از آنچه فکر میکنیم اهل بخشیدناند، به شرط اینکه دفعه دوم تکرار نشود). این بار برای فروش عید، کد تخفیف میخواهد. پشت تلفن هم فقط یک جمله گفته است:
صاحبمغازه
«یه کد تخفیف بذار برای عید، ده درصد. همین.»
امید این بار مستقیم سراغ پرامپت «یه کد تخفیف بساز» نمیرود.
۱. نیازمندیها: چه چیزی و چرا
مرحله اول فقط درباره رفتار است، نه کد. چه کسی، چه کاری میکند و از کجا بفهمیم درست کار میکند. هیچ اسمی از فریمورک و جدول دیتابیس اینجا نمیآید. امید از ایجنت میخواهد پیشنویس نیازمندیها را بنویسد و بعد، سؤالهایی را که خودش جوابشان را نمیداند، به صاحب مغازه زنگ میزند و میپرسد. نسخه نهایی چیزی شبیه این شد:
هدف: مشتری بتواند هنگام پرداخت یک کد تخفیف وارد کند و ده درصد از مبلغ کالاها کم شود.
-
تخفیف فقط روی مبلغ کالاهاست، نه هزینه ارسال.
-
هر شماره موبایل هر کد را فقط یک بار میتواند استفاده کند.
-
کد از ۲۵ اسفند تا ۱۳ فروردین معتبر است.
-
کد با حروف کوچک و بزرگ و با فاصله اضافه هم پذیرفته شود.
معیار پذیرش: کد منقضی رد شود؛ استفاده دوم با همان شماره رد شود؛ مبلغ نهایی هیچوقت منفی نشود؛ هزینه ارسال دست نخورد.
۲. طراحی: چطور
مرحله دوم جایی است که تصمیمهای فنی گرفته میشود: اطلاعات کجا ذخیره شود، کدام فایلها عوض شوند و بررسی کد کجا انجام شود. در مثال ما مهمترین تصمیم این بود که بررسی کد تخفیف در سرور انجام شود، نه در مرورگر، چون هر چیزی که در مرورگر باشد را کاربر میتواند دور بزند. این همان تصمیمی است که در وایب کدینگ معمولا هیچکس نمیگیرد، چون هیچکس اصلا نمیپرسد.
۳. تسکها: به چه ترتیبی
مرحله سوم طراحی را به قدمهای کوچکی میشکند که هر کدام جداگانه ساخته و امتحان میشوند. همان الگوی «یک قدم در هر پرامپت» درس دوم، فقط این بار فهرستش از قبل نوشته شده است.
-
۱. جدول کدهای تخفیف و جدول استفادهها (کد + شماره موبایل) ساخته شود.
-
۲. تابع بررسی کد در سرور، با تست برای کد منقضی، استفاده دوم و حروف کوچک و بزرگ.
-
۳. فیلد کد تخفیف در صفحه پرداخت و نمایش مبلغ کمشده.
-
۴. تست کامل مسیر خرید با کد، از سبد تا پرداخت.
| مرحله | به چه سؤالی جواب میدهد | چه کسی تصمیم میگیرد |
|---|---|---|
| نیازمندیها | چه چیزی و چرا؟ | شما و کارفرما، با پیشنویس ایجنت |
| طراحی | چطور؟ | شما، با پیشنهاد ایجنت |
| تسکها | به چه ترتیبی؟ | ایجنت مینویسد، شما تایید میکنید |
دو چیزی که SDD را واقعا به کار میآورد
اگر از این درس فقط دو چیز یادتان بماند، این دو باشد. بدون آنها SDD فقط چند فایل اضافه در پروژه است.
۱. مشخصات را خودتان بخوانید و ویرایش کنید
پیشنویس اول نیازمندیها را ایجنت در دو دقیقه نوشت و ظاهرش هم کاملا حرفهای بود، با تیتر و فهرست و معیار پذیرش. اما امید وقتی خطبهخط خواندش، دو چیز دید. در پیشنویس، تخفیف روی کل سبد خرید حساب شده بود، یعنی هزینه ارسال هم ده درصد ارزانتر میشد. و هیچ جای سند نگفته بود یک شماره چند بار میتواند کد را استفاده کند، پس عملا هر کس میتوانست صد بار با همان کد خرید کند. هیچکدام از این دو خطای ایجنت نبود. صاحب مغازه چیزی دربارهشان نگفته بود و ایجنت هم رایجترین حالت را نوشته بود.
حالا فرض کنید امید سند را نخوانده بود و فقط گفته بود «اجرا کن». ایجنت با دقت کامل همان دو تصمیم غلط را پیاده میکرد، برایشان تست هم مینوشت و تستها هم سبز میشدند. یعنی SDD دقیقا همان کدی را تحویل میداد که وایب کدینگ میداد، فقط با چند فایل مرتبتر کنارش.
مشخصاتی که شما نخوانده باشید، فقط حدسهای ایجنت است که مرتب نوشته شده.
هدف SDD نوشتن سند نیست. هدفش این است که دخالت و کنترل شما روی خروجی بیشتر شود، آن هم در ارزانترین لحظه ممکن، یعنی وقتی هنوز هیچ کدی نوشته نشده و عوض کردن یک تصمیم فقط یعنی پاک کردن یک خط متن.
۲. مشخصاتها یکجا میمانند و مستند پروژه میشوند
سه ماه بعد، صاحب مغازه زنگ میزند: «یه مشتری میگه با کد عید هزینه ارسالش هم کم شده، راسته؟». اگر امید وایب کد کرده بود، باید کد را باز میکرد و دنبال جواب میگشت، یا بدتر، از ایجنت میپرسید و جوابی میگرفت که از کجا معلوم درست باشد. اما حالا فایل مشخصات کد تخفیف را باز میکند و در سی ثانیه جواب میدهد: نه، تخفیف فقط روی مبلغ کالاهاست و تستش هم همین را میسنجد.
ابزارهای SDD همه مشخصات را در یک پوشه مشخص در خود پروژه نگه میدارند. با گذشت زمان این پوشه به مستند زنده پروژه تبدیل میشود: چه چیزهایی پیاده شده، با چه قاعدههایی، و چه چیزهایی هنوز فقط پیشنهادند و ساخته نشدهاند. فریلنسر تازهای که شش ماه بعد به پروژه اضافه میشود، یا خود امید که دیگر یادش نیست آن موقع چه تصمیمی گرفت، به جای حدس زدن از روی کد، همین پوشه را میخواند. و ایجنت هم در گفتوگوهای بعدی.
Spec Kit و OpenSpec: دو ابزار برای شروع
لازم نیست برای SDD ابزار خاصی نصب کنید. میشود سه فایل را با دست ساخت و از ایجنت خواست از رویشان کار کند. اما ابزارهای آماده قالب و دستورهای حاضر دارند و جلوی جا افتادن مرحلهها را میگیرند. دو تا از شناختهشدهترینهایشان اینها هستند و هر دو متنباز و رایگاناند و با Claude Code کار میکنند.
Spec Kit را GitHub ساخته است1. کار با آن از یک «قانون اساسی» (Constitution) برای کل پروژه شروع میشود، یعنی اصولی که همه فیچرها باید رعایت کنند، و بعد هر فیچر به ترتیب با دستورهای /speckit.specify برای نیازمندیها، /speckit.plan برای طراحی، /speckit.tasks برای فهرست کارها و /speckit.implement برای ساختن جلو میرود. خروجی هر فیچر در یک پوشه جدا ذخیره میشود. ساختار کاملی دارد و برای شروع یک پروژه یا فیچرهای بزرگ مناسب است، اما همین کامل بودنش برای کارهای کوچک سنگین میشود.
OpenSpec را شرکت Fission AI ساخته و سبکتر است2. چرخهاش سه قدم دارد: پیشنهاد یک تغییر (Proposal)، اجرای آن (Apply) و بایگانی (Archive). نکته جالبش این است که مشخصات فعلی پروژه را از تغییرهای پیشنهادی جدا نگه میدارد. هر تغییر اول در پوشه تغییرها مینشیند و فقط وقتی ساخته و بایگانی شد، با مشخصات اصلی ادغام میشود. یعنی دقیقا همان مستند زندهای که بالاتر گفتیم: هر چیزی در پوشه مشخصات اصلی هست، ساخته شده، و هر چیزی هنوز در پوشه تغییرهاست، نه. برای پروژهای که از قبل وجود دارد، مثل همان فروشگاه زعفران، معمولا انتخاب راحتتری است.
| Spec Kit | OpenSpec | |
|---|---|---|
| سازنده | GitHub | Fission AI |
| مراحل | قانون اساسی، نیازمندی، طراحی، تسکها، اجرا | پیشنهاد، اجرا، بایگانی |
| وزن | سنگینتر و کاملتر | سبکتر |
| مناسب برای | پروژه تازه یا فیچر بزرگ | پروژه موجود و تغییرهای پشت سر هم |
اسم دقیق دستورها در نسخههای مختلف این ابزارها چند بار عوض شده و در هر ایجنت هم کمی فرق میکند. پیش از شروع، راهنمای همان نسخهای را که نصب کردهاید بخوانید.
SDD سربار دارد و همیشه لازم نیست
حالا بخش صادقانه درس. SDD وقت میگیرد. خواندن و اصلاح سه سند، حتی وقتی پیشنویس را ایجنت نوشته، برای یک فیچر متوسط نیم ساعت تا یک ساعت کار است. اگر برای هر تغییر کوچکی این مسیر را بروید، دو هفته بعد از خودتان میپرسید چرا عوض کردن رنگ یک دکمه سه فایل مشخصات دارد.
خطر دیگرش این است که ایجنت عاشق نوشتن است. اگر محدودش نکنید، برای یک فیچر کوچک سندی چندصفحهای با دهها معیار پذیرش مینویسد که خواندنش از ساختن خود فیچر بیشتر طول میکشد. بیرگیتا بوکلر در یادداشتی که درباره ابزارهای SDD در سایت مارتین فاولر نوشت، دقیقا به همین اشاره کرد: برای یک باگ کوچک، ابزار حجمی از سند ساخت که با اندازه مسئله هیچ تناسبی نداشت3. و سند بلندی که کسی حوصله خواندنش را ندارد، ما را برمیگرداند به نکته اول بخش قبل.
کی SDD، کی نه
قاعدهای که در درس دوم از راهنمای Claude Code آوردیم اینجا هم کار میکند: اگر میتوانید تغییر را در یک جمله توضیح بدهید، مشخصات لازم نیست. عوض کردن متن یک دکمه، درست کردن یک باگ ساده یا یک اسکریپت یکبارمصرف، با یک پرامپت خوب کافی است. اما هر چیزی که با پول، اطلاعات کاربران یا چند فایل و چند روز کار سروکار دارد، ارزش مشخصات را دارد.
برای همین ما SDD را جایگزین وایب کدینگ نمیدانیم. اینها ابزارهای کنار هماند. یک برنامهنویس باتجربه در یک روز کاری برای یک تغییر کوچک پرامپت مینویسد، برای امتحان یک ایده وایب کد میکند و برای کد تخفیف عید، که پول مشتری و صاحب مغازه در میان است، اول مشخصات مینویسد.
منابع
سؤالات متداول
توسعه مبتنی بر مشخصات (Spec-Driven Development یا SDD) یعنی پیش از اینکه ایجنت کدی بنویسد، رفتار مورد نظر به شکل نیازمندیها، طراحی و فهرست کارها نوشته و بازبینی شود، و همین سندها مرجع پیادهسازی و تست شوند.
Spec Kit را GitHub ساخته و مسیر کاملتری دارد، از قانون اساسی پروژه تا نیازمندی، طراحی، تسکها و اجرا، و برای پروژههای تازه و فیچرهای بزرگ مناسبتر است. OpenSpec سبکتر است، با چرخه پیشنهاد، اجرا و بایگانی، و مشخصات فعلی را از تغییرهای پیشنهادی جدا نگه میدارد، برای همین معمولا برای پروژههای موجود راحتتر است. هر دو متنباز و رایگاناند و با Claude Code کار میکنند.
نه. SDD سربار دارد و برای تغییرهای کوچک وقت هدر میدهد. اگر تغییر را میشود در یک جمله توضیح داد، یک پرامپت خوب کافی است. مشخصات را برای چیزهایی بگذارید که با پول، اطلاعات کاربران یا چند فایل و چند روز کار سروکار دارند.
بله، و این مهمترین قسمت کار است. مشخصاتی که نخوانید، فقط حدسهای ایجنت است که مرتب نوشته شده و ایجنت با دقت کامل همان حدسها را پیاده میکند. در مثال این درس، خواندن پیشنویس جلوی دو تصمیم غلط را گرفت: تخفیف روی هزینه ارسال و استفاده نامحدود از یک کد.
تمرین درس
آخرین فیچری را که با کمک AI ساختهاید به یاد بیاورید، فیچری که بیش از یک بار رفتوبرگشت داشت. اگر قرار بود پیش از شروع، فقط بخش نیازمندیهایش را بنویسید، چه چیزی در آن میآمد که در پرامپت اولتان نیامده بود؟ برای فیچر بعدیتان از ایجنت بخواهید فقط پیشنویس نیازمندیها را بنویسد، بدون هیچ کدی. بعد آن را خطبهخط بخوانید و هر جایی را که با چیزی که در ذهن داشتید فرق دارد علامت بزنید. تعداد علامتها را بشمارید. همین عدد، تعداد تصمیمهایی است که بدون این مرحله ایجنت به جای شما میگرفت. در درس بعد سراغ نوشتن خود نیازمندیها میرویم: چطور یک خواسته یکخطی مثل «یه کد تخفیف بذار برای عید» را به سؤالهای درست برای کارفرما و معیارهای پذیرشی تبدیل کنیم که بشود از رویشان تست نوشت.
درسهای مهندسی نرم افزار و وایب کدینگ
۰ از ۷ دیده شده- ۱مهندسی نرم افزار با هوش مصنوعی چیست؟ تعریف، کاربردها و تفاوتش با برنامهنویسی سنتی
- ۲پرامپت نویسی برای برنامهنویسی: چطور از هوش مصنوعی، کد درست بگیریم؟
- ۳بهترین ابزارها و مدلهای هوش مصنوعی برای برنامهنویسی
- ۴وایب کدینگ یعنی چیست؟ از توییت کارپاتی تا کاربردها و محدودیتها
- ۵آموزش وایب کدینگ: ساخت اولین اپ با هوش مصنوعی قدمبهقدم
- ۶وقتی وایب کدینگ گیر میکند: دیباگ، ریست و برگشت به نسخه سالم
- ۷توسعه مبتنی بر مشخصات (SDD) چیست؟ چرا قبل از کد باید مشخصات بنویسی