מדריך AGENTS.md ו-HUMAN.md: איך להדריך סוכני תכנות

מהו AGENTS.md

AGENTS.md הוא קובץ Markdown פשוט הממוקם בשורש המאגר (repository), ומנחה סוכני תכנות כיצד לעבוד על הפרויקט. האתר הרשמי מתאר אותו כ-"README עבור סוכנים: מקום ייעודי וצפוי לספק הקשר והנחיות שיעזרו לסוכני תכנות מבוססי בינה מלאכותית לעבוד על הפרויקט שלכם". הפורמט מנוהל על ידי ה-Agentic AI Foundation תחת ה-Linux Foundation, ויותר מעשרים סוכנים קוראים אותו, ביניהם Codex, Cursor, Jules, Devin ו-GitHub Copilot (נכון ליולי 2026).

הסיבה לקיום המוסכמה הזו היא פרקטית. אדם חדש בצוות שלכם קורא את ה-README, מנחש את פקודת ה-build, ושואל מישהו כאשר הניחוש שגוי. סוכן אינו יכול לשאול. הוא מנחש, מריץ את npm test על פרויקט שמשתמש ב-pnpm test, קורא את השגיאה, ומנסה משהו אחר. אתם משלמים על כל אחד מה-tokens האלו. כתיבת הפקודה הנכונה פעם אחת מסירה את כל סוג הכשל הזה.

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

היכן ממוקם הקובץ ואיזה קובץ גובר

מקמו את הקובץ הראשון בשורש המאגר (repository root). בתוך monorepo ניתן להוסיף קבצים נוספים בתוך כל תת-פרויקט, והכלל פשוט: "סוכנים קוראים באופן אוטומטי את הקובץ הקרוב ביותר בעץ הספריות, לכן הקרוב ביותר הוא הקובץ הקובע". התנגשות בין שני קבצים נפתרת לטובת הקובץ שנמצא בעריכה, וכל מה שתקלידו בצ'אט גובר על שניהם.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

כדאי להשתמש בקינון (nesting), כיוון שזו הדרך היחידה להגדיר כלל שנכון בתיקייה אחת ושגוי בתיקייה הבאה. כלל כמו "כל endpoint מאמת את הקלט שלו" שייך לצד ה-endpoints. בקובץ שורש, הוא נטען עבור כל משימה לא קשורה ואינו מועיל. אם קובץ השורש שלכם כבר גדל וכולל סעיף עבור כל שירות, פיצולו למבנה מקונן הוא הפתרון, והוא מגדיר אילו כללים עוברים למטה ואילו נשארים בראש.

מה צריך לכלול בקובץ AGENTS.md

רשמו את כל מה שסוכן לא יכול להסיק מקריאת הקוד. פקודות ה-build, ה-test וה-lint המדויקות צריכות להופיע ראשונות, בפורמט שניתן להדביק ישירות בטרמינל. הוסיפו את הפקודה להרצת בדיקה בודדת, שכן סוכן שיודע להריץ רק את כל חבילת הבדיקות יריץ אותה ארבעים פעמים. ציינו מוסכמות שחורגות מברירת המחדל של הכלי, כיוון שהסוכן כבר מכיר את ברירת המחדל וזקוק למידע רק על החריגות שלכם. הוסיפו את מבנה הודעות ה-commit ואת הכללים ל-pull request אם קיימים כאלה.

היו קונקרטיים מספיק כדי שניתן יהיה לאמת טענה. "השתמש בהזחה של 2 רווחים" היא הנחיה שימושית כי ניתן לבדוק אם היא בוצעה או לא. "עצב את הקוד כראוי" אינה הנחיה כזו, כיוון שאין בה דבר שניתן לאימות. כך גם לגבי מיקומים: "מטפלי API נמצאים ב-src/api/handlers/" עדיף על "שמור על קבצים מאורגנים".

