⚠️ פרק 14

מלכודות נפוצות, פתרון בעיות ושיטות עבודה מומלצות

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

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

#איפה להתחיל

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

#1. זיהום חלון ההקשר ודחיסת יתר

• המלכודת: המשך עבודה באותו חלון שיחה למשימות שונות, או הצטברות ניסיונות תיקון כושלים. קריאות קבצים ישנות, לוגים ופלטי בדיקות ממלאים את ההקשר, מבלבלים את המודל ומייקרים כל פנייה. במצב קיצוני מופיעה השגיאה Autocompact is thrashing: the context refilled to the limit...: הדחיסה האוטומטית הצליחה, אבל קובץ או פלט כלי מילאו מחדש את החלון כמה פעמים ברצף, ו-Claude Code מפסיק לנסות כדי לא לבזבז קריאות API על לולאה שאינה מתקדמת.
• הליך התאוששות משגיאת Autocompact is thrashing:
  1. בקשו מקלוד לקרוא את הקובץ החורג בחלקים קטנים יותר, כגון טווח שורות מסוים או פונקציה, במקום את הקובץ כולו.
  2. הריצו /compact עם מיקוד שמשמיט את הפלט הגדול, למשל /compact keep only the plan and the diff.
  3. העבירו את העבודה על הקובץ הגדול ל-subagent כדי שתרוץ בחלון הקשר נפרד.
  4. הריצו /clear אם אין צורך בהמשך השיחה הקודמת.
• ניהול שוטף ואגרסיבי של ההקשר:
  • הריצו /clear לעיתים קרובות בין משימות שאינן קשורות כדי לאפס את חלון ההקשר לחלוטין.
  • אם תיקנתם את קלוד יותר מפעמיים על אותה בעיה באותו סשן, ההקשר עמוס בגישות כושלות. הריצו /clear והתחילו מחדש עם פרומפט ספציפי יותר שמשלב את מה שלמדתם. סשן נקי עם פרומפט טוב יותר כמעט תמיד משיג תוצאות טובות יותר מסשן ארוך שצבר תיקונים.
  • כאשר מגיעים לגבול ההקשר מופעלת דחיסה אוטומטית (auto compaction). קלוד מתמצת את המידע החשוב ביותר: דפוסי קוד, מצב קבצים והחלטות מפתח.
  • לשליטה רבה יותר, הריצו /compact <instructions>, למשל /compact Focus on the API changes.
  • אם /compact מחזיר Not enough messages to compact., בשיחה יש מעט מדי תורות לסיכום. זה יכול לקרות גם כשההקשר מלא, למשל לאחר הדבקה גדולה אחת שמילאה אותו.
  • לדחיסה של חלק מהשיחה לחצו Esc + Esc או הריצו /rewind, בחרו נקודת ביקורת (checkpoint), ובחרו באחת משתי אפשרויות הסיכום בתפריט ה-rewind:
    • Summarize from here: מתמצת הודעות מאותה נקודה והלאה ושומר על ההקשר המוקדם ללא שינוי.
    • Summarize up to here: מתמצת הודעות מוקדמות ושומר על ההודעות האחרונות במלואן.
  • הגדירו התנהגות דחיסה ב-CLAUDE.md עם הוראות כגון: "When compacting, always preserve the full list of modified files and any test commands" כדי להבטיח שהקשר קריטי יישמר גם אחרי סיכום.
  • לשאלות צדדיות שאינכם רוצים שיישמרו בהיסטוריה, השתמשו ב-/btw. התשובה אינה נכנסת להיסטוריית השיחה ולא מגדילה את ההקשר.
  • עקבו באופן רציף אחרי צריכת ההקשר באמצעות שורת סטטוס מותאמת אישית (statusline), והיעזרו ב-/context כדי לראות מה תופס את רוב הטוקנים.

#2. הסתמכות על CLAUDE.md כמנגנון אבטחה מוחלט

• המלכודת: כתיבת הוראות כמו "לעולם אל תמחק קבצים" או "אל תדחוף ל-main" ב-CLAUDE.md, מתוך הנחה שהדבר מונע את הפעולות בוודאות.
• הפתרון:
  • הוראות ב-CLAUDE.md הן הנחיות למודל (advisory), ולא מחסום תוכנתי דטרמיניסטי.
  • לאכיפה מוחלטת השתמשו בכללי הרשאות ב-settings.json או כתבו Hooks.
  • Hooks מריצים סקריפטים אוטומטית בנקודות מוגדרות בתהליך העבודה של קלוד, והם דטרמיניסטיים ומבטיחים שהפעולה אכן תתבצע.
  • ניתן לבקש מקלוד לכתוב Hooks עבורכם, למשל: "Write a hook that runs eslint after every file edit" או "Write a hook that blocks writes to the migrations folder.".
  • כדי להגדיר Hooks ידנית, ערכו ישירות את .claude/settings.json, והריצו /hooks כדי לצפות במה שמוגדר.
  • ניתן להגדיר Stop hook: סקריפט שמריץ בדיקה וחוסם את סיום התור עד שהיא עוברת. Claude Code עוקף את ה-Hook ומסיים את התור אם ה-Hook חוסם אותו 8 פעמים ברציפות.

