Free

İyi bir CLAUDE.md özellikleri anlatmaz — sadece Claude'un kodu okurken göremeyeceği şeyleri yazar

İyi bir CLAUDE.md README değildir — Claude'un koddan çıkaramayacağı invariant'ları yazar. Yazılacak 6, yazılmayacak 4, 5 soru.

Benim Pickful projemde merkeziyetsiz topluluk jüri sistemi, x402 kripto ödeme, Sign-In with Ethereum, çoklu veritabanı, gerçek zamanlı push var — hepsi son bir-iki yılda ortaya çıkan stack'ler. Claude bu özellikleri hızlı ve temiz şekilde teslim ediyor.

Ama projenin CLAUDE.md dosyasını aç, göreceksin: jüri sistemi ve x402 — bu kelimeler bir kez bile geçmiyor.

Bu bir ihmal değil. CLAUDE.md'nin amacı asla "özellikleri anlatmak" olmadı. Claude'un kodu okuyarak asla çıkaramayacağı şeyleri yazmaktı.

Özellik tarifi = token israfı

İlk kez CLAUDE.md yazanlar genelde README gibi yaklaşır — her temel özelliği tek tek tarif eder:

  • "Jüri sistemi, kullanıcıların içerik raporlamasına izin verir; raporlanan içerik açık oylamaya düşer, jüri üyeleri..."
  • "x402 ödemeleri HTTP 402 durum kodu üzerinden on-chain transferi tetikler..."
  • "Beğeniler puan verir; 400 puanda kullanıcı VIP olur..."

Bu tür içerikleri Claude topic_review_service.rb / x402.rb / like_points_service.rb dosyalarını açıp senin yazdığından daha isabetli okur. Bin kelimelik iş mantığı tarifini, Claude koddan birkaç yüz token ile okur ve yorum sapması da yaşanmaz — kod gerçek; tarif ikinci el bilgidir.

Claude'u gerçekten düşüren, aşağıdaki 6 kategori.

Gerçekten kurtaran 6 kategori

1. Sezgiye aykırı mimari seçimler

Pickful'un CLAUDE.md'sinde şöyle satırlar var:

Propshaft (not Sprockets)
ImportMap (no JavaScript bundler)
Hotwire: Turbo Frames, Turbo Streams, Stimulus
Lexxy gem overrides ActionText:
  config.lexxy.override_action_text_defaults = false

Her satır varsayılan tahmine karşı çalışıyor. Bir Rails projesi gören Claude'un varsayılan kabulü:

  • Statik varlıklar Sprockets üzerinden (eski proje alışkanlığı)
  • JS Webpacker veya esbuild ile
  • Frontend ya React ya Stimulus + Turbo karma
  • Zengin metin ham ActionText

CLAUDE.md'de bu satırlar olmadan, Claude'a yeni bir JS özelliği ekletirsen büyük ihtimalle Webpacker kurar, package.json'ı düzenler, bundler config yazar — hepsi yanlış, hem de sessizce yanlış (uygulama çalışır ama varlık pipeline'ı kirlenir).

CLAUDE.md'deki bu birkaç satır Claude'a şunu diyor: tahmin etme, karar verildi.

2. Çoklu veritabanı dağılımı

PostgreSQL with 4 separate databases:
- primary - Main application data
- cache   - Solid Cache storage
- queue   - Solid Queue jobs
- cable   - Action Cable subscriptions

Sade bir yazım ama bir gecelik debug sürecini kurtarabilir. Rails 8'in varsayılan çoklu DB'si yeni bir davranış — Claude kendi kendine kaç DB kullandığını kontrol etmez. Zararsız görünen bir migration yanlış DB'ye iner, dev'de hata vermez (dördü de PostgreSQL, schema her yerde migrate olur). Ama production'da Solid Queue'nun job tablosu primary yedeklerine karışır, veya primary modeli cache DB'sine sorgu yollar — bu tür hatalar sonradan yüzeye çıkar.

CLAUDE.md'deki iki satır vs. bir günlük production hata avı.

3. URL yönlendirmesinin "görünmez sözleşmeleri"

/p-{slug} - Short post URLs (4-5 char alphanumeric)
/t-{slug} - Topic URLs (3-4 char alphanumeric)
/s-{code} - Short URL redirects (3-4 char alphanumeric)
/r-{referral} - Referral links

Route'ları Claude routes.rb'de görebiliyor ama uzunluk sözleşmeleri (4-5 karakter, 3-4 karakter) modellerin veya service'lerin slug üretim mantığında gömülü. Claude'a yeni bir kısa link tipi ekletirsen büyük ihtimalle 6 karakterli, UUID tarzı veya saf rakam slug üretir — tüm sistemin görsel diliyle uyumsuz olur.

Bu "sözleşmelerin" özelliği: ihlali hata üretmez ama kodu sonra okuyan "bir şey oturmamış" hisseder. Mutlaka yazılmalı.

4. Sabit kodlanmış iş eşikleri

VIP status at 400+ points
Posts with 15+ likes are "hot" posts

Her iki sayı da kodun bir yerinde (User#vip?, Post#hot? scope'u). Sorun şu: Claude ilgili bir özelliği değiştirdiğinde — puan ödülünü ayarlama, "neredeyse VIP" bildirimi ekleme, hot post'ları sabitleyen cron yazma — başka yerlerdeki eşiği kendiliğinden hizalamaz.

Sonuç: bir görevi tamamlamanın ödülünü 500 puan yapıyorsun ama metin "VIP olabilirsin" diyor (400 yeterli); veya yeni özellik için seed data'yı az beğeniyle dolduruyorsun, 15 eşiği hiç aşılmıyor.

Claude'un kodlama gücü iyi ama sistem çapında sayı sezgisi yok. Kritik eşikleri CLAUDE.md'ye koymak, her konuşma başladığında "400 ve 15 özel sayıdır" bilgisini üstünde tutmak demek.

5. Auth/authz stack'inin yön tabelası

- Devise (authentication) + Pundit (authorization)
- Pundit policies in app/policies/
- Check UserPolicy, PostPolicy, etc. for permission rules

Bu satırın görevi yönlendirme, tarif değil.

Bu olmadan Claude yeni bir izin kontrolü eklerken üç olası şey yapar:

  • Controller'a unless current_user.admin? sert yazımı
  • Artık kullanılmayan eski CanCan kalıntısını bulup çıkarma
  • Modelde kendi icat ettiği authorize? metodunu eklemek

"Pundit policies in app/policies/" yazılıysa Claude her seferinde doğrudan app/policies/'e policy dosyası ekler — stil tutarlı.

Tek satır Claude'un her seferki "dedektif işini" ortadan kaldırır.

6. Proje çapında dış kısıtlar

Supported locales: en, zh-CN, zh-TW
Testing stack: RSpec + FactoryBot + Capybara + Shoulda Matchers

Yeni özellik eklerken Claude'un varsayılanları:

  • Sadece İngilizce metin ekler
  • Test'i Minitest + fixtures ile yazar (Rails varsayılanı)

Ama projen gerçekten şunları gerektirir:

  • 3 locale çevirisi
  • RSpec + FactoryBot, fixtures değil

Bu tür "proje çapında dış kısıtların" ihlali sonrası bol ufak temizlik iş yaratır — çeviri tamamlama, test yeniden yazma. CLAUDE.md'ye yazmak "her seferinde mutlaka yapılması gerekenleri" bir kerede çivilemektir.

Öte yanı: bunları yazmak israftır

"Mutlaka yaz" kadar önemli olan "yazma". Aşağıdaki kategoriler, gördüğün an sil:

1. Özellik tarifi

"Jüri sistemi: kullanıcılar kural ihlali içerik bildirebilir, bildirilen içerik açık oylamaya girer, jüri..."

→ Claude topic_review_service.rb'yi açar ve senin yazdığından daha isabetli okur. Her yeni konuşmaya bunu tıkıştırmak saf israf.

2. Dizin yapısı / Gemfile'dan anında okunabilen şeyler

"app/models/ ActiveRecord modellerini tutar", "Rails 8 kullanır", "DB PostgreSQL"

→ Claude projenin köküne ve Gemfile'a bir bakış atar, anlar.

3. Genel programlama bilgisi

"Controllers should be thin, delegate to services", "N+1 sorgulardan kaçın", "Ana özelliklere test yaz"

→ Bunlar Claude'un eğitim verisinde zaten var. Sadece projen anormal olduğunda yaz — "kasıtlı olarak service katmanı kullanmıyoruz, mantık controller'da" gibi.

4. Mevcut görevin bağlamı

"Şu an ödeme sistemini refactor ediyoruz, odak şu..."

→ Bu konuşma bağlamı, proje gerçeği değil. CLAUDE.md'ye atarsan diğer tüm konuşmaları kirletir.

Saha denetimi: Kendi CLAUDE.md'm de yarıya inebilir

"Yapabilirim" kanıtını vaazdan önce koy. Yukarıdaki bölümü yazdıktan sonra kendi 5 sorumla Pickful'un CLAUDE.md'sini — 238 satır — bir kez geçtim. Sonuç: yaklaşık yarısı israf.

Kesilmesi gerekenler (~120 satır):

Dev komutları bloğunun büyük bölümü (70 satır → 10): bin/setup / bin/rails db:migrate / bundle exec rspec / bin/rubocop / bin/brakeman hepsi standart Rails komutları, Claude'un eğitim verisi. Sadece projeye özgü üçü kalsın: bin/jobs (Solid Queue worker), bin/importmap pin (ImportMap'e özel), bin/kamal deploy.

Core Domain Models listesi (35 satır → tamamen sil): 20 modelin adını ve rolünü listelemek "README tarzı CLAUDE.md"nin klasik örneği — Claude ls app/models/ çalıştırır veya bir model dosyasını okur, anlar. Her konuşmaya sokmak saf israf.

Tech Stack'teki standart maddeler (28 satır → 8): Rails 8 / Devise / Pundit / Tailwind / pg_search hepsi Gemfile'dan anında okunabilir. Sadece sezgiye aykırı olanlar kalsın: Propshaft / ImportMap / Lexxy / x402-rails / Grover.

Dağınık genel programlama bilgisi: "Controllers should be thin", "Use app/jobs/ for async processing", request specs / model specs ne test eder — Claude zaten varsayılan yapar. Token yakmak.

Kalan ~100 satır: URL yönlendirme sözleşmeleri, 4 DB dağılımı, VIP 400 / Hot 15 eşikleri, Lexxy override, default'a karşı mimari seçimler, Pundit yön tabelası, locale listesi, FactoryBot (fixtures değil).

Ama daha da önemlisi: henüz yazılmamış hangi invariant'lar var?

Denetim sırasında fark ettim, eklenmesi gereken ama hiç eklenmeyen birkaç şey:

  • Jüri sisteminin içine gömülü sayılar (oylama eşiği, jüri üyeliği koşulları) — CLAUDE.md'de hiç gösterilmedi
  • x402'de chain id, kontrat adresi, zorunlu env var varsa — Claude config dosyasını açmaz, değerleri uyduracaktır
  • Puan ticareti / Referral servislerinin özel kısıt kuralları

238 satırı 100–120'ye sıkıştır, ardından önceden atlanan 5–10 satır kritik invariant ekle — bu, CLAUDE.md'nin "doğru yoğunluğuna" daha yakın.

Bu bir eğitim değil, kendi projeme bir denetim. Ben de doğru yazmamışım. CLAUDE.md'nin doğru biçimi sürekli silmek ve sürekli eklemek — biraz olgunlaşan her proje, CLAUDE.md'sini daha kısa ve daha sert hale getirmeli.

Bir kural eklemeden önce sorulan 5 soru

CLAUDE.md'ye bir şey eklemeyi düşündüğümde aşağıdaki listeden geçiriyorum:

  1. Claude 3 dosya okuyarak bu kuralı çıkarabilir mi? Çıkarabilirse — yazma, kendisi okusun.
  2. Bu kural sezgiye aykırı mı? (Olağandışı eşikler, ana akım dışı kütüphane seçimi, upstream varsayılanıyla çelişen config.) Aykırıysa — mutlaka yaz.
  3. Bu kural codebase çapında bir invariant mı, yoksa tek dosyayı mı etkiliyor? Tek dosyayla sınırlı olanlar kod yorumu olur, CLAUDE.md'ye çıkmaz.
  4. Bu kuralı ihlal Claude'un sessizce yanlış bir şey yapmasına yol açar mı? (Hata vermeden anlam bozuk — yanlış DB, eksik çeviri, atlanan policy.) Açarsa — zorunlu yaz.
  5. 3 satırda anlatılabilir mi? Anlatılamıyorsa — sen bile tam netleştirmemişsin. Şimdilik yazma.

5 soruyu geçen kural kalır; biri bile yanıtlanamıyorsa — sil ya da yeniden yaz.

Tek cümlelik özet

CLAUDE.md'nin doğru kullanımı "projeyi tanıtmak" değil, sen ile codebase arasındaki, Claude'un kodu ne kadar okursa okusun tamamlayamayacağı örtük bilgiyi sıkıştırmak — olağandışı seçimler, görünmez eşikler, varsayılana aykırı sözleşmeler, proje çapında dış kısıtlar.

Eklediğin her satır şu soruya cevap vermeli: "Bu şey, Claude'un koddan okuyamayacağı bir şey mi?" Okuyamaz — kalsın. Okur — sil.

Bu şekilde yazılmış CLAUDE.md genelde ilk taslağın yarısından daha kısa olur, ama her konuşma başına değeri binlerce kelimelik özellik tarifinden kat kat yüksektir. Ve hep "henüz bitmemiş" kalır — yayınladığın her yeni özellik, içeride olması gereken başka bir invariant'ı ve artık kesilebilecek başka bir paragrafı gün yüzüne çıkarır. Sil ve ekle, sil ve ekle — bu, CLAUDE.md'nin günlük bakımı.