قبل از کد، مسئله را روشن کن

این درس چه چیزی به شما می‌دهد؟

فرض کنید صاحب محصول می‌گوید: «برای فهرست کارها یک فیلتر بگذار.» اگر همان لحظه سراغ کد بروید، هنوز معلوم نیست مشکل واقعی چیست، چه کسی آن را تجربه می‌کند و بعد از حل شدن چه تغییر بیرونی باید دیده شود. AI هم معمولاً جاهای خالی را با حدس‌های محتمل پر می‌کند؛ حدس‌هایی که ممکن است هیچ‌وقت خواستهٔ صاحب مسئله نبوده باشند.

در این درس یک «شرح مسئلهٔ نسخهٔ ۱» (Problem Brief v1) می‌سازید. این artifact فقط سه چیز را روشن می‌کند: مسئلهٔ قابل مهندسی، نتیجهٔ قابل مشاهده، و تفکیک واقعیت/فرض/ابهام. قرار نیست هنوز راه‌حل انتخاب کنید، محدوده و محدودیت‌ها را کامل ببندید یا معیارهای پذیرش بنویسید. FND-001-P02 فقط مالک scope، constraints و non-goals بعد از روشن‌شدن مسئله است؛ معیارهای پذیرش در این درس بسته نمی‌شوند و بدون authority به P02 نسبت داده نمی‌شوند.

زمان فعال تقریبی: ۴۵ دقیقه.

این درس مناسب شماست اگر: درخواست‌های کوتاه و مبهم را به AI یا هم‌تیمی می‌دهید و می‌خواهید قبل از اجرا، مسئله و نتیجهٔ مورد انتظار روشن باشد.

این درس برای این کارها نیست: انتخاب implementation، طراحی معماری، نوشتن acceptance criteria، یا تبدیل unknownها به تصمیم‌های قطعی.

پیش‌نیاز سخت — ORI-006: باید بتوانید از روی یک claim یا پیشنهاد فنی، منبع/شواهد و حدود اطمینان را بررسی کنید و چیزی را بدون evidence به‌عنوان واقعیت نپذیرید.

پروب کوتاه پیش‌نیاز ORI-006

قبل از انتخاب مسیر این درس، این بستهٔ کوچک را بررسی کنید:

• ادعا: «Raven CLI 4 برای استفادهٔ production در این تیم تأیید شده است.»
• شاهد A: صفحهٔ رسمی vendor می‌گوید Raven CLI 4.x تا پایان ۲۰۲۷ پشتیبانی محصولی دارد.
• شاهد B: wiki داخلی تیم با تاریخ ژانویهٔ ۲۰۲۵ می‌گوید «فقط Raven 3 تأیید است»، اما owner و وضعیت بازبینی آن مشخص نیست.
• شاهد C: یک screenshot بدون تاریخ نشان می‌دهد Raven CLI 4 روی یک دستگاه اجرا شده است.

در چهار خط بنویسید: مرز دقیق ادعا، هر شاهد واقعاً اختیار اثبات چه چیزی را دارد، چه چیزی هنوز unknown است، و تصمیم شما ACCEPT / MODIFY / DEFER چیست.

معیار PASS قطعی، ۴ از ۴ است: (۱) پشتیبانی vendor را با تأیید داخلی تیم یکی نکنید؛ (۲) screenshot اجرای موفق را evidence تأیید production ندانید؛ (۳) وضعیت تأیید داخلی را تا روشن‌شدن authority/freshness به‌صورت unknown نگه دارید؛ (۴) ادعای فعلی را بدون evidence تکمیلی ACCEPT نکنید و MODIFY یا DEFER را با دلیل انتخاب کنید.

اگر حتی یکی از چهار معیار را از دست دادید، ادامه ندهید. repair هدفمند ORI-006 را فقط روی همان شکست انجام دهید: برای اشتباه authority به بخش «چه نوع منبعی برای چه ادعایی؟»، برای provenance/freshness به «هفت بررسی پیش از ACCEPT»، و برای تصمیم نهایی به «ACCEPT، MODIFY یا DEFER» و «Final card check» برگردید. سپس همین probe را یک بار دیگر انجام دهید؛ ورود به FND-001-P01 فقط با ۴/۴ مجاز است.