#3. קובץ CLAUDE.md עמוס ומיותר

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

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

• הריצו /context כדי לוודא שקלוד טען את הקובץ.
• על כל שורה שאלו: "האם הסרת השורה הזו תגרום לקלוד לטעות?". אם לא, מחקו אותה. אם קלוד כבר עושה משהו נכון ללא ההוראה, מחקו אותה או הפכו אותה ל-Hook.
• התייחסו לקובץ כמו לקוד: בדקו אותו כשיש תקלות, גזמו אותו באופן קבוע, ובחנו האם שינויים בו משפיעים בפועל על התנהגות המודל.
• עבור קובץ CLAUDE.md שנמצא ב-Git, הריצו /doctor וקלוד יציע קיצוצים של תוכן שניתן להסיק מתוך בסיס הקוד.
• אם קלוד מדלג על הוראה מסוימת, הוסיפו הדגשה כגון "IMPORTANT" לאותה שורה בלבד. אם מדגישים שורות רבות, שום דבר אינו בולט.
• שמרו את CLAUDE.md ב-Git כדי שכל חברי הצוות יוכלו לתרום לו. הערך של הקובץ מצטבר לאורך זמן.
• קובצי CLAUDE.md יכולים לייבא קבצים נוספים באמצעות תחביר @path/to/import.
• עבור ידע תחום או תהליכי עבודה שרלוונטיים רק לעיתים, השתמשו ב-Skills במקום להעמיס על CLAUDE.md. קלוד טוען אותם לפי דרישה בלי לנפח כל שיחה.

#4. ניסוח פרומפטים עמומים, אימות תוצאות ומצב תוכנית

• המלכודת: בקשות כלליות כמו "תתקן את הקוד" או "שפר את הביצועים", בלי לספק קריטריוני בדיקה, בלי הקשר מדויק, או קפיצה מיידית לקידוד בלי תכנון מקדים של שינויים מורכבים. מלכודת נוספת היא פער של אמון ללא אימות (trust-then-verify gap): קלוד מייצר יישום שנראה סביר אך אינו מטפל במקרי קצה. הכלל המנחה הוא: אם אינכם יכולים לאמת את השינוי, אל תוציאו אותו לסביבת ייצור.
• מתן דרך לקלוד לבדוק את עבודתו:
  • קלוד עוצר כאשר העבודה נראית גמורה. בלי בדיקה שניתן להריץ, המשתמש הופך ללולאת האימות וכל שגיאה ממתינה לתשומת לבו. ספקו בדיקה שמפיקה תוצאת הצלחה או כישלון שקלוד יכול לקרוא בשיחה: מערך בדיקות, קוד יציאה של פקודת בנייה, לינטר, סקריפט המשווה פלט מול נתוני בדיקה, או צילום מסך של דפדפן בהשוואה לעיצוב. זה ההבדל בין סשן שחייבים להשגיח עליו לבין סשן שניתן לעזוב אותו לפעול לבד.
  • קלוד מבצע את העבודה, מריץ את הבדיקה, קורא את התוצאה ומתקן בלולאה עד שהיא עוברת.
  • אחרי שהבדיקה של קלוד עוברת, הריצו בעצמכם /verify כדי לאמת את השינוי מול האפליקציה הפועלת.

• קביעת רמת החסימה לאימות:

  • בפרומפט יחיד: בקשו מקלוד לבצע את הבדיקה ולתקן באותה הודעה.
  • לאורך סשן שלם: הגדירו את הבדיקה כתנאי ב-/goal. מעריך נפרד בודק אותה מחדש אחרי כל תור וקלוד ממשיך לעבוד עד שהיעד מושג. אם קלוד נתקע, Claude Code עוצר בסופו של דבר את הריצה כשהיעד עדיין מוגדר.
  • כמחסום דטרמיניסטי: Stop hook מריץ את הבדיקה כסקריפט וחוסם את סיום התור עד שהיא עוברת. המערכת עוקפת את ה-Hook ומסיימת את התור לאחר 8 חסימות רצופות.
  • חוות דעת שנייה: subagent אימות או תהליך עבודה דינמי שבו מודל נקי בוחן את הממצאים ומנסה להפריך את התוצאה, כך שהסוכן המבצע אינו הגורם שנותן לעצמו ציון.
  • דרשו מקלוד להציג ראיות להצלחה (פלט הבדיקה, הפקודה שהורצה ותוצאתה, או צילום מסך) במקום רק להצהיר שהעבודה הושלמה. סקירת ראיות מהירה יותר מהרצה ידנית חוזרת, ומתאימה לסשנים שלא השגחתם עליהם.

