مصاحبه سری AI ۱۶: یک Spec Coding خوب باید چگونه باشد؟

یک Spec Coding خوب (توسعه مبتنی بر مشخصات)،核心 آن تبدیل "ایده‌های مبهم" به "قراردادهای دقیق، قابل تأیید و قابل اجرا" است. این فقط نوشتن یک سند نیست، بلکه ایجاد یک زبان ارتباطی بدون ابهام بین انسان و AI (یا انسان و انسان) است. در زیر از چهار بعد ساختار محتوای مشخصات، اصول نگارش، فرایند همکاری با AI، و تأیید کیفیت، شکل یک مشخصات خوب را ارائه می‌دهم.

یک. ساختار استاندارد سند مشخصات (مثلاً برای یک ماژول功能)

بخش	محتوای الزامی	مثال
۱. هدف و محدوده	یک جمله توضیح دهد چه کاری انجام می‌شود، به وضوح مشخص کند چه کاری انجام نمی‌شود	"پیاده‌سازی API ثبت‌نام کاربر، شامل تأیید ایمیل نمی‌شود"
۲. قرارداد ورودی/خروجی	ساختار داده، نوع، فیلدهای اجباری/اختیاری، مقادیر نمونه	درخواست `POST /register` بدنه `{email: string, password: string}`، پاسخ `201` یا `400` حاوی کد خطا
۳. رفتار و منطق	قوانین کسب‌وکار، شرایط مرزی، انتقال حالت	"طول رمز عبور ۸-۲۰ کاراکتر، حداقل شامل یک عدد؛ در صورت وجود ایمیل، بازگشت `409`"
۴. مدیریت خطا	تمام سناریوهای استثنایی ممکن و کدهای خطا/پیام‌های مربوطه	"اتصال پایگاه داده شکست → بازگشت `503`، عدم نمایش堆スタック"
۵. نیازمندی‌های غیرعملکردی	عملکرد (زمان پاسخ < ۲۰۰ms)، امنیت (پرس‌وجوهای پارامتری)، لاگ، قابلیت مشاهده	"همه SQLها باید از pre-compiled استفاده کنند؛ `email` را ثبت کنید اما `password` را ثبت نکنید"
۶. موارد آزمایش (کلیدی)	حداقل ۳ ورودی معمولی + ۲ ورودی مرزی/استثنایی، با خروجی مورد انتظار	جدول زیر را ببینید
۷. وابستگی‌ها و محدودیت‌ها	استفاده از چه کتابخانه‌ای، نسخه، متغیرهای محیطی	"Python 3.10+، FastAPI، متغیر محیطی `DB_URL`"

مثال موارد آزمایش (جاسازی شده در مشخصات)

سناریو	ورودی	خروجی مورد انتظار
ثبت‌نام عادی	email: `a@b.com`, pwd: `Pass1234`	`201`، بازگشت `user_id`
رمز عبور خیلی کوتاه	pwd: `Ab1`	`400`، کد خطا `WEAK_PASSWORD`
ایمیل از قبل وجود دارد	ایمیل یکسان	`409`، کد خطا `EMAIL_EXISTS`

یک مشخصات خوب باید ابتدا موارد آزمایش را بنویسد، زیرا AI می‌تواند مستقیماً بر اساس آنها تست‌های واحد تولید کند و پس از اتمام به طور خودکار تأیید کند.

دو. اصول اصلی نگارش مشخصات (تغییر SMART)

اصل	توضیح	مثال نقض
دقیق (Precise)	استفاده از اعداد مشخص، انواع، شرایط بولی، اجتناب از "تا حد امکان"، "معمولاً"	❌ "رمز عبور باید به اندازه کافی امن باشد" → ✅ "رمز عبور حداقل ۸ کاراکتر، شامل حرف بزرگ، حرف کوچک، عدد"
قابل تأیید (Verifiable)	هر نیاز می‌تواند از طریق تست خودکار یا بررسی دستی موفق/شکست تعیین شود	❌ "کد باید زیبا باشد" → ✅ "پیچیدگی سیکلوماتیک تابع ≤ ۱۰، بدون بلوک کد تکراری"
بدون ابهام (Unambiguous)	یک اصطلاح در کل سند به یک معنا استفاده شود، در صورت لزوم واژه‌نامه ارائه شود	❌ "اگر کاربر وجود ندارد، خطا برگردان" → ✅ "کاربر وجود ندارد → بازگشت `404` و `{code: 'USER_NOT_FOUND'}`"
کامل (Complete)	پوشش مسیر خوشحال، تمام مسیرهای استثنایی، نیازمندی‌های غیرعملکردی	❌ فقط سناریوی موفق نوشته شده → ✅ شامل timeout پایگاه داده، عدم مجوز و غیره
اتمی (Atomic)	یک مشخصات فقط یک قابلیت قابل تحویل مستقل را توصیف کند (برای تکمیل یکباره AI مناسب)	❌ با یک مشخصات "کل سیستم پرداخت" را بنویسید → ✅ به "تولید فاکتور پرداخت"، "بررسی امضای بازگشتی"، "بازپرداخت" تقسیم کنید

