Repository Mapping ל-AI — איך מודל מבין Codebase ענק

מאת צוות מדיה דיל · 09.08.2026 · AI · 7 דק׳

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

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

למה זה בכלל בעיה חדשה

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

למה גישה נאיבית לא עובדת

הגישה הפשוטה ביותר - לזרוק לפרומפט את כל תוכן הריפו, או לתת למודל לקרוא קובץ-קובץ באופן חופשי - נכשלת משתי סיבות. הראשונה היא כלכלית וטכנית: חלון ההקשר מוגבל, וגם כשהוא גדול, עלות ו-latency גדלים ליניארית עם כמות הטוקנים. השנייה עמוקה יותר - מחקרים על ביצועי מודלים מראים שירידה באיכות ההתייחסות למידע ("lost in the middle") מתרחשת כשההקשר עמוס במידע לא רלוונטי, גם אם טכנית הוא "נכנס". מודל שמקבל 50 קבצים כשרק 3 רלוונטיים לא רק מבזבז טוקנים - הוא נוטה לפספס את הפרטים החשובים בתוך הרעש.

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

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

• מפת מבנה (structural map) - עץ התיקיות והקבצים, לרוב עם תיאור קצר לכל מודול - "מה יש כאן" ברמת-על.
• גרף תלויות (dependency graph) - מי קורא למי: imports, exports, קריאות פונקציה בין קבצים. זה מאפשר לשאול "אם אני משנה את הפונקציה הזו, מה עוד עלול להישבר".
• אינדקס סמלים (symbol index) - רשימת כל הפונקציות, מחלקות, טיפוסים והמיקום המדויק שלהם, בדרך כלל נבנה באמצעות ניתוח AST.
• שכבת embeddings - ייצוג וקטורי של קטעי קוד לצורך חיפוש סמנטי כשהשאילתה היא תיאור טבעי ולא מונח מדויק.

השילוב של ארבע השכבות מאפשר לענות על טווח רחב של שאילתות: "איפה מוגדר ה-User model" (symbol index), "מה תלוי בקובץ הזה" (dependency graph), "איפה יש קוד שמטפל בהרשאות" (embeddings), "מה המבנה הכללי של השירות" (structural map).

איך בונים גרף תלויות בפועל

הבנייה מתבססת על ניתוח סטטי של הקוד - פרסור כל קובץ למבנה AST, וחילוץ קשרי import/export ממנו. עבור JavaScript/TypeScript, למשל, הכלים בונים גרף שבו כל צומת הוא מודול, וכל קשת מייצגת import. הגרף הזה מאפשר שאילתות שימושיות מאוד לסוכן: "אילו קבצים משתמשים בפונקציה הזו" (impact analysis לפני שינוי), "מהו העומק המקסימלי של שרשרת התלויות" (זיהוי אזורים שבירים), ו"אילו מודולים אין להם תלויות נכנסות" (קוד מת פוטנציאלי).

{
  "module": "services/payment.ts",
  "exports": ["chargeCustomer", "refund"],
  "imports": ["lib/idempotency.ts", "models/order.ts"],
  "imported_by": ["routes/checkout.ts", "webhooks/stripe.ts"],
  "symbols": [
    {"name": "chargeCustomer", "kind": "function", "line": 42},
    {"name": "PaymentError", "kind": "class", "line": 12}
  ]
}

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

אסטרטגיית האחזור בזמן ריצה

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

Chunking לקוד - למה זה שונה מטקסט רגיל

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

עדכון המפה - ריפו שמשתנה כל הזמן

מפה שנבנתה פעם אחת ולא מתעדכנת הופכת מהר מאוד ללא רלוונטית - קוד משתנה כל commit. המימוש הנכון הוא אינקרמנטלי: hook על commit או merge שמזהה אילו קבצים השתנו, מריץ מחדש את ניתוח ה-AST רק עליהם, ומעדכן את גרף התלויות והאינדקס הווקטורי בהתאם. בריפו גדול עם קצב commits גבוה, זה ההבדל בין מפה שרלוונטית תמיד לבין מפה שסוכן AI מתחיל לא לסמוך עליה.

עלות בניית המיפוי מול תועלת האחזור

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

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

מיפוי היררכי - מ-Monorepo ועד Microservices

