شروع پروژه

چیت‌شیت

توسعه‌ی ایجنت مبتنی بر ارزیابی (Eval-Driven)

Eval-Driven Agent Development

اجرای مورد‌های ارزیابی، گیت‌گذاری mergeها، بازبینی با شیوه‌نامه‌ی نمره‌دهی، و گیت‌گذاری تغییرات پرامپت و گزارش. با کتابخانه‌ی استاندارد Python.

  • ۱۳ بخش
  • ۳ درس مرتبط
  • کد و دستورها عیناً از دوره‌ی اصلی
فهرست مطالب
  1. از سازنده تا تأیید نهایی
  2. سه لایه‌ی ارزیابی
  3. حلقه‌ی ارزیاب-بهینه‌ساز
  4. اجرای درس‌ها و پروژه‌ها
  5. گیت‌گذاری یک وظیفه
  6. شیوه‌نامه‌ی نمره‌دهی بازبین
  7. مقادیر پیش‌فرض و اعداد
  8. تستر پسرفت پرامپت (Prompt Regression Tester)
  9. داور گزارش (Report Judge)
  10. عیب‌یابی
  11. پرسش‌ها
  12. نکات
  13. کدهای یافته‌های گیت

از سازنده تا تأیید نهایی

معماری
خیربلهایجنت سازنده (Builder Agent)نوشتن diffدست‌سازه‌ها (Artifacts)تفاوت‌های بازنگری، دامنه، قوانین، بازخوردگیت اعتبارسنجیقطعی، بدون LLMverification_report.jsonقبول شده: true یا falseرد وضعیت اتمامارجاع به انسانایجنت بازبین (Reviewer Agent)فقط‌خواندنی، شیوه‌نامه‌ی نمره‌دهیتأیید نهایی انسانreads review_report.json

سه لایه‌ی ارزیابی

مقایسه
عاملبنچ‌مارک‌های ایستاآفلاین سفارشیآنلاین
نمونه‌هاSWE-bench Verified، GAIA، BFCL V4مدل زبانی در نقش داور، اجرا، مسیر کامل اجرابازپخش‌های نشست، هشدارهای گاردریل
کاربردمقایسه‌ی میان‌مدلیساختار محصول شمارفتار در محیط عملیاتی
معیارهاتوانمندی عمومیپچ‌های مناسب محصول شماهزینه و تاخیر به ازای هر گام
مواردی که باید مراقب بودنرخ آلودگی، 32.67٪ نشت دادهداورها هم توهم می‌زننداتصال هر شکست به یک مورد جدید

حلقه‌ی ارزیاب-بهینه‌ساز

گام‌به‌گام
  1. پیشنهاددهندهcase.proposer(feedback) یک کاندید ارائه می‌دهد.
  2. داورcase.judge(candidate) وضعیت ok و دلیل را برمی‌گرداند.
  3. اصلاحدلیل به بازخورد بعدی تبدیل می‌شود.
  4. توقفپس از max_rounds مورد شکست می‌خورد.
  5. گیت CIبخش ci_gate پسرفت فراتر از آستانه را مسدود می‌کند.

اجرای درس‌ها و پروژه‌ها

دستورها
دستورکارکرد
python3 code/main.pyاجرای دمو درس. درس‌های 38 و 39 گزارش‌های JSON می‌نویسند
VERIFY_DEMO_MODE=1 python3 code/main.py --strictدموی گیت با سکرت دمو. هر warn تبدیل به block می‌شود
python3 code/main.py --floor <value>دموی گیت با حداقل پوشش متغیر
python3 scripts/project_test.py <project> --init learning-artifacts/<project>ساخت میز کار یادگیرنده
python3 scripts/project_test.py <project> --stage <n> --path learning-artifacts/<project>تست یک مرحله از میز کار شما
python3 scripts/project_test.py <project> --all --solution --strictبررسی راه‌حل مرجع
python3 <dir>/cli.py <cases> <baseline> <candidate> --out <json> --markdown <md>بررسی diff پرامپت. افزودن --allow-configuration-change برای تغییر مدل
python3 <dir>/cli.py <claims> --out <json> --html <html>ممیزی گزارش. افزودن --research-payload برای بار داده گزارش