مسیر مناسب خودتان را انتخاب کنید

همهٔ مسیرها به یک خروجی و یک معیار شواهد می‌رسند؛ تفاوت فقط در مقدار کمک است.

پروب سه‌مفهومی مسیر

قبل از انتخاب مسیر، بدون نگاه‌کردن به توضیح‌های پایین سه پاسخ کوتاه بدهید:

1. K01: جملهٔ «یک دکمهٔ فیلتر آبی بساز» را طوری بازنویسی کنید که فقط شکاف فعلی را بگوید و هیچ solutionی را الزام نکند.
2. K02: جملهٔ «وقتی PR merge شد کار تمام است» را به یک نتیجهٔ بیرونی و قابل مشاهده تبدیل کنید.
3. K03: جملهٔ «فیلتر باید بین sessionها بماند» هیچ evidence ندارد؛ آن را fact / assumption / unknown طبقه‌بندی و دلیل را در یک خط بنویسید.

هر پاسخ فقط وقتی PASS است که همان مفهوم را مستقل و بدون واردکردن تصمیم downstream نشان دهد. ۳/۳ → مسیر باتجربه/Fast Path؛ ۲/۳ → مسیر ترمیم فقط برای همان مفهوم شکست‌خورده؛ ۰ یا ۱/۳ → مسیر پایه. نقشهٔ repair: K01 و K02 به «سه مفهوم پایه» برمی‌گردند؛ K03 به «واقعیت، فرض و ابهام» و در صورت نیاز «سه خطای محتمل و روش ترمیم» برمی‌گردد.

• مسیر پایه: کیس فیلتر کارها را قدم‌به‌قدم با قالب قابل‌مشاهده جلو ببرید.
• مسیر ترمیم: فقط همان مفهوم شکست‌خورده در probe بالا را ترمیم کنید؛ مفاهیم مسلط را دوباره از اول نخوانید.
• مسیر باتجربه / Fast Path: فقط با PASS کامل ۳/۳، مستقیم به مقصد پایدار «تمرین مستقل» بروید. کیس شما عمداً اطلاعات ناقص یا متناقض خواهد داشت.

شرط خروج از Fast Path: artifact شما باید همان evidence bar مسیر پایه را پاس کند؛ تجربه باعث کاهش معیار نمی‌شود.

مدل ذهنی: قبل از «چطور»، سه سؤال را ببند

یک درخواست مبهم معمولاً زود به «چطور بسازیم؟» می‌پرد. این درس قبل از آن سه سؤال را جدا می‌کند:

1. چه شکافی وجود دارد؟ وضعیت فعلی چه چیزی را برای یک actor نامناسب یا ناقص کرده است؟
2. اگر مسئله حل شود، چه چیز بیرونی دیده می‌شود؟ نتیجه باید بدون دیدن کد قابل مشاهده یا سنجش باشد.
3. کدام گزاره را می‌دانیم، کدام را حدس می‌زنیم و کدام هنوز پاسخ ندارد؟ هر گزارهٔ تصمیم‌ساز باید وضعیت روشن داشته باشد.

TA-001 این رابطه را به‌صورت جدول «مفهوم → فیلد artifact → evidence → مرز» نشان می‌دهد. هیچ امتیاز یا عدد ساختگی در آن وجود ندارد.

نکتهٔ مرزی: «scope»، «constraints»، «non-goals» و معیارهای پذیرش هنوز اینجا بسته نمی‌شوند. سؤال‌های scope/constraints/non-goals را برای FND-001-P02 نگه دارید. اگر سؤال به acceptance criteria مربوط است، فقط آن را به‌عنوان تصمیم downstream باز ثبت کنید؛ این Bible مالکیت آن را به P02 نداده است.

سه مفهوم پایه

۱) مسئلهٔ قابل مهندسی

مسئله، فاصلهٔ روشن میان وضعیت فعلی و نتیجهٔ موردنیاز است؛ نه فهرست کار و نه راه‌حل پیشنهادی.

ضعیف: «یک دکمهٔ Filter بساز.» بهتر: «کاربر در فهرست ترکیبی کارهای انجام‌شده و ناتمام، نمی‌تواند سریع فقط موارد ناتمام را ببیند.»