בארגונים עם monorepo שמכיל עשרות שירותים, מיפוי שטוח של כל הריפו כיחידה אחת יוצר בעיה הפוכה מזו שרצינו לפתור - יותר מדי הקשר לא רלוונטי. הפתרון הנפוץ הוא מיפוי היררכי: שכבת-על שממפה את גבולות השירותים (איזה תיקיית root שייכת לאיזה שירות, מהם ה-API contracts בין שירותים), ומתחתיה מיפוי מפורט לכל שירות בנפרד. כשסוכן מקבל משימה, הוא קודם מזהה לאיזה שירות היא שייכת ברמת השכבה העליונה, ורק אז "צולל" למיפוי המפורט של אותו שירות בלבד. הגישה הזו שומרת את זמן האחזור קצר גם בריפו בגודל עצום, ומונעת מצב שבו שינוי בשירות אחד "מזהם" את ההקשר עם קוד לא קשור משירות אחר לגמרי. זה גם המקום שבו גבולות ה-API - REST endpoints, event schemas, gRPC contracts - הופכים לחלק חשוב מהמפה, כי הם מגדירים את נקודות התפר שבהן שינוי בשירות אחד עלול לשבור שירות אחר בלי שהקוד עצמו "מקושר" ישירות.

מיפוי היסטוריה - מה Git מוסיף לתמונה

מעבר למבנה הסטטי של הקוד ברגע נתון, היסטוריית ה-git מוסיפה ממד שימושי מאוד למיפוי: אילו קבצים משתנים תמיד יחד (co-change patterns), מי הכותב האחרון של כל קטע קוד, ובאילו קבצים יש היסטוריית תיקוני באגים גבוהה במיוחד. מידע כזה עוזר לסוכן לתעדף - אם קובץ מסוים משתנה כמעט בכל commit יחד עם קובץ אחר, סביר שיש ביניהם תלות סמויה שלא נראית בניתוח סטטי של imports בלבד, למשל תלות דרך API חיצוני משותף או קונבנציה לא-מפורשת. שילוב שכבת ההיסטוריה עם גרף התלויות הסטטי נותן תמונה עשירה משמעותית ממה שכל שכבה נותנת לבד, והוא שימושי במיוחד למשימות כמו איתור regression - הבנה מהירה של אילו שינויים היסטוריים גרמו לבעיות דומות בעבר.

טעויות נפוצות

• הסתמכות רק על חיפוש טקסטואלי - grep מוצא מחרוזת מדויקת אבל מפספס כשהתיאור במשימה לא תואם מילולית לשמות בקוד.
• מפה סטטית שלא מתעדכנת - מובילה לסוכן שמסתמך על מידע שגוי על מבנה הקוד.
• חיתוך chunks לפי שורות במקום לפי AST - פוגע קשות באיכות האחזור לקוד.
• התעלמות מ-monorepo boundaries - במונורפו עם כמה שירותים, מיפוי גלובלי בלי הפרדה לפי שירות מייצר רעש מיותר.
• התעלמות מהיסטוריית git - אובדן מידע יקר על תלויות סמויות שלא נראות בניתוח סטטי בלבד.

שאלות נפוצות

האם צריך לבנות Repository Mapping בעצמי או יש כלים מוכנים?

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

מה גודל הריפו שממנו כדאי להתחיל להשתמש במיפוי מלא?

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

איך זה מתקשר ל-Context Engineering?

Repository Mapping הוא רכיב אחד בתוך הנדסת הקשר רחבה יותר - האסטרטגיה הכוללת של מה נכנס לפרומפט, מתי, ובאיזה סדר.

האם מיפוי הריפו עוזר גם ל-Code Review אוטומטי?

מאוד. גרף התלויות מאפשר לreviewer אוטומטי להבין את ה"רדיוס פגיעה" של שינוי - לא רק מה שונה, אלא מה עוד עלול להיפגע ממנו.

מה קורה כשהמפה "מתיישנת" ולא תואמת את הקוד בפועל?

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

בניית שכבת מיפוי ריפו מותאמת אישית - עם גרף תלויות, אינדוקס AST ואחזור סמנטי - היא תשתית קריטית לכל מערכת AI שעובדת על קוד בקנה מידה ארגוני. מדיה דיל בונה תשתיות כאלה כחלק מפתרונות ה-AI שלנו. לשיחת ייעוץ אפשר לפנות בוואטסאפ.

תגיות: Repository Mapping · Codebase · AST · Dependency Graph · Semantic Code Search · AI Agent · Context Engineering

← חזרה לבלוג · צור קשר