آموزش عملی GitHub Spec Kit و Open Spec برای SDD

آموزش Spec Kit و OpenSpec | یک فیچر، دو ابزار SDD
در درس قبل دیدیم SDD چیست. این بار یک فیچر واقعی را یک بار با Spec Kit و یک بار با OpenSpec از ایده تا کد جلو میبریم تا ببینید هر کدام کجا به کار میآید و کجا باید بایستید و بخوانید.
دو ابزار شناختهشده توسعه مبتنی بر مشخصات، یعنی Spec Kit از GitHub و OpenSpec، روی کاغذ شبیه هماند. هر دو متنباز و رایگاناند، هر دو با Claude Code و دهها ایجنت دیگر کار میکنند و هر دو قبل از کد، سند میسازند. فرقشان وقتی معلوم میشود که یک فیچر مشخص را با هر دو بسازید. ما در این درس دقیقا همین کار را میکنیم: یک فیچر کوچک ولی پردردسر را در فروشگاه زعفران امید، یک بار با هر ابزار، از نصب تا تحویل میبریم. نکته غافلگیرکنندهاش این است که ابزار سنگینتر همیشه بهتر نیست. برای بیشتر پروژههایی که از قبل وجود دارند، ابزار سادهتر انتخاب بهتری است، به شرط اینکه خواندن سندها را خودتان جدی بگیرید.
زعفران سرگل تموم شد
اواسط آبان است و صاحب مغازه زعفرانفروشی دوباره به امید زنگ میزند. این بار صدایش کلافه است.
صاحبمغازه
«امید جان، سرگل یه مثقالی تموم شده. روزی ده تا دایرکت میاد که کی میاد، کی میاد. منم که نمیدونم کی میاد، بستگی به بار داره.»
امید
«خب یه دکمه بذاریم زیر محصول، "موجود شد خبرم کن". شمارهشونو میگیریم، وقتی اومد پیامک میدیم.»
صاحبمغازه
«آره، همین. فقط این دفعه پیامکاش مثل اون دفعه پولمونو نخورهها.»

