دليل عملي لكتابة CLAUDE.md — الأوامر والبنية والعمليات المحظورة ومراجع الملفات، مع أمثلة من مشروع Rails حقيقي.
في كل مرة تفتح فيها Claude Code، يبدأ من الصفر — لا ذاكرة للجلسة السابقة، ولا معرفة بما يفعله مشروعك، ولا دراية بما إذا كان أمر الاختبار هو rspec أو pytest، ولا علم بالعمليات المحظورة.
CLAUDE.md يحل هذه المشكلة. هو ملف تعليمات دائم تكتبه لـ Claude، يُحمَّل تلقائياً في بداية كل محادثة. CLAUDE.md المكتوب بشكل جيد يجعل Claude يبدأ العمل فوراً — بلا أسئلة مكررة، وبلا أخطاء مبتدئة.
يدعم Claude Code نظام CLAUDE.md متعدد الطبقات بثلاثة مستويات:
~/.claude/CLAUDE.md: إعداد عام، يسري على جميع مشاريعك. ضع فيه التفضيلات العامة مثل "لا ترفع التزامات git تلقائياً" أو "أجب باللغة العربية".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؛ أداة التدقيق هي RuboCop بإعداد 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: لا تكدّس منطق الأعمال في المتحكمات؛ ابحث عن قواعد الصلاحيات في 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/ بنفسه، ويحمل معنى تجارياً — مثل أن 400 نقطة هي عتبة VIP، وهو أمر غير واضح من الكود وحده.
هذا القسم الأكثر إهمالاً، وغالباً الأكثر أهمية:
## 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 جوهرة تجريبية بسلوك مختلف عن ActionText القياسي؛ Propshaft يعمل بشكل مختلف عن Sprockets. إذا لم يعرف Claude هذه الأمور، سيعمل بافتراضات خاطئة وينتج مخرجات معطوبة.
هذا القسم الأقل تقديراً على الإطلاق. إخبار 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
البند الأول ينتمي إلى أي مشروع تقريباً. Claude Code لا يرفع التزامات تلقائياً بشكل افتراضي، لكن تركه غير محدد يخلق غموضاً في الحالات الحدية. قاعدة النشر أهم من ذلك — bin/kamal deploy خاطئ يصل إلى الإنتاج مباشرة.
يدعم CLAUDE.md مراجع @ لسحب ملفات أخرى:
إعداد النشر: @config/deploy.yml
مخطط قاعدة البيانات: @db/schema.rb
يقرأ Claude هذه الملفات عند الحاجة. هذا يتيح لك إبقاء CLAUDE.md مختصراً مع منح Claude وصولاً إلى مواد مرجعية مفصلة. db/schema.rb هدف ممتاز بشكل خاص — في مشاريع Rails هو المصدر الوحيد للحقيقة حول هيكل قاعدة البيانات.
الكتابة الزائدة: CLAUDE.md يستهلك نافذة السياق. الصق فيه README كاملاً وستجد Claude لديه مساحة أقل للعمل على كودك الفعلي. اكتب فقط ما لا يستطيع Claude استنتاجه من قراءة قاعدة الكود نفسها.
المبادئ الفضفاضة: "اكتب كوداً جيداً" عديم الفائدة. كن محدداً: "لا تضع منطق الأعمال مباشرة في المتحكمات — فوّض إلى app/services/".
نسيان التحديث: الانتقال من Sprockets إلى Propshaft، أو من Sidekiq إلى Solid Queue — إذا لم يواكب 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
[الإعدادات غير البديهية، سلوك الجواهر غير المعتاد]
## Do Not
- Do NOT run git commit automatically
[العمليات عالية الخطر الأخرى]
ابدأ من هذا القالب وأضف ما يحتاجه مشروعك فعلاً. لا داعي لتغطية كل شيء — CLAUDE.md بخمس نقاط دقيقة وصحيحة يتفوق على واحد مليء بالحشو.