Spec Kit: راه حل وایب کدینگ (Vibe Coding) در 2026

intent مبهم و فرض‌های پنهان در درخواست‌های ساده

یه جمله ساده مثل «برای اپ من login اضافه کن» به‌ظاهر واضحه، ولی وقتی بازش کنی می‌بینی پر از تصمیم‌های نگفته است. روش ورود چیه؟ OAuth یا پسورد ساده؟ مدیریت session چطوره؟ محدودیت نرخ درخواست؟ نمایش خطاها؟ مهاجرت داده‌های قدیمی؟ سطح دسترسی کاربرها؟ تجربه کاربری و تست‌ها؟ این‌ها همه چیزهایی هستن که اول باید روشن بشن.برای اطلاعات بیشتر در این مورد می‌تونی پرامپت‌های دقیق برای Claude رو ببینی.

این‌ها همون چیزیه که بهش می‌گیم intent مبهم و فرض‌های پنهان. وقتی این فرض‌ها رو مشخص نکنی، AI Agent به‌جای تو تصمیم می‌گیره؛ و تصمیمی که Agent گرفته لزوماً همون چیزی نیست که تو می‌خواستی.

تصمیم‌های معماری که تا ریویو کد پنهان می‌مونن

وقتی این جزئیات از اول روشن نباشن، Agent مجبوره خودش انتخاب کنه. این انتخاب‌ها معمولاً دیده نمی‌شن تا وقتی که کد نوشته شده و به مرحله ریویو رسیده. اونجاست که می‌فهمی معماری انتخاب‌شده با چیزی که تیم روش توافق داشت فرق داره. هزینه این کشف دیرهنگام زیاده: بازنویسی، بحث دوباره درباره تصمیم‌هایی که باید از اول روشن می‌شدن، و از دست دادن زمانی که می‌شد صرف کار جدید کرد.

نقش context پراکنده در افزایش rework

بخش زیادی از دوباره‌کاری‌ها ریشه‌شون توی context پراکنده و rework هست. وقتی اطلاعات مربوط به یه فیچر بین چت‌های مختلف، کامنت‌های کد، و حافظه چندتا نفر پخش باشه، هر بار که Agent یا یه عضو تیم جدید وارد می‌شه باید دوباره context رو از صفر بسازه. این پراکندگی باعث می‌شه هم‌راستایی تیم به‌هم بریزه و همون کار چندبار با نتیجه‌های متفاوت انجام بشه.

نکته مهمی که اینجا باید روشن بشه اینه که spec منبع intent پذیرفته‌شده است و کد منبع رفتار واقعی اجرایی. ارزش اصلی Spec Kit دقیقاً توی آشکار کردن فاصله بین این دوتاست؛ جایی که این دو باهم فرق دارن، یعنی یه جای کار درست پیش نرفته.

harness فرایندی و artifacts، نه ابزار اجرایی

Spec Kit خودش کد رو اجرا نمی‌کنه و جای مدل هوش مصنوعی نمی‌شینه. کاری که می‌کنه اینه که یه ساختار مشخص برای تعامل بین انسان و AI Agent فراهم می‌کنه تا هر مرحله از فکر تا کد، مستند و قابل بازبینی بمونه. این harness فرایندی و artifacts چیزی هست که اجازه می‌ده هر تصمیم رو ثبت کنی، بعداً بهش برگردی و اگه لازم شد اصلاحش کنی.

نکته کلیدی: Spec Kit جای CLI، پرامپت و skill رو برای هدایت Agent می‌گیره؛ ولی خودش نه کد می‌نویسه نه اجرا می‌کنه.

قضاوت مهندسی رو جابه‌جا می‌کنه، حذف نمی‌کنه

