Claude Plugin Eval: איך לבדוק אם הסקיל שלכם באמת משפר את קלוד, ותבנית לשבע בדיקות אמיתיות

מה זה claude plugin eval

בגרסה 2.1.269 של Claude Code נוספה פקודה חדשה: claude plugin eval. היא לוקחת את הפלאגין או הסקיל שכתבתם, מריצה מולו כמה משימות אמיתיות, נותנת לכל הרצה ציון, ואז מריצה את אותן משימות בדיוק בלי הפלאגין, כדי להראות מה הוא באמת הוסיף.

עד עכשיו בדקתם סקיל בדרך אחת: הרצתם אותו פעם אחת, ראיתם תשובה יפה, והנחתם שהוא עובד. הבעיה היא שסוכן הוא לא דטרמיניסטי, אותה בקשה יכולה לתת תשובה אחרת בכל פעם. הרצה אחת לא מספרת כלום.

הפקודה פותרת את זה בשלוש דרכים: כל משימה רצה שלוש פעמים כברירת מחדל, כל הרצה מתחילה בסשן נקי לגמרי, וכל משימה רצה בשתי זרועות, עם הפלאגין ובלי. ההפרש בין השתיים הוא המספר שמעניין אתכם.

מה צריך לפני שמתחילים

• Claude Code בגרסה 2.1.269 ומעלה. בדקו עם claude —version ועדכנו עם claude update.
• תיקיית פלאגין עם plugin.json או .claude-plugin/plugin.json, או פלאגין מסוג תיקיית סקילים.
• אותו חשבון שאתם עובדים איתו רגיל. כל הרצה וכל שופט הם קריאת מודל אמיתית שנספרת במכסה שלכם או בחשבון ה-API.

איך מתחילים: שלוש פקודות

1. שהסוכן יכתוב לכם את הבדיקות

נכנסים לתיקיית הפלאגין ומריצים:

cd my-plugin
claude plugin eval init

הפקודה שואלת אתכם על הפלאגין, מציעה מקרי בדיקה וגריידרים, מנסה אותם וכותבת את הקבצים. זה המסלול המומלץ: לא צריך לכתוב את הסוויטה ביד.

2. להריץ את כל הסוויטה

claude plugin eval .

כל מקרה רץ שלוש פעמים עם הפלאגין ושלוש פעמים בלי, כלומר מקרה אחד הוא שש הרצות.

3. לקרוא את הסיכום

CASE        WITH  W/OUT  D      RUNS  COST
first-case  1.00  0.33   +0.67  6     $0.41
1 case(s) - mean D +0.67 - 74s - $0.41

WITH הוא הציון עם הפלאגין, W/OUT בלעדיו, ו-D חיובי אומר שהפלאגין העלה את הציון. אם D יוצא אפס: הפלאגין לא תרם כלום, והרגע חסכתם לעצמכם עבודה.

מבנה התיקייה

סוויטת בדיקות היא תיקייה בשם evals בתוך הפלאגין. כל מקרה הוא תת-תיקייה משלו:

my-plugin/
  .claude-plugin/plugin.json
  skills/...
  evals/
    first-case/
      prompt.md          # frontmatter + the prompt
      graders/
        criteria.md      # grader on the result
        skill-fired.md   # grader on how it got there
      case.yaml          # optional: context fields only
    results/             # written by every run - gitignore it

שישה סוגי בדיקות

כל קובץ בתוך graders הוא בדיקה אחת שרצה אחרי ההרצה. ארבעה סוגים מחושבים מהתמליל ומהקבצים ולא עולים שקל. שניים קוראים למודל שופט ומוסיפים לעלות.

אין גריידרים עם קוד משלכם. הכלל המעשי: בנו את רוב הבדיקות על ארבע החינמיות, ושמרו את השופט רק למקומות שבאמת דורשים שיפוט.

איך נראה מקרה בדיקה אחד

הקובץ prompt.md מכיל את ההודעה שקלוד מקבל, ובראש שלו את מגבלות ההרצה:

---
max_turns: 10
allowed_tools: [Read, Glob, Grep, Skill]
---
Write me a commit message for this change: I renamed getUser
to fetchUser and updated the three call sites.

כתבו את הבקשה כמו שמשתמש היה מקליד אותה, בלי להזכיר את שם הסקיל. זאת בדיוק הנקודה: אתם בודקים אם קלוד בוחר בסקיל לבד.

כל קובץ בתוך graders הוא בדיקה. גריידר של שופט נראה ככה:

---
type: llm
---
PASS if the message has a short imperative subject line.
FAIL if it describes the rename in more than one sentence.

וגריידר חינמי שבודק שהסקיל בכלל נטען:

---
type: tool_used
tool: Skill
min: 1
---

