توسعهٔ مستند‌محور در برابر کدنویسی حسی در نرم‌افزارهای پیچیده

اگر امروز از هوش مصنوعی برای نوشتن کدهای پیچیده استفاده می‌کنید، احتمالاً با لحظه‌ای مواجه شده‌اید که یک اصلاح کوچک، کل سیستم را به هم ریخته است. این همان نقطه‌ای است که «کدنویسی حسی» (Vibe Coding) — یعنی ارسال پرامپت‌های مبهم به یک مدل زبانی بزرگ (LLM) پیشرفته و وصله‌پینه کردن کد حاصل از آن از طریق آزمون و خطا تا زمانی که «به نظر درست برسد» — در مقیاس تولید شکست می‌خورد. برای اسکریپت‌های آخر هفته یا پروتوتایپ‌های یک‌بارمصرف، این روش شبیه جادو است، اما مهندسی نرم‌افزار حرفه‌ای با این رویکرد به یک دیوار برخورد می‌کند.

در پروژه‌های واقعی که با هم‌روندی (Concurrency)، معماری‌های چندپلتفرمی، قراردادهای سخت‌گیرانه و تأخیرهای بسیار پایین (Ultra-low latency) سروکار دارند، «کدنویسی حسی» با واقعیت برخورد کرده و در مقیاس تولید فرو می‌پاشد. این وضعیت به آنچه توسعه‌دهندگان «مرگ بر اثر هزاران وصله» می‌نامند منجر می‌شود: شما یک دکمه می‌خواهید، هوش مصنوعی وضعیت (State) را می‌شکند؛ شما می‌خواهید وضعیت را اصلاح کنید، او چرخه حیات (Lifecycle) را به هم می‌ریزد؛ و وقتی می‌خواهید چرخه حیات را درست کنید، نشت حافظه (Memory Leak) معرفی می‌کند. این وضعیت یک «توهم پیشرفت» ایجاد می‌کند؛ جایی که حجم کدها به‌صورت نمایی رشد می‌کند، اما قابلیت درک سیستم سقوط می‌کند. در نهایت، پروژه غیرقابل بازرسی می‌شود، زیرا هیچ توسعه‌دهنده انسانی — و هیچ عامل هوش مصنوعی در آینده — نمی‌تواند مفروضات طراحی را درک کند یا بفهمد چگونه بدون فروپاشی کل این «خانه کاهگلی»، کدها را بازسازی (Refactor) کند.

همان‌طور که در تحلیل قبلی ما درباره‌ی تبدیل شدن کدنویسی حسی به استاندارد کارهای ساده اشاره کردیم، اکنون چارچوبی به نام توسعهٔ مستند-محور (Spec-Driven Development یا SDD) به‌عنوان جایگزینی حرفه‌ای، سخت‌گیرانه و مقیاس‌پذیر معرفی شده است. طبق گزارشی که در ۲۱ سپتامبر ۲۰۲۶ در dev.to منتشر شد، این متدولوژی با اسناد فنی به‌عنوان تنها منبع حقیقت (Single Source of Truth) برخورد می‌کند؛ به این معنا که هیچ کدی در محیط تولید نوشته یا تغییر نمی‌کند مگر اینکه ابتدا به‌طور صریح در یک سند زنده مدل‌سازی شده باشد.

سیستمی را تصور کنید که در آن هوش مصنوعی نمی‌تواند صرفاً تابع بعدی را «حدس» بزند. در عوض، او باید از یک سلسله‌مراتب سخت‌گیرانه پیروی کند: یک سند نیازمندی‌ها (spec.md)، یک طرح معماری فنی (plan.md) و یک چک‌لیست قابل تأیید از وظایف اتمیک (tasks.md). این ساختار از «انحراف معماری» (Architectural Drift) که در کدنویسی به کمک هوش مصنوعی رایج است، جلوگیری می‌کند.

چارچوب حاکمیتی

برای جلوگیری از اینکه عامل‌های هوش مصنوعی به سمت هرج‌ومرج معماری سوق پیدا کنند، SDD یک «قانون اساسی پروژه» (docs/constitution.md) پیاده‌سازی می‌کند. این سند قوانینی غیرقابل مذاکره را تعیین می‌کند که هیچ پرامپت یا تصمیم فنی نمی‌تواند آن‌ها را نقض کند. در پروژه Virtual Studio Companion، این قانون اساسی از ۸ اصل بنیادی تشکیل شده است:

