📘 תיעוד 35

יצירת סוכני משנה מותאמים אישית

צור והשתמש בסוכני משנה (subagents) ייעודיים של AI ב-Claude Code עבור תהליכי עבודה ייעודיים למשימה וניהול הקשר (context) משופר.

סוכני משנה (subagents) הם עוזרי AI ייעודיים שמטפלים בסוגים מסוימים של משימות. השתמש באחד מהם כאשר משימת צד עלולה להציף את השיחה הראשית שלך בתוצאות חיפוש, יומנים (logs) או תכני קבצים שלא תתייחס אליהם שוב: סוכן המשנה מבצע את העבודה הזו בהקשר משלו ומחזיר רק את הסיכום. הגדר סוכן משנה מותאם אישית כאשר אתה מפעיל שוב ושוב את אותו סוג של עובד עם אותן הוראות.

כל סוכן משנה פועל בחלון הקשר משלו עם הוראת מערכת (system prompt) מותאמת אישית, גישה לכלים ספציפיים והרשאות עצמאיות. כאשר Claude נתקל במשימה שתואמת את התיאור של סוכן המשנה, הוא מאציל את המשימה לאותו סוכן משנה, שעובד באופן עצמאי ומחזיר תוצאות. כדי לראות את החיסכון בהקשר בפועל, המחשת חלון ההקשר (context window visualization) מדגימה הפעלה שבה סוכן משנה מטפל במחקר בחלון נפרד משלו.

הערה: סוכני משנה פועלים בתוך הפעלה (session) בודדת. כדי להריץ הפעלות עצמאיות רבות במקביל ולנטר אותן ממקום אחד, ראה סוכני רקע (background agents). עבור הפעלות נפרדות שמעבירות הודעות זו לזו, ראה העברת הודעות בין הפעלות (cross-session messaging). עבור צוות מתואם של הפעלות ש-Claude יוצר ומפקח עליהן, ראה צוותי סוכנים (agent teams).

סוכני משנה עוזרים לך:

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

Claude משתמש בתיאור של כל סוכן משנה כדי להחליט מתי להאציל משימות. כאשר אתה יוצר סוכן משנה, כתוב תיאור ברור כדי ש-Claude ידע מתי להשתמש בו.

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

#סוכני משנה מובנים

Claude Code כולל סוכני משנה מובנים ש-Claude משתמש בהם אוטומטית בעת הצורך. כל אחד מהם יורש את ההרשאות של שיחת ההורה, ורובם פועלים עם ערכת כלים מוגבלת.

Explore ו-Plan מדלגים על קובצי ה-CLAUDE.md שלך ועל מצב ה-git של הפעלת ההורה כדי לשמור על מחקר מהיר ולא יקר. כל סוכן מובנה אחר וסוכן משנה מותאם אישית טוענים את שניהם. לפירוט המלא של מה שמגיע לסוכן משנה, ראה מה נטען בעת ההפעלה.

#Explore

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

• מודל: יורש משיחת הראשית, מוגבל עד Opus ב-Claude API, כך ש-Explore לעולם אינו רץ על מודל יקר יותר מזה שכבר בחרת עבור ההפעלה, אלא אם תגדיר את CLAUDE_CODE_SUBAGENT_MODEL ותכפה אותו על כל סוכן משנה.
• כלים: כלי קריאה בלבד, הכלים Write ו-Edit נדחים.
• מטרה: גילוי קבצים, חיפוש קוד, חקר בסיס הקוד.

החל מגרסה v2.1.198, Explore יורש את המודל של השיחה הראשית במקום לרוץ תמיד על Haiku. ב-Claude API, המודל הנורש מוגבל ל-Opus: שיחה ראשית ברמה גבוהה יותר מריצה את Explore על Opus, ושיחה ראשית על Sonnet או Haiku מריצה את Explore על אותו מודל. בכל ספק אחר, כגון Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry או Claude Platform ב-AWS, Explore יורש את מודל השיחה הראשית ישירות.

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

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

בעת הפעלת Explore, Claude מציין רמת יסודיות: quick עבור איתורים ממוקדים, medium עבור חקר מאוזן, או very thorough עבור ניתוח מקיף.

#Plan

סוכן מחקר המשמש במהלך מצב תוכנית (plan mode) כדי לאסוף הקשר לפני הצגת תוכנית.

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

כאשר אתה במצב תוכנית ו-Claude צריך להבין את בסיס הקוד שלך, הוא מאציל את המחקר לסוכן המשנה Plan כך שפלט החקר נשאר בחלון הקשר נפרד בזמן שהשיחה הראשית נשארת במצב קריאה בלבד.

#General-purpose

סוכן בעל יכולות גבוהות עבור משימות מורכבות ומרובות שלבים הדורשות גם חקר וגם פעולה.

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

Claude מאציל ל-general-purpose כאשר המשימה דורשת הן חקר והן שינוי, הסקת מסקנות מורכבת לפירוש תוצאות, או מספר שלבים התלויים זה בזה.

#סוכנים אחרים

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

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

• כדי לחסום סוג מובנה ספציפי, הוסף אותו ל-permissions.deny כפי שמוצג בסעיף השבתת סוכני משנה ספציפיים.
• כדי למנוע מ-Claude להאציל משימות לכל סוכן משנה שהוא, דחה את הכלי Agent עצמו באמצעות permissions.deny.
• כדי להסיר רק את סוכני המשנה המובנים Explore ו-Plan, הגדר את CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude יקרא ויחקור קבצים ישירות במקום להאציל אליהם. דורש את Claude Code מגרסה v2.1.198 ומעלה.
• במצב לא אינטראקטיבי וב-Agent SDK, הגדר את CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 כדי להסיר את כל הסוגים המובנים ולספק רק סוכנים משלך.

קריאה לכלי Agent שמשמיטה את subagent_type נכשלת עם השגיאה subagent_type is required כאשר להפעלה אין סוכן משנה מסוג general-purpose שניתן לסגת אליו כברירת מחדל.

מעבר לסוכני משנה מובנים אלה, תוכל ליצור סוכנים משלך עם הוראות מותאמות אישית, הגבלות כלים, מצבי הרשאות, hooks ומיומנויות (skills). הסעיפים הבאים מראים כיצד להתחיל ולהתאים אישית סוכני משנה.

#התחלה מהירה: יצירת סוכן המשנה הראשון שלך

סוכני משנה הם קובצי Markdown עם YAML frontmatter. כדי ליצור אחד, בקש מ-Claude לכתוב אותו עבורך, או כתוב את הקובץ בעצמך.

החל מגרסה v2.1.198, הפקודה /agents אינה פותחת עוד את אשף היצירה האינטראקטיבי. הרצתה מדפיסה תזכורת לבקש מ-Claude או לערוך את .claude/agents/ ישירות. קובצי סוכני משנה, שדות ה-frontmatter והמיקומים .claude/agents/ ו-~/.claude/agents/ נותרו ללא שינוי, רק אשף הטרמינל הוסר.

מדריך זה יוצר סוכן משנה ברמת המשתמש שסוקר קוד ומציע שיפורים:

1. בקש מ-Claude ליצור את סוכן המשנה: ב-Claude Code, תאר את סוכן המשנה הרצוי והיכן לשמור אותו:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude כותב את הקובץ עם name, description, רשימת tools, model והוראת מערכת (system prompt).

2. סקור את הקובץ: פתח את ~/.claude/agents/code-improver.md וודא שה-frontmatter תואם למה שביקשת. התוצאה נראית כך:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

מכיוון שהקובץ נמצא ב-~/.claude/agents/, סוכן המשנה זמין בכל פרויקט במחשב שלך. כדי להגביל את הטווח שלו לפרויקט אחד בלבד, העבר אותו לתיקיית .claude/agents/ של אותו פרויקט. הסעיף בחירת טווח סוכן המשנה משווה בין השניים.

3. נסה אותו: בקש מ-Claude להאציל משימה לסוכן המשנה החדש:

Use the code-improver agent to suggest improvements in this project

Claude מאציל לסוכן המשנה החדש שלך, שסורק את בסיס הקוד ומחזיר הצעות לשיפור. בתמליל השיחה (transcript), ההאצלה מופיעה כשורה של קריאה לכלי המציגה את שם סוכן המשנה ולאחריו תיאור משימה קצר, כגון code-improver(Suggest code improvements).

אם Claude אינו מוצא את סוכן המשנה החדש, הפעל מחדש את Claude Code ונסה שוב. מצב זה מתרחש רק כאשר ~/.claude/agents/ לא הייתה קיימת לפני תחילת ההפעלה, כיוון שהפעלה פעילה אינה מזהה תיקיית agents שזה עתה נוצרה.

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

באפשרותך גם לכתוב קובצי סוכני משנה באופן ידני, להגדיר אותם באמצעות דגלי CLI, או להפיץ אותם באמצעות תוספים (plugins). הסעיפים הבאים מכסים את כל אפשרויות התצורה.

הערה: ב-Claude Code גרסה v2.1.197 ומטה, הפקודה /agents פותחת אשף אינטראקטיבי עם כרטיסיית Running המציגה סוכני משנה פעילים וכרטיסיית Library ליצירה, עריכה ומחיקה שלהם.

#הגדרת סוכני משנה

מיקום הקובץ של סוכן המשנה קובע עבור מי הוא זמין, וה-frontmatter שלו קובע מה הוא יכול לעשות. סעיף זה מכסה היכן קובצי סוכני משנה ממוקמים וכל שדה שהם תומכים בו.

#בחירת טווח סוכן המשנה

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

סוכני משנה של פרויקט (.claude/agents/) אידיאליים עבור סוכני משנה הספציפיים לבסיס קוד מסוים. בצע להם check-in למערכת בקרת הגרסאות כדי שהצוות שלך יוכל להשתמש בהם ולשפר אותם בשיתוף פעולה.

סוכני משנה של פרויקט מתגלים על ידי סריקה במעלה עץ התיקיות מתיקיית העבודה הנוכחית, כך שכל תיקיית .claude/agents/ בין המיקום הנוכחי לבין שורש המאגר נסרקת. החל מגרסה v2.1.178, כאשר יותר מאחת מתיקיות מקוננות אלו מגדירה את אותו ה-name, Claude Code משתמש בהגדרה הקרובה ביותר לתיקיית העבודה.

כאשר אתה מוסיף תיקייה באמצעות --add-dir או /add-dir, Claude Code טוען גם את תיקיית ה-.claude/agents/ שלה, לצד סוכני המשנה של הפרויקט שלך. ראה תיקיות נוספות לפרטים על סוגי תצורה אחרים הנטענים מ---add-dir. כדי לשתף סוכני משנה בין פרויקטים ללא --add-dir, השתמש ב-~/.claude/agents/ או בתוסף.

סוכני משנה של משתמש (~/.claude/agents/) הם סוכני משנה אישיים הזמינים בכל הפרויקטים שלך.

Claude Code סורק את .claude/agents/ ואת ~/.claude/agents/ באופן רקורסיבי, כך שתוכל לארגן הגדרות בתוך תת תיקיות כגון agents/review/ או agents/research/. נתיב תת התיקייה אינו משפיע על אופן הזיהוי או ההפעלה של סוכן המשנה, משום שהזהות נקבעת אך ורק על פי שדה ה-name ב-frontmatter.

שמור על ערכי name ייחודיים בכל העץ: אם שני קבצים תחת אותה תיקיית .claude/agents/, כולל תת התיקיות שלה, מצהירים על אותו שם, Claude Code טוען רק אחד מהם, שנבחר לפי סדר הקריאה של מערכת הקבצים ולא לפי קדימות מתועדת. בין תיקיות פרויקט מקוננות, ההגדרה הקרובה ביותר לתיקיית העבודה מנצחת, כפי שתואר לעיל. בדיקת התקינות של /doctor מדווחת על קבצים באותה תיקייה החולקים את אותו השם ומציעה לשנות את שמם או להסיר את כולם למעט אחד. לפני גרסה v2.1.205, הפקודה /doctor פתחה מסך אבחון שפירט כפילויות והציג איזו הגדרה פעילה.

תיקיות agents/ של תוספים נסרקות אף הן באופן רקורסיבי. שלא כמו בטווח של פרויקט ומשתמש, תת תיקייה בתוך תיקיית agents/ של תוסף הופכת לחלק מהמזהה התחום (scoped identifier): קובץ בנתיב agents/review/security.md בתוסף my-plugin נרשם כ-my-plugin:review:security.

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

עבור macOS, Linux, WSL:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

עבור Windows PowerShell:

claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

הדגל --agents מקבל JSON עם שדה prompt בתוספת שדות frontmatter אלה: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background ו-isolation. השתמש ב-prompt עבור הוראת המערכת, המקבילה לגוף ה-Markdown בסוכני משנה מבוססי קבצים. כל מפתח ברמה העליונה ב-JSON הוא שם הסוכן. אל תתחיל שם בתו -.

למידע על האופן שבו Claude Code מתמודד עם ערך שאינו מצליח לטעון, ועל הדגלים ומשתנה הסביבה שמדלגים על בדיקה זו, ראה Invalid --agents configuration.

סוכני משנה מנוהלים נפרסים על ידי מנהלי המערכת בארגון. מקם קובצי Markdown בתוך .claude/agents/ בתוך תיקיית ההגדרות המנוהלות, תוך שימוש באותו מבנה frontmatter כמו סוכני משנה של פרויקט ומשתמש. הגדרות מנוהלות מקבלות עדיפות על פני סוכני משנה של פרויקט ומשתמש בעלי אותו שם.

סוכני משנה של תוספים מגיעים מתוספים (plugins) שהתקנת. הם נטענים אוטומטית לצד סוכני המשנה המותאמים אישית שלך ומופיעים בהשלמה האוטומטית של אזכור @ תחת שמם התחום (scoped name). ראה את מדריך רכיבי התוספים לפרטים על יצירת סוכני משנה של תוספים.

הערה: מטעמי אבטחה, סוכני משנה של תוספים אינם תומכים בשדות ה-frontmatter הבאים: hooks, mcpServers או permissionMode. שדות אלה זוכים להתעלמות בעת טעינת סוכנים מתוסף. אם אתה זקוק להם, העתק את קובץ הסוכן לתוך .claude/agents/ או ~/.claude/agents/. באפשרותך גם להוסיף כללים אל permissions.allow בתוך settings.json או settings.local.json, אך כללים אלה חלים על כל ההפעלה כולה, ולא רק על סוכן המשנה של התוסף.

הגדרות סוכני משנה מכל אחד מטווחים אלה זמינות גם עבור צוותי סוכנים (agent teams): בעת יצירת חבר צוות, תוכל להתייחס לסוג סוכן משנה, ו-Claude Code יחיל חלקים מאותה הגדרה על חבר הצוות. ראה צוותי סוכנים לפרטים על אילו חלקים חלים בכל מצב תצוגה.

#כתיבת קובצי סוכני משנה

קובצי סוכני משנה משתמשים ב-YAML frontmatter עבור הגדרות תצורה, ולאחריו הוראת המערכת (system prompt) ב-Markdown:

הערה: Claude Code עוקב אחר השינויים ב-~/.claude/agents/ וב-.claude/agents/. כאשר אתה מוסיף או עורך קובץ סוכן משנה בדיסק, או מבקש מ-Claude לכתוב אחד עבורך, Claude Code מזהה את השינוי תוך מספר שניות וההאצלה הבאה תשתמש בהגדרה המעודכנת, ללא צורך בהפעלה מחדש.

שלושה מקרים עדיין דורשים הפעלה מחדש:

1. מנגנון המעקב מכסה רק תיקיות שהיו קיימות בעת תחילת ההפעלה, לכן לאחר יצירת קובץ סוכן ראשון בתיקיית agents חדשה, הפעל מחדש כדי לטעון אותו.
2. Claude Code אינו עוקב אחר .claude/agents/ בתוך תיקיות שנוספו באמצעות --add-dir או /add-dir, לכן לאחר הוספה או עריכה של סוכן משנה שם, הפעל מחדש כדי לטעון את השינוי.
3. הפעלות שהחלו עם --disable-slash-commands אינן עוקבות אחר תיקיות אלו כלל.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

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

במצב לא אינטראקטיבי, העבר את --append-subagent-system-prompt כדי להוסיף את הטקסט שלך לסוף הוראת המערכת של כל סוכן משנה, כולל סוכני משנה מקוננים, למעט סוכן משנה מפוצל (forked subagent), אשר עושה שימוש חוזר בהוראה של השיחה עצמה. דורש את Claude Code מגרסה v2.1.205 ומעלה. אם הטקסט שלך ארוך מכדי להעבירו בשורת הפקודה, שמור אותו בקובץ והעבר את הנתיב באמצעות הדגל --append-subagent-system-prompt-file. דגל הקובץ דורש את Claude Code מגרסה v2.1.261 ומעלה.

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

סוכן משנה עם isolation: worktree מריץ את פקודות ה-Bash וה-PowerShell שלו בתוך ה-worktree שלו. פקודה שתיקיית העבודה שלה פותרת לעותק המרכזי שלך במקום זאת, למשל משום שתיקיית ה-worktree הוסרה בזמן שסוכן המשנה רץ, נכשלת עם שגיאה. לפני גרסה v2.1.203, פקודה כזו יכלה לרוץ בעותק המרכזי.

בדיקת תיקיית עבודה זו מכסה את כל המאגר המכיל את התיקייה שממנה הפעלת את Claude Code. כאשר ההפעלה שלך רצה ב-worktree מקושר משל עצמה, הבדיקה מכסה גם את העותק המרכזי שממנו מקושר אותו worktree. לפני גרסה v2.1.210, הבדיקה כיסתה רק את תיקיית ההפעלה עצמה. פקודה שתיקיית העבודה שלה פתרה למיקום אחר באותו מאגר, כגון שורש המאגר כאשר הפעלת את Claude Code מתת תיקייה של monorepo, רצה שם במקום להיכשל.

עבור פקודות Bash, Claude Code בודק גם את הפקודה עצמה בשתי דרכים:

• הוא חוסם פקודה שמנתבת מחדש את git לעותק המרכזי.
• הוא מסרב להריץ פקודה כאשר אינו יכול לוודא מטקסט הפקודה שכל פעולת git שהפקודה מריצה נשארת בתוך ה-worktree, למשל כאשר שם הפקודה מחושב בזמן ריצה.

וקטורי הניתוב מחדש וכללי המבנה מפורטים תחת כיצד Claude Code אוכף בידוד. פקודות PowerShell עוברות רק את בדיקת תיקיית העבודה.

פקודות Monitor עוברות את אותן בדיקות תיקיית עבודה ותוכן פקודה כמו פקודות Bash.

כאשר השיחה הראשית עצמה פועלת מבודדת ב-worktree, Claude Code מחיל את אותן בדיקות על ההפעלה ועל כל סוכן משנה שהיא יוצרת, כולל סוכני משנה ללא isolation: worktree. ראה כיצד Claude Code אוכף בידוד.

#שדות frontmatter נתמכים

ניתן להשתמש בשדות הבאים ב-YAML frontmatter. רק name ו-description הם שדות חובה.

כתוב את cacheTtl בתוך המיפוי experimental, ולא ברמה העליונה של ה-frontmatter:

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

#קובצי סוכני משנה ש-Claude Code מדלג עליהם

Claude Code מדלג על קובץ בתיקיית agents של פרויקט, משתמש או הגדרות מנוהלות, או בתיקייה תחת נתיב שהוספת באמצעות --add-dir, מבלי לדווח על כך בהפעלה, כאשר ב-frontmatter יש אחת מהבעיות הבאות:

• אין name: Claude Code מתייחס לקובץ כתיעוד שנשמר לצד הסוכנים שלך.
• תווי --- הפותחים אינם בשורה הראשונה של הקובץ: Claude Code קורא את הקובץ כאילו אין לו frontmatter ומתייחס אליו כתיעוד.
• ערך name שמתחיל ב-- או מכיל :: Claude Code מדלג על הקובץ וכותב שגיאה ליומן הדיבאג. ראה שורת name בטבלה לעיל.
• קיים name אך אין description: Claude Code מדלג על הקובץ וכותב את הסיבה ליומן הדיבאג.
• YAML שאינו עובר ניתוח תחבירי (parse): Claude Code אינו קורא שדות מהקובץ, מדלג עליו וכותב את שגיאת הניתוח ליומן הדיבאג.

כדי לראות את יומן הדיבאג, הפעל את Claude Code עם --debug.

סוכן משנה של תוסף שה-frontmatter שלו חסר name או אינו עובר פענוח עדיין נטען, תחת שם הקובץ שלו.

#בדיקת תיקיית agents לפני הפעלה

כדי למצוא קבצים בתיקיית agents שה-frontmatter שלהם אינו עובר פענוח, הרץ claude plugin validate כנגד התיקייה, למשל .claude/agents או ~/.claude/agents. Claude Code בודק רק את התיקייה שציינת, ואינו מסמן קובץ שה-frontmatter שלו עבר פענוח אך אין לו name. דורש את Claude Code מגרסה v2.1.233 ומעלה.

#בחירת מודל

שדה ה-model שולט באיזה מודל סוכן המשנה משתמש:

• כינוי מודל (Model alias): השתמש באחד הכינויים הזמינים: sonnet, opus, haiku או fable.
• מזהה מודל מלא (Full model ID): השתמש במזהה מודל מלא כגון claude-opus-5 או claude-sonnet-5. מקבל את אותם ערכים כמו הדגל --model.
• inherit: השתמש באותו מודל כמו השיחה הראשית.

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

1. פרמטר ה-model המועבר לכל הפעלה ספציפית
2. שדה ה-model ב-frontmatter של הגדרת סוכן המשנה, שבו inherit בוחר את מודל השיחה הראשית
3. משתנה הסביבה CLAUDE_CODE_SUBAGENT_MODEL, כאשר אתה מגדיר אותו לכינוי מודל או למזהה מודל
4. המודל של השיחה הראשית

הגדרת CLAUDE_CODE_SUBAGENT_MODEL כשלעצמה אינה משנה את המודל שעליו רצים סוכני המשנה המובנים Explore ו-Plan. כדי לשנות אותו, ראה הרצת כל סוכני המשנה על מודל יחיד.

לפני גרסה v2.1.251, המשתנה CLAUDE_CODE_SUBAGENT_MODEL הופיע ראשון בסדר זה ודרס הן את הפרמטר של ההפעלה והן את ה-frontmatter, כולל model: inherit.

הגדרת המשתנה ל-inherit זהה להשארתו ריק. לפני גרסה v2.1.196, ערך זה כפה על סוכני המשנה לעבור למודל השיחה הראשית והתעלם מהמקורות האחרים.

Claude Code בודק את ערכי הפרמטר של ההפעלה, ה-frontmatter ומשתנה הסביבה מול רשימת המורשים של הארגון שלך, availableModels. עבור ערך חסום, הוא מחליף אותו במודל אחר:

• כאשר הערך החסום הוא כינוי משפחה כגון opus, Claude Code מריץ את סוכן המשנה על הגרסה החדשה ביותר של אותה משפחה שרשימת המורשים מתירה, בהתאם לאותם כללי החלפה וטווח ספקים של הפקודה /model. לפני גרסה v2.1.222, Claude Code הריץ את סוכן המשנה על המודל הנורש גם עבור כינוי משפחה חסום.
• עבור כל ערך חסום אחר, אצל ספקים שבהם החלפה זו אינה פועלת, או כאשר רשימת המורשים אינה מתירה אף גרסה של המשפחה, Claude Code מריץ את סוכן המשנה על המודל הנורש במקום זאת. אם הגדרת את CLAUDE_CODE_SUBAGENT_MODEL, Claude Code מנסה מודל זה תחילה, תחת אותם כללים.

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

כדי לבדוק על איזה מודל סוכן משנה רץ, הרץ /tasks. Claude Code מציין את המודל בשורת סוכן המשנה, ומוסיף את רמת המאמץ (effort level) כאשר הגדרת סוכן המשנה, או המיומנות שממנה התפצל, מגדירה effort. דורש את Claude Code מגרסה v2.1.242 ומעלה.

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

החל מגרסה v2.1.198, סוכני משנה יורשים גם את תצורת החשיבה המורחבת (extended thinking) של השיחה הראשית: אם חשיבה מופעלת בהפעלה שלך, היא מופעלת עבור סוכן המשנה, ואם היא כבויה, היא נשארת כבויה. אין הגדרת חשיבה ייעודית לכל סוכן משנה. לפני גרסה v2.1.198, סוכני משנה פעלו עם חשיבה מורחבת מושבתת ללא קשר להגדרת השיחה הראשית.

#הרצת כל סוכני המשנה על מודל יחיד

המשתנה CLAUDE_CODE_SUBAGENT_MODEL משמש כברירת מחדל, ולכן הגדרת סוכן משנה או מודל ש-Claude מעביר עדיין קודמים לו. כדי להחיל מודל אחד על כל סוכן משנה, חבר צוות (teammate) וסוכן תהליך עבודה (workflow agent), הגדר בנוסף את CLAUDE_CODE_SUBAGENT_MODEL_FORCE כ-1. דורש את Claude Code מגרסה v2.1.257 ומעלה.

• אם תגדיר את שני המשתנים, סוכני משנה ירוצו על המודל שב-CLAUDE_CODE_SUBAGENT_MODEL.
• אם תגדיר רק את CLAUDE_CODE_SUBAGENT_MODEL_FORCE, סוכני משנה ירוצו על מודל השיחה הראשית.

לדוגמה, כדי להריץ כל סוכן משנה על Haiku, הגדר את שני המשתנים בבלוק env של קובץ הגדרות:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

כדי לוודא שההגדרה נכנסה לתוקף, הרץ /tasks בזמן שסוכן משנה רץ. שורת סוכן המשנה מציגה את המודל שעליו הוא פועל.

בזמן ש-CLAUDE_CODE_SUBAGENT_MODEL_FORCE מופעל, Claude Code מתעלם משדה ה-model של כל הגדרת סוכן משנה, כולל סוכני המשנה המובנים Explore ו-Plan, ו-Claude אינו יכול להעביר מודל בעת הפעלת סוכן משנה. שני סוגים של סוכני משנה עדיין רצים על מודל השיחה הראשית:

• פיצול (fork)
• מיומנות הרצה בסוכן משנה עם model: inherit

כאשר אתה מגדיר רק את CLAUDE_CODE_SUBAGENT_MODEL_FORCE, סוכן המשנה המובנה Explore שומר על מגבלת המודל שלו.

#שליטה ביכולות של סוכן המשנה

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

#כלים זמינים

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

• Agent, כאשר סוכן המשנה נמצא במגבלת העומק. בפיצול הכלי נשאר רשום אך מחזיר שגיאה במקום ליצור סוכן
• AskUserQuestion
• EndConversation, שיכול לסיים רק את השיחה הראשית. ראה התנהגות הכלי EndConversation
• EnterPlanMode
• ExitPlanMode, אלא אם כן ה-permissionMode של סוכן המשנה הוא plan
• ScheduleWakeup
• TaskOutput
• WaitForMcpServers
• Workflow

המסנן השני חל על סוכני משנה הפועלים ברקע. מלבד Agent ו-ExitPlanMode, הפועלים לפי תנאי המסנן הראשון בכל מקום שבו סוכן המשנה רץ, סוכן משנה ברקע שומר על כל כלי MCP אך רק על הכלים המובנים הבאים: Read, Grep, Glob, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage ו-Artifact. Claude Code מסיר כל כלי מובנה אחר מסוכן משנה ברקע, בין אם נורש ובין אם צוין בשדה tools, כך שאותה הגדרה יכולה להניב כלים שונים בחזית וברקע. ההסרה אינה מדווחת על שגיאה אלא אם היא משאירה את רשימת ה-tools ללא אף כלי תקף. הכלי ListAgents פועל לפי מסננים אלה כמו כל כלי מובנה: סוכן משנה בחזית יורש אותו בהפעלות שבהן העברת הודעות בין הפעלות מופעלת, וסוכן משנה ברקע אינו שומר עליו.

חברי צוות בצוותי סוכנים שומרים בנוסף על כלי המשימות וכלי ה-cron הבאים: TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete ו-CronList.

בהפעלה ללא כלי Task, Claude Code אינו מספק את כלי ה-Task גם לסוכני משנה, גם כאשר סוכן המשנה מריץ מודל אחר. חבר צוות הפועל בתוך אותו תהליך (in-process) פועל לפי ההפעלה שלך באותו אופן, בעוד שחבר צוות בתוך חלון מפוצל (split pane) משלו רץ כתהליך Claude Code נפרד, כך שהמודל שלו קובע.

כדי להגביל כלים, השתמש בשדה tools כרשימת מורשים (allowlist) או בשדה disallowedTools כרשימת חסומים (denylist). דוגמה זו משתמשת ב-tools כדי לאפשר רק את Read, Grep, Glob ו-Bash. סוכן המשנה אינו יכול לערוך קבצים, לכתוב קבצים או להשתמש בכלי MCP כלשהם:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

דוגמה זו משתמשת ב-disallowedTools כדי לרשת את מאגר הכלים של סוכן המשנה למעט Write ו-Edit. סוכן המשנה שומר על Bash, כלי MCP ושאר מאגר הכלים שלו:

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

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

כאשר אף ערך ברשימת ה-tools אינו מתאים לכלי מוכר, למשל משום שכל הערכים מאויתים בשגיאה או מציינים כלי שאינו זמין לסוכני משנה, Claude Code בדרך כלל מסרב להפעיל את סוכן המשנה והכלי Agent מחזיר שגיאה המציינת את הערכים שלא נפתרו. ראה Agent would be spawned with zero tools לנוסח ההודעה וכיצד לתקן כל ערך. לפני גרסה v2.1.208, סוכן משנה כזה הופעל ללא כלים כלל ויכול היה להחזיר תוצאה ריקה או מבלבלת.

שני השדות מקבלים תבניות ברמת שרת MCP בנוסף לשמות כלים מדויקים: mcp__<server> או mcp__<server>__* מעניק או מסיר כל כלי מהשרת הנקוב. ב-disallowedTools, התבנית mcp__* מסירה בנוסף כל כלי MCP מכל שרת שהוא. דוגמה זו מסירה כל כלי משרת ה-MCP בשם github תוך שמירה על כלים משרתים אחרים והכלים המובנים במאגר שלו:

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

#הגבלת סוכני המשנה שניתן להפעיל

כאשר סוכן פועל כתהליך הראשי באמצעות claude --agent, הוא יכול להפעיל סוכני משנה באמצעות הכלי Agent. כדי להגביל אילו סוגי סוכני משנה הוא יכול להפעיל, השתמש בתחביר Agent(agent_type) בתוך שדה ה-tools.

הערה: בגרסה 2.1.63 שונה שמו של הכלי Task ל-Agent. הפניות קיימות ל-Task(...) בהגדרות ובהגדרות סוכנים עדיין פועלות ככינויים.

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

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

כדי לאפשר יצירת כל סוכן משנה ללא הגבלות, השתמש ב-Agent ללא סוגריים:

tools: Agent, Read, Bash

אם תשמיט את Agent לחלוטין מרשימת ה-tools, הסוכן לא יוכל להפעיל סוכני משנה כלל באמצעות הכלי Agent.

תחביר רשימת המורשים Agent(agent_type) תקף רק עבור סוכן הפועל כתהליך הראשי באמצעות claude --agent. בהגדרת סוכן משנה, רישום Agent ב-tools מאפשר לאותו סוכן משנה להפעיל סוכני משנה משלו כל עוד מגבלת העומק מתירה זאת, אך כל רשימת סוגים בתוך הסוגריים זוכה להתעלמות.

#הגדרת שרתי MCP לסוכן משנה ספציפי

השתמש בשדה mcpServers כדי להעניק לסוכן משנה גישה לשרתי MCP שאינם זמינים בשיחה הראשית. שרתים המוגדרים ישירות (inline) כאן מחוברים בעת הפעלת סוכן המשנה, בכפוף לכלל האמון עבור תיקיית קובץ הסוכן, ומנותקים כאשר הוא מסיים. הפניות טקסטואליות חולקות את החיבור של הפעלת ההורה.

הערה: שדה ה-mcpServers תקף בשני ההקשרים שבהם קובץ סוכן יכול לרוץ:

• כסוכן משנה, שנוצר באמצעות הכלי Agent או אזכור @
• כהפעלה הראשית, שהופעלה באמצעות --agent או הגדרת agent

כאשר הסוכן הוא ההפעלה הראשית, הגדרות שרת ישירות (inline) מתחברות בהפעלה לצד שרתים מ-.mcp.json ומקובצי הגדרות, תחת אותו כלל אמון עבור תיקיית קובץ הסוכן. בתוך /mcp, שרת מרוחק (HTTP או SSE) שהשתמשת בו בעבר יכול להציג את הסטטוס cached במקום זאת. Claude Code מחבר אותו כאשר Claude קורא לראשונה לאחד הכלים שלו.

כל רשומה ברשימה היא הגדרת שרת ישירה או מחרוזת המתייחסת לשרת MCP שכבר הוגדר בהפעלה שלך:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  
# הגדרה ישירה: מוגבלת לסוכן משנה זה בלבד
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  
# הפניה לפי שם: שימוש חוזר בשרת שכבר הוגדר
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

הגדרות ישירות (inline) משתמשות באותו מבנה נתונים כמו רשומות שרת ב-.mcp.json, עם שם השרת כמפתח, ותומכות בסוגים stdio, http, sse ו-ws.

כדי להשאיר שרת MCP מחוץ לשיחה הראשית לחלוטין ולמנוע מתיאורי הכלים שלו לצרוך הקשר שם, הגדר אותו ישירות כאן ולא בתוך .mcp.json. סוכן המשנה מקבל את הכלים, והשיחה הראשית לא.

Claude Code טוען שרת ישיר מקובץ סוכן בתיקיית .claude/agents/ של הפרויקט שלך, או בתיקיית .claude/agents/ של תיקיית --add-dir, רק לאחר שאישרת אמון בתיקייה שממנה הגיע קובץ הסוכן. לפני גרסה v2.1.238, Claude Code טען שרתים אלה מבלי לבדוק אמון.

• אמון שאינו נחשב: אמון בתיקיית אב, והאמון האוטומטי שהפעלה עם -p או SDK מקבלת עבור הוקים בקובצי הגדרות.
• עד לאישור: Claude Code מדלג על כל שרת ישיר באותו קובץ סוכן וכותב את מפתח ה-projects["<path>"].hasTrustDialogAccepted המדויק עבור ~/.claude.json ליומן הדיבאג.
• תיקיות --add-dir: תיקייה מחוץ למאגר של סביבת העבודה המהימנה שלך זקוקה לרשומת אמון משלה, כיוון שקובצי ה-.claude/agents/ שלה אינם יורשים את האמון של סביבת העבודה שלך.

Claude Code טוען שני סוגי שרתים מבלי לבדוק אמון עבור התיקייה שממנה הגיע קובץ הסוכן:

• שם המתייחס לשרת שכבר הגדרת
• שרת ישיר בקובץ סוכן מתוך ~/.claude/agents/, בקובץ שהעברת עם --agents או אפשרות agents ב-SDK, או בקובץ שההגדרות המנוהלות מספקות

החל מגרסה v2.1.153, הגבלות ה-MCP החלות על ההפעלה הראשית מכסות גם שרתים המוצהרים ב-frontmatter של סוכן משנה:

• --strict-mcp-config ו---bare
• תצורת MCP מנוהלת לארגונים
• מדיניות allowedMcpServers ו-deniedMcpServers

כאשר אחת מאלו חוסמת שרת, Claude Code מדלג עליו ומציג אזהרה המציינת את השרתים שנחסמו.

הגבלות הגדרות מנוהלות חלות על כל סוכן משנה ללא קשר לאופן שבו הוגדר. הדגל --strict-mcp-config אינו מסנן שרתים שאתה מעביר ישירות דרך --agents או דרך אפשרות agents ב-SDK, כיוון שאלה קלטים מפורשים של המפעיל.

#מצבי הרשאות

הגדר את permissionMode כדי לבחור את מצב ההרשאות שבו סוכן המשנה פועל. השתמש בערכי התצורה של המצבים, כך שמצב ידני (Manual) הוא default. אם תשאיר אותו ריק, סוכן המשנה יירש את מצב השיחה הראשית, אשר מתחיל כמצב אוטומטי (auto mode) בתוכניות Pro, Max ו-Team, אלא אם ההגדרות שלך או הארגון שלך שינו זאת. הגדרת השדה דורסת מצב זה, למעט במקרים המתוארים להלן.

אזהרה: השתמש ב-bypassPermissions בזהירות. הוא מדלג על בקשות הרשאה ומאפשר לסוכן המשנה לבצע פעולות ללא אישור, כולל כתיבה לנתיבים .git, .config/git, .claude, .vscode, .idea, .husky, .cargo, .devcontainer, .yarn ו-.mvn.

גם במצב זה, הפעולות שאף מצב אינו מאשר אוטומטית עדיין חלות. ראה מצבי הרשאות לפרטים.

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

אם מצב עקיפה (bypass) מושבת על ידי permissions.disableBypassPermissionsMode, Claude Code מתעלם מההגדרה permissionMode: bypassPermissions ב-frontmatter וסוכן המשנה רץ עם המצב של הפעלת ההורה. לפני גרסה v2.1.223, Claude Code החיל את המצב מה-frontmatter גם כאשר העקיפה הושבתה.

#טעינה מראש של מיומנויות לתוך סוכני משנה

השתמש בשדה skills כדי להזריק תוכן של מיומנויות (skills) להקשר של סוכן המשנה בעת ההפעלה. הדבר מעניק לסוכן המשנה ידע מקצועי בתחום מבלי לדרוש ממנו לגלות ולטעון מיומנויות במהלך הריצה.

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

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

לא ניתן לטעון מראש מיומנויות שמגדירות disable-model-invocation: true, מכיוון שטעינה מראש נשענת על אותה ערכת מיומנויות ש-Claude מוסמך להפעיל. זה כולל את מיומנות /verify המצורפת: רק אתה יכול להריץ אותה, ולכן לא ניתן לטעון אותה מראש.

אם מיומנות ברשימה חסרה או מושבתת, למשל על פי מדיניות הארגון שלך, Claude Code מדלג עליה ורושם אזהרה ליומן הדיבאג.

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

#הפעלת זיכרון מתמיד

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

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

בחר טווח בהתאם למידת התחולה הרצויה של הזיכרון:

זיכרון סוכן משנה הוא חלק מזיכרון אוטומטי (auto memory): אם תכבה את הזיכרון האוטומטי, באמצעות ההגדרה autoMemoryEnabled או המשתנה CLAUDE_CODE_DISABLE_AUTO_MEMORY, לשדה memory לא תהיה כל השפעה וסוכן המשנה יופעל ללא הוראות הזיכרון או גישת כלי הזיכרון המתוארים להלן.

כאשר זיכרון מופעל:

• הוראת המערכת של סוכן המשנה כוללת הוראות לקריאה וכתיבה לתיקיית הזיכרון.
• הוראת המערכת של סוכן המשנה כוללת גם את 200 השורות הראשונות או 25KB הראשונים של MEMORY.md בתיקיית הזיכרון, הנמוך מביניהם, עם הוראות לתמצת ולתחזק את MEMORY.md אם הוא חורג ממגבלה זו.
• הכלים Read, Write ו-Edit מופעלים אוטומטית כדי שסוכן המשנה יוכל לנהל את קובצי הזיכרון שלו.

#טיפים לזיכרון מתמיד

• הטווח project הוא ברירת המחדל המומלצת. הוא מאפשר לשתף את הידע של סוכן המשנה באמצעות בקרת גרסאות.
• בקש מסוכן המשנה לעיין בזיכרון שלו לפני תחילת העבודה: "Review this PR, and check your memory for patterns you've seen before".
• בקש מסוכן המשנה לעדכן את הזיכרון שלו לאחר סיום משימה: "Now that you're done, save what you learned to your memory". לאורך זמן, פעולה זו בונה בסיס ידע שהופך את סוכן המשנה ליעיל יותר.
• כלול הוראות זיכרון ישירות בקובץ ה-Markdown של סוכן המשנה כדי שיתחזק באופן יזום את בסיס הידע שלו:

Update your agent memory as you discover codepaths, patterns, library
locations, and key architectural decisions. This builds up institutional
knowledge across conversations. Write concise notes about what you found
and where.

#כללים מותנים באמצעות hooks

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

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

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Claude Code מעביר קלט הוק כמבנה JSON דרך stdin לפקודות ההוק. סקריפט האימות קורא JSON זה, מחלץ את פקודת ה-Bash, ויוצא עם קוד 2 כדי לחסום פעולות כתיבה:

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

ב-macOS וב-Linux, הפוך את הסקריפט לקובץ בר-ביצוע, אחרת ההוק ייכשל במקום לחסום פעולות:

chmod +x ./scripts/validate-readonly-query.sh

כדי לבדוק את הכלל, בקש מסוכן המשנה להריץ פקודת UPDATE: הסקריפט יוצא עם קוד 2, Claude Code חוסם את הפקודה, וסוכן המשנה מקבל את ההודעה Blocked: Only SELECT queries are allowed.

ראה קלט הוק למבנה הקלט המלא וקודי יציאה להשפעת קודי יציאה על ההתנהגות. ב-Windows, כתוב סקריפטים של הוקים ב-PowerShell והוסף shell: powershell לרשומת ההוק כפי שמוצג בהרצת הוקים ב-PowerShell.

#השבתת סוכני משנה ספציפיים

באפשרותך למנוע מ-Claude להשתמש בסוכני משנה ספציפיים על ידי הוספתם למערך ה-deny בהגדרות שלך. השתמש במבנה Agent(subagent-name) כאשר subagent-name תואם לשדה ה-name של סוכן המשנה.

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

פעולה זו עובדת הן עבור סוכני משנה מובנים והן עבור סוכנים מותאמים אישית. תוכל גם להשתמש בדגל ה-CLI בשם --disallowedTools:

claude --disallowedTools "Agent(Explore)"

ראה תיעוד הרשאות לפרטים נוספים על כללי הרשאות.

#הגדרת hooks עבור סוכני משנה

סוכני משנה יכולים להגדיר הוקים (hooks) הרצים במהלך מחזור החיים של סוכן המשנה. ישנן שתי דרכים להגדיר הוקים:

• ב-frontmatter של סוכן המשנה: הגדרת הוקים הרצים רק כאשר אותו סוכן משנה פעיל.
• בתוך settings.json: הגדרת הוקים לכלל ההפעלה אשר מופעלים גם בתוך סוכני משנה. אירועי כלים כגון PreToolUse ו-PostToolUse מופעלים עבור קריאות הכלים של סוכן המשנה באותו אופן שבו הם מופעלים בשיחה הראשית, ו-SubagentStart ו-SubagentStop מופעלים כאשר סוכן משנה מתחיל או מסיים.

הוקים מקובצי הגדרות, הגדרות מדיניות מנוהלות ותוספים חלים כולם בתוך סוכני משנה, כך שהוק PreToolUse ב-settings.json רץ גם לפני כל כלי שסוכן משנה משתמש בו.

#Hooks ב-frontmatter של סוכן המשנה

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

הערה: הוקים ב-frontmatter מופעלים כאשר הסוכן נוצר כסוכן משנה באמצעות הכלי Agent או אזכור @, וכן כאשר הסוכן רץ כהפעלה הראשית באמצעות --agent או הגדרת agent. במקרה של הפעלה ראשית, הם רצים לצד כל ההוקים המוגדרים ב-settings.json.

כדי לאפשר להוקים ב-frontmatter של סוכן משנה ברמת הפרויקט לרוץ, אשר את תיבת הדו-שיח של אמון בסביבת העבודה עבור התיקייה המכילה את קובץ הסוכן. הוקים מסוכני משנה ברמת המשתמש ב-~/.claude/agents/ ומהגדרות שאתה מעביר עם --agents רצים ללא שלב זה. אם הוספת תיקייה עם --add-dir מחוץ למאגר של סביבת העבודה המהימנה שלך, אשר אמון בתיקייה זו בנפרד: הוקים של .claude/agents/ שלה אינם יורשים את האישור של סביבת העבודה.

עד שתאשר אמון בתיקייה, סוכן המשנה עדיין ירוץ, אך Claude Code ידלג על הוקי ה-frontmatter שלו וירשום שגיאה ליומן הדיבאג המסבירה כיצד לאשר אמון בתיקייה. זהו כלל מחמיר יותר מזה של הוקים בקובצי הגדרות: מתן אמון בתיקיית אב אינו מספיק, והפעלה עם -p אינה נחשבת כמהימנה. הסעיף מה רץ לפני שאתה נותן אמון בתיקייה משווה בין השניים. לפני גרסה v2.1.218, הוקים ב-frontmatter יכלו לרוץ מתיקיות שלא נתת בהן אמון, כולל בהפעלות לא אינטראקטיביות.

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

דוגמה זו מאמתת פקודות Bash באמצעות ההוק PreToolUse ומריצה linter לאחר עריכת קבצים באמצעות PostToolUse:

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

כאשר הסוכן מופעל כסוכן משנה, הוקים של Stop ב-frontmatter מומרים אוטומטית לאירועי SubagentStop.

#Hooks ברמת הפרויקט עבור אירועי סוכני משנה

הגדר הוקים ב-settings.json המגיבים לאירועי מחזור החיים של סוכני משנה בהפעלה הראשית.

דוגמה זו מריצה סקריפט הגדרה רק כאשר סוכן המשנה db-agent מתחיל, וסקריפט ניקוי כאשר סוכן משנה כלשהו עוצר:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

התאמה עם מקף כמו db-agent מתאימה במדויק ב-Claude Code גרסה v2.1.195 ומעלה. בגרסאות קודמות היא מוערכת כביטוי רגולרי ללא עיגון ומופעלת גם עבור כל סוג סוכן המכיל אותה, כגון prod-db-agent. בגרסאות אלו עגן אותה כ-^db-agent$.

ראה הוקים למבנה התצורה המלא של הוקים.

#עבודה עם סוכני משנה

#הבנת האצלה אוטומטית

Claude מאציל משימות באופן אוטומטי בהתבסס על תיאור המשימה בבקשתך, שדה ה-description בתצורות סוכני המשנה וההקשר הנוכחי. כדי לעודד האצלה יזומה, כלול ביטויים כמו "use proactively" בשדה התיאור של סוכן המשנה שלך.

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

#הפעלת סוכני משנה באופן מפורש

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

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

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

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

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

@"code-reviewer (agent)" look at the auth changes

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

סוכני משנה המסופקים על ידי תוסף (plugin) מופעל מופיעים בתפריט ההשלמה תחת שמם התחום, כגון my-plugin:code-reviewer או my-plugin:review:security כאשר התוסף מארגן סוכנים בתת תיקיות. סוכני משנה בעלי שם הפועלים ברקע בהפעלה זו מופיעים אף הם בתפריט ההשלמה ומציגים את הסטטוס שלהם לצד שמם.

תוכל גם להקליד את האזכור ידנית מבלי להשתמש בתפריט: @agent-<name> עבור סוכני משנה מקומיים, או @agent- ולאחריו השם התחום עבור סוכני משנה של תוספים, לדוגמה @agent-my-plugin:code-reviewer. בזמן שאתה מקליד תבנית זו תפריט ההשלמה מציג התאמות לקבצים ולא לסוכנים. אזכור הסוכן עדיין מתפענח כאשר אתה שולח את ההודעה.

הרצת כל ההפעלה כסוכן משנה: העבר את --agent <name> כדי להתחיל הפעלה שבה התהליך הראשי עצמו מקבל את הוראת המערכת, הגבלות הכלים והמודל של אותו סוכן משנה:

claude --agent code-reviewer

הוראת המערכת של סוכן המשנה מחליפה את הוראת המערכת הרגילה של Claude Code במלואה, בדיוק כפי שעושה הדגל --system-prompt. קובצי CLAUDE.md וזיכרון הפרויקט עדיין נטענים דרך זרימת ההודעות הרגילה. שם הסוכן מופיע כ-@<name> בכותרת ההפעלה כדי שתוכל לוודא שהוא פעיל.

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

עבור סוכן משנה המסופק על ידי תוסף, תוכל להעביר רק את שם הסוכן ו-Claude Code ימצא אותו:

claude --agent security-reviewer

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

claude --agent my-plugin:security-reviewer

אם התוסף ממקם את הסוכן בתת תיקייה של תיקיית ה-agents/ שלו, כלול את תת התיקייה בשם התחום, לדוגמה claude --agent my-plugin:review:security.

כדי להפוך זאת לברירת המחדל עבור כל הפעלה בפרויקט, הגדר את agent בתוך .claude/settings.json:

{
  "agent": "code-reviewer"
}

דגל ה-CLI גובר על ההגדרה אם שניהם קיימים.

#הרצת סוכני משנה בחזית או ברקע

סוכני משנה יכולים לפעול בחזית (foreground) או ברקע (background):

• סוכני משנה בחזית חוסמים את השיחה הראשית עד להשלמתם. בקשות הרשאה מועברות ישירות אליך כשהן עולות.
• סוכני משנה ברקע פועלים במקביל בזמן שאתה ממשיך לעבוד. כאשר סוכן משנה ברקע מגיע לקריאת כלי הדורשת הרשאה, Claude Code מעלה את הבקשה בשיחה הראשית ומציין את שם סוכן המשנה המבקש. אשר כדי לאפשר לסוכן המשנה להמשיך, או הקש Esc כדי לדחות את אותה קריאת כלי מבלי לעצור את סוכן המשנה. לפני גרסה v2.1.186, סוכני משנה ברקע דחו אוטומטית כל קריאת כלי שדרשה אישור.

עבור כל סוכן משנה ש-Claude יוצר באמצעות הכלי Agent, Claude Code בוחר בחזית או ברקע לפי המקרה הראשון שמתקיים מבין הבאים:

1. אם חבר צוות מאותו תהליך של צוות סוכנים יצר את סוכן המשנה, Claude Code מריץ אותו בחזית. Claude Code מסרב עם שגיאה ליצור סוכן משנה של חבר צוות שהגדרתו קובעת background: true. במקומות שבהם מצב פיצול (fork mode) כבוי ולא כיבית משימות רקע, Claude Code מסרב עם שגיאה גם כאשר חבר צוות מגדיר run_in_background: true.
2. אם תגדיר את CLAUDE_CODE_DISABLE_BACKGROUND_TASKS כ-1, Claude Code יריץ את סוכן המשנה בחזית, בכל סוג של הפעלה ובין אם מצב פיצול מופעל ובין אם לאו.
3. במקומות שבהם מצב פיצול מופעל, כפי שהוא כברירת מחדל בהפעלה אינטראקטיבית, Claude Code מריץ את סוכן המשנה ברקע, הן פיצולים והן סוכני משנה שאינם פיצול, ו-Claude אינו יכול לבקש הרצה בחזית.
4. במקומות שבהם מצב פיצול כבוי, Claude מריץ את סוכן המשנה ברקע כברירת מחדל ובחזית כאשר הוא זקוק לתוצאה לפני שימשיך. מצב פיצול כבוי במצב לא אינטראקטיבי עם -p וב-Agent SDK אלא אם תפעיל אותו. כדי להשאיר סוכן משנה מסוים ברקע גם כאשר Claude רוצה את התוצאה מיידית, הגדר את שדה ה-frontmatter שלו background ל-true.

עבור מיומנות עם context: fork, Claude Code פועל לפי הכללים בהרצת מיומנויות בסוכן משנה במקום זאת, בין אם מצב פיצול מופעל ובין אם לאו.

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

סוכן משנה ברקע יכול להשאיר פקודת Bash או PowerShell ברקע הפועלת מעבר לסיום התור שלו. כאשר פקודה זו מסתיימת, Claude Code שולח לסוכן המשנה הודעה.

תוצאותיו של סוכן משנה ברקע מגיעות ל-Claude כהודעת השלמה בתור מאוחר יותר. Claude ממתין להודעה זו לפני שהוא מדווח על תוצאות סוכן המשנה, ואם תשאל על ההתקדמות לפני כן, הוא ידווח שסוכן המשנה עדיין רץ. לפני גרסה v2.1.211, Claude דיווח לעיתים על תוצאות עבור סוכן משנה ברקע שטרם סיים את עבודתו.

באפשרותך גם לכוון זאת בעצמך:

• במקומות שבהם מצב פיצול כבוי, בקש מ-Claude להריץ משימה ברקע או בחזית.
• הקש Ctrl+B כדי להעביר משימה פעילה לרקע.

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

• כאשר סוכן משנה מסיים בהצלחה, Claude Code מסיר את השורה שלו באופן מיידי, ולמעט במצב קורא מסך, מציג /tasks to see subagents בשורת המידע התחתונה למשך 30 שניות. במהלך 30 שניות אלו, הרץ /tasks והקש Enter על סוכן המשנה כדי לפתוח את תמליל השיחה שלו. לפני גרסה v2.1.232, Claude Code שמר את השורה למשך 30 שניות לאחר סיום סוכן המשנה, בדומה לסוכן שנכשל, ולא הציג רמז בשורת המידע התחתונה.
• כאשר סוכן משנה נכשל או שאתה עוצר אותו, Claude Code שומר את השורה שלו למשך 30 שניות. כדי לנקות את השורה מוקדם יותר, בחר בה והקש x.

סוכן משנה ברקע שהושלם נשאר רשום ב-/tasks, מסומן כהושלם וממוין מתחת לעבודה פעילה, עבור אותו חלון זמן של הרמז התחתון שצוין לעיל. תצוגת הפרטים שלו נשארת פתוחה כאשר סוכן המשנה מסיים. סוכני משנה שנכשלים או שאתה עוצר יוצאים מהרשימה. לפני גרסה v2.1.208, סוכן משנה שהושלם יצא מהרשימה ברגע שסיים ותצוגת הפרטים שלו נסגרה.

#שמות סוכני משנה

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

בהפעלה אינטראקטיבית שבה צוותי סוכנים מופעלים, סוכן משנה ש-Claude יוצר מהשיחה הראשית עם name מופעל כחבר צוות במקום זאת, אלא אם הקריאה היא פיצול (fork) או מעבירה isolation בקריאה עצמה. ערך isolation ב-frontmatter של סוכן המשנה אינו מונע זאת, וחבר הצוות רץ אז בתיקיית העבודה של ההפעלה הראשית. ראה כיצד Claude מתחיל צוותי סוכנים.

#שגיאות API בסוכני משנה

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

החל מגרסה v2.1.199, סוכן משנה שריצתו מסתיימת בשגיאת API, כגון מגבלת שימוש או שגיאת שרת חוזרת, מדווח על כשל זה בחזרה ל-Claude במקום להחזיר את טקסט השגיאה כאילו היה ממצאיו של סוכן המשנה. מה ש-Claude מקבל תלוי במקום שבו סוכן המשנה רץ:

• חזית (Foreground): אם מגבלת קצב, עומס יתר או שגיאת שרת קוטעים סוכן משנה שכבר הפיק פלט טקסטואלי, הכלי Agent מחזיר את הפלט החלקי בצירוף הערה שסוכן המשנה נקטע ולא השלים את משימתו. סוכן משנה שלא הפיק דבר, או שכל פלטו היה קריאות לכלים, נכשל עם השגיאה Agent terminated early due to an API error, ולאחריה פירוט השגיאה. בגרסה v2.1.199, מגבלת קצב, עומס יתר או שגיאת שרת שקטעו סוכן שהפיק רק קריאות כלים החזירו תוצאה חלקית ריקה המכילה רק את הערת הקטיעה.
• רקע (Background): סוכן המשנה מסומן כנכשל, וההודעה ש-Claude מקבל כאשר הוא מסתיים מציינת את שגיאת ה-API וכוללת את הפלט האחרון של סוכן המשנה, כך שעבודה חלקית אינה הולכת לאיבוד.

כאשר אתה מגדיר שרשרת מודלים חלופיים (fallback model chain) וסוכן משנה נתקל בכשל שהשרשרת מכסה, כגון אי זמינות המודל שלו, Claude Code מעביר את סוכן המשנה למודל הראשון בשרשרת שמקבל את הבקשה. סוכן המשנה ממשיך לעבוד במקום להסתיים בשגיאה.

לאחר ששגיאת ה-API הבסיסית נפתרת, בקש מ-Claude לנסות שוב את המשימה או לחדש את סוכן המשנה.

#סריקת פלט של סוכני משנה

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

• החדרת לוכסן אחורי (Backslash insertion): הסריקה מחדירה לוכסן אחורי לתוך טקסט המחקה את הפלט של Claude Code עצמו, כגון תגית <system-reminder> או שורה המתחילה ב-Human: או Assistant:, כך שהחיקוי ייקרא כטקסט רגיל במקום להיחשב בטעות כחלק מהשיחה.
• שורת סימון (Marker line): הסריקה מוסיפה שורה המתחילה ב-[harness: subagent output matched instruction-shaped pattern(s): כאשר הדו"ח מחקה תגית כמו <system-reminder> או מזכיר הגדרות הרשאה כגון bypassPermissions או --dangerously-skip-permissions. אזכורי הגדרות הרשאה מקבלים את שורת הסימון, אך הטקסט עצמו נשאר כפי שנכתב.

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

הערה: סריקת פלט של סוכני משנה דורשת את Claude Code מגרסה v2.1.210 ומעלה.

#דפוסים נפוצים

#בידוד פעולות בנפח גבוה

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

Use a subagent to run the test suite and report only the failing tests with their error messages

#הרצת מחקר במקביל

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

Research the authentication, database, and API modules in parallel using separate subagents

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

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

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

#שרשור סוכני משנה

עבור תהליכי עבודה מרובי שלבים, בקש מ-Claude להשתמש בסוכני משנה ברצף. כל סוכן משנה משלים את משימתו ומחזיר תוצאות ל-Claude, אשר מעביר לאחר מכן את ההקשר הרלוונטי לסוכן המשנה הבא.

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

#בחירה בין סוכני משנה לבין השיחה הראשית

השתמש בשיחה הראשית כאשר:

• המשימה דורשת תקשורת הלוך ושוב תכופה או ליטוש הדרגתי.
• שלבים מרובים חולקים הקשר משמעותי, כגון תכנון, מימוש ובדיקה.
• אתה מבצע שינוי מהיר וממוקד.
• זמני תגובה (latency) חשובים. סוכן משנה שאינו פיצול (fork) מתחיל מחדש ועלול להזדקק לזמן כדי לאסוף הקשר.

השתמש בסוכני משנה כאשר:

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

שקול שימוש במיומנויות (Skills) במקום זאת כאשר אתה מעוניין בהוראות או בתהליכי עבודה לשימוש חוזר הרצים בהקשר השיחה הראשית ולא בהקשר מבודד של סוכן משנה.

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

#מתן אפשרות לסוכני משנה להפעיל סוכני משנה משלהם

כברירת מחדל, סוכן משנה יכול להפעיל סוכני משנה משלו, עד שלוש שכבות מתחת לשיחה הראשית. בהגעה למגבלת העומק, Claude Code מונע את הכלי Agent מכל סוכן משנה למעט פיצול (fork), כך שסוכן משנה במגבלה מבצע את עבודתו המואצלת בעצמו ומחזיר סיכום יחיד. פיצול במגבלה שומר על Agent ברשימת הכלים הנורשת שלו, אך הכלי מחזיר שגיאה במקום להפעיל סוכן.

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

כדי לשנות את המגבלה, הגדר את CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH למספר שכבות סוכני המשנה שברצונך לאפשר מתחת לשיחה הראשית שלך. לדוגמה, רשומה זו ב-settings.json מגבילה את הקינון לשתי שכבות:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

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

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

Claude Code מציג סוכני משנה מקוננים כעץ בפאנל סוכני המשנה שמתחת להזנת ההוראה, ומסמן כל שורה שעדיין יש לה צאצאים בפאנל בספירה שלהם בצורה (+N). פתח שורה כדי לראות את אחיו של אותו סוכן משנה ואת ילדיו הישירים עם נתיב חזרה אל main.

הערה: גרסאות קודמות השתמשו בברירות מחדל שונות:

• v2.1.172 עד v2.1.216: סוכני משנה יכלו לקנן כברירת מחדל, עד לעומק של חמש שכבות, ולא ניתן היה לשנות את המגבלה.
• v2.1.217 עד v2.1.218: ברירת המחדל של המגבלה הייתה אחת, כך שסוכן משנה לא יכול היה להפעיל סוכנים משלו אלא אם הגדלת אותה. גרסה v2.1.219 העלתה את ברירת המחדל לשלוש.

#מגבלת סוכני משנה מקבילים

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

כברירת מחדל, כאשר 20 סוכני משנה פועלים בהפעלה, יצירת סוכן נוסף באמצעות הכלי Agent נכשלת עם ההודעה Concurrent subagent limit reached, והשגיאה מנחה את Claude לא לנסות שוב. יצירת סוכנים מצליחה שוב כאשר מספר הסוכנים הפעילים יורד מתחת למגבלה. כדי לשנות את המגבלה, הגדר את CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS לכל מספר שלם חיובי. הפעלות שבהן ultracode פעיל פטורות מכך: המגבלה אינה נאכפת שם. דורש את Claude Code מגרסה v2.1.217 ומעלה.

המגבלה חוסמת רק סוכני משנה ש-Claude יוצר באמצעות הכלי Agent, אך הפעלות אחרות תופסות את אותם המקומות:

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

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

#ניהול הקשר של סוכן המשנה

#מה נטען בעת ההפעלה

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

ההקשר הראשוני של סוכן משנה שאינו פיצול מכיל:

• הוראת מערכת (System prompt): ההוראה של הסוכן עצמו בתוספת פרטי סביבה ש-Claude Code מצרף, ולא הוראת המערכת של Claude Code. סוכני משנה מותאמים אישית מגדירים את שלהם בגוף ה-Markdown או בשדה ה-prompt. לסוכנים מובנים יש הוראות מוגדרות מראש.
• הודעת משימה (Task message): הוראת ההאצלה ש-Claude כותב כאשר הוא מעביר את העבודה.
• קובצי CLAUDE.md: כל רמה של היררכיית CLAUDE.md שהשיחה הראשית טוענת, כולל ~/.claude/CLAUDE.md, כללי פרויקט, CLAUDE.local.md וקובצי מדיניות מנוהלים. הסוכנים המובנים Explore ו-Plan מדלגים על כך.
• מצב Git: תמונת מצב שנלקחה בתחילת הפעלת ההורה. אינו קיים כאשר תיקיית העבודה אינה מאגר Git או כאשר includeGitInstructions מוגדר כ-false. Explore ו-Plan מדלגים עליו בכל מקרה.
• מיומנויות שנטענו מראש: התוכן המלא של כל מיומנות המופיעה בשדה skills של הסוכן. סוכנים מובנים אינם טוענים מיומנויות מראש.
• רשימת עמיתים (Sibling roster): תזכורת מערכת המפרטת את main וכל סוכן אחר בעל שם בהפעלה, שכל אחד מהם הוא ערך to תקף עבור SendMessage. דורש את Claude Code מגרסה v2.1.206 ומעלה. הרשימה מופיעה רק כאשר כלי סוכן המשנה כוללים את SendMessage ולפחות לסוכן אחד נוסף יש שם, בין אם Claude העניק לו שם בעת יצירתו ובין אם הוא פועל כחבר צוות בצוות סוכנים. זוהי תמונת מצב שנלקחה בעת הפעלת סוכן המשנה, כך שסוכנים שקיבלו שם מאוחר יותר אינם מופיעים.

Explore ו-Plan הם סוכני המשנה היחידים שמשמיטים את CLAUDE.md ואת מצב ה-git. אין שדה frontmatter או הגדרה לכל סוכן שיכולים לשנות אילו סוכנים מדלגים עליהם.

השיחה הראשית קוראת את תוצאות Explore ו-Plan עם הקשר CLAUDE.md המלא, כך שרוב הכללים אינם צריכים להגיע לסוכן המשנה עצמו. אם כלל מסוים חייב להגיע, כגון "התעלם מתיקיית vendor/", חזור עליו בהוראה שאתה נותן ל-Claude בעת ההאצלה.

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

• סגנון פלט (Output style): סוכן משנה מריץ הוראת מערכת משלו, ולכן סגנון הפלט שלך אינו מעצב את תגובותיו, למעט בפיצול.
• זיכרון אוטומטי (Auto memory): הזיכרון האוטומטי של השיחה הראשית אינו נטען. כדי להעניק לסוכן משנה זיכרון מתמיד משלו, השתמש בשדה memory.
• גודל חלון ההקשר: חלון ההקשר של סוכן משנה נקבע לפי המודל שלו, ולא לפי המודל של ההורה. האצלה למודל בעל חלון קטן יותר מעניקה לאותו סוכן משנה חלון קטן יותר.

#חידוש סוכני משנה

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

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

• כאשר סוכן משנה מסיים, Claude מקבל את מזהה הסוכן שלו (agent ID).
• הסוכנים המובנים Explore ו-Plan הם חד פעמיים ואינם מחזירים מזהה סוכן, כך ש-Claude אינו יכול לחדש אותם. השתמש ב-general-purpose או בסוכן משנה מותאם אישית כאשר עליך להמשיך בעבודה.
• כאשר סוכן משנה עוצר במגבלת ה-maxTurns שלו, Claude Code מסמן את הפלט המוחזר כחלקי. עבור סוכני משנה המחזירים מזהה סוכן, Claude Code מציין בתוצאה ש-Claude יכול לשלוח הודעה לסוכן המשנה כדי להמשיך מהמקום שבה עצר.

Claude משתמש בכלי SendMessage עם המזהה או השם של הסוכן כשדה to כדי לחדש אותו. הכלי SendMessage אינו דורש שצוותי סוכנים יהיו מופעלים. רק הודעות מובנות של פרוטוקול צוות, כגון shutdown_request ו-plan_approval_response, דורשות זאת. מעבר לסוכני משנה וחברי צוות, בהפעלות שבהן העברת הודעות בין הפעלות מופעלת, Claude יכול להשתמש באותו כלי כדי לשלוח הודעות להפעלות Claude Code האחרות שלך, במחשב זה או מעבר לו.

כדי לחדש סוכן משנה, בקש מ-Claude להמשיך את העבודה הקודמת:

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

סוכן משנה שהסתיים ומקבל SendMessage מתחדש אוטומטית ברקע ללא צורך בקריאת Agent חדשה. הדבר תקף גם לסוכן משנה ש-Claude עצר באמצעות הכלי TaskStop.

סוכן משנה שעצרת בעצמך, באמצעות x בתוך /tasks או בקשת stop_task ב-SDK, אינו מתחדש אוטומטית. אם Claude שולח לו הודעה, ההודעה נדחית ונמסר ל-Claude שהסוכן בוטל.

בזמן ששורת סוכן המשנה עדיין מופיעה בפאנל סוכני המשנה, הקלד לתוך תמליל השיחה שלו כדי לחדש אותו בעצמך. לאחר מכן, הודעה מ-Claude יכולה לחדש אותו אוטומטית שוב. דורש את Claude Code מגרסה v2.1.191 ומעלה.

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

החל מגרסה v2.1.199, הכלי SendMessage בודק ששם עדיין מתייחס לאותו סוכן שאליו הגיע מוקדם יותר בשיחה. אם סוכן חדש יותר קיבל את השם, כגון סוכן רקע שנוצר מחדש ועשה שימוש חוזר בשם, Claude Code מסרב לשליחה במקום למסור אותה לסוכן הלא נכון, והשגיאה מדווחת לאיזה סוכן השם מגיע כעת כדי ש-Claude יוכל לכוון מחדש. כדי להגיע לסוכן הקודם בזמן שהוא עדיין רץ, Claude פונה אליו באמצעות מזהה הסוכן שקיבל בעת יצירת אותו סוכן. הבדיקה מוגבלת לשיחה הנוכחית ומתאפסת בביצוע /clear.

החל מגרסה v2.1.198, סוכן משנה מתייחס להודעות מהסוכן שהפעיל אותו כהנחיות משימה רגילות, כולל תיקוני מסלול באמצע המשימה, ופועל לפיהן במסגרת הגדרות ההרשאה שלו. שתי מגבלות עדיין חלות ללא קשר לזהות שולח ההודעה: שום הודעה מאף סוכן אינה נחשבת כאישור שלך לבקשת הרשאה ממתינה, ושום הודעת סוכן אינה יכולה לשנות את הגדרות ההרשאה, קובץ ה-CLAUDE.md או התצורה של סוכן משנה. רק מערכת ההרשאות או ההודעות שלך יכולות להעניק אישור.

באפשרותך גם לבקש מ-Claude את מזהה הסוכן אם ברצונך להתייחס אליו במפורש, או למצוא מזהים בקובצי התמליל בנתיב ~/.claude/projects/{project}/{sessionId}/subagents/. כל תמליל נשמר כ-agent-{agentId}.jsonl.

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

• דחיסת השיחה הראשית: כאשר השיחה הראשית נדחסת (compacts), תמלילי סוכני המשנה אינם מושפעים. הם שמורים בקבצים נפרדים.
• התמדה של ההפעלה: תמלילי סוכני משנה נשמרים בתוך ההפעלה שלהם. תוכל לחדש סוכן משנה לאחר הפעלה מחדש של Claude Code על ידי חידוש אותה הפעלה.
• ניקוי אוטומטי: Claude Code מוחק תמלילי סוכני משנה לאחר תקופת השימור של cleanupPeriodDays, 30 יום כברירת מחדל, לפי כללי סריקת השימור.

#דחיסה אוטומטית

סוכני משנה תומכים בדחיסה אוטומטית (automatic compaction) תוך שימוש באותו היגיון כמו השיחה הראשית. הדחיסה מופעלת תחת אותם תנאים, והמשתנה CLAUDE_AUTOCOMPACT_PCT_OVERRIDE חל גם על סוכני משנה. ראה משתני סביבה למועד כניסת הדריסה לתוקף.

#פיצול השיחה הנוכחית

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

Claude מתחיל פיצול על ידי בקשת סוג סוכן המשנה fork דרך הכלי Agent. אתה שולט ביכולתו לעשות זאת באמצעות מצב פיצול (fork mode), המופעל כברירת מחדל בהפעלות אינטראקטיביות.

תוכל להתחיל פיצול בעצמך באמצעות הפקודה /subtask ולאחריה תיאור משימה, בין אם מצב פיצול מופעל ובין אם לאו. בגרסאות v2.1.161 עד v2.1.211 הפקודה היא /fork. Claude Code מעניק שם לפיצול על פי המילים הראשונות של המשימה. הדוגמה הבאה מפצלת את השיחה כדי לנסח בדיקות יחידה בזמן שאתה ממשיך במימוש בהפעלה הראשית:

/subtask draft unit tests for the parser changes so far

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

#צפייה בפיצולים פעילים והכוונתם

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

כאשר פיצול מסיים בהצלחה, Claude Code מסיר את השורה שלו. Claude Code שומר את השורה של פיצול שנכשל או שעצרת למשך 30 שניות, בדומה לכל סוכן משנה אחר ברקע. לפני גרסה v2.1.232, Claude Code שמר גם את השורה של פיצול שהסתיים בהצלחה למשך 30 שניות.

השתמש במקשים אלה כדי לקיים אינטראקציה עם הפאנל:

כאשר תמליל של פיצול או של סוכן משנה פתוח, הודעות המשך ומיומנויות (skills) נשלחות לאותו סוכן, אך פקודות מובנות עדיין רצות בשיחה הראשית שלך. החל מגרסה v2.1.199, הקלדת /model או /fast בתצוגה זו מציגה הודעה המבהירה שהיא משנה את המודל או את המצב המהיר של השיחה הראשית, ולא של הסוכן הנצפה, במקום להריץ זאת בדממה.

#במה פיצולים שונים מסוכני משנה אחרים

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

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

כאשר Claude יוצר פיצול באמצעות הכלי Agent, הוא יכול להעביר isolation: "worktree" כך שעריכות הקבצים של הפיצול ייכתבו ל-git worktree נפרד במקום לעותק העבודה שלך. פיצול אינו יכול ליצור פיצולים נוספים.

#הפעלה או כיבוי של מצב פיצול

Claude Code מפעיל את מצב הפיצול כברירת מחדל בהפעלות אינטראקטיביות ומשאיר אותו כבוי כברירת מחדל במצב לא אינטראקטיבי עם -p וב-Agent SDK. ברירת המחדל האינטראקטיבית דורשת את Claude Code מגרסה v2.1.232 ומעלה. בגרסאות קודמות, הגדר את CLAUDE_CODE_FORK_SUBAGENT ל-1 כדי להפעיל את מצב הפיצול.

תוכל לזהות שמצב פיצול מופעל לפי האופן שבו Claude Code מטפל בכלי Agent:

• Claude יכול ליצור פיצול על ידי בקשת סוג סוכן המשנה fork. כאשר Claude אינו מבקש סוג, הוא מקבל את סוכן המשנה general-purpose, אם להפעלה עדיין יש סוג זה. סוכני משנה שנוצרו מהגדרה, כגון Explore, פועלים כרגיל.
• Claude Code מריץ את סוכני המשנה ש-Claude יוצר ברקע, הן פיצולים והן סוכנים שאינם פיצול, מלבד המקרים שנשארים בחזית. Claude Code מסיר בנוסף את הפרמטר run_in_background של הכלי Agent, כך ש-Claude אינו יכול לבקש הרצה בחזית.

הגדר את משתנה הסביבה CLAUDE_CODE_FORK_SUBAGENT כדי לדרוס את ברירות המחדל:

• 1 מפעיל את מצב הפיצול גם במצב לא אינטראקטיבי וב-Agent SDK.
• 0 מכבה את מצב הפיצול בכל סוג של הפעלה.

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

#דוגמאות לסוכני משנה

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

טיפ: שיטות מומלצות:

• תכנן סוכני משנה ממוקדים: כל סוכן משנה צריך להצטיין במשימה ספציפית אחת.
• כתוב תיאורים המייחדים סוכן משנה בודד: Claude משתמש בתיאור כדי להחליט מתי להאציל. נסח כל תיאור בצורה ספציפית מספיק כדי לנתב לסוכן המשנה הנכון, ושמור על סך התיאורים במסגרת תקציב 15,000 הטוקנים.
• הגבל גישה לכלים: הענק רק הרשאות נחוצות לשם אבטחה ומיקוד.
• בצע check-in לבקרת גרסאות: שתף סוכני משנה ברמת הפרויקט עם הצוות שלך.

#סוקר קוד (Code reviewer)

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

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

#מנפה שגיאות (Debugger)

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

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

#מדען נתונים (Data scientist)

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

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

#מאמת שאילתות מסד נתונים (Database query validator)

סוכן משנה המאפשר גישה ל-Bash אך מאמת פקודות כדי להתיר אך ורק שאילתות SQL לקריאה בלבד. דוגמה זו מראה כיצד להשתמש בהוקים מסוג PreToolUse עבור אימות מותנה כאשר נדרשת שליטה עדינה יותר מזו שמספק שדה ה-tools.

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

Claude Code מעביר קלט הוק כמבנה JSON דרך stdin לפקודות הוק. סקריפט האימות קורא JSON זה, מחלץ את הפקודה המבוצעת, ובודק אותה מול רשימה של פעולות כתיבה ב-SQL. אם מזוהה פעולת כתיבה, הסקריפט יוצא עם קוד 2 כדי לחסום את הביצוע ומחזיר הודעת שגיאה ל-Claude דרך stderr.

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

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

ב-macOS וב-Linux, הפוך את הסקריפט לקובץ בר-ביצוע:

chmod +x ./scripts/validate-readonly-query.sh

ב-Windows, כתוב את סקריפט האימות ב-PowerShell והוסף shell: powershell לרשומת ההוק. ראה הרצת הוקים ב-PowerShell.

ההוק מקבל JSON דרך stdin כאשר פקודת ה-Bash נמצאת ב-tool_input.command. קוד יציאה 2 חוסם את הפעולה ומזין את הודעת השגיאה בחזרה ל-Claude. ראה הוקים לפרטים על קודי יציאה וקלט הוק למבנה הקלט המלא.

הוראת המערכת מנחה את סוכן המשנה לסרב לבקשות כתיבה, כך שההוק משמש כרשת ביטחון: אם סוכן המשנה ינסה לכתוב בכל זאת, Claude Code יחסום את הפקודה וסוכן המשנה יראה את ההודעה Blocked: Write operations not allowed. Use SELECT queries only..

#הצעדים הבאים

כעת, משהבנת את סוכני המשנה, חקור את התכונות הקשורות הבאות:

• הפצת סוכני משנה באמצעות תוספים כדי לשתף סוכני משנה בין צוותים או פרויקטים
• הרצת Claude Code באופן תכנותי באמצעות ה-Agent SDK עבור CI/CD ואוטומציה
• שימוש בשרתי MCP כדי להעניק לסוכני משנה גישה לכלים ולנתונים חיצוניים