המדריך המלא לכתיבת CLAUDE.md — מסמך הנחיות לקלוד טוב, יעיל וחסכוני

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

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

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

הדרך הקצרה: הקובץ הראשון שלכם בשתי דקות

אם אתם רק רוצים להתחיל, זה כל מה שצריך לעשות עכשיו:

cd my-project
claude

ובתוך השיחה:

/init

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

ההמשך של המדריך הוא איך הופכים אותו מ”שימושי” ל”באמת עובד”.

איפה הקובץ יושב, ומה נטען מתי

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

הקובץ	מתי נטען
~/.claude/CLAUDE.md	בכל שיחה
./CLAUDE.md	בכל שיחה
./CLAUDE.local.md	בכל שיחה
.claude/rules/ בלי paths	בכל שיחה
src/api/CLAUDE.md	רק בתוך התיקייה
.claude/rules/ עם paths	רק בקבצים תואמים
.claude/skills/	רק כשמתאים

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

ולמי ששייך למי: הקובץ ב-~/.claude/ הוא אישי וחל על כל הפרויקטים במחשב; ./CLAUDE.md בשורש הפרויקט משותף לצוות דרך git; ו-CLAUDE.local.md הוא פרטי ולא נכנס ל-git, אז שם מקומן של העדפות שרק אתם צריכים.

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

שלב 1: מריצים ‎/init ונותנים לקלוד לנחש

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

שני דברים ששווה לדעת עליו:

• הוא לא דורס: אם כבר יש CLAUDE.md, /init מציע שיפורים במקום למחוק את מה שכתבתם
• הוא קורא גם הגדרות של כלים אחרים: אם הפרויקט מגיע עם כללי Cursor (בתיקיית ‎.cursor/rules‎) או הנחיות Copilot, הוא מכניס את החלקים הרלוונטיים לקובץ שהוא מייצר

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

שלב 2: גוזמים את מה שקלוד מסיק לבד

זה השלב שרוב האנשים מדלגים עליו, וזה גם השלב שהשתנה ביולי 2026. Anthropic הסירה יותר מ-80% מפרומפט המערכת של קלוד קוד עבור מודלי דור קלוד 5 בלי ירידה מדידה בביצועים, וההמלצה שנגזרת מזה חדה: לשמור על הקובץ קל, ולהשקיע את רוב הטוקנים במלכודות שבתוך הקוד.

התיעוד אפילו מגדיר מה נגזר ומה נשאר, כי הפקודה /doctor יודעת לבצע את החיתוך הזה בעצמה:

גוזמים (קלוד מסיק מהקוד)	שומרים (אין לזה זכר בקוד)
פריסת תיקיות ומבנה הפרויקט	מלכודות שנראות תקינות ושוברות בשקט
רשימות תלויות וספריות	הנימוק מאחורי החלטה לא מובנת מאליה
סקירת ארכיטקטורה כללית	מוסכמות שסוטות מברירת המחדל של הכלים
הסבר מה כל קובץ עושה	פקודות מדויקות להרצה ולבדיקה
”הפרויקט משתמש ב-TypeScript"	"מחירים נשמרים באגורות, לא בשקלים”

הכלל המעשי: לפני שאתם משאירים שורה, שאלו “האם סוכן שקורא את הקוד היה מגיע לזה לבד?” אם התשובה כן — היא מבזבזת מקום. מבנה הפרויקט הוא הפריט בעל הערך הנמוך ביותר בקובץ, ובגרסה 2.1.206 ומעלה /doctor יציע לכם לחתוך אותו.

שלב 3: מוסיפים את המלכודות — זה הלב

עכשיו מגיע החלק שבאמת מחזיר את ההשקעה. מלכודת היא כל דבר שעובד “נכון” לפי הקוד ובכל זאת שובר משהו. דוגמאות אמיתיות:

• יחידות ופורמטים: “מחירים נשמרים באגורות כמספר שלם” — סוכן שיכתוב שקלים עשרוניים ישבור חישובים בשקט
• סדר פעולות מחייב: “יוצרים מיגרציה לפני שמעדכנים את הסכימה, אחרת הפריסה נכשלת”
• דברים שנראים כמו באג ואינם: “השדה ‎legacy_id‎ נראה מיותר, אבל מערכת החיוב עדיין קוראת אותו”
• גבולות אדומים: “אף פעם לא לדחוף ישר ל-main”, “לא לגעת בתיקיית ‎src/legacy/‎ בלי אישור”
• מוסכמות מקומיות בלי היגיון אוניברסלי: “כל התאריכים נשמרים ב-UTC גם כשהתצוגה בשעון ישראל”

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