• هسته خالص (commonMain): ممنوعیت مطلق وارد کردن کتابخانه‌های android.* ،java.* یا هر کتابخانه پلتفرمی دیگر در کدهای مشترک. هر چیزی باید از طریق پورت‌ها و رابط‌ها (Interfaces) حل شود.
• حذف جاوا در کلاینت: فایل اجرایی ویندوز با jpackage و یک میکرو-رانتایم Temurin (jlink) بسته‌بندی می‌شود؛ به این معنی که کاربر نهایی نیازی به نصب جاوا ندارد.
• لایسنس‌های باز: محدود کردن کتابخانه‌ها به Apache 2.0، MIT یا BSD؛ لایسنس‌های کپی‌لفت مانند GPLv3 اکیداً ممنوع هستند.
• تاب‌آوری شبکه: سیستم نمی‌تواند فرض کند که mDNS به دلیل ایزولاسیون AP در روترها کار می‌کند؛ بنابراین، کد QR مکانیسم اصلی و بدون شرط اتصال است.
• یکپارچگی تم: پشتیبانی سخت‌گیرانه از StudioDarkColors و StudioLightColors با استفاده از isSystemInDarkTheme() برای تشخیص تم.
• اولویت SDD و TDD: هیچ کدی پیاده‌سازی نمی‌شود مگر اینکه ابتدا یک تست واحد (Unit Test) برای اعتبارسنجی رفتار مورد انتظار نوشته شده باشد.
• CI/CD بدون اصطکاک: خط لوله‌های خودکار GitHub Actions برای خروجی‌های لینوکس (app-debug.apk) و ویندوز (.exe / .msi).
• حذف رشته‌های سخت‌افزاری: ۱۰۰٪ متون رابط کاربری باید از Res.string.* تامین شوند.

در کنار این قانون، فایل AGENTS.md قرار دارد. این فایل توپولوژی مخزن (Monorepo) و دستورات خاص ترمینال، مانند ./gradlew allTests و ./gradlew :desktopApp:desktopTest را در اختیار هوش مصنوعی قرار می‌دهد. این سند گردش‌کار SDD را تعریف کرده و صراحتاً عامل هوش مصنوعی را از بداهه‌پردازی در کدنویسی منع می‌کند.

کالبدشکافی یک مستند فنی

هر ویژگی در گردش‌کار SDD در مسیر specs/<feature>/ قرار می‌گیرد و به سه مصنوع متمایز تجزیه می‌شود:

• spec.md (نیازمندی‌های تجاری): از نحو EARS (رویکرد آسان به نحو نیازمندی‌ها) و معیارهای BDD (توسعه رفتار-محور) استفاده می‌کند. برای مثال، نیازمندی RF-003 مشخص می‌کند که «زمانی که (WHEN) میزبان تشخیص دهد OBS Studio در حال اجرا است، سیستم باید (MUST) به پورت ۴۴۵۵ متصل شود، IObsConnector را پیاده‌سازی کند، چالش SHA256 را حل کند و Browser Source مربوط به Virtual Studio Camera را به‌روزرسانی کند». معیارهای پذیرش به این صورت نوشته می‌شوند: «با فرض اینکه (GIVEN) OBS متصل است، زمانی که (WHEN) کاربر روی Disconnect OBS کلیک می‌کند، آنگاه (THEN) میزبان باید سوکت را بسته و به وضعیت DISCONNECTED تغییر حالت دهد در حالی که استریم موبایل حفظ شود».
• plan.md (طراحی فنی): شامل طراحی‌های فنی و نمودارهای توالی Mermaid است. این سند جریان دقیق را مدل می‌کند: میزبان Ktor (پورت‌های ۸۰۸۰-۸۰۹۰) را لینک کرده و یک QR با TTL ۱۲۰ ثانیه‌ای تولید می‌کند؛ گوشی QR را اسکن کرده و HANDSHAKE_INIT را ارسال می‌کند؛ سپس میزبان ورودی OBS را ایجاد کرده و یک استریم multipart MJPEG ارائه می‌دهد.
• tasks.md (چک‌لیست اتمیک): چک‌لیستی که هر مورد آن دارای یک شرط سخت‌گیرانه «انجام‌شده در صورتی که» است. برای مثال، وظیفه T04 (پیاده‌سازی ObsWebSocketAdapter) تنها زمانی کامل علامت می‌خورد که آداپتور بتواند دست‌دادن (Handshake) احراز شده در ws://localhost:4455 را حل کند، KtorObsTransport را با یک بافر بازپخش (Replay Buffer) برابر با ۱ برای جلوگیری از دست رفتن فریم op: 0 پیاده کند و تمام تست‌های T03 را پاس کند.

پرامپت‌های عملیاتی برای اجرای سطح ارشد

راز جلوگیری از تخریب پروژه در چهار پرامپت عملیاتی خاص است که برای مراحل مختلف چرخه حیات نرم‌افزار طراحی شده‌اند:

