מאת אסף ביטון
1,468 שעות עם Claude Code. 685 סשנים. 122 אלף שורות קוד על שני מחשבים במקביל. ועדיין, ב-2:47 לפנות בוקר, מצאתי את עצמי בוהה ב-component שהוא יצר עם class-based syntax. ב-2026. לפרויקט React 19 שלי. ה-CLAUDE.md היה 200 שורות של context מתועד בקפידה, ו-Claude התעלם בערך מ-80% ממנו.
מה תקבלו במדריך הזה: איך לקנפג את CLAUDE.md למקסימום היענות, אילו טעויות גורמות ל-Claude להתעלם מהכללים, ומתי בכלל כדאי לעבור ל-AGENTS.md. 15 דקות קריאה, חוסך שעות של תסכול.
לפני שמתחילים:
- Claude Code מותקן (מנוי Max או Pro)
- פרויקט עם מבנה תיקיות בסיסי
- נוחות עם terminal ו-CLI
Learn how to configure Claude Code with CLAUDE.md and AGENTS.md files for optimal project performance.
הכי מתאים ל: Senior developers who want to delegate long autonomous tasks and review results, DevOps teams integrating AI into CI pipelines for automated test fixing
מחקתי את הקובץ והתחלתי מחדש. שלוש פעמים. בדקתי 8 קונפיגורציות שונות על פרויקטים אמיתיים, על Mac ועל Linux במקביל. מה שגיליתי שינה לי לגמרי את הצורה שאני חושב על AI context: יותר תיעוד הופך את Claude לגרוע יותר, לא טוב יותר.
ובמהלך החפירה הזאת נתקלתי במשהו שכמעט לא מוזכר בתיעוד של Anthropic: AGENTS.md, סטנדרט פתוח שמאחוריו OpenAI, Google ועוד 20 כלי קוד AI. יכול להיות שזה מה שיכריע את הקרב לטווח הארוך, לא CLAUDE.md.
עוד לא נכנסתם ל-Claude Code? תתחילו ב-מדריך Claude Code המלא שלנו: תמחור (20 עד 200 דולר בחודש), benchmarks ושיקולי אבטחה. אפשר גם לחפור ב-כרטיס הכלי של Claude Code בקטלוג שלנו. המדריך הזה ממוקד אך ורק בקנפוג של CLAUDE.md ו-AGENTS.md.
שלב 1: להבין את הבעיה האמיתית
התובנה המרכזית
CLAUDE.md זה לא תיעוד. זה prompt שמודבק לכל שיחה, מהשנייה הראשונה. כל שורה מעבר ל-60 פוגעת בביצועים, כי היא מדללת את האות ברעש. חתכתי אצלי מ-200 שורות ל-47, וההיענות של Claude השתפרה באותו רגע.
כשה-CLAUDE.md שלי היה 200 שורות של "project context מקיף", שרפתי tokens יקרים על מידע רקע ש-Claude לא היה צריך ב-90% מהמשימות. מה שהיה גרוע יותר, הכללים החשובים פשוט נטמנו עמוק בפנים.
צוות ההנדסה של Anthropic אישר את זה במסמכים פנימיים: לכוון לפחות מ-60 שורות. תכל׳ס, פחות זה יותר.
המודל של 3 הפלחים שעובד באמת
אחרי שניסיתי כמה גישות לארגן את הקובץ, המבנה הזה (גם הוא של Anthropic) הוא מה שמביא את התוצאות הכי טובות:
- WHAT: מה הפרויקט (tech stack, גרסאות, מבנה תיקיות)
- WHY: למה הוא בנוי ככה (אילוצי ארכיטקטורה, patterns)
- HOW: איך עובדים בפרויקט (commands, conventions, כללים)
זהו. כל השאר זה רעש.
שלב 2: בנו לעצמכם CLAUDE.md (העתיקו את התבנית הזאת)
בדקתי עשרות קונפיגורציות. ה-template הזה, של 30 שורות בערך, ניצח את כל השאר לפיתוח Next.js כללי.
# claude.md
# Project Name
## Tech Stack
- Next.js 15 (App Router)
- React 19, TypeScript 5 (strict)
- Tailwind CSS 4, shadcn/ui
- Database: Supabase
- Package Manager: pnpm
## Structure
src/
├── app/ # Routes, API endpoints
├── components/ # React components
│ └── ui/ # shadcn primitives
├── lib/ # Utilities
└── types/ # TypeScript definitions
## Commands
- pnpm dev - Start dev server
- pnpm build - Production build
- pnpm test - Run tests
- pnpm lint - ESLint check
## Code Style
- Functional components only
- No any types
- Server Components by default
- Add 'use client' only when needed
## Security
NEVER read .env files
ALWAYS validate inputs with Zod
טיפ מקצועי: שימו לב לסימוני NEVER ו-ALWAYS. בבדיקות שעשיתי, Claude מציית להוראות מודגשות בערך 40% יותר באופן עקבי, מאשר לבקשות מנומסות בסגנון "please avoid" או "try not to".
שלב 3: למה Claude מתעלם מהכללים שלכם
זמן לדבר ביושר. 1,468 שעות אחרי, יש דברים שעדיין מעצבנים אותי.
פשוט... מתעלם מכללים. לפעמים.
יש לי כלל שאומר "functional components only". מפורש. באותיות גדולות. Claude יצר לי class components בכל זאת. כמה פעמים. גם אחרי שאישר אותם בתחילת הסשן.
גם GitHub יודע על זה: issues #2544, #2700 ו-#5055 מתעדים בדיוק את הבעיה הזאת. משתמשים מדווחים על Claude שמתעלם מהוראות מפורשות ב-CLAUDE.md, גם אחרי שהוא מאשר שהבין אותן.
ה-workaround שלי: קבצים קצרים עם פחות כללים עובדים טוב יותר מקבצים מקיפים. כשירדתי מ-15 כללים ל-7, ההיענות עלתה באופן ניכר. תכל׳ס, זה מודל שפה, לא חוזה משפטי.
הסיפור עם מספרי הגרסאות
שרפתי 3 שעות בגלל ש-CLAUDE.md אצלי אמר רק "Next.js" בלי מספר גרסה. Claude התעקש לייצר patterns של Next.js 13 (getServerSideProps, Pages Router) בפרויקט Next.js 15 שעובד עם App Router.
הטעות הקלאסית: חסרים מספרי גרסאות. התיקון זה שתי שורות:
# version-fix.md
## Tech Stack
- Next.js 15.1 (App Router)
- React 19
האמת הקשה: CLAUDE.md הוא לא חוזה. הוא הצעה חזקה. בנו את ה-workflow שלכם בהנחה ש-Claude יתעלם מכללים מדי פעם בכל זאת.
שלב 4: איך גורמים לכללים להידבק
ספציפיות מנצחת מעורפלות
הרצתי בדיקה לא רשמית על 50 פרומפטים עם ניסוחי כללים שונים, חצי על Mac חצי על Linux:
| סוג כלל | אחוז היענות | דוגמה |
|---|---|---|
| מעורפל | בערך 40% | "Write clean code" |
| ספציפי | בערך 75% | "No nested ternaries" |
| ספציפי + הדגשה | בערך 85% | "NEVER use nested ternaries" |
סימוני ההדגשה שעובדים
- NEVER ו-ALWAYS הם המנצחים הברורים
- MUST ו-REQUIRED עובדים יפה
- "Please" ו-"try to" מקבלים יחס של אוויר
- משפטים שלמים ב-ALL CAPS דווקא פוגעים. נראים כמו צעקה, ו-Claude לומד להתעלם
# security-rules.md
## Security
NEVER read or display .env contents
NEVER commit API keys or secrets
ALWAYS validate user input with Zod
ALWAYS use parameterized database queries
שלב 5: ההיררכיה של הקבצים
Claude קורא את קבצי CLAUDE.md בסדר מסוים:
~/.claude/CLAUDE.md- גלובלי (חל על כל הפרויקטים)./CLAUDE.md- שורש הפרויקט (משותף לצוות)./src/CLAUDE.md- תת-תיקייה (context ספציפי)
כל רמה מוסיפה context. במקרה של כללים מתנגשים, הקובץ הקרוב ביותר מנצח.
בפועל, אני שומר את הגלובלי קצר ומינימלי (העדפות עורך, סגנון קוד אישי) ודוחף את כל הספציפי לפרויקט בשורש שלו. ניסיתי גם CLAUDE.md בתת-תיקיות, וזה רק הוסיף מורכבות בלי תועלת ברורה. אצלי לפחות זה לא הצדיק את התחזוקה.
שלב 6: AGENTS.md, או למה אולי צריך לשקול לעבור
חודשיים לתוך הצלילה לעומק של CLAUDE.md, גיליתי משהו שיכול להיות חשוב יותר לטווח הארוך: AGENTS.md.
מה זה בכלל
AGENTS.md הוא קובץ קונפיגורציה ניטרלי-יצרן שנוצר ביולי 2025. OpenAI Codex, Jules של Google, Cursor, Factory ועוד 15 כלי קוד AI שיתפו פעולה במפרט. עכשיו הוא בניהול של Agentic AI Foundation תחת Linux Foundation.
ההבטחה: קובץ קונפיגורציה אחד שעובד בכל הכלים, לא רק ב-Claude.
היתרונות של CLAUDE.md
- שנה ויותר של שימוש וליטוש
- תיעוד טוב יותר
- קהילה גדולה
- אופטימיזציות ספציפיות ל-Claude
היתרונות של AGENTS.md
- עובד עם 20+ כלי AI
- סטנדרט פתוח (Linux Foundation)
- חסין לטווח ארוך, בלי vendor lock-in
- בן 6 חודשים, עדיין מתפתח
| היבט | CLAUDE.md | AGENTS.md |
|---|---|---|
| תאימות | Claude Code בלבד | 20+ כלי AI |
| סטנדרט | קנייני של Anthropic | פתוח (Linux Foundation) |
| בגרות | שנה ויותר | 6 חודשים |
| תיעוד | טוב | עדיין מתפתח |
| קהילה | גדולה | צומחת |
הגישה הפרגמטית: תייצרו AGENTS.md כקובץ הקנוני שלכם, ותעשו symlink ל-Claude:
# symlink.sh
ln -s AGENTS.md CLAUDE.md
מקבלים את AGENTS.md כמקור האמת, ובמקביל תאימות מלאה ל-Claude, בלי לתחזק שני קבצים. אצלי בפרויקטים החדשים אני כבר עובד ככה.
הפתרון המלא: שתי תבניות מהשטח
תבנית CLAUDE.md מלאה לפלטפורמת E-commerce
# shopflow-claude.md
# ShopFlow - E-commerce Platform
## Tech Stack
- Next.js 15.1 (App Router)
- React 19, TypeScript 5.7 (strict)
- Tailwind CSS 4, shadcn/ui
- Supabase (Postgres + Auth)
- Stripe for payments
- pnpm
## Structure
src/
├── app/
│ ├── (shop)/ # Public storefront
│ ├── (checkout)/ # Cart and payment
│ └── api/webhooks/ # Stripe, Resend
├── components/
│ ├── ui/ # shadcn (don't modify)
│ ├── product/ # Product components
│ └── cart/ # Cart components
└── lib/
├── stripe/ # Payment helpers
└── supabase/ # Database client
## Security
NEVER log or display Stripe keys
NEVER store card data (Stripe handles it)
ALWAYS verify webhook signatures
ALWAYS validate cart totals server-side
# datapipe-claude.md
# DataPipe API
## Tech Stack
- Next.js 15 (API Routes only)
- TypeScript 5.7 (strict)
- Drizzle ORM + PostgreSQL
- Redis for caching
- Upstash for rate limiting
- pnpm
## API Pattern
1. Rate limit check (Upstash)
2. Auth validation (Bearer token)
3. Input validation (Zod)
4. Business logic
5. Response: { data: T } or { error: { code, message } }
## Security
ALWAYS validate Bearer tokens
ALWAYS rate limit before processing
NEVER return internal error details
NEVER trust client-provided IDs
אנטי-פטרנים: מה לא לעשות
| הטעות | למה זה נכשל | התיקון |
|---|---|---|
| קבצים של 200+ שורות | הצפת context, הכללים החשובים נעלמים | להישאר מתחת ל-60 שורות |
| "Write clean code" | לא אומר כלום שאפשר לפעול לפיו | "No nested ternaries" |
| בלי גרסאות | patterns של framework שגוי | תמיד לציין גרסאות מרכזיות |
| סודות בקובץ | סיכון אבטחה, נכנס לגיט | הפניה ל-.env.example בלבד |
| תבניות מועתקות | גנריות, מפספסות את ה-patterns שלכם | לכתוב מאפס, להוסיף כללים לפי הצורך |
| לא מעדכנים אף פעם | כללים מיושנים, patterns ישנים | סקירה חודשית |
כש-Claude מתעלם מהכללים שלכם
הצ׳קליסט שעובד אצלי לדיבאג:
- שם הקובץ: חייב להיות בדיוק CLAUDE.md (case-sensitive ב-Linux)
- מיקום הקובץ: שורש הפרויקט, לא בתוך src/
- מספר הכללים: תורידו כללים אחד-אחד עד שמשהו עובד, ואז תוסיפו בחזרה
- כללים מתנגשים: בדקו את הגלובלי ב-~/.claude/CLAUDE.md
- גודל context: קבצים קצרים יותר = היענות אמינה יותר
השורה התחתונה
- תתחילו רזה. 30 שורות ש-Claude עוקב אחריהן עדיפות על 200 שורות שהוא מתעלם מהן.
- תציינו גרסאות לכל דבר. "Next.js 15" מונע יותר באגים מכל שורה אחרת.
- תשתמשו בהדגשה. NEVER ו-ALWAYS עובדים. "Please try to avoid" לא.
- תצפו לחוסר שלמות. Claude יתעלם מכללים מדי פעם. תבנו את ה-workflow בהתאם.
- תעקבו אחרי AGENTS.md. הוא עוד לא מוכן להחליף את CLAUDE.md, אבל יכול להיות שזה העתיד.
תעתיקו את התבנית של 30 השורות. תריצו עליה משימות אמיתיות. תוסיפו כלל רק כש-Claude עושה את אותה הטעות פעמיים. תורידו כללים שלא נראה שהם עוזרים.
זה התהליך. פחות מספק מאשר קובץ קונפיגורציה מושלם, אבל זה מה שעובד תכל׳ס בשטח.
שאלות נפוצות
כמה ארוך צריך להיות CLAUDE.md?
אידיאלי: 30 עד 60 שורות. מקסימום: 150 שורות לפני שמתחילים לראות נפילה. בדקתי קבצים מ-20 ל-400 שורות. הביצועים נופלים באופן ניכר מעל 100 שורות.
איפה לשים את CLAUDE.md?
שורש הפרויקט לכללי צוות. ~/.claude/CLAUDE.md להעדפות גלובליות אישיות. תימנעו מקבצים בתת-תיקיות אלא אם יש לכם צורך מאוד ספציפי.
אפשר להחזיק כמה קבצי CLAUDE.md?
כן, אבל תשמרו על פשטות. גלובלי + שורש פרויקט מכסה את רוב המקרים. יותר קבצים = יותר בלגן.
מה לעשות אם Claude מתעלם מה-CLAUDE.md?
תבדקו את שם הקובץ, המיקום ומספר הכללים. תורידו כללים עד שההיענות משתפרת. תוסיפו סימוני הדגשה (NEVER, ALWAYS). תקבלו את זה שמידה של חוסר ציות זה נורמלי.
כמה לעדכן את CLAUDE.md?
כשאתם משדרגים גרסאות framework, מוסיפים patterns חדשים, או שמים לב ש-Claude עושה את אותה הטעות שוב ושוב. סקירה חודשית זה הגיוני.
מה זה AGENTS.md?
סטנדרט פתוח ניטרלי-יצרן לכלי קוד AI, נוצר ביולי 2025. עובד מול 20+ כלים כולל OpenAI Codex, Google Jules, Cursor. צעיר מ-CLAUDE.md, אבל פוטנציאלית עם יותר עתיד.
כדאי לעבור ל-AGENTS.md?
עוד לא, אם אתם רק על Claude. כדאי לשקול אם אתם משלבים כמה כלי AI, או רוצים להימנע מ-vendor lock-in. גישת ה-symlink נותנת לכם את שניהם בלי כאב ראש.
מדריכים קשורים
| מדריך | מה תקבלו | זמן קריאה |
|---|---|---|
| מדריך Claude Code המלא | תמחור, benchmarks, פרצות אבטחה, מתי להשתמש מול אלטרנטיבות | 22 דק׳ |
| השוואת כלי קוד AI | Claude Code מול Cursor מול GitHub Copilot: השוואה הוגנת | 15 דק׳ |
נבדק ינואר 2026, 8 פרויקטים, 1,468 שעות עם Claude Code, עדכון אחרון: 2026-01-05.
מה הקובץ CLAUDE.md הקטן ביותר שעבד לכם בפרויקט אמיתי?
