איך לכתוב AGENTS.md שבאמת עוזר לסוכן הקידוד שלכם

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

מה AGENTS.md הוא

AGENTS.md הוא פורמט Markdown פשוט ופתוח שנותן לסוכני קידוד מקום צפוי למצוא בו הקשר והוראות של הפרויקט. הוא התחיל כשיתוף פעולה בין OpenAI Codex, Amp, Google Jules, Cursor, ו-Factory, וכעת מנוהל על ידי Agentic AI Foundation תחת ה-Linux Foundation. מעל 25 כלים קוראים אותו — כולל Codex, Cursor, VS Code, GitHub Copilot, Aider, Windsurf, JetBrains Junie, Zed, ו-goose — והוא מופיע ביותר מ-60,000 מאגרי קוד פתוח.

חשבו על זה כ-README שנכתב עבור הסוכן במקום עבור אדם: ה-README מסביר את הפרויקט שלכם לתורם חדש; AGENTS.md אומר לסוכן את הדברים שאחרת הוא היה מנחש שגוי. (משתמשי Claude Code יזהו את CLAUDE.md כמקבילה; צוותים רבים שומרים את שניהם, או יוצרים symlink מאחד לאחר.)

איפה הוא הולך

שימו את AGENTS.md בשורש המאגר. ב-monorepo, הוסיפו קבצים מקוננים בתוך כל חבילה — סוכנים קוראים את הקובץ הקרוב ביותר בעץ הספריות, כך ש-packages/api/AGENTS.md גובר על זה שבשורש כשהסוכן עובד בתיקייה ההיא. זה מאפשר לשירות Python ול-frontend של TypeScript כל אחד לקבל הוראות מותאמות.

מה לשים בו

הפורמט הוא פשוט Markdown — השתמשו בכל כותרות שאתם רוצים. סקשנים שימושיים נפוצים כוללים:

• פקודות build ובדיקה — הפקודות המדויקות, לא קירובים
• סגנון קוד — formatter, linter, וכל מוסכמה ש-linter לא יתפוס
• הוראות בדיקה — איך להריץ בדיקה יחידה, מה חייב לעבור לפני ששינוי גמור
• שיקולי אבטחה — קבצים או פעולות שלעולם אין לגעת בהם
• מוסכמות commit / PR — פורמט הודעה, מתן שמות לבְּרַנְצ'ים
• שלבי פריסה — רק אם הסוכן צפוי לגעת בהם

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

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (do NOT run in CI)
- Test a single file: `pnpm vitest run path/to/file.test.ts`
- Lint + typecheck before any commit: `pnpm check`

## Conventions
- Use the existing `db()` helper in `src/lib/db.ts`; never open a raw client.
- Dates are stored as UTC ISO strings. Never use `Date.now()` in tests.

## Do not touch
- `src/generated/**` is codegen output. Edit the schema, then run `pnpm gen`.

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

קצר יותר בדרך כלל טוב יותר

יש פיתוי לבקש מהסוכן לייצר AGENTS.md ענקי עבורכם. התנגדו לו. מחקר של ETH Zurich מ-2026, שדווח על ידי InfoQ, מדד את ההשפעה האמיתית של הקבצים האלה ומצא שההשפעה שולית ומעורבת. קבצי הקשר שנוצרו על ידי LLM למעשה הורידו את שיעורי הצלחת המשימות בכ-3% בממוצע בעוד העלו את עלויות ההסקה ביותר מ-20%. קבצים שנכתבו על ידי אדם עזרו במידה צנועה — בערך 4% רווח בהצלחה — אבל עדיין דחפו סוכנים לקחת יותר צעדים, והעלו עלות בעד ~19%.

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

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

workflow שעובד

1. התחילו ריק. אל תכתבו AGENTS.md עד שצפיתם בסוכן עושה משהו שגוי.
2. הוסיפו את התיקון, לא את התיאוריה. כשהוא מריץ את פקודת הבדיקה הלא נכונה, הוסיפו את הנכונה. כשהוא מפרמט מחדש קובץ בדרך שלכם וה-linter מתלונן, הוסיפו את הכלל.
3. שמרו על זה הדוק. אם שורה רק חוזרת על מה שהסוכן יכול לקרוא מ-package.json או משמות התיקיות, מחקו אותה.
4. השתמשו בקינון ל-monorepos כך שהקובץ של כל חבילה יישאר קטן.
5. קראו אותו מחדש כל חודש. הוראות מיושנות גרועות מאין — סוכן שעוקב אחר פקודת build לא-עדכנית נכשל בביטחון.

קבצי AGENTS.md הטובים ביותר נקראים כדף-רמאות onboarding תמציתי עבור חבר הצוות האחד שלעולם לא שוכח אבל גם לעולם לא מסיק. כתבו את הדברים שהם לא יכולים לנחש, ושום דבר אחר.