۱. اجرای متوالی (Batch SDD): این پرامپت هوش مصنوعی را مجبور می‌کند در نقش یک توسعه‌دهنده ارشد عمل کند. او موظف است ابتدا قانون اساسی و AGENTS.md را بخواند. برای هر وظیفه، AI باید این حلقه را طی کند: شناسایی نیازمندی‌ها $\rightarrow$ طبقه‌بندی به عنوان منطق دامنه (TDD) یا زیرساخت (تأیید بیلد) $\rightarrow$ اجرا $\rightarrow$ ارائه مدرک ترمینال (مثلاً BUILD SUCCESSFUL) $\rightarrow$ علامت‌گذاری وظیفه به عنوان انجام‌شده $\rightarrow$ ایجاد یک Conventional Commit.

۲. اجرای گام‌به‌گام: برای کنترل دقیق استفاده می‌شود و AI را به یک ID وظیفه واحد محدود می‌کند. عامل باید تست را بنویسد، آن را با شکست مواجه کند، حداقل کد لازم برای پاس شدن تست را پیاده کند و سپس متوقف شده و منتظر تأیید انسانی بماند.

۳. تشخیص بحرانی: وقتی خطاها رخ می‌دهند، SDD اجازه نمی‌دهد از AI بخواهید فوراً آن را «اصلاح» کند. در عوض، توسعه‌دهنده لاگ‌ها و Traceها را ارائه داده و به AI می‌گوید: «مشکلات را شناسایی کن، اما هنوز راهکاری پیشنهاد نده». این کار از اعمال وصله‌های محلی عجولانه که قراردادهای معماری را می‌شکنند، جلوگیری می‌کند.

۴. بهبود کانونی: پس از تشخیص ریشه مشکل، از این پرامپت برای به‌روزرسانی spec.md ،plan.md یا tasks.md استفاده می‌شود. این تضمین می‌کند که پروژه به تاریخچه‌ای آشفته از وصله‌های پراکنده تبدیل نشود و مستندات با واقعیت کد هم‌راستا بمانند.

کاربرد واقعی: Virtual Studio Companion

برای اثبات کارایی SDD، توسعه‌دهندگان پروژه Virtual Studio Companion را ساختند؛ مجموعه‌ای پیچیده که از Kotlin Multiplatform (KMP) و Compose Multiplatform استفاده می‌کند. این سیستم یک دستگاه اندرویدی را به دوربینی با تأخیر بسیار پایین برای OBS Studio در ویندوز تبدیل می‌کند و یک مانیتور ویدئویی بومی را از طریق Skia و کدهای QR استاندارد ISO/IEC 18004 یکپارچه می‌سازد.

قابلیت‌های سیستم:

• اپلیکیشن اندروید: ضبط ویدیو ۱۰۸۰p از طریق CameraX، فشرده‌سازی فریم‌ها به JPEG در یک ترد اختصاصی CameraX-Worker ،محاسبه FPS و بیت‌ریت در یک پنجره لغزان ۱۰۰۰ میلی‌ثانیه‌ای و ارسال فریم‌های باینری از طریق WebSocket. همچنین از Google ML Kit برای اسکن QR با شتاب‌دهنده سخت‌افزاری استفاده می‌کند.
• میزبان ویندوز: یک سرور Ktor داخلی (پورت‌های ۸۰۸۰-۸۰۹۰) که کدهای QR را از طریق ZXing Core تولید می‌کند. فریم‌های ویدئویی را در لحظه با استفاده از org.jetbrains.skia.Image.makeFromEncoded برای یک مانیتور بازگشتی ۱۶:۹ بومی رمزگشایی می‌کند.
• یکپارچگی با OBS: ارائه یک استریم HTTP multipart مداوم در مسیر /stream/mjpeg و یک صفحه پیش‌نمایش واکنش‌گرا. ارتباط با OBS Studio v5 از طریق WebSocket و حل چالش‌های SHA256 برای تزریق یک Browser Source.
• همگام‌سازی دوطرفه: کنترل از راه دور زوم و چراغ قوه با جلوگیری از حلقه بازگشتی (Echo-loop)، به همراه تله‌متری زنده برای باتری، وضعیت حرارتی و تأخیر RTT.

چند چالش با پیچیدگی بالا با استفاده از این متد حل شد:

مورد اول: سیاست Cleartext اندروید و نمایشگر سوراخ‌دار. وقتی اندروید ترافیک Wi-Fi محلی را مسدود کرد (UnknownServiceException: CLEARTEXT communication not permitted)، تیم صرفاً یک فلگ به Manifest اضافه نکرد. آن‌ها نیازمندی‌های غیرعملکردی (RNF-005) را در spec.md بازنویسی کردند تا سیاست شبکه محلی را به عنوان یک نیازمندی رسمی بگنجانند. آن‌ها network_security_config.xml را برای فعال‌سازی ترافیک محلی در شبکه‌های خصوصی پیاده کردند. علاوه بر این، مشکلی در اسکنر QR حل شد که در آن BlendMode.Clear باعث ایجاد یک جعبه سیاه می‌شد؛ با اصلاح وظیفه T08 و استفاده از Modifier.graphicsLayer(compositingStrategy = CompositingStrategy.Offscreen)، یک برش نیمه‌شفاف ۵۰٪ کاملاً شفاف به دست آمد.

