SSD Nodes Learn Hosting plans →
מדריכים Matt Connorמאת Matt Connor · עודכן 2026-10-30

ניהול קובצי AGENTS.md מקוננים ב-monorepo

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

מה המשמעות של קובצי AGENTS.md מקוננים בתוך monorepo

קובצי AGENTS.md מקוננים בתוך monorepo משמעותם קובץ קטן אחד בשורש המאגר ועוד קובץ אחד בתוך כל תיקיית שירות. הקובץ בשורש מכיל את הכללים המעטים שתקפים בכל מקום, בתוספת מיפוי של מיקומי הקבצים האחרים. כל קובץ שירות מכיל את הפקודות והמוסכמות עבור אותה תיקייה בלבד. סוכן (agent) שעורך את services/worker/queue.py קורא את קובץ השורש ואת קובץ העבודה, ואינו מבזבז כלל הקשר (context) על ה-front end שבו הוא לעולם לא יגע.

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

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

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

מדוע קובץ AGENTS.md שורשי אחד וגדול מפסיק לעבוד?

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

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

הוא גוזל הקשר (context) בכל משימה. קבצים אלו נטענים בתחילת הסשן, לפני שהסוכן יודע מה עומד לשאול. התיעוד של Claude Code מציב מספר יעד: "יש לשאוף לפחות מ-200 שורות לכל קובץ CLAUDE.md. קבצים ארוכים יותר צורכים יותר הקשר ומפחיתים את רמת הציות". Codex מפסיק למזג קובצי הוראות ברגע שהגודל המשולב שלהם מגיע ל-32 KiB, ערך ה-project_doc_max_bytes המוגדר כברירת מחדל. קובץ שורשי שמתעד ארבעה שירותים מבזבז את התקציב הזה על שלושה מהם בכל משימה בודדת.

הוראות מתחילות לסתור זו את זו. ספריית ה-web דורשת pnpm test. תהליך הרקע דורש pytest -q. כאשר הן כתובות בקובץ אחד, כל כלל נכון רק בחלק מהזמן, ולכן הסוכן צריך לנחש איזה מהם תקף. התיעוד של Claude Code מתאר את התוצאה: "אם שתי הוראות סותרות זו את זו, Claude עשוי לבחור באחת מהן באופן שרירותי". פיצול הקובץ לא מונע מהכלל השני להיכנס להקשר. Claude Code משרשר את כל קובצי ההוראות שנטענו במקום לתת לאחד להחליף את השני, כך שהקובץ השורשי תמיד שם, וברגע שהסוכן פתח קבצים גם ב-apps/web וגם ב-services/worker, שני קובצי הספריות נמצאים בהקשר יחד. מה שקובץ לכל ספרייה עושה הוא לקשור כל כלל לספרייה שהוא מנהל. ציינו את שם הספרייה בראש הקובץ, כפי שעושות הדוגמאות להלן עם # apps/web, וכל פקודה תציין היכן היא תקפה כאשר כמה קבצים טעונים בו-זמנית. כאשר כלל שאתם בטוחים שכתבתם בבירור נדלג עליו בכל זאת, עבודה מול הסיבות לכך שהוראה לעולם לא מיושמת עדיפה על שכתוב הניסוח בפעם הרביעית.

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

האם הסוכן קורא את קובץ ה-root, או רק את הקרוב ביותר?

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

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

ובנוגע להתנגשויות:

קובץ ה-AGENTS.md הקרוב ביותר לקובץ הנערך הוא הקובע; הנחיות מפורשות של המשתמש בצ'אט גוברות על הכל.

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

Codex מבהיר את המנגנון: "Codex משרשר קבצים מה-root ומטה, ומחבר ביניהם באמצעות שורות ריקות. קבצים הקרובים יותר לספרייה הנוכחית שלך גוברים על הנחיות קודמות". Claude Code פועל באותה דרך. בתחילת סשן הוא קורא "כל AGENTS.md ו-.claude/AGENTS.md בספריית העבודה שלך ובספריות שמעליה", והתיעוד שלו מציג את מודל הטעינה בבירור: "כל הקבצים שנמצאו משורשרים להקשר במקום להחליף זה את זה". ספריות מתחת לספריית העבודה מתנהגות אחרת: Claude Code טוען את ה-AGENTS.md של תת-ספרייה לפי דרישה, "כאשר Claude פותח שם קובץ באמצעות כלי ה-Read".

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

