سپردن وظایف برنامه‌نویسی به ایجنت‌های هوش مصنوعی (Coding Agents) معمولاً با سرعتی باورنکردنی انجام میشود؛ اما سرعت بالا همیشه به معنای خروجی درست نیست. وقتی یک درخواست کلی مانند «اعتبارسنجی ورودی را اضافه کن» را به یک مدل تحویل می‌دهید، ایجنت خلاءهای موجود در تعریف مسئله را با حدس‌های منطقی اما شاید کاملاً اشتباه پر می‌کند. نتیجه کدی تمیز و دارای تست است که در عمل با ساختار و قراردادهای معماری مخزن شما ناسازگار است.
حل این چالش نیازمند تغییر نقطه‌ی شروع کار است: نخستین گام در تعامل با ایجنت نباید ویرایش فایل باشد، بلکه باید تدوین یک چارچوب وظیفه (Task Frame) بر پایه‌ی شواهد قطعی در مخزن کد باشد. در این درس یاد می‌گیرید که چگونه پیش از اجرای هر تغییری، مرزهای مشخصی برای مسیرهای مجاز و ممنوع، ملاک‌های دقیق پذیرش و مجهولات پروژه مشخص کنید تا جلوی هدررفت منابع و بازنویسی‌های فرسایشی گرفته شود.
یک ایجنت کدنویسی می‌تواند یک وظیفه‌ی شفاف را سریع پیاده‌سازی کند. یک وظیفه‌ی نامشخص را هم می‌تواند سریع پیاده‌سازی کند. سرعت یکسان است، ولی هزینه نه.
اهداف یادگیری
- تبدیل یک درخواست به چارچوب وظیفه‌ی محدود (Bounded task frame) پیش از ویرایش کد.
- تفکیک واقعیتهای مخزن از فرضیات و پرسش‌های باز.
- تعیین مسیرهای مجاز، مسیرهای ممنوع و شواهد پذیرش.
- تصمیمگیری درباره‌ی اینکه چه زمانی شناسایی اولیه برای شروع کار کافی است.
شکست پرهزینه
«جلوگیری از ثبت ایمیل تکراری را اضافه کن» در ظاهر دقیق به نظر می‌رسد، اما نیست. آیا یکتا بودن متعلق به API است، سرویس دامنه، یا پایگاه داده؟ آیا مقایسه حساس به بزرگی و کوچکی حروف است؟ در حال حاضر چه ساختار خطایی به‌صورت عمومی ارائه میشود؟ آیا مایگریشن (Migration) مجاز است؟ کدام تست این رفتار را اثبات می‌کند؟
یک ایجنت توانمند این فاصله‌ها را با انتخاب‌هایی باورپذیر پر می‌کند. خطر ماجرا دقیقاً همین‌جاست؛ چون پیاده‌سازی می‌تواند تمیز، تست‌شده و در عین حال با سیستم ناسازگار باشد.
بنابراین، نخستین واحد کاریِ یک ایجنت کدنویسی، دستکاری فایل نیست؛ چارچوب وظیفه‌ای است که شواهد مخزن از آن پشتیبانی می‌کند.
چارچوب وظیفه
یک چارچوب کاربردی 6 فیلد دارد:
| فیلد | پرسش |
|---|---|
| هدف | چه رفتار قابل‌مشاهده‌ای باید تغییر کند؟ |
| واقعیتهای مخزن | چه مواردی را در کد، تست‌ها، پیکربندی یا تاریخچه بررسی و تأیید کردید؟ |
| مسیرهای مجاز | تغییرات کجا اجازه دارند اعمال شوند؟ |
| مسیرهای ممنوع | چه بخش‌هایی باید دست‌نخورده باقی بمانند؟ |
| شواهد پذیرش | کدام دستورها یا مشاهدات هدف را اثبات می‌کنند؟ |
| مجهولات | کدام تصمیم‌ها هنوز به شواهد یا قضاوت انسانی نیاز دارند؟ |
واقعیت‌ها به سند نیاز دارند. ادعای «API برای موارد تکراری از 409 استفاده می‌کند» تا وقتی نتوانید به تست یا هندلر (Handler) موجود اشاره کنید، واقعیت نیست. مسیر فایل و شماره‌ی خط کافی است؛ هرچند وقتی رفتار سیستم مطرح است، نتیجه‌ی یک دستور سند بهتری است.
شناسایی اولیه یعنی جست‌وجو برای محدودیت‌ها
کل مخزن را نخوانید. فقط دنبال بخش‌هایی بگردید که دست‌انداز و محدودیت تغییر هستند:
- رفتار فعلی و فراخواننده‌ی (Caller) آن.
- نزدیک‌ترین تست موجود.
- قرارداد عمومی (Public contract) یا ساختار سریالایزشده‌ی داده.
- دستورالعمل‌های پروژه که بر آن مسیر حاکمند.
- دستورهای بیلد (Build) و اعتبارسنجی.
- تغییرات مشابه‌ی انجام‌شده که الگوهای بومی پروژه را نشان می‌دهند.
وقتی هر تصمیمِ برنامه‌ریزی‌شده یا با شواهد تأیید شد، یا صراحتاً واگذار گردید، یا در فهرست مجهولات قرار گرفت، خواندن را متوقف کنید. مطالعه‌ی بیشتر بعد از این نقطه، اغلب بهانه‌ای برای طفره رفتن از کار است.
مجهولات نشانهٔ شکست نیستند
مجهول، یک فاصلهی مهارشده است؛ فرض، پاسخی مهارنشده به آن فاصله است.
هر مجهول را دسته‌بندی کنید:
- قابل‌کشف (Discoverable): مخزن یا سیستمِ در حال اجرا می‌تواند پاسخش را بدهد.
- قابل‌تصمیم‌گیری (Decidable): قرارداد وظیفه به ایجنت اختیار انتخاب داده است.
- انسانی (Human): انتخاب ایجنت رفتار محصول، هزینه، ریسک یا سازگاری عمومی را تغییر می‌دهد.
- موکول‌شده (Deferred): انتخاب، خارج از این بخش کاری است و جزو اهداف این مرحله نیست.
ایجنت باید مجهولاتِ قابل‌کشف و تفویض‌شده را حل کند و پیش برود. اما در مواجهه با مجهولات انسانی، باید دست نگه دارد؛ پیش از آنکه تصمیم در لابه‌لای کدها دفن شود.
اثبات پذیرش پیش از پیاده‌سازی
سند اثبات را پیش از تکه (Patch) بنویسید. این اثبات می‌تواند چنین چیزهایی باشد:
- دستور اجرای یک تست واحد یا یکپارچگیِ مشخص؛
- سناریوی مرورگر (Browser journey) با ویوپورت مشخص و وضعیت موردانتظار؛
- درخواست شبکه و قرارداد دقیق پاسخ آن؛
- سنجش کارایی همراه با یک آستانه؛
- بررسی دامنه برای اطمینان از اینکه هیچ فایل نامربوطی تغییر نکرده است.
اینکه بگوییم «تست‌ها پاس می‌شوند» برنامه‌ی اثبات نیست. نام تستی را ببرید که مرجع کار است، و مشخص کنید چه ادعایی را ثابت می‌کند.
ساخت پروژه
این کارگاه یک TaskFrame می‌سازد، مرزها و شواهد آن را بررسی و اعتبارسنجی می‌کند و خروجی را در outputs/task-frame.md می‌نویسد.
از مسیر همین درس اجرا کنید:
python3 code/main.py
python3 -m unittest discover code/tests -vاین نمونه را به 4 روش خراب کنید: هدف را حذف کنید، سند یک واقعیت را بردارید، بین یک مسیر مجاز و ممنوع هم‌پوشانی بسازید، و دستور پذیرش را پاک کنید. اعتبارسنج باید هر چارچوب را به دلیلی جداگانه رد کند.
استفاده از آن در یک مخزن واقعی
پیش از آنکه از ایجنت بخواهید کدی را ویرایش کند:
- هدف را در قالب یک رفتار بنویسید، نه تغییر فایل.
- دو یا سه واقعیت را همراه با شواهد دقیق ثبت کنید.
- کوچک‌ترین مجموعه‌ی مسیرهای مجاز را مشخص کنید.
- فضای منفی (بخش‌های دست‌نخورده) را صراحتاً نام ببرید.
- دستور یا مشاهده‌ای را بنویسید که وظیفه را می‌بندد.
- تصمیم‌هایی را فهرست کنید که هنوز شواهد کافی برایشان به دست نیاورده‌اید.
این چارچوب باید در یک صفحه جا شود. اگر جا نمی‌شود، احتمالاً وظیفه‌ی شما شامل چند تغییر مستقل است که هر کدام جداگانه قابل‌تأییدند.
تمرین‌ها
- یک باگ واقعی را در یکی از مخزن‌های خودتان بدون ارائه‌ی راه‌حل چارچوب‌بندی کنید.
- ادعایی در چارچوب پیدا کنید که در واقع فقط یک فرض است؛ آن را با شواهد جایگزین کنید.
- یک مجهول انسانی اضافه کنید که پاسخش قرارداد عمومی را تغییر دهد.
- یک مسیر مجازِ گسترده را به کوچک‌ترین مجموعه‌ی امن خرد کنید.
- یک سند دامنه به شواهد پذیرش اضافه کنید.
برای مطالعه‌ی بیشتر
- نصیبه و ایستربروک، مهندسی نیازمندی‌ها: یک نقشه‌ی راه، برای متصل کردن پیاده‌سازی به اهداف دنیای واقعی و محدودیت‌های در حال تحول.
- یانگ و دیگران، SWE-agent: رابط‌های ایجنت-کامپیوتر مهندسی نرم‌افزار خودکار را ممکن می‌سازند، برای دیدن شواهدی از اینکه رابط کاربری پیرامون یک ایجنت کدنویسی چطور اثربخشی آن را تغییر می‌دهد.
خروجی این درس
فایل outputs/task-frame.md را نگه دارید. این فایل ورودی درس بعدی است؛ جایی که این چارچوب به یک برنامه‌ی اجرایی مبتنی بر شواهد تبدیل میشود.