توسعه مبتنی بر مشخصات چیست؟ آموزش SDD با GitHub Spec Kit
راهنمای عملی توسعه مبتنی بر مشخصات یا SDD؛ از تبدیل ایده مبهم به Specification، Plan و Tasks تا پیاده‌سازی کنترل‌شده با GitHub Spec Kit و عامل‌های هوش مصنوعی.
توسعه مبتنی بر مشخصات یا Spec-Driven Development رویکردی است که در آن پیش از تولید کد، رفتار مورد انتظار نرم‌افزار به‌صورت دقیق، قابل بازبینی و قابل آزمون نوشته می‌شود. در SDD، Specification یک توضیح تزئینی کنار پروژه نیست؛ منبع مشترک حقیقت است و Plan، Task، تست و پیاده‌سازی باید به آن برگردند.
این ایده با رشد عامل‌های کدنویسی اهمیت تازه‌ای پیدا کرده است. وقتی AI می‌تواند در چند دقیقه صدها خط کد بسازد، گلوگاه از «سرعت تایپ» به «دقت نیت و تصمیم» منتقل می‌شود. اگر خواسته مبهم باشد، خروجی سریع فقط ابهام را با حجم بیشتری تکثیر می‌کند. GitHub Spec Kit یک ابزار متن‌باز برای اجرای گردش کار ساختاریافته Specify → Plan → Tasks → Implement است و می‌تواند با عامل‌های مختلف کار کند.
چرا SDD اکنون موضوعی نوظهور است؟
در بررسی Google Trends ایران در ۹ سپتامبر ۲۰۲۶، میانگین جست‌وجوی مستقیم spec driven development در بازه‌های ۹۰روزه و ۱۲ماهه نزدیک صفر بود؛ بنابراین درست نیست آن را یک ترند عمومی یا وایرال بنامیم. با این حال، عبارت مرتبط spec driven development ai در هر دو بازه وضعیت Breakout داشت و خود عبارت در هفته‌های پایانی اوت از صفر به مقادیر ۴ و ۵ رسید.
پیشنهادهای واقعی Google Search نیز نیت‌های کاربردی مانند with GitHub Copilot، with Claude Code، vs test driven development، vs vibe coding، Frameworks و Examples را نشان دادند. نتیجه دقیق این است: SDD یک موضوع نوظهور با حجم مطلق پایین و رشد شدید نیت مرتبط با AI است؛ انتخاب آن برای آموزش زودهنگام منطقی است، اما نباید درباره محبوبیت آن اغراق کرد.
توسعه مبتنی بر مشخصات دقیقاً چه چیزی را تغییر می‌دهد؟
در پروژه سنتی، Requirement نوشته می‌شود، توسعه‌دهنده آن را تفسیر می‌کند و پس از مدتی فاصله‌ای میان سند و کد شکل می‌گیرد. در SDD، مشخصات باید آن‌قدر روشن باشد که انسان، عامل AI و آزمون خودکار برداشت نزدیک به هم داشته باشند. اگر نتیجه پیاده‌سازی اشتباه است، فقط Patch کردن کد کافی نیست؛ باید ببینید ابهام از Specification یا Plan وارد شده است.
Specification با PRD یا Prompt چه تفاوتی دارد؟
- Prompt یک ورودی مکالمه‌ای است و ممکن است پس از پایان Session گم شود.
- PRD هدف کسب‌وکار و دامنه محصول را توضیح می‌دهد، اما همیشه جزئیات قابل آزمون ندارد.
- Specification رفتار، ورودی، خروجی، محدودیت، سناریوی خطا و معیار پذیرش را به شکلی قابل بررسی ثبت می‌کند.
- Plan مشخصات را به معماری، فناوری، قرارداد و مسیر Migration ترجمه می‌کند.
- Tasks Plan را به واحدهای کوچک، مرتب و قابل تحویل تقسیم می‌کند.
یک Specification خوب الزاماً طولانی نیست. باید پرسش‌های پرریسک را زود آشکار کند: مالک داده کیست؟ کاربر بدون مجوز چه می‌بیند؟ عملیات تکراری چه رفتاری دارد؟ شکست سرویس جانبی چگونه جبران می‌شود؟
گردش کار GitHub Spec Kit چگونه است؟
مستندات رسمی Spec Kit چهار مرحله مرکزی معرفی می‌کند: Spec → Plan → Tasks → Implement. هر مرحله یک Artifact ماندگار Markdown تولید می‌کند که ورودی مرحله بعد است. این زنجیره Context عامل را از Promptهای پراکنده به اسناد نسخه‌پذیر تبدیل می‌کند.
| مرحله | پرسش اصلی | خروجی | دروازه بازبینی |
|---|---|---|---|
| Specify | چه رفتاری باید ساخته شود؟ | داستان کاربر، سناریو و معیار پذیرش | ابهام، تناقض و Scope |
| Plan | چگونه و با چه محدودیتی ساخته شود؟ | معماری، مدل داده، قرارداد و تحقیق | ریسک، امنیت و سازگاری |
| Tasks | ترتیب تغییرات چیست؟ | کارهای کوچک با وابستگی روشن | قابلیت تحویل و تست‌پذیری |
| Implement | آیا کد با Spec منطبق است؟ | کد، تست و مستندات | Diff، CI و معیار پذیرش |
Constitution چه نقشی دارد؟
Spec Kit برای پروژه یک Constitution یا مجموعه اصول پایدار در نظر می‌گیرد. قواعدی مانند «همه Endpointها Authorization دارند»، «Migration باید قابل بازگشت باشد»، «تست Integration برای مرز دیتابیس الزامی است» یا «Secret در Repository ممنوع است» باید پیش از Featureها ثبت شوند. این قواعد به Plan و Implementation جهت می‌دهند و جلوی مذاکره دوباره درباره اصول ثابت را می‌گیرند.
نصب و شروع GitHub Spec Kit
طبق راهنمای رسمی، CLI با uv نصب می‌شود. پیش از نصب، مخزن رسمی و نسخه بسته را بررسی کنید. ابزار برای Windows، macOS و Linux مستند شده است و هنگام مقداردهی اولیه، Integration عامل کدنویسی انتخاب می‌شود.
uv tool install specify-clispecify checkspecify init sample-shop --integration genericcd sample-shopgit status --shortنام Integration را با عامل واقعی خود جایگزین کنید. گزینه generic برای ابزاری مفید است که Integration اختصاصی ندارد. پس از Init، فایل‌ها و فرمان‌های ساخته‌شده را پیش از اجرا Commit یا دست‌کم Diff کنید تا تغییرات ابزار با تغییرات Feature مخلوط نشوند.
مثال: Specification برای بازیابی رمز عبور
درخواست «صفحه فراموشی رمز عبور بساز» مبهم است. معلوم نیست حساب ناشناخته چه پاسخی می‌گیرد، Token چقدر معتبر است، استفاده دوباره چه می‌شود یا Rate Limit چگونه اعمال می‌شود. Spec زیر این تصمیم‌ها را قابل بازبینی می‌کند؛ مقادیر نمونه‌اند و باید با سیاست امنیتی پروژه تطبیق داده شوند.
# Feature: Password reset ## User storyAs a registered user, I can request a one-time reset link. ## Acceptance criteria- Known and unknown emails receive the same public response.- The token expires after 15 minutes and works only once.- Five requests per account per hour are allowed.- Existing sessions are revoked after a successful reset.- Security events are audited without storing the token. ## Out of scope- Changing the primary email address- Support-assisted account recoveryمزیت Spec این است که تیم امنیت، محصول و توسعه می‌توانند پیش از تولید کد درباره رفتار تصمیم بگیرند. Agent اکنون می‌تواند Plan، مدل داده و تست را بر اساس قرارداد روشن پیشنهاد دهد؛ نه اینکه خودش سیاست حساب کاربری را حدس بزند.
فرمان‌های اصلی Specify تا Implement
- Specify: مسئله و رفتار مطلوب را بدون قفل‌کردن زودهنگام فناوری بنویسید.
- Clarify: ابهام‌های پراثر را پیدا کنید؛ پاسخ را به سند برگردانید، نه فقط به Chat.
- Plan: معماری، قرارداد API، مدل داده، امنیت، Observability و Migration را تعریف کنید.
- Tasks: کارها را با وابستگی، فایل احتمالی، تست و Definition of Done خرد کنید.
- Implement: هر Task را جدا اجرا کنید و بعد از هر واحد، Diff و تست را بازبینی کنید.
- Validate: انطباق کد، تست و مستندات با معیار پذیرش را بررسی کنید.
نام دقیق فرمان‌ها و قابلیت‌ها ممکن است با نسخه ابزار تغییر کند؛ CLI Reference همان نسخه را معیار قرار دهید. هدف روش، حفظ Traceability از Requirement تا Code است، نه حفظ‌کردن چند Slash Command.
SDD چه تفاوتی با TDD و وایب کدینگ دارد؟
TDD چرخه Red، Green و Refactor را برای طراحی و صحت کد به کار می‌گیرد. SDD از سطح رفتار و Intent شروع می‌کند و سپس Plan و Tasks را می‌سازد. این دو رقیب نیستند: معیار پذیرش Spec می‌تواند ورودی تست‌های TDD باشد و تست‌ها شواهد انطباق Implementation را فراهم کنند.
وایب کدینگ روی گفت‌وگوی سریع و اصلاح نتیجه تمرکز دارد. SDD پیش از سرعت، ساختار و حافظه ماندگار می‌سازد. برای نمونه‌سازی کم‌ریسک، وایب کدینگ کافی است؛ برای Feature چندنفره یا محصولی که باید نگه‌داری شود، Spec کمک می‌کند Context از Session یک مدل مستقل بماند. برای شناخت مرزهای این روش، مقاله وایب کدینگ چیست؟ از نمونه سریع تا کد امن را بخوانید.
خطاهای رایج در Spec-Driven Development
Spec بسیار کلی
عبارت‌هایی مانند «سریع باشد» یا «امن باشد» قابل آزمون نیستند. آن‌ها را به شاخص و سناریو تبدیل کنید: زمان پاسخ در صدک مشخص، نقش‌های مجاز، رفتار Timeout، Audit و محدودیت درخواست.
قفل‌کردن زودهنگام راه‌حل
Specification باید ابتدا What و Why را روشن کند. اگر از خط اول Framework و جدول دیتابیس را الزام کنید، فضای Plan و تحقیق را می‌بندید. فناوری فقط وقتی وارد Spec شود که واقعاً Constraint کسب‌وکار یا سازگاری است.
تولید همه Artifactها بدون توقف انسانی
سرعت ساخت سند تضمین کیفیت نیست. بین Specify و Plan و پیش از Implement دروازه بازبینی بگذارید. مسئله‌ای که در Spec با یک جمله اصلاح می‌شود، پس از تولید Migration و API هزینه بیشتری دارد.
فراموش‌کردن Spec پس از Merge
اگر رفتار واقعی تغییر کرد، Spec نیز باید به‌روز شود. Incident، Metric و بازخورد کاربر ورودی تکامل Specification هستند. سندی که با Production ناسازگار است دوباره همان شکاف مستندات سنتی را ایجاد می‌کند.
چک‌لیست یک Spec قابل اجرا
- مسئله و کاربر هدف بدون اشاره مبهم تعریف شده‌اند.
- سناریوی اصلی، جایگزین و شکست نوشته شده‌اند.
- معیارهای پذیرش قابل اندازه‌گیری و قابل تست‌اند.
- Scope و موارد خارج از Scope مشخص‌اند.
- داده حساس، مجوز و سیاست نگه‌داری روشن است.
- وابستگی خارجی و رفتار قطعی آن مستند شده است.
- Performance، Accessibility و Observability در صورت نیاز معیار دارند.
- Migration و Rollback در Plan بررسی شده‌اند.
- هر Task به یک بخش Spec و یک روش اعتبارسنجی وصل است.
- تصمیم‌های مهم به‌صورت نسخه‌پذیر در Repository مانده‌اند.
چه زمانی SDD ارزش بیشتری دارد؟
Featureهای چندتیمی، سامانه‌های قانون‌محور، API عمومی، Migration داده، پروژه Brownfield و کار با عامل‌های خودکار بیشترین سود را می‌برند. برای Script یک‌بارمصرف شاید هزینه نوشتن Spec کامل توجیه نداشته باشد؛ یک معیار پذیرش کوتاه کافی است. اندازه Artifact باید با ریسک و طول عمر تغییر متناسب باشد.
اگر برای اجرای Taskها از عامل متن‌باز استفاده می‌کنید، راهنمای نصب OpenCode و تنظیم مجوزهای امن نشان می‌دهد چگونه دسترسی خواندن، ویرایش و فرمان را محدود کنید. SDD مشخص می‌کند عامل چه بسازد؛ Permission تعیین می‌کند عامل چه کاری اجازه دارد انجام دهد.
جمع‌بندی
توسعه مبتنی بر مشخصات پاسخ به یک واقعیت تازه است: تولید کد ارزان‌تر شده، اما تصمیم درست همچنان کمیاب است. Specification دقیق، Plan قابل دفاع و Tasks ردیابی‌پذیر، AI را از یک مولد پاسخ به عضو کنترل‌شده فرایند توسعه تبدیل می‌کنند. GitHub Spec Kit این گردش کار را آماده می‌کند، ولی جای قضاوت محصول، امنیت و Code Review را نمی‌گیرد.
برای یادگیری طراحی نیازمندی و ساخت پروژه‌های واقعی با عامل‌های هوش مصنوعی، مسیرهای آموزشی خانه برنامه‌نویسان البرز را بررسی کنید.