המדריך המלא לתיקיית .claude/ ב-Claude Code

תוכן עניינים

תוכן עניינים

אם אתם עובדים עם Claude Code ועדיין לא הגדרתם תיקיית .claude/ בפרויקט שלכם, אתם משאירים כסף על השולחן. לא מטאפורית – ממש. ולא רק כסף – גם זמן, והרבה! כל סשן עבודה בלי הקשר מותאם הוא סשן שבו המודל מנחש במקום לדעת, שואל במקום לעשות, וחוזר על טעויות שכבר תיקנתם אתמול.

 

תיקיית .claude/ היא מערכת ההפעלה של הפרויקט שלכם מול Claude Code. היא מגדירה מי הוא, איך הוא עובד, מה מותר ומה אסור, ומתי הוא צריך להפעיל אוטומציות בלי לשאול. ההבדל בין פרויקט "רגיל" לפרויקט "Optimized" הוא בדיוק מה שנמצא בתיקייה הזו.

 

במדריך הזה נבנה את התיקייה צעד אחר צעד, עם דוגמאות מלאות שאפשר להעתיק ולהתאים. לא רק "מה לשים שם" – אלא איך לחשוב על כל רכיב ולמה הוא משנה את חוויית העבודה.

מבנה התיקייה – תמונת-על

לפני שנצלול לכל רכיב, הנה המבנה המלא. לא כל פרויקט צריך את הכל – אבל חשוב להכיר את כל האפשרויות כדי לדעת מה רלוונטי לכם.

 


project/
├── CLAUDE.md                  # הוראות מרכזיות (נקרא אוטומטית)
├── CLAUDE.local.md            # (git-לא נכנס ל) הגדרות אישיות
├── mcp.json                   # (!חייב להיות בשורש) MCP חיבורי
├── .gitignore
└── .claude/
    ├── hooks/
    │   ├── PostToolUse.sh     # רץ אחרי כל שימוש בכלי
    │   ├── SessionStart.sh    # רץ בתחילת כל סשן
    │   └── PreCompact.sh      # context רץ לפני דחיסת
    ├── commands/
    │   └── ship.md            # /ship - פקודת מותאמת
    ├── skills/
    │   ├── carousel/          # תבנית ליצירת קרוסלות
    │   └── drill/             # תבנית לתרגילים חוזרים
    ├── agents/
    │   ├── code-reviewer.md   # תת-סוכן לסקירת קוד
    │   ├── researcher.md      # תת-סוכן למחקר
    │   └── log-analyzer.md    # תת-סוכן לניתוח לוגים
    ├── output-styles/
    │   └── terse.md           # סגנון תגובה מצומצם
    ├── rules/
    │   └── api.md             # חוקים ממוקדי-נתיב
    ├── plugins/
    │   └── vercel/            # הרחבה (בטא)
    ├── settings.json          # הגדרות ברמת הצוות
    └── settings.local.json    # הגדרות אישיות מקומיות

 

עיקרון מנחה: כל מה שבשורש הפרויקט (CLAUDE.md, mcp.json) נקרא אוטומטית בכל סשן. כל מה שבתוך .claude/ נטען לפי הצורך, לפי הקשר, או לפי בקשה מפורשת. זו ההפרדה שמאפשרת לשמור את חלון ההקשר נקי.

 

CLAUDE.md – הקובץ שמגדיר הכל

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

 

חוק הברזל: מתחת ל-200 שורות. תמיד. הוראות ארוכות מדי מדללות את קשב המודל. אם אתם צריכים יותר – השתמשו ב-rules/ ו-skills/ שנטענים לפי הקשר.

 

מה כן לכלול:

  • ארכיטקטורת הפרויקט ברמה גבוהה (stack, מבנה תיקיות מרכזי)
  • קונבנציות קוד (naming, patterns, מה לא לעשות)
  • פקודות שגרתיות (build, test, lint, deploy)
  • הנחיות ספציפיות לסגנון עבודה

 

מה לא לכלול:

  • תיעוד API מלא (שייך ל-rules/)
  • קוד ארוך או דוגמאות מפורטות (שייך ל-skills/)
  • מידע אישי או secrets (שייך ל-CLAUDE.local.md)

 

דוגמה מלאה ל-CLAUDE.md של פרויקט SaaS:

 


# Project: Mango – Customer Feedback Platform

## Architecture
- **Frontend:** Next.js 14 (App Router), TypeScript, Tailwind CSS
- **Backend:** Node.js API routes in /src/app/api/
- **Database:** PostgreSQL via Prisma ORM
- **Auth:** NextAuth.js with Google + email providers
- **Hosting:** Vercel (production), local dev with `pnpm dev`

## Directory Structure
- `src/app/` – pages and API routes
- `src/components/` – shared UI components (use shadcn/ui)
- `src/lib/` – utilities, db client, helpers
- `src/types/` – TypeScript type definitions
- `prisma/` – schema and migrations

## Commands
- Build: `pnpm build`
- Dev: `pnpm dev`
- Test: `pnpm test` (Vitest)
- Lint: `pnpm lint` (ESLint + Prettier)
- DB migrate: `pnpm prisma migrate dev`

## Code Conventions
- Always use TypeScript strict mode
- Components: PascalCase, one per file
- API routes: return typed responses using `NextResponse.json()`
- Never use `any` type – define proper interfaces
- Prefer server components; use "use client" only when necessary
- Error handling: always wrap async operations in try/catch
- Imports: use `@/` alias for src directory

## Git
- Commit messages: conventional commits (feat:, fix:, chore:)
- Never commit directly to main – always create a branch
- PR description must include what changed and why

## Important Notes
- All user-facing text must support i18n (use `t()` function)
- Never log sensitive data (emails, tokens, passwords)
- Rate limiting is handled at middleware level – don't add custom rate limits

 

לגבי CLAUDE.local.md – זהו הקובץ המקומי שלכם. הוא לא נכנס ל-git (תוסיפו אותו ל-.gitignore!) ומכיל דברים שרלוונטיים רק לסביבה שלכם:

 


# Local Settings

## Environment
- I'm working on macOS with Homebrew
- Local DB runs on port 5433 (not default 5432)
- My test user: dev@example.com / password123

## Preferences
- I prefer verbose explanations when debugging
- Always show me the full diff before committing
- Use Hebrew for comments in my personal branches

hooks/ – אוטומציה שרצה תמיד

Hooks הם הרכיב הדטרמיניסטי היחיד במערכת. בניגוד מכל דבר אחר ב-.claude/ – הם לא תלויים בהחלטת המודל. הם רצים תמיד, בנקודות קבועות, בדיוק כמו git hooks.

 

זה הופך אותם למושלמים לדברים שאסור לשכוח: logging, validation, עדכון state, או כל פעולה שצריכה לקרות ב-100% מהמקרים.

 

Hook מתי רץ שימושים טיפוסיים
SessionStart.sh בתחילת כל סשן חדש git pull, בדיקת env, טעינת קונטקסט
PostToolUse.sh אחרי כל שימוש בכלי auto-format, validation, logging
PreCompact.sh לפני דחיסת context window שמירת state, סיכום ביניים

 

דוגמה: SessionStart.sh שמוודא שהפרויקט מעודכן:

 


#!/bin/bash
# .claude/hooks/SessionStart.sh
# Ensures project is up-to-date at session start

echo "🔄 Pulling latest changes..."
git pull --rebase origin main 2>/dev/null

if [ $? -ne 0 ]; then
    echo "⚠️  Git pull failed – you may have local conflicts"
    exit 1
fi

echo "📦 Checking dependencies..."
if [ -f "pnpm-lock.yaml" ]; then
    pnpm install --frozen-lockfile --silent
elif [ -f "package-lock.json" ]; then
    npm ci --silent
fi

echo "✅ Session ready. Project is up-to-date."
exit 0

 

דוגמה: PostToolUse.sh שמריץ formatting אוטומטי:

 


#!/bin/bash
# .claude/hooks/PostToolUse.sh
# Auto-formats files after Claude edits them

TOOL_NAME="$1"
FILE_PATH="$2"

# Only run after file write/edit operations
if [[ "$TOOL_NAME" == "write" || "$TOOL_NAME" == "edit" ]]; then
    if [[ "$FILE_PATH" == *.ts || "$FILE_PATH" == *.tsx ]]; then
        npx prettier --write "$FILE_PATH" 2>/dev/null
        echo "✨ Formatted: $FILE_PATH"
    fi
fi

exit 0

 

טיפ חשוב: תמיד הוסיפו exit 0 (הצלחה) או exit 1 (כשלון) מפורש. Claude Code משתמש ב-exit code כדי להבין אם ההוק הצליח ולהתאים את ההתנהגות שלו בהתאם.

commands/ – פקודות Slash מותאמות

כל קובץ .md בתיקיית commands/ הופך אוטומטית לפקודת slash שזמינה בצ'אט. שם הקובץ הוא שם הפקודה. הרעיון פשוט: במקום להקליד אותה הוראה שוב ושוב, אתם מגדירים אותה פעם אחת ומפעילים בלחיצה.

 

החלק הראשון בקובץ הפקודה (בין סימוני ה ---) נקרא frontmatter. הוא כולל תיאור של הפקודה והמשתנים, באופן שמוצג אוטומאטית ב live docs של קלוד-קוד.

 

דוגמה: commands/ship.md – פקודת deployment מלאה:

 


---
description: Build, test, and deploy the current branch
arguments:
  - name: target
    description: Deployment target (staging or production)
    default: staging
---

# Ship Command

Execute the full deployment pipeline for target: {{target}}

## Steps

1. Run the full test suite: `pnpm test`
2. If tests pass, run the linter: `pnpm lint`
3. If lint passes, build the project: `pnpm build`
4. If build succeeds, deploy:
   - If target is "staging": `vercel deploy --preview`
   - If target is "production": `vercel deploy --prod`
5. After successful deploy, create a git tag with current date and time
6. Report the deployment URL

## On Failure

If any step fails:
- Stop immediately
- Show the error clearly
- Suggest a fix if obvious
- Do NOT proceed to the next step

 

עכשיו אפשר פשוט לכתוב /ship production בצ'אט ו-Claude ירוץ על כל הרצף.

 

דוגמה נוספת: commands/review.md – סקירת קוד מהירה:

 


---
description: Review staged changes before commit
arguments: []
---

# Code Review

Review all currently staged git changes (`git diff --cached`).

Check for:
1. **Bugs:** Logic errors, off-by-one, null references
2. **Security:** Exposed secrets, SQL injection, XSS vectors
3. **Performance:** N+1 queries, unnecessary re-renders, large payloads
4. **Style:** Naming conventions, dead code, missing types

Format your response as a table:
| File | Line | Severity | Issue | Suggestion |

If everything looks good, just say "✅ Ready to commit" with a suggested commit message.

 

שימו לב לשימוש ב-{{arg}} להעברת פרמטרים. כל ארגומנט שמוגדר ב-frontmatter הופך לזמין בתוך הגוף של ה-command.

skills/ – תבניות למשימות חוזרות

Skills שונות מ-commands בנקודה מהותית: הן לא מופעלות ע"י פקודה מפורשת. הן נטענות אוטומטית כשהמודל מזהה שהמשימה הנוכחית תואמת ל-skill מסוימת. תחשבו על skill כ"מומחיות" שהמודל "זוכר" שיש לו כשהוא צריך אותה.

 

החלק הראשון בקובץ הפקודה (בין סימוני ה ---) נקרא frontmatter. הוא מעין תקציר של הפקודה, וחשוב שיהיה קצר וקולע. קלוד שולח ל-LLM אוסף של תקצירי הפקודות הללו, כדי לקבל החלטה מה מתאים, ובמה להתעמק – ולקרוא את התיאור המלא.

 

כל skill היא תיקייה שמכילה לפחות קובץ SKILL.md, ואופציונלית גם קבצי דוגמה, templates, או assets.

 

דוגמה: skills/carousel/SKILL.md – יצירת קרוסלות לאינסטגרם:

 


---
name: instagram-carousel
trigger: When user asks to create carousel content, social media slides, or Instagram posts
---

# Instagram Carousel Skill

You create professional Instagram carousel content.

## Format Rules

- Exactly 10 slides per carousel
- Each slide: one clear message, max 25 words
- Slide 1: Hook (question or bold statement)
- Slides 2-9: Content (one idea per slide, progressive)
- Slide 10: CTA (call to action)

## Visual Direction

For each slide, specify:
- Background color (from brand palette)
- Text placement (center/top/bottom)
- Icon or illustration suggestion
- Font weight (bold for hooks, regular for body)

agents/ – תת-סוכנים מבודדים

זה כבר מתחיל להיות באמת מעניין – כי פה אנו יוצאים מגבולות ה״עוזר האישי״ ומתחילים לחשוב על מבנים ארגוניים. אפקטיביות, עבודת צוות, שיתוף הקשר ומידור. Agents הם תת-סוכנים עם הוראות ספציפיות וחלון הקשר מבודד משלהם. כל agent לא "יודע" על שיחות אחרות ולא מושפע מהן, מה שמונע זיהום הקשר ושומר על מיקוד גבוה.

 

סוכנים נפוצים:

  • code-reviewer.md – בודק קוד ומחפש באגים, בעיות אבטחה, ביצועים וסגנון
  • researcher.md – סוכן חיפוש וסינתזה: מגשר בין מקורות, מסכם ומשווה
  • log-analyzer.md – מנתח stack traces, מזהה דפוסים ומציע תיקונים

 

יתרון משמעותי: אפשר להריץ מספר agents במקביל על קטעי קוד שונים ולצרף את תוצאותיהם. לדוגמה – agent אחד סוקר קוד בזמן שאחר מנתח לוגים, ושלישי מבצע מחקר. כל אחד עובד בבידוד מלא.

 

ה-frontmatter במקרה של תתי-סוכנים משמש את Claude Code להחליט מתי להפעיל כל סוכן. זה חלק קריטי, וניסוח טוב וממוקד – שווה הרבה! בשדה ה-tools יוצרים הגבלה של הסוכן לכלים מסוימים (isolation), ובשדה ה-model מפרטים מה המודל הדיפולטיבי שעליו מבוסס תת-הסוכן. באופן זה ניתן לבחור את ה״אדם הנכון לתפקיד הנכון״, לצורך התאמת עלויות, אופי ויכולות.

 


---
name: code-reviewer
description: Reviews code for bugs, security, performance and style issues. Call when you need structured code review on a file or snippet.
tools: read_file, bash
model: claude-haiku-4-5
---

# Code Reviewer Agent

## Role
You are a focused code review agent. You receive a code snippet or file path and return a structured review. Nothing else.

## Instructions
- Review for: bugs, security issues, performance problems, and style inconsistencies
- Do NOT rewrite the code unless explicitly asked
- Do NOT explain what the code does - only what's wrong with it
- If nothing is wrong, say so in one line

## Output Format
```
### Bugs
- <issue> → <fix suggestion>

### Security
- <issue> → <fix suggestion>

### Performance
- <issue> → <fix suggestion>

### Style
- <issue> → <convention to follow>

### Summary
<one line verdict>
```

## Constraints
- Max response: 300 tokens
- No prose, no preamble
- Hebrew output if input is in Hebrew context

output-styles/ – שליטה על פורמט התגובה

output-styles/ מגדיר איך Claude מגיב, לא מה הוא עושה. זו הפרדה חשובה – אתם שולטים בפורמט הפלט בלי להתערב בלוגיקה.

 

דוגמאות:

  • terse.md – מצב קצר ותכליתי: קוד בלבד, ללא הסבר, ללא סמול-טוק
  • אפשר ליצור styles נוספים לפי הצורך: verbose, markdown-only, json-only

 

הסגנון נבחר ידנית או מוגדר כברירת מחדל ב-settings.json. זה שימושי במיוחד כשאתם עובדים על משימות שונות לאורך היום – לפעמים צריכים הסבר מפורט, ולפעמים רק את הקוד.

 


---
name: terse
description: Code and results only. No prose, no explanations, no preamble.
---

# Terse Output Style

## Rules
- Return code blocks only - no explanation before or after
- If the answer is not code, return a single sentence maximum
- No "here is...", no "sure!", no summaries
- No bullet points unless explicitly requested
- Errors: one line, format → `ERROR: <what failed>`
- Done: one line, format → `DONE: <what changed>`

 

הנוסח קצר בכוונה – output-style לא צריך להיות ארוך. הוא הוראת מצב, לא workflow.

rules/ – חוקים ממוקדי-נתיב

Rules הם אולי הרכיב ה"חכם" ביותר מבחינת ניהול הקשר. הם נטענים רק כשהמודל עובד על קבצים שתואמים לנתיב מוגדר – ולא בשום מקרה אחר.

 

דוגמה: קובץ api.md עם glob של src/api/** ייטען רק בעריכת קבצי API. הוא לא "מזהם" את ההקשר כשאתם עובדים על frontend.

 

שימושים נפוצים:

  • כללי validation לקבצי DB
  • הוראות style לקומפוננטות UI
  • מדיניות security לנתיבי auth

 


---
name: api-rules
glob: src/api/**
description: Rules applied only when working on API files.
---

# API Rules

## Rules
- Every endpoint must have input validation before any logic
- Never return raw DB errors to the client - map to HTTP status codes
- Auth middleware must be applied on every non-public route
- Response format is always `{ data, error, meta }` - no exceptions
- No business logic inside route handlers - delegate to service layer

 

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

settings.json ו-settings.local.json – הגדרות גלובליות

שני קבצי ההגדרות פועלים בשכבות, בדומה לעיקרון ה-override המוכר:

 

settings.json – הגדרות משותפות לכל הצוות:

 

  • מודל ברירת מחדל
  • הרשאות כלים (tools)
  • hooks פעילים

 


// settings.json (shared, committed to git)
{
  "model": "claude-sonnet-4-5",
  "hooks": {
    "PostToolUse": ".claude/hooks/PostToolUse.sh",
    "SessionStart": ".claude/hooks/SessionStart.sh",
    "PreCompact": ".claude/hooks/PreCompact.sh"
  },
  "tools": {
    "allow": ["read_file", "write_file", "bash", "web_search"],
    "deny": ["delete_file"]
  },
  "output": {
    "defaultStyle": "terse"
  }
}

 

settings.local.json – override אישי מקומי (מוחרג מ-git):

 

  • API keys
  • העדפות אישיות

 


// settings.local.json (personal, in .gitignore)
{
  "model": "claude-opus-4-5",
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-...",
    "DB_URL": "postgresql://localhost/mydb_dev"
  },
  "tools": {
    "allow": ["delete_file"]
  }
}

 

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

plugins/ – הרחבות (בטא 2026)

Plugins הם מנגנון חדש להרחבת יכולות Claude Code. כל plugin מוגדר עם frontmatter בפורמט ייעודי ויכול לכלול פקודות מותאמות, agents, חיבורי MCP ועוד.

 

דוגמה: תיקיית vercel/ – אינטגרציה עם Vercel ישירות מתוך Claude Code, כולל deploy, preview וניהול דומיינים. במקום לעבור לטרמינל נפרד – הכל זמין מתוך סביבת העבודה.

 

⚠️ שימו לב: מאחר שמדובר עדיין בגרסת בטא, ה-API עשוי להשתנות. בדקו את הדוקומנטציה הרשמית לפני שאתם מסתמכים על plugins ב-production.

mcp.json – חיבורי MCP

קובץ mcp.json מגדיר את שרתי ה-MCP (Model Context Protocol) שהפרויקט משתמש בהם. נקודה חשובה שכדאי לזכור: הקובץ חייב להיות בשורש הפרויקט (ליד package.json), לא בתוך תיקיית .claude/.

 

זו טעות נפוצה שגורמת ל-Claude Code פשוט לא לזהות את חיבורי ה-MCP. אם הגדרתם servers ושום דבר לא עובד – בדקו קודם כל את מיקום הקובץ.

 

מתבלבלים בין Skills לבין Connectors, Plugins ו-MCP? מומלץ לעיין במדריך הזה.

 

סיכום – 10 כללי אצבע ליישום מיידי

כדי שתוכלו להתחיל ליישם מיד, הנה רשימה תמציתית של עשרת הכללים החשובים ביותר:

 

  1. CLAUDE.md – מתחת ל-200 שורות תמיד. הוראות ארוכות מדוללות קשב ופוגעות בתוצאות.
  2. hooks/ = דטרמיניסטי. הם רצים בכל פעם, בלי תלות בהחלטת המודל.
  3. skills/ = לפי דרישה. נטענות רק כשהמודל מזהה משימה מתאימה.
  4. rules/ = הפרידו הוראות לפי נתיב. שמרו על הקשר עבודה נקי וממוקד.
  5. mcp.json בשורש הפרויקט, לא בתוך .claude/.
  6. agents/ = חלון הקשר מבודד לכל סוכן. אין התנגשויות או זיהום הקשר.
  7. output-styles/ = כשאתם רוצים פלט עקבי – JSON תמיד, קוד בלבד, וכדומה.
  8. קבצי *.local תמיד ב-.gitignore. אל תדחפו חומר סודי ל-repo.
  9. plugins/ עדיין בבטא (2026) – בדקו changelog לפני שימוש ב-production.
  10. הריצו /doctor בתוך Claude Code לאימות שכל הקבצים נקראים כהלכה.

 

תיקיית .claude/ היא לא סתם עוד תיקיית קונפיגורציה. היא למעשה ה"מוח הארגוני" של הפרויקט שלכם ביחס ל-Claude Code. ככל שתשקיעו יותר בארגון שלה – כך התוצאות שתקבלו יהיו טובות, עקביות ומדויקות יותר.

 

בהצלחה!