آزمون سریع: آیا یک نفر دیگر از روی جمله می‌فهمد چه چیزی اکنون کم/غلط است، بدون اینکه مجبور باشد راه‌حل را حدس بزند؟

۲) نتیجهٔ قابل مشاهده

نتیجه یعنی رفتاری که بعد از حل مسئله در بیرون سیستم دیده می‌شود؛ «کد نوشته شد» یا «کامپوننت اضافه شد» فعالیت‌اند، نه نتیجه.

برای کیس مشترک: «کاربر می‌تواند نمایش را به کارهای ناتمام محدود کند و دوباره به نمایش همهٔ کارها برگردد.» این جمله هنوز implementation را تعیین نمی‌کند.

۳) واقعیت، فرض و ابهام

• واقعیت: evidence یا authority قابل اشاره دارد.
• فرض: فعلاً محتمل است اما تأیید نشده.
• ابهام: برای ادامهٔ تصمیم‌گیری پاسخ لازم دارد یا باید عمداً باز نگه داشته شود.

مثال: «فیلتر باید بعد از بستن مرورگر باقی بماند» اگر هیچ منبعی ندارد، واقعیت نیست. آن را assumption یا unknown ثبت کنید؛ پنهانی به قرارداد تبدیلش نکنید.

شرح مسئلهٔ نسخهٔ ۱ را چگونه بسازیم؟

Problem Brief v1 باید آن‌قدر کوچک بماند که قبل از کد ساخته شود، اما آن‌قدر روشن باشد که دو نفر دربارهٔ مسئلهٔ متفاوت حرف نزنند.

یک Problem Brief خوب «تمام پروژه» را حل نمی‌کند. کارش این است که نقطهٔ شروع را صادقانه کند: مسئله چیست، نتیجهٔ بیرونی چیست، و کجا هنوز نمی‌دانیم.

AI کجا کمک می‌کند و کجا نه؟

AI می‌تواند عبارت‌های مبهم را نقد کند، چند تعبیر ممکن را کنار هم بگذارد، unknownهای احتمالی را یادآوری کند یا consistency artifact را بررسی کند. اما AI نباید بدون evidence تصمیم بگیرد actor واقعی چه کسی است، unknown را به requirement تبدیل کند، یا approval انسان را جعل کند. تصمیم نهایی دربارهٔ گزاره‌های مبهم با انسان و evidence است.

مثال حل‌شده: درخواست «فیلتر اضافه کن»

درخواست اولیه: «روی task list یک فیلتر unfinished بگذار.»

نسخهٔ بد: «یک toggle آبی اضافه کن، state را در URL ذخیره کن و وقتی component ساخته شد کار تمام است.» این متن سه تصمیم را بدون مجوز وارد کرده: راه‌حل UI، persistence در URL و تعریف پایان بر اساس activity.

Problem Brief v1 محدود:

• Actor/context: کاربری که در یک فهرست ترکیبی از کارهای تمام‌شده و ناتمام کار می‌کند.
• شکاف فعلی: هنگام مرور فهرست، راه روشن و موجودی برای محدودکردن نمایش به کارهای ناتمام ندارد.
• نتیجهٔ قابل مشاهده: کاربر می‌تواند فقط کارهای ناتمام را ببیند و سپس به نمایش همهٔ کارها برگردد.
• واقعیت: دادهٔ هر کار وضعیت انجام‌شده/ناتمام دارد؛ این موضوع در کیس ارائه‌شده صریح است.
• فرض: شاید کاربران بخواهند انتخاب فیلتر بین sessionها حفظ شود؛ evidence فعلی ندارد.
• ابهام: آیا persistence لازم است؟ آیا behavior باید در URL قابل share باشد؟
• تحویل به P02: تصمیم دربارهٔ persistence، constraintهای UI و محدودهٔ دقیق رفتار هنوز بسته نشده است.

این نسخه عمداً نمی‌گوید دکمه، checkbox، query string یا framework چه باشد. اگر تیم بعداً راه‌حل دیگری انتخاب کند، Problem Brief هنوز معتبر می‌ماند.

