AI
November 18, 2026
6 דקות קריאה

CLAUDE.md: איך לכתוב קובץ הוראות טוב ל-Claude Code

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

הקובץ CLAUDE.md הוא קובץ Markdown ש־Claude Code טוען בתחילת כל סשן. אפשר לחשוב עליו כחוזה בינכם לבין Claude: מה הוא חייב לדעת על הפרויקט כדי לא לטעות. הנה איך לכתוב אותו נכון.

העיקרון המרכזי: כתבו את מה שהקוד לא אומר

אין טעם לתאר ב־CLAUDE.md את מבנה התיקיות או את רשימת התלויות. את זה Claude רואה בעצמו. כתבו רק את מה שאי אפשר להסיק מהקוד.

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

ארבע רמות של CLAUDE.md

יש כמה מקומות שבהם אפשר לשים את הקובץ, והם מצטרפים זה לזה ולא דורסים זה את זה:

רמהמיקוםמי רואה
Managedמדיניות ארגונית (מנוהלת על ידי IT)כל הארגון
User~/.claude/CLAUDE.mdרק אתם, בכל הפרויקטים, רק במחשב הזה
Project./CLAUDE.md או ./.claude/CLAUDE.mdכל הצוות (נכנס ל־git)
Local./CLAUDE.local.mdרק אתם, בפרויקט הזה (ב־gitignore)

כל הרמות מחוברות יחד ל־prompt אחד. Claude עולה במעלה עץ התיקיות וטוען כל CLAUDE.md שהוא מוצא. קבצים בתתי־תיקיות נטענים רק כשעובדים עליהן.

מבנה מומלץ: פחות מ־200 שורות

הנה שלד שאפשר להתחיל ממנו:

# Project name
One or two sentences: what it is and who it is for.

## Stack
Only the unexpected parts (for example: "Postgres 17 with RLS, not Prisma").

## Conventions
What you would comment on in a Code Review.

## Always
- Run `pnpm test` before finishing.

## Never
- Do not edit `migrations/` by hand.

## Gotchas
- `config.ts` is loaded twice in dev. This is intentional.

הסעיף "לעולם לא" הוא לפי המדריך הסעיף הכי שווה, כי הוא נולד מכשלונות אמיתיים. כל פעם ש־Claude עשה משהו שלא רציתם, זו הזדמנות להוסיף שורה אחת לשם.

ייבוא קבצים עם @

כשהמידע ארוך מדי לגוף הקובץ, אפשר לייבא קובץ אחר:

@docs/architecture.md
@~/.claude/my-preferences.md
  • @path/to/file נפרש במלואו בעת ההפעלה.
  • אפשר לקנן עד 4 רמות של ייבוא.
  • הייבוא שורד /compact: הוא נטען מחדש אחרי דחיסה.

חוקים מותנים עם .claude/rules/

ייבוא עם @ נטען תמיד. אם חוק רלוונטי רק לחלק מהקוד, שימו אותו בתיקייה .claude/rules/ עם paths: בכותרת הקובץ:

---
paths:
  - "src/api/**/*.ts"
---
# API rules
- Every endpoint returns `{ data, error }`.

החוק נטען רק כש־Claude נוגע בקבצים שמתאימים לתבנית. מגרסה 2.1.285 חוקים כאלה נטענים גם בעריכה וכתיבה (Write/Edit), ולא רק בקריאה.

פקודות שעוזרות

  • /init: יוצר CLAUDE.md ראשוני. הוא נוטה לתאר את מה שכבר רואים בקוד, ולכן ערכו ומחקו בלי רחמים. הגדרת CLAUDE_CODE_NEW_INIT=1 מפעילה גרסה אינטראקטיבית שעוברת גם על Skills ו־Hooks.
  • /memory: פותח את קבצי ה־CLAUDE.md לעריכה.
  • /doctor prompt-audit (חדש בגרסה 2.1.283): בודק את CLAUDE.md, ה־Skills וה־Agents ומסמן דפוסי prompting מיושנים. שווה להריץ אחרי כל שדרוג מודל.
  • /import codex|gemini|cursor: מביא קבצי הוראות, MCP ופקודות מ־Codex, מ־Gemini CLI או מ־Cursor.

צ'קליסט קצר לפני שמסיימים

  1. הקובץ קצר מ־200 שורות.
  2. כל שורה עוברת את המבחן: Claude היה טועה בלעדיה.
  3. יש סעיף "לעולם לא" שנולד מטעויות אמיתיות.
  4. חוקים שרלוונטיים רק לחלק מהקוד עברו ל־.claude/rules/ עם paths:.
  5. העדפות אישיות נמצאות ב־User או ב־Local, לא ב־Project שכל הצוות רואה.

אפשר גם לבקש מ־Claude להסביר קוד שירשתם: הפערים שהוא מגלה הם שורות חדשות ל־CLAUDE.md.

התחלה מהירה בארבעה צעדים

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

  1. /init: יוצר CLAUDE.md ראשוני. ערכו אותו והשאירו רק את מה שהקוד לא אומר.
  2. /context: ראו מה באמת נטען לחלון ההקשר.
  3. Shift+Tab: מחליף בין מצבי הרשאות (ברירת המחדל עכשיו: auto).
  4. לשינוי בכמה קבצים, התחילו ב־/plan.

דוגמה: שורה שכדאי לשמור מול שורה שכדאי למחוק

שורה כמו "הפרויקט כתוב ב־TypeScript ויש בו תיקיית src" היא מידע ש־Claude רואה בעצמו, ולכן אפשר למחוק אותה. לעומת זאת שורה כמו "Postgres 17 עם RLS, לא Prisma" היא בדיוק מהסוג שמונע טעות, כי אי אפשר להניח אותה מראש. אותו דבר לגבי "לא לגעת ב־migrations/ ידנית": זו הוראה שנולדה מכשלון, והיא שווה את הטוקנים.

שתי פעולות מתוך רשימת "עשרה דברים לעשות השבוע" במדריך נוגעות ישירות לנושא: לקצץ את CLAUDE.md לפחות מ־200 שורות, ולהעביר חוקים מותנים ל־.claude/rules/ עם paths:.

כדאי לזכור גם שהקובץ הוא מסמך חי. הוא לא נכתב פעם אחת ונשכח: כל כשל חוזר של Claude הוא סימן לשורה שחסרה, וכל שורה שכבר לא מונעת טעויות היא מועמדת למחיקה. בדיקה תקופתית עם /doctor prompt-audit, במיוחד אחרי שדרוג מודל, עוזרת לתפוס הוראות מיושנות.

את המדריך המלא, בחינם ובעברית, אפשר למצוא ב־GitHub או בגרסת האתר: https://tovtechorg.github.io/Claude-Code-in-Hebrew/.