CLAUDE.md קצר: מה למחוק, מה להשאיר, ותבנית מוכנה

מה המחקר על AGENTS.md בדק, ומה הוא מצא?

המחקר נקרא Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?. הכותבים מ-ETH ציריך, האוניברסיטה הטכנולוגית של ציריך, ומחברת LogicStar.ai. הגרסה הראשונה פורסמה ב-arXiv בפברואר 2026, והגרסה השלישית ב-29 בספטמבר 2026.

הם בדקו סוכני קוד בשני מצבים: משימות מוכרות מ-SWE-bench עם קבצי הקשר שמודל כתב, ואוסף חדש של באגים מפרויקטים שבהם המפתחים עצמם כתבו את הקובץ. ומה יצא, לפי התקציר:

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

למה CLAUDE.md ארוך עולה לכם כסף?

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

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

התיעוד של אנתרופיק אומר דבר דומה: ממליצים לשמור כל CLAUDE.md מתחת ל-200 שורות, וכותבים שקבצים ארוכים צורכים יותר הקשר ומורידים את מידת ההיצמדות להוראות.

מה מוחקים מ-CLAUDE.md?

כל דבר שקלוד יכול לגלות לבד תוך כמה שניות של קריאה:

• תיאור כללי של הפרויקט. "זה אתר של עסק לאיפור שבנוי ב..." הוא רואה את זה מהקבצים. זה בדיוק מה שהמחקר מצא שלא עוזר.
• עץ תיקיות. הוא מריץ ls ומקבל אותו עדכני. העץ בקובץ מתיישן אחרי שבוע.
• הסברים על הטכנולוגיה. שהפרויקט ב-React, איך עובד Next.js. הוא יודע.
• הוראות כלליות. "תכתוב קוד נקי", "תבדוק את העבודה". אלה לא משנות כלום, כי הוא כבר מנסה.
• תהליכים ארוכים של פעם בחודש. לפי התיעוד, תהליך רב שלבי עובר לסקיל, וכלל שנוגע רק לחלק מהפרויקט עובר לקובץ ב-.claude/rules/ שנטען רק כשצריך.

מה משאירים בקובץ?

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

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

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

תבנית CLAUDE.md קצרה, להעתקה

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

# Project rules

## Commands
- Dev server: [e.g. npm run dev, port 3000]
- Tests: [e.g. npm test, run before every commit]
- Deploy: [e.g. git push to main, auto-deploys]

## Rules Claude cannot guess
- [e.g. All user-facing text is Hebrew, RTL]
- [e.g. Never edit files in /generated, they are rebuilt]
- [e.g. Prices come only from data/prices.json]

## Gotchas
- [Something that broke before and is not obvious from the code]

## My preferences
- Answer in Hebrew, short. Code and comments in English.
- [e.g. Ask before deleting files or installing packages]

שימו לב מה אין בה: אין "About this project", אין עץ תיקיות, אין רשימת טכנולוגיות. אם אחרי שבוע של עבודה קלוד עושה את אותה טעות פעמיים, זה הרגע להוסיף שורה.

פרומפט שעושה את הדיאטה בשבילכם

יש לכם כבר קובץ ארוך? פותחים קלוד קוד בפרויקט ומדביקים:

תקרא את CLAUDE.md של הפרויקט הזה ותעשה לו דיאטה.
לכל שורה תחליט: להשאיר, למחוק, או להעביר.
למחוק: תיאור כללי של הפרויקט, עץ תיקיות, הסברים על הטכנולוגיה,
והוראות כלליות כמו "תכתוב קוד נקי". כל מה שאתה יכול לגלות לבד מהקבצים.
להשאיר: פקודות, כללים לא סטנדרטיים, מלכודות שלא רואים מהקוד, והעדפות שלי.
להעביר: תהליך ארוך לסקיל, וכלל שנוגע לחלק אחד בפרויקט לקובץ ב-.claude/rules/.
קודם תראה לי טבלה עם ההחלטה לכל סעיף ומספר השורות לפני ואחרי.
אל תשנה כלום עד שאאשר. תשמור גיבוי בשם CLAUDE.md.bak.

אחרי הדיאטה, הפקודה /context מראה אילו קבצי זיכרון נטענו. ולבדיקה של סתירות והוראות שהתיישנו בכל קבצי ההוראות, התיעוד מציע את /doctor prompt-audit. עליו יש לנו מדריך נפרד: בדיקה תקופתית עם /doctor.

חשוב לדעת

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