• מתן הקשר ספציפי בפרומפטים:

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

• פרומפטים עמומים שימושיים רק בשלב של חקירה וגישוש כשיש אפשרות לתקן כיוון. שאלה כמו "what would you improve in this file?" יכולה להעלות נקודות שלא חשבתם לשאול עליהן.

• העברת תוכן עשיר לקלוד:

  • הפנו לקבצים ישירות באמצעות @ במקום לתאר היכן הקוד נמצא. קלוד קורא את הקובץ לפני שהוא משיב.
  • הדביקו או גררו תמונות וצילומי מסך ישירות לתוך הפרומפט.
  • ספקו קישורי URL לתיעוד ול-API. השתמשו ב-/permissions כדי לאשר דומיינים נפוצים ברשימת היתרים.
  • הזרימו פלט פקודות ישירות לקלוד באמצעות צינור: cat error.log | claude.
  • הנחו את קלוד לשלוף הקשר בעצמו באמצעות פקודות Bash, כלי MCP או קריאת קבצים.

• ארבעת שלבי העבודה במצב תוכנית (Plan Mode): מתן אפשרות לקלוד לקפוץ ישירות לקידוד עלול לייצר קוד שפותר את הבעיה הלא נכונה. הפרדת המחקר והתכנון מהביצוע מונעת זאת. ההליך המומלץ כולל ארבעה שלבים:

  1. חקירה (Explore): היכנסו למצב תוכנית על ידי לחיצה על Shift+Tab עד שהסטטוס מציג ⏸ plan mode on, או התחילו סשן עם claude --permission-mode plan. קלוד קורא קבצים ועונה על שאלות בלי לבצע שינויים.

read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.

2. תכנון (Plan): בקשו מקלוד ליצור תוכנית יישום מפורטת.

I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.

לחצו Ctrl+G כדי לפתוח את התוכנית ישירות בעורך הטקסט שלכם לעריכה ישירה לפני שקלוד ממשיך. 3. יישום (Implement): צאו ממצב תוכנית על ידי אישור התוכנית או לחיצה על Shift+Tab, ותנו לקלוד לקודד תוך אימות מול התוכנית שלו.

implement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.

4. קומיט (Commit): בקשו מקלוד לבצע קומיט עם הודעה תיאורית ולפתוח PR.

commit with a descriptive message and open a PR

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

• ראיון לפני תכנון תכונות גדולות: עבור תכונות גדולות, תנו לקלוד לראיין אתכם תחילה. התחילו עם פרומפט קצר ובקשו מקלוד לראיין אתכם באמצעות הכלי AskUserQuestion. קלוד שואל על היבטים שאולי לא שקלתם, כולל יישום טכני, ממשק וחוויית משתמש, מקרי קצה ושיקולים הנדסיים. החליפו את [brief description] בפרומפט הבא:

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

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

• שאלות על בסיס הקוד להתאקלמות (Onboarding): בעת כניסה לפרויקט חדש, שאלו את קלוד שאלות כפי שהייתם שואלים מהנדס בכיר:
  • כיצד עובד מנגנון הרישום ליומן (logging)?
  • כיצד יוצרים נקודת קצה חדשה ב-API?
  • מה עושה async move { ... } בשורה 134 של foo.rs?
  • באילו מקרי קצה מטפל CustomerOnboardingFlowImpl?
  • מדוע הקוד קורא ל-foo() במקום ל-bar() בשורה 333? השימוש בקלוד לצורך התאקלמות מקצר את זמן הכניסה לפרויקט ומפחית עומס מחברי צוות אחרים. אין צורך בפרומפטים מיוחדים: פשוט שואלים ישירות.

#5. מצבי הרשאות, בידוד Sandbox ולוח העתקה

• המלכודת: עבודה במצב ידני הגוררת אישורים חוזרים על כל פעולה, או פקודות לוח העתקה שנכשלות מתוך סביבת בידוד או דרך SSH.
• הפתרון בהרשאות ובידוד:
  • בחשבונות Pro, Max ו-Team, מצב ברירת המחדל להפעלת שיחה אינטראקטיבית בטרמינל וב-VS Code הוא auto. מודל מסווג נפרד בודק את הפעולות וחוסם רק פעולות בסיכון (כגון הסלמת הרשאות, תשתית לא מוכרת או פעולות הנובעות מתוכן עוין).
  • במנויים אחרים מצב ברירת המחדל הוא manual, שבו קלוד שואל לפני כל פעולה שעלולה לשנות את המערכת: כתיבת קבצים, פקודות Bash וכלי MCP. זהו מצב בטוח אך מעייף.
  • כדי לצמצם שאלות בלי לוותר על שליטה, במצב ידני ובמצב אוטומטי כאחד:
    • הגדירו רשימת היתרים עם /permissions לכלים ספציפיים שאתם יודעים שהם בטוחים (למשל npm run lint או git commit).
    • הפעילו בידוד ברמת מערכת ההפעלה באמצעות /sandbox, המגביל גישה למערכת הקבצים ולרשת ומאפשר לקלוד לפעול בחופשיות רבה יותר בתוך גבולות מוגדרים.