جمله آخر شوخی نبود. همانطور که در درسهای قبل دیدیم، یک بار پنل پیامک این فروشگاه به خاطر کدی که هیچکس دقیق نخوانده بود خالی شده بود. فیچر «خبرم کن» هم ظاهرش ساده است، اما دقیقا همان جاهای خالیای را دارد که ایجنت با حدس پر میکند: چه کسی میتواند شماره ثبت کند، پیامک کی فرستاده شود، به چند نفر و چند بار.
امید از درس قبل یاد گرفته که برای چیزی که با پول سروکار دارد، اول مشخصات بنویسد. اما هنوز نمیداند کدام ابزار. پس تصمیم میگیرد کاری بکند که ما هم پیشنهادش میکنیم: همین فیچر را روی دو شاخه جدای گیت، یک بار با Spec Kit و یک بار با OpenSpec، بسازد و کنار هم مقایسه کند. یک فیچر کوچک، دو بار، بهترین راه برای فهمیدن ابزار است. فیچر بزرگ را برای وقتی نگه دارید که ابزارتان را انتخاب کردهاید.
قبل از شروع: سه چیزی که لازم دارید
اول یک ایجنت کدنویسی. ما در این درس از Claude Code استفاده میکنیم، به همان دلیلهایی که در درس سوم گفتیم، اما هر دو ابزار با ایجنتهای دیگر هم کار میکنند. طبق مستندات Spec Kit در آبان ۱۴۰۵، این ابزار بیش از چهل ایجنت را پشتیبانی میکند، از Codex و Gemini تا Qoder و OpenCode[^1]، و OpenSpec هم بیش از سی ایجنت را[^2]. پس اگر ابزار دیگری دارید، فقط اسم دستورها کمی فرق میکند. مثلا در Codex به جای / اول دستورها $ میگذارید.
دوم، پیشنیازهای نصب. Spec Kit یک ابزار خط فرمان پایتونی است و پایتون ۳.۱۱ به بالا و ابزار uv را میخواهد. OpenSpec با Node.js نسخه ۲۲.۲۰ به بالا نصب میشود. اگر نصب با خطای شبکه نیمهکاره ماند (که با اینترنت ما بعید نیست)، قبل از اینکه سراغ عوض کردن نسخهها بروید، اول اتصال و تنظیمات پروکسی ترمینالتان را چک کنید. بیشتر وقتها مشکل از همانجاست، نه از ابزار.
سوم، یک commit تمیز. هر دو ابزار در پوشه پروژه فایل میسازند و Spec Kit موقع نصب روی پروژه موجود ممکن است فایلهایی را بازنویسی کند. همان قانون نسخه سالم درس ششم اینجا هم برقرار است: قبل از نصب، همه چیز را commit کنید تا اگر چیزی خراب شد، یک دستور تا برگشتن فاصله داشته باشید.
مسیر اول: Spec Kit قدمبهقدم
Spec Kit مسیر کاملی دارد و برای هر مرحله یک دستور جدا. مستندات خودش دو مسیر پیشنهاد میکند: مسیر کوتاه که specify، plan، tasks، implement و converge است، و مسیر کامل که constitution، clarify، checklist و analyze را هم دارد[^1]. امید مسیر کامل را میرود، چون میخواهد ببیند هر مرحله چه چیزی اضافه میکند.
۱. نصب روی پروژه موجود
فروشگاه از قبل وجود دارد، پس به جای ساختن پروژه تازه، Spec Kit را در همان پوشه نصب میکند:
--here یعنی همین پوشه و --force اجازه میدهد در پوشهای که خالی نیست نصب شود. همین --force دلیل آن commit تمیز است. نصب یک پوشه .specify و چند مهارت (Skill) برای Claude Code میسازد. به کد خود فروشگاه دست نمیزند، ولی اگر فایلی هماسم با فایلهای خودش پیدا کند، ممکن است رویش بنویسد. حالا Claude Code را در پوشه پروژه باز میکند و بقیه دستورها را داخل چت آن میزند، نه در ترمینال.
۲. قانون اساسی، فقط آنچه واقعا درست است

