איך לכתוב קובץ AGENTS.md כדי שכל סוכן קוד מבוסס בינה מלאכותית יבין את הפרויקט שלכם

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

מה זה AGENTS.md בעצם

AGENTS.md הוא "README לסוכנים": קובץ Markdown רגיל שאתם מניחים בשורש המאגר שלכם כדי לספר לכלי הקוד מבוססי הבינה המלאכותית איך הפרויקט שלכם עובד (agents.md). זו אינה שפת קונפיגורציה חדשה — אין שדות חובה ואין תחביר מיוחד. השתמשו בכל כותרות ה-Markdown שתרצו.

הפורמט חשוב משום שהוא חוצה-כלים באמת. נכון לאמצע 2026 הוא נקרא באופן טבעי על ידי OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Devin, Aider, Zed, VS Code, JetBrains Junie ועוד עשרות — 28+ כלים ו-60,000+ מאגרי קוד פתוח (agents.md; Codersera). כיום הוא מנוהל על ידי Agentic AI Foundation של ה-Linux Foundation, לצד Model Context Protocol של Anthropic. גם Claude Code קורא את AGENTS.md, אם כי הפורמט הטבעי והעשיר יותר שלו נותר CLAUDE.md (DeployHQ).

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

למה קובץ עדיף על חזרה על עצמכם בצ'אט

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

מה לשים בו

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

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

היו קונקרטיים. "כתבו קוד נקי" לא אומר לסוכן כלום. "השתמשו ב-pnpm, לא ב-npm; הריצו pnpm test לפני הסיום; לעולם אל תערכו קבצים ב-src/generated/" — זה בר-אכיפה.

דוגמה קונקרטית

הנה AGENTS.md תמציתי עבור אפליקציית ווב טיפוסית:

# AGENTS.md

## Project
Next.js 15 + TypeScript storefront. Package manager is pnpm.

## Setup & commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`

## Testing
- Run all tests: `pnpm test`
- All tests must pass before a task is considered done.

## Code style
- TypeScript strict mode; no `any`.
- Format with Prettier (`pnpm format`) — do not hand-format.
- Prefer named exports. Reuse helpers in `src/lib/` before writing new ones.

## Do not touch
- `src/generated/**` is auto-generated. Never edit by hand.
- Never commit `.env` files.

מסרו את זה ל-Claude Code, ל-Cursor או ל-Copilot וכל אחד מהם יאמץ את אותם הכללים.

מונו-ריפו: השתמשו בקבצים מקוננים

במונו-ריפו אתם יכולים להניח AGENTS.md בכל חבילה בנוסף לאחד בשורש. כאשר סוכן עובד בתוך תת-ספרייה, הקובץ הקרוב ביותר מנצח (agents.md). שמרו את המוסכמות המשותפות בשורש ואת הפקודות הספציפיות לחבילה בקבצים המקוננים, כך שסוכן שעורך את packages/api/ יקבל את פקודות הבנייה והבדיקה של אותה חבילה אוטומטית.

AGENTS.md מול CLAUDE.md מול חוקי Cursor

ייתכן שכבר יש לכם קבצים ספציפיים לכלי כמו CLAUDE.md או .cursor/rules. אתם לא חייבים לזרוק אותם. בפועל, צוותים שמים את המוסכמות המשותפות והבלתי-תלויות-בכלי ב-AGENTS.md — הדברים שכל סוכן צריך — ושומרים תוספות ספציפיות לכלי בקובץ הטבעי של הכלי שתומך בתכונות עשירות יותר (DeployHQ). Claude Code, למשל, קורא את שניהם, כאשר CLAUDE.md הוא הפורמט הבעתי יותר שלו. דפוס נפוץ הוא לשמור AGENTS.md קנוני אחד, ובמקום שכלי זקוק לקובץ משלו, להפנות את הקובץ הזה אל AGENTS.md כך שיש מקור אמת יחיד. התחילו עם AGENTS.md; פנו לקובץ הספציפי לכלי רק כשאתם זקוקים לתכונה שרק הוא תומך בה.

שמרו על קיצור וספציפיות

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

איך לשמור עליו שימושי

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