$ man how-to/how-to-write-claude-md

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

PATTERN

Claude Code טוען CLAUDE.md ממספר מיקומים, ומאחד אותם לפי סדר: 1. ~/.claude/CLAUDE.md - קונפיגורציה גלובלית. חלה על כל פרויקט. שים את ההעדפות האישיות שלך כאן: הגדרות עורך, סגנון commit, העדפות תקשורת. 2. /project-root/CLAUDE.md - קונפיגורציית פרויקט. חלה על הריפו הזה. שים הוראות ספציפיות לפרויקט כאן: פקודות build, תקני קוד, סקירת ארכיטקטורה. 3. /project-root/src/CLAUDE.md - קונפיגורציית תיקייה. חלה כשעובדים בתיקיית src/. שים הוראות ספציפיות למודול כאן: מוסכמות API למודול ה-API, תבניות קומפוננטות למודול ה-UI. כל רמה מוסיפה להקשר. גלובלי ועוד פרויקט ועוד תיקייה. השתמש בזה כדי להימנע מחזרה: גלובלי מטפל בסגנון האישי שלך, פרויקט מטפל ב-codebase, תיקייה מטפלת במודול. ל-monorepos: שים מוסכמות משותפות ב-CLAUDE.md של השורש. שים הוראות ספציפיות לאפליקציה בתיקיית כל אפליקציה. לדוגמה, website/apps/dashboard/CLAUDE.md יכול לומר "אפליקציה זו משתמשת ב-Tailwind CSS וקומפוננטות shadcn/ui" בעוד ש-CLAUDE.md של השורש מכסה את קונפיגורציית TypeScript המשותפת.

PATTERN

קבצי CLAUDE.md האפקטיביים ביותר מכסים שישה תחומים: 1. פקודות build וטסטים. הפקודות המדויקות ל-build, test, lint ופריסה. לא "הרץ את הטסטים" אלא "npm run test" או "pytest -x tests/". Claude Code משתמש בהם ישירות. 2. מבנה הפרויקט. מפה קצרה של ה-codebase. היכן קוד המקור, היכן הטסטים, היכן קבצי קונפיגורציה. שתיים עד חמש שורות, לא עץ תיקיות שלם. 3. מוסכמות קוד. הזחה, דפוסי שמות, סדר imports, שמות קבצים. ספציפי וניתן לאימות: "השתמש בהזחה של 2 רווחים" ולא "עצב קוד יפה." 4. כללי בטיחות. מה לעולם לא לעשות. "לעולם אל תקבל קבצי .env." "לעולם אל תדחוף ל-main בלי שהטסטים עוברים." "לעולם אל תמחק קבצי migration." אלה מעקות בטיחות שמונעים טעויות יקרות. 5. הוראות תהליך עבודה. איך אתה רוצה ש-Claude Code יפעל. "הרץ טסטים לפני סימון משימה כהושלמה." "כתוב העברת הקשר בסוף כל סשן." "היכנס למצב תכנון למשימות עם 3+ שלבים." 6. הפניות מרכזיות. מצביעים על מסמכים חשובים. "ראה docs/ARCHITECTURE.md לתכנון מערכת." "ראה .cursor/rules/ לכללי תבנית קבצים." מצביעים, לא עותקים - זה שומר על ה-CLAUDE.md רזה.

ANTI-PATTERN

טעויות נפוצות שהופכות קבצי CLAUDE.md לגרועים יותר: אל תדביק בלוקים גדולים של קוד. הם הופכים למיושנים כשהקוד משתנה. הצבע על הקובץ במקום: "ראה src/lib/auth.ts לתבנית האימות." אל תעלה מעבר ל-200 שורות. כל שורה צורכת טוקני הקשר. CLAUDE.md בן 500 שורות אוכל מהמקום הזמין לקוד ושיחה בפועל. אם צריך יותר פירוט, השתמש בתחביר @import לטעינת קבצים לפי דרישה. אל תכתוב הוראות מעורפלות. "כתוב קוד טוב" ו"עקוב אחרי שיטות עבודה מומלצות" חסרי משמעות ל-AI. הם מתפרשים אחרת בכל סשן. "השתמש ב-early returns במקום if-else מקוננים" ספציפי ועקבי. אל תשכפל תיעוד. אם יש לך CONTRIBUTING.md, הצבע עליו. אל תעתיק את תוכנו לתוך CLAUDE.md. מקור אמת אחד. אל תכלול סודות או משתני סביבה. CLAUDE.md נשלט בגרסאות. אם ה-build שלך צריך מפתחות API, אמור "הגדר OPENAI_API_KEY ב-.env" ולא את ערך המפתח בפועל.

CODE

CLAUDE.md תומך בייבוא קבצים אחרים עם תחביר @path/to/file. קבצים מיובאים מתרחבים inline כש-Claude Code טוען את ההקשר. השתמש ב-imports עבור: - מסמכי ארכיטקטורה: @docs/ARCHITECTURE.md - מוסכמות צוות: @docs/CONVENTIONS.md - תיעוד API: @docs/API.md זה שומר על CLAUDE.md של השורש רזה (מתחת ל-200 שורות) תוך מתן גישה ל-Claude לפניות מפורטות כשצריך. הקבצים המיובאים נטענים רק כש-CLAUDE.md מעובד, אז הם לא צורכים טוקנים עד שסשן מתחיל. תבנית שעובדת: שמור את CLAUDE.md כתוכן העניינים והשתמש ב-imports לפרקים. CLAUDE.md אומר "להוראות פריסה, ראה @docs/DEPLOY.md." Claude רואה את מסמך הפריסה המלא כשהוא צריך אותו.

PRO TIP

הדרך המהירה ביותר: פתח Claude Code בפרויקט שלך והרץ /init. הוא מייצר CLAUDE.md התחלתי על בסיס מבנה הפרויקט, package.json, וקבצי קונפיגורציה קיימים. סקור אותו, גזום את הדברים הגנריים, והוסף את ההוראות הספציפיות לפרויקט שלך. אם רוצים להתחיל מאפס, צור CLAUDE.md בתיקיית השורש של הפרויקט עם שלושת הסעיפים האלה: ## Build Commands npm install npm run dev npm run test npm run build ## Project Structure - src/ - קוד מקור של האפליקציה - tests/ - קבצי טסטים - docs/ - תיעוד ## Rules - הרץ טסטים לפני commit - השתמש ב-TypeScript strict mode - לעולם אל תקבל קבצי .env זה מספיק כדי להפוך את Claude Code למשמעותית יותר שימושי. אפשר להרחיב עם הזמן כשמבחינים בדפוסים - כל פעם ש-Claude Code עושה משהו לא נכון, הוסף כלל. כל פעם שמסבירים משהו מחדש, הוסף את זה לקובץ. ה-CLAUDE.md מתבשל עם השימוש, כמו מחבת ברזל יצוק.