גם לכללים שליליים יש מקום. "לעולם אל תערוך קבצים תחת dist/, הם נוצרים על ידי npm run build" מונע טעות ספציפית, ומכיוון שהוא מציין את הסיבה, הסוכן יכול להסיק בעצמו מקרים דומים שלא רשמתם. כלל לגבי היקף השינויים (scope) שייך לכאן גם הוא, כיוון שסוכן שיושאר לשיקול דעתו יבצע שינויים נרחבים יותר ממה שביקשתם: מיומנות אחת שמועתקת לעיתים קרובות אינה עושה דבר מלבד להתעקש על השינוי הקטן ביותר שעובד.

מה לעולם לא להכניס לקובץ כזה

לעולם אל תכניסו סודות לאחד מהקבצים הללו. הקובץ עובר commit ל-git, נטען להקשר (context) בתחילת כל סשן, ונשלח לספק המודל בכל בקשה. מפתח API בתוך AGENTS.md הוא מפתח API שנמצא בהיסטוריית ה-repository שלכם ובלוגים של צד שלישי. הצביעו על המיקום של הסוד במקום להדביק אותו: "סיסמת מסד הנתונים נמצאת ב-.env, שמוגדר ב-gitignore; בקשו אישור לפני קריאתו." המשמעת הרחבה יותר בנושא זה מפורטת ב-שמירה על פרטי הזדהות מחוץ להישג ידו של סוכן.

השמיטו כל דבר שהסוכן יכול להסיק בעצמו על ידי התבוננות. רשימת קבצים בתיקייה שהודבקה, עותק של רשימת התלויות שלכם, או סקירה ארכיטקטונית שרק חוזרת על שמות התיקיות: כל אלו הופכים ללא רלוונטיים כבר בשבוע שאחרי כתיבתם, ובינתיים הם גוזלים מקום ב-context בכל סשן. שמרו את המלכודות ואת הסיבות. וותרו על המלאי. כדאי להפריד את הסיבות, כיוון שסוכן שלא מבין מדוע קיים מבנה לא שגרתי יבצע לו refactor שקט ויעלים אותו; זו הסיבה לשמירה על קובץ DESIGN.md לצד קובץ זה.

CLAUDE.md הוא מופע ה-Claude Code של אותו רעיון

Claude Code קורא את CLAUDE.md ואינו קורא את AGENTS.md באופן עצמאי. קובץ פרויקט נמצא ב-./CLAUDE.md או ב-./.claude/CLAUDE.md, העדפות אישיות לכל פרויקט נשמרות ב-~/.claude/CLAUDE.md, וארגון יכול לדחוף קובץ ברמת המכונה ל-/etc/claude-code/CLAUDE.md ב-Linux. קבצים שמתגלים משורשרים משורש מערכת הקבצים ועד לספריית העבודה שלכם, כך שהקובץ הקרוב ביותר למקום שבו הפעלתם את הסשן נקרא אחרון. כל סשן שאתם מתחילים באותה ספרייה טוען את אותו מחסנית (stack), וזה מה שמאפשר להריץ שניים מהם זה לצד זה על מכונה אחת, ו-סשנים אלו יכולים להעביר עבודה זה לזה בזמן שהם רצים.

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

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

קישור סימבולי (symlink) עובד כאשר אין לכם מה להוסיף:

ln -s AGENTS.md CLAUDE.md

הפקודה אינה מדפיסה דבר במקרה של הצלחה. בסשן הבא שלכם הריצו את /context וודאו ש-CLAUDE.md מופיע תחת Memory files. אם הוא חסר מהרשימה הזו, הקובץ מעולם לא נטען, ולכן שום דבר בו לא הוחל. כדי ליצור טיוטה ראשונה במקום לכתוב אחת, הריצו את /init: הוא קורא את בסיס הקוד ומייצר קובץ התחלתי, וכאשר כבר קיים CLAUDE.md הוא מציע שיפורים במקום לדרוס אותו.

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

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

כלים המייצרים קבצים אלו עבורך

