درس 11. مشاهده‌پذیر ساختن زمان اجرای ایجنت

Code examples: code/ Practice project: Project 06. Build a Complete Agent Harness

شما از یک ایجنت (agent) می‌خواهید قابلیتی را پیاده‌سازی کند. 20 دقیقه اجرا می‌شود، تعداد زیادی فایل را دستکاری می‌کند، و سپس به شما می‌گوید «انجام شد، اما دو آزمون رد می‌شوند». می‌پرسید چرا — «مطمئن نیستم، شاید مشکل زمان‌بندی باشد». می‌پرسید کدام مسیرهای بحرانی را تغییر داده است — «اجازه دهید کد را بررسی کنم…»

این سناریو بسیار رایج است، و علت ریشه‌ای آن توانمندی ایجنت نیست — بلکه فقدان مشاهده‌پذیری (observability) در هارنس (harness) است. هنگامی که ایجنت وظیفه‌ای را بدون دید کافی به وضعیت واقعی زمان اجرا به انجام می‌رساند، هر تصمیمی که می‌گیرد اساساً یک حدس است.

بدون مشاهده‌پذیری، ایجنت‌ها تحت عدم قطعیت تصمیم می‌گیرند، ارزیابی‌ها به قضاوت‌های ذهنی بدل می‌شوند، و تلاش‌های مجدد به سرگردانی کورکورانه تبدیل می‌گردند. هم OpenAI و هم Anthropic قابلیت اطمینان را به‌عنوان یک مسئلهٔ شواهد مطرح می‌کنند: هارنس باید رفتار زمان اجرا و سیگنال‌های ارزیابی را در قالبی ارائه دهد که واقعاً بتواند تصمیم بعدی را هدایت کند.

هزینهٔ واقعی فقدان مشاهده‌پذیری#

هنگامی که هارنس فاقد مشاهده‌پذیری باشد، چهار دسته از مشکلات به‌طور سیستماتیک پدیدار می‌شوند.

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

ارزیابی به یک امر رازآلود بدل می‌شود. بدون چارچوب‌های نمره‌دهی و معیارهای پذیرش، ارزیاب‌ها (انسان یا ایجنت) مجبورند به مفروضات ضمنی تکیه کنند. یک خروجی یکسان می‌تواند از ارزیاب‌های مختلف ارزیابی‌های کاملاً متفاوتی دریافت کند. ارزیابی کیفیت تکرارناپذیر می‌شود.

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

صخرهٔ اطلاعاتی تحویل نشست. هنگامی که کار ناتمام به نشست بعدی تحویل داده می‌شود، فقدان مشاهده‌پذیری یعنی نشست جدید باید وضعیت سیستم را از صفر عیب‌یابی کند. نشست جدید باید دوباره کد را بخواند، دستورات را دوباره اجرا کند، و تصمیم بگیرد کدام سیگنال‌ها اهمیت دارند؛ سوابق نسخه‌بندی‌شدهٔ پیشرفت و راستی‌آزمایی وضعیت قابل‌بررسی را فراهم می‌سازند.

سناریویی واقعی در Claude Code#

یک هارنس را در نظر بگیرید که از جریان کاری سه‌نقشی «برنامه‌ریز-تولیدکننده-ارزیاب» استفاده می‌کند، و وظیفهٔ «افزودن حالت تاریک به برنامه» را اجرا می‌نماید.

بدون مشاهده‌پذیری: برنامه‌ریز توضیحی مبهم ارائه می‌دهد. تولیدکننده بر اساس همان ابهام حالت تاریک را پیاده‌سازی می‌کند، اما نتیجه با انتظارات ضمنی برنامه‌ریز همخوانی ندارد. ارزیاب آن را بر اساس استانداردهای ضمنی خود رد می‌کند اما نمی‌تواند مشخصاً بگوید کجای کار ایراد دارد — فقط «حس خوبی ندارد». تولیدکننده بر اساس دلایل رد مبهم، کورکورانه تلاش مجدد می‌کند. چرخه 3 تا 4 بار تکرار می‌شود، حدود 45 دقیقه طول می‌کشد، و به‌زحمت خروجی قابل‌قبولی تولید می‌نماید.

