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

מהו AGENTS.md

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

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

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

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

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

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

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

מה נכלל בקובץ AGENTS.md

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

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

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

מה לעולם לא שייך לקובץ כזה

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

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

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

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

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

@AGENTS.md

## Claude Code

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

קישור סמלי מתאים כאשר אין לכם מה להוסיף:

ln -s AGENTS.md CLAUDE.md

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

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

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

כלים שכותבים את הקבצים האלה עבורכם

שני פרויקטים שהופיעו ברשימת הפרויקטים המובילים ב-GitHub ב-30 July 2026 מראים לאן המוסכמה מתפתחת.

agent0ai/dox (1,368 כוכבים נכון ל-July 2026) הוא framework לשמירה על עדכניות של עץ קובצי AGENTS.md. הוא אינו מפיץ package ואינו כולל 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 כוכבים נכון ל-July 2026) מיישם את התבנית על אדם במקום על מאגר. הפרויקט מציג את HUMAN.md שלך כתוצר של המערכת, ולא כקובץ שאתה מקליד: "מודל חי של מה שחשוב עכשיו, של האופן שבו אתה נוטה לקבל החלטות ושל הכיוון שאליו תשומת הלב שלך נעה". הוא פועל באופן מקומי ב-macOS 13 ואילך, מתעד פעילות לאחר שתעניק ל-macOS את ההרשאה הנדרשת, וחושף את התוצאה לסוכנים באמצעות MCP (פרוטוקול הקשר של מודל). נתיב ההתקנה המקוצר:

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

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

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

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

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

# 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.

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

FAQ

האם AGENTS.md הוא אותו קובץ כמו CLAUDE.md?

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

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

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

האם כדאי לבצע commit של AGENTS.md ל-git?

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

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

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