• לוח העתקה בתוך Sandbox:
  • כשהבידוד פעיל, פקודות כמו pbcopy, xclip ו-wl-copy נכשלות בהגעה ללוח המערכת מתוך פקודת Bash מבודדת ולוח העתקה אינו משתנה.
  • כדי להעתיק, בקשו מקלוד להדפיס את התוכן בתשובתו והריצו /copy. הפקודה כותבת ללוח ישירות מתהליך Claude Code (ולא מפקודה מבודדת), מעתיקה בלוק קוד בודד או תשובה שלמה, ושומרת את התוכן לקובץ עם נתיב מודפס שמשמש כגיבוי כשכתיבת הלוח אינה מגיעה לטרמינל (למשל מעל SSH).
  • להרצת פקודות צינור שמגיעות ישירות ללוח מחוץ לבידוד, הוסיפו pbcopy *, wl-copy * או xclip * להגדרת excludedCommands בהגדרות.
• העתקה דרך חיבור SSH מרוחק:
  • כאשר Claude Code רץ על מכונה מרוחקת בחיבור SSH, הוא אינו יכול להריץ כלי לוח מקומי במכונה שלכם. מחוץ ל-tmux, בעת בחירת טקסט ברינדור מסך מלא (fullscreen rendering) או הרצת /copy, קלוד שולח את הטקסט לטרמינל כרצף בריחה OSC 52, והטרמינל שלכם קובע אם להניח אותו בלוח המקומי. הפקודה /copy מדווחת Copied to clipboard בין אם הטקסט הגיע ליעדו ובין אם לא, ומחוץ ל-tmux הודעת הבחירה מציגה sent N chars via OSC 52.
  • טרמינלים מסוימים מתעלמים מ-OSC 52. ב-iTerm2 יש להפעיל את ההגדרה תחת Settings > General > Selection > Applications in terminal may access clipboard, ואילו ב-macOS Terminal.app אין תמיכה ב-OSC 52 כלל.
  • להעתקת טקסט ללא OSC 52:
    • החזיקו את מקש הבחירה המקורי (native-selection) של הטרמינל בזמן הגרירה עם העכבר, והעתיקו עם הקיצור הרגיל (כגון Cmd+C). המקש הוא Fn ב-Terminal.app ו-Option ב-iTerm2.
    • הגדירו את משתנה הסביבה CLAUDE_CODE_DISABLE_MOUSE=1 במכונה המרוחקת כדי שהטרמינל ינהל את בחירת הטקסט לכל אורך הסשן.

#6. ביצועים ויציבות: צריכת זיכרון, תקיעות, טבלאות ותצוגה

• הליך התמודדות עם שימוש גבוה במעבד או בזיכרון: Claude Code נועד לעבוד עם רוב סביבות הפיתוח, אך עלול לצרוך משאבים משמעותיים בעיבוד מאגרי קוד גדולים. אם נתקלתם בבעיות ביצועים:
  1. השתמשו ב-/compact באופן קבוע לצמצום גודל ההקשר. אם הפקודה מחזירה Not enough messages to compact., השיחה מכילה מעט מדי תורות לסיכום (מצב שעלול לקרות גם בהקשר מלא בעקבות הדבקה גדולה בודדת).
  2. סגרו והפעילו מחדש את Claude Code בין משימות גדולות.
  3. שקלו להוסיף ספריות בנייה גדולות לקובץ .gitignore.
  4. הפעילו מחדש עם claude --safe-mode כדי לבדוק האם תוסף, שרת MCP או Hook הם מקור הבעיה. מצב זה משבית את כל ההתאמות האישיות לסשן הנוכחי. אם הצריכה יורדת, פנו לניפוי שגיאות בהגדרות לאיתור הגורם.
• אבחון מעמיק עם /heapdump:
  • אם צריכת הזיכרון נותרת גבוהה לאחר השלבים הללו, הריצו /heapdump. הפקודה מייצרת שני קבצים ב-~/Desktop (או בתיקיית הבית בלינוקס ללא שולחן עבודה):
    • תמונת זיכרון JavaScript בשם <session-id>.heapsnapshot.
    • פירוט זיכרון בשם <session-id>-diagnostics.json.
  • הפקודה מוסתרת מתפריט הפקודות, ויש להקליד אותה במלואה.
  • אזהרת אבטחה: הקובץ .heapsnapshot מכיל כל מחרוזת שנמצאת בתהליך, כולל תוכן השיחה המלא ופרטי הזדהות. אל תצרפו אותו לקריאות ציבוריות ואל תשתפו אותו.
  • הפקודה מדפיסה סיכום בשיחה המציג זיכרון Resident Set Size (RSS), זיכרון JS heap, חוצצי מערכים (array buffers), זיכרון native שלא נספר, ואינדיקטורים לדליפת זיכרון (כגון קצב גידול גבוה או מספר חריג של handles פתוחים).
  • דיווח או חקירה עצמית:
    • לדיווח: פתחו תקלה ב-GitHub וצרפו רק את הקובץ -diagnostics.json, המכיל נתונים סטטיסטיים ללא תוכן שיחה או פרטי גישה.
    • לחקירה עצמית: אם הסיכום מראה שרוב הזיכרון נמצא ב-JS heap, פתחו את הקובץ .heapsnapshot ב-Chrome DevTools תחת Memory > Load ומיינו לפי retained size. אם רוב הזיכרון הוא native, תמונת הזיכרון אינה מציגה זאת, ויש לכלול בדיווח את אינדיקטורי הדליפה מתוך הסיכום.
