CLAUDE.md — המוח של הפרויקט שלך

מה זה CLAUDE.md — ולמה זה Game Changer

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

זה מתסכל, זה בזבוז זמן, וזה גורם לתוצאות פחות טובות. אם Claude לא יודע שהפרויקט שלכם משתמש ב-TypeScript ולא JavaScript, הוא ייצור קבצי JavaScript. אם הוא לא יודע שהתיקייה src/components/ היא המקום הנכון לקומפוננטות, הוא יכתוב אותן במקום הלא נכון. אם הוא לא יודע שהדיפלוי שלכם הוא דרך Vercel, הוא יציע פתרונות שלא רלוונטיים.

CLAUDE.md פותר את הבעיה הזאת לגמרי.

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

אבל בניגוד לעובד אנושי שיתעצבן מלקרוא אותו דבר כל יום, Claude עושה את זה בשמחה ובמילישניות. והתוצאה? במקום 5-10 דקות של "הכנסה לעניינים" בתחילת כל סשן, אתם מתחילים לעבוד מיד. אם אתם פותחים 3-4 סשנים ביום, זה 20-40 דקות שנחסכות כל יום.

השם רגיש לאותיות גדולות (case-sensitive) ב-Linux, אז חשוב שיהיה בדיוק CLAUDE.md — עם כל האותיות גדולות. ב-Mac ו-Windows זה פחות קריטי, אבל הרגל טוב הוא תמיד להשתמש בשם המדויק. הקובץ ממוקם בתיקיית השורש (root) של הפרויקט שלכם — באותו מקום שבו יש package.json או requirements.txt.

מה קורה בלי CLAUDE.md?

בלי CLAUDE.md, כל סשן מתחיל כך:

• Claude לא יודע מה הפרויקט עושה — הוא צריך לסרוק קבצים כדי לנחש
• Claude לא מכיר את ה-tech stack — הוא עלול לבחור שפה או framework לא נכונים
• Claude לא יודע את הקונבנציות שלכם — camelCase או snake_case? Tabs או spaces?
• Claude לא מכיר פקודות חשובות — npm run dev או yarn dev? Port 3000 או 8080?
• Claude לא יודע מה אסור לעשות — "לעולם אל תמחק קבצי מיגרציה" או "אל תשנה את ה-API key"
• Claude לא יודע על Gotchas — באגים ידועים, workarounds, והחלטות עיצוב מפתיעות

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

מה קורה עם CLAUDE.md?

עם CLAUDE.md, כל סשן מתחיל כך:

• Claude כבר יודע שהפרויקט הוא "אתר שיווקי ב-Next.js 15 עם Supabase"
• Claude יודע שהסגנון הוא TypeScript + Tailwind CSS
• Claude מכיר את הפקודה npm run dev ויודע שהשרת עולה על port 3000
• Claude יודע שהתוכן צריך להיות בעברית, עם מונחים מקצועיים באנגלית
• Claude יודע שאסור לשנות קבצי .env ולמחוק מיגרציות

ההבדל הוא דרמטי. במקום 5 דקות של "הסבר מי אתה", מתחילים ישר עם "תעשה לי X". וה-X הזה יהיה מדויק יותר, כי Claude מבין את ההקשר.

אבולוציה של CLAUDE.md — דוגמה אמיתית

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

# Digital Agency Website

## Stack
- WordPress + Elementor
- WooCommerce for shop
- Hebrew content, RTL layout

## Commands
- Dev: Local by Flywheel
- Deploy: WP Engine Git Push

# Digital Agency Website

## Stack
- WordPress 6.5 + Elementor Pro 3.21
- WooCommerce 9.x for shop
- Hebrew content, RTL layout
- PHP 8.2, MySQL 8

## Commands
- Dev: Local by Flywheel (port 10008)
- Deploy: WP Engine Git Push (branch: main)
- Test: `wp theme unit-test` + manual QA

## Rules
- NEVER edit theme files directly — use child theme
- All CSS goes in child-theme/style.css, not inline
- Hebrew text: use native Hebrew, not Google Translate
- Images: always WebP, max 200KB

## Gotchas
- WooCommerce cart breaks if caching plugin is active — disable for /cart and /checkout
- Elementor widgets lose styling after import — always re-check colors
- The "שירותים" page uses a custom template — services-page.php

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

ההיררכיה — Global, Project ו-Rules

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

רמה 1: Global CLAUDE.md — ההעדפות האישיות שלך

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

• "תענה תמיד בעברית להסברים"
• "אל תמחק קבצים בלי לשאול"
• "אני מעדיף תשובות קצרות וענייניות"
• "תמיד תשתמש ב-TypeScript ולא JavaScript"