שני פרויקטים ברשימת ה-trending של GitHub נכון ל-30 ביולי 2026 מדגימים לאן נושבת הרוח בתחום זה.

agent0ai/dox (עם 1,368 כוכבים נכון ליולי 2026) הוא תשתית לשמירה על עץ של קובצי AGENTS.md מעודכנים. הפרויקט אינו מפיץ חבילה או סביבת הרצה (runtime). עליך להעתיק את תוכן ה-AGENTS.md שלו לתוך קובץ ה-AGENTS.md הראשי שלך, וזו כל ההתקנה. עבור פרויקט קיים, עליך להנחות את ה-agent שלך:

Initialize DOX tree for this project now.

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

HUMAN.md, אותו טריק מופנה אליך

Intuition-Lab/personal-model (1,260 כוכבים נכון ליולי 2026) מיישם את התבנית על אדם במקום על מאגר קוד. הפרויקט מציג את ה-HUMAN.md שלך כפלט של המערכת ולא כקובץ שאתה כותב: "מודל חי של מה שחשוב כרגע, איך אתה נוטה להחליט, ולאן תשומת הלב שלך נעה". הוא רץ מקומית על macOS 13 ומעלה, לוכד פעילות לאחר מתן הרשאות ב-macOS, וחושף את התוצאה לסוכנים באמצעות MCP (פרוטוקול הקשר למודל). נתיב ההתקנה הקצר:

uv tool install personal-model
persome onboard
persome model open --after 30

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

אזהרה אחת. קובץ HUMAN.md הוא פרופיל של אדם, ולכן הוא רגיש מעצם הגדרתו. הרחק אותו ממאגרים ציבוריים. שמור אותו ב-~/.claude/CLAUDE.md, או בתוך CLAUDE.local.md שמוגדר ב-gitignore בשורש הפרויקט; הוא ייטען לצד הקובץ המגובה ב-git ויטופל באותו אופן.

תבנית התחלה שניתן להעתיק

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

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

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

FAQ

האם הקובץ AGENTS.md זהה לקובץ CLAUDE.md?

אלו שני שמות קבצים לאותו רעיון. Claude Code קורא את CLAUDE.md ומתעלם מ-AGENTS.md אלא אם כן קישרת ביניהם. שמרו על קובץ אחד כמקור האמת וקשרו אליו את הקובץ השני, באמצעות שורה המכילה @AGENTS.md בראש הקובץ CLAUDE.md או באמצעות ln -s AGENTS.md CLAUDE.md. שני עותקים מלאים שמתוחזקים בנפרד יציגו מידע סותר תוך חודש.

האם כתיבת AGENTS.md מבטיחה שהסוכן יפעל לפיו?

לא. התוכן מועבר כהקשר (context), לכן המודל קורא אותו ובדרך כלל מציית לו, אך שום דבר לא חוסם פעולה שסותרת אותו. הנחיות מעורפלות הן אלו שזוכות לרמת הציות הנמוכה ביותר, ושני קבצים שנותנים הנחיות מנוגדות יגרמו לסוכן לבחור אחת מהן באופן שרירותי. עבור כלל שחייב להתקיים בכל פעם, השתמשו ב-hook או בכלל הרשאות, שנאכפים על ידי ה-client ללא קשר להחלטת המודל.

האם יש להוסיף את AGENTS.md ל-git?

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

מהו HUMAN.md והאם אני זקוק לו?

HUMAN.md הוא פרופיל קריא למכונה של אדם ולא של פרויקט. הוא מכיל את התפקיד שלכם, את המגבלות שלכם, ואת ההחלטות שכבר קיבלתם כדי שלא יעלו מחדש בכל session. אינכם זקוקים לכלי עבודה כדי להתחיל: עשרים שורות שנכתבו ידנית בקובץ ההנחיות ברמת המשתמש יספקו לכם את רוב הערך. התייחסו אליו כאל מידע אישי ושמרו אותו מחוץ לכל מאגר (repository) שאתם מבצעים לו push.