AGENTS.md: שבעה חוקים שהופכים את הסוכן לבכיר

מה זה קובץ AGENTS.md?

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

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

הפורמט נולד משיתוף פעולה בין קודקס של OpenAI, Amp, Jules של גוגל, Cursor ו-Factory, והיום הוא מנוהל על ידי Agentic AI Foundation תחת קרן לינוקס. היתרון הגדול: קובץ אחד עובד בהרבה כלים, אז אם תעברו מקודקס ל-Cursor או לקלוד קוד, החוקים באים איתכם.

מה כתוב בקובץ AGENTS.md של מתכנת בכיר?

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

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

העתקה# AGENTS.md

## How to work in this project
Act like a senior engineer who has to maintain this code for years.

1. Simplest fix that works.
   Solve the problem in front of you with the smallest change that fully works.
   No new layers, abstractions or "future-proofing" unless I ask for them.

2. Use what is already here.
   Use the libraries, components and patterns this project already uses.
   Do not install a new package or add a new service without asking me first,
   and tell me why the existing ones are not enough.

3. Check before you guess.
   Before using a library, API or command, read its docs or the existing code
   that already uses it. If you cannot verify something, say so instead of guessing.

4. Touch only what the task needs.
   Do not rename, reformat or "clean up" files that are not part of the task.
   Keep the change easy to review.

5. Prove it works.
   Run the project's checks (tests, build, lint) or open the page before you
   say "done". If something fails, show me the real error, not a summary.

6. Ask when it matters.
   If the task is unclear or there are two reasonable ways to do it,
   ask one short question first. For small details, pick the obvious option
   and tell me what you assumed.

7. Explain in plain language.
   When you finish, write 2-3 sentences: what changed, where, and anything
   I need to do. No silent workarounds: if you skipped or faked something, say it.

מה כל חוק עושה

1. הפתרון הכי פשוט שעובד: מונע את המגדלים. הסוכן פותר את מה שביקשתם, לא את מה שאולי תבקשו בעוד שנה.
2. מה שכבר יש: בלי חבילות חדשות בלי לשאול. כל חבילה חדשה היא עוד דבר שיכול להישבר.
3. לבדוק לפני שמנחשים: הסוכן קורא את התיעוד או את הקוד הקיים, במקום להמציא פקודה שנראית נכונה.
4. לגעת רק במה שצריך: שינוי קטן אפשר לבדוק. שינוי בעשרים קבצים אף אחד לא קורא.
5. להוכיח שזה עובד: "סיימתי" מגיע רק אחרי שהבדיקות רצו או שהעמוד נפתח.
6. לשאול כשזה חשוב: שאלה אחת קצרה בהתחלה חוסכת שעה של תיקונים בסוף.
7. להסביר בשפה פשוטה: שתיים או שלוש שורות על מה השתנה, בלי לטאטא דברים מתחת לשטיח.

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

איך מוסיפים AGENTS.md לפרויקט?

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

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

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

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

האם קלוד קוד קורא AGENTS.md?

כן, אבל עם תנאי. לפי התיעוד של קלוד קוד, מגרסה v2.1.277 הוא קורא AGENTS.md לבד, אבל רק כשאין בפרויקט קובץ CLAUDE.md. כשזה קורה תראו בתחילת השיחה שורה כמו no CLAUDE.md found; AGENTS.md loaded.

אם כבר יש לכם CLAUDE.md, או שאתם בגרסה ישנה, הדרך הבטוחה היא לייבא את הקובץ. שמים בראש ה-CLAUDE.md את השורה הזאת, ומתחתיה הוראות שרלוונטיות רק לקלוד:

העתקה@AGENTS.md

## Claude only
Use plan mode for big changes.

ככה יש לכם קובץ חוקים אחד לכל הכלים, וקלוד קורא אותו פעם אחת בלבד, גם אם הוא מגיע בשתי דרכים. דרך נוספת: בתוך קלוד קוד כותבים /config ומשנים את Project instructions ל-claude-md-and-agents-md, כדי שיקרא את שני הקבצים יחד.

על הצד השני של המטבע, כמה קצר הקובץ צריך להיות ומה מחקר מצא על קבצים ארוכים מדי, כתבתי במדריך ל-CLAUDE.md קצר. ועל כל מערכת הזיכרון של קלוד קוד יש את המדריך ל-CLAUDE.md וזיכרון.

מה חשוב לדעת על AGENTS.md?

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