درس 01. مدل‌های قوی به‌معنای اجرای قابل‌اعتماد نیستند | مهندسی هارنس

Code examples: code/ Practice project: Project 01. Prompt-Only vs. Rules-First: How Much Difference Does a Harness Make

در 29 سپتامبر 2025، شرکت Anthropic گزارش داد که Claude Sonnet 4.5 به 77.2% در SWE-bench Verified دست یافته است. این عدد در نگاه اول مناسب به‌نظر می‌رسد — اما هنوز نباید جشن گرفت. این‌ها وظایفی هستند که با دقت انتخاب شده‌اند و دارای شرح مسئلهٔ شفاف و آزمون‌های آماده هستند. در مقابل، وقتی نیازمندی‌های روزمرهٔ خود را به ایجنت (agent) می‌سپارید — مشخصات مبهم، بدون آزمون‌های موجود و قواعد کاری ضمنی که در سراسر کد پراکنده‌اند — نرخ قبولی باز هم کاهش می‌یابد. شما با اطمینان کامل وظیفه‌ای را تحویل می‌دهید، ایجنت 20 دقیقه اجرا می‌شود و به شما می‌گوید «همه چیز انجام شد»، اما وقتی به کد نگاه می‌کنید می‌بینید: قابلیتی را اضافه کرده اما آزمون‌ها را شکسته است، باگی را رفع کرده اما باگ‌های جدیدی به وجود آورده است، و حتی آن چیزی نیست که شما خواسته بودید.

وقتی این اتفاق می‌افتد، نخستین واکنش اکثر افراد این است: «مدل به اندازهٔ کافی خوب نیست — بگذار مدل گران‌قیمت‌تری را امتحان کنم.» پیش از آنکه دست به جیب شوید، در نظر بگیرید که شاید مشکل اصلاً از مدل نباشد.

همان اسب، سرنوشت‌های متفاوت#

شرکت Anthropic همان پرامپت (prompt) یکسان («یک ویرایشگر بازی دو‌بعدی رترو بسازید») و همان مدل (Opus 4.5) را زیر دو هارنس (harness) مقایسه کرد. اجرای اول: بدون هیچ ساختار کمکی — 20 دقیقه، 9 دلار؛ برنامه باز شد، اما موجودیت‌ها به ورودی‌ها پاسخ ندادند. اجرای دوم: هارنس کامل — معماری سه ایجنتی شامل برنامه‌ریز، تولیدکننده و ارزیاب — 6 ساعت، 200 دلار؛ نویسنده توانست موجودیتی را حرکت دهد، اما فیزیک بازی ناهمواری‌هایی داشت و یک دیوار مانع پیشرفت می‌شد. هستهٔ گیم‌پلی کار می‌کرد؛ برنامه هنوز کامل نبود.

آن‌ها مدل را تغییر ندادند. Opus 4.5 همان Opus 4.5 بود. آنچه تغییر کرد، یراق و دهنهٔ اسب (tack) بود. درست مانند یک اسب اصیل مسابقه: بدون زین و یراق مناسب هم می‌توان بر آن سوار شد، اما نمی‌توان مسافتی طولانی رفت، با سرعت حرکت کرد، و زمین خوردن سوارکار اصلاً جای شگفتی نخواهد داشت. هارنس در واقع همان مجموعهٔ کامل یراق و زین و دهنه است.

مقالهٔ مهندسی هارنس سال 2025 شرکت OpenAI این موضوع را حتی صریح‌تر بیان می‌کند. آن‌ها گفتند که Codex در مخزنی با هارنس مناسب، از وضعیت «غیرقابل‌اعتماد» مستقیماً به «قابل‌اعتماد» جهش می‌کند. به این واژه‌گزینی توجه کنید — نه «کمی بهتر»، بلکه یک جهش کیفی. منظور از هارنس در اینجا تمام زیرساخت‌های مهندسی خارج از وزن‌های مدل است.

ایجنت‌ها واقعاً در کجا متوقف می‌شوند#

حالت‌های شکست مشخص در واقع به چند مورد محدود خلاصه می‌شوند:

نیازمندی‌های مبهم — ایجنت فقط می‌تواند حدس بزند. «یک قابلیت جستجو اضافه کن» — این جمله تقریباً هیچ معنایی ندارد. جستجوی چه چیزی؟ جستجوی تمام‌متن یا پرس‌وجوهای ساختاریافته؟ آیا نتایج باید صفحه‌بندی شوند؟ برجسته‌سازی چطور؟ از آنجا که این جزئیات را شفاف نکرده‌اید، ایجنت مجبور است حدس بزند. حدس درست یک شانس است؛ اما حدس نادرست به‌معنای بازکاری‌ای است که هزینه‌اش چندین برابر مشخص‌کردن دقیق نیازمندی از ابتدا خواهد بود.
قواعد ضمنی که نوشته نشده‌اند — ایجنت هیچ راهی برای رعایت آن‌ها ندارد. تمام تیم شما از نحو جدید SQLAlchemy 2.0 استفاده می‌کنند، اما ایجنت به‌طور پیش‌فرض کد 1.x می‌نویسد. تمام اندپوینت‌های API باید از احراز هویت OAuth 2.0 عبور کنند، اما این قانون تنها در ذهن شما و پیامی در اسلک از سه ماه پیش وجود دارد. ایجنت هیچ تصوری از آن ندارد — نه اینکه نخواهد رعایت کند، بلکه واقعاً این قاعده را ندیده است.
راه‌اندازی ناقص محیط — ایجنت انرژی خود را صرف تعمیر محیط می‌کند. محیط توسعهٔ ناقص، وابستگی‌های از دست رفته، نسخه‌های اشتباه ابزارها — ایجنت به‌جای انجام کار اصلی که به آن سپرده‌اید، پنجرهٔ زمینه (context) ارزشمند خود را با خطاهای pip install و تداخل نسخه‌های Node هدر می‌دهد.
نبود روش‌های راستی‌آزمایی — ایجنت زمانی کار را تمام‌شده می‌داند که حس کند تمام شده است. هیچ آزمونی نیست، هیچ لینتی وجود ندارد، یا دستورات راستی‌آزمایی (verification) هرگز به اطلاع ایجنت نرسیده‌اند. ایجنت کد را می‌نویسد، نگاهی به آن می‌اندازد، به این نتیجه می‌رسد که همه‌چیز خوب است، و اتمام کار را اعلام می‌کند. شرکت Anthropic پدیدهٔ جالبی را هم مشاهده کرده است: وقتی ایجنت‌ها حس می‌کنند زمینهٔ آن‌ها رو به اتمام است، برای پایان دادن شتاب می‌کنند، مراحل راستی‌آزمایی را نادیده می‌گیرند، و به‌جای راه‌حل بهینه گزینه‌ای ساده را برمی‌گزینند. آن‌ها این وضعیت را «اضطراب زمینه» (context anxiety) می‌نامند.
از دست رفتن وضعیت بین نشست‌ها — هر نشست جدید از صفر آغاز می‌شود. تمام یافته‌های نشست پیشین از بین می‌روند. هر نشست جدید باید دوباره ساختار پروژه را بکاود و سازماندهی کد را بشناسد. ایجنت‌های بدون وضعیت (state) پایدار در وظایفی که بیش از 30 دقیقه طول می‌کشند، با جهش شدید نرخ شکست روبه‌رو می‌شوند.

واژگان کلیدی#

با در نظر گرفتن سناریوهای بالا، این مفاهیم دیگر صرفاً اصطلاحات فنی پیچیده نیستند:

شکاف توانمندی (Capability Gap): فاصلهٔ عظیم میان عملکرد مدل در بنچمارک‌ها و عملکرد آن در وظایف واقعی. وظایف بنچمارک با شرح مسئلهٔ شفاف، آزمون‌ها و محیط آماده ارائه می‌شوند؛ اما در وظایف واقعی اغلب خود شما باید آن‌ها را فراهم کنید.
هارنس (Harness): هر چیزی خارج از مدل — دستورالعمل‌ها (instructions)، ابزارها، محیط، مدیریت وضعیت، و بازخورد راستی‌آزمایی. اگر جزو وزن‌های مدل نیست، هارنس است؛ همان چیزی که آن را «یراق و دهنه» نامیده‌ایم.
شکست ناشی از هارنس (Harness-Induced Failure): مدل از توانمندی کافی برخوردار است، اما محیط اجرا دارای نقص‌های ساختاری است. مقایسهٔ بازی رترو در بالا نمونه‌ای از این وضعیت است.
شکاف راستی‌آزمایی (Verification Gap): فاصلهٔ میان اطمینان ایجنت به خروجی خود و درستی واقعی آن. ایجنت می‌گوید «کارم تمام شد» در حالی که تمام نشده است — این رایج‌ترین حالت شکست است.
حلقهٔ تشخیص (Diagnostic Loop): اجرا، مشاهدهٔ شکست، انتساب علت به لایه‌ای مشخص از هارنس، اصلاح آن لایه، و اجرای دوباره. این روش‌شناسی اصلی مهندسی هارنس است.
تعریف اتمام (Definition of Done): مجموعه‌ای از شرایط که می‌توان با دستور آن‌ها را راستی‌آزمایی کرد — آزمون‌ها پاس شوند، لینت بدون خطا باشد، بررسی تایپ‌ها موفق باشد. بدون یک تعریف اتمام صریح، ایجنت تعریفی برای خود اختراع خواهد کرد.