سه خطای محتمل و روش ترمیم

خطا ۱: مسئله را با راه‌حل یکی می‌کنیم

«یک دکمهٔ فیلتر بساز» ممکن است یک پیشنهاد خوب باشد، اما هنوز problem statement نیست. ترمیم: راه‌حل را موقتاً حذف کنید و شکاف فعلی را بنویسید.

خطا ۲: پایان را با تولید artifact فنی یکی می‌کنیم

«وقتی PR merge شد تمام است» دربارهٔ فعالیت تیم است. ترمیم: بپرسید کاربر یا سیستم بیرونی بعد از حل چه تفاوتی را تجربه می‌کند.

خطا ۳: assumption را شبیه constraint می‌نویسیم

«باید در URL ذخیره شود» بدون authority ممکن است فقط یک حدس باشد. ترمیم: منبع را نشان دهید؛ اگر ندارید، آن را assumption/unknown نگه دارید و به مرحلهٔ مناسب تحویل دهید.

قاعدهٔ مشترک: سرعت، اجازهٔ پنهان‌کردن ابهام نیست. یک unknown صریح از یک requirement خیالی قابل‌اعتمادتر است.

پل مسیر باتجربه: وقتی درخواست‌ها متناقض‌اند

در کار واقعی، مشکل همیشه «اطلاعات کم» نیست؛ گاهی evidenceها با هم نمی‌خوانند. برای مسیر باتجربه، این وضعیت را در نظر بگیرید:

• ticket می‌گوید «فقط کارهای ناتمام»؛
• اسکرین‌شات قدیمی سه حالت نشان می‌دهد؛
• یک پیام تیمی از «حفظ فیلتر» حرف می‌زند اما مشخص نیست هنوز معتبر است.

کار شما حل‌کردن تناقض با حدس نیست. Problem Brief باید آنچه معتبر است را fact نگه دارد، موارد بی‌authority را assumption/unknown کند و مشخص کند چه سؤال‌هایی قبل از تصمیم‌های P02 نیاز به پاسخ دارند. اگر evidence کافی نیست، artifact می‌تواند با unknown صریح باقی بماند؛ اطمینان ساختگی ممنوع است.

چه چیزی را حالا می‌بندیم و چه چیزی را نه؟

دو افراط رایج است: یا فوراً وارد implementation می‌شویم، یا آن‌قدر specification می‌نویسیم که قبل از فهم مسئله، همهٔ تصمیم‌های بعدی را تصاحب می‌کنیم.

در این درس فقط سه تصمیم اطلاعاتی بسته می‌شوند: تعریف شکاف، تعریف outcome بیرونی، و وضعیت fact/assumption/unknown. این محدودیت یک trade-off عمدی است: artifact سریع و قابل بازبینی می‌ماند و در عین حال مانع می‌شود راه‌حل زودتر از مسئله تثبیت شود.

اگر برای پاسخ‌دادن به «چه چیزی باید رخ دهد؟» ناچار شدید scope، constraints یا non-goals را تعیین کنید، آن سؤال را برای P02 باز نگه دارید. اگر بحث به معیار قبولی/acceptance criteria رسید، آن را صرفاً به‌عنوان تصمیم downstream باز ثبت کنید؛ نه اینجا قطعی کنید و نه مالکیتش را به P02 نسبت دهید.

تمرین هدایت‌شده و مستقل

تمرین هدایت‌شده

یک فروشگاه داخلی می‌گوید: «در سفارش‌ها search بگذار.» اطلاعات موجود: اپراتورها برای پیداکردن سفارش مشخص بین صفحات حرکت می‌کنند؛ شمارهٔ سفارش در داده وجود دارد؛ معلوم نیست جست‌وجو باید نام مشتری، شمارهٔ سفارش یا هر دو را پوشش دهد.

یک Problem Brief v1 بنویسید. راه‌حل UI را انتخاب نکنید. حداقل یک fact، یک assumption یا unknown و یک نتیجهٔ بیرونی ثبت کنید.

تمرین مستقل — مقصد Fast Path

