توسعه‌دهندگان هنگام کار با ابزارهای هوش مصنوعی و مدل‌های زبانی بزرگ، مدام با ادعاهایی درباره‌ی هوشمندی مدل‌ها روبه‌رو می‌شوند؛ اما در محیط کار واقعی، مدل‌هایی که صرفاً با یک پرامپت رها می‌شوند، کدهای خارج از دامنه تولید می‌کنند، تستها را دور می‌زنند و پروژه‌ها را به شکست می‌کشانند. مسئله‌ی اساسی امروز ما مهندسی محیط یا بستری است که ایجنت در آن کار می‌کند، نه صرفاً تغییر مدل پشت صحنه.
در این درس تمام اجزای میز کار ایجنت (Workbench) را که در درس‌های گذشته ساختیم، وارد یک ریپازیتوری شبیه به کدهای واقعی روزمره می‌کنیم. با اجرای یک تسک واحد به دو روشِ «فقط پرامپت» و «هدایت‌شده با میز کار»، خروجی‌ها را با متریک‌های مشخص اندازه می‌گیریم تا ببینیم مرزبندی‌های مهندسی چگونه جلوی خطاهای خاموش نرم‌افزار را می‌گیرند.
یازده درس درباره‌ی سطوح میز کار (workbench surfaces)، اگر در مواجهه با یک بیس‌کد واقعی دوام نیاورند، هیچ ارزشی ندارند. در این درس، یک تسک مشخص را دو بار روی یک برنامه‌ی نمونه‌ی کوچک اجرا می‌کنیم: یک بار فقط با پرامپت (prompt-only) و بار دیگر با هدایت میز کار (workbench-guided). اعداد خودشان صحبت خواهند کرد.
اهداف یادگیری
- به‌کارگیری هم‌زمان هر هفت سطح میز کار روی یک برنامه‌ی کوچک.
- اجرای یک تسک مشخص به دو روش (فقط با پرامپت و با هدایت میز کار) و سنجش پنج خروجی کلیدی.
- بررسی گزارش «قبل/بعد» و تشخیص این‌که کدام سطوح بیشترین اهرم اثرگذاری را فراهم کرده‌اند.
- دفاع از میز کار در برابر مخالفت‌هایی از این دست که «مدل من به اندازه‌ی کافی خوب است».
مسئله
دمو روی تسکهای بازیچه هیچ‌کس را متقاعد نمی‌کند. فایده‌ی میز کار زمانی اثبات می‌شود که یک تسک ملموس روی یک ریپازیتوری واقعی با شکست‌های کمتر، بازگردانی‌های (reverts) کمتر و بسته‌ای تحویل پروداکشن شود که نشست بعدی بتواند از آن استفاده کند.
این درس چنین ریپازیتوری ملموسی را در اختیارتان می‌گذارد و تسک مشابهی را از هر دو پایپ‌لاین عبور می‌دهد. نتیجه، گزارش «قبل/بعد» مستندی خواهد بود که می‌توانید دست هر فرد مرددی بدهید.
مفاهیم پایه
برنامه‌ی نمونه
یک هندلر مینیمال به سبک FastAPI در مسیر sample_app/:
- فایل
app.pyهمراه با اندپوینت/signup(هنوز بدون اعتبارسنجی). - فایل
test_app.pyبا یک تست مسیر ایده‌آل (happy-path). - فایل‌های
README.mdوscripts/release.shبه‌عنوان طعمه‌هایی در منطقه‌ی ممنوعه.
صورت تسک
اعتبارسنجی ورودی را به اندپوینت
/signupاضافه کنید: رمزهای عبور کوتاه‌تر از 8 کاراکتر رد شوند و پاسخ 422 همراه با یک پوشش خطای ساختاریافته (typed error envelope) برگردد. تستی بنویسید که درستی این رفتار جدید را اثبات کند.
دو پایپ‌لاین
فقط با پرامپت:
- خواندن README.
- خواندن
app.py. - ویرایش فایل‌ها.
- ادعای اتمام کار.
با هدایت میز کار:
- اجرای اسکریپت راه‌اندازی (درس 35).
- خواندن قرارداد دامنه (scope contract) (درس 36).
- خواندن وضعیت (درس 34).
- ویرایشِ صرفاً فایل‌های مجاز.
- اجرای دستور پذیرش از طریق مجری بازخورد (درس 37).
- اجرای دروازه‌ی اعتبارسنجی (verification gate) (درس 38).
- اجرای بازبین (درس 39).
- تولید بستهی تحویل (handoff) (درس 40).
پنج خروجی سنجیده‌شده
| خروجی | دلیل اهمیت |
|---|---|
tests_actually_run |
ادعای «تستها پاس شدند» در اغلب مواقع قابل راستی‌آزمایی نیست |
acceptance_met |
تستی که اثبات‌کننده‌ی هدف است، باید دقیقاً همان تستی باشد که اجرا شده |
files_outside_scope |
خزش دامنه (Scope creep) مهم‌ترین شکست خاموش سیستم‌ها است |
handoff_quality |
نشست بعدی هزینه‌ی این خروجی را می‌دهد یا از مزایای آن بهره‌مند می‌شود |
reviewer_total |
قضاوت کیفی علاوه بر بررسی دروازه |
پیاده‌سازی
اسکریپت code/main.py هر دو پایپ‌لاین را روی فیکسچر برنامه‌ی نمونه اجرا و مدیریت می‌کند. هر دو پایپ‌لاین اسکریپت‌نویسی شده‌اند (بدون حضور LLM در حلقه) تا نتایج سنجش کاملاً تکرارپذیر باشند. این اسکریپت مقایسه‌ی نهایی را در دو فایل before-after-report.md و comparison.json می‌نویسد.
اجرای آن:
python3 code/main.pyخروجی: جدولی در کنسول از خروجی‌های هر پایپ‌لاین، گزارش Markdown ذخیره‌شده در کنار اسکریپت، و فایل JSON برای هرکسی که بخواهد نمودار آن را رسم کند.
الگوهای پروداکشن در دنیای واقعی
سؤال افراد شکاک این است: «میز کار عملاً چقدر کمک می‌کند؟» آمار و ارقام سال 2026 بسیار گویاتر از هر توضیحی هستند.
صعود از رتبه‌ی خارج از 30 به رتبه‌ی 5 در Terminal Bench با همان مدل. مقاله‌ی کالبدشناسی بستر آزمایشی ایجنت از LangChain (آوریل 2026): یک ایجنت کدنویسی تنها با تغییر بستر آزمایشی (harness)، از رتبه‌ای خارج از 30 تیم اول به رتبه‌ی 5 در Terminal Bench 2.0 رسید. مدل همان بود؛ سطوح تغییر کردند. بیست‌وپنج رتبه جابه‌جایی خالص.
رسیدن Vercel از 80٪ به 100٪ تنها با حذف ابزارها. Vercel گزارش داد که حذف 80٪ از ابزارهای ایجنت، نرخ موفقیت آن را از 80٪ به 100٪ رساند. سطح ابزار کوچک‌تر، دامنه‌ی دقیق‌تر، و مسیرهای کمتری برای خطا. فضای منفی برنده می‌شود.
دو برابر شدن دقت Harvey صرفاً از طریق بستر آزمایشی. ایجنت‌های حقوقی این مجموعه بدون هیچ تغییری در مدل و صرفاً با بهینه‌سازی بستر آزمایشی، دقت خود را بیش از دو برابر کردند.
88٪ از پروژه‌های ایجنت هوش مصنوعی سازمانی هرگز به پروداکشن نمی‌رسند. مقاله‌ی مهندسی بستر آزمایشی برای ایجنت‌های زبانی در preprints.org (مارس 2026) ریشه‌ی این شکست‌ها را در محیط اجرا (Runtime) می‌داند، نه در قدرت استدلال مدل: وضعیت‌های منسوخ، تلاش‌های مجدد شکننده، کانتکست‌های بیش از حد متورم، و بازیابی ضعیف از خطاهای میانی.
فروپاشی در کانتکست‌های طولانی (Long-context collapse). نرخ موفقیت پایه‌ی WebAgent از 40-50٪ در شرایط کانتکست طولانی به زیر 10٪ سقوط می‌کند؛ عمدتاً به دلیل افتادن در حلقه‌های بی‌نهایت و فراموشی هدف. حلقه‌ی Ralph Loop و بستهی تحویل دست‌به‌دست دقیقاً برای مهار همین بحران طراحی شده‌اند.
موارد منفی کاذب (False negatives) همچنان وجود دارند. تسکهای واقعی تکمرحلهای، لینت‌های یک‌خطی، اجرای فرمت‌کننده‌ها و هر چیزی که مدل عیناً حفظ کرده است — این موارد فقط با پرامپت سریعتر انجام می‌شوند. بنچ‌مارک باید با صداقت این تسک‌ها را فهرست کند تا میز کار به‌اشتباه کاری اضافه و بیهوده تلقی نشود.
نتیجه‌گیری این نیست که «بستر آزمایشی همیشه برنده است». مدل‌ها با گذشت زمان ترفندهای بستر آزمایشی را در خود حل می‌کنند. پیام اصلی این است که امروز، بار اصلی مهندسی روی دوش همین هفت سطح قرار دارد و داده‌ها هم این را اثبات می‌کنند.
استفاده‌ی عملی
این درس، همان پرونده‌ی مستندی است که می‌توانید به آن استناد کنید وقتی:
- کسی می‌پرسد چرا هر PR باید یک
agent-rules.mdو یک قرارداد دامنه همراه داشته باشد. - تیمی می‌خواهد «فقط برای این اسپرینت» دروازه‌ی اعتبارسنجی را کنار بگذارد.
- محصول ایجنت جدیدی معرفی می‌شود و شما به یک بنچ‌مارک قابل‌حمل نیاز دارید تا بسنجید آیا واقعاً در زمان صرفه‌جویی می‌کند یا نه.
اعداد خیلی رساتر از کلمات حرف می‌زنند.
تحویل نهایی
فایل outputs/skill-workbench-benchmark.md یک بستر ارزیابی (evaluation harness) قابل‌حمل است که هر محصول ایجنتی را در هر دو پایپ‌لاین روی برنامه‌ی نمونه‌ی خودِ پروژه تست می‌کند و پنج خروجی کلیدی را گزارش می‌دهد.
تمرین‌ها
- یک خروجی ششم اضافه کنید: زمان تا اولین ویرایش معنادار. چطور می‌توان آن را شفاف و تمیز اندازه گرفت؟
- این مقایسه را روی یک تسک واقعیِ «روز دوم» در بیس‌کد خودتان اجرا کنید. اعداد میز کار در چه نقطه‌ای افت می‌کنند؟
- یک مرحله‌ی بررسی «منفی کاذب» اضافه کنید: تسک‌هایی که فقط با پرامپت سریعتر انجام می‌شدند و سربار میز کار هزینه‌ی واقعی بوده است. با این حال، از نگه‌داشتن میز کار دفاع کنید.
- «ایجنت» اسکریپتی را با یک فراخوانی واقعی LLM جایگزین کنید. کدام خروجی‌ها نویز بیشتری پیدا می‌کنند؟
- خلاصه‌ای تک‌صفحه‌ای برای یک فرد غیرفنی بنویسید. چه نکاتی پس از خلاصه کردن جان سالم به در می‌برند؟
اصطلاحات کلیدی
| اصطلاح | آنچه دیگران می‌گویند | معنای واقعی آن |
|---|---|---|
| برنامه‌ی نمونه (Sample app) | «ریپوی اسباب‌بازی» | به اندازه‌ی کافی کوچک اما واقع‌گرایانه برای به‌کارگیری هر هفت سطح |
| پایپ‌لاین (Pipeline) | «گردش کار» | توالی منظمی از خواندن و نوشتن روی سطوح که ایجنت دنبال می‌کند |
| گزارش قبل/بعد (Before/after report) | «فاکتور و سند اثبات» | دست‌سازه‌ای (artifact) که به فرد مردد نشان می‌دهید |
| منفی کاذب (False negative) | «سربار بیهوده‌ی میز کار» | تسک‌هایی که فقط با پرامپت سریعتر پیش می‌روند؛ فهرست کردن صادقانه‌ی آنها مفید است |
| بنچ‌مارک میز کار (Workbench benchmark) | «امتیاز قابلیت اطمینان» | بستر آزمایشی قابل‌حملی که این مقایسه را روی بیس‌کد خودتان اجرا می‌کند |
برای مطالعه‌ی بیشتر
- LangChain, The Anatomy of an Agent Harness — مستند صعود از جمع 30 تیم اول به رتبه‌ی 5 در Terminal Bench
- MongoDB, The Agent Harness: Why the LLM Is the Smallest Part of Your Agent System — آمارهای مربوط به Vercel و Harvey
- preprints.org, Harness Engineering for Language Agents — نرخ شکست 88 درصدی پروژه‌های سازمانی و ریشه‌های آن در محیط اجرا
- HN: Improving 15 LLMs at Coding in One Afternoon. Only the Harness Changed — بازتولید نتایج روی 15 مدل مختلف
- Cloudflare, Orchestrating AI Code Review at Scale — اجرای 131 هزار بازبینی کد در 30 روز در محیط پروداکشن
- Anthropic, Building Effective Agents
- فازهای 14 · 32 تا 14 · 40 — سطوحی که این درس آنها را به‌صورت سرتاسری (end-to-end) تمرین می‌دهد
- فاز 14 · 19 — بنچ‌مارک‌های کلان SWE-bench ،GAIA و AgentBench که این درس مکمل آن‌هاست
- فاز 14 · 30 — توسعه‌ی ایجنت مبتنی بر ارزیابی که همین بستر آزمایشی به آن متصل می‌شود