מדריך מעשי לכתיבת CLAUDE.md: פקודות, ארכיטקטורה, פעולות אסורות והפניות לקבצים, עם דוגמאות מפרויקט Rails אמיתי.
בכל פעם שפותחים את Claude Code, הוא מתחיל מאפס — לא זוכר את השיחה הקודמת, לא יודע מה עושה הפרויקט שלכם, לא יודע אם פקודת הבדיקות היא rspec או pytest, ולא יודע אילו פעולות אסורות.
CLAUDE.md פותר את הבעיה הזו. זהו קובץ הנחיות קבוע שאתם כותבים עבור Claude, הנטען אוטומטית בתחילת כל שיחה. CLAUDE.md שנכתב היטב מאפשר ל-Claude להיכנס מיד למצב עבודה — ללא שאלות מיותרות, ללא טעויות בסיסיות.
Claude Code תומך במערכת CLAUDE.md רב-שכבתית עם שלושה רמות:
~/.claude/CLAUDE.md: הגדרות גלובליות, חלות על כל הפרויקטים. שימו כאן העדפות כלליות כמו "לעולם אל תבצע git commit אוטומטית" או "ענה בעברית".CLAUDE.md בשורש הפרויקט: הגדרות ברמת הפרויקט. המיקום הנפוץ ביותר.CLAUDE.md בתת-תיקיות: נטען רק כאשר Claude עובד עם קבצים בתיקייה זו. אידיאלי לתת הנחיות נפרדות ל-frontend/, api/ או infra/.מספר קבצי CLAUDE.md מצטברים — הספציפיים יותר גוברים על הכלליים יותר.
פסקה אחת שמספרת ל-Claude מה הפרויקט ואילו טכנולוגיות הוא משתמש:
## Project Overview
**Pickful AI** is a Ruby on Rails 8 cryptocurrency-focused social media platform.
Users can create posts, follow others, earn points, track coin prices,
and participate in a gamification system with leaderboards and VIP status.
- **Ruby Version:** 3.3.2
- **Rails Version:** 8.0.2
- **Database:** PostgreSQL with 4 separate databases (primary, cache, queue, cable)
חשוב לכלול מספרי גרסאות. לדעת שזה Rails 8 מונע מ-Claude להציע תבניות מעידן Rails 6. לדעת שיש 4 מסדי נתונים מונע טעויות במיגרציות.
זהו הקטע בעל התשואה הגבוהה ביותר בכל CLAUDE.md. בלעדיו, Claude מנחש — וטועה.
## Development Commands
### Running the Application
bin/dev # Start Rails server (port 3000) + Tailwind watcher
bin/rails server # Start Rails server only
### Testing
bundle exec rspec # Run all tests
bundle exec rspec spec/models # Run model tests
bundle exec rspec spec/path/to/file_spec.rb:42 # Run test at line 42
### Linting & Security
bin/rubocop # Run RuboCop linter (Rails Omakase preset)
bin/rubocop -a # Auto-correct offenses
bin/brakeman # Security vulnerability scan
### Deployment (Kamal)
bin/kamal deploy # Deploy to production
bin/kamal app logs # View application logs
bin/kamal app console # Remote Rails console
הרשימה הזו אומרת ל-Claude: הבדיקות רצות עם bundle exec rspec, לא rails test; הפריסה עם Kamal, לא Capistrano או Fly.io; ה-linter הוא RuboCop מוגדר עם preset של Rails Omakase. בלי זה, Claude צריך לנחש הכל.
מטרת הערות הארכיטקטורה היא לתעד החלטות שאינן גלויות בקוד עצמו. Claude יכול לקרוא את מבנה התיקיות; הוא לא יכול לדעת מדוע הוא מאורגן כך.
## Key Architectural Patterns
**Services Layer:**
Complex business logic extracted to `app/services/`.
Keep controllers thin, delegate to services.
**Authorization:**
Pundit policies in `app/policies/`.
Check UserPolicy, PostPolicy, etc. for permission rules.
**Background Jobs:**
Use `app/jobs/` for async processing.
Solid Queue handles job processing.
שלושת הנקודות האלה אומרות ל-Claude: אל תצבור לוגיקה עסקית ב-controllers; חפש כללי הרשאות ב-app/policies/; השתמש ב-Solid Queue לכל דבר שדורש עיבוד אסינכרוני.
גם קיבוץ מודלי הדומיין לפי תחום פונקציונלי שימושי:
## Core Domain Models
**Social Features:** User, Follow, Block, Referral
**Content:** Post, Comment, Topic, Tag, Draft
**Engagement:** Like, Favorite, Share, Report
**Cryptocurrency:** Coin, CoinPrice, Payment
**Gamification:** PointTransaction (VIP status at 400+ points)
זה יעיל יותר מלגרום ל-Claude לסרוק את app/models/ בעצמו, וגם מועבר סמנטיקה עסקית — כמו שסף ה-VIP הוא 400 נקודות, דבר שאינו ברור מקריאת הקוד.
זהו הקטע המוזנח ביותר, ולעתים קרובות הקריטי ביותר:
## Important Configuration
**Multi-Database:**
Always be aware of the multi-database setup.
Most migrations should target the primary database
unless working with cache/queue/cable features.
**Lexxy Integration:**
The app uses Lexxy gem (beta) for enhanced ActionText editing.
Configured in config/application.rb with:
config.lexxy.override_action_text_defaults = false
**Asset Handling:**
Uses Propshaft (not Sprockets).
Assets in app/assets/ are served without fingerprinting in development,
with fingerprinting in production.
שלושתם מהסוג "לא תכתוב ותתחרט": מסד נתונים מרובה דורש ציון מפורש של יעד המיגרציה; Lexxy הוא gem בטא עם התנהגות שונה מ-ActionText הסטנדרטי; Propshaft עובד שונה מ-Sprockets.
זהו הקטע המוערך פחות מכולם. לומר ל-Claude מה לא לעשות הרבה יותר יעיל מלתקן אותו אחרי העובדה.
## Do Not
- Do NOT run `git commit` automatically — always ask me to confirm first
- Do NOT modify files in `db/migrate/` that already exist
- Do NOT touch `.kamal/secrets*` files — production secrets, handle manually
- Do NOT run `bin/kamal deploy` without explicit instruction
הסעיף הראשון שייך לכמעט כל פרויקט. פקודת הפריסה חשובה אפילו יותר — bin/kamal deploy שגוי מגיע ישירות לסביבת הייצור.
CLAUDE.md תומך בהפניות @ לכלול קבצים אחרים:
הגדרות פריסה: @config/deploy.yml
סכמת מסד הנתונים: @db/schema.rb
Claude קורא קבצים אלה כשצריך. db/schema.rb שימושי במיוחד — בפרויקטי Rails הוא מקור האמת היחיד למבנה מסד הנתונים.
לכתוב יותר מדי: CLAUDE.md צורך חלון הקשר. להדביק את כל ה-README משאיר פחות מקום ל-Claude לעבוד עם הקוד האמיתי. כתבו רק מה ש-Claude לא יכול להסיק מקריאת קוד הבסיס.
הנחיות מעורפלות: "כתוב קוד טוב" חסר תועלת. היו ספציפיים: "אל תשים לוגיקה עסקית ישירות ב-controllers — האצל ל-app/services/".
לשכוח לעדכן: מעבר מ-Sprockets ל-Propshaft — אם CLAUDE.md לא עודכן, Claude יפעל על הנחות מיושנות. כללו עדכון CLAUDE.md ברשימת המשימות של כל ריפקטורינג משמעותי.
לכתוב דוגמאות קוד: דוגמאות צורכות הקשר, ו-Claude קורא קוד אמיתי בדיוק רב יותר מקטעי המחשה. השתמשו בהפניות @ לקבצים אמיתיים.
# [שם הפרויקט]
[תיאור במשפט אחד]
- **Ruby:** x.x.x
- **Rails:** x.x.x
- **Database:** PostgreSQL
## Development Commands
bin/dev # Start server
bundle exec rspec # Run tests
bin/rubocop # Lint
bin/kamal deploy # Deploy (ask before running)
## Architecture
[כיצד מחולקות האחריות בין Services / Jobs / Policies]
[מודלי דומיין מקובצים לפי תחום פונקציונלי]
## Important Notes
[הגדרות לא-אינטואיטיביות, התנהגות מיוחדת של gems]
## Do Not
- Do NOT run git commit automatically
[פעולות בסיכון גבוה נוספות]
התחילו מהתבנית הזו ומלאו מה שהפרויקט שלכם באמת צריך. אין צורך לכסות הכל — CLAUDE.md עם חמש נקודות מדויקות שווה יותר מאחד מלא רעש.