یه ادعای مهم که باید روشن بشه اینه که Spec Kit قضاوت مهندسی انسان رو جایگزین نمی‌کنه؛ فقط محل اعمال این قضاوت رو از انتهای کار به ابتدای کار منتقل می‌کنه. یعنی به‌جای اینکه بعد از نوشتن کد بشینی و ببینی چی اشتباه پیش رفته، از همون اول مجبوری تصمیم‌های سخت رو بگیری. این جابه‌جایی به‌خودی‌خود کار رو راحت‌تر نمی‌کنه، ولی هزینه اشتباه رو زودتر آشکار می‌کنه.

نیاز به تعامل مستمر انسان و AI

Spec Kit بدون verification مداوم عملاً بی‌فایده‌ست. اگه فقط یه spec زیبا بنویسی و بعدش کد رو بدون بازبینی قبول کنی، دقیقاً همون مشکلی که می‌خواستی حل کنی دوباره برمی‌گرده. این ابزار نیازمند اینه که آدم‌ها مرتب بین spec و کد رفت‌وآمد کنن، نتیجه رو چک کنن و اختلاف‌ها رو پیدا کنن.

زنجیره اصلی: از specify تا implement

هر مرحله یه artifact مشخص تولید می‌کنه که نقش خودش رو توی مدیریت پیچیدگی داره:

مرحله plan؛ جایی که تصمیم‌های پنهان آشکار می‌شن

یکی از فایده‌های ملموس plan اینه که تصمیم‌هایی که قبلاً تا ریویو کد پنهان می‌موندن، حالا زودتر روی میز میان. وقتی Agent مجبور بشه قبل از نوشتن کد، معماری و استک فنی رو صریح بنویسه، تیم می‌تونه قبل از شروع کار واقعی روی این تصمیم‌ها بحث کنه، نه بعدش.

converge؛ بستن حلقه بین spec و کد

converge یه فرآینده که کد رو در برابر spec می‌سنجه و کار باقی‌مونده رو مشخص می‌کنه. این مرحله یه ابزار اثبات درستی (test oracle) نیست؛ بلکه یه راه برای بستن حلقه بین چیزی که قرار بود ساخته بشه و چیزی که واقعاً ساخته شده است.

قابلیت‌های جانبی: bug fixing و assess

کنار زنجیره اصلی، Spec Kit دوتا قابلیت اضافه هم داره که کاربردی هستن:

1. بخش رفع باگ: یه روند assess → fix → test رو دنبال می‌کنه تا مشکل به‌جای پنهون شدن پشت علائم، از ریشه بررسی بشه.
2. بخش ارزیابی (assess): قبل از اینکه اصلاً شروع به ساختن کنی، ایده رو تعریف و تحقیق می‌کنه تا مطمئن بشی ارزش ساختن داره.

feature‌های بزرگ و وابسته به معماری

جایی که Spec Kit واقعاً می‌درخشه، feature‌های بزرگ و وابسته‌ای هستن که به معماری یا سیستم موجود دست می‌زنن. توی این حالت، ریسک اشتباه بالاست و هزینه کشف دیرهنگام یه تصمیم غلط خیلی سنگین‌تر از هزینه نوشتن یه spec دقیقه. وقتی تغییری قراره چند بخش سیستم رو تحت تأثیر بذاره، از قبل مشخص کردن plan و architecture باعث می‌شه ریویو کد راحت‌تر و مؤثرتر پیش بره.

تیم‌های چندنفره با نیاز به context مشترک

وقتی چند نفر یا چندتا Agent روی یه feature کار می‌کنن، نداشتن یه سند مشترک باعث می‌شه هرکس یه برداشت متفاوت داشته باشه. یه spec که version-controlled باشه و کنار اون یه constitution مشترک وجود داشته باشه، این ریسک هم‌راستا نبودن رو به‌شکل قابل توجهی کم می‌کنه.

handoff‌های پیچیده و فاصله بین سند و کد قابل اجرا

خیلی وقت‌ها یه سند زیبا و کامل نوشته می‌شه ولی وقتی می‌رسه به مرحله اجرا، معلوم می‌شه اون سند عملاً قابل پیاده‌سازی نیست یا جاهای مهمی رو نگفته. مرحله‌های tasks و analyze توی Spec Kit دقیقاً برای کم کردن همین فاصله طراحی شدن؛ یعنی فاصله بین «سند قشنگ» و «کاری که واقعاً می‌شه انجامش داد».