هنگام بروز شکست، ابتدا هارنس را اصلاح کنید#

تنها یک اصل اساسی وجود دارد: وقتی مشکلی پیش می‌آید، ابتدا مدل را عوض نکنید — هارنس را بررسی کنید. اگر همان مدل در وظایف مشابه و با ساختار مناسب موفق می‌شود، فرض کنید مشکل از هارنس است.

این کار در عمل چگونه است؟ هر شکستی را به لایه‌ای مشخص نسبت دهید. صرفاً نگویید «مدل به اندازهٔ کافی خوب نیست». از خود بپرسید: آیا وظیفه مبهم بود؟ آیا زمینه ناکافی بود؟ آیا هیچ روش راستی‌آزمایی وجود نداشت؟ هر شکست را به یکی از پنج لایهٔ دفاعی نسبت دهید — مشخصات وظیفه، تأمین زمینه، محیط اجرا، بازخورد راستی‌آزمایی، یا مدیریت وضعیت. این‌ها لایه‌های تشخیص شکست هستند، نه مفاهیم بنیادی جداگانه. این عادت را بسازید، و خواهید دید که جملهٔ «مدل خوب نیست» کمتر و کمتر در گزارش‌های شما ثبت می‌شود.

سپس برای هر وظیفه یک تعریف اتمام صریح بنویسید. نگویید «یک قابلیت جستجو اضافه کن». دقیقاً مشخص کنید:

Completion criteria:
- New endpoint GET /api/search?q=xxx
- Supports pagination, default 20 items
- Results include highlighted snippets
- All new code passes pytest
- Type checking passes (mypy --strict)

یک فایل AGENTS.md در ریشهٔ مخزن قرار دهید و در آن فناوری‌های پروژه، قواعد معماری، و دستورات راستی‌آزمایی را به ایجنت بگویید. این نخستین گام در مهندسی هارنس است و بیشترین بازگشت سرمایه را دارد. یک فایل AGENTS.md ممکن است مؤثرتر از ارتقا به مدلی گران‌قیمت‌تر باشد — و این شوخی نیست.

از آنجا، یک حلقهٔ تشخیص بسازید. شکست‌ها را به‌صورت «دوباره خنگ‌بازی مدل» تلقی نکنید. با آن‌ها به‌عنوان نشانه‌هایی برخورد کنید که نشان می‌دهند هارنس شما نقصی را نمایان کرده است. با هر شکست، لایهٔ مربوطه را شناسایی کنید، آن را برطرف سازید، و دیگر هرگز از آن طریق شکست نخورید. پس از چند دوره، هارنس شما قوی‌تر می‌شود و عملکرد ایجنت تثبیت می‌گردد. یک گزارش ساده کفایت می‌کند — برای هر وظیفه، آیا موفق شد یا شکست خورد، و کدام لایه باعث شکست شد. پس از چند دور خواهید دید کدام لایه گلوگاه است و می‌توانید انرژی خود را روی آن متمرکز کنید.

آزمایش یک‌میلیون‌خطی#

در اوت 2025، سه مهندس در OpenAI آزمایشی را آغاز کردند. قواعد ساده بود: خودشان کدی نمی‌نوشتند — تنها Codex کد می‌نوشت. با شروع از یک مخزن گیت خالی، پنج ماه بعد مخزن شامل حدود یک میلیون خط کد بود. منطق برنامه، زیرساخت، ابزارها، و مستندات — همگی توسط ایجنت تولید شده بودند. تیم بعداً به هفت مهندس گسترش یافت؛ در این بازه حدود 1,500 پول‌ریکوئست (PR) ادغام شد، با میانگین 3.5 پول‌ریکوئست به‌ازای هر مهندس در روز.

پیشرفت اولیه به‌طرز شگفت‌آوری کند بود. Codex بد نبود — فقط از ابزارها و ساختارهای کاملی که برای حرکت به سوی اهداف سطح بالا نیاز داشت، محروم بود. آن سه مهندس رفته‌رفته الگو را یافتند: اهداف بزرگ را به بلوک‌های ساختمانی کوچک خرد کنید — طراحی، کدنویسی، بررسی، آزمون — به ایجنت اجازه دهید آن‌ها را یکی‌یکی سوار کند، و سپس از این بلوک‌ها برای ترکیب وظایف پیچیده‌تر بهره ببرید. هر بار مشکلی پیش می‌آمد، مسئله تقریباً هیچ‌گاه «تلاش ناکافی» نبود. همیشه این بود: «ایجنت هنوز چه چیزی را کم دارد، و آیا می‌توان آن توانمندی مفقود را به‌شیوه‌ای که هم قابل‌فهم و هم قابل‌اجرا باشد تأمین کرد؟»