مورد دوم: پرش نشست واکنشی. باگی که باعث می‌شد اپلیکیشن بلافاصله پس از جفت‌شدن (Pairing) قطع شود، از طریق پرامپت «تشخیص بحرانی» شناسایی شد. AI دریافت که CameraScreen در حال مشاهده uiState.connectionState است. چون ViewModel در ابتدا در وضعیت Disconnected بود و کوروتین اتصال چند میلی‌ثانیه زمان می‌برد تا شروع شود، مشاهده‌گر تابع onDisconnect() را اجرا می‌کرد. راهکار شامل به‌روزرسانی CameraStreamViewModel برای پذیرش initialConfig: PairingConfig? و مقداردهی اولیه در وضعیت ConnectionState.Pairing(config) بود، در حالی که یک گارد hasActiveSession به onDisconnect() اضافه شد.

مورد سوم: رقابت WebSocket (replay = 1). یک شکست بحرانی هنگام اتصال به OBS رخ داد. تشخیص نشان داد که تنظیم replay = 0 در MutableSharedFlow باعث می‌شد اولین فریم «سلام» (op: 0) از طرف OBS در شرایط بار پردازشی CPU دور ریخته شود. چون جمع‌کننده (Collector) چند میلی‌ثانیه زمان می‌برد تا مشترک شود، پیام گم می‌شد و منجر به تایم‌اوت ۴ ثانیه‌ای می‌شد. راهکار، یک به‌روزرسانی کانونی در مستندات برای تضمین replay = 1 و قرار دادن اشتراک در یک Mutex قبل از باز کردن سوکت بود.

مورد چهارم: قطع اتصال متقارن و مستقل. در ابتدا، قطع اتصال OBS باعث می‌شد نشست موبایل نیز بسته شود. تیم نیازمندی‌های RF-003 و RF-004 را به‌روزرسانی کرد تا DesktopHostViewModel.disconnectObs() را به‌طور مستقل از disconnectSession() پیاده‌سازی کند. آن‌ها دکمه‌های متنی در Compose Desktop طراحی کردند: اگر متصل باشد، «Disconnect OBS» (Res.string.desktop_action_disconnect_obs) را نشان می‌دهد و اگر قطع باشد، «Connect OBS» را. دکمه قرمز کلی همچنان برای نشست گوشی رزرو شده است.

تقارن در گیت (Git Symmetry)

در یک جریان حرفه‌ای SDD، تاریخچه گیت تپه‌ای از تغییرات انباشته نیست، بلکه آینه‌ای از مستندات است. هر ویژگی (feat) یا اصلاح (fix) پیش از آن یا همراه با یک به‌روزرسانی مستند (docs(specs)) می‌آید.

برای مثال، تاریخچه مخزن الگوی واضحی را نشان می‌دهد:

• 66c9063 docs(specs): refine obs connection and disconnect specifications and tasks $\rightarrow$ 58deef0 feat(desktop): support independent obs disconnect and fix websocket transport race condition
• 75e5b79 docs(specs): refine mobile pairing initialization and transition guard in spec and tasks $\rightarrow$ 8395458 fix(android): prevent premature screen exit and initialize CameraStreamViewModel in pairing state

این ساختار یک ماتریس ردیابی ۱:۱ ایجاد می‌کند که به هر بازرس انسانی یا عامل هوش مصنوعی در آینده اجازه می‌دهد دقیقاً بفهمد چرا یک تصمیم طراحی ماه‌ها پیش گرفته شده است.

این تغییر، فرض بنیادی کدنویسی با هوش مصنوعی را تغییر می‌دهد. هدف دیگر سرعت تولید نیست، بلکه حاکمیت بر عامل است. با انتقال «هوش» از پرامپت به مستندات، توسعه‌دهنده کنترل معماری را بازپس می‌گیرد.

برای کسانی که نرم‌افزارهای در سطح تولید (Production-grade) می‌سازند، انتقال از «حس کردن» به «مشخص کردن» تنها راه اجتناب از فروپاشی اجتناب‌ناپذیر کدهای تولید شده توسط AI است. اکنون می‌توانید پیاده‌سازی کامل این متدولوژی را در مخزن متن‌باز Virtual Studio Companion در گیت‌هاب (نسخه v1.0.1) بررسی کنید.