2.5 CLAUDE.md והקשר הפרויקט הרצאה
לאורך הפרק חזרנו על עובדה אחת: כל סשן של Claude Code מתחיל עם context window נקי. הagent לא זוכר את השיחה של אתמול, לא זוכר שהעדפתם pnpm על npm, ולא זוכר איך מריצים את הבדיקות בפרויקט הזה. בכל סשן חדש הוא מתחיל מאפס. זו בעיה מעשית: אתם לא רוצים להסביר מחדש כל בוקר את אותם דברים. הפתרון הוא CLAUDE.md - קובץ טקסט פשוט שהagent קורא בתחילת כל סשן, ושבו כותבים את מה שהייתם צריכים אחרת לחזור עליו שוב ושוב. בהרצאה הזו נבין מה הקובץ הזה, מה שמים בו, איך הוא מכוון את הagent, ההבדל בין זיכרון פרויקט לזיכרון משתמש, ואיך לשמור אותו רזה.
מה זה CLAUDE.md - project memory¶
CLAUDE.md הוא קובץ Markdown שאתם כותבים כדי לתת לagent prompts קבועים. אתם כותבים אותו בטקסט רגיל; Claude קורא אותו בתחילת כל שיחה וטוען אותו לתוך context window. במילים אחרות, זו הדרך להפוך ידע חד-פעמי לידע קבוע: במקום להסביר בכל סשן איך בנוי הפרויקט, כותבים את זה פעם אחת בקובץ, והagent יידע את זה תמיד.
נקודה חשובה להבנה נכונה: CLAUDE.md הוא context, לא אכיפה. הוא נטען כהודעה לagent, לא ככלל שנאכף על ידי המערכת. הagent קורא אותו ומנסה לעקוב אחריו, אבל אין ערובה לציות מוחלט, במיוחד לprompts מעורפלים או סותרים. אם צריך לחסום פעולה באופן מוחלט - זה תפקידם של כללי deny בהרשאות או של hooks, לא של CLAUDE.md. הקובץ מעצב התנהגות; הוא לא שולט בה בכוח.
מה שמים בו - what to put in it¶
הכלל הפשוט: שימו בו את מה שהייתם צריכים אחרת להסביר מחדש. התיעוד ממליץ להוסיף ל-CLAUDE.md כשקורה אחד מאלה: הagent חזר על אותה טעות פעם שנייה, סקירת קוד תפסה משהו שהוא היה צריך לדעת, אתם מקלידים שוב את אותו תיקון שהקלדתם בסשן הקודם, או שעמית חדש היה זקוק לאותו context כדי להיות פרודוקטיבי.
בפועל, ארבע קטגוריות ממלאות את רוב הקבצים:
- פקודות בנייה והרצה: איך מריצים את הבדיקות, איך בונים, איך מריצים את הtool מקומית. אלה דברים שהagent מנחש אחרת, ולפעמים מנחש לא נכון.
- מוסכמות: סגנון קוד, כללי מתן שמות, פורמט הודעות commit, שפת התיעוד.
- הערות ארכיטקטורה: איפה נמצא מה, איך הרכיבים מתחברים, החלטות עיצוב מרכזיות.
- כללי עשה ואל תעשה: "תמיד הרץ lint לפני commit", "אף פעם אל תדחוף ישירות ל-main", "השתמש ב-async/await, לא ב-callbacks".
הכלל לניסוח: כתבו הprompts ספציפיים ובני אימות. "השתמש בהזחה של שני רווחים" עדיף על "עצב את הקוד יפה". "הרץ npm test לפני commit" עדיף על "בדוק את השינויים". ככל שהprompt קונקרטי יותר, כך הagent עוקב אחריו בעקביות רבה יותר.
איפה הקובץ יושב - זיכרון פרויקט מול זיכרון משתמש¶
יש כמה מיקומים אפשריים ל-CLAUDE.md, וכל אחד עם היקף שונה. שני החשובים ביותר הם זיכרון פרויקט וזיכרון משתמש:
| היקף | מיקום | מטרה | משותף עם |
|---|---|---|---|
| הprompts משתמש | ~/.claude/CLAUDE.md |
העדפות אישיות לכל הפרויקטים | רק אתם |
| הprompts פרויקט | ./CLAUDE.md או ./.claude/CLAUDE.md |
הprompts משותפים לצוות | הצוות דרך git |
| הprompts מקומיים | ./CLAUDE.local.md |
העדפות אישיות לפרויקט זה | רק אתם (הוסיפו ל-gitignore) |
ההבחנה המרכזית: זיכרון פרויקט (./CLAUDE.md) נכנס ל-git ומשותף לכל הצוות - שמים בו את מה שנכון לכל מי שעובד על הפרויקט: ארכיטקטורה, פקודות בנייה, מוסכמות. זיכרון משתמש (~/.claude/CLAUDE.md) הוא אישי וחל על כל הפרויקטים שלכם - שמים בו העדפות אישיות, כמו סגנון תגובה שאתם מעדיפים או קיצורי דרך של הtools שלכם. יש גם מדיניות ארגונית ברמת המערכת, אבל בה נוגעים מנהלי IT.
כשיש כמה קבצים, כולם נטענים ומשורשרים יחד. הסדר הוא מהיקף רחב לצר: הprompts משתמש נטענים לפני prompts פרויקט, כך שprompt ספציפי לפרויקט מופיע בcontext אחרי הprompt האישי. הקובץ המקומי CLAUDE.local.md מיועד להעדפות פרטיות שלא נכנסות ל-git, ולכן יש להוסיף אותו ל-.gitignore.
איך הקובץ מכוון את הagent - how it steers¶
בגלל ש-CLAUDE.md נטען לתחילת כל סשן, הוא משפיע על כל החלטה שהagent מקבל. נראה דוגמה. נניח שאין קובץ, ואתם מבקשים "הרץ את הבדיקות". הagent ינחש - אולי ינסה pytest, אולי python -m unittest, ואם הפרויקט משתמש במשהו אחר הוא ייכשל וינסה שוב. עכשיו נניח שב-CLAUDE.md כתוב:
## Tests
- Run the tests with: make test
- The tests require a local Redis instance running on port 6379
עכשיו הagent יריץ make test ישר, ואם Redis לא רץ הוא יידע שזו הסיבה. חסכתם לו סבב ניחוש שלם. זה הכוח של הקובץ: הוא ממיר ידע שהיה חבוי בראש שלכם למידע שהagent פועל לפיו מהצעד הראשון.
עוד דוגמה לכלל "אל תעשה": אם כתוב "אף פעם אל תדחוף ישירות ל-main, תמיד פתח ענף", הagent יפתח ענף מעצמו כשתבקשו commit, במקום לדחוף ל-main ולגרום לכם לתקן בדיעבד.
דוגמה מציאותית - a realistic CLAUDE.md¶
הנה איך נראה CLAUDE.md מלא וריאלי לפרויקט Node.js קטן. שימו לב לכותרות, לתמציתיות, ולספציפיות:
# CLAUDE.md
## What this project is
A user-management API built on Express and PostgreSQL.
Entry point: src/server.js.
## Commands
- Install: npm install
- Run locally: npm run dev
- Tests: npm test (requires a local DB, see docker-compose.yml)
- Style check: npm run lint
## Structure
- src/routes/ - route definitions
- src/services/ - business logic
- src/db/ - queries and schema
- A new route always goes through a service, never accesses the DB directly
## Conventions
- Two-space indentation
- Variable names in camelCase, constants in UPPER_SNAKE
- Every endpoint must validate input with zod
## Do and don't
- Run npm run lint before every commit
- Never push directly to main, open a feature branch
- Don't add new dependencies without asking first
הקובץ הזה קצר - פחות מ-30 שורות - וזה בכוונה. כל שורה בו קונקרטית ושימושית. הוא נותן לagent בדיוק את מה שהוא צריך כדי לעבוד נכון בפרויקט מהצעד הראשון.
ליצור ולתחזק את הקובץ - creating and maintaining¶
לא צריך לכתוב את הקובץ מאפס. הפקודה /init בתוך סשן מייצרת CLAUDE.md התחלתי אוטומטית: הagent מנתח את בסיס הקוד ויוצר קובץ עם פקודות בנייה, הוראות בדיקה ומוסכמות שהוא מגלה. אם כבר קיים CLAUDE.md, /init מציע שיפורים במקום לדרוס. משם מעדנים ידנית ומוסיפים דברים שהagent לא יכול לגלות לבד.
לצפייה ועריכה של הקבצים הטעונים, הפקודה /memory מציגה את כל קבצי ה-CLAUDE.md הטעונים בסשן ומאפשרת לפתוח כל אחד לעריכה. אם תרצו להוסיף משהו לזיכרון תוך כדי עבודה, אפשר פשוט לבקש מ-Claude "תוסיף את זה ל-CLAUDE.md", והוא יכתוב עבורכם.
עוד מנגנון ששווה להכיר בשמו: זיכרון אוטומטי - auto memory. זהו זיכרון שהagent מנהל בעצמו, ובו הוא שומר לעצמו למידות תוך כדי עבודה - פקודות בנייה שגילה, תובנות ניפוי, העדפות שלכם. ההבדל: CLAUDE.md כותבים אתם ומכיל prompts; זיכרון אוטומטי כותב הagent ומכיל למידות. שניהם נטענים בתחילת כל סשן. גם את הזיכרון האוטומטי אפשר לצפות ולערוך דרך /memory.
ייבוא קבצים - imports¶
לפעמים רוצים לפצל את הprompts לכמה קבצים במקום לדחוס הכל לקובץ אחד. CLAUDE.md תומך בייבוא של קבצים נוספים בתחביר @path/to/file. הקבצים המיובאים מורחבים ונטענים לcontext בתחילת הסשן לצד הקובץ הראשי. למשל:
See @README for a description of the project and @package.json for available commands.
# Additional prompts
- Git workflow @docs/git-instructions.md
שימו לב לפרט חשוב: כדי להזכיר נתיב בלי לייבא אותו, עוטפים אותו בגרשיים אחוריים. כתיבת הנתיב בגרשיים אחוריים משאירה אותו כטקסט; אותו נתיב מחוץ לגרשיים מייבא את הקובץ. הבחנה זו מונעת ייבוא בשוגג של קבצים שרק רציתם להזכיר בשמם.
הערה שימושית: הייבוא חוסך ארגון, אבל לא חוסך context - הקבצים המיובאים נטענים במלואם בתחילת הסשן, בדיוק כמו לו כתבתם אותם בקובץ הראשי. לכן ייבוא הוא כלי לסדר, לא לחיסכון בtokens. אם המטרה היא לחסוך context, המנגנון הנכון הוא כלל ממוקד-נתיב שנטען רק כשעובדים על קבצים תואמים.
עוד נקודה מעשית: אם הrepo שלכם כבר משתמש בקובץ AGENTS.md עבור tool agent אחר, Claude Code קורא CLAUDE.md ולא AGENTS.md. הפתרון הפשוט הוא ליצור CLAUDE.md שמייבא את השני עם @AGENTS.md, כך ששני הtools יקראו את אותם prompts בלי לשכפל אותם.
מה שורד דחיסת context - surviving compaction¶
בשיחות ארוכות, context window מתמלא, ו-Claude Code דוחס אותו אוטומטית - מנקה פלט ישן ומסכם את השיחה. תהליך זה עלול לאבד prompts שנאמרו רק בצ'אט מוקדם בשיחה. כאן CLAUDE.md מראה יתרון נוסף: הקובץ בשורש הפרויקט שורד דחיסה - אחרי דחיסה, Claude קורא אותו מחדש מהדיסק ומזריק אותו שוב לסשן.
המסקנה המעשית: אם יש prompt שאתם רוצים שיישאר בתוקף לאורך שיחה ארוכה, אל תסתפקו לומר אותו בצ'אט - כתבו אותו ב-CLAUDE.md. prompt שנאמר רק בשיחה עלול להיעלם בדחיסה; prompt שכתוב בקובץ חוזר תמיד. זו עוד סיבה למה הקובץ הוא הכלי הנכון לכללים קבועים, בעוד הצ'אט מתאים להוראות נקודתיות לסשן הנוכחי.
לשמור אותו רזה - keeping it lean¶
CLAUDE.md נטען לcontext window בתחילת כל סשן, וצורך tokens לצד השיחה שלכם. יש לכך שתי השלכות. ראשית, קובץ ארוך גוזל context יקר. שנית, וזה פחות אינטואיטיבי, קובץ ארוך פוגע בציות: ככל שהקובץ ארוך יותר, כך הagent עוקב אחריו בפחות עקביות. התיעוד ממליץ לשאוף לפחות מ-200 שורות לקובץ.
לכן, הכלל: שמרו בקובץ רק עובדות שהagent צריך להחזיק בכל סשן - פקודות, מוסכמות, מבנה, כללי "תמיד". אם הכנסתם תהליך רב-שלבי, או משהו שרלוונטי רק לחלק אחד מהקוד, הוא לא שייך ל-CLAUDE.md הראשי. לפריטים כאלה יש מנגנונים ייעודיים: הskill - לתהליך שנטען לפי דרישה, או כלל ממוקד-נתיב שנטען רק כשעובדים על קבצים תואמים. את אלה נלמד בהמשך; לעת עתה, מספיק לזכור שהקובץ הראשי צריך להישאר רזי.
עוד עצה: בדקו את הקובץ מדי פעם והסירו prompts מיושנים או סותרים. אם שני prompts סותרים זה את זה, הagent עלול לבחור אחד באופן שרירותי. קובץ נקי ועקבי עדיף על קובץ עמוס.
סיכום¶
- CLAUDE.md הוא קובץ Markdown שהagent קורא בתחילת כל סשן. הוא ממיר ידע חד-פעמי לcontext קבוע, כי כל סשן מתחיל אחרת מאפס.
- הקובץ הוא context, לא אכיפה. הוא מעצב התנהגות אבל לא מבטיח ציות; לחסימה מוחלטת משתמשים בכללי
denyאו ב-hooks. - שמים בו פקודות בנייה והרצה, מוסכמות, הערות ארכיטקטורה, וכללי עשה/אל תעשה, בניסוח ספציפי ובר-אימות.
- זיכרון פרויקט (
./CLAUDE.mdאו./.claude/CLAUDE.md) נכנס ל-git ומשותף לצוות; זיכרון משתמש (~/.claude/CLAUDE.md) אישי וחל על כל הפרויקטים;CLAUDE.local.mdלהעדפות פרטיות (הוסיפו ל-gitignore). - הקובץ מכוון את הagent מהצעד הראשון: הוא חוסך סבבי ניחוש ומכתיב כללי עשה/אל תעשה.
- יוצרים קובץ התחלתי עם
/init, צופים ועורכים עם/memory, ואפשר לבקש מ-Claude להוסיף לו. זיכרון אוטומטי הוא מנגנון משלים שהagent מנהל בעצמו. - שומרים אותו רזה - מתחת ל-200 שורות. קובץ ארוך גוזל context ופוגע בציות. תהליכים ארוכים או ממוקדי-נתיב שייכים ל-skills או לכללים, לא לקובץ הראשי.