این آزمایش مستقیماً فرضیهٔ اصلی این درس را اثبات می‌کند: همان مدل در یک محیط برهنه در مقایسه با محیطی با هارنس کامل، خروجی‌های بنیادین متفاوتی تولید می‌کند. مدل تغییر نکرد؛ محیط تغییر کرد.

منبع: OpenAI: Harness engineering: leveraging Codex in an agent-first world

مثالی ملموس‌تر#

تیمی از Claude Sonnet برای افزودن اندپوینت‌های جدید API به یک برنامهٔ وب پایتونی با اندازهٔ متوسط (FastAPI + PostgreSQL + Redis، حدود 15,000 خط کد) استفاده کرد.

در ابتدا آن‌ها فقط یک جمله ارائه دادند: «اندپوینت‌های ترجیحات کاربر را زیر /api/v2/users اضافه کن». نتیجه چه شد؟ ایجنت بخش زیادی از نشست را صرف کاوش در ساختار مخزن کرد، کدی تولید نمود که معقول به‌نظر می‌رسید اما از الگوهای مدیریت خطای پروژه پیروی نمی‌کرد، از نحو قدیمی SQLAlchemy استفاده نمود، و با وجود اینکه اندپوینت خطاهای زمان اجرا داشت، اتمام کار را اعلام کرد. نشست بعدی مجبور بود تمام کار اکتشاف را از نو انجام دهد.

بعدها آن‌ها فایل AGENTS.md (شرح معماری پروژه و نسخه‌های پشتهٔ فناوری)، دستورات صریح راستی‌آزمایی (pytest tests/api/v2/ && python -m mypy src/)، و اسناد تصمیمات معماری را اضافه کردند. سپس همان مدل از قراردادهای پروژه پیروی کرد و کار خود را با دستوراتی که می‌توانست اجرا کند مورد بررسی قرار داد.

آن‌ها مدل را تغییر ندادند. آن‌ها هارنس را تغییر دادند.

نکات کلیدی#

توانمندی مدل و قابلیت اطمینان در اجرا دو مقولهٔ متفاوت هستند. حتی یک اسب اصیل مسابقه به یراق مناسب نیاز دارد.
وقتی کارها شکست می‌خورند، ابتدا هارنس را بررسی کنید و سپس مدل را. تعویض مدل پرهزینه‌ترین گزینه است — و در بیشتر موارد، مشکل اصلاً از مدل نیست.
هر شکست یک نشانه است: هارنس شما دارای نقصی ساختاری است. آن را پیدا کنید و رفع نمایید.
فقط نگویید «مدل به اندازهٔ کافی خوب نیست». پنج لایه را به‌صورت روشمند بررسی کنید: وظیفه به‌طور شفاف تعریف نشده است، زمینه ناکافی است، محیط پیکربندی نادرستی دارد، راستی‌آزمایی وجود ندارد، یا وضعیت میان نشست‌ها از دست رفته است. در نه بار از ده بار، مشکل در یکی از این لایه‌ها قرار دارد.
یک فایل AGENTS.md ممکن است از ارتقا به مدلی گران‌قیمت‌تر مؤثرتر باشد.

منابع بیشتر#

تمرین‌ها#

آزمایش مقایسه‌ای: پایگاه کدی را که به‌خوبی می‌شناسید و یک وظیفهٔ تغییر غیرپیش‌پاافتاده انتخاب کنید. ابتدا ایجنت را بدون هیچ پشتیبانی هارنس اجرا کرده و شکست‌ها را ثبت کنید. سپس یک AGENTS.md و دستورات صریح راستی‌آزمایی بیفزایید و دوباره با همان ایجنت اجرا نمایید. دو نتیجه را مقایسه کنید و هر شکست را به یکی از پنج لایهٔ دفاعی نسبت دهید.
سنجش شکاف راستی‌آزمایی: 5 وظیفهٔ کدنویسی را انتخاب کنید. پس از هر وظیفه، ثبت کنید که آیا ایجنت ادعای اتمام کار می‌کند یا خیر، سپس درستی واقعی را با آزمون‌های مستقل راستی‌آزمایی کنید. نسبت دفعاتی که ایجنت ادعای انجام کار دارد اما در واقعیت کار انجام نشده است را محاسبه نمایید — این همان شکاف راستی‌آزمایی شماست. سپس بیندیشید: چه دستورات راستی‌آزمایی می‌توانند این نسبت را کاهش دهند؟
تمرین حلقهٔ تشخیص: وظیفه‌ای در پروژهٔ خود پیدا کنید که ایجنت مکرراً در آن شکست می‌خورد. یک‌بار آن را اجرا کرده و شکست را ثبت نمایید. آن را به یکی از پنج لایه نسبت دهید. آن لایه را اصلاح کنید. دوباره اجرا کنید. این روند را سه تا پنج دور تکرار کرده و بهبودها را در هر دور ثبت نمایید.