צוותים שעובדים עם Claude Code, Cursor ו-Codex במקביל מגלים מהר שקובץ הוראות אחד כבר לא מספיק. בשורש הריפו יושב AGENTS.md, ולידו CLAUDE.md שמישהו הוסיף לפני כמה חודשים. בתיקיית .claude/skills יש נהלים לפריסה ולמיגרציות, ולפעמים יש גם קובץ אישי שאף אחד אחר בצוות לא רואה. בשלב מסוים עולה שאלה פשוטה: כש-AGENTS.md ו-CLAUDE.md אומרים דבר אחד ו-Skill אומר דבר אחר, מה הסוכן עושה בפועל?
התשובה פחות מסודרת ממה שרוב המדריכים מציגים. במקורות הזמינים אין כלל מתועד בנוסח ״CLAUDE.md גובר על Skill״. ההכרעה נקבעת בעיקר על ידי ה-loader של כל כלי: אילו קבצים נטענים לקונטקסט, באיזה שלב בסשן, ומה שורד דחיסת קונטקסט (compaction). לפי ניתוח של Alex Dunlop, ההבדל המעשי בין הכלים הוא ה-loader ולא שם הקובץ. רק שלושה מתוך ארבעה-עשר כלים שנבדקו מפרסמים את סדר הטעינה שלהם.
הנושא דחוף עכשיו גם בגלל שינוי קונקרטי. לפי אותו מקור, Claude Code התחיל לקרוא AGENTS.md כ-fallback בגרסה v2.1.277 מ-18 בספטמבר 2026, אבל רק כשאין CLAUDE.md בתיקייה הנוכחית או מעליה. המדריך הזה מסביר לצוותי Next.js ו-TypeScript איך כל קובץ הוראות לסוכן קוד נטען, מאיפה מגיעות הסתירות, איך לבנות מבנה שמונע אותן, ואיך לבדוק בפועל איזו הוראה הגיעה לסוכן.
התשובה הקצרה: אין מנצח אחד, יש loader
הדרך הנכונה לחשוב על סדר עדיפויות בהוראות סוכן AI היא לא כטבלת ״מי גובר על מי״, אלא כשלוש שאלות נפרדות:
- האם הקובץ נטען בכלל? הוראה שלא הגיעה לקונטקסט לא יכולה לנצח. ב-Claude Code, אם קיים CLAUDE.md, מתעלמים מ-AGENTS.md אלא אם מייבאים אותו או משנים את הגדרת Project instructions ב-
/config. - מתי הוא נטען? CLAUDE.md בשורש נטען בתחילת הסשן, CLAUDE.md בתת-תיקייה נטען רק כשקוראים קבצים מתחתיו, וגוף של Skill נטען רק כשהוא מופעל, לפי Anthropic.
- האם הוא שורד לאורך הסשן? אחרי compaction חלק מהמנגנונים מוזרקים מחדש וחלק לא.
כששתי הוראות סותרות נמצאות בקונטקסט באותו זמן, המודל מכריע לפי ההקשר. המאמר של Anthropic שמתאר את שיטות ההכוונה של Claude Code לא קובע מנצח מפורש בין CLAUDE.md ל-Skill. המסקנה המעשית: לא לנסות לנחש מי ינצח, אלא להסיר את הסתירה ולבדוק אמפירית מה נטען.
למה ״AGENTS.md הוא תקן״ זה רק חצי נכון
לפי Dunlop, AGENTS.md הוא שם קובץ ולא תקן: אין סכמה, אין מספר גרסה ואין שפת MUST/SHOULD. מנגד, Build This Now טוען שמפרט ה-AAIF מגדיר שדות סכמה כמו allowed_tools ו-disallowed_tools, ו-Claude Code פשוט מתעלם מהם.
המקורות סותרים כאן זה את זה, אבל המסקנה המעשית זהה בשני המקרים. גם אם יש שדות מוגדרים, אין ערובה שכלי מסוים מכבד אותם. לכן כדאי לכתוב AGENTS.md כ-Markdown פשוט וקריא, ולא לסמוך על שדות מובנים כמנגנון אכיפה.
איך כל מנגנון נטען: AGENTS.md, CLAUDE.md, SKILL.md, rules ו-hooks
Anthropic מתארת שבע שיטות להכוונת Claude Code: CLAUDE.md, rules, skills, subagents, hooks, output styles והוספה ל-system prompt. כל אחת שונה בתזמון הטעינה, בהתנהגות בזמן compaction וב״סמכות״ שלה. כדי להבין סתירות צריך להבין קודם את ההבדלים האלה.
CLAUDE.md וההיררכיה שלו
CLAUDE.md בשורש הפרויקט נטען בתחילת הסשן ונשמר (memoized). CLAUDE.md בתת-תיקייה נטען לפי דרישה, כשהסוכן קורא קבצים תחת אותה תיקייה, לפי Anthropic.
מקור צד שלישי, Build This Now, מתאר היררכיה של שש שכבות:
~/.claude/CLAUDE.mdגלובלי ברמת המשתמש- CLAUDE.md בשורש הריפו
CLAUDE.local.mdאישי- CLAUDE.md בתת-תיקייה
- auto-memory
- קבצים שמיובאים עם
@(החלשים ביותר לפי המקור)
הכלל שהמקור מציע הוא ״הפנימי גובר על החיצוני״. חשוב לזכור שזו טענה של צד שלישי ולא תיעוד רשמי של Anthropic. כדאי להתייחס אליה כהנחת עבודה שצריך לאמת, לא כחוק.
לגבי auto-memory, לפי memU נטענים בכל סשן 200 השורות הראשונות או 25KB. זה עוד מקור הוראות שקל לשכוח שקיים. הוא יכול להכיל ״לקחים״ שהסוכן שמר לעצמו ושסותרים את מה שכתוב בריפו.
AGENTS.md
AGENTS.md הוא קובץ Markdown פשוט שנקרא על ידי יותר מ-20 כלים לפי BuildBetter, ויותר מ-30 לפי Build This Now, ביניהם Codex, Cursor ו-Gemini CLI. גם נתוני האימוץ שנויים במחלוקת: Build This Now מביא הערכות של יותר מ-20,000 ריפוזיטוריז בתחילת 2026 לעומת יותר מ-60,000 באמצע השנה.
לפי memU, קבצי הוראות כמו CLAUDE.md ו-AGENTS.md נטענים במלואם בכל סשן, ולכן כל שורה בהם עולה טוקנים בכל אינטראקציה. עם זאת, חשוב לסייג: אופן הטעינה המדויק בכל כלי, כלומר היכן הוא מחפש, באיזה סדר הוא ממזג קבצים ומה הוא עושה עם קבצים מקוננים, ברובו לא מתועד. לפי Dunlop, רק שלושה מתוך ארבעה-עשר כלים מפרסמים את הסדר שלהם, ולכן ״נטען במלואו״ הוא הנחת עבודה סבירה ולא התחייבות של כל כלי.
Skills (SKILL.md)
Agent Skills הוצגו על ידי Anthropic ב-16 באוקטובר 2025 ופורסמו כתקן פתוח בדצמבר 2025 באתר agentskills.io, ו-OpenAI Codex קורא את אותו פורמט SKILL.md. ההבדל המהותי הוא בטעינה. בתחילת הסשן נטענים רק השם והתיאור, בעלות של כ-100 טוקנים לכל Skill במצב סרק, והגוף נטען רק כשה-Skill מופעל.
לפי Anthropic, Skills שהופעלו מוזרקים מחדש אחרי compaction עד תקציב משותף. המשמעות לשאלת העדיפות: Skill אינו שכבה שפועלת תמיד ומתחרה ב-CLAUDE.md. הוא נכנס לתמונה רק כשהתיאור שלו תואם את המשימה, ואז הוא יושב בקונטקסט לצד ה-CLAUDE.md, לא במקומו.
Rules ו-hooks
Rules, לפי Anthropic, מוזרקים מחדש אחרי compaction, ולכן הם מתאימים להוראות שחייבות להישאר בתוקף גם בסשן ארוך. Hooks רצים על אירועי מחזור חיים ועוקפים את ה-compaction לגמרי. Anthropic ממצבת אותם לאוטומציה דטרמיניסטית כמו הרצת linters או חסימת פקודות.
טבלת השוואה: מתי נטען ולמה מתאים
מנגנון | מתי נטען | עלות קונטקסט | מתאים ל |
|---|---|---|---|
AGENTS.md | כל סשן, במלואו (בכלים שתומכים, לפי רוב המקורות) | כל שורה, בכל סשן | הקשר פרויקט משותף לכל הכלים |
CLAUDE.md בשורש | תחילת סשן, memoized | כל שורה, בכל סשן | הקשר ותוספות ספציפיות ל-Claude |
CLAUDE.md בתת-תיקייה | כשנקראים קבצים מתחתיו | רק כשרלוונטי | הקשר מקומי למודול |
Rules | נטענים ומוזרקים מחדש אחרי compaction | תלויה בהיקף | מדיניות קשיחה |
Skills | שם ותיאור בהתחלה, גוף בהפעלה | כ-100 טוקנים בסרק | נהלים צעד-אחר-צעד |
Hooks | על אירועי מחזור חיים | לא תלויים בקונטקסט | אכיפה דטרמיניסטית |
יתרונות וחסרונות בקצרה
- AGENTS.md: חוצה כלים ולא דורש סכמה, ומשמש כעת כ-fallback ב-Claude Code. מנגד, Claude Code מתעלם ממנו כשיש CLAUDE.md, וסדר הקינון משתנה בין כלים.
- CLAUDE.md: הקובץ הייעודי של Claude Code, עם היררכיה ותמיכה ב-
@imports. מנגד, הוא נוטה להתנפח ולצבור כללים מתחרים, וכל שורה עולה טוקנים. - Skills: נטענים לפי דרישה, ניידים בין כלים ויכולים לכלול סקריפטים. מנגד, ההפעלה תלויה בהתאמת התיאור, ויותר מדי Skills הופכים את ההתנהגות לבלתי צפויה.
AGENTS.md ו-CLAUDE.md ב-Claude Code: fallback, @import ו-symlink
זה החלק שבו רוב הצוותים טועים, בעיקר כי מאמרים ישנים מתארים התנהגות של גרסאות קודמות. לפי Dunlop, יש שלושה מצבים:
- רק AGENTS.md קיים: מגרסה v2.1.277, Claude Code משתמש בו כ-fallback.
- רק CLAUDE.md קיים: נטען כרגיל.
- שניהם קיימים: CLAUDE.md נטען ו-AGENTS.md נשאר בחוץ, אלא אם CLAUDE.md מייבא אותו או שמשנים את הגדרת Project instructions ב-
/config.
חשוב לציין שמספר הגרסה והתאריך מגיעים מבלוג יחיד ולא אומתו מול התיעוד הרשמי. לכן כדאי לבדוק את ההתנהגות על הגרסה המותקנת בפועל, בשיטות שמפורטות בהמשך.
המלצה נפוצה בגרסאות קודמות, למשל ב-BSWEN, הייתה לשים כללים כלליים ב-AGENTS.md, כללים ספציפיים ב-CLAUDE.md, ולא להניח ש-Claude קורא את AGENTS.md. החלק האחרון כבר לא מדויק לגרסאות v2.1.277 ומעלה כשאין CLAUDE.md, אבל עדיין נכון ברגע שקיים CLAUDE.md.
הניסוי שמראה את ההבדל
בבדיקה שתוארה על גרסה v2.1.223, כשהוגדרה מילת קוד רק ב-AGENTS.md, הסוכן ענה UNKNOWN. כש-CLAUDE.md הכיל את השורה @AGENTS.md, הסוכן החזיר את מילת הקוד. כלומר, הייבוא הוא מה שמכניס את התוכן לקונטקסט.
הפתרון המומלץ: CLAUDE.md שמייבא את AGENTS.md
המבנה הפשוט והעמיד ביותר לצוות מעורב הוא AGENTS.md עם כל הכללים המשותפים, ו-CLAUDE.md קצר שמתחיל בייבוא ואחריו רק תוספות ייחודיות ל-Claude:
@AGENTS.md
## Claude Code only
- For database schema changes, use the db-migration skill.
- Run /context if unsure which instruction files are loaded.כך יש מקור אמת אחד לכללים, ו-Claude Code רואה אותם גם כשקיים CLAUDE.md. ההוראות ב-CLAUDE.md צריכות להשלים את AGENTS.md, לא לחזור עליו ובטח לא לסתור אותו.
מלכודת ה-symlink ב-Windows
פתרון פופולרי אחר הוא להפוך את CLAUDE.md ל-symlink שמצביע על AGENTS.md. הבעיה: לפי Dunlop, כשהריפו משוכפל עם core.symlinks=false, שהיא ברירת המחדל ב-Windows, ה-symlink הופך לקובץ זעיר, ו-Claude Code טוען אותו בשקט בלי שום תוכן שימושי. בדרך כלל מדובר בקובץ טקסט רגיל שמכיל רק את נתיב היעד, וזו הסיבה שהוא נראה תקין במבט חטוף ברשימת הקבצים.
זה רלוונטי במיוחד לצוותים ישראליים רבים, שבהם חלק מהמפתחים עובדים על Windows וחלק על macOS או לינוקס. אותו ריפו מתנהג אחרת אצל כל אחד, ואף אחד לא מקבל שגיאה. כך בודקים:
# האם git מוגדר לתמוך ב-symlinks במכונה הזו?
git config --get core.symlinks
# האם CLAUDE.md שמור בריפו כ-symlink? (mode 120000 = symlink)
git ls-files -s CLAUDE.md
# כמה בתים יש בקובץ בפועל? קובץ של כמה בתים בודדים הוא בדרך כלל רק נתיב
wc -c CLAUDE.mdהמסקנה: ייבוא עם @AGENTS.md עדיף על symlink, כי הוא עובד זהה בכל מערכת הפעלה.
מאיפה סתירות בין קבצי הוראות באמת מגיעות
סתירות כמעט אף פעם לא נכתבות בכוונה. הן מצטברות. אלה המקורות הנפוצים:
1. כפילות שהתפצלה
מישהו העתיק את AGENTS.md ל-CLAUDE.md, ומאז כל אחד מהם עודכן בנפרד. אחרי כמה חודשים אחד אומר npm והשני pnpm. אם CLAUDE.md קיים ולא מייבא את AGENTS.md, Claude Code רואה רק גרסה אחת, ו-Cursor או Codex רואים את השנייה. זו לא סתירה בתוך סוכן אחד אלא סתירה בין סוכנים, וזה גרוע יותר כי קשה לזהות אותה.
2. קבצים מקוננים וקבצי rules של כלים אחרים
קבצי AGENTS.md מקוננים בתתי-תיקיות נותנים הנחיות ספציפיות יותר, אבל לפי Promptessor התמיכה בהם וסדר העדיפויות משתנים בין כלים. קובץ מקונן שעובד מצוין ב-Codex עשוי לא להיטען כלל בכלי אחר.
אותו עיקרון חל על קבצי rules ייעודיים. Cursor נמנה עם הכלים שקוראים AGENTS.md, אבל המקורות לא מתעדים את סדר העדיפויות שלו מול קבצי ה-rules שלו. לכן ההחלטה הבטוחה היא לשמור את הכללים המהותיים ב-AGENTS.md, ולהשתמש בקבצים ייעודיים רק למה שבאמת ייחודי לכלי. כל כלל ששוכפל הוא סתירה עתידית.
3. Skill שחוזר על כללים כלליים
Skill למיגרציות שכותב ״להריץ npm test״ בעוד AGENTS.md אומר ״להריץ pnpm test״ הוא מקור קלאסי לסתירה. ברגע שה-Skill מופעל, שתי ההוראות נמצאות בקונטקסט יחד, ואין כלל מתועד שקובע מי מנצח.
4. שכבות שלא רואים
קובץ ~/.claude/CLAUDE.md גלובלי, CLAUDE.local.md אישי ו-auto-memory קיימים אצל מפתח אחד ולא אצל אחר. כשמפתח מדווח ש״הסוכן מתעלם מהכללים״, לעיתים קרובות מדובר בהוראה גלובלית אישית שסותרת את הריפו.
5. compaction וטעינה לפי דרישה
CLAUDE.md בתת-תיקייה נכנס רק כשנקראים קבצים מתחתיו, ו-Skills מוזרקים מחדש אחרי compaction רק עד תקציב משותף. התוצאה: באותו סשן, ההוראות שבקונטקסט בתחילתו שונות מאלה שבו אחרי שעה. סתירה יכולה להופיע ולהיעלם בלי שמישהו שינה קובץ.
המחיר של סתירה
דוגמה ממחישה: לפי BSWEN, בדיון ב-Reddit דווח על AGENTS.md עם שני כללים סותרים, ״לבדוק מצב לפני פעולה״ ו״לבצע את הפעולה מיד״. לפי הדיווח, הם גרמו לסוכן להיכנס ללולאה ולשרוף כ-50 דולר בקריאות API. זה סיפור אנקדוטלי, אבל הדפוס מוכר. ההמלצה של Promptessor ברורה: להסיר הוראות סותרות, לא להשאיר אותן לפרשנות של הסוכן.
מבנה מומלץ לריפו Next.js וכללים שלא מתנגשים
חלוקה שימושית מגיעה מ-Andrew Connell: CLAUDE.md הוא הקשר, rules הן מדיניות קשיחה, skills הם נהלים לפי דרישה, commands הם סקריפטים, ו-hooks הם אכיפה. כשכל סוג הוראה נמצא במקום אחד בלבד, הסיכוי לסתירה יורד משמעותית.
מבנה תיקיות
.
├── AGENTS.md # הקשר וכללים משותפים לכל הכלים
├── CLAUDE.md # @AGENTS.md + תוספות ל-Claude בלבד
├── .claude/
│ ├── settings.json # hooks והרשאות
│ └── skills/
│ ├── db-migration/
│ │ └── SKILL.md
│ └── release/
│ └── SKILL.md
├── src/
│ ├── app/
│ └── lib/
├── .github/workflows/ci.yml # האכיפה האמיתית
└── package.jsonקבצי הוראות מקוננים כדאי להוסיף רק כשיש מודול עם כללים שונים באמת. גם אז כדאי לבדוק בכל כלי בנפרד שהקובץ נטען, משום שההתנהגות לא אחידה.
דוגמה ל-AGENTS.md
# AGENTS.md
## Stack
- Next.js App Router, TypeScript in strict mode, pnpm
- Database access only through src/lib/db
## Commands
- Dev server: pnpm dev
- Type check: pnpm typecheck (tsc --noEmit)
- Lint: pnpm lint
- Tests: pnpm test
## Conventions
- Server Components by default. Add "use client" only for interactivity.
- Validate all external input with Zod at the boundary.
- No `any`. Use `unknown` and narrow.
## RTL and Hebrew
- Root layout uses <html lang="he" dir="rtl">.
- Use logical CSS properties (margin-inline-start, not margin-left).
## Done means
- pnpm typecheck, pnpm lint and pnpm test all pass.סעיף ה-RTL אינו מגיע מהמקורות, אלא הצעה מעשית לפרויקטים בעברית. סוכני קוד נוטים לייצר CSS עם margin-left ו-padding-right שנשבר בממשק מימין לשמאל, וכלל כזה ב-AGENTS.md חוסך תיקונים חוזרים. על בעיה דומה של סוכנים שמייצרים קוד מיושן אפשר לקרוא במדריך סוכני קוד AI וקוד JavaScript מיושן.
דוגמה ל-Skill שלא מתנגש
העיקרון: ה-Skill מתאר נוהל, ומפנה ל-AGENTS.md לכל דבר כללי במקום לחזור עליו.
---
name: db-migration
description: Use when changing the database schema or creating a migration in this repo.
---
# Database migration procedure
Follow the commands and conventions in AGENTS.md. This skill adds only the migration steps.
1. Edit the schema file in src/lib/db.
2. Generate a migration and review the SQL before applying it.
3. Apply the migration to the local database only.
4. Update affected types and run the checks listed under Done means in AGENTS.md.ה-Skill לא מזכיר שום פקודת npm או pnpm משלו. אם מנהל החבילות ישתנה, צריך לעדכן מקום אחד בלבד. לפי Termdock, גודל אידיאלי ל-SKILL.md הוא מתחת ל-500 שורות.
מקום אחד לכל כלל
מבנה טוב לא יעזור אם הכללים עצמם עמומים או משוכפלים. כל כלל צריך לגור בדיוק בקובץ אחד. אם כלל מופיע גם ב-AGENTS.md וגם ב-Skill, אחד מהם יימחק. בתחילת כל Skill אפשר לכתוב ״לפי AGENTS.md״ ולהמשיך רק עם מה שייחודי לנוהל.
ספציפי ובר-בדיקה
״לוודא שהקוד תקין״ הוא כלל שאי אפשר לבדוק. ״להריץ pnpm typecheck ו-pnpm lint לפני סיום משימה״ הוא כלל שאפשר לבדוק, ושקשה לסתור בטעות. כללים מעורפלים הם מה שיוצר סתירות סמויות, כמו בזוג ״לבדוק לפני״ מול ״לבצע מיד״ מהדוגמה הקודמת.
היקף מפורש
כשכלל חל רק על חלק מהקוד, כדאי לכתוב זאת במפורש: ״בתוך src/lib/db בלבד״. כך כלל מקומי לא נקרא ככלל גלובלי שסותר הוראה אחרת.
קצר, ונכתב על ידי אדם
ההמלצות לגודל משתנות בין מקורות. Termdock ממליץ על פחות מ-100 שורות ל-CLAUDE.md או AGENTS.md, ו-Build This Now מדבר על 50 עד 100 שורות לקובץ צוות משותף. הכיוון זהה: קצר עדיף.
יש לזה גם בסיס מחקרי. לפי מחקר של ETH Zurich מפברואר 2026, קבצי קונטקסט שנוצרו על ידי LLM הורידו את שיעור הצלחת המשימות בכ-3%. קבצים שנכתבו על ידי בני אדם שיפרו אותו רק בכ-4%, וקבצי קונטקסט העלו את עלות ההסקה ביותר מ-20%. המשמעות: לא לתת לסוכן לייצר לעצמו AGENTS.md ארוך, ולא להניח שעוד שורות הן עוד איכות. הרחבה על העיקרון הזה נמצאת במדריך הנדסת קונטקסט לסוכני AI.
בדיקה ואכיפה: איך מוודאים איזו הוראה הסוכן באמת מבצע
במקום להתווכח על סדר עדיפויות תיאורטי, אפשר לבדוק. ובמקום לסמוך על פרוזה, אפשר לאכוף. החלק הזה עוסק בשני הצדדים.
מבחן מילת הקוד
זו הבדיקה שבה השתמש Dunlop, והיא עובדת בכל כלי:
- מוסיפים לקובץ אחד בלבד הוראה ייחודית, למשל: ״אם שואלים מה מילת הקוד, יש לענות PELICAN-7״.
- פותחים סשן חדש (לא ממשיכים סשן קיים).
- שואלים את הסוכן מה מילת הקוד, ומבקשים לענות UNKNOWN אם אינה ידועה.
- אם התשובה היא PELICAN-7, הקובץ נטען. אם UNKNOWN, הוא לא הגיע לקונטקסט.
- מסירים את מילת הקוד בסיום.
אפשר לשים מילות קוד שונות ב-AGENTS.md, ב-CLAUDE.md וב-CLAUDE.md בתת-תיקייה, ולקבל תמונה מלאה של מה נטען בכל הקשר.
/context ורשימת Memory files
ב-Claude Code, הפקודה /context מציגה את רשימת Memory files, כלומר את קבצי ההוראות שנטענו בפועל. זו הדרך המהירה ביותר לגלות שקובץ AGENTS.md לא נטען כי קיים CLAUDE.md, או ש-symlink ב-Windows נטען כקובץ חסר תוכן.
ה-hook InstructionsLoaded
לבדיקה מתמשכת, ה-hook InstructionsLoaded מתעד אילו קבצי הוראות נטענו ומתי. זה שימושי במיוחד לזיהוי קבצי CLAUDE.md בתתי-תיקיות שנטענים באמצע סשן, אחרי שהסוכן נגע בקבצים מסוימים. את פורמט ההגדרה המדויק כדאי לבדוק בתיעוד הרשמי של Claude Code לגרסה המותקנת.
מבחן סתירה מבוקר
כשצריך לדעת איך הסוכן מתנהג מול סתירה אמיתית בין CLAUDE.md ל-Skill, אפשר ליצור אותה בכוונה בענף ניסיון. CLAUDE.md אומר לענות במילה אחת, ה-Skill אומר לענות במילה אחרת, ומפעילים משימה שמתאימה לתיאור ה-Skill.
חשוב להבין מה הבדיקה מראה: את ההתנהגות של מודל וגרסה מסוימים, לא כלל קבוע. התוצאה יכולה להשתנות בין גרסאות. לכן המטרה של הבדיקה היא להמחיש שיש בעיה, לא להצדיק השארה של הסתירה.
בדיקה חוצת כלים
בצוות שמשתמש ב-Cursor, Codex ו-Claude Code, מריצים את מבחן מילת הקוד בכל כלי. אם כלי אחד לא רואה את AGENTS.md, עדיף לגלות את זה בבדיקה של חמש דקות ולא בקוד שנבנה לפי כללים אחרים ומגיע לסקירה. על העומס שקוד כזה יוצר בתהליך הסקירה אפשר לקרוא במדריך code review לקוד שנכתב על ידי AI.
מפרוזה לאכיפה: hooks בזמן העבודה
הוראה בשפה טבעית היא בקשה, לא ערובה. גם כשהקבצים נטענים כראוי, המודל עלול להתעלם מכלל בסשן ארוך או תחת לחץ של משימה מורכבת. לכן כל דבר שאסור לדלג עליו צריך לעבור מפרוזה למנגנון דטרמיניסטי.
Anthropic ממצבת hooks לאוטומציה דטרמיניסטית, והם עוקפים compaction. הנה דוגמה להמחשה להרצת lint אחרי כל עריכה ב-.claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "pnpm lint --quiet" }
]
}
]
}
}הדוגמה הזו אינה מגיעה מהמקורות שנסקרו. את שמות האירועים והפורמט המדויק כדאי לאמת מול התיעוד העדכני, כי הם עשויים להשתנות בין גרסאות.
CI כשכבת האכיפה האחרונה
עיקרון שחוזר בדיונים על אבטחת סוכני קוד הוא שהבטחות אבטחה צריכות לשבת בהרשאות, ב-hooks, ב-CI או בתשתית, ולא רק בהוראות בשפה טבעית. העיקרון הזה מתיישב היטב עם ההבחנה של Anthropic בין הוראות לבין אוטומציה דטרמיניסטית. CI אוכף את אותם כללים על כל סוכן ועל כל מפתח, בלי קשר לאיזה קובץ הוראות נטען:
name: ci
on: [pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm typecheck
- run: pnpm lint
- run: pnpm testבסביבת פרודקשן מומלץ להצמיד actions ל-SHA ולא לתגית, כפי שמוסבר במדריך אבטחת GitHub Actions. ההיגיון דומה גם לגבי הוראות שמגיעות מבחוץ: README או לוג יכולים להכניס הוראות לקונטקסט, נושא שמפורט במדריך על הזרקת פרומפט עקיפה.
ביקורת וגיזום כל כמה חודשים
קבצי הוראות גדלים בשקט. Andrew Connell מתאר CLAUDE.md שתפח ל-540 שורות, ותוכנית להעביר את המדיניות ממנו ל-rules. Boris Cherny ממליץ לנסות כל חצי שנה למחוק את CLAUDE.md, את ה-Skills ואת ה-hooks, כדי לראות מה מודלים חדשים כבר לא צריכים. כותב המאמר שמצטט אותו קיצץ CLAUDE.md של יותר מ-500 שורות ל-165, ודיווח על פחות כללים מתחרים.
צ'קליסט לביקורת תקופתית:
- להריץ
/contextולוודא שהקבצים הנטענים הם הצפויים. - לחפש כפילויות בין AGENTS.md, CLAUDE.md ו-Skills (פקודות, מנהל חבילות, נתיבים).
- למחוק כללים שכבר נאכפים על ידי lint, TypeScript או CI.
- לבדוק אם קיימים קבצים גלובליים או מקומיים שסותרים את הריפו אצל מפתחים בצוות.
- לעבור על auto-memory: לפי memU נטענות בכל סשן 200 השורות הראשונות או 25KB, ו״לקחים״ ישנים שנשמרו שם עלולים לסתור את הכללים העדכניים בריפו.
- לבדוק שתיאורי ה-Skills עדיין מדויקים, כי ההפעלה תלויה בהם.
- להריץ שוב את מבחן מילת הקוד בכל כלי שהצוות משתמש בו.
שאלות נפוצות
אם AGENTS.md ו-CLAUDE.md סותרים, מי מנצח ב-Claude Code?
במקרה הנפוץ אין בכלל התמודדות. אם קיים CLAUDE.md, Claude Code טוען אותו ומתעלם מ-AGENTS.md אלא אם CLAUDE.md מייבא אותו עם @AGENTS.md. אם קיים רק AGENTS.md (בגרסה v2.1.277 ומעלה), הוא נטען. כששניהם בקונטקסט, למשל דרך ייבוא, המקורות לא מתעדים כלל הכרעה רשמי, ולכן צריך פשוט להסיר את הסתירה.
איך משתפים קובץ אחד בין Claude Code לכלים אחרים?
כותבים את הכללים המשותפים ב-AGENTS.md ומוסיפים @AGENTS.md בראש CLAUDE.md, ואחריו רק תוספות ייחודיות ל-Claude. symlink אמנם עובד, אבל נשבר בשקט בשכפול ב-Windows עם core.symlinks=false.
האם Claude Code Skills גוברים על CLAUDE.md?
המקורות לא מתעדים סדר עדיפויות כזה. Skills נטענים רק כשהם מופעלים, ומוזרקים מחדש אחרי compaction בתוך תקציב משותף, בזמן ש-CLAUDE.md בשורש נוכח תמיד. הדרך הנכונה היא למנוע חפיפה ביניהם ולבדוק את ההתנהגות בפועל.
איך יודעים אילו הוראות נטענו בפועל?
מריצים /context ובודקים את רשימת Memory files, או משתמשים ב-hook InstructionsLoaded כדי לתעד אילו קבצים נטענו ומתי. מבחן מילת קוד, כלומר הוראה ייחודית בקובץ אחד ושאלה ישירה לסוכן, מראה איזה קובץ הגיע לקונטקסט, והוא עובד בכל כלי.
מה שמים איפה?
לפי החלוקה של Andrew Connell: הקשר פרויקט שמפתח חדש צריך ביום הראשון נכנס ל-CLAUDE.md או AGENTS.md. מדיניות קשיחה נכנסת ל-rules, נהלים צעד-אחר-צעד נכנסים ל-Skills, ובדיקות שאסור לדלג עליהן נכנסות ל-hooks ול-CI.
האם קבצי קונטקסט באמת עוזרים?
במידה מוגבלת. לפי מחקר ETH Zurich, קבצים שנוצרו על ידי LLM פגעו מעט בהצלחה, קבצים שנכתבו על ידי בני אדם שיפרו אותה רק בכ-4%, והעלות עלתה ביותר מ-20%. לכן כדאי לשמור עליהם קצרים, ספציפיים וכתובים ביד.
סיכום
השאלה ״מי מנצח בין AGENTS.md ו-CLAUDE.md ל-Skill״ מקבלת תשובה לא צפויה: ברוב המקרים אף אחד, כי ההכרעה האמיתית קורית בשלב הטעינה. Claude Code מתעלם מ-AGENTS.md כשקיים CLAUDE.md, אלא אם מייבאים אותו. Skills נכנסים לקונטקסט רק כשהם מופעלים. CLAUDE.md בתת-תיקייה נכנס רק כשנוגעים בקבצים שלו. ההיררכיה של שש השכבות שמתוארת ברשת מגיעה ממקור צד שלישי, ולא מתיעוד רשמי, ואופן הטעינה של רוב הכלים האחרים כמעט לא מתועד.
לצוות Next.js ו-TypeScript, הגישה המעשית היא: AGENTS.md קצר וכתוב ביד כמקור אמת משותף, CLAUDE.md שמייבא אותו ומוסיף רק את מה שייחודי ל-Claude, Skills שמתארים נהלים בלי לחזור על כללים, ו-hooks ו-CI לכל מה שחייב לקרות. במקום לנחש, בודקים עם /context ומבחן מילת קוד, ופעם בכמה חודשים גוזמים את מה שכבר לא נחוץ, כולל auto-memory.
מקורות
- CLAUDE.md vs AGENTS.md: It's the Loader, Not the File (Alex Dunlop)
- Steering Claude Code: when to use CLAUDE.md, skills, hooks, and subagents (Anthropic)
- Anthropic Agent Skills: The SKILL.md Format Explained (memU)
- SKILL.md vs CLAUDE.md vs AGENTS.md Compared (Termdock)
- AGENTS.md vs CLAUDE.md Explained (Build This Now)
- Claude Code skills vs rules vs hooks (Andrew Connell)
- AGENTS.md for Codex and AI Coding Agents (BSWEN)
- Claude Code Best Practices: Audit Your Setup (Wyndo)
- Best AGENTS.md Examples (Promptessor)
- AGENTS.md vs .cursorrules vs Claude Skills: 2026 Comparison (BuildBetter)






