איך לכתוב קובץ AGENTS.md לסוכני קוד

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

המדריך מסביר מה לכלול, נותן תבנית, מראה איך Claude Code ו־Gemini CLI מוצאים את הקובץ ומציע בדיקה מהירה. אותם שלבים חלים גם כשאתם מפעילים סוכנים מהטלפון עם Mono מבית Reunified.

1. החליטו מה שייך לקובץ

האתר agents.md מתאר אותו כ־README לסוכנים. כללו בו את העובדות שכל סשן צריך, ודלגו על כל מה שהסוכן יכול ללמוד מהקוד.

ב־monorepo אפשר להוסיף AGENTS.md בתוך כל חבילה. הקובץ הקרוב ביותר גובר, והוראה ישירה שלכם בצ׳אט גוברת עליו.

2. התחילו מתבנית קצרה

הנה דוגמה בדויה עבור ״tidy-recipes״, אפליקציית ווב ב־TypeScript שמשתמשת ב־pnpm:

# AGENTS.md

## Overview
TypeScript web app for saving recipes. Components live in src/components.

## Setup
- `pnpm install`

## Test and lint
- `pnpm test` and `pnpm lint`

## Code style
- TypeScript only. One component per file.

## Boundaries
- Never edit db/migrations/.
- Ask before adding a dependency.

## Before you finish
- Run `pnpm test` and `pnpm lint`.
- List the files you changed and the test results.

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

3. כתבו כללים שסוכן יכול לבדוק

כלל טוב מאפשר לכם לבדוק אחר כך אם הסוכן פעל לפיו.

כתבו גבולות ככללי ״לעולם לא״ ו״שאל קודם״, כלל אחד בכל שורה.

4. גרמו ל־Claude Code ול־Gemini CLI לקרוא אותו

האתר agents.md מונה את Codex, את Gemini CLI, את opencode וסוכנים נוספים שתומכים בפורמט, אבל חלקם צריכים קודם הגדרה.

כברירת מחדל, גרסאות עדכניות של Claude Code קוראות את AGENTS.md רק כשאין CLAUDE.md,‏ ‎.claude/CLAUDE.md או CLAUDE.local.md בתיקיית העבודה או באחת התיקיות שמעליה (ראו את התיעוד שלו על זיכרון). אם יש לכם אחד מהקבצים האלה או גרסה ישנה יותר, ייבאו את AGENTS.md מתוך CLAUDE.md. בפרויקט tidy-recipes יש CLAUDE.md ישן, אז הוסיפו את השורה הזו בראש הקובץ והשאירו מתחתיה הערות שמיועדות רק ל־Claude:

@AGENTS.md

Prefer small commits.

פתחו סשן חדש, הריצו ‎/context וודאו ש־CLAUDE.md מופיע תחת קובצי הזיכרון (Memory files). אם אין CLAUDE.md, הפקודה ‎/memory מציגה במקום זה את הנתיב של AGENTS.md.

Gemini CLI קורא כברירת מחדל את GEMINI.md. כדי להוסיף את AGENTS.md, הוסיפו את ההגדרה הזו לקובץ ‎.gemini/settings.json של הפרויקט (ראו את התיעוד שלו על GEMINI.md):

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

פתחו סשן חדש, ואז הריצו ‎/memory show כדי לראות מה נטען. בסוכנים אחרים, בדקו את התיעוד שלהם.

5. בדקו את הקובץ עם משימה קטנה

בסשן חדש, תנו לסוכן את המשימה הזו:

קודם פרט את כללי הפרויקט שטענת ואת הקובץ שממנו הגיע כל כלל. אחר כך שנה את טקסט הכפתור ״Save recipe״ ל״Save״ בקובץ src/components/SaveButton.tsx. אל תשנה שום דבר אחר.

השוו את התוצאה לקובץ:

• הוא ציין את AGENTS.md (או את CLAUDE.md עם הייבוא).
• הוא הריץ pnpm test ו־pnpm lint ודיווח על התוצאות.
• הוא לא נגע ב־db/migrations/‎ ולא הוסיף תלות.
• הוא פירט את הקבצים ששינה.

אמתו את העריכה בעצמכם עם git diff (ראו בדיקת שינויי קוד שנוצרו ב־AI). אם הסוכן לא מצליח לציין כלל, כנראה שהקובץ לא נטען, אז חזרו לשלב 4. אם הוא ציין כלל ודילג עליו, נסחו את הכלל בצורה מוחשית יותר.

6. הקפידו שהקובץ יישאר קצר ועדכני

התיעוד של Claude Code ממליץ להשאיר את CLAUDE.md מתחת ל־200 שורות, כי קבצים ארוכים יותר תופסים יותר הקשר והסוכן מקפיד עליהם פחות. שאפו לאותו אורך גם ב־AGENTS.md. המדריך לחלון ההקשר מסביר מה קורה כשההקשר מתמלא.

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

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

ב־Mono, הסוכן מתחיל לעבוד בתיקיית העבודה של הפרויקט במחשב שלכם, ושם הוא מחפש את הקבצים האלה. אתם יכולים לפתוח את AGENTS.md, את CLAUDE.md או את ‎.gemini/settings.json בעורך של Mono, גם מהטלפון, והעריכות נשמרות אוטומטית. כדי ליצור את הקובץ, בקשו מהסוכן או פתחו טרמינל מכרטיס הפרויקט. Mono לא בודק את הקובץ ולא משנה איזה קובץ הסוכן טוען. Mono עדיין לא זמין, אבל אפשר להצטרף לרשימת ההמתנה.