اصلاح‌های کوچک و typo؛ جایی که ceremony زیاد ضرر داره

برای یه فیچر کوچیک، مثلاً چیزی حدود سه تا پنج story point، یا یه تغییر ساده مثل رفع تایپو، طی کردن کل زنجیره Spec Kit احتمالاً بازدهی منفی داره. وقتی زمانی که صرف نوشتن constitution، spec و plan می‌شه بیشتر از خودِ کاره، این ceremony کامل به‌جای کمک، مانع سرعت می‌شه.

تفاوت بین قابلیت قوی و بوروکراسی بی‌مورد

نکته مهمی که باید در نظر بگیری اینه که قابلیت‌های قوی Spec Kit با بوروکراسی بیش‌ازحد برای تغییرات ساده فرق داره. یه تیم باید بتونه تشخیص بده کِی این ساختار واقعاً کمک می‌کنه و کِی فقط داره سرعت رو کند می‌کنه. استفاده کورکورانه از یه workflow واحد برای همه نوع تسک، معمولاً نتیجه خوبی نمی‌ده.

خطر drift میان کد و spec

یه ریسک واقعی که باید جدی گرفته بشه اینه که drift میان کد و spec یه خطر واقعی است و نیازمند discipline، سیاست ریویو و ابزارهای مستمر برای کنترلشه. اگه بعد از نوشتن spec، هیچ‌کس مسئولیت نداشته باشه که مرتب چک کنه کد هنوز با spec هم‌خونی داره یا نه، این دوتا به‌مرور از هم فاصله می‌گیرن و spec عملاً بی‌فایده می‌شه.

مسئله اصلی AI کم‌بودن context و شفافیت توی نیازمندی‌ها نیست؛ بلکه نبود verification و feedback loop هست. یعنی حتی اگه spec فوق‌العاده دقیقی بنویسی، اگه کسی نباشه که مرتب کد رو در برابر اون spec بسنجه، دقتِ spec به‌تنهایی کافی نیست.

نیازی به fork کردن کل ریپو یا re-spec همه پروژه‌ها نیست

یکی از سوءتفاهم‌های رایج اینه که فکر می‌کنی برای استفاده از Spec Kit باید کل مخزن کد رو fork کنی یا همه پروژه‌های موجود رو دوباره spec بنویسی. این‌طور نیست. تیم می‌تونه صرفاً یه feature جدید رو specify کنه و فقط بخشی از context که واقعاً نگه‌داری می‌شه رو داخل اون بیاره.

شروع نقطه‌ای برای پروژه‌های موجود

برای پروژه‌های قدیمی که از قبل کد زیادی دارن، re-spec کردن همه‌چیز نه واقع‌بینانه‌ست نه لازم. یه رویکرد منطقی‌تر اینه که فقط feature جدیدی که داری اضافه می‌کنی رو از طریق Spec Kit ببری جلو، و بقیه کد رو دست‌نخورده بذاری. این‌طوری هم از مزیت ساختار بهره می‌بری، هم مجبور نیستی هزینه سنگین بازنویسی مستندات کل پروژه رو بدی.

selection منطقی بر اساس پیچیدگی و context

بهترین رویکرد اینه که تیم خودش تصمیم بگیره کدوم تسک نیاز به کل زنجیره Spec Kit داره و کدوم نه. این تصمیم باید بر اساس دو معیار اصلی باشه: پیچیدگی خود تسک، و اینکه چقدر context سازمانی برای اون تسک لازمه. یه تغییر جزئی با context محدود، احتمالاً نیازی به constitution و plan رسمی نداره؛ ولی یه فیچر بزرگ که چند بخش سیستم رو لمس می‌کنه، از این ساختار سود می‌بره.