תיעוד 60

ניפוי באגים בתצורה

אבחן למה CLAUDE.md, הגדרות, hooks, שרתי MCP או skills לא נכנסים לתוקף. השתמש ב-/context, ב-/doctor, ב-/hooks וב-/mcp כדי לראות מה באמת נטען.

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

לבעיות התקנה, אימות וקישוריות, ראה פתרון בעיות התקנה והתחברות.

#ראה מה נטען להקשר

פקודת /context מציגה את כל מה שתופס את חלון ההקשר בסשן הנוכחי. היא מפרקת את זה לפי קטגוריה: הנחיית מערכת, כלי מערכת, כלי MCP, סוכני משנה מותאמים עם המקור שממנו כל אחד נטען, קובצי זיכרון, skills והודעות השיחה. הרץ אותה קודם כדי לאשר אם CLAUDE.md, כללים או תיאורי skill נמצאים בכלל. מקטע ה-skills ב-/context כולל גם skills ארוזים, ש-/skills לא מציג.

במצב מסך מלא, /context מקפל את הפירוט לפי פריט, אז הרץ /context all כדי להרחיב אותו.

לפירוט על קטגוריה מסוימת, המשך עם הפקודה הייעודית:

פקודה	מציג
`/memory`	מיקומי קובצי זיכרון בהיקפי משתמש ופרויקט, עם אפשרות לפתוח כל אחד בעורך, וגם גישה לתיקיית הזיכרון האוטומטי ולמתג הזיכרון האוטומטי
`/skills`	skills זמינים ממקורות פרויקט, משתמש ותוסף
`/hooks`	תצורות hook פעילות
`/mcp`	שרתי MCP מחוברים והסטטוס שלהם
`/permissions`	כללי allow ו-deny שנפתרו ושבתוקף כרגע
`/doctor`	בדיקת הגדרה: תקינות ההתקנה, קובצי הגדרות לא תקינים, הרחבות שלא בשימוש, שמות subagent כפולים באותה תיקייה, ותוכן `CLAUDE.md` שנכנס למאגר ש-Claude יכול לגזור מבסיס הקוד, עם תיקונים מוצעים
`/debug [issue]`	מפעיל רישום דיבוג לסשן ומבקש מ-Claude לאבחן לפי פלט היומן ונתיבי ההגדרות
`/status`	מקורות הגדרות פעילים, כולל אם הגדרות מנוהלות בתוקף

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

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

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

[!NOTE]

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

#בדיקת הגדרות שנפתרו

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

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

הרץ /status כדי לראות אילו מקורות הגדרות פעילים, כולל אם הגדרות מנוהלות בתוקף. כדי להבין באיזה היקף Claude Code משתמש למפתח נתון, ראה קדימות הגדרות.

#בדיקת שרתי MCP

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

שרתים בהיקף פרויקט ב-.mcp.json דורשים אישור חד פעמי. אם סגרת את ההנחיה, השרת נשאר מושבת עד שתאשר אותו מ-/mcp.
שרת שנכשל בהפעלה מוצג כנכשל ב-/mcp. נתיבי קבצים יחסיים ב-command או ב-args הם סיבה נפוצה, כי הם נפתרים מול התיקייה שממנה הפעלת את Claude Code ולא מול המיקום של .mcp.json.
שרת שמוצג כמחובר אבל מציג אפס כלים עלה בהצלחה אבל לא מחזיר רשימת כלים. בחר Reconnect מ-/mcp. אם הספירה נשארת אפס, הרץ claude --debug=mcp וקרא את stderr של השרת ביומן הדיבוג ב-~/.claude/debug/<session-id>.txt.

למיקומי תצורה ולכללי היקף, ראה MCP.

#בדיקת hooks

הרץ /hooks כדי לרשום כל hook שנרשם לסשן הנוכחי, מקובץ לפי אירוע. אם hook שהגדרת לא מופיע, Claude Code לא טען אותו. בדוק את הסיבות האלה:

ה-hook מוגדר בקובץ נפרד. hooks נמצאים תחת המפתח "hooks" בקובץ הגדרות.
הערך של matcher הוא מערך במקום מחרוזת אחת. Claude Code מציג את הרשומה כהגדרה לא תקינה כשמתחילים סשן אינטראקטיבי וב-claude doctor. אם המערך נמצא תחת PreToolUse או PermissionRequest, גם שאר ה-hooks של הקובץ הזה לא נטענים.
ה-hook נמצא ב-frontmatter של skill, ואתה או Claude עדיין לא הפעלתם את ה-skill בסשן הזה. הפעל אותו או בקש מ-Claude לעשות זאת, ואז הרץ /hooks שוב. אם ה-hook עדיין לא מופיע, בדוק סיבות אחרות, כמו frontmatter שלא נותח או אחד מהמגבלות על skill hooks.

אם ה-hook מופיע אבל לא מופעל, ה-matcher הוא בדרך כלל הסיבה. בדוק בו את הטעויות האלה:

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

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

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

