📘 תיעוד 44

בדיקת תוספים באמצעות evals

כתוב מקרי eval עבור תוסף ה-Claude Code שלך, הרץ אותם באמצעות claude plugin eval, דרג את התוצאות, השווה מול קו בסיס ללא תוסף, והתנה את המעבר ב-CI בציון שהתקבל.

הפקודה claude plugin eval מריצה את ה-תוסף שלך מול חבילת מקרי בדיקה ומנקדת את התוצאות. כל מקרה מורכב מ-prompt מציאותי בתוספת בודק אחד או יותר (grader). בודק הוא בדיקת עבר או נכשל על מה ש-Claude הפיק, כגון ביטוי רגולרי (regex) על התשובה, האם כלי מסוים הופעל, או מחוון (rubric) שעל פיו מודל שני שופט את התשובה.

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

השתמש ב-evals כדי למדוד באיזו מידה של אמינות התוסף שלך מכוון את Claude לתוצאה הנכונה, כדי לתפוס נסיגות (regressions) כאשר אתה משנה את התוסף או כאשר מודל חדש יוצא לשוק, וכדי לראות מה התוסף תורם בהשוואה למצב ללא תוסף כלל.

דף זה מיועד למחברי תוספים וכישורים (skills) שיש להם תוסף עובד ורוצים לבדוק את התנהגותו, ולצוותים שמתנים שינויים בתוסף במעבר ב-CI. פורמט המקרים שלו נפרד מקובץ evals/evals.json שבו משתמש התוסף skill-creator. כדי ליצור תוסף, ראה יצירת תוספים. כדי לבדוק קבצי תוסף לאיתור שגיאות תחביר וסכמה ולא את התנהגותו, השתמש ב-claude plugin validate.

הערה: כל הרצת eval וכל בודק שופט (judge grader) הם קריאת מודל אמיתית בחשבונך, הנחשבת במניין השימוש של התוכנית שלך או בחשבון ה-API שלך, לכן בדוק תחילה את הדרישות. לאחר מכן צור את חבילת ה-eval הראשונה שלך, או עבור אל הרצת evals ב-CI אם כבר יש לך חבילה כזו.

#דרישות

כדי להריץ evals של תוספים אתה זקוק ל:

• Claude Code בגרסה v2.1.269 ומעלה. הרץ claude --version כדי לבדוק ו-claude update כדי לשדרג.
• תיקיית תוסף עם מניפסט plugin.json או .claude-plugin/plugin.json, או תוסף מסוג skills-directory.
• אותם פרטי אימות וספק מודל שבהם משתמשות הפעלות ה-Claude Code הרגילות שלך. הרצות eval, בודקים המנוקדים על ידי שופט (judge), ו-claude plugin eval init קוראים למודל עם פרטי האימות שלך, כך שהם נספרים כחלק ממגבלות השימוש בתוכנית שלך או בחשבון ה-API שלך. כאשר הפקודה מדווחת על עלות, הנתון הוא הערכה לפי מחיר מחירון של אותן קריאות.

#כיצד פועלת הרצת eval

חבילת eval שוכנת בתיקייה בשם evals/ בתוך התוסף שלך, במבנה המוצג בסעיף כתיבה וליטוש של מקרים. כל מקרה הוא תיקיית משנה משלו עם prompt ובודק אחד או יותר (graders). ה-prompt הוא דבר שמשתמש בתוסף עשוי להקליד, כגון בקשה שאחד מהכישורים שלו אמור לטפל בה.

#מה קורה במהלך הרצה

עבור כל הרצה של מקרה, Claude Code מתחיל הפעלה לא אינטראקטיבית חדשה ומבודדת עם התוסף שלך בלבד טעון, שולח את ה-prompt, ומאפשר ל-Claude לעבוד עד שהוא מסיים או מגיע למגבלת התורות (turns) או הזמן של המקרה. כל בודק בודק לאחר מכן את התשובה הסופית, את התמליל (transcript), או קובץ ש-Claude יצר, וקובע עבר או נכשל.

#כיצד מקרה מקבל ציון

