מה זה CLAUDE.md ואיך כותבים אחד טוב

למה קובץ אחד משנה כל כך?

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

CLAUDE.md פותר בדיוק את זה. תחשבו עליו כתדריך לעובד חדש — רק שהעובד הזה קורא אותו מחדש, בריכוז מלא, בתחילת כל בוקר. מה שכתוב שם הוא מה שקלוד קוד יודע לפני שהקלדתם מילה.

מה נכנס לקובץ, ומה נשאר בחוץ?

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

מה שכן:

• פקודות שגרתיות: איך מריצים, בודקים, בונים ופורסים — כדי שהסוכן לא ינחש
• מוסכמות קוד: סגנון הזחה, שמות, פורמט — כתובים ספציפית, לא “לכתוב יפה”
• מבנה הפרויקט: איפה יושבת הלוגיקה, איפה הקומפוננטות, איפה הסכימה
• גבולות אדומים: “לא לגעת בתיקייה X”, “אף פעם לא לדחוף ישר ל-main”
• החלטות שסוכן לא ינחש: בחירות ארכיטקטורה ומוסכמות מקומיות שאין להן היגיון אוניברסלי

מה שלא:

• נוהל רב-שלבי שלם: “איך כותבים פוסט”, “איך בודקים דוח כספי” — זה מקומו של סקיל, שנטען רק כשצריך אותו
• הנחיה שרלוונטית רק לחלק אחד מהקוד: לזה יש כללים ממוקדי-נתיב (‎.claude/rules/) שנטענים רק כשעובדים על קבצים תואמים
• סודות ומפתחות: אלה הולכים למשתני סביבה, לא לקובץ שנכנס ל-git

איך נראה CLAUDE.md טוב? דוגמה מוסברת

הנה קובץ אמיתי וקומפקטי לחנות אונליין. שימו לב כמה מעט צריך:

# Acme Store — חנות אונליין (Next.js)

## פקודות
- התקנה: `npm install`
- הרצה מקומית: `npm run dev` (פורט 3000)
- בדיקות: `npm test` — להריץ לפני כל commit
- בילד: `npm run build`

## מבנה
- קומפוננטות: `src/components/`
- לוגיקת API: `src/app/api/`
- סכימת DB: `prisma/schema.prisma`

## כללים
- TypeScript strict — בלי שימוש ב-any
- הזחה של 2 רווחים
- לא לגעת ב-`src/legacy/` בלי אישור
- מחירים נשמרים באגורות (מספר שלם), לא בשקלים עשרוניים

ומה עושה אותו טוב:

• הכותרת ממקמת מיד: שם הפרויקט והטכנולוגיה בשורה אחת. הסוכן יודע שהוא ב-Next.js לפני שקרא קובץ אחד
• הפקודות מדויקות: לא “להריץ בדיקות” אלא הפקודה עצמה, עם ההערה מתי. סוכן שיודע את הפקודה לא ינחש אחת שגויה
• הכלל האחרון הוא הזהב: ש”מחירים נשמרים באגורות” זה בדיוק סוג הדבר שאף סוכן לא ינחש — וטעות בו שוברת חישובים בשקט. שורה אחת חוסכת באג

הכלל שמפריד בין טוב למצוין: כל שורה עולה טוקנים

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

היעד הרשמי הוא מתחת ל-200 שורות. שלושה עקרונות שומרים על הקובץ רזה וחד:

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

נקודה שחשוב לומר ביושר: CLAUDE.md מגיע לקלוד כהודעה, לא כחוק ברזל. הוא מעצב התנהגות, לא אוכף אותה — אין ערובה לציות מושלם, במיוחד להנחיות מעורפלות. כלל שחייב לרוץ תמיד (למשל בדיקה לפני כל commit) עדיף לממש כ-hook, שרץ כפקודה בלי תלות בשיקול הדעת של הסוכן.

הטעויות הנפוצות

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

איפה מתחילים, ומה עושה זאת לבד

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

ובמקביל רץ מנגנון משלים: קלוד קוד יכול לצבור לעצמו זיכרון אוטומטי (auto memory) — הערות שהוא כותב על סמך התיקונים וההעדפות שלכם, בלי שתכתבו מילה. CLAUDE.md הוא מה שאתם מכתיבים; הזיכרון האוטומטי הוא מה שהוא לומד תוך כדי. השניים עובדים ביחד.

שורה תחתונה

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

רוצים קיצור דרך? ערכת ההתחלה בחינם כוללת תבנית CLAUDE.md בעברית שאפשר להעתיק ולהתאים לפרויקט תוך דקות — נקודת פתיחה טובה בהרבה מקובץ ריק.