/speckit-constitution اصولی را مینویسد که همه فیچرهای بعدی با آن سنجیده میشوند. وسوسه اینجا این است که یک فهرست بلند از اصول قشنگ بنویسید. مستندات خود Spec Kit صریحا از این کار منع میکند و میگوید برای پروژه موجود فقط اصولی را بنویسید که همین الان واقعا رعایت میشوند[^1]. قانون اساسیای که با کد نمیخواند، فقط سر و صدا اضافه میکند.
/speckit-constitution این پروژه یک فروشگاه اینترنتی زعفران با Next.js و TypeScript و PostgreSQL است و فقط یک برنامهنویس دارد. فقط این اصول را بنویس:
۱. هر منطقی که با پول یا پیامک سروکار دارد فقط در سرور اجرا شود.
۲. هر ارسال پیامک باید سقف تعداد در ساعت داشته باشد.
۳. برای هر منطق مالی تست خودکار نوشته شود.
۴. وابستگی جدید بدون دلیل نوشتهشده اضافه نشود.
چیزی از خودت اضافه نکن.
اصل دوم یادگار همان ماجرای پنل پیامک است. یعنی قانون اساسی خوب معمولا از زخمهای قبلی پروژه میآید، نه از کتاب.
۳. نیازمندیها و سؤالهایی که نپرسیده بودید
حالا خود فیچر. در /speckit-specify فقط از «چه چیزی و چرا» حرف میزنید، بدون اسم جدول و فریمورک:
/speckit-specify یک دکمه «موجود شد خبرم کن» زیر محصولات ناموجود. مشتری شماره موبایلش را ثبت میکند و وقتی محصول دوباره موجود شد، یک پیامک با لینک محصول میگیرد. هدف این است که صاحب مغازه مجبور نباشد به دایرکتهای «کی میاد» جواب بدهد.
خروجی یک فایل spec.md است، همراه با یک چکلیست کیفیت نیازمندیها. بعد /speckit-clarify میآید و این همان قدمی است که Spec Kit را از یک قالب ساده جدا میکند. ایجنت سند را میخواند، جاهای مبهمش را پیدا میکند و از شما سؤال میپرسد، معمولا چند سؤال کوتاه با گزینههای پیشنهادی. در اجرای امید یکی از سؤالها این بود که «آیا کاربر مهمان، بدون ورود به حساب، هم میتواند شماره ثبت کند؟». امید اول بیفکر میخواست بگوید بله، بعد یاد ماجرای قبلی افتاد. اگر هر کسی بتواند هر شمارهای را ثبت کند، یک ربات میتواند پنج هزار شماره بیربط ثبت کند و روزی که زعفران برسد، فروشگاه پول پنج هزار پیامک را میدهد. جوابش شد: فقط کاربر واردشده، با همان شمارهای که با آن وارد شده است.
البته سؤالهای ایجنت هر بار فرق میکند و تضمینی نیست که دقیقا همین را بپرسد. حتی ممکن است مهمترین سؤال را اصلا نپرسد. clarify جای خواندن شما را نمیگیرد، فقط کمکتان میکند.
۴. طراحی، تسکها و ایست بازبینی
/speckit-plan جایی است که بالاخره فریمورک و دیتابیس وارد بحث میشوند. امید در پرامپتش فقط مینویسد که از همان Next.js و PostgreSQL فعلی و همان پنل پیامکی که داریم استفاده شود. خروجی plan.md است و اینجا اولین ایست بازبینی جدی امید است. در طرح، ایجنت نوشته بود که «پس از افزایش موجودی، پیامک بلافاصله برای همه مشترکین ارسال میشود.» جملهای بیآزار، تا وقتی که یادتان بیاید انبار این فروشگاه فایل موجودی را هر شب حدود ساعت دو بامداد بهروز میکند. یعنی صد و چند مشتری ساعت دو صبح پیامک زعفران میگرفتند.
دومین ایراد کمتر دیده میشد. فرض کنید سیصد نفر منتظرند و فقط چهل بسته رسیده است. پیامک به هر سیصد نفر میرود، دویست و شصت نفر به صفحهای میرسند که دوباره نوشته «ناموجود» و این بار عصبانیتر از قبل دایرکت میدهند. امید هر دو را در plan.md اصلاح کرد: ارسال فقط بین ۹ صبح تا ۹ شب، و ارسال به ترتیب ثبتنام و حداکثر به اندازه دو برابر موجودی.