• טבלאות גדולות נחתכות בטרמינל: טבלת Markdown המכילה יותר מ-200 שורות מציגה את 200 השורות הראשונות ולאחריהן שורה: … N more rows not shown. רק התצוגה מוגבלת: הטבלה המלאה נשמרת בשיחה, והפקודה /copy מעתיקה את כל השורות. אם הטבלה גדולה מכדי לקרוא אותה בטרמינל, בקשו מקלוד לכתוב אותה לקובץ. לפני גרסה 2.1.208 קלוד קוד רינדר כל שורה, ולכן שחזור סשן שהכיל טבלה ענקית עלול היה להיתקע בזמן הרינדור מחדש.
• פקודה נתקעת או קופאת: אם Claude Code אינו מגיב:
  1. לחצו Ctrl+C כדי לנסות לבטל את הפעולה הנוכחית.
  2. אם אין תגובה, סגרו את הטרמינל והפעילו מחדש. הפעלה מחדש אינה מאבדת את השיחה. הריצו claude --resume באותה תיקייה כדי להמשיך בסשן.
• טקסט משובש בטרמינל משובץ של עורך (VS Code, Cursor, Devin Desktop): אם תווים מופיעים כריבועים, מריחות או גליפים שגויים, הסיבה היא לרוב מאיץ הגרפיקה (GPU renderer) של הטרמינל. הריצו /terminal-setup בתוך Claude Code כדי להגדיר את terminal.integrated.gpuAcceleration ל-"off", או הגדירו זאת ידנית בהגדרות העורך וטענו מחדש את החלון.
• גלילת גלגלת העכבר איטית ברינדור מסך מלא: ברינדור מסך מלא (fullscreen rendering), Claude Code גולל את השיחה בעצמו. כדי להגדיל את מספר השורות בכל תנועת גלגלת, הריצו /scroll-speed ושמרו, או הגדירו את משתנה הסביבה CLAUDE_CODE_SCROLL_SPEED (מלבד בטרמינל של JetBrains, שבו קלוד מפעיל טיפול גלילה משלו ושני האמצעים אינם משפיעים). לגלילה מהירה ללא שינוי מהירות, לחצו PgUp ו-PgDn לגלילה של חצי מסך בכל פעם, או הריצו /tui default כדי לחזור לרינדור הקלאסי.

#7. תקלות חיפוש, איתור קבצים וסביבת WSL

• המלכודת: כלי החיפוש (Search), תיוגי @file, סוכנים מותאמים או מיומנויות אינם מוצאים קבצים, או שחיפוש ב-WSL מחזיר מעט תוצאות ואיטי במיוחד.
• התקנת ripgrep מקומי במידה והבינארי המובנה אינו פועל: אם ripgrep המובנה אינו רץ במערכת שלכם, התקינו את החבילה המתאימה:
  • ב-macOS:

brew install ripgrep

• ב-Ubuntu/Debian:

sudo apt install ripgrep

• ב-Alpine (נמצא במאגר הקהילה של Alpine):

apk add ripgrep

• ב-Arch:

pacman -S ripgrep

• ב-Windows:

winget install BurntSushi.ripgrep.MSVC

לאחר ההתקנה, הגדירו את USE_BUILTIN_RIPGREP ל-0, במשתני הסביבה של המעטפת או בבלוק env בקובץ settings.json:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

כדי לוודא שהשינוי נכנס לתוקף, הריצו claude doctor בטרמינל ובדקו שבשורת Search מופיע נתיב ה-ripgrep של המערכת במקום OK (bundled).

• חיפוש איטי או חלקי ב-WSL: קריאת דיסק בין מערכות קבצים ב-WSL פוגעת בביצועים ועלולה לגרום להחזרת פחות תוצאות מהמצופה. החיפוש עדיין פועל, אך מחזיר פחות תוצאות מאשר במערכת קבצים טבעית (שימו לב ש-claude doctor עדיין יציג Search כ-OK במצב זה). הפתרונות לפי התיעוד:
  1. הגשת חיפושים ספציפיים וממוקדים יותר: צמצמו את מספר הקבצים הנסרקים על ידי ציון תיקיות או סוגי קבצים (לדוגמה: "Search for JWT validation logic in the auth-service package" או "Find use of md5 hash in JS files").
  2. העברת הפרויקט למערכת הקבצים של Linux: ודאו שהפרויקט שמור תחת נתיב הלינוקס (/home/) ולא במערכת הקבצים של Windows (/mnt/c/).
  3. עבודה מקורית ב-Windows: שקלו להריץ את Claude Code ישירות ב-Windows במקום דרך WSL, לשיפור ביצועי מערכת הקבצים.