سه. فرایند Spec Coding در همکاری با AI

انسان مشخصات را می‌نویسد (ساختار فوق، به ویژه موارد آزمایش و امضای تابع).
مشخصات را یکباره به AI بدهید (نیازهای اضافی را به صورت مکالمه‌ای اضافه نکنید، از آلودگی ویب جلوگیری کنید).
AI کد + تست‌های واحد را خروجی می‌دهد (AI باید موارد آزمایش را در مشخصات به تست‌های قابل اجرا تبدیل کند).
تست‌ها را اجرا کنید: اگر همه عبور کردند، به مرحله بعد بروید؛ اگر نه، مشخصات را اصلاح کنید یا مستقیماً کد را تصحیح کنید (در اینجا می‌توان وارد یک حلقه کوچک شد، اما تغییرات باید ثبت شوند).
بررسی انسانی: بررسی کنید که آیا قابلیت‌های خارج از مشخصات (scope creep) معرفی شده است، امنیت/عملکرد را بررسی کنید.
تثبیت: سند مشخصات و کد نهایی را با هم به مخزن ارسال کنید، به عنوان سند دائمی.

عملکرد کلیدی: Spec به عنوان کد — استفاده از spec.md + test_spec.py، که فایل تست مستقیماً از مثال‌های مشخصات می‌آید، به طوری که بعداً با تغییر کد فقط با اجرای تست می‌توان تأیید کرد که مشخصات نقض نشده است.

چهار. اثرات یک مشخصات خوب (می‌تواند به عنوان معیار پذیرش استفاده شود)

قطعی بودن: مشخصات یکسان به AIهای مختلف (یا افراد مختلف) خروجی‌های مشابهی می‌دهد.
قابل آزمایش بودن: پس از نوشتن کد، بلافاصله ۹۰٪ صحت به طور خودکار قابل تأیید است.
قابل نگهداری بودن: شش ماه بعد، هر کسی که مشخصات را ببیند، می‌تواند هدف طراحی اولیه را درک کند.
هزینه ارتباطی پایین: در بحث تیمی، فقط مشخصات بحث می‌شود، نه خطوط کد خاص.
امنیت/کیفیت داخلی: الزامات امنیتی (مانند پرس‌وجوهای پارامتری) و شرایط مرزی در مشخصات نوشته می‌شود، AI باید رعایت کند.

پنج. مثال یک مشخصات خوب (نسخه ساده)

# مشخصات: API ثبت‌نام کاربر

## محدوده
- دریافت email, password
- ارسال ایمیل تأیید نمی‌کند، اعتبار ایمیل را بررسی نمی‌کند

## قرارداد
POST /register
Content-Type: application/json
درخواست: { "email": string, "password": string }
پاسخ 201: { "user_id": string }
پاسخ 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
پاسخ 409: { "code": "EMAIL_ALREADY_EXISTS" }

## رفتار
- email باید از قالب پایه RFC 5322 پیروی کند (a@b.c)
- password: طول ۸-۲۰، حداقل شامل یک عدد و یک حرف بزرگ
- رمز عبور با bcrypt و هزینه نمک ۱۰ ذخیره شود
- اگر قبل از ذخیره در پایگاه داده ایمیل وجود داشته باشد → 409

## موارد آزمایش (ورودی -> کد وضعیت + فیلدهای پاسخ)
| ورودی email | password | مورد انتظار |
|------------|----------|------|
| test@x.com | Pass1234  | 201, user_id وجود دارد |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (ایمیل موجود) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## غیرعملکردی
- SQL باید از پرس‌وجوهای پارامتری استفاده کند (جلوگیری از تزریق)
- لاگ ثبت IP مبدأ ثبت‌نام، لاگ رمز عبور ثبت نشود
- زمان پاسخ ۹۵٪ درخواست‌ها < 100ms (بدون bcrypt)

## وابستگی‌ها
- Python 3.10+، FastAPI، bcrypt، asyncpg

Spec Coding خوب = تبدیل "تصمیمات طراحی" انسان به "موارد آزمایش + امضای نوع + محدودیت‌های رفتار" ماشین، به طوری که AI فقط مسئول پر کردن پیاده‌سازی باشد، در حالی که انسان همیشه کیفیت و جهت را کنترل می‌کند.