مهمترین تصمیمهای این فیچر در هیچ دستوری نبود. در دو جمله بود که امید خواند و عوض کرد.
بعد /speckit-checklist و /speckit-tasks میآیند. اولی یک چکلیست برای کیفیت خود نیازمندیها میسازد، نه برای کد، و دومی فایل tasks.md را با ترتیب وابستگیها. قبل از ساختن، /speckit-analyze هر سه سند را کنار هم میخواند و ناسازگاریها را گزارش میدهد، بدون اینکه چیزی را عوض کند. مثلا اگر در spec.md هنوز نوشته باشد «ارسال فوری» ولی در plan.md بازه ۹ تا ۹ آمده باشد، همینجا پیدا میشود. ایراد را در سند اصلی درست میکنید و دوباره analyze را اجرا میکنید.
۵. ساختن و همگرا شدن
/speckit-implement تسکها را به ترتیب میسازد. اگر آیتمی در چکلیست تیک نخورده باشد، قبل از شروع میپرسد که ادامه بدهد یا نه. برای فیچرهای بزرگ مستندات پیشنهاد میکند هر بار فقط یک فاز را بسازید. آخر کار /speckit-converge کد را با سه سند مقایسه میکند و اگر چیزی جا مانده باشد، تسک تازه به tasks.md اضافه میکند. implement و converge را آنقدر تکرار میکنید تا گزارش بدهد کد با سندها همگرا شده است (Converged)[^1].
اگر درس قبل را خواندهاید
در نسخههای قدیمیتر Spec Kit دستورها با نقطه نوشته میشدند، مثل /speckit.specify، و مستندات هنوز گاهی همین شکل را به کار میبرد. در Claude Code و بیشتر ایجنتهای امروزی همان دستورها با خط تیرهاند: /speckit-specify. مرحله converge هم بعدا اضافه شده است.
مسیر دوم: OpenSpec، سبکتر و سریعتر
حالا امید به شاخه دوم برمیگردد، همان کد فروشگاه بدون هیچکدام از تغییرهای Spec Kit، و همین فیچر را با OpenSpec شروع میکند.
openspec init میپرسد از کدام ایجنتها استفاده میکنید و برایشان مهارت نصب میکند. چرخه پیشفرضش در نسخه ۲ فقط چهار دستور دارد1: /openspec-explore برای فکر کردن و بررسی کد قبل از هر تصمیم، که اختیاری است، /openspec-propose برای ساختن پیشنهاد تغییر، /openspec-apply-change برای ساختن و /openspec-archive-change برای بایگانی. دستوری برای قانون اساسی، سؤال پرسیدن یا چک ناسازگاری در این چرخه پیشفرض نیست. یک پروفایل گسترده هم دارد که دستورهایی مثل openspec-verify-change را اضافه میکند، اما امید عمدا با همان پیشفرض جلو میرود.
امید این بار فقط یک دستور میزند:
/openspec-propose add-restock-sms دکمه «موجود شد خبرم کن» زیر محصولات ناموجود، فقط برای کاربر واردشده و با شماره همان حساب. وقتی موجودی برگشت، پیامک با لینک محصول، فقط بین ۹ صبح تا ۹ شب، به ترتیب ثبتنام و حداکثر به اندازه دو برابر موجودی. برای ارسال پیامک سقف ساعتی بگذار.
دقت کنید چه اتفاقی افتاد. پرامپت امید این بار همه درسهایی را که از مسیر Spec Kit گرفته بود در خودش دارد: ساعت ارسال، سقف تعداد، کاربر واردشده. در کار واقعی کسی یک فیچر را دو بار نمیسازد. اگر امید از اول با OpenSpec شروع کرده بود، اینها را باید خودش، موقع خواندن، پیدا میکرد. چون OpenSpec از شما سؤال نمیپرسد، فرض میکند خواستهتان را گفتهاید. این مهمترین فرق دو ابزار است و در بخش بعد دوباره سراغش میآییم.
خروجی propose یک پوشه برای همین تغییر است:
نیازمندیها در قالب سناریو نوشته میشوند، با WHEN برای موقعیت و THEN برای نتیجه. این قالب برای خواندن خیلی راحتتر از نثر است، چون هر سناریو را میشود جدا خواند و پرسید «درسته یا نه؟»:
امید proposal.md و این سناریوها را میخواند. یک ایراد پیدا میکند: هیچ سناریویی نگفته بود بعد از ارسال پیامک، شماره از فهرست حذف شود. یعنی دفعه بعد که این زعفران تمام میشد و دوباره میرسید، همان آدمها دوباره پیامک میگرفتند، حتی کسی که دفعه قبل خرید کرده بود. یک سناریو اضافه میکند و بعد /openspec-apply-change را میزند تا تسکها ساخته شوند.
بعد از تحویل و تست، /openspec-archive-change پوشه تغییر را به changes/archive میبرد و نیازمندیهایش را با openspec/specs ادغام میکند. این همان مستند زندهای است که در درس قبل گفتیم. هر چه در specs است ساخته شده و هر چه هنوز در changes است، فقط پیشنهاد است. سه ماه بعد که صاحب مغازه بپرسد «به کسی که قبلا خریده هم پیامک میره؟»، جواب در یک فایل است.
یک فیچر، دو خروجی
هر دو شاخه در نهایت یک فیچر کارکردنی تحویل دادند. فرق در مسیر بود:
| Spec Kit | OpenSpec | |
|---|---|---|
| دستورهایی که امید زد | حدود ده دستور، از constitution تا converge | سه دستور: propose، apply، archive |
| سؤال از شما | دارد (clarify) | ندارد؛ explore اختیاری است |
| چک ناسازگاری سندها | دارد (analyze و converge) | در پروفایل پیشفرض ندارد؛ پروفایل گسترده verify دارد |
| اصول کل پروژه | قانون اساسی | دستور جدایی برایش ندارد [نیاز به بررسی] |
| مشخصات بعد از تحویل | در پوشه هر فیچر میماند | با مشخصات اصلی پروژه ادغام میشود |
| حجم سندی که باید بخوانید | بیشتر | کمتر |
ردیف آخر از همه مهمتر است. یادتان هست در درس قبل گفتیم مشخصاتی که نخوانید فقط حدسهای ایجنت است که مرتب نوشته شده؟ Spec Kit سند بیشتری تولید میکند و هر سند اضافه، یعنی وسوسه بیشتر برای اینکه بقیهاش را نخوانید. امید در مسیر Spec Kit دو ایراد مهم در plan.md پیدا کرد، اما اعتراف کرد که چکلیست کیفیت را فقط ورق زد و تیک زد. این اتفاق عجیبی نیست. وقتی ابزار پنج سند به شما میدهد، چشم آدم روی چهارمی و پنجمی سر میخورد.
از آن طرف OpenSpec، دستکم در چرخه پیشفرضش، دو چیزی را که Spec Kit به شما هدیه میدهد ندارد: سؤال پرسیدن و چک ناسازگاری. در مسیر OpenSpec، پیدا کردن جاهای خالی کاملا کار شماست. اگر برنامهنویس تازهکاری هستید که هنوز نمیدانید چه سؤالی باید از کارفرما پرسید، clarify در Spec Kit عملا یک معلم مجانی است.
یک کار کوچک که OpenSpec را قویتر میکند
اگر OpenSpec را انتخاب کردید، بعد از propose و قبل از apply این را از ایجنت بخواهید: «این proposal و سناریوها را بخوان و پنج سؤالی را که باید قبل از ساختن از من بپرسی بنویس. هنوز هیچ کدی ننویس.» عملا یک clarify دستی ساختهاید، بدون سربار بقیه مسیر.
کدام را انتخاب کنیم؟
برای بیشتر کسانی که این دانشنامه را میخوانند، یعنی فریلنسر یا تیم دو سه نفرهای که روی پروژهای از قبل موجود کار میکند و هر هفته چند تغییر کوچک و متوسط میدهد، OpenSpec انتخاب پیشفرض است. سبک است، هر تغییر را جدا نگه میدارد، بعد از تحویل مشخصات اصلی پروژه را بهروز میکند و مهمتر از همه، حجم سندی که تولید میکند آنقدر کم است که واقعا میخوانیدش.
Spec Kit را وقتی بردارید که یکی از این سه را دارید. پروژهای که از صفر شروع میشود و میخواهید از روز اول اصولش را بنویسید. فیچری بزرگ که چند هفته طول میکشد و ناسازگاری بین سندهایش واقعا ممکن است. یا تیمی که چند نفر با چند ایجنت روی یک کد کار میکنند و یک قانون اساسی مشترک جلوی ده سلیقه مختلف را میگیرد. در این موقعیتها، همان مراحل اضافهای که برای فیچر «خبرم کن» زیادی بود، ارزش وقتشان را دارند.
البته این موضع یک ضعف هم دارد که باید بگوییم. OpenSpec به شما اعتماد میکند. اگر خودتان سؤال درست را نپرسید، هیچکس نمیپرسد. برای همین اگر تازه شروع کردهاید، شاید ارزش داشته باشد دو سه فیچر اول را با Spec Kit بروید، فقط برای اینکه یاد بگیرید clarify چه سؤالهایی میپرسد، و بعد سراغ OpenSpec بیایید.
این ابزارها هر چند ماه عوض میشوند
این درس بر اساس وضعیت آبان ۱۴۰۵ نوشته شده، یعنی Spec Kit با دستورهای خط تیرهدار و OpenSpec نسخه ۲. هر دو ابزار در یک سال گذشته اسم دستورهایشان را عوض کردهاند: Spec Kit از نقطه به خط تیره رسید و OpenSpec در نسخه ۲ دستورهای /opsx را کنار گذاشت. قبل از شروع، README همان نسخهای را که نصب کردهاید بخوانید و اگر دستوری کار نکرد، اول نسخه را چک کنید.
و یک چیز آخر که از هر دو مسیر میشود گرفت. در هیچکدام، ابزار خودش ایرادهای اصلی فیچر را درست نکرد. پیامک ساعت دو صبح و پیامک تکراری به کسی که قبلا خریده را امید با خواندن پیدا کرد. حتی ماجرای ربات و پنج هزار شماره را هم clarify فقط به شکل یک سؤال پیش کشید و جواب درست را امید داد. ابزار فقط جایی ساخت که این خواندن ممکن و ارزان باشد.
منابع
سؤالات متداول
Spec Kit یک ابزار خط فرمان متنباز از GitHub برای توسعه مبتنی بر مشخصات است که با Claude Code و بیش از چهل ایجنت دیگر کار میکند. با uv tool install specify-cli نصب میشود و بعد با specify init در پروژه راه میافتد. در این درس آن را با specify init --here --force --integration claude روی فروشگاه زعفران امید نصب کردیم.
Spec Kit مسیر کاملتری دارد، با قانون اساسی، سؤال پرسیدن از شما (clarify) و چک ناسازگاری سندها. OpenSpec فقط سه چهار دستور دارد، از شما سؤال نمیپرسد و بعد از هر تغییر، مشخصات اصلی پروژه را بهروز میکند. در مثال این درس، Spec Kit حدود ده دستور و OpenSpec سه دستور لازم داشت.
برای بیشتر پروژههای موجود و تیمهای کوچک، OpenSpec. سبکتر است و سند کمتری تولید میکند، پس احتمال اینکه واقعا بخوانیدش بیشتر است. Spec Kit را برای پروژه تازه، فیچر چندهفتهای یا تیمی نگه دارید که به اصول مشترک نیاز دارد.
در نسخههای فعلی با خط تیره نوشته میشوند، مثل /speckit-specify و /speckit-plan، و داخل چت Claude Code زده میشوند، نه در ترمینال. در مستندات قدیمیتر شکل نقطهدار /speckit.specify را میبینید. اگر دستوری پیدا نشد، اول نسخه نصبشده را چک کنید.
تمرین درس
یک فیچر متوسط از پروژه خودتان انتخاب کنید که با پول، پیامک یا اطلاعات کاربر سروکار دارد. قبل از نصب هر ابزاری، روی کاغذ بنویسید سه چیزی که فکر میکنید ایجنت در آن اشتباه حدس میزند چیست. -همان فیچر را با OpenSpec پیشنهاد بدهید (فقط propose، بدون apply). سناریوها را بخوانید و ببینید چند تا از سه حدس شما در آنها درست و چند تا غلط نوشته شده است. -اگر وقت دارید، روی یک شاخه جدا با Spec Kit تا مرحله clarify بروید و ببینید سؤالهایش کدام یک از سه مورد شما را پوشش میدهد و کدام را نه.
درسهای مهندسی نرم افزار و وایب کدینگ
۰ از ۹ دیده شده- ۱مهندسی نرم افزار با هوش مصنوعی چیست؟ تعریف، کاربردها و تفاوتش با برنامهنویسی سنتی
- ۲پرامپت نویسی برای برنامهنویسی: چطور از هوش مصنوعی، کد درست بگیریم؟
- ۳بهترین ابزارها و مدلهای هوش مصنوعی برای برنامهنویسی
- ۴وایب کدینگ یعنی چیست؟ از توییت کارپاتی تا کاربردها و محدودیتها
- ۵آموزش وایب کدینگ: ساخت اولین اپ با هوش مصنوعی قدمبهقدم
- ۶وقتی وایب کدینگ گیر میکند: دیباگ، ریست و برگشت به نسخه سالم
- ۷توسعه مبتنی بر مشخصات (SDD) چیست؟ چرا قبل از کد باید مشخصات بنویسی
- ۸آموزش عملی GitHub Spec Kit و Open Spec برای SDD
- ۹ایجنت کدنویسی (Coding Agent) چیست؟ از حلقه ایجنت تا محدودیتهاش