AGENTS.md — כיצד מלמדים סוכן לעבוד נכון בתוך Repository
מאת צוות מדיה דיל · 12.08.2026 · Agentic Development · 5 דק׳
מדריך מעשי לכתיבת קובץ AGENTS.md אפקטיבי — מה לכלול, מה להשמיט, ואיך למנוע מהסוכן לחזור על אותן טעויות שוב ושוב בפרויקט.
צוות פיתוח שהתחיל להשתמש בסוכני קוד באופן שוטף גילה תבנית מתסכלת: כל סוכן חדש שמופעל על ה-repository "ממציא מחדש" את אותן החלטות — משתמש בספריית HTTP הלא נכונה, כותב טסטים בפורמט שלא תואם את שאר הפרויקט, או מריץ פקודת build שגויה כי לא ידע שיש script ייעודי. הפתרון לא היה "לתת prompt יותר טוב" בכל פעם מחדש, אלא לכתוב פעם אחת קובץ הנחיה קבוע שכל סוכן קורא בתחילת הסשן — AGENTS.md. זהו הקובץ שהפך בפועל לתקן הבלתי רשמי של התעשייה למתן context מבני לסוכני קוד, וההבדל בין קובץ AGENTS.md טוב לגרוע הוא לרוב ההבדל בין סוכן שעוזר לבין סוכן שיוצר עוד עבודה.
מה AGENTS.md פותר בפועל
ה-prompt שמפתח כותב לסוכן מתאר בדרך כלל את המשימה — "תקן את הבאג הזה", "תוסיף endpoint חדש". הוא כמעט אף פעם לא מתאר את ההקשר הרחב: איך מריצים טסטים בפרויקט הזה, אילו קבצים אסור לגעת בהם, מה מוסכמות השמות, ואיפה נמצא ה-source of truth לסכמת ה-DB. בלי המידע הזה, סוכן נאלץ לנחש, ולפעמים הניחוש הזה יקר — למשל כשהוא מריץ migration נגד DB פרודקשן במקום סביבת פיתוח, כי אף אחד לא אמר לו איפה גבול הבטיחות עובר. AGENTS.md הוא בדיוק המקום לתעד את הידע ה"מובן מאליו" הזה, שבדרך כלל עובר בעל-פה בין מפתחים ולעולם לא נכתב.
חשוב להבחין בין AGENTS.md לבין README רגיל: README מיועד לבני אדם שמכירים כבר את התחום ורק צריכים הקשר ראשוני. AGENTS.md מיועד לתהליך שמריץ את הפרויקט תוך דקות בלי שום ידע קודם, ולכן חייב להיות ישיר, פרוצדורלי, ולעיתים חוזר על מידע שנראה "ברור מאליו" לבן אדם.
הבדל נוסף חשוב הוא הטון. README כתוב לרוב בשפה שיווקית-הסברית — "הפרויקט הזה מאפשר לכם...". AGENTS.md צריך להיקרא כמו רשימת הוראות תפעול: פועל יחיד, ציווי, בלי הקדמות. "הרץ npm run test:unit לפני כל commit" עדיף על "מומלץ להריץ את בדיקות היחידה". ההבדל הזה נראה קוסמטי אבל משפיע בפועל על מידת הוודאות שסוכן מייחס להוראה — ניסוח מותנה נוטה להתפרש כהמלצה שאפשר לדלג עליה בלחץ זמן, בעוד ציווי ברור מתפרש כדרישה.
מה כן לכלול: ה-Core של קובץ טוב
קובץ AGENTS.md אפקטיבי, לפי ניסיון מצוותים שכבר עובדים כך, מתמקד בסעיפים ספציפיים:
- פקודות הרצה — build, test, lint, ולא רק שמם אלא גם flags נדרשים וזמן ריצה משוער.
- גבולות בטיחות — אילו קבצים/תיקיות אסורים לשינוי, אילו פעולות דורשות אישור אנושי מפורש.
- מוסכמות פרויקט — דפוסי error handling, מבנה תיקיות, קונבנציית naming שחורגת מהסטנדרט.
- מלכודות ידועות — התנהגות לא אינטואיטיבית בקוד שגרמה לבאגים בעבר.
- הפניה למקורות אמת — היכן נמצא ה-schema, ה-API contracts, וקבצי spec רלוונטיים.
הרעיון המרכזי: כל שורה ב-AGENTS.md צריכה למנוע טעות ספציפית וידועה, לא לתאר את הפרויקט באופן כללי. קובץ שמתאר "המערכת בנויה מ-Frontend ו-Backend" לא עוזר לאף סוכן — קובץ שאומר "אל תריץ npm run db:reset נגד DATABASE_URL של production, יש script נפרד ל-staging" כן.
מלכודת ה-Context Bloat
הטעות השכיחה ביותר בכתיבת AGENTS.md היא הפיכתו למסמך ארוך מדי, שמנסה לתעד הכול. קובץ שתופס אלפי שורות לא רק מבזבז context window יקר בכל סשן — הוא גם מקטין את הסבירות שהמידע הקריטי באמת ייקרא ויופעל, כי הוא טובע בתוך רעש. גישה טובה יותר היא היררכיה: AGENTS.md מרכזי קצר בשורש הפרויקט, וקבצי AGENTS.md משניים בתיקיות ספציפיות (כמו api/ או packages/billing/) שמכילים רק את ההקשר הרלוונטי לאותו תת-אזור, ונטענים רק כשהסוכן פועל שם בפועל.
מבנה מדורג כזה גם פותר בעיה שנייה: קובץ ענק אחד דורש עדכון תמידי מכל מי שנוגע בכל חלק במערכת, בעוד שקבצים ממוקדים אפשר לתחזק בצורה מבוזרת, כל צוות אחראי על החלק שלו.
מבחן פשוט לבדיקה אם קובץ AGENTS.md סובל מ-context bloat: להריץ סוכן על משימה קונקרטית ולבדוק אם הוא בפועל פנה למידע מהקובץ, או שהוא פשוט התעלם ממנו וניחש לבד. אם ההתעלמות חוזרת על עצמה, כדאי לחשוד שהקובץ ארוך מדי או לא ממוקד מספיק, ולא להסיק ישר שהסוכן "לא קורא הוראות" — ברוב המקרים הבעיה היא באיכות המידע ובמיקומו, לא ביכולת הסוכן לעבד אותו.
שילוב עם ארכיטקטורת Sub-Agents
כשעובדים עם ארכיטקטורת סוכני-משנה, כמו זו שמפורטת במדריך Sub-Agents ב-Claude Code, AGENTS.md הופך לחשוב אף יותר: סוכן-משנה שמתמחה בכתיבת טסטים צריך context שונה מסוכן-משנה שמתמחה בסקירת אבטחה, ולכן שווה לתחזק סעיפים ייעודיים לכל תפקיד בתוך הקובץ, או קבצים נפרדים לגמרי לפי תחום אחריות. הגישה הזו גם עוזרת כשעובדים עם מספר סוכנים מקבילים על אותו repository, נושא שמקבל טיפול מלא במדריך Parallel Coding Agents — כל סוכן מקבל את אותה נקודת התייחסות משותפת, ולא מפתח פרשנות עצמאית לכללים.
תחזוקה: איך שומרים על הקובץ מעודכן
הבעיה הגדולה ביותר בטווח הארוך היא ש-AGENTS.md נכתב פעם אחת בהתלהבות ואז מתיישן, בדיוק כמו כל תיעוד אחר. הפרקטיקה הטובה ביותר שנצפתה בצוותים מבוגרים היא לחייב עדכון של AGENTS.md כחלק מכל PR שמשנה קונבנציה, workflow או מוסיף מלכודת חדשה — ממש כמו שדורשים עדכון טסטים. חלק מהצוותים אפילו מריצים סוכן ייעודי, שתפקידו לבדוק אחרי כל merge משמעותי אם ה-AGENTS.md עדיין תקף, ולסמן סתירות בין מה שכתוב שם לבין מה שקורה בפועל בקוד — צעד שמתקשר ישירות לרעיון של Repository Intelligence חי ולא סטטי.
בפועל, קבוצה שמנהלת ריבוי AGENTS.md צריכה גם למנוע סתירות בין הקובץ המרכזי לקבצים המשניים — למשל כלל גורף בשורש שאומר "כל endpoint חדש חייב טסט אינטגרציה" מול קובץ משנה בתיקיית legacy שמתעד חריגה מודעת מהכלל הזה. כשסוכן נתקל בסתירה כזו בלי כלל הכרעה ברור, הוא עלול לבחור אקראית איזה מקור לציית לו, ולכן כדאי להוסיף היררכיית עדיפויות מפורשת: קובץ ספציפי יותר גובר על קובץ כללי יותר, אלא אם נאמר אחרת.
תגיות: AGENTS.md · coding agent context · prompt engineering · repository conventions · sub-agents · AI coding