התנהגות זו נבדקה מול התיעוד של Codex ו-Claude Code ב-27 באוקטובר 2026. כלים מממשים את המוסכמה בצורה מעט שונה והם אכן משתנים, לכן יש לוודא את חוקי הטעינה עבור הסוכן שהצוות שלכם מריץ.

FAQ

מבנה עבודה עבור מאגר עם שלושה שירותים

repo/
  AGENTS.md                   rules true everywhere, plus the map
  apps/web/AGENTS.md          TypeScript client, Vite, Vitest
  services/worker/AGENTS.md   Python queue consumer, pytest
  infra/AGENTS.md             Terraform and the deploy scripts

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

# AGENTS.md

This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.

- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts

## Rules for the whole repository

- The package manager is `pnpm`. `npm install` writes a second lockfile
  that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
  `schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
  in the same commit.

הקובץ הייעודי לכל ספרייה הוא המקום שבו מפורטים הפרטים, והוא יכול להיות ארוך ככל שהספרייה דורשת.

# apps/web

Browser client. Vite and React, TypeScript with `strict` on.

## Commands

- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.

## Conventions

- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
  because the client attaches the auth header and retries on 429.

## Traps

- `pnpm build` does not type check. Vite strips the types instead of
  checking them, so a broken type still produces a green build.
  Run `pnpm typecheck` as a separate step.

קובץ ה-worker הוא בעל מבנה זהה אך תוכן שונה: פקודת ההתקנה, pytest -q, הסיבה לכך שהצרכן חייב להישאר אידמפוטנטי, והמיגרציה שחייבת לרוץ לפני שהבדיקות יעברו. קובץ ה-infra הוא המקום שבו כותבים את הכללים שמונעים מסוכן (agent) לגרום נזק. לעולם אל תריצו את terraform apply. הריצו את terraform plan ועצרו שם, וציינו את ה-state backend שכבר מוגדר כדי שהסוכן לא ינסה לאתחל אחד חדש.

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

מי מעדכן את הקובץ כאשר הקוד משתנה?

כלל אחד בלבד, והוא חל על קובץ ה-root: מי שמשנה קוד בתיקייה מסוימת מעדכן את הקובץ AGENTS.md של אותה תיקייה באותו commit.

הסיבה לכך היא מכנית, לא תרבותית. הקובץ המקומי לכל תיקייה מופיע באותו diff של הקוד, כך שהבודק (reviewer) של ה-pull request רואה את שניהם בו-זמנית. קובץ root שייך לכולם, מה שאומר שהוא לא שייך לאף אחד, והוא לעולם לא מופיע ב-diff שאותו מישהו כבר קורא.

גבו את הכלל בבדיקה אוטומטית ב-pull request. הבדיקה מאתרת את קובץ ה-AGENTS.md הקרוב ביותר מעל כל קובץ שהשתנה, ומדווחת כאשר הקובץ הזה לא עבר עריכה.

#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)

nearest_doc() {
  d=$(dirname "$1")
  while [ "$d" != "." ]; do
    if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
    d=$(dirname "$d")
  done
  echo "AGENTS.md"
}

printf '%s\n' "$changed" | while read -r f; do
  [ -n "$f" ] || continue
  case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
  doc=$(nearest_doc "$f")
  printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
  echo "note: $f changed but $doc was not updated"
done

ב-branch שביצע שינויים ב-API client מבלי לעדכן את התיעוד, הפלט ייראה כך:

note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updated

השאירו זאת כאזהרה ולא כחסימה (failure). חסימה קשיחה גורמת לאנשים להוסיף שורה ריקה לקובץ רק כדי שה-CI יציג אישור ירוק; קובץ שנערך כדי לספק רובוט שווה פחות מקובץ שלא קיים כלל. האזהרה מעניקה לבודק שאלה לשאול, וזה החלק שבאמת עובד.

כיצד ניתן לזהות קובץ AGENTS.md שהתיישן?

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

השוו את גיל הקובץ לגיל הקוד שהוא מתאר. %cs מדפיס את תאריך ה-commit כ-YYYY-MM-DD.

for f in $(git ls-files '*AGENTS.md'); do
  d=$(dirname "$f")
  printf '%s  doc:%s  code:%s\n' "$f" \
    "$(git log -1 --format=%cs -- "$f")" \
    "$(git log -1 --format=%cs -- "$d")"
done
apps/web/AGENTS.md          doc:2026-02-11  code:2026-08-07
services/worker/AGENTS.md   doc:2026-07-29  code:2026-08-09
infra/AGENTS.md             doc:2026-08-01  code:2026-08-01

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

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

grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
  [ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
done

קראו את הפלט במקום להטמיע בדיקה זו ב-CI. הפקודה מסמנת גם תבניות glob כמו src/**/*.ts וכל URL שצוטט, כיוון ששניהם מכילים לוכסן ואינם קבצים על הדיסק. בגרסה Claude Code v2.1.283 ומעלה, /doctor prompt-audit מריץ עבורכם בדיקה דומה: הוא מחפש "הפניות לקבצים או פקודות שאינם קיימים" וקבצים הסותרים זה את זה, מכסה את קובצי ה-AGENTS.md שלכם כברירת מחדל, ואינו משנה דבר עד שתבקשו ממנו להחיל את העריכות שהוא מציע.

התסמין במהלך סשן. הסוכן קורא את הקובץ, מנסה לפתוח את src/api/client.ts כי הקובץ הורה לו לעשות זאת, והכלי מחזיר:

No such file or directory

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

האם Claude Code קורא קובצי AGENTS.md?

כן, החל מגרסה v2.1.277 של Claude Code, והכלל המדויק חשוב כיוון שהמבנה המקונן תלוי בו. נכון לתיעוד מיום 27 באוקטובר 2026: "Claude Code יכול לקרוא את AGENTS.md כהוראות הפרויקט שלך, כך שמאגר שכבר הוגדר עבור סוכני קידוד אחרים יעבוד ללא צורך בהוספת CLAUDE.md, ייבוא או הגדרה." ערך ברירת המחדל של Project instructions, הלא הוא claude-md-or-agents-md, קורא את "קובצי ה-AGENTS.md שלך כאשר אין לך CLAUDE.md או CLAUDE.local.md בספריית העבודה שלך או מעליה." קבצים מקוננים כלולים גם הם: Claude קורא את ה-AGENTS.md של ספריית משנה "כאשר Claude פותח שם קובץ באמצעות כלי הקריאה (Read tool)", כל עוד "באותה ספריית משנה אין אף אחד משלושת קובצי ה-CLAUDE.md שלה". שלושת אלו הם CLAUDE.md, .claude/CLAUDE.md ו-CLAUDE.local.md, לכן CLAUDE.local.md אישי בתוך apps/web מספיק כדי לעצור את הטעינה של apps/web/AGENTS.md.

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

מספר גרסה לבדו אינו מאשר שהדבר עבד. עליך להשתמש בגרסה v2.1.277 ומעלה, אך לפני גרסה v2.1.281 סשנים מסוימים, כגון אלו ב-Amazon Bedrock או עם טלמטריה מושבתת, קוראים קובצי CLAUDE.md בלבד, ובמקרים מסוימים הסשן הראשון לאחר שדרוג מגרסה v2.1.276 ומטה מדלג גם על AGENTS.md: התיעוד מציין ש-"Claude קורא את AGENTS.md החל מהסשן הבא שלך". לכן, בדוק את הסשן עצמו. בסשן אינטראקטיבי, Claude Code מדפיס שורה כגון no CLAUDE.md found; AGENTS.md loaded: ואחריה הנתיב, ובגרסאות נוכחיות /memory מציג את הקובץ ברשימה. לפני גרסה v2.1.280, /memory ו-/context לא הציגו ברשימה AGENTS.md ש-Claude קרא ישירות, לכן בגרסאות אלו שאל את Claude מהן הוראות הפרויקט שלו.

צורת הייבוא עדיין נכונה במקומות שבהם Claude אינו יכול לקרוא את AGENTS.md ישירות: גרסה ישנה יותר, סשן לפני v2.1.281 ב-Amazon Bedrock או עם טלמטריה מושבתת, סשן שבו התוסף המובנה שקורא את הקובץ מושבת, או פרויקט ששומר על CLAUDE.md עם Project instructions המוגדר ל-claude-md. הכנס זאת ל-services/worker/CLAUDE.md:

@AGENTS.md

## Claude Code

Use plan mode for changes under `services/worker/migrations/`.

צורת ה-symlink נכונה כאשר אין שום דבר ספציפי לכלי להוסיף.

git ls-files '*AGENTS.md' | while read -r f; do
  ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.md

ln אינו מדפיס דבר כאשר הוא מצליח, לכן בדוק את הרשימה: apps/web/CLAUDE.md -> AGENTS.md. לאחר מכן התחל סשן והרצ את /context, שם הקבצים שנטענו יופיעו תחת Memory files. ב-Windows, קישור סימבולי (symlink) דורש הרשאות מנהל (Administrator) או מצב מפתח (Developer Mode), ו-Git מושך קישור סימבולי שבוצע לו commit כקובץ טקסט רגיל אלא אם כן core.symlinks מופעל, מה שמשאיר את ה-clone הזה עם CLAUDE.md של שורה אחת במקום ההוראות שלך. אם מישהו שמבצע clone למאגר עובד על Windows, השתמש בייבוא @AGENTS.md במקום זאת. אם הגדרת אחד מפתרונות העקיפה לפני ש-Claude Code קרא את AGENTS.md בעצמו, אתה יכול להשאיר אותו: התיעוד מציין שהשארת הייבוא "לעולם לא גורמת ל-Claude לקרוא את AGENTS.md פעמיים", ו-CLAUDE.md מקושר סימבולית נקרא פעם אחת.

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

הגדרות שמפנות סוכנים אחרים ל-AGENTS.md

Codex קורא את AGENTS.md באופן טבעי. בכל רמה הוא בודק תחילה את AGENTS.override.md, מה שנותן לספרייה אחת עקיפה מקומית ללא עריכת הקובץ המשותף. הוא מפסיק למזג ברגע שהגודל המשולב מגיע ל-32 KiB, ה-project_doc_max_bytes המוגדר כברירת מחדל, וזו סיבה נוספת לשמור על קובץ השורש קטן.

Aider לוקח אותו דרך .aider.conf.yml עם השורה read: AGENTS.md.

Gemini CLI לוקח אותו דרך .gemini/settings.json עם { "context": { "fileName": "AGENTS.md" } }.

התיעוד במעלה הזרם (Upstream) מתעד שם חלופי תואם לאחור עבור מאגרים שעדיין משתמשים בשם היחיד הישן יותר: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.

ב-monorepo גדול מאוד, הגדרת ה-claudeMdExcludes של Claude Code מדלגת על קובצי אב לפי נתיב או glob, מה ששימושי כאשר ספרייה של צוות אחר נמצאת מעל שלך. התבניות שלו חלות גם על קובצי ה-AGENTS.md ש-Claude Code קורא.

במה זה שונה מזיכרון של סוכן (agent memory) או ממיומנות (skill)?

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

הקובץ AGENTS.md נכתב על ידך, מבוצע לו commit ל-git, הוא עובר סקירה ב-pull request, והוא זהה עבור כל מי שמשכפל (clone) את המאגר. זיכרון של סוכן נכתב על ידי הסוכן, מאוחסן מחוץ למאגר, והוא מקומי למכונה אחת בלבד. התיעוד של Claude Code משרטט את אותו הגבול: הקובץ CLAUDE.md מכיל "הנחיות וכללים" שאתה כותב, זיכרון אוטומטי מכיל "למידות ותבניות" ש-Claude כותב, וספריית הזיכרון אינה משותפת בין מכונות. המבחן פשוט: אם עובדה חייבת להיות נכונה עבור עמית שביצע clone טרי, היא לא יכולה להיות בזיכרון. המאמר כיצד זיכרון סוכן נשמר בין סשנים מכסה את החלק הזה של התמונה.

מיומנות (skill) היא הדבר השלישי. AGENTS.md הוא הקשר (context) שנטען בכל סשן; מיומנות היא הליך שנטען כאשר יש בו צורך. התיעוד של Claude Code מציע כלל שימושי: "אם רשומה היא הליך רב-שלבי או שהיא רלוונטית רק לחלק אחד של בסיס הקוד, העבר אותה למיומנות או לכלל בעל טווח (scope) מוגדר לפי נתיב". החלק השני של המשפט הזה הוא בדיוק מה שקובץ AGENTS.md מקונן פותר. החלק הראשון הוא מה ש-מיומנויות סוכן נועדו עבורו, וכאשר יש צורך באותו הליך ביותר ממאגר אחד, שתף את המיומנות בין מאגרים במקום להדביק את אותן פסקאות בעשרה קובצי AGENTS.md שונים.

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

FAQ

האם קובץ AGENTS.md מקונן מחליף את קובץ השורש או מתווסף אליו?

הוא מתווסף אליו. לפי התיעוד של ה־upstream, "הקובץ הקרוב ביותר מקבל עדיפות", מה שמתאר מה קורה במקרה של התנגשות, לא מה נטען בפועל. Codex "משרשר קבצים מהשורש ומטה, ומפריד ביניהם בשורות ריקות", ו־Claude Code משרשר כל קובץ שהוא מוצא בזמן סריקה מעלה מתיקיית העבודה במקום לדרוס אותם. הקובץ הקרוב ביותר קובע רק כאשר שני קבצים נותנים הנחיות שונות על אותו נושא. כתבו חוקים משותפים בשורש פעם אחת, ואל תחזרו עליהם בכל תיקייה.

מה צריך להיות הגודל של קובץ ה-AGENTS.md בשורש?

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

איך מונעים מהקבצים האלו להתיישן?

הוסיפו חוק אחד בקובץ השורש: מי שמשנה קוד בתיקייה מעדכן את ה-AGENTS.md של אותה תיקייה באותו commit. הצבת הקובץ לצד הקוד היא מה שגורם לחוק להישמר, כיוון שהשינוי מופיע באותו pull request diff שאדם כבר קורא. הוסיפו אזהרת CI שממפה כל נתיב שהשתנה ל-AGENTS.md הקרוב ביותר שמעליו, ומדי פעם השוו את git log -1 --format=%cs של כל קובץ מול אותה פקודה שמורצת על התיקייה שהוא מתעד.

האם Claude Code קורא קובצי AGENTS.md?

כן, החל מגרסה v2.1.277. לפי התיעוד שנבדק ב-27 באוקטובר 2026, Claude Code קורא את AGENTS.md כברירת מחדל כאשר אין לכם CLAUDE.md או CLAUDE.local.md בתיקיית העבודה שלכם או מעליה, והוא קורא את ה-AGENTS.md של תיקיית משנה כאשר הוא פותח שם קובץ עם כלי ה-Read ולאותה תיקיית משנה אין CLAUDE.md, .claude/CLAUDE.md או CLAUDE.local.md משלה. אל תוסיפו CLAUDE.md לצד כל AGENTS.md: עם קובץ אחד בתיקיית העבודה או מעליה, Claude קורא "רק את קובצי ה-CLAUDE.md שלכם". אם אתם זקוקים גם ל-CLAUDE.md, הגדירו את Project instructions ל-claude-md-and-agents-md ב-/config, או הציבו @AGENTS.md בשורה הראשונה שלו. הריצו את /memory בסשן וודאו שנתיב ה-AGENTS.md מופיע ברשימה.

איפה שמים חוק שרלוונטי רק לעיתים?

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

האם המאמר הזה היה מועיל?