#8. הרחבת היכולות: כלי CLI, שרתי MCP, מיומנויות, Hooks ותוספים

• שימוש בכלי CLI חיצוניים: כלי CLI הם הדרך היעילה ביותר מבחינת ניצול הקשר לאינטראקציה עם שירותים חיצוניים. אם אתם עובדים מול GitHub, התקינו את כלי ה-CLI הרשמי gh. קלוד יודע להשתמש בו לפתיחת issues, הגשת pull requests וקריאת תגובות. ללא gh, קלוד עדיין יכול להשתמש ב-API של GitHub, אך בקשות ללא אימות מגיעות במהירות למגבלות קצב (rate limits). קלוד לומד ביעילות גם כלי CLI חדשים: ניתן להשתמש בפרומפט כגון: Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C.. כלי CLI מומלצים נוספים כוללים את aws, gcloud ו-sentry-cli.
• חיבור שרתי MCP: שרתי MCP מאפשרים לקלוד להטמיע משימות ממערכות ניהול משימות, לתשאל מסדי נתונים, לנתח נתוני ניטור, לשלב עיצובים מ-Figma ולאטמת תהליכי עבודה. לחיבור שרת MCP הריצו claude mcp add עם שם וכתובת או פקודה. לדוגמה:

claude mcp add --transport http notion https://mcp.notion.com/mcp

• יצירת Skills מותאמים: מיומנויות מרחיבות את הידע של קלוד עם מידע ייחודי לפרויקט, לצוות או לתחום שלכם. קלוד מחיל אותן אוטומטית כשהן רלוונטיות, או שניתן להפעיל אותן ישירות עם /skill-name. כדי ליצור מיומנות, הוסיפו תיקייה עם קובץ SKILL.md תחת .claude/skills/:

---
name: api-conventions
description: REST API design conventions for our services
---
# API Conventions
- Use kebab-case for URL paths
- Use camelCase for JSON properties
- Always include pagination for list endpoints
- Version APIs in the URL path (/v1/, /v2/)

מיומנויות יכולות להגדיר גם תהליכי עבודה חוזרים להפעלה ידנית. הגדירו disable-model-invocation: true עבור תהליכים בעלי תופעות לוואי שברצונכם להפעיל ידנית בלבד:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.

1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR

להפעלת התהליך הריצו למשל /fix-issue 1234.

• הגדרת תת-סוכנים מותאמים (Custom Subagents): תת-סוכנים רצים בחלון הקשר עצמאי משלהם עם סט כלים מורשה מוגדר, ומתאימים למשימות שקוראות קבצים רבים או דורשות מיקוד מיוחד בלי להעמיס על השיחה הראשית. הגדירו עוזרים בתיקיית .claude/agents/, למשל:

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.

הנחו את קלוד להשתמש בסוכן במפורש: "Use a subagent to review this code for security issues.".

• התקנת תוספים (Plugins): תוספים מאגדים מיומנויות, Hooks, תת-סוכנים ושרתי MCP לחבילת התקנה יחידה מקהילת המפתחים ומ-Anthropic. הריצו /plugin כדי לעיין במאגר. בעבודה עם שפות בעלות טיפוסיות (typed languages), התקינו תוסף code intelligence לניווט סמלים מדויק וזיהוי שגיאות אוטומטי לאחר עריכות.

#9. ניהול שיחה, חזרה לאחור וסנכרון סשנים

• תיקון כיוון מוקדם ולעיתים קרובות: התוצאות הטובות ביותר מושגות במשוב מהיר:
  • מקש Esc: עוצר את קלוד באמצע פעולה. ההקשר נשמר, כך שניתן לכוון אותו מחדש.
  • Esc + Esc או /rewind: פותח את תפריט ה-rewind לשחזור מצב השיחה והקוד, או לסיכום מהודעה נבחרת.
  • הפקודה "Undo that": מבקשת מקלוד לבטל את השינויים שביצע.
  • /clear: מאפס את ההקשר במעבר בין משימות שאינן קשורות.
  • חוק שני התיקונים: אם תיקנתם את קלוד יותר מפעמיים באותו סשן על אותו נושא, ההקשר נסתם בגישות כושלות. הריצו /clear והתחילו מחדש עם פרומפט מדויק יותר שמשלב את מה שנלמד.
