CLAUDE.md, הקובץ שגורם לקלוד להכיר את הפרויקט שלכם

פתיחה

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

אז אתם מסבירים שוב פעם. ושוב פעם.

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

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

מה הקובץ הזה בעצם עושה

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

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

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

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

איפה הקובץ יושב

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

בתיקיית הפרויקט, ./CLAUDE.md או ./.claude/CLAUDE.md. זה המקום העיקרי, וזה מה שרוב האנשים צריכים. הוא נשמר בגיט ומשותף לכל מי שעובד על הפרויקט.

בתיקיית הבית שלכם, ~/.claude/CLAUDE.md. זה להעדפות אישיות שחלות על כל הפרויקטים שלכם.

ויש גם ./CLAUDE.local.md, לדברים אישיים שקשורים לפרויקט הזה אבל שאתם לא רוצים לשתף. תוסיפו אותו ל-.gitignore כדי שלא ייכנס לגיט.

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

איך יוצרים אותו בשנייה

אתם לא צריכים לכתוב אותו מאפס. תריצו בתוך תיקיית הפרויקט:

/init

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

ואם כבר יש לכם קובץ, /init לא ידרוס אותו. הוא יציע לכם שיפורים.

הטעות שכמעט כולם עושים

וכאן החלק שבשבילו כתבתי את המדריך הזה.

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

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

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

תחשבו על זה כמו על בן אדם. אם תיתנו לו רשימה של עשרה כללים, הוא יזכור את כולם. אם תיתנו לו המון כללים, הוא יזכור כמה מהם ולא תדעו אילו.

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

זהו. זה כל הסוד, וזה גם מה שמפריד בין קובץ שעובד לקובץ שיושב.

מה כן נכנס לקובץ

הכלל הפשוט ביותר: מה שהייתם צריכים להסביר מחדש בכל שיחה.

Anthropic נותנים ארבעה סימנים לזיהוי, ואלה בדיוק הרגעים שבהם צריך להוסיף שורה.

קלוד עשה את אותה טעות פעם שנייה.

ביקורת קוד תפסה משהו שקלוד היה אמור לדעת על הפרויקט הזה.

הקלדתם את אותו תיקון שהקלדתם גם בשיחה הקודמת.

ומישהו חדש בצוות היה צריך בדיוק את אותו הסבר.

ומה שנכנס בפועל: פקודות הבנייה והבדיקה, המוסכמות שלכם, מבנה הפרויקט, וכללים מסוג "תמיד תעשה כך", הכל!

מה לא נכנס לקובץ

וזה חשוב באותה מידה.

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

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

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

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

זה הכל.

איך לכתוב שורה שבאמת עובדת

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

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

לדוגמא: במקום "תבדוק את השינויים", תכתבו "הרץ npm test לפני שמירה".

לדוגמא: במקום "תשמור על סדר בקבצים", תכתבו "מטפלי ה-API יושבים ב-src/api/handlers/".

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

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

יש לכם כבר קובץ ורוצים לסדר אותו

זה החלק המעשי, ורוב האנשים נמצאים בדיוק שם.

/doctor

איך יודעים שזה בכלל עובד

שתי פקודות, וכדאי להכיר את שתיהן.

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

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

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

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

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

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

איך אני הייתי מתחיל

אלה כללי אצבע שיחסכו לכם זמן.

תריצו /init ותקבלו בסיס בחינם.

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

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

ותעברו עליו פעם בחודש. קובץ שגדל לאט הוא בדיוק סוג הדבר שאף אחד לא שם לב אליו עד שהוא כבר לא עובד.

סיום

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

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

ובהמשך נתקדם.