שלב 4: בודקים שהקובץ באמת נטען

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

/context

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

/memory

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

שלב 5: מתחזקים לפי טעויות חוזרות

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

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

איפה ההנחיה הזאת בכלל שייכת?

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

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

שלוש דוגמאות מלאות, לפי סוג פרויקט

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

אתר או אפליקציית ווב:

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

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

## כללים
- TypeScript strict — בלי שימוש ב-any
- לא לגעת ב-`src/legacy/` בלי אישור

## מלכודות
- מחירים נשמרים באגורות (מספר שלם), לא בשקלים עשרוניים
- כל התאריכים ב-UTC; ההמרה לשעון ישראל קורית רק בתצוגה
- `npm run dev` נכשל בשקט אם חסר `.env.local` — להעתיק מ-`.env.example`

אוטומציה או סקריפט נתונים בפייתון:

# דוח מכירות שבועי (Python)

## פקודות
- הרצה: `py -3.13 weekly_report.py` — לא `python`, גרסה 3.14 שוברת את pandas כאן
- בדיקות: `pytest -q`

## מלכודות
- קובצי הקלט מגיעים בקידוד cp1255, לא UTF-8 — לפתוח עם encoding מפורש
- ה-API של הספק מגביל ל-60 בקשות בדקה ומחזיר 200 עם גוף ריק כשחורגים
- להריץ תמיד עם `--dry-run` קודם; בלעדיו הסקריפט שולח מיילים ללקוחות

פרויקט תוכן, בלי קוד בכלל:

# בלוג החברה — ניהול תוכן

## מבנה
- פוסטים ב-`posts/`, שם קובץ בפורמט `YYYY-MM-DD-slug.md`

## כללי כתיבה
- כתיב מלא בלי ניקוד, פנייה בלשון רבים
- שמות מותגים באנגלית; מחירים בשקלים

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

שורה טובה מול שורה גרועה

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

במקום זה	כתבו את זה
”לכתוב קוד נקי"	"פונקציה מעל 40 שורות מתפצלת"
"לפרמט את הקוד כמו שצריך"	"הזחה של 2 רווחים"
"לבדוק את השינויים"	"‎npm test‎ לפני כל commit"
"להיזהר עם בסיס הנתונים"	"אין להריץ מיגרציות על פרודקשן, רק דרך CI"
"הפרויקט בנוי ב-React עם רכיבים”	(למחוק — קלוד רואה את זה בקוד)

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

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

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

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

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

CLAUDE.md מול הזיכרון האוטומטי

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

	CLAUDE.md	זיכרון אוטומטי
מי כותב	אתם	קלוד
מה נכנס	הוראות וכללים	תבניות ותובנות שהוא למד
היקף	פרויקט, משתמש או ארגון	לפי מאגר קוד, מקומי למחשב
שליטה	מלאה, זה קובץ שלכם	ניתן לכיבוי ולעריכה דרך ‎/memory

השניים משלימים: CLAUDE.md הוא מה שאתם מכתיבים, והזיכרון האוטומטי הוא מה שקלוד לומד תוך כדי. אם אתם מבקשים מקלוד “תזכור ש…”, זה נשמר בזיכרון האוטומטי — כדי שזה ייכנס לקובץ, בקשו במפורש להוסיף ל-CLAUDE.md.

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

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

שלושה דברים קטנים ששווה לדעת

• הערות שלא עולות טוקנים: הערת HTML ברמת בלוק (‎<!-- הערה למתחזקים -->‎) נחתכת לפני שהתוכן נכנס להקשר. מושלם לתיעוד פנימי בתוך הקובץ בלי לשלם עליו
• צירוף קבצים אחרים: אפשר לשלוב קובץ עם ‎@path/to/file‎, אבל שימו לב — הקובץ המצורף נטען בפתיחה בדיוק כמו השאר, כך שזה מסדר את הארגון ולא מוריד את העלות
• אם יש לכם כבר AGENTS.md: קלוד קוד קורא CLAUDE.md ולא AGENTS.md. הפתרון הנקי הוא CLAUDE.md שמכיל שורה אחת שמצרפת אותו, ומתחתיה תוספות ספציפיות לקלוד. בווינדוס עדיף הצירוף על קישור סימבולי, שדורש הרשאות מנהל

שורה תחתונה

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

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