با مشاهده‌پذیری کامل: برنامه‌ریز یک قرارداد اسپرینت خروجی می‌دهد که مشخص می‌کند کدام مؤلفه‌ها باید تغییر کنند، استانداردهای راستی‌آزمایی برای هرکدام چیست، و موارد مستثنی (مانند استایل‌های چاپ) کدام‌اند. تولیدکننده بر اساس قرارداد پیاده‌سازی می‌کند، و مشاهده‌پذیری زمان اجرا فرایند بارگذاری و اعمال استایل هر مؤلفه را ثبت می‌نماید. ارزیاب از یک چارچوب نمره‌دهی برای ارزیابی بُعد به بُعد استفاده می‌کند، همراه با استناد به شواهد مشخص: «کنتراست رنگ دکمه ناکافی است (استاندارد WCAG AA برابر با 4.5:1 است، مقدار اندازه‌گیری‌شده 2.1:1 می‌باشد)». یک تکرار نتیجه‌ای با کیفیت بالا تولید می‌کند، در حدود 15 دقیقه.

تفاوت از اینجاست که آیا قرارداد و شواهد در خارج از ذهن ایجنت وجود دارند یا خیر.

مشاهده‌پذیری لایه‌بندی‌شده#

مشاهده‌پذیری صرفاً «افزودن لاگ‌های بیشتر» نیست. در دو لایه عمل می‌کند، و هر دو ضروری هستند.

flowchart LR
    Contract["Define the task upfront<br/>which files to change / what not to touch / pass criteria"] --> Generator["Generator"]
    Generator --> Signals["Collect at runtime<br/>logs / traces / health checks"]
    Contract --> Review["Check item by item against the list<br/>functionality / tests / boundaries"]
    Signals --> Review
    Review --> Verdict["Point out which item failed<br/>and where to fix it"]
    Verdict --> Generator

مشاهده‌پذیری زمان اجرا: سیگنال‌های سطح سیستم — گزارش‌ها، ردیابی‌ها، رویدادهای فرایند، و بررسی‌های سلامت. پاسخ می‌دهد به «سیستم چه کرد».

مشاهده‌پذیری فرایند: دید به مصنوعات (artifacts) تصمیم‌گیری در هارنس — برنامه‌ها، چارچوب‌های نمره‌دهی، و معیارهای پذیرش. پاسخ می‌دهد به «چرا این تغییر باید پذیرفته شود».

مفاهیم اصلی#

• مشاهده‌پذیری زمان اجرا: سیگنال‌های سطح سیستم شامل لاگ‌ها، ردیابی‌ها، رویدادهای فرایند، و بررسی‌های سلامت. پاسخ به «سیستم چه کرد».
• مشاهده‌پذیری فرایند: قابلیت مشاهدهٔ مصنوعات تصمیم‌گیری هارنس شامل برنامه‌ها، چارچوب‌های نمره‌دهی، و معیارهای پذیرش. پاسخ به «چرا این تغییر باید پذیرفته شود».
• ردیابی وظیفه (Task Trace): سابقهٔ کامل مسیر تصمیم‌گیری از شروع وظیفه تا اتمام، شبیه به ردیابی درخواست‌ها در سیستم‌های توزیع‌شده. هر گامی که ایجنت برمی‌دارد، همراه با زمینه‌اش، ثبت می‌شود — بنابراین وقتی مشکلی پیش می‌آید، می‌توانید کل فرایند را بازپخش کنید.
• قرارداد اسپرینت (Sprint Contract): توافقی کوتاه‌مدت که پیش از آغاز کدنویسی مذاکره می‌شود، و دامنهٔ وظیفه، استانداردهای راستی‌آزمایی، و موارد مستثنی را مشخص می‌سازد. ابزار اصلی برای مشاهده‌پذیری فرایند.
• چارچوب نمره‌دهی ارزیاب (Evaluator Rubric): ارزیابی کیفیت را از قضاوت ذهنی به نمره‌دهی ساختاریافته و مبتنی بر شواهد تبدیل می‌کند، و به ارزیاب‌های مختلف امکان می‌دهد برای یک خروجی یکسان به نتایج مشابهی برسند.
• مشاهده‌پذیری لایه‌بندی‌شده: مشاهده‌پذیری لایهٔ سیستم و لایهٔ فرایند که هم‌زمان طراحی شده و یکدیگر را تقویت می‌کنند. سیگنال‌های زمان اجرا رفتار را توضیح می‌دهند؛ مصنوعات فرایند نیت را تشریح می‌کنند.

چرا ایجنت‌ها نمی‌توانند خودشان این را حل کنند#

شاید فکر کنید: «آیا ایجنت نمی‌تواند صرفاً لاگ‌های خودش را چاپ کند؟» مشکل اینجاست:

1. ایجنت‌ها نمی‌دانند چه چیزهایی را نمی‌دانند. آن‌ها به‌طور فعالانه سیگنال‌هایی را که متوجه نیاز به آن‌ها نیستند ثبت نمی‌کنند. بدون محدودیت‌های سطح هارنس، ایجنت‌ها تنها آنچه را که فکر می‌کنند مهم است ثبت می‌نمایند — و آنچه آن‌ها مهم می‌دانند معمولاً کافی نیست.
2. قالب‌های لاگ ناسازگارند. نشست‌های مختلف از قالب‌های لاگ متفاوتی استفاده می‌کنند، که تحلیل سیستماتیک را غیرممکن می‌سازد.
3. مشاهده‌پذیری فرایند با لاگ‌گذاری حل نمی‌شود. قراردادهای اسپرینت و چارچوب‌های نمره‌دهی مصنوعاتی ساختاریافته هستند که نیازمند پشتیبانی سطح هارنس می‌باشند — افزودن چند دستور چاپ (print) کارساز نخواهد بود.

چگونه مشاهده‌پذیری را بسازیم#

1. تعبیهٔ جمع‌آوری سیگنال‌های زمان اجرا درون هارنس#

به ایجنت برای چاپ لاگ‌هایش تکیه نکنید. هارنس باید به‌طور خودکار سیگنال‌های زیر را جمع‌آوری کند:

• چرخهٔ حیات برنامه: وضعیت‌های فازهای راه‌اندازی، آماده‌به‌کار، در حال اجرا، و خاموشی
• اجرای مسیر قابلیت: سوابق اجرای مسیرهای بحرانی، شامل نقاط ورود، نقاط بررسی، و خروج‌ها
• جریان داده‌ها: سوابق جریان داده‌ها میان مؤلفه‌ها
• بهره‌برداری از منابع: الگوهای غیرعادی مصرف منابع (مانند رشد مداوم حافظه)
• خطاها و استثناها: زمینهٔ کامل خطا، نه صرفاً پیام‌های خطا

2. پیاده‌سازی قراردادهای اسپرینت#

پیش از آغاز هر وظیفه، تولیدکننده و ارزیاب (که ممکن است فراخوانی‌های متفاوتی از همان ایجنت باشند) قراردادی را مذاکره می‌کنند که مشخص می‌سازد چه چیزی باید ساخته شود و «تمام شد» چگونه به‌نظر می‌رسد:

# Sprint Contract: Dark Mode Support

## Scope
- Modify the theme toggle component
- Update global CSS variables
- Add dark mode tests

## Verification Standards
- Visual regression tests pass for each component
- Main flow end-to-end tests pass
- No flash of unstyled content (FOUC)

## Exclusions
- Not handling print styles
- Not handling third-party component dark mode

3. تدوین چارچوب نمره‌دهی ارزیاب#

«خوب است یا نه» را به نمره‌دهی کمّی تبدیل کنید:

# Scoring Rubric

| Dimension | A | B | C | D |
|-----------|---|---|---|---|
| Code correctness | All tests pass | Main flow passes | Partial pass | Build fails |
| Architecture compliance | Fully compliant | Minor deviations | Obvious deviations | Serious violations |
| Test coverage | Main + edge cases | Main flow only | Only skeleton | No tests |

4. استانداردسازی با OpenTelemetry#

برای هر نشست هارنس یک trace، برای هر وظیفه یک span، و برای هر مرحلهٔ راستی‌آزمایی sub-spanهایی ایجاد کنید. از ویژگی‌های استاندارد برای حاشیه‌نویسی اطلاعات کلیدی استفاده نمایید. به این ترتیب داده‌های مشاهده‌پذیری با زنجیره ابزارهای استاندارد (Jaeger, Zipkin) یکپارچه می‌شوند.

آزمایش معماری سه ایجنتی Anthropic#

گزارش مارس 2026 شرکت Anthropic اجرای به‌روزرسانی‌شدهٔ DAW با همان معماری سه ایجنتی را ارائه می‌دهد («ساخت یک DAW تحت وب با استفاده از Web Audio API»). نسخهٔ اول، ساخته‌شده برای Opus 4.5، از تولیدکننده‌ای استفاده می‌کرد که در اسپرینت‌ها کار می‌کرد و ارزیابی که به هر اسپرینت نمره می‌داد. نسخهٔ به‌روزرسانی‌شده، اجراشده روی Opus 4.6، ساختار اسپرینت را حذف کرد: سازنده به‌طور مداوم کار می‌کند، و ارزیاب پس از هر دور ساخت بررسی را انجام می‌دهد. جدول زیر اجرای به‌روزرسانی‌شده را نشان می‌دهد:

هر نقش جایگاهی شفاف در مشاهده‌پذیری ایفا می‌کند. شرح نقش‌های زیر نسخهٔ اول را پوشش می‌دهد؛ نسخهٔ به‌روزرسانی‌شده لایهٔ اسپرینت تولیدکننده را حذف می‌کند:

برنامه‌ریز (Planner): نیازمندی 1 تا 4 جمله‌ای کاربر را دریافت کرده و آن را به مشخصات کامل محصول بسط می‌دهد. به آن دستور داده شد که «در دامنه جسور باشد» و «روی زمینهٔ محصول و طراحی فنی سطح بالا تمرکز کند نه پیاده‌سازی فنی جزئی». دلیل: اگر برنامه‌ریز پیش از موعد جزئیات فنی ریز را مشخص کند و در آن‌ها اشتباه کند، آن خطاها به بخش‌های پایینی سرازیر می‌شوند. رویکرد بهتر این است که خروجی‌ها محدود شوند و به ایجنت اجازه داده شود در طول اجرا مسیر خود را بیابد.

تولیدکننده (Generator): ویژگی به ویژگی و اسپرینت به اسپرینت پیاده‌سازی می‌کند. پیش از هر اسپرینت، یک قرارداد اسپرینت با ارزیاب مذاکره می‌نماید که تعریف می‌کند «تمام شد» برای آن بلوک قابلیت به چه معناست. سپس بر اساس قرارداد پیاده‌سازی می‌کند، خودارزیابی انجام می‌دهد، و کار را به QA تحویل می‌دهد.

ارزیاب (Evaluator): از Playwright MCP برای تایجنت با برنامهٔ در حال اجرا مانند یک کاربر واقعی استفاده می‌کند — تست عملکرد UI، اندپوینت‌های API، و وضعیت پایگاه داده. به هر اسپرینت در چهار بُعد نمره می‌دهد: عمق محصول، کارکرد، طراحی بصری، و کیفیت کد. هر بُعد دارای آستانه‌ای سخت‌گیرانه است — اگر هرکدام کاستی داشته باشد، اسپرینت رد می‌شود و تولیدکننده بازخورد تفصیلی برای اصلاحات دریافت می‌کند.

نمونه بازخورد از دور اول QA: «این یک برنامهٔ چشم‌نواز بصری با یکپارچگی خوب هوش مصنوعی است، اما چندین ویژگی اصلی DAW صرفاً نمایشی هستند و فاقد عمق تایجنتی می‌باشند: کلیپ‌ها قابل کشیدن/جابجایی نیستند، پنل رابط کاربری سازها (پیچ‌های سینت، پدهای درام) وجود ندارد، و ویرایشگر جلوه‌های بصری (منحنی‌های EQ، سنجش‌گرهای کمپرسور) تعبیه نشده است.» این‌ها موارد حاشیه‌ای نیستند — تایجنتات اصلی هستند که یک DAW را قابل‌استفاده می‌سازند. بازخوردی مشخص و متکی بر شواهد — نه اینکه «حس خوبی ندارد».

ارزیاب همیشه تا این حد دقیق نبود. نسخه‌های اولیه مشکلات معقول را شناسایی می‌کردند، سپس خود را قانع می‌کردند که آن مشکلات چندان شدید نیستند و در نهایت کار را تأیید می‌کردند. راه‌حل: خواندن لاگ‌های ارزیاب، یافتن نقاطی که قضاوت آن از قضاوت انسانی فاصله گرفت، و به‌روزرسانی پرامپت QA برای پرداختن به آن مشکلات خاص. پس از چند دور از این حلقهٔ توسعه، نمره‌دهی ارزیاب قابل‌اعتماد شد.

منبع: Anthropic: Harness design for long-running application development

نکات کلیدی#

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

منابع بیشتر#

• Observability Engineering - Charity Majors — چارچوب نظری و عملی برای مهندسی مشاهده‌پذیری مدرن
• Dapper - Google (Sigelman et al.) — تجارب پیشگامانه در ردیابی توزیع‌شده در مقیاس بزرگ
• Harness Design - Anthropic — معرفی قراردادهای اسپرینت و چارچوب‌های نمره‌دهی ارزیاب
• Site Reliability Engineering - Google — کاربرد سیستماتیک مشاهده‌پذیری در سیستم‌های عملیاتی

تمرین‌ها#

1. تحلیل شکاف مشاهده‌پذیری: هارنس کنونی خود را برای مشاهده‌پذیری لایهٔ سیستم و لایهٔ فرایند ارزیابی کنید. وضعیت‌های سیستمی را که نمی‌توان از روی سیگنال‌های موجود تفکیک کرد بیابید، و مواردی را برای اضافه شدن پیشنهاد دهید.

2. تمرین قرارداد اسپرینت: یک قرارداد اسپرینت برای یک وظیفهٔ واقعی بنویسید. از ایجنت بخواهید مطابق با قرارداد عمل کند، و کارایی و کیفیت را با و بدون قرارداد مقایسه کنید.

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