לדלג לתוכן

4.3 קבצים גדולים תמונות ופלט ארוך הרצאה

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

הבעיה עם "פשוט לתת הכל" - the naive approach

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

כוונו לפרוסה הנכונה - point at the slice

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

השוו בין שתי הגישות:

# Bad - pastes 3000 lines into the chat
[pastes the entire auth.py file]
find the bug

# Good - points at the slice
There's an authentication bug in auth.py, probably in the
refresh_token function. Read just that function and check
the expiration handling.

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

סינון פלט לפני שהוא נכנס - filtering output

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

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

# runs and puts into context only the lines with an error
! grep -n "ERROR" app.log | tail -50

# only the relevant part of a huge file
! sed -n '1200,1260p' huge_file.py

זה מכניס לcontext עשרות שורות במקום עשרות אלפים. לפי התיעוד, החל מגרסה מסוימת Claude אף מגיב אוטומטית לפלט של פקודת ! ברגע שהוא נוחת - כך אפשר להריץ ! npm test ולקבל הסבר על הכשלים בלי פרומפט נוסף.

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

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

# if tests are running, filter to show only failures
if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"updatedInput\":{\"command\":\"$filtered_cmd\"}}}"
else
  echo "{}"
fi

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

פלט ארוך של פקודות - long command output

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

אפשר לבקש מ-Claude להריץ פקודה ברקע, או להעביר פקודה שכבר רצה לרקע עם Ctrl+B (במשתמשי tmux לוחצים פעמיים). כמה נקודות מהתיעוד:

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

את מה שרץ ברקע רואים עם הפקודה /tasks. הרעיון: פלט ארוך לא צריך לזרום לcontext, הוא צריך לשבת בקובץ, ו-Claude ישלוף ממנו את הפרוסה הרלוונטית.

האצלה לsub-agent - delegate to a subagent

הtool החזק ביותר לפעולות "רועשות" הוא האצלה לsub-agent. פעולות שצורכות הרבה context - הרצת בדיקות, שליפת תיעוד, עיבוד קובצי לוג - אפשר להאציל לsub-agent. לפי התיעוד, כך הפלט המפורט נשאר בcontext של sub-agent, ורק סיכום חוזר לשיחה הראשית שלכם. לsub-agent יש context טרי ונפרד לגמרי.

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

תמונות וצילומי מסך - images and screenshots

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

הדרך המרכזית להעביר תמונה היא הדבקה מהלוח. לפי התיעוד, Ctrl+V מדביק תמונה מהלוח (ב-iTerm2 גם Cmd+V, ב-Windows ו-WSL Alt+V). שימו לב: זה שונה מהדבקת טקסט רגילה. כשמדביקים תמונה, מוכנס למקום הסמן צ'יפ בצורת [Image #N], כך שאפשר להתייחס אליו במיקום בתוך הפרומפט:

[paste a screenshot with Ctrl+V, Image #1 appears]
This screen should look like [Image #1], but for me the button
wraps to a new line. Check the CSS of .checkout-button and fix it.

שימושים אופייניים:

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

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

ידע במקום סריקה - skills over exploration

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

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

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

המדד הנכון - what to keep in mind

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

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

זרימת עבודה מלאה - a worked example

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

# 1. Filter the log in shell mode - only lines around the error
! grep -n "TimeoutError" prod.log | tail -30

# 2. Paste the screenshot of the error
[Ctrl+V -> Image #1]

# 3. Point Claude at the slice, not the whole file

ואז הפרומפט: "השגיאה ב-[Image #1] תואמת ל-TimeoutError שרואים בלוג למעלה. אני חושד ב-connection pool ב-db/pool.py. תקרא רק את הפונקציה acquire ותבדוק את הטיפול ב-timeout." בגרסה הזו, הcontext סופג 30 שורות לוג במקום 40,000, תמונה אחת רלוונטית, ופונקציה אחת במקום מודול שלם. אם הבדיקה של התיקון מייצרת פלט ארוך, מריצים אותה ברקע או מאצילים אותה לsub-agent. זו כל התמונה: בכל שלב, הפרוסה במקום השלם.

סיכום

  • אל תדביקו הכל: קובץ ענק, לוג של אלפי שורות או פלט ארוך מנפחים את הcontext, עולים טוקנים, פוגעים באיכות, ובמקרה קיצון גורמים לשגיאת thrashing בדחיסה.
  • כוונו לפרוסה: תנו ל-Claude מיקום ומה שמחפשים (למשל שם פונקציה), ותנו לו לקרוא רק את הקטע הרלוונטי במקום את כל הקובץ.
  • סננו לפני: מצב shell עם ! והרצת grep/sed מכניס לcontext רק שורות רלוונטיות. הוקים - hooks מסוג PreToolUse יכולים לסנן פלט אוטומטית (למשל grep על ERROR) ולצמצם עשרות אלפי טוקנים למאות.
  • פלט ארוך: הריצו ברקע (Ctrl+B, או בקשה מ-Claude). הפלט נכתב לקובץ, Claude שולף ממנו רק את הנחוץ; רואים מה רץ עם /tasks. משימה נעצרת מעל 5GB.
  • האצלה לsub-agent: פעולות רועשות (בדיקות, לוגים, תיעוד) מוטב להאציל - הפלט נשאר בcontext של sub-agent, ורק סיכום חוזר אליכם.
  • תמונות: Ctrl+V מדביק תמונה ומכניס צ'יפ [Image #N]. שימושי לדיבוג ויזואלי, עבודה מול עיצוב ושגיאות. הדבקת מוקאפ נותנת לagent יעד לאימות ומשפרת את התוצאה.