הרצה בודדת של סוכן שאינו דטרמיניסטי מלמדת מעט מאוד, לכן כל מקרה רץ שלוש פעמים כברירת מחדל. הציון של הרצה הוא החלק היחסי מתוך הבודקים שלה שעברו, משוקלל אם הגדרת משקלים, וציון המקרה הוא הממוצע של כלל הרצותיו. מקרה עובר כאשר הציון שלו מגיע ל---threshold, שהוא 1.0 כברירת מחדל. מבחינת קריאות מודל, חבילה מבצעת בקירוב מספר מקרים × מספר הרצות של הרצות סוכן עם התוסף, וכמות זהה עבור קו הבסיס ללא תוסף, בתוספת שלוש קריאות שופט קצרות לכל בודק מסוג llm או baseline בכל הרצה.

#קו הבסיס ללא תוסף

ציון גבוה כשלעצמו אינו מעיד על כך שהתוסף עזר, מכיוון ש-Claude עשוי להצליח באותה מידה בלעדיו. כדי להפריד בין השניים, ההרצות של כל מקרה מבוצעות שוב ללא תוסף טעון כברירת מחדל, ואתה מקבל שני ציונים, WITH ו-W/OUT. ההפרש ביניהם, Δ, מייצג את מה שהתוסף תרם. אם מקרה מקבל ציון 1.0 הן עם התוסף והן בלעדיו, התוסף אינו הסיבה שבגללה הוא עבר. שתי קבוצות ההרצות נקראות with-arm ו-without-arm. הסעיף ניקוד מול קו הבסיס ללא תוסף מפרט כיצד בודקים מנוקדים ביניהן וכיצד לכבות את קו הבסיס.

#יצירת חבילת ה-eval הראשונה שלך

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

• Claude Code בגרסה v2.1.269 ומעלה ושאר הדרישות
• מסוף פתוח בתיקיית השורש של התוסף שלך, זו שמכילה את plugin.json או .claude-plugin/plugin.json
• כישור (skill) אחד בתוסף שברצונך לבדוק, ובקשה שמשתמש עשוי להקליד ואמורה להפעיל אותו

1. יצירת המקרים

   מתיקיית השורש של התוסף, הרץ:

   העתק

   claude plugin eval init

   אם Claude Code עדיין אינו נותן אמון בתיקייה זו, הוא שואל תחילה Trust this plugin directory?. ענה y. לאחר מכן נפתחת הפעלת Claude Code אינטראקטיבית. Claude קורא את התוסף שלך ושואל אותך כיצד נראית תוצאה טובה, מציע הודעות prompt שאמורות להפעיל את התוסף ושאינן אמורות להפעיל אותו, מתכנן בודקים (graders) עבור כל אחד, מריץ אותם פעם אחת כניסיון כדי לוודא שהם פועלים כראוי, וכותב תיקיית מקרה אחת לכל prompt תחת evals/, שכל אחת מהן קרויה על שם ה-prompt שלה. כאשר Claude מודיע לך שהחבילה מוכנה, צא מאותה הפעלה באמצעות /exit או Ctrl+D כדי לחזור למעטפת (shell) שלך.

   אם כבר יש לך הפעלת Claude Code פתוחה בתיקיית השורש של התוסף, תוכל במקום זאת לבקש מ-Claude שם להריץ claude plugin eval init. Claude יריץ את הפקודה ולאחר מכן ישאל אותך את אותן השאלות באותה שיחה.

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

2. הרצת החבילה

   בחזרה במעטפת שלך בתיקיית השורש של התוסף, הרץ כל מקרה תחת evals/:

   העתק

   claude plugin eval .

   הבעת אמון בתיקייה זו כבר במהלך שלב 1, ולכן ההרצה מתחילה מיד. אם כתבת את המקרה באופן ידני במקום זאת, ההרצה שואלת תחילה Trust this plugin directory? [y/N]. ענה y. הסעיף למה הרצה יכולה לגשת מסביר למה אתה מסכים.

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

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

   כאשר החבילה מסיימת מוצגת טבלת סיכום, ולאחריה המיקום שאליו הועבר הדוח:

   העתק

   CASE        WITH  W/OUT Δ      RUNS COST    NOTES
   first-case  1.00  0.33  +0.67  6    $0.41
   
   1 case(s) · mean Δ +0.67 · 74s · $0.41
   Report: /Users/you/my-plugin/evals/results/2026-09-10T17-02-11-482Z/report.html
   Published: https://claude.ai/... · keep local next time with --no-publish

   WITH מציין את ציון המקרה כאשר התוסף שלך טעון, W/OUT מציין את הציון בלעדיו, ו-Δ חיובי פירושו שהתוסף העלה את הציון. COST הוא הערכה לפי מחיר מחירון של קריאות המודל, ו-NOTES מציג את ההסבר של הבודק שנכשל בעל המשקל הגבוה ביותר, או את שגיאת ההרצה, מתוך ה-with-arm.

