CLAUDE.md: המדריך המלא לצוותי פיתוח

אם יש דבר אחד שמבחין בין צוותים שעובדים ב-Claude Code ב-"מצב חובבני" לצוותים שמפיקים ערך אמיתי - זה CLAUDE.md. הקובץ הקטן הזה הוא ההבדל בין Claude שמנחש למה אתם מתכוונים, ל-Claude שכבר מכיר את הפרויקט שלכם כמו מפתח וותיק. במדריך הזה: 6 חלקי חובה, template מוכן, ו-best practices מהשטח.

מה זה CLAUDE.md?

CLAUDE.md הוא קובץ טקסט פשוט (Markdown) שממוקם בשורש הפרויקט שלכם. Claude Code טוען אותו אוטומטית בתחילת כל session, ומתייחס אליו כאל "instructions" - הוראות אישיות לפרויקט.

זה בעצם הזיכרון הקבוע של Claude לפרויקט - conventions, ארכיטקטורה, כלים, ומה לא לעשות.

CLAUDE.md בארגונים - מספרים

למה זה כל כך חשוב?

בלי CLAUDE.md, Claude מתחיל כל משימה "עיוור":

• ❌ לא יודע אם זה React או Vue
• ❌ לא יודע אם להשתמש ב-npm או yarn
• ❌ לא מכיר את הקונבנציות של הצוות
• ❌ לא יודע אילו קבצים לא לגעת
• ❌ לא מבין את המבנה הארכיטקטוני
• ❌ לא יודע איך להריץ tests או build

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

3 סוגי CLAUDE.md

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

Template מנצח להעתקה

הנה ה-template שאנחנו משתמשים בו ברוב הארגונים שאנחנו עובדים איתם. תעתיקו, התאימו, ותתחילו לעבוד:

# שם הפרויקט

תיאור קצר בשורה אחת של מה הפרויקט עושה ולמי.

## Stack
- Language: TypeScript 5.3
- Framework: Next.js 14 (App Router)
- Database: PostgreSQL + Prisma ORM
- Testing: Vitest + Playwright
- Package manager: pnpm (NOT npm or yarn)
- UI: Tailwind CSS + shadcn/ui

## Architecture
- /app           - Next.js pages
- /components    - Shared React components
- /lib           - Business logic (pure functions)
- /db            - Prisma schema & migrations
- /tests         - Test files
- /docs          - Documentation

## Conventions
- TypeScript strict mode
- Named exports (NOT default)
- File naming: kebab-case.ts
- Components: PascalCase.tsx
- Hooks: useCamelCase.ts
- Tests: filename.test.ts (next to source)

## Rules (Important!)
- NEVER modify /db/migrations (only create new ones with `pnpm prisma migrate dev`)
- NEVER install packages without asking
- NEVER commit .env or secrets
- ALWAYS run `pnpm test` before suggesting a commit
- ALWAYS use existing UI components from /components/ui
- ALWAYS write tests for new features

## Common tasks
- Run dev: `pnpm dev`
- Run tests: `pnpm test`
- Run e2e: `pnpm test:e2e`
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`
- Create migration: `pnpm prisma migrate dev --name <name>`

## Business context
המוצר שלנו - SaaS לניהול לקוחות לעורכי דין. הקהל: משרדים בינוניים בישראל.
החשיבות: כל data של לקוחות חסוי. תמיד להתייחס ל-privacy ו-encryption.

6 חלקי החובה

1. Stack ברור

Claude צריך לדעת בדיוק באיזו שפה ו-frameworks אתם עובדים. ציינו גם גרסאות - זה משנה! TypeScript 4 שונה מ-TypeScript 5, Next.js 13 שונה מ-Next.js 14.

2. מבנה תיקיות

אל תסמכו על זה ש-Claude "יבין לבד". ספרו לו איזו תיקייה ממה. זה חוסך עשרות חיפושי קבצים מיותרים.

3. Conventions

Naming, formatting, patterns שאתם אוהבים. זה מונע תיקונים מיותרים אחר כך. דוגמה: "named exports" - כל פעם ש-Claude יכתוב export default תצטרכו לתקן.

4. Rules עם NEVER / ALWAYS

אלה המילים הכי חשובות. Claude מקשיב להן בעדיפות גבוהה. השתמשו בהן להגדיר גבולות.

5. Common Tasks

רשימה של הפקודות שאתם מריצים ביום-יום. Claude ישתמש בהן במקום לנחש. זה גם מתעד את ה-workflow לחברי צוות חדשים.

6. Context עסקי

לא רק טכני! שורה או שתיים על למה המוצר שלכם קיים, מי הלקוחות, והמטרות. זה משנה את ה-judgment של Claude.

דוגמה לחשיבות: אם המוצר הוא SaaS לתחום פיננסים, Claude יקפיד יותר על security. אם זה כלי שיווק - יקפיד על ביצועים ו-UX. ה-context שינוי את ה-tradeoffs.

טעויות נפוצות שכדאי להימנע מהן

Pro Tip: Memory Imports

Claude Code תומך ב-@path/to/file בתוך CLAUDE.md - זה מאפשר לכם לייבא קבצים אחרים. דוגמה:

# CLAUDE.md - הקובץ הראשי קטן ומאורגן

# פרויקט: SaaS for Law Firms

@docs/architecture.md       # ארכיטקטורה מפורטת
@docs/api-conventions.md    # standards של API
@.claude/workflows.md       # workflows רוטיניים
@.claude/security.md        # הוראות אבטחה

## Quick rules
- Stack: TypeScript + Next.js + Prisma
- Run: pnpm dev | pnpm test | pnpm typecheck

דוגמאות מארגונים אמיתיים

סוכנות פרסום בתל אביב

סוכנות פרסום שעובדת עם Claude Code על campaigns dashboard. ה-CLAUDE.md שלהם כולל:

• Stack: Next.js + Recharts + Tailwind
• Rules: NEVER מחיקת campaign data, ALWAYS confirmation לפני פעולות פיננסיות
• Business context: דוחות לקוחות חייבים להיראות מקצועיים - design matters

משרד עורכי דין

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

• Stack: Vue 3 + Pinia + Laravel API
• Rules: NEVER לוגים של פרטי לקוח, ALWAYS encryption-at-rest
• Business context: כל data חסוי תחת חוק עו"ד-לקוח

חברת פיננסים

חברת השקעות שעובדת על portfolio analytics:

• Stack: Python + FastAPI + PostgreSQL + Streamlit
• Rules: ALWAYS audit trail לכל transaction, NEVER hardcoded credentials
• Business context: compliance לרשות ני"ע, כל החלטה ניתנת לבדיקה

שאלות נפוצות

סיכום

CLAUDE.md הוא ההשקעה הכי רנטבילית שתעשו ב-Claude Code. שעה אחת של עבודה על CLAUDE.md טוב חוסכת עשרות שעות בחודשים הבאים.

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