در یک سامانهٔ آموزشی، کاربران بعد از upload تکلیف گاهی دوباره فایل را می‌فرستند چون نمی‌دانند upload اول موفق بوده است. یک نفر پیشنهاد می‌دهد «progress bar اضافه کنیم». دادهٔ موجود فقط این است که duplicate upload در گزارش پشتیبانی دیده شده و سامانه بعد از پایان upload پیام موفقیت نشان می‌دهد؛ زمان نمایش/وضوح آن بررسی نشده است.

بدون استفاده از wording کیس task-list، Problem Brief v1 بسازید و در پایان سه چیز را جدا کنید: آنچه این درس باید روشن کند، سؤال‌های scope/constraints/non-goals که برای FND-001-P02 باز می‌مانند، و هر سؤال acceptance که فقط به‌عنوان تصمیم downstream باز می‌ماند و به P02 نسبت داده نمی‌شود.

چطور بفهمیم artifact کافی است؟

قبل از عبور، چهار سؤال را بررسی کنید:

1. بسته‌شدن مفاهیم: آیا هر سه مفهوم در artifact دیده می‌شوند و با هم اشتباه نشده‌اند؟
2. قابلیت قضاوت مستقل: آیا یک reviewer بدون دیدن کد می‌تواند بفهمد مشکل چیست و چه outcome بیرونی انتظار می‌رود؟
3. مرز همسایه: آیا scope/constraints/non-goals را به‌جای P02 بسته‌اید؟ آیا acceptance criteria را هم در P01 بسته‌اید یا بدون authority به P02 نسبت داده‌اید؟
4. مالکیت انسانی: آیا هر تصمیم مهم traceable است یا unknown بودنش صریح مانده؟ AI نباید authority نهایی شده باشد.

شرط prerequisite نیز دوباره اعمال می‌شود: اگر هنگام دفاع از factها نمی‌توانید بگویید evidence از کجا آمده یا چه چیزی فقط assumption است، repair مربوط به ORI-006 لازم است.

خروجی این درس «کد» نیست. evidence معتبر، Problem Brief v1 + توضیح مرز + یک تصمیم انسانی قابل دفاع است.

ارزیابی و انتقال

ارزیابی پنج بخش دارد: یادآوریِ یک تمایز، ساخت artifact در کیس تازه، تشخیص یک artifact خراب، تصمیم دربارهٔ پیشنهاد مبهم AI و انتقال به domain جدید. سؤال‌های blocking فقط وقتی پاس می‌شوند که artifact و rationale قابل بررسی باشند؛ انتخاب گزینه بدون evidence کافی نیست.

برای انتقال، همان سه invariant را نگه دارید اما wording کیس مشترک را کپی نکنید: شکاف روشن، outcome بیرونی، و وضعیت fact/assumption/unknown. سپس فقط سؤال‌های scope/constraints/non-goals را به FND-001-P02 تحویل دهید؛ acceptance criteria را اگر مطرح شد، به‌عنوان تصمیم downstream باز نگه دارید و صریحاً به P02 نسبت ندهید.

منابع و تازگی

مفاهیم اصلی این درس از authority داخلی قفل‌شدهٔ curriculum می‌آیند؛ استاندارد یا vendor بیرونی تعریف‌کنندهٔ قالب MAKNOW نیست.

برای زمینهٔ requirements engineering، وضعیت ISO/IEC/IEEE 29148 در ۵ سپتامبر ۲۰۲۶ دوباره بررسی شد: نسخهٔ ۲۰۱۸ همچنان استاندارد منتشرشده است و در وضعیت «to be revised» قرار دارد؛ پیش‌نویس Edition 3 در مرحلهٔ DIS در حال توسعه است و هنوز جایگزین نسخهٔ ۲۰۱۸ نشده است. این وضعیت ممکن است تغییر کند و قبل از انتشار/بازاعتبارسنجی آینده باید دوباره بررسی شود.

این درس ادعای جاری دربارهٔ workflow یک محصول AI خاص ندارد؛ بنابراین مستندات زندهٔ Codex/Copilot/Claude به‌عنوان authority برای تصمیم‌های learner استفاده نشده‌اند. اگر در نسخهٔ آینده claim محصولی وارد متن شود، همان claim باید با منبع رسمی و تاریخ بازیابی تازه bind شود.