4. פתיחת הדוח ואיטרציה

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

   הממצא הראשוני הנפוץ ביותר הוא Δ קרוב לאפס כאשר הבודק tool_used: Skill של המקרה נכשל, מה שמעיד על כך ש-Claude אינו בוחר בכישור שלך בעת ניסוח טבעי. התאם את שדה ה-description של הכישור, הרץ שוב claude plugin eval ., והשווה.

   כדי לבצע איטרציה על מקרה יחיד בעלות נמוכה, הרץ זרוע אחת (arm) פעם אחת בלבד. הרצה בודדת כוללת רעש, לכן ודא כל שינוי בהרצה של שלוש פעמים כברירת מחדל לפני שתסמוך עליו. כאשר מריצים זרוע אחת, הטבלה מציגה את העמודות SCORE ו-PASS% במקום WITH, W/OUT, ו-Δ:

   העתק

   claude plugin eval . --case <case-name> --runs 1 --ablation none

   החלף את <case-name> באחד משמות התיקיות תחת evals/.

#כתיבה וליטוש של מקרים

המקרים ש-claude plugin eval init כותב הם קבצים פשוטים שניתן לפתוח, לשנות ולהוסיף עליהם. מקרה הוא תיקייה תחת תיקיית ה-eval של התוסף שמכילה prompt.md, case.yaml, או את שניהם. כדי לקבץ מקרים, קנן אותם תחת תיקייה שאינה מקרה בפני עצמה. כל דבר בתוך תיקיית מקרה, כגון graders/ וקבצי fixture, שייך לאותו מקרה.

זהו המבנה ש-claude plugin eval init כותב וזה המבנה שיש להשתמש בו עבור חבילות חדשות. הסימוכין של חבילת eval מכיל את העץ המלא, כולל mocks ותוצאות:

my-plugin/
├── .claude-plugin/plugin.json
├── skills/...
└── evals/
    ├── first-case/
    │   ├── prompt.md          
# frontmatter: case fields; body: the prompt
    │   ├── graders/
    │   │   ├── criteria.md    
# frontmatter: type + options; body: rubric or pattern
    │   │   └── skill-fired.md
    │   └── case.yaml          
# optional: only for context.* fields
    ├── ignores-unrelated-request/
    │   └── ...
    └── results/               
# written by each run; add to .gitignore

#כתיבת מקרה באופן ידני

מתן אפשרות ל-Claude לכתוב את המקרים באמצעות claude plugin eval init הוא הנתיב המומלץ. כדי לכתוב מקרה בעצמך במקום זאת, התחל מתבנית ריקה. הפקודה הבאה כותבת מקרה בשם first-case עם קובץ prompt.md זמני ובודק זמני אחד, ואינה מריצה דבר:

claude plugin eval init --bare first-case

evals/first-case/
├── prompt.md            
# the prompt sent to Claude, plus run limits
└── graders/
    └── criteria.md      
# one grader: how to score the result

ב-prompt.md אתה כותב את ההודעה ש-Claude מקבל בכל הרצה, ומגדיר את מגבלות ההרצה והכלים שבהם המקרה רשאי להשתמש ב-frontmatter שלו. פתח את evals/first-case/prompt.md והחלף את גוף הטקסט הזמני בבקשה שאחד הכישורים שלך אמור לטפל בה, מנוסחת כפי שמשתמש היה מקליד אותה ולא על ידי ציון שם הכישור. דוגמה זו מיועדת לכישור שמנסח הודעות commit. השתמש בבקשה משלך:

---
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.

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

כל קובץ תחת graders/ הוא בדיקה אחת המוחלת לאחר ההרצה. פתח את evals/first-case/graders/criteria.md והחלף את הטקסט הזמני במחוון עבור מודל השופט, הכתוב כתנאי PASS ו-FAIL מוגדרים:

---
type: llm
---

