تعامل با ایجنت‌های کدنویسی اغلب در دو تله‌ی بزرگ گرفتار می‌شود: یا تسک‌ها آن‌قدر کلی و مبهم تعریف می‌شوند که مدل ناچار است کلیت معماری و رفتار سیستم را حدس بزند، یا آن‌قدر جزئیات ریز و دیکته‌شده دارند که ایجنت عملاً به یک ماشین تایپ برای سناریوهای منسوخ بدل می‌شود. این شیوه هزینه‌ی بازبینی کد را بالا می‌برد و مزیت استفاده از مدل‌های زبانی را از بین می‌برد.
راهکار پایدار، نوشتن مشخصات فنی در قالب یک قرارداد اجرایی است. در این شیوه، شواهد اعتبارسنجی و قواعد نقض‌ناپذیر سیستم را شفاف و قفل می‌کنید، اما تصمیم‌های خرد، کم‌هزینه و بازگشت‌پذیر را آگاهانه به خود ایجنت واگذار می‌نمایید. نتیجه این رویکرد، تولید کدی باکیفیت‌تر، قابل‌تکرار و همراه با آزمون‌های دقیق است.
یک مشخصات فنی کارآمد، پایدارها و شواهد را تثبیت میکند و در عین حال دست ایجنت را برای تصمیم‌های پیاده‌سازیِ بازگشت‌پذیر باز می‌گذارد. مشخصات فنی یک مرز تصمیمگیری است، نه فیلم‌نامه.
اهداف یادگیری
- تفکیک خروجی، پایدارها، نمونهها، اهداف نامربوط و اثبات.
- دسته‌بندی تصمیم‌ها به حالتهای قفلشده، محدودشده یا واگذارشده.
- حفظ قدرت تصمیمگیری ایجنت در مواردی که انتخاب‌ها کم‌هزینه و بازگشت‌پذیرند.
- الزام چک‌پوینت‌های انسانی در صورت تغییر رفتارهای عمومی سیستم یا پیامدها.
دو سر طیف نامطلوب
وقتی تسک را کم‌تر از حد مشخص کنید، ایجنت ناچار می‌شود سیستم را حدس بزند. وقتی تسک را بیش از حد مشخص کنید، از آن می‌خواهید طرحی را عیناً پیاده کند که شاید از ابتدا هم اشتباه بوده است.
نقطه‌ی تعادل کارآمد، یک قرارداد اجرایی است:
| سطح قرارداد | هدف |
|---|---|
| خروجی (Outcome) | نتیجه‌ی قابل‌مشاهده |
| پایدارها (Invariants) | شرط‌هایی که همیشه باید برقرار بمانند |
| نمونهها (Examples) | حالتهای ملموس برای شفاف‌کردن نیت |
| اهداف نامربوط (Non-goals) | رفتارهای هم‌جواری که عمداً کنار گذاشته شده‌اند |
| سیاست تصمیمگیری (Decision policy) | تعیین نوع تصمیم‌ها: قفلشده، محدودشده یا واگذارشده |
| اثبات (Proof) | شواهد لازم پیش از اعلام اتمام کار |
سه حالت تصمیمگیری
- قفلشده (Locked): ایجنت حق انتخاب ندارد. این حالت را برای سازگاری عمومی، اختیارات، امنیت، هزینه‌های بازگشت‌ناپذیر یا تعهدات محصول به کار ببرید.
- محدودشده (Bounded): ایجنت فقط در چارچوب محدودیت‌های صریح حق انتخاب دارد. این حالت را برای سقف بودجه‌ی جست‌وجو، تعداد تلاش‌های مجدد، وابستگی‌های مجاز یا مجموعه‌ای مشخص از رابط‌ها به کار ببرید.
- واگذارشده (Delegated): تصمیمگیری کاملاً بر عهدهی ایجنت است و باید دلیل انتخابش را توضیح دهد. این حالت را برای ساختار محلی کد، نام‌گذاری‌ها، بازآرایی‌های بازگشت‌پذیر و جزئیات پیاده‌سازی به کار ببرید.
مشخص‌کردن رفتار از طریق نمونهها
نمونهها نیت را بسیار بهتر از صفت‌ها فشرده و منتقل می‌کنند. واژه‌هایی مثل «مفید»، «مقاوم» و «آماده‌ی محیط پروداکشن» جنبه‌ی اجرایی ندارند. ارائه‌ی مجموعه‌ی کوچکی از نمونه‌های عادی، مرزی، شکست و ممنوع، مبنایی ملموس در اختیار سازنده و مدل اعتبارسنج می‌گذارد.
البته نمونهها جایگزین پایدارها نمی‌شوند؛ موفقیت در یک سناریو هرگز نمی‌تواند یک قاعدهی ایمنی کلی را اثبات کند.
تناسب شواهد با ادعا
- تست واحد (Unit test) قرارداد یک تابع محلی را اثبات میکند.
- تست سیم (Wire test) رفتار سریال‌سازی و بستر انتقال را اثبات میکند.
- مسیر مرورگر (Browser journey) مسیر تعامل با رابط کاربری را اثبات میکند.
- مجموعه‌ی بازپخش (Replay set) رفتار سیستم را در نمونه‌های شاخص نشان می‌دهد.
- لاگ بازرسی (Audit log) اثبات میکند که مرزهای اختیارات حفظ شده‌اند.
هرگز شواهد لایه‌های پایین‌تر را به‌عنوان اثبات ادعاهای لایه‌های بالاتر قبول نکنید.
حفظ آگاهانه‌ی نادانسته‌ها
اگر در مشخصات فنی بنویسید «پیاده‌سازی می‌تواند از هر منبع فقط‌خواندنی که در سقف زمانی پاسخ دهد استفاده کند»، این کار ابهام نیست؛ بلکه یک تصمیم واگذارشده‌ی آگاهانه است که مرز و روش اثبات مشخصی دارد.
مشخصات فنی باید هم‌گام با تغییر شواهد تکامل یابند. دلیلِ پشت تصمیم‌های قفلشده و محدودشده را ثبت کنید تا تیم‌های بعدی بتوانند بدون باستان‌شناسی، آن‌ها را بازنگری کنند.
پیاده‌سازی
این آزمایشگاه تک‌تک سطوح قرارداد را اعتبارسنجی میکند، حالتهای تصمیمگیری را می‌سنجد و فایل outputs/executable-specification.json را خروجی می‌دهد.
python3 code/main.py
python3 -m unittest discover code/tests -vتصمیم نوشتن روی پروداکشن را از حالت قفلشده به واگذارشده تغییر دهید. توضیح دهید که چرا این مقدار از نظر اسکیمای داده معتبر است اما از دید ریسک محصول پذیرفتنی نیست.
تمرین‌ها
- یکی از تیکت‌های بک‌لاگ را به این شش سطحِ مشخصات فنی تبدیل کنید.
- سه دستور پیاده‌سازی را حذف و به‌جای آن‌ها یک پایدار و دو نمونه جایگزین کنید.
- همه‌ی تصمیم‌ها را دسته‌بندی کنید و دلیل هر انتخاب قفلشده یا محدودشده را بیاورید.
- برای هر پایدار، یک رسید اثبات تعیین کنید.
- قیدی را که فاقد شواهد یا توجیه منطقی ریسک است حذف کنید.
برای مطالعه‌ی بیشتر
- مقاله‌ی Nuseibeh and Easterbrook, Requirements Engineering: A Roadmap برای بررسی ارتباط میان اهداف، مشخصات فنی دقیق، اعتبارسنجی، توافق و تکامل سیستم.
- مقاله‌ی Zave and Jackson, Four Dark Corners of Requirements Engineering برای تفکیک فرضیات محیطی، نیازمندی‌ها و مشخصات فنی.
- مقاله‌ی Gotel and Finkelstein, An Analysis of the Requirements Traceability Problem برای حفظ علت وجود نیازمندی‌ها و منشأ آن‌ها.
چه چیزی برایتان می‌ماند
فایل outputs/executable-specification.json را نگه دارید. این فایل به همان قراردادی تبدیل می‌شود که ایجنت‌های کدنویسی و بازبین‌های انسانی بر سر آن اشتراک دارند.