گیت‌گذاری یک وظیفه

کد
python
art = Artifacts(task_id="T-001",
    acceptance_commands=accept,  # خروجی صفر یعنی اتمام کار
    feedback=[{"command": accept[0], "exit_code": 0}],
    scope_report={"forbidden_writes": [], "off_scope_writes": []},
    rule_report=[{"slug": "done/tests-pass", "passed": True}],
    coverage_report={"current": 0.84, "previous": 0.85},
    head_commit="a1b2c3d")
report = verify(art, strict=False, coverage_floor=0.80)
report.passed                    # مقدار False به ازای هر یافته‌ی مسدودکننده (block)
record_override(task_id, finding_code, reason, user_id, head_commit)
verify_signature(entry)          # بررسی HMAC برای override

شیوه‌نامه‌ی نمره‌دهی بازبین

مفهوم‌ها
تناسب با مسئله
آیا وظیفه همان‌طور که بیان شده حل شده؟
انضباط دامنه
ویرایش‌ها در چارچوب قرارداد هستند؟
فرضیات
مکتوب شده‌اند؟
کیفیت اعتبارسنجی
پذیرش، دستیابی به هدف را اثبات می‌کند؟
آمادگی تحویل وظیفه
نشست بعدی می‌تواند کار را ادامه دهد؟
امتیازها
هر کدام 0 تا 2، مجموع از 10.
حکم ارزیابی
7 یا بالاتر pass، در غیر این صورت soft_fail.
hard_fail
مجموع کمتر از 5 یا وجود هر امتیاز 0.

مقادیر پیش‌فرض و اعداد

پیش‌فرض‌ها
تنظیمپیش‌فرضیادداشت
max_rounds3دورهای ارزیاب-بهینه‌ساز به ازای هر مورد
regression_threshold0.05ci_gate بالاتر از این مقدار را مسدود می‌کند
COVERAGE_FLOOR_DEFAULT0.80کمتر از این مقدار مسدودکننده (block) است
COVERAGE_REGRESSION_DELTA0.01افت بیشتر نسبت به آخرین merge مسدود می‌شود
`release_gate` `min_pass`1.0نسبت قبولی در [0,1]
`release_gate` `max_regressions`0بودجه‌ی مجاز پسرفت به صورت عدد صحیح
`judge_claim` `threshold`0.8امتیاز همپوشانی برای در نظر گرفتن به عنوان پشتیبانی‌شده
`compare` `samples`2000نمونه‌برداری مجدد بوت‌استرپ، seed=7

تستر پسرفت پرامپت (Prompt Regression Tester)

کار و کد
وظیفهکد
شناسه‌های یکتا، انواع بررسی شناخته‌شدهvalidate_cases(cases)
انواع بررسی`contains`, `excludes`, `json`
نمره‌دهی به یک پاسخ ضبط‌شدهscore_response(response, checks)
جفت کردن نسخه‌ها بر اساس شناسه‌ی موردcompare(cases, baseline, candidate)
وضعیت‌های جفت‌ها`stable_pass`, `regressed`, `improved`
انتشار یا مسدودسازیrelease_gate(report)
اتصال ضبط به موردهاcase_sha256 == case_digest(cases)
بارگذاری یک اجرای متصل به منشأ و سندیتload_run(raw, cases)

داور گزارش (Report Judge)

کار و کد
وظیفهکد
یک ادعا در هر جملهparse_claims(text)
پشتیبانی واژگانی از یک ادعاsupport(claim, source)
ارجاعات داور در برابر شواهدjudge_claim(claim, evidence)
دلایل امتیاز صفر`negation`, `number`, `uncited`
دقت، بازخوانی، پوششscore_report(text, evidence)
وزن‌های امتیاز`precision` 0.5, `recall` 0.25
وضعیت‌ها`no_evidence`, `needs_review`
بوت‌استرپ جفت‌شدهcompare(baseline, candidate)

