איך כותבים קובץ CLAUDE.md טוב - מדריך מעשי מניסיון אמיתי

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

למה בכלל צריך את זה

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

מה כן כדאי לכלול

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

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

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

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

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

מה כדאי להימנע ממנו

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

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

הנחיות מעורפלות שאין להן משמעות פרקטית. "תכתוב קוד נקי" זה לא הנחיה שימושית - זה סיסמה. "תשתמש בפונקציות עזר מ-utils.py לפני שאתה כותב לוגיקה חדשה" זה הנחיה שימושית כי אפשר לפעול לפיה.

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

איך לבנות אותו בהדרגה, לא בבת אחת

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

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

דוגמה למבנה שעובד

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

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

לסיכום

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

רוצים לראות דוגמאות אמיתיות מפרויקטים אחרים? הצטרפו לקהילה בדיסקורד.