התבנית: שבע בדיקות אמיתיות

זאת התבנית שהבטחתי בסרטון. שבעה מקרים שמכסים את מה שבאמת שובר פלאגין: חמישה בודקים שהוא עובד, ושניים שליליים בודקים שהוא לא נטען איפה שהוא לא שייך.

שני המקרים השליליים נראים כמו בזבוז עד שרואים אותם בדוח: ה-D שלהם יהיה אפס כשהכול תקין, ושלילי ברגע שהסקיל מתחיל להיטען איפה שלא צריך. זה בדיוק מה שלא הייתם מגלים בלי בדיקה.

הדרך המהירה לבנות את זה: להריץ את init ואז לתת לסוכן את הטבלה הזאת -

claude plugin eval init

ובתוך השיחה: תבנה לי שבעה מקרים לפי הטבלה הזאת, ותשתמש רק בגריידרים הקבועים חוץ מהמקומות שמסומנים llm.

איך קוראים את הדוח

בסוף ההרצה נפתח דוח HTML עם חמישה מספרים בראש. אלה המספרים מהדוח לדוגמה בתיעוד הרשמי:

בשורת המטא-דאטה מופיעים גם הזמן והעלות. בדוגמה: 2m 22s ו-0.93 דולר ל-18 הרצות.

הממצא הכי נפוץ בהרצה הראשונה הוא D קרוב לאפס יחד עם גריידר tool_used שנכשל. זה אומר שקלוד לא בוחר בסקיל שלכם בניסוח טבעי, והבעיה היא כמעט תמיד התיאור של הסקיל ולא הקוד.

האופציות שכדאי להכיר

לבדוק מקרה אחד בזול, לפני שמריצים את הכול:

claude plugin eval . --case first-case --runs 1 --ablation none

הרצה אחת היא רועשת. אשרו כל שינוי בשלוש ההרצות הרגילות לפני שאתם סומכים עליו.

להריץ את זה ב-CI

הפקודה מחזירה קוד יציאה, אז אפשר לחסום מיזוג של שינוי שמוריד את הציון. שני דגלים חשובים ב-CI: נעילת המודל, ואישור אמון לתיקייה, שבלעדיו ההרצה נדחית.

claude plugin eval . --trust-plugin --model <model-id> \
  --threshold 0.8 --max-cost-usd 5

קוד יציאה 0: כל המקרים עברו את הסף. קוד 1: מקרה נכשל. קוד 2: נגמרה תקרת העלות והרצות לא התחילו.

איפה הקאץ

שלושה דברים שחשוב להבין לפני שמריצים:

• עלות: כל הרצה וכל שופט הם קריאת מודל אמיתית על החשבון שלכם. שבעה מקרים בשלוש הרצות ובשתי זרועות הם 42 הרצות סוכן. התחילו עם runs 1 ותקרת עלות.
• הרשאות: פלאגין שאתם לא מכירים רץ עם ההרשאות שלכם, וה-hooks וה-MCP שלו רצים בשמכם. הריצו eval רק על פלאגין שהייתם מריצים ממילא.
• בידוד: כל הרצה מקבלת בית וקונפיגורציה חד-פעמיים. ה-CLAUDE.md, ה-hooks, ה-MCP והסקילים האחרים שלכם לא נטענים. אם המשימה צריכה משהו, שימו אותו בפרומפט או ב-scaffold_script.

טיפים

• כתבו את הפרומפט כמו משתמש ולא כמו מפתח. ברגע שכתבתם תשתמש בסקיל, ביטלתם את הבדיקה.
• שני גריידרים לכל מקרה: אחד על התוצאה, כמו regex או llm, ואחד על הדרך, כמו tool_used או tool_order.
• פלט ארוך תבדקו עם regex ולא עם שופט. שופט קורא טקסט ארוך ומשנה דעה בין הרצות.
• רובריקה של llm נכתבת כתנאי PASS ו-FAIL קונקרטיים, לא כבקשה לבדוק אם זה טוב.
• כשהציון נמוך, חשדו קודם בשופט ורק אחר כך בסקיל. כך כתוב גם בתיעוד הרשמי.
• הוסיפו את התיקייה evals/results ל-gitignore. כל הרצה כותבת לשם.
• D אפס הוא לא כישלון של הבדיקה. זאת התשובה: הפלאגין לא תרם.
• הריצו מחדש אחרי כל שחרור מודל. סקיל שעבד מצוין יכול להפסיק להיטען במודל חדש, וזאת בדיוק הסיבה שהפיצר נבנה.

לינקים

• התיעוד הרשמי: code.claude.com/docs/en/plugin-evals
• הודעת ההשקה: x.com/ClaudeDevs
• ההסבר של הצוות על init: x.com/trq212