عیب‌یابی

عیب‌یابی

  • امتیازهای ارزیابی خوانا نیستند

    علت
    نبود خط مبنا
    راه‌حل
    ذخیره‌ی آخرین خط مبنای معتبر

  • داور خروجی اشتباه را تایید می‌کند

    علت
    داور مبتنی بر LLM بدون ارجاع‌دهی مکانی
    راه‌حل
    ارجاع‌دهی مکانی داور به ابزارهای خارجی

  • ارزیابی‌ها قبول می‌شوند، محیط عملیاتی شکست می‌خورد

    علت
    بیش‌برازش روی ارزیابی‌ها
    راه‌حل
    چرخش دوره‌ای موردها

  • هشدارهای نادرست در CI

    علت
    موردهای ناپایدار و غیرقطعی
    راه‌حل
    تثبیت seedها، گرفتن اسنپ‌شات از وضعیت

  • refused to start: VERIFY_OVERRIDE_SECRET is unset

    علت
    سکرت override تنظیم نشده است
    راه‌حل
    متغیر محیطی را تنظیم کنید، یا برای دمو VERIFY_DEMO_MODE=1 را قرار دهید

  • recording does not match cases

    علت
    فهرست موردها پس از ضبط تغییر کرده است
    راه‌حل
    ضبط‌های جدید ایجاد کنید

  • model/settings changed; explicitly allow this experiment

    علت
    پیکربندی خط مبنا و کاندید متفاوت است
    راه‌حل
    فلگ --allow-configuration-change را ارسال کنید

  • order_requires_review برای یک ادعای درست

    علت
    قاعده‌ی واژگانی بازنویسی را رد می‌کند
    راه‌حل
    یک انسان ادعا را بازبینی کند

پرسش‌ها

پرسش و پاسخ
چرا هیچ LLMای در گیت نیست؟
گیت برای دست‌سازه‌های یکسان، هر بار همان حکم ارزیابی را می‌دهد.
چه کسی یک مسدودی (block) را override می‌کند؟
فقط انسان، همراه با override_reason و overridden_by.
چرا بازبین جداگانه؟
تفکیک نقش‌ها: پرامپت متفاوت، ورودی‌های متفاوت، بدون دسترسی نوشتن.
چرا جفت کردن موردها با شناسه؟
میانگین می‌تواند یک پسرفت جدی را پنهان کند.
چرا بازخوانی null است؟
بازخوانی و پوشش نیاز به برچسب دارند؛ بدون برچسب در دسترس نیستند.

نکات

نکته‌ها
  • ارزیابی‌ها را کنار کد نگه دارید. در هر PR آن‌ها را در CI اجرا کنید.
  • هر گاردریل و هر قاعده‌ی آموخته‌شده را به یک مورد ارزیابی نگاشت کنید.
  • به ازای هر وظیفه یک گزارش در outputs/verification/<task_id>.json بنویسید.
  • فلگ --strict را فقط روی branchهای انتشار به کار ببرید؛ پیش‌فرض سراسری نیست.
  • پس از هر تغییر پرامپت، بازبین را روی یک مجموعه‌ی کالیبراسیون 10 تا 20 وظیفه‌ای اجرا کنید.
  • اگر توافق زیر 80٪ بود، پیش از انتشار بازبین، شیوه‌نامه‌ی نمره‌دهی را بازنگری کنید.

کدهای یافته‌های گیت

مفهوم‌ها
acceptance.missing
مسدودکننده (block). فرمانی هرگز اجرا نشد.
acceptance.failed
مسدودکننده (block). کد خروجی غیرصفر.
feedback.null_exit
مسدودکننده (block). بدون کد خروجی.
scope.forbidden
مسدودکننده (block). **scope.off_scope**: هشدار (warn).
coverage.below_floor
مسدودکننده (block). **coverage.missing**: هشدار (warn).

درس‌هایی که این موضوع را از صفر می‌سازند