یکی از رایج‌ترین مشکلات هنگام کار با ایجنتهای کدنویسی، تکیه بر فهرستهای ساده و خطی برای انجام کارهاست؛ برنامه‌هایی که صرفاً درخواست اولیه را با جملاتی کلی مثل «API را تغییر بده» تکرار می‌کنند. این رویکرد معمولاً به دوباره‌کاری، تغییرات پیش‌بینی‌نشده در قراردادهای برنامه و اتلاف زمان منجر میشود، زیرا هیچ ارجاعی به واقعیت‌های درون مخزن کد ندارد.
در این درس یاد می‌گیرید که چگونه یک برنامه را به‌جای فهرست متنی، به شکل یک گراف وابستگی مبتنی بر شواهد (Evidence-backed execution plan) مدل‌سازی کنید. با این روش، هر گام دلیل مشخصی در کد دارد، پیش‌نیازهای دقیق آن تعیین میشود و تا زمانی که اثباتِ پایان کار ارائه نشود، گام‌های وابسته اجرا نخواهند شد.
این رویکرد ساختاریافته کمک میکند تا وظایف موازی به‌درستی تفکیک شوند و در صورت قطع غیرمنتظره‌ی نشست کاری ایجنت، بتوان بدون گم‌کردن وضعیت پیشرفت، پروژه را دقیقاً از نقطه‌ی امن بعدی ادامه داد.
برنامه یک فهرست کارهای قشنگ‌تر نیست؛ یک گراف وابستگی است که در آن هر تغییر دلیلی دارد و هر گره پایانی اثباتی.
اهداف یادگیری
- تبدیل چارچوب مسئله به وظایف کاری همراه با شواهد (Evidence) و اثبات.
- مدل‌سازی اولویت اجرا به شکل وابستگیها، به‌جای توالی متنی ساده.
- شناسایی واقعیت‌های نامشخص، وابستگی‌های ناشناخته و چرخه‌ها پیش از ویرایش فایلها.
- تفکیک گام‌هایی که می‌توانند همزمان اجرا شوند از گام‌هایی که حتماً باید منتظر بمانند.
چرا برنامه‌های ایجنت‌ها شکست می‌خورند
برنامه‌های ضعیف صرفاً درخواست اولیه را در زمان آینده تکرار می‌کنند:
- API را به‌روزرسانی کن.
- تست‌ها را اضافه کن.
- مستندات را به‌روزرسانی کن.
در این فهرست هیچ‌چیز نمی‌گوید چه چیزهایی در مخزن پیدا شده، چرا دقیقاً همین فایلها درست هستند، کدام قرارداد اول تغییر میکند یا چه کارهایی می‌توانند همزمان انجام شوند. ایجنت (Agent) می‌تواند تک‌تک این گام‌ها را اجرا کند و با این حال کار دوباره روی دستتان بگذارد.
یک برنامه‌ی قوی، برای هر وظیفهی کاری 5 تعهد مشخص ایجاد میکند:
| تعهد | هدف |
|---|---|
| شناسه | مرجع یکتا و ثابت برای وابستگیها و تحویل کار |
| تغییر | کوچکترین تغییر ممکن در رفتار یا قرارداد |
| شواهد | واقعیت‌های کشفشده در مخزن که تغییر را توجیه می‌کنند |
| وابستگیها | کارهایی که حتماً باید اول محقق شده باشند |
| اثبات | اعتبارسنجی دقیقی که باعث بسته شدن کار میشود |
پیش از پیاده‌سازی، قرارداد را مشخص کنید
وقتی چند بخشِ مختلف به یک رفتار معین وابسته‌اند، اول همان رفتار را تعریف کنید. با این کار، تست‌ها، پیاده‌سازی، مستندات و تست‌های یکپارچه‌سازی می‌توانند از یک قرارداد واحد استفاده کنند، نه اینکه هرکدام نسخه‌ی ساختگی خودش را بسازد.
این گراف، امکان اجرای هم‌زمانِ امن را نشان می‌دهد. بعد از تثبیت قرارداد، پیاده‌سازی و مستندسازی می‌توانند دوشادوش هم پیش بروند. بخش یکپارچه‌سازی منتظر هر دوی آن‌ها می‌ماند.
شواهد، مسیر برنامه را تغییر می‌دهند
شواهد مخزن صرفاً جنبه‌ی تزئینی ندارند؛ باید بتوانند دامنه‌ی کار را تغییر دهند:
- وجود یک تابع کمکی آماده، نیاز به ساخت یک ساختار انتزاعی جدید را حذف میکند.
- نتیجه‌ی یک تست سازگاری، یک گام مهاجرت (Migration) تحمیل میکند.
- محدودیت‌های استقرار (Deployment)، تغییرِ اسکیما را به کار دیگری منتقل میکند.
- شکل تایپ پاسخ عمومی، ترتیب پیاده‌سازی و مستندسازی را عوض میکند.
اگر شواهد نتوانند برنامه را تغییر دهند، احتمالاً اصلاً شواهدی مرتبط با آن تصمیم نبوده‌اند.
طراحی برای وقفه
جلسات ایجنتهای کدنویسی بدون هشدار قبلی قطع می‌شوند. برنامه‌ای که قابلیت ادامه‌یافتن بعد از وقفه (Interrupt) را دارد، وظایف کاری را آن‌قدر ریز خرد میکند که یک نشست دیگر بتواند موارد زیر را مشخص کند:
- کدام وظیفه تمام شده است؛
- کدام اثبات اجرا شده است؛
- کدام دست‌سازه‌ها (Artifacts) تغییر کرده‌اند؛
- کدام وابستگیها اکنون آزاد شده‌اند؛
- کار امن بعدی چیست.
وضعیت پیشرفت را فقط داخل چک‌باکس‌های محیط چت نگه ندارید. برنامه را کنار خودِ کار ذخیره کنید.
اعتبارسنجی برنامه
پیش از شروع اجرا، اگر هرکدام از این شرایط برقرار بود برنامه را رد کنید:
- شناسه‌ای تکراری باشد؛
- وظیفه‌ای هیچ شواهدی نداشته باشد؛
- وظیفه‌ای هیچ اثباتی نداشته باشد؛
- در بخش وابستگیها، نام وظیفه‌ای ناشناخته آمده باشد؛
- گراف دارای چرخه باشد؛
- اولین اقدام بازگشتناپذیر پیش از رفع ابهام مربوطه رخ دهد.
5 مورد اول مکانیکی هستند. مورد آخر نیازمند قضاوت است و باید صراحتاً بیان شود.
ساخت آن
فایل code/main.py وظایف کاری را مدل‌سازی میکند، مدارک اثبات آن‌ها را اعتبارسنجی میکند، با مرتب‌سازی توپولوژیک (Topological Sort) امواج اجرا را به‌دست می‌آورد و خروجی را در outputs/evidence-plan.json می‌نویسد.
اجرا کنید:
python3 code/main.py
python3 -m unittest discover code/tests -vاین مثال سه موج تولید میکند. تعریف قرارداد اول اجرا میشود. پیاده‌سازی و مستندسازی با هم پیش می‌روند. گیت یکپارچه‌سازی در آخر کار اجرا میشود.
استفاده از آن با ایجنت کدنویسی
پیش از آنکه ایجنت فایلها را تغییر دهد، از او بخواهید برنامه را آماده کند. برنامه را با بررسی این سه معیار بازبینی کنید:
- هر مسیر و هر ادعای رفتاری، مدرکی در مخزن داشته باشد.
- هر وظیفه یک روش اثباتِ پایان مشخص و شفاف داشته باشد.
- گراف، کارهای پرهزینه یا بازگشتناپذیر را تا زمان رفع ابهامی که به آن وابسته‌اند به تعویق بیندازد.
برنامه را تایید کنید، نه وعده‌ی مبهمِ «حواسم هست» را.
تمرین‌ها
- یک کار مهاجرت اضافه کنید که نیازمند تایید صریح انسان باشد.
- یک چرخه بسازید و اختلاف‌نظر محصولی پنهان پشت آن را توضیح دهید.
- وظیفه‌ای را که دو دستور اثبات دارد به دو وظیفه خرد کنید.
- یک وظیفهی کاری اضافه کنید که بتواند در موج دوم اجرا شود، بدون اینکه به هیچ‌کدام از branchهای موجود دست بزند.
- خروجی برنامه را در قالب Markdown رندر کنید، درحالی‌که ساختار JSON همچنان منبع اصلی حقیقت بماند.
مطالعه‌ی بیشتر
- Nuseibeh and Easterbrook, Requirements Engineering: A Roadmap، برای درک رابطه‌ی رفت‌وبرگشتی میان اهداف، مشخصات فنی، توافقات و تکامل سیستم.
- Barry Boehm, A Spiral Model of Software Development and Enhancement، برای سازمان‌دهی مراحل توسعه حول محور رفع ریسک، به‌جای تکیه بر توالی خطیِ صلب.
دستاورد شما
فایل outputs/evidence-plan.json را نگه دارید. این فایل در درس بعدی قرارداد واگذاری کار خواهد بود.