• נקודות ביקורת (Checkpoints) ושחזור:
  • כל פרומפט שפותח תור מייצר נקודת ביקורת אוטומטית. קלוד שומר תמונת מצב של הקבצים לפני כל שינוי, כך שנקודת הביקורת יכולה לשחזר אותם.
  • לחצו פעמיים על Escape או הריצו /rewind כדי לפתוח את תפריט השחזור. ניתן לשחזר שיחה בלבד, לשחזר קוד בלבד, לשחזר את שניהם יחד, או לסכם מהודעה נבחרת.
  • במקום לתכנן כל צעד בזהירות, אפשר לתת לקלוד לנסות גישה מסוכנת, ואם היא נכשלת: לחזור לאחור ולנסות גישה אחרת. נקודות הביקורת נשמרות עם השיחה, כך שניתן לסגור את הטרמינל, לחדש את הסשן מאוחר יותר ועדיין לחזור לאחור.
  • מגבלה חשובה: נקודות ביקורת עוקבות אך ורק אחרי שינויים שבוצעו באמצעות כלי עריכת הקבצים של קלוד. שינויים שבוצעו באמצעות פקודות Bash או תהליכים חיצוניים אינם נלכדים. זה אינו תחליף ל-Git.
• חידוש וניהול סשנים:
  • Claude Code שומר שיחות מקומית. כאשר משימה מתפרסת על פני כמה ישיבות עבודה, אין צורך להסביר את ההקשר מחדש.
  • הריצו claude --continue כדי להמשיך מהמקום שבו עצרתם.
  • הריצו claude --resume כדי לבחור סשן מתוך רשימה.
  • תנו לסשנים שמות תיאוריים באמצעות /rename (למשל oauth-migration) והתייחסו אליהם כמו לענפי Git: כל מסלול עבודה מקבל הקשר נפרד ומתמשך.

#10. אוטומציה והרחבה: סשנים מקבילים, ריצה אוטונומית ובדיקה עוינת

• הרצה ללא ממשק אינטראקטיבי (Non-interactive mode):
  • באמצעות claude -p "prompt" ניתן להריץ את קלוד ישירות מסקריפטים, מתהליכי CI או מ-pre-commit hooks. הריצה שומרת סשן שניתן להמשיך בהמשך, אלא אם מועבר הדגל --no-session-persistence.
  • פורמטי הפלט מאפשרים עיבוד ממוחשב: טקסט רגיל, JSON, או הזרמת JSON:

# שאילתות חד-פעמיות בטקסט רגיל
claude -p "Explain what this project does"

# פלט מובנה לסקריפטים כאובייקט JSON יחיד עם שדה result
claude -p "List all API endpoints" --output-format json

# הזרמת פלט בזמן אמת עם אובייקט JSON לכל שורה
claude -p "Analyze this log file" --output-format stream-json --verbose

• שילוב בצינורות עיבוד נתונים:

claude -p "<your prompt>" --output-format json | your_command

• ריצה אוטונומית ב-auto mode:
  • להרצה ללא הפרעות עם בדיקות אבטחה ברקע, השתמשו ב-auto mode:

claude --permission-mode auto -p "fix all lint errors"

• מודל מסווג סוקר פקודות לפני הרצתן וחוסם הסלמת הרשאות, תשתית לא מוכרת ופעולות מונחות תוכן עוין, בזמן שעבודה שגרתית מתקדמת ללא בקשות אישור.
• כאשר המסווג חוסם שוב ושוב פעולות בריצה ללא ממשק עם דגל -p, Claude Code אינו עוצר את הריצה.
• הרצת סשנים מרובים במקביל:
  • סשנים במקביל מאיצים פיתוח, מאפשרים ניסויים מבודדים ומספקים הקשר נקי לבדיקת קוד (כדי שקלוד לא יהיה מוטה כלפי קוד שזה עתה כתב בעצמו).
  • דרכי הפעלה מקבילות:
    • עבודה עם Worktrees: הפעלת סשנים נפרדים של ה-CLI בתיקיות checkout נפרדות של Git כדי למנוע התנגשויות עריכה.
    • הודעות בין סשנים (Cross-session messaging): העברת ממצאים בין סשנים שאתם מריצים.
    • אפליקציית שולחן העבודה (Desktop app): ניהול חזותי של מספר סשנים מקומיים.
    • קלוד בענן (Claude Code on the web): הרצת סשנים על גבי תשתית מנוהלת של Anthropic.
    • תצוגת סוכנים (Agent view): תצוגה מקדימה מחקרית. הרצת claude agents לשיגור סשנים שרצים ברקע וצפייה בהם ממסך יחיד.
    • צוותי סוכנים (Agent teams): תכונה ניסיונית הכבויה כברירת מחדל, לתיאום אוטומטי של מספר סשנים עם משימות משותפות ומוביל צוות.
  • דפוס כותב ובודק (Writer/Reviewer pattern):