PASS if <what a correct response contains>.
FAIL if <what a wrong or missing response looks like>.

לאחר מכן הוסף בודק שני שמוודא שהכישור שלך הוא אכן זה שיצר את התשובה. צור את evals/first-case/graders/skill-fired.md, והחלף את your-skill-name ב-name מתוך ה-SKILL.md של הכישור שלך:

---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?your-skill-name"'
---

בודק זה עובר כאשר Claude הפעיל את הכישור לפחות פעם אחת במהלך ההרצה, כולל בצורת מרחב השמות שלו plugin-name:skill-name. הסעיף סוגי בודקים מונה את שאר הבדיקות הזמינות, כגון התאמה לביטוי רגולרי (regex) או אימות שקובץ מסוים נוצר.

כאשר שני הקבצים שמורים, הרץ את המקרה באותו האופן כפי שנעשה במדריך המהיר, באמצעות claude plugin eval . מתיקיית השורש של התוסף.

#הגדרת מגבלות הרצה וכלים ב-prompt.md

הגדר את max_turns, timeout_seconds, model, tags, ואת הכלים המורשים שבהם המקרה רשאי להשתמש ב-allowed_tools ב-frontmatter של prompt.md. הסימוכין של frontmatter ב-prompt.md מפרט כל שדה ואת ערך ברירת המחדל שלו. Claude מקבל את גוף ההודעה בדיוק כפי שכתבת אותו. אזכורים של ‎@path בתוכו אינם מורחבים לקבצים מצורפים, כך שאם Claude צריך לקרוא קובץ, הענק כלי לשם כך ב-allowed_tools.

#בחירה ושקלול של graders

ה-frontmatter של בודק מגדיר את ה-type שלו, ובאופן אופציונלי weight שגורם לו לקבל משקל רב יותר בציון ההרצה, ו-arm השולט באופן שבו הוא מנוקד מול קו הבסיס. מתוך ששת הסוגים, regex, tool_used, tool_order, ו-file_exists מחושבים מתוך התמליל והקבצים ואינם עולים דבר, בעוד ש-llm ו-baseline קוראים למודל שופט ומוסיפים לעלות ההרצה.

אין בודקים של קוד מותאם אישית. הסעיף סוגי בודקים מפרט את האפשרויות ואת תנאי המעבר של כל סוג, והסעיף למה בודק יכול להסתכל מפרט את הערכים ש-target ו-focus מקבלים.

השופט עבור בודקי llm ו-baseline הוא מודל קטן ומהיר כברירת מחדל. העבר --judge-model sonnet או מזהה מודל מלא כדי להשתמש במודל חזק יותר עבור מחוונים בעלי דקויות.

#בחירת graders שנותנים אות יציב

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

• עבור פלט ארוך כגון קובץ שנוצר, בדוק אותו באמצעות בודק regex על תוכן הקובץ, אשר בודק את הקובץ כולו באותו אופן בכל פעם. שמור בודקי llm לפלטים קצרים, עם מחוונים הכתובים כתנאי PASS ו-FAIL מוגדרים.
• תן לכל מקרה בודק אחד על התוצאה, כגון ההודעה הסופית או קובץ שנוצר, ובודק אחד על האופן שבו Claude הגיע לשם, כגון tool_used או tool_order. יחד הם מעידים הן אם התשובה הייתה נכונה והן אם התוסף שלך יצר אותה.
• אם בודק מסוג tool_used: Skill של מקרה עובר אך Δ הוא שלילי, חשוד בשופט לפני התוסף. מודל שופט קטן עלול לסמן תשובה נכונה כשגויה מכיוון שהיא מעוצבת אחרת ממה שהמחוון מתאר. הרץ שוב עם --judge-model sonnet, והדק את המחוון כך שהעיצוב לא יכריע את התוצאה.
• כדי לוודא שפעולת build או בדיקה עברה בתוך ההרצה, בקש ב-prompt ש-Claude יריץ אותה ויכתוב את התוצאה לקובץ, בדוק את הקובץ הזה, וודא שהפקודה רצה באמצעות בודק tool_used אשר ה-input_match שלו מציין את שם הפקודה.

#ניקוד מול קו הבסיס ללא תוסף

