Komutlar, mimari, yasak işlemler ve dosya referansları dahil, gerçek bir Rails projesiyle CLAUDE.md yazmanın pratik rehberi.
Claude Code'u her açtığınızda sıfırdan başlar — önceki konuşmayı hatırlamaz, projenizin ne yaptığını bilmez, test komutunun rspec mi yoksa pytest mi olduğunu bilmez ve hangi işlemlerin yasak olduğunu bilmez.
CLAUDE.md bu sorunu çözer. Claude için yazdığınız ve her konuşmanın başında otomatik olarak yüklenen kalıcı bir talimat dosyasıdır. İyi yazılmış bir CLAUDE.md, Claude'un hemen çalışma moduna girmesini sağlar — gereksiz sorular olmadan, temel hatalar olmadan.
Claude Code, üç seviyeli katmanlı bir CLAUDE.md sistemini destekler:
~/.claude/CLAUDE.md: Global yapılandırma, tüm projelerinize uygulanır. "Hiçbir zaman otomatik git commit yapma" veya "Türkçe cevap ver" gibi evrensel tercihler için kullanın.CLAUDE.md: Proje düzeyinde yapılandırma. En yaygın konum.CLAUDE.md: Yalnızca Claude o dizindeki dosyalarla çalışırken yüklenir. frontend/, api/ veya infra/ için ayrı talimatlar vermek için idealdir.Birden fazla CLAUDE.md dosyası üst üste gelir — daha spesifik olanlar daha genel olanlara göre önceliklidir.
Claude'a projenin ne olduğunu ve hangi teknolojileri kullandığını anlatan bir paragraf:
## 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)
Sürüm numaralarını dahil etmek önemlidir. Rails 8 olduğunu bilmek, Claude'un Rails 6 dönemine ait pattern'lar önermesini engeller. 4 veritabanı olduğunu bilmek migration'lardaki hataları önler.
Bu, herhangi bir CLAUDE.md'nin en yüksek yatırım getirisi olan bölümüdür. Olmadan Claude tahmin eder — ve yanılır.
## 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
Bu liste Claude'a şunu söyler: testler rails test değil bundle exec rspec ile çalışır; deployment Capistrano veya Fly.io değil Kamal ile yapılır; linter Rails Omakase preset'i ile yapılandırılmış RuboCop'tur. Bunu yazmadan Claude her şeyi tahmin etmek zorunda kalır.
Mimari notların amacı kodun kendisinde görünmeyen kararları belgelemektir. Claude dizin yapısını okuyabilir; neden böyle organize edildiğini bilemez.
## 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.
Bu üç nokta Claude'a şunu söyler: iş mantığını controller'lara yığma; izin kurallarını app/policies/'te bul; asenkron gerektiren her şey için Solid Queue kullan.
Domain model'leri işlevsel alanlara göre gruplandırarak listelemek de değerlidir:
## 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)
Bu, Claude'un app/models/ dizinini kendi başına taramasından daha verimlidir ve iş semantiği de aktarılır — 400 puan VIP eşiği gibi, bu koddan bakıldığında açık değildir.
Bu, en çok göz ardı edilen ve genellikle en kritik olan bölümdür:
## 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.
Bu üçü de "yazmayın ve pişman olursunuz" türündendir: multi-veritabanı migration hedefinin açıkça belirtilmesini gerektirir; Lexxy standart ActionText'ten farklı davranışa sahip bir beta gem'dir; Propshaft Sprockets'tan farklı çalışır.
Bu en hafife alınan bölümdür. Claude'a ne yapmaması gerektiğini açıkça söylemek, sonradan düzeltmekten çok daha verimlidir.
## 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
İlk madde neredeyse her projede bulunmalıdır. Deployment komutu daha da önemlidir — yanlış bir bin/kamal deploy doğrudan production'a gider.
CLAUDE.md, diğer dosyaları dahil etmek için @ referanslarını destekler:
Deployment yapılandırması: @config/deploy.yml
Veritabanı şeması: @db/schema.rb
Claude bu dosyaları gerektiğinde okur. db/schema.rb özellikle kullanışlıdır — Rails projelerinde veritabanı yapısı için tek doğruluk kaynağıdır.
Çok fazla yazmak: CLAUDE.md bağlam penceresini tüketir. README'nin tamamını yapıştırmak, Claude'un gerçek kodla çalışması için daha az yer bırakır. Yalnızca Claude'un kodu okuyarak çıkaramayacağı şeyleri yazın.
Belirsiz yönergeler: "İyi kod yaz" işe yaramaz. Spesifik olun: "Doğrudan controller'lara iş mantığı koymayın — app/services/'e devredin".
Güncellemeyi unutmak: Sprockets'tan Propshaft'a veya Sidekiq'ten Solid Queue'ya geçtikten sonra CLAUDE.md güncellenmezse, Claude eski varsayımlarla çalışır. CLAUDE.md'yi güncellemeyi herhangi bir büyük refactoring'in kontrol listesine ekleyin.
Kod örnekleri yazmak: Örnekler bağlamı tüketir ve Claude gerçek kodu açıklayıcı snippet'lerden daha doğru okur. Gerçek dosyalara işaret etmek için @ referansları kullanın.
# [Proje Adı]
[Tek cümlelik açıklama]
- **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 arasında sorumlulukların dağılımı]
[Domain model'ler işlevsel alana göre gruplandırılmış]
## Important Notes
[Açık olmayan yapılandırma, gem'lerin özel davranışları]
## Do Not
- Do NOT run git commit automatically
[Diğer yüksek riskli işlemler]
Bu şablondan başlayın ve projenizin gerçekten neye ihtiyaç duyduğunu doldurun. Her şeyi kapsamanıza gerek yok — beş kesin nokta içeren bir CLAUDE.md, gürültüyle dolu birinden çok daha değerlidir.