• ניתן ליישם דפוס דומה עם בדיקות: סשן אחד כותב בדיקות, וסשן שני כותב את הקוד שגורם להן לעבור.
• פיזור משימות על פני קבצים (Fan out):
  • במאגר Git, הריצו /batch <instruction> כדי שקלוד יפצל את השינוי בין 5 ל-30 תת-סוכנים, כאשר כל תת-סוכן פועל ב-worktree נפרד ופותח pull request.
  • לפיזור משימות מתוך סקריפט משלכם, השתמשו בלולאה על claude -p לפי שלושת השלבים:
    1. יצירת רשימת משימות: בקשו מקלוד לשמור לקובץ את רשימת הקבצים הדורשים הגירה, למשל: list all 2,000 Python files that need migrating and save the list to files.txt.
    2. כתיבת סקריפט שרץ בלולאה על הרשימה:

for file in $(cat files.txt); do
  claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

3. בדיקה על קבצים בודדים והרצה מלאה: כוונו את הפרומפט בהתאם לתקלות ב-2 עד 3 הקבצים הראשונים, ואז הריצו על כל הקבצים. הדגל `--allowedTools` מגביל את מה שקלוד מורשה לבצע, דבר קריטי בריצה ללא השגחה.

• שלב ביקורת עוינת (Adversarial Review):
  • לפני שמגדירים משימה כהושלמה, הפעילו תת-סוכן שיבדוק את ה-diff בהקשר נקי וידווח על פערים. סוכן בודק רואה רק את ה-diff ואת הקריטריונים שסיפקתם, ללא נימוקי העבודה המקוריים, וכך מעריך את התוצאה בצורה אובייקטיבית.
  • לבדיקת תקינות, הריצו את המיומנות המובנית /code-review, הבודקת את ה-diff הנוכחי לאיתור באגים בתוך subagent נקי ומחזירה ממצאים לסשן.
  • לבדיקת ה-diff מול התוכנית, נסחו פרומפט בדיקה ממוקד:

Use a subagent to review the rate limiter diff against PLAN.md. Check that
every requirement is implemented, the listed edge cases have tests, and
nothing outside the task's scope changed. Report gaps, not style preferences.

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

#11. דפוסי כשל נפוצים שכדאי לזהות מוקדם

• סשן "כלבו" (The kitchen sink session): התחלתם במשימה אחת, שאלתם משהו לא קשור, וחזרתם למשימה הראשונה. ההקשר מלא במידע לא רלוונטי שמסיח את דעתו של קלוד.
  • תיקון: הריצו /clear בין משימות שאינן קשורות.
• תיקונים חוזרים ונשנים (Correcting over and over): קלוד טועה, אתם מתקנים, הוא עדיין טועה, אתם מתקנים שוב. ההקשר מזדהם בגישות כושלות.
  • תיקון: לאחר שני תיקונים שנכשלו, הריצו /clear וכתבו פרומפט פתיחה טוב יותר שמשלב את מה שלמדתם.
• קובץ CLAUDE.md עמוס מדי (The over-specified CLAUDE.md): כאשר הקובץ ארוך מדי, קלוד מתעלם מחלק מההוראות משום שכללים חשובים נבלעים ברעש.
  • תיקון: גזמו ללא רחמים. אם קלוד כבר פועל נכון בלי ההוראה, מחקו אותה או העבירו אותה ל-Hook.
• פער בין אמון לאימות (The trust-then-verify gap): קלוד מייצר יישום שנראה אמין במבט ראשון, אך אינו מתמודד עם מקרי קצה.
  • תיקון: ספקו תמיד אמצעי אימות (בדיקות, סקריפטים, צילומי מסך). אם אינכם יכולים לאמת, אל תוציאו לייצור.
• חקירה אינסופית (The infinite exploration): ביקשתם מקלוד "לחקור" נושא מסוים בלי לתחום את המשימה. קלוד קורא מאות קבצים וממלא את ההקשר.
  • תיקון: הגדירו גבולות ברורים לחקירה מראש או השתמשו ב-subagents כדי שהחקירה לא תכלה את חלון ההקשר הראשי שלכם.

#12. קבלת עזרה נוספת ודיווח על תקלות

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

1. הריצו /doctor לבדיקת ההתקנה וההגדרות, והריצו /mcp לבדיקת סטטוס שרתי ה-MCP.
2. השתמשו בפקודה /feedback בתוך Claude Code כדי לדווח על בעיות ישירות ל-Anthropic.
3. בדקו את מאגר ה-GitHub של Claude Code (https://github.com/anthropics/claude-code) לאיתור תקלות מוכרות.
4. שאלו את קלוד ישירות על יכולותיו ותכונותיו, שכן יש לו גישה מובנית לתיעוד שלו.

עבור בעיות בחשבון, חיוב או מנויים, פנו לתמיכה של Anthropic: התחברו בכתובת claude.ai (משתמשי קונסול: platform.claude.com), לחצו על ראשי התיבות שלכם בפינה השמאלית התחתונה ובחרו באפשרות Get help.