כאשר תוסף נבדק, כל מקרה רץ בשתי זרועות כברירת מחדל. ה-with-arm היא ההרצות שלו עם התוסף טעון, וה-without-arm היא אותו מספר הרצות ללא תוסף כלל. הסיכום והדוח מציגים את שני הציונים ואת Δ, שהוא ציון ה-with-arm פחות ציון ה-without-arm. העבר --ablation none כדי להריץ רק את ה-with-arm, מה שחוצה את העלות לחצי כאשר אינך זקוק להשוואה, כגון בעת איטרציה על בודקים.

בהרצה של שתי זרועות, חלק מהבודקים מדווחים עם scored: false. בדיקה כגון "הכישור הופעל" לעולם אינה יכולה לעבור ללא התוסף, ולכן החשבתה הייתה דוחפת את ה-without-arm לכיוון אפס ומנפחת את Δ. כדי לשמור על שתי הזרועות ברות השוואה, Claude Code מוציא בודקים כאלה מהציון בשתי הזרועות ומדווח עליהם ב-with-arm כאינדיקטורים של עבר או נכשל בלבד. זה כולל:

• כל בודק מסוג tool_used שבו ה-tool הוא Skill
• כל בודק שאתה מסמן ב-arm: with-only

אם כל בודק במקרה מסוים הוא אחד מאלה, הם מנוקדים כרגיל במקום זאת, מכיוון שלא יישאר דבר לנקד. הגדר arm: both על בודק כדי לנקד אותו בשתי הזרועות ללא תלות, שזה מה שאתה רוצה עבור בדיקה בסגנון "אסור להפעיל את הכישור" עם min: 0 ו-max: 0. תחת --ablation none שום דבר אינו מוחרג, ולכן אותה חבילה יכולה להפיק ציון אבסולוטי שונה בשני המצבים.

#שימוש בתיקיית eval אחרת

אם evals/ כבר תפוסה על ידי כלי אחר, החזק את החבילה בתיקייה אחרת. תוכל לתעד את אותה תיקייה ב-plugin.json של התוסף כך שכל הרצה וכל משתף פעולה ישתמשו בה, או להעביר אותה בשורת הפקודה עבור הרצה בודדת:

• ב-plugin.json: הוסף "experimental": { "evals": "quality/evals" }.
• בשורת הפקודה: העבר --eval-dir quality/evals הן ל-claude plugin eval והן ל-claude plugin eval init.

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

#הגדרת fixtures ו-mocks

מקרה עשוי להזדקק ליותר מאשר רק prompt: קבצים או מאגר git בסביבת העבודה, שיחה קודמת שיש להמשיך, או תשובות משרתי ה-MCP שהתוסף שלך מתקשר איתם. כל אחד מאלה מוגדר לצד המקרה כך שההרצות יישארו ניתנות לשחזור.

#אתחול סביבת העבודה או השיחה

כל הרצה מתחילה בסביבת עבודה ריקה. כאשר מקרה זקוק ליותר מאשר ה-prompt, הוסף קובץ case.yaml לצד prompt.md עם בלוק context.

כדי ליצור תחילה קבצי fixture או מאגר git, כתוב סקריפט Bash בתיקיית המקרה וציין את שמו ב-context.scaffold_script. הסקריפט רץ תחת המשתמש שלך, מחוץ לארגז החול (sandbox) של הסוכן, ורק כאשר אתה מעביר --scaffold, לכן העבר דגל זה רק עבור חבילות שאתה או הארגון שלך כתבתם. כדי להמשיך שיחה קודמת, שמור את התמליל כקובץ .jsonl וציין את שמו ב-context.history_file, וה-prompt של המקרה יהפוך לתור המשתמש הבא. כדי לאפשר ל-Claude לקרוא תיקיות fixture במקרה במהלך ההרצה, רשום אותן ב-context.add_dirs.

קובץ case.yaml זקוק גם ל-schema_version: "1.1" ול-name. הסימוכין של שדות case.yaml כולל את הרשימה המלאה.

קובץ case.yaml זה מאתחל סביבת עבודה מתוך סקריפט ומאפשר ל-Claude לקרוא fixtures מתוך תיקיית resources/:

schema_version: "1.1"
name: changelog-from-diff
tags: [smoke]
context:
  scaffold_script: fixture.sh
  add_dirs: [resources]

#דימוי (Mock) של שרתי MCP

באפשרותך להעריך תוסף שכישוריו קוראים לכלי MCP ללא השירות האמיתי מאחוריהם. שים קובץ Markdown אחד לכל כלי תחת evals/mocks/<server>/<tool>.md עבור החבילה כולה, או תחת תיקיית mocks/ של המקרה עצמו עבור מקרה בודד, כאשר <server> הוא שם השרת בהגדרת ה-MCP של התוסף שלך.

הרצה לעולם אינה מפעילה את שרתי ה-MCP האמיתיים של התוסף שלך אלא אם תבקש זאת. Claude Code רושם תחליף (stand-in) תחת שמו של כל שרת. כלים בעלי קובץ mock עונים מתוכו ומורשים ללא מתן הרשאה באמצעות --allow-tools, וכלי ללא קובץ mock אינו זמין ל-Claude. שרת ללא שום mocks כלל מופיע בשורת התקדמות ה-mocked: של המקרה בתור plugin_<plugin>_<server>[not started: no mock].

גוף הקובץ הוא מה שהכלי מחזיר ל-Claude. mock זה משמש כתחליף לכלי create_issue בשרת בשם tracker, בודק את הקלט ש-Claude שולח, ומחזיר את הכותרת כהד. שמור אותו בתור evals/mocks/tracker/create_issue.md:

---
expect:
  title: string
  priority: [low, medium, high]
---

Created issue #4821: {{input.title}}

הזן שדות מקלט הקריאה באמצעות {{input.<field>}}, ואת תוכנו של קובץ fixture לצד ה-mock באמצעות {{file:fixtures/{input.<field>}.json}}. הבלוק expect: שומר על הקלט. אם קריאה מפרה אותו, ההרצה נעצרת עם ציון 0 ומתעדת את הסיבה, כך שמקרה יכול לאמת מה התוסף שלך ביקש מהשרת לבצע. הגדר error: true כדי להחזיר את גוף הטקסט כשגיאת כלי במקום זאת, או type: agent כדי שמודל קטן יענה בשם השרת מתוך הוראות שבגוף הטקסט. הסימוכין של קבצי mock מונה כל מפתח ואת הקבצים _server.md ו-_tools.json.

כדי לנקד את הקריאות עצמן, כוון בודק אל target: mock_calls.

כדי להריץ מול שרתי ה-MCP האמיתיים של התוסף במקום זאת, העבר אחד מדגלים אלה. בשני המקרים תהליכים אלה רצים תחת המשתמש שלך, מחוץ לארגז החול של ההרצה, והכלים שלהם זקוקים למתן הרשאה באמצעות --allow-tools:

• --allow-real-servers: הפעל את התהליך האמיתי עבור כל שרת שלא יצרת לו mock, והמשך לענות מתוך הקבצים עבור כלים שיש להם mock
• --mocks off: התעלם מ-mocks/ לחלוטין והפעל כל שרת שהתוסף מצהיר עליו

#שחזור (Replay) של תשובות mock מסוג agent

mock מסוג type: agent עונה באמצעות קריאה ל---judge-model, ולכן הפלט שלו משתנה בין הרצות ומשתנה אם אתה מחליף את השופט. כאשר הרצה מסתיימת ללא שגיאה או עצירה יזומה, Claude Code שומר כל תשובה שנתן mock מסוג agent תחת תיקיית התוצאות ב-mock-recordings/.

פתח שם את ADOPT.txt כדי לראות כל הקלטה ואת התיקייה .replay/<server>/ שאליה יש להעתיק אותה, לצד ה-mock שיצר אותה. לאחר שתעתיק הקלטה לשם, הרצות עתידיות יענו לקריאה הזהה מתוכה ללא קריאת מודל. בצע commit ל-mocks/.replay/ יחד עם שאר mocks/ כדי שהרצות CI יהיו ניתנות לשחזור.

#הרצת evals

ברגע שקיימת חבילה, claude plugin eval מריצה אותה. אתה בוחר איזה תוסף ואילו מקרים ירוצו באמצעות ארגומנט היעד (target), מעניק הרשאה לכל הכלים שהמקרים צריכים מעבר לערכת הקריאה בלבד באמצעות --allow-tools, ושולט במספר ההרצות, במודלים, בעלות ובפלט באמצעות האפשרויות האחרות.

#בחירה מה להעריך

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