הקובץ הגלובלי לא נשמר ב-Git — הוא אישי שלכם, נשאר על המחשב שלכם בלבד. חשבו עליו כמו "פרופיל ברירת מחדל" שלכם. הוא בדרך כלל קטן (20-50 שורות) ומכיל רק העדפות שרלוונטיות לכם כאדם — לא לפרויקט מסוים. אם עובדים על כמה מחשבים, תצטרכו להעתיק את הקובץ ידנית או לנהל אותו דרך dotfiles.

רמה 2: Project CLAUDE.md — ההקשר של הפרויקט

הקובץ ./CLAUDE.md בתיקיית השורש של הפרויקט חל רק על הפרויקט הזה. זה המקום להקשר טכני ומקצועי ספציפי:

• מה הפרויקט עושה
• מה ה-tech stack (שפות, frameworks, שירותים)
• מבנה התיקיות
• פקודות חשובות (build, test, deploy)
• כללים וקונבנציות ספציפיות
• דברים שנפוץ לטעות בהם (Gotchas)

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

רמה 3: .claude/rules/ — חוקים מודולריים

תיקיית .claude/rules/ מאפשרת לכם לפצל את ההוראות לקבצים נפרדים, כל אחד מתמקד בנושא אחד. כל קבצי ה-.md בתיקייה הזו נטענים אוטומטית — בדיוק כמו CLAUDE.md, בלי שום הגדרה נוספת. זה שימושי במיוחד כשה-CLAUDE.md שלכם מתחיל להתנפח ואתם רוצים סדר. היתרון הגדול: אפשר לטעון חוקים רק כשעובדים עם סוגי קבצים מסוימים (Python rules רק כשפותחים קובץ Python, למשל). נדבר על זה בהרחבה בסעיף הייעודי.

סדר העדיפויות — מי גובר על מי?

כשיש סתירה בין הרמות, מי מנצח? הכלל הוא הספציפי גובר על הכללי, וההוראה האחרונה גוברת:

דוגמה מעשית: ב-Global CLAUDE.md כתבתם "Always respond in Hebrew". ב-Project CLAUDE.md כתבתם "Code comments in English". ובשיחה אתם אומרים "answer this specific question in English". מה יקרה? Claude יענה לשאלה הזו באנגלית (שיחה גוברת), אבל בהמשך יחזור לעברית (Global) עם הערות בקוד באנגלית (Project). כל שכבה מטפלת בתחום שלה, ואין סתירה אמיתית.

# My Preferences

- Always respond in Hebrew for explanations
- Never delete files without asking first
- I prefer concise, actionable responses
- When creating code, always use TypeScript
- Show me the command before running it

פקודת /init — הגדרה אוטומטית בשנייה

לא רוצים לכתוב CLAUDE.md מאפס? לא בטוחים מה לכלול? יש קיצור דרך מבריק: הפקודה /init.

כשאתם מריצים /init בתוך Claude Code, הוא מנתח את הפרויקט שלכם — קורא את מבנה התיקיות, בודק קבצי תצורה כמו package.json, requirements.txt, Dockerfile, קורא את ה-README אם יש, ובודק את היסטוריית Git האחרונה. מכל המידע הזה הוא בונה CLAUDE.md מותאם אישית.

/init חכם מספיק לזהות:

• סוג הפרויקט: Python, JavaScript, Go, Rust ועוד
• Frontend מול Backend מול Fullstack
• Monorepo מול שירות בודד
• כלי build ו-test (npm, pip, cargo, docker)
• פרויקטים שאינם קוד — תוכן, נתונים, שיווק

מה /init מייצר — דוגמה מעשית

כדי שתבינו מה לצפות, הנה דוגמה של מה ש-/init מייצר כשמריצים אותו על פרויקט Next.js טיפוסי:

# my-shop

## Overview
E-commerce web application built with Next.js.

## Tech Stack
- Framework: Next.js 15 (App Router)
- Styling: Tailwind CSS
- Database: Supabase (PostgreSQL)
- Language: TypeScript
- Package manager: npm

## Project Structure
- src/app/ — App Router pages and layouts
- src/components/ — React components
- src/lib/ — Utility functions
- public/ — Static assets

## Development
- `npm run dev` — Start dev server (localhost:3000)
- `npm run build` — Production build
- `npm test` — Run tests
- `npm run lint` — Lint check

## Key Files
- src/app/layout.tsx — Root layout
- src/lib/supabase.ts — Supabase client
- tailwind.config.ts — Tailwind configuration

שימו לב למה /init מצא: את ה-tech stack, את מבנה התיקיות, ואת הפקודות. לא רע בכלל — זה חוסך הרבה עבודה. אבל מה חסר? כללים (Rules), מלכודות (Gotchas), הקשר עסקי (מי קהל היעד, מה המוצר), שפה מועדפת (עברית?), ותבניות עיצוב (Brand Voice). את כל אלה אתם צריכים להוסיף ידנית — וזה בדיוק ה-30% שהופכים CLAUDE.md טוב למצוין. הנה תהליך מעשי:

1. הריצו /init — קבלו את הבסיס האוטומטי
2. הוסיפו "What This Project Does" — 2-3 משפטים על המטרה העסקית
3. הוסיפו Rules — לפחות 3-5 כללים קריטיים
4. הוסיפו Gotchas — לפחות 1-2 מלכודות ידועות
5. מחקו שורות לא רלוונטיות — לפעמים /init מוסיף דברים שלא צריך

התהליך הזה לוקח בדרך כלל 5-10 דקות, ונותן לכם CLAUDE.md שהוא 90%+ מדויק ושימושי.

כתיבת CLAUDE.md מושלם — התבנית המוזהבת

בין אם התחלתם מ-/init ובין אם מדף לבן, הנה המבנה שכדאי לכל CLAUDE.md לעקוב אחריו. זו "התבנית המוזהבת" (Golden Template) — מוכחת, קלה לשימוש, ועובדת לכל סוג פרויקט.

# Project Name

## What This Project Does
[2-3 sentences about the project's purpose]

## Tech Stack / Tools
- [Tool/framework 1]
- [Tool/framework 2]
- [Key services or platforms]

## Key Structure
- [Main directories and what they contain]
- [Important files and their roles]

## Common Commands
- Dev: `command here`
- Test: `command here`
- Build: `command here`
- Deploy: `command here`

## Rules
- [Critical do's and don'ts]
- [Conventions to follow]
- [Things to NEVER do]

## Gotchas
- [Non-obvious things that cause confusion]
- [Previous decisions and WHY they were made]
- [Known issues to work around]

בואו נפרק כל סעיף ונבין למה הוא חשוב:

What This Project Does — מה הפרויקט עושה

2-3 משפטים שנותנים ל-Claude את ה"תמונה הגדולה". בלי זה, Claude רואה קבצים אבל לא מבין את ההקשר העסקי. כשהוא יודע שזה "אתר חנות אופנה אונליין שפונה לנשים 25-40", הוא יכתוב קוד אחר ממה שהוא יכתוב לפרויקט "דשבורד ניהול פנימי לצוות DevOps".

Tech Stack — מה משתמשים בו

רשימה מדויקת של הכלים, השפות, ה-frameworks והשירותים. ציינו גרסאות כשזה רלוונטי — "Next.js 15" ולא רק "Next.js", כי יש הבדלים משמעותיים בין גרסאות. אם משתמשים בשירותי ענן — ציינו אותם: Vercel, Supabase, AWS וכו'.

Key Structure — מבנה התיקיות

Claude יכול לסרוק את התיקיות בעצמו, אבל לומר לו מראש חוסך זמן ומונע טעויות. במיוחד חשוב לציין תיקיות שאינן אינטואיטיביות — "הקומפוננטות המשותפות נמצאות ב-src/shared/ ולא ב-src/components/".

Common Commands — פקודות חשובות

פקודות ה-dev, test, build ו-deploy. Claude ישתמש בפקודות האלה כשהוא צריך להריץ, לבדוק, או לבנות דברים. בלי הסעיף הזה, הוא ינחש — ולפעמים ינחש לא נכון. למשל, אם אתם משתמשים ב-pnpm ולא npm, ציינו את זה כאן. אם יש פקודת lint מיוחדת, הוסיפו אותה. אם ה-deploy עובר דרך script מותאם אישית — תעדו את הפקודה המדויקת, לא "deploy to server".

Rules — כללים

זה הסעיף הקריטי ביותר — ה-"do's and don'ts" שמגדירים מה מותר, מה אסור, ומה חובה. כללים טובים הם ספציפיים ואכיפים. הנה דוגמאות לכללים אפקטיביים:

• "Always use TypeScript (.ts/.tsx), never JavaScript (.js/.jsx)"
• "Never modify existing migration files — always create new ones"
• "All user-facing text must be in Hebrew. Code comments in English"
• "Test every new component before committing. Run: npm test -- --related"
• "Use kebab-case for file names (my-component.tsx), PascalCase for React components (MyComponent)"
• "API routes must validate input with Zod schemas"
• "Never commit directly to main — always use feature branches"

שימו לב: כל כלל ברשימה הזו ספציפי, ברור, ואפשר לאכוף אותו. השוו את זה ל"כתוב קוד נקי" — שזה גנרי, לא אכיף, ובזבוז טוקנים. Claude כבר כותב קוד נקי כברירת מחדל. מה שהוא צריך מכם זה ההנחיות הספציפיות שלא יכול לנחש לבד.

Gotchas — מלכודות

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

• "The API on port 3001 requires CORS headers — don't forget them"
• "We use a custom date format (DD/MM/YYYY), not the US format"
• "The 'users' table has a soft-delete — never use DELETE, use UPDATE with deleted_at"

הגודל הנכון — Sweet Spot

שאלה שעולה הרבה: כמה ארוך צריך להיות CLAUDE.md? יש sweet spot:

כלל אצבע: אם אתם לא יכולים לקרוא את ה-CLAUDE.md שלכם בדקה אחת — הוא ארוך מדי. קצרו, פצלו, או העבירו חלקים ל-.claude/rules/.

תבניות לסוגי פרויקטים שונים

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

תבנית A: פרויקט שיווק ותוכן

# [Brand] Content Project

## Brand Voice
- Tone: Professional but approachable
- Avoid: Jargon, passive voice, clickbait
- Target audience: [description]

## Content Types
- Blog posts: 800-1200 words, SEO-optimized
- Social media: Short, punchy, with CTA
- Email: Personal tone, clear subject lines

## SEO Guidelines
- Primary keyword in H1 and first paragraph
- 2-3 secondary keywords naturally distributed
- Meta description: 155 characters max

## Rules
- All content in Hebrew unless specified otherwise
- Always include a call-to-action
- Never use competitor brand names
- Images should have descriptive alt text in Hebrew

שימו לב: בפרויקט שיווקי, חשוב לציין את ה-Brand Voice (טון המותג), קהל היעד, ואילוצי SEO. Claude יתאים את הסגנון למה שכתבתם כאן. אם כתבתם "professional but approachable" — התוכן יהיה שונה מ-"casual and fun".

תבנית B: פרויקט פיתוח ווב

# [App Name]

## Stack
- Frontend: Next.js 15 + Tailwind CSS
- Backend: Supabase (PostgreSQL)
- Auth: Supabase Auth
- Deploy: Vercel

## Commands
- Dev: `npm run dev` (localhost:3000)
- Test: `npm test`
- Build: `npm run build`
- Deploy: `git push origin main` (auto-deploys via Vercel)

## Structure
- src/app/ — Next.js App Router pages
- src/components/ — Reusable React components
- src/lib/ — Utility functions and Supabase client
- supabase/migrations/ — Database migration files

## Rules
- Use TypeScript, never JavaScript
- Components in src/components/, pages in src/app/
- Test every new component before committing
- Never modify existing migration files — create new ones
- All user-facing text in Hebrew

## Gotchas
- Supabase client must be initialized from src/lib/supabase.ts
- Dev server sometimes needs restart after .env changes
- Tailwind classes must use the custom color palette in tailwind.config.ts

תבנית C: פרויקט ניתוח נתונים

# Data Analysis Project

## Data Sources
- Main dataset: data/sales_2024.csv (date, product, amount, region)
- Reference: data/products.csv (product catalog)
- External: Google Sheets via API (monthly sync)

## Tools
- Python 3.11, pandas, matplotlib, seaborn
- Output format: markdown reports in reports/
- Charts saved as PNG in charts/

## Conventions
- Currency: ILS, format with 2 decimals
- Date format: DD/MM/YYYY (Israeli standard)
- Charts: Use Hebrew labels when possible
- Column names: snake_case in English

## Rules
- Never overwrite raw data files in data/
- Always create backup before transformations
- Every analysis script must have a docstring
- Save intermediate results in data/processed/

מה לא לשים ב-CLAUDE.md

יודעים מה חשוב כמו מה כן לשים ב-CLAUDE.md? לדעת מה לא לשים שם. הנה הרשימה השחורה:

1. סודות ופרטי גישה — לעולם לא

אף פעם אל תשימו ב-CLAUDE.md: API keys, סיסמאות, tokens, connection strings, או כל מידע רגיש אחר. הסיבה פשוטה ומפחידה: CLAUDE.md נשמר ב-Git, ו-Git זוכר הכל — גם אם תמחקו את המידע בקומיט הבא, הוא נשאר בהיסטוריה לנצח. כל מי שיש לו גישה ל-repo יכול למצוא אותו בעזרת git log. השתמשו בקבצי .env (שנמצאים ב-.gitignore) או מנהל סודות (secrets manager) כמו Vault, AWS Secrets Manager, או Cloudflare KV.

2. לוגים ודמפים ארוכים

אל תדביקו ב-CLAUDE.md הודעות שגיאה שלמות או לוגים ארוכים. אם יש בעיה חוזרת, תמצתו אותה ל-1-2 משפטים. למשל, במקום 50 שורות של stack trace, כתבו: "Known issue: The auth middleware sometimes throws CORS errors when running locally. Fix: restart the dev server."

3. הוראות מובנות מאליהן

אל תכתבו "כתוב קוד נקי" או "היה מועיל". Claude כבר עושה את זה. הוראות גנריות מדי רק מבזבזות טוקנים. במקום זאת, היו ספציפיים: "Use early returns instead of nested if-else", "Maximum function length: 30 lines", "Every function must have JSDoc comments".

4. דוקומנטציה שלמה

CLAUDE.md הוא לא ויקי. אל תדביקו שם API documentation שלם או מדריך של 500 שורות. אם Claude צריך מידע מפורט, הפנו אותו: "See docs/api.md for the full API reference." Claude ידע לקרוא את הקובץ בעצמו כשיצטרך.

5. מידע מיושן

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

6. יותר מדי טקסט

CLAUDE.md שגדול מ-500 שורות צורך יותר מדי טוקנים מחלון ההקשר. הפתרון: פצלו ל-.claude/rules/ (סעיף 3.7).

שורה תחתונה — מה כן ומה לא

דוגמה — CLAUDE.md טוב מול CLAUDE.md רע

בואו נראה שתי גרסאות של אותו סעיף "Rules" ונבין מה עובד ומה לא:

## Rules
- Write clean code
- Be helpful and thorough
- Follow best practices
- Make sure everything works
- Use good variable names

## Rules
- Use Hebrew for all user-facing text, English for code and comments
- Date format: DD/MM/YYYY (Israeli standard), never MM/DD/YYYY
- Currency: always ₪ (ILS), format: ₪1,234.56
- Phone validation: Israeli format (05X-XXX-XXXX or 0X-XXX-XXXX)
- Never use parseInt without radix — always parseInt(x, 10)

תיקיית .claude/rules/ — הגדרות מודולריות

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

מבנה דוגמה

.claude/rules/
├── code-style.md      # Coding conventions
├── testing.md         # Testing requirements
├── security.md        # Security rules
├── content-hebrew.md  # Hebrew content guidelines
└── deploy.md          # Deployment procedures

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

Conditional Activation — אקטיבציה מותנית

וכאן מגיע הפיצ'ר החכם באמת. אתם יכולים להגדיר שקובץ rules ייטען רק כשעובדים עם סוגי קבצים מסוימים. זה נעשה עם YAML Frontmatter — כותרת מיוחדת בתחילת הקובץ:

---
globs: ["*.py", "**/*.py"]
---
# Python Style Rules
- Use type hints on all function signatures
- Follow PEP 8 naming conventions
- Maximum function length: 30 lines
- Use dataclasses instead of plain dicts for structured data
- Prefer list comprehensions over map/filter when readable

הקסם כאן: חוקי Python נטענים רק כשאתם עובדים עם קבצי .py. אם באותו פרויקט יש גם TypeScript, חוקי Python לא יצרכו טוקנים כשאתם עובדים על קבצי .ts. זה חכם, חסכוני, ונקי.

עוד דוגמאות של Conditional Rules

---
globs: ["*.css", "*.scss", "**/*.tsx"]
---
# Styling Rules
- Use Tailwind utility classes, avoid custom CSS
- Dark mode: always use dark: prefix
- Responsive: mobile-first (sm, md, lg, xl)
- Never use !important

---
globs: ["*.md", "content/**/*.md"]
---
# Content Guidelines
- Write in Hebrew, technical terms in English
- Every article must have: H1, intro paragraph, at least 3 H2 sections
- Include a TL;DR at the top
- Link to sources for all statistics

מתי לפצל ומתי לא?

התחילו עם CLAUDE.md אחד. כשהוא מגיע ל-200 שורות — זה הזמן לחשוב על פיצול. לא לפני. פיצול מוקדם מדי יוצר מורכבות מיותרת. הנה הכלל:

• פרויקט קטן (עד 200 שורות הוראות) → CLAUDE.md בודד, בלי rules/
• פרויקט בינוני (200-500 שורות) → CLAUDE.md + 2-3 קבצי rules/
• פרויקט גדול / Monorepo (500+ שורות) → CLAUDE.md קצר + rules/ עם conditional activation

גרסאות ושיתוף צוותי

שאלה חשובה: האם לעשות commit ל-CLAUDE.md ב-Git? כן, בהחלט. CLAUDE.md ו-.claude/rules/ הם דוקומנטציה של הפרויקט — כמו README, רק שימושית יותר. הם צריכים להיות חלק מה-repo.

הכלל הפשוט

שיתוף צוותי

כשיש צוות שעובד עם Claude Code על אותו פרויקט, ה-CLAUDE.md המשותף מבטיח עקביות. כל חבר צוות מקבל את אותן הוראות, אותם כללים, אותן קונבנציות. זה כמו style guide שאוכף את עצמו אוטומטית.

העדפות אישיות — כמו שפת תשובה, רמת פירוט, או סגנון עבודה — נשארות ב-Global CLAUDE.md של כל אחד. ככה מבטיחים גם עקביות טכנית (Project CLAUDE.md) וגם חופש אישי (Global CLAUDE.md).

מחזור עדכון

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

• מיד: כשמשנים tech stack, כשמוסיפים כלל חשוב, כשמגלים Gotcha חדש
• חודשי: סקירה כללית — מחיקת הוראות מיושנות, הוספת לקחים חדשים
• אחרי טעות: כל פעם ש-Claude עושה טעות בגלל חוסר הקשר — עדכנו את CLAUDE.md

# Claude Code
.claude/settings.local.json
.claude/memory/
# BUT do NOT ignore:
# CLAUDE.md
# .claude/rules/
# .claude/settings.json

תקציב ההקשר — למה גודל משנה

בפרק 1 למדנו על חלון ההקשר (Context Window) — כמות הטקסט ש-Claude יכול "לזכור" בתוך שיחה. נכון למרץ 2026, חלון ההקשר של Claude Code הוא 200K טוקנים כברירת מחדל, ו-1M טוקנים עם Opus 4.6 ו-Sonnet 4.6 (זמין לכל המשתמשים, כולל Max, Team ו-Enterprise — ללא תוספת מחיר). כל טוקן ב-CLAUDE.md צורך מקום מתוך חלון ההקשר — לפני שאתם מקלידים מילה אחת. לכן, חשוב להבין את ה"תקציב":

כלל הזהב: שאפו לפחות מ-5,000 טוקנים סך הכל עבור CLAUDE.md + כל קבצי rules. עם Conditional Activation (מהסעיף הקודם), רק חוקים רלוונטיים נטענים — וזה חוסך עוד יותר. חוקרים מעריכים שמודלים מתקדמים כמו Claude יכולים לעקוב באופן אמין אחרי כ-150-200 הוראות בו-זמנית, וה-system prompt של Claude Code כבר צורך כ-50 מהן — אז כדאי לשמור את CLAUDE.md ממוקד.

איך לבדוק את הצריכה?

הפקודה /context מראה את מצב חלון ההקשר הנוכחי — כולל כמה טוקנים CLAUDE.md צורך. הריצו אותה מיד אחרי פתיחת סשן חדש כדי לראות את ה-baseline. אם CLAUDE.md + rules צורכים יותר מ-5% — הגיע הזמן לקצץ.

Auto-Memory — Claude זוכר בשבילך

מעבר ל-CLAUDE.md שאתם כותבים ידנית, יש מנגנון נוסף: Auto-Memory (זיכרון אוטומטי). זה מנגנון שבו Claude Code לומד מההתנהגות שלכם לאורך זמן ושומר הקשר שימושי אוטומטית.

איך זה עובד?

כש-Claude Code מזהה דפוס חוזר או העדפה ברורה, הוא שומר את זה בקובץ זיכרון. למשל:

• "המשתמש מעדיף TypeScript על JavaScript" (אחרי כמה פעמים שביקשתם TypeScript)
• "הפרויקט הזה משתמש ב-port 3001 לשרת הפיתוח" (אחרי שראה את זה)
• "המשתמש רוצה הסברים בעברית" (אחרי כמה שיחות בעברית)

ניהול Auto-Memory

הפקודה /memory מאפשרת לכם לראות, לערוך, ולמחוק זכרונות אוטומטיים. חשוב לבדוק את הזיכרון האוטומטי מדי פעם, כי לפעמים Claude זוכר דברים שכבר לא נכונים. אם שיניתם port או החלפתם framework — הזיכרון האוטומטי עשוי עדיין להפנות לישן.

ההגדרה autoMemoryDirectory מאפשרת לכם לבחור איפה קבצי הזיכרון נשמרים. כברירת מחדל הם נשמרים בתוך .claude/, אבל אפשר לשנות את המיקום.

CLAUDE.md מול Auto-Memory — מה ההבדל?

חשבו על זה כך: CLAUDE.md הוא מה שאתם מלמדים את Claude מראש. Auto-Memory הוא מה שClaude לומד לבד מההתנהגות שלכם. שניהם חשובים ומשלימים.

דוגמה מעשית — auto-memory בפעולה

נניח שעבדתם שבועיים על פרויקט Python, וב-5 סשנים שונים ביקשתם מ-Claude לכתוב type hints. אחרי כמה סשנים, auto-memory שומר: "User prefers type hints on all Python functions." מעכשיו, גם בלי שתבקשו, Claude יוסיף type hints. זה נוח — אבל מה קורה אם עברתם לפרויקט אחר שלא צריך type hints? Auto-memory עשוי עדיין להשפיע. לכן, ניקוי תקופתי חשוב.

דוגמה נוספת: עבדתם על פרויקט עם port 3001. עברתם לפרויקט חדש עם port 3000. Auto-memory עשוי עדיין "לזכור" 3001 ולגרום לבלבול. זו הסיבה ש-CLAUDE.md (ידני) עדיף תמיד על auto-memory — כי אתם שולטים בו ויכולים לוודא שהמידע מדויק ורלוונטי לפרויקט הנוכחי.

Frameworks להחלטות

שגרת עבודה — תחזוקת CLAUDE.md

CLAUDE.md אפקטיבי רק אם הוא מעודכן. מידע מיושן גרוע יותר מבלי מידע בכלל — כי Claude יפעל בביטחון מלא לפי ההוראות הלא-נכונות, ואתם תבזבזו זמן יקר על Debug של בעיה שהמקור שלה הוא שורה ישנה ב-CLAUDE.md. הנה שגרת התחזוקה שתשמור אותו חד ורלוונטי:

תרחיש אמיתי — CLAUDE.md בעבודה יומית

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

בוקר רגיל — בלי CLAUDE.md

דנה פותחת Claude Code ורוצה לכתוב פוסט לבלוג על מוצר חדש. היא צריכה:

1. "הפרויקט שלנו הוא אתר Next.js, התוכן בעברית..."
2. "אנחנו משתמשים ב-Tailwind CSS לעיצוב..."
3. "הפוסטים נשמרים ב-content/blog/..."
4. "ה-SEO שלנו דורש H1 עם המילה המפתח..."
5. "הטון שלנו הוא מקצועי אבל נגיש..."

5 דקות של הסבר — לפני שהיא מתחילה לעבוד. ומחר בבוקר? שוב אותו הסבר.

בוקר רגיל — עם CLAUDE.md

דנה פותחת Claude Code. הקובץ CLAUDE.md כבר נטען אוטומטית. היא כותבת:

"תכתוב פוסט בלוג על המוצר החדש שלנו — SmartWidget Pro. נושא: חיסכון בזמן לצוותי שיווק."

Claude כבר יודע הכל: את ה-tech stack, את תיקיית התוכן, את כללי ה-SEO, את הטון, ואת השפה. הוא מייצר פוסט מוכן תוך 30 שניות — בעברית, עם SEO מדויק, בפורמט הנכון, בתיקייה הנכונה. דנה בודקת, מתקנת משפט אחד, ומפרסמת.

ההבדל: 5 דקות הסבר מול 0 דקות הסבר. חודש של עבודה יומית = 2+ שעות שנחסכו. ומעבר לזמן — האיכות טובה יותר כי Claude מבין את ההקשר מהרגע הראשון.

CLAUDE.md של דנה

# SmartWidget Marketing Site

## What This Project Does
Marketing website + blog for SmartWidget, an Israeli B2B SaaS
for marketing teams. Target audience: marketing managers 28-45.

## Stack
- Next.js 15 + Tailwind CSS
- Content: MDX files in content/blog/
- CMS: Contentlayer for MDX processing
- Deploy: Vercel (auto from main branch)

## Content Rules
- ALL content in Hebrew, tech terms in English
- Tone: Professional but approachable (not academic)
- Blog posts: 800-1500 words, must include H1 with keyword
- Meta description: max 155 chars, include primary keyword
- Date format: DD/MM/YYYY
- Currency: ₪ (ILS)

## SEO
- Primary keyword in H1 and first 100 words
- 2-3 secondary keywords naturally distributed
- Internal links: at least 2 per blog post
- Image alt text in Hebrew

## Rules
- Never publish without meta description
- CTA at bottom of every blog post
- Mobile-first: test on 375px width before publishing
- Images: WebP format, max 150KB per image

## Gotchas
- MDX files need frontmatter with exact date format
- The blog RSS feed breaks if slug contains Hebrew
- Vercel preview URLs expire after 30 days

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

Walkthrough מלא — בניית CLAUDE.md מ-/init ועד commit

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

שלב 1: ניתוח אוטומטי עם /init

פותחים את הפרויקט בטרמינל ומפעילים Claude Code. מריצים /init. Claude Code סורק את הפרויקט ומוצא: package.json עם Next.js, תיקיית content/ עם קבצי Markdown, tailwind.config.ts, ותיקיית public/images/. הוא יוצר CLAUDE.md שנראה ככה:

# Digital Marketing Blog

## Stack
- Next.js 15 with App Router
- Tailwind CSS
- MDX for content

## Structure
- content/ — Blog posts in MDX format
- src/app/ — Next.js pages
- public/images/ — Static images

## Commands
- Dev: npm run dev
- Build: npm run build

לא רע בכלל. אבל חסרים כמה דברים קריטיים. הנה מה שנוסיף:

שלב 2: הוספה ידנית — מה ש-/init פספס

# Digital Marketing Blog — nVision Agency

## What This Project Does
Content marketing blog for nVision, a digital marketing agency
in Tel Aviv. Hebrew content targeting Israeli small businesses.
Published 3-4 articles per week. SEO-optimized for Google IL.

## Stack
- Next.js 15 with App Router + TypeScript
- Tailwind CSS with custom brand colors
- MDX for content (content/ directory)
- Vercel for deployment (auto-deploy on push to main)
- Google Analytics 4 via next/script

## Structure
- content/blog/ — Blog posts in MDX (filename = slug)
- content/guides/ — Long-form guides (2000+ words)
- src/app/ — Next.js pages (don't create new routes without asking)
- src/components/ — Reusable React components
- public/images/blog/ — Blog post images (WebP format, max 200KB)

## Commands
- Dev: `npm run dev` (localhost:3000)
- Build: `npm run build`
- Deploy: `git push origin main` (auto-deploys)
- New post: create MDX file in content/blog/ with frontmatter

## SEO Rules
- Every post MUST have: title, description, keywords in frontmatter
- H1 from title, first H2 within 200 words
- Meta description: 145-155 chars, include primary keyword
- Images: descriptive alt text in Hebrew, WebP format
- Internal links: at least 2 per article

## Content Rules
- ALL content in Hebrew
- Technical terms in English with Hebrew explanation on first use
- Tone: Professional, friendly, practical — like a smart colleague
- Short paragraphs: 2-4 sentences max
- Every article ends with a CTA (call-to-action)
- Never mention competitor agency names

## Gotchas
- MDX frontmatter MUST include 'date' in YYYY-MM-DD format
- Images in WebP only — PNG/JPG will fail the build
- The sitemap auto-generates from content/ — don't edit manually
- Hebrew slug in URL: use transliterated English, not Hebrew chars
- GA4 tracking breaks if next/script strategy isn't "afterInteractive"

שלב 3: בדיקה וcommit

עכשיו פותחים סשן חדש של Claude Code ובודקים. שואלים: "מה הפרויקט עושה?" — Claude עונה בדיוק. שואלים: "צריך להוסיף מאמר חדש על SEO מקומי" — Claude יוצר קובץ MDX בתיקייה הנכונה, עם frontmatter מלא, בעברית, עם CTA בסוף, ועם internal links. הכל בפעם הראשונה, בלי תיקונים.

עושים commit:

git add CLAUDE.md && git commit -m "Add CLAUDE.md with content and SEO guidelines"

סה"כ זמן: 2 דקות ל-/init, 10 דקות עריכה, 1 דקה commit. 13 דקות שיחסכו לכם שעות לאורך השבועות הבאים.

תרגילים מעשיים

תרגיל 1: בנה CLAUDE.md מאפס לעסק ישראלי

תרגיל 2: הפוך CLAUDE.md בינוני למודולרי

תרגיל 3: CLAUDE.md קבוצתי

אם אתה עושה רק דבר אחד

בדוק את עצמך — האם עברת את פרק 3?

צ'קליסט סיום פרק

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

• מבין/ה מה זה CLAUDE.md ולמה הוא חיוני לכל פרויקט
• מבין/ה את ההיררכיה: Global → Project → Rules → שיחה
• ניסיתי את הפקודה /init על פרויקט אמיתי
• יצרתי Global CLAUDE.md ב-~/.claude/CLAUDE.md עם העדפות אישיות
• יצרתי Project CLAUDE.md לפרויקט אמיתי עם התבנית המוזהבת
• ה-CLAUDE.md שלי כולל: תיאור פרויקט, tech stack, פקודות, כללים, ו-Gotchas
• מבין/ה מה לא לשים ב-CLAUDE.md (סודות, לוגים, מידע מיושן)
• מכיר/ה את תיקיית .claude/rules/ ו-Conditional Activation
• מבין/ה את תקציב ההקשר — בדקתי עם /context
• מכיר/ה את Auto-Memory ובדקתי עם /memory
• עשיתי commit ל-CLAUDE.md ול-.claude/rules/ (אם יש)
• בדקתי: שאלתי את Claude שאלה על הפרויקט — והוא ענה נכון בלי הסבר נוסף

סיכום הפרק

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

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

ואם לקחתם רק דבר אחד מהפרק הזה: 5 שורות. 2 דקות. CLAUDE.md. עשו את זה עכשיו, לפני שתמשיכו לפרק הבא.