אם /hooks מציג את ה-hook אבל הוא עדיין לא מופעל, השלב הבא הוא לצפות בהערכת ה-hook בזמן אמת. התחל סשן עם claude --debug והפעל את קריאת הכלי. יומן הדיבוג רושם כל אירוע, אילו matchers נבדקו, ואת קוד היציאה והפלט של ה-hook. ראה ניפוי באגים ב-hooks לפורמט היומן ופתרון בעיות hooks לדפוסי כשל נפוצים.

#בדיקה מול תצורה נקייה

התחל עם claude --safe-mode, שמפעיל סשן כשההתאמות שלך מושבתות, כולל:

CLAUDE.md
Skills, תוספים ו-hooks
שרתי MCP
פקודות וסוכנים מותאמים
סגנונות פלט מותאמים
קיצורי מקשים מותאמים

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

מצב בטוח עדיין מחיל hooks מנוהלים ומדיניות הגדרות מהארגון שלך. תוספים מנוהלים, skills, CLAUDE.md ושרתי MCP כבויים.

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

1. צור תיקייה ריקה ועבור אליה

במעטפת, בלי סשן Claude Code רץ, צור את התיקייה ועבור אליה:

Bash או Zsh:

mkdir -p ~/claude-clean/empty && cd ~/claude-clean/empty

PowerShell:

New-Item -ItemType Directory -Force "$HOME/claude-clean/empty" | Out-Null
Set-Location "$HOME/claude-clean/empty"

2. הפעל את Claude Code עם תיקיית תצורה נקייה

מאותה מעטפת, הגדר את CLAUDE_CONFIG_DIR לתיקייה חדשה במקום ~/.claude, והעבר --setting-sources user כדי לכבות תצורת פרויקט כמו .claude/settings.json, CLAUDE.md ו-.mcp.json:

Bash או Zsh:

המשתנה חל על ההפעלה הזו בלבד.

CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user

PowerShell:

המשתנה נשאר מוגדר לשאר סשן PowerShell הזה, ולכן הפעלות claude מאוחרות יותר באותו חלון ממשיכות להשתמש בתיקייה הנקייה. כדי לחזור לתיקייה הרגילה שלך, הרץ Remove-Item Env:CLAUDE_CONFIG_DIR לפני ההפעלה הבאה.

$env:CLAUDE_CONFIG_DIR = "$HOME/claude-clean/config"
claude --setting-sources user

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

3. שחזר את הבעיה

חזור על מה שהפעיל את הבעיה בסשן הנקי:

הבעיה נעלמה: הסיבה בתצורת המשתמש או הפרויקט שלך. העתק את ~/.claude.json ואת הקבצים ב-~/.claude אל ~/claude-clean/config אחד בכל פעם. אם אף אחד לא מחזיר את הבעיה, עבור לתיקיית הפרויקט באותה מעטפת והפעל את Claude Code בלי --setting-sources user. ב-Bash או Zsh, הרץ CLAUDE_CONFIG_DIR=~/claude-clean/config claude. ב-PowerShell המשתנה עדיין מוגדר, אז הרץ claude.
הבעיה נמשכת: הסיבה מחוץ לתצורת המשתמש והפרויקט שלך. הרץ /status בסשן כדי לבדוק הגדרות מנוהלות, בדוק במעטפת משתני סביבה, ואז ראה פתרון בעיות.

#בדיקת סיבות נפוצות

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

תסמין	סיבה	תיקון
ה-hook אף פעם לא מופעל	`matcher` הוא מערך JSON במקום מחרוזת	השתמש במחרוזת אחת עם `\|` כדי להתאים לכמה כלים, לדוגמה `"Edit\|Write"`. ראה דפוסי matcher.
ה-hook אף פעם לא מופעל	`matcher` משתמש ב-`,` כמפריד בגרסה שלפני v2.1.191	Claude Code v2.1.191 ומעלה מתייחס ל-`,` כמפריד רשימה כמו `\|`. גרסאות קודמות מעריכות פסיק כתו מילולי, אז `"Edit,Write"` לא מתאים לכלום. השתמש ב-`\|` במקום, או שדרג את Claude Code.
ה-hook אף פעם לא מופעל	הערך של `matcher` באותיות קטנות, לדוגמה `"bash"`	ההתאמה תלוית רישיות. שמות הכלים באות גדולה: `Bash`, `Edit`, `Write`, `Read`.
ה-hook אף פעם לא מופעל	hooks מוגדרים בקובץ נפרד במקום ב-`settings.json`	אין קובץ hooks נפרד לתצורת פרויקט או משתמש. הגדר hooks תחת המפתח `"hooks"` ב-`settings.json`. רק תוספים טוענים `hooks/hooks.json` נפרד. ראה תצורת hook.
הרשאות או hooks שהוגדרו גלובלית מתעלמים מהם	התצורה נוספה ל-`~/.claude.json`	`~/.claude.json` מחזיק מצב אפליקציה ומתגי ממשק. `permissions`, `hooks` ו-`env` שייכים ל-`~/.claude/settings.json`. אלה שני קבצים שונים.
ערך ב-`settings.json` נראה כאילו מתעלמים ממנו	אותו מפתח מוגדר ב-`settings.local.json`	`settings.local.json` דורס את `settings.json`, ושניהם דורסים את `~/.claude/settings.json`. ראה קדימות הגדרות.
skill לא מופיע ב-`/skills`	קובץ ה-skill נמצא ב-`.claude/skills/name.md` במקום בתיקייה	השתמש בתיקייה עם `SKILL.md` בפנים: `.claude/skills/name/SKILL.md`.
skill מופיע ב-`/skills` אבל Claude אף פעם לא מפעיל אותו	ל-skill יש `disable-model-invocation: true` ב-frontmatter, או שהתיאור שלו לא תואם לאופן שבו מנסחים את הבקשה	בדוק את התג ב-`/skills`: תווית "user-only" אומרת ש-Claude לא יפעיל אותו בעצמו. ראה הפעלת skill.
הוראות `CLAUDE.md` בתיקיית משנה נראות כאילו מתעלמים מהן	קבצים בתיקיות משנה נטענים לפי דרישה, לא בתחילת הסשן	כדי לטעון את `CLAUDE.md` של תיקיית משנה, בקש מ-Claude לקרוא קובץ אחר באותה תיקיית משנה. ראה מתי נטענים קבצים בתיקיות משנה.
subagent מתעלם מהוראות `CLAUDE.md`	סוכני Explore ו-Plan המובנים מדלגים על `CLAUDE.md` בהפעלה. subagent מותאם טוען אותו באותו אופן כמו השיחה הראשית, אלא אם יש לו `omitClaudeMd` מוגדר בהגדרה שלו	ל-Explore או Plan, חזור על ההוראה בהנחיית ההאצלה. ל-subagent שמגדיר `omitClaudeMd`, הסר את השדה. לכל subagent מותאם אחר, שים הוראות קריטיות בגוף קובץ הסוכן, שהופך להנחיית המערכת של הסוכן. ראה מה נטען בהפעלה.
לוגיקת ניקוי אף פעם לא רצה בסוף הסשן	אין hook מסוג `SessionEnd` מוגדר	הוסף hook מסוג `SessionEnd` ב-`settings.json`. ראה רשימת אירועי hook.
שרתי MCP ב-`.mcp.json` אף פעם לא נטענים	הקובץ נמצא תחת `.claude/`, או שהשרתים שלו יושבים תחת מפתח עליון `servers`, כמו ב-`mcp.json` של VS Code, במקום `mcpServers`	תצורת MCP של פרויקט נמצאת בשורש המאגר כ-`.mcp.json`, לא בתוך `.claude/`, עם שרתים תחת המפתח `mcpServers`. ראה תצורת MCP.
שרתי MCP שנוספו תחת `mcpServers` ב-`settings.json` אף פעם לא מופיעים	`settings.json` לא קורא מפתח `mcpServers`	הגדר שרתי פרויקט ב-`.mcp.json` בשורש המאגר, או הרץ `claude mcp add --scope user` לשרתים בהיקף משתמש. ראה תצורת MCP.
שרת MCP של פרויקט נוסף אבל לא מופיע	הנחיית האישור החד פעמית נסגרה	שרתים בהיקף פרויקט דורשים אישור. הרץ `/mcp` כדי לראות סטטוס ולאשר.
שרת MCP נכשל בהפעלה מחלק מהתיקיות	`command` או `args` משתמשים בנתיב קובץ יחסי	השתמש בנתיבים מוחלטים לסקריפטים מקומיים. קבצי הפעלה ב-`PATH` כמו `npx` או `uvx` עובדים כמו שהם.
שרת MCP עולה בלי משתני הסביבה הצפויים	רשומת התצורה של השרת לא מגדירה אותם, והם לא בסביבה ש-Claude Code מעביר לשרתי stdio: הסביבה שלו עצמו, פחות המשתנים שהוא מסיר מתהליכי משנה	הגדר `env` לכל שרת בתוך רשומת `.mcp.json` של השרת, דבר שלא תלוי בסביבת ההפעלה או באמון בסביבת העבודה.
כלל דחייה `Bash(rm *)` לא חוסם את `/bin/rm` או `find -delete`	כללי Bash מתאימים למחרוזת הפקודה המילולית, לא לקובץ ההפעלה שמתחת. ראה מה כלל Bash לא מתאים	השתמש ב-hook מסוג PreToolUse או בארגז החול לערובה קשיחה.

#משאבים קשורים

לעיון מלא בכל משטח הגדרה, ראו את הדף הייעודי:

מדריך ספריית .claude: המיקום של כל קובץ הגדרות ומה קורא אותו
הגדרות: באיזה קובץ להשתמש ובאיזה ערך Claude Code משתמש. מדריך ההגדרות מכיל את רשימת המפתחות המלאה
מדריך Hooks: שמות אירועים, payloads, ופורמט הפלט של --debug
MCP: הגדרת שרת, אישור, והפלט של /mcp
פתרון בעיות התקנה והתחברות: command not found, PATH, ובעיות אימות
פתרון בעיות: ביצועים, תקיעות, ובעיות חיפוש