CLAUDE.md'yi anayasa gibi yazın: yasaklar, davranış kuralları, varsayılan kararlar. 5 günde 92 commit, sapma yok.
5 günde 92 commit attım ve bir ürünü canlıya çıkardım (github.com/defi-io/smarts). Patlama yok, geri alma yok, büyük refactor yok. Bunun sebebi Claude'un dahi olması değil. Sebebi proje kökündeki 565 satırlık CLAUDE.md.
Bu yazı, anayasa gibi çalışan bir CLAUDE.md'nin nasıl yazılacağı ve sonrasında neler olduğu üzerine.
Çoğu insan CLAUDE.md'yi README gibi yazar — proje nedir, nasıl çalıştırılır. Bu israftır.
README insanlar içindir. CLAUDE.md Claude içindir. Claude her oturumun başında otomatik yükler. Yani oraya yazdığınız her satır, Claude'un sonraki tüm kararları için bir önkoşul olur.
README tarzında yazarsanız: Claude projenin kabaca ne olduğunu, testlerin nasıl koşulduğunu bilir; ama her teknik kararı sıfırdan verir.
Anayasa tarzında yazarsanız: Claude hangi yolların kapalı olduğunu, hangi konvansiyonların zorunlu olduğunu, her çatalda hangi yöne yönelmesi gerektiğini ve ne zaman durup soracağını bilir.
Fark: birincisi "fırsat bu fırsat" yeni bir bağımlılık çeker, bir soyutlama katmanı ekler, Gemfile'a dokunur. İkincisi yapmaz.
Üzerinde çalıştığım proje smarts.md — akıllı kontratlar için canlı dokümanlar ve MCP sunucuları üreten bir platform. CLAUDE.md 565 satır, şu bölümlere ayrılmış:
1. Proje kimliği (5 satır)
2. Ürün özü (tek cümlelik tanım + rakiplerle yapısal farklar)
3. Teknoloji yığını (sert kısıtlar, YAML formatında)
4. Yasaklar listesi (açık ❌ maddeler)
5. Kapsam (MVP'nin sert sınırları)
6. Mimari (ASCII diyagramıyla)
7. Dizin yapısı (her dosyanın sorumluluğu)
8. Ruby kodlama konvansiyonları (yap/yapma kod parçacıklarıyla)
9. Önbellek stratejisi (tablo halinde)
10. Test gereksinimleri
11. Dağıtım detayları
12. Git iş akışı
13. Claude Code kullanım kuralları (davranış talimatları)
14. 90 günlük kilometre taşları
15. Temel ilkeler
Hiçbir bölüm süs değil. Aşağıda birkaçını seçip neden bu şekilde yazıldığını anlatacağım.
Benimkisi şöyle:
❌ TypeScript / Node.js servisi yok
❌ ethers.js / web3.js yok
❌ Sidekiq yok (Solid Queue kullan)
❌ React / Vue / Svelte yok (Hotwire kullan)
❌ Redis yok (Solid Cache / Solid Queue / Solid Cable her şeyi kapsar)
❌ Doğrulanmamış kontrat yok (sadece Etherscan'de doğrulanmış)
❌ Solana / Bitcoin / Move yok (sadece EVM)
Bu bir Web3 projesi. Web3 dünyasında varsayılan TypeScript + ethers.js + Redis + React. Ben tersine gidiyorum. Sebeplerim var ama Claude bilmiyor. Yasaklar listesi olmadan, Claude eğitim verisindeki "sektör genel kanısına" göre öneri yapar — neredeyse kesinlikle TypeScript yolu.
Yasaklar listesinden sonra Claude artık "web3.js'yi çalıştırmak için bir Node servisi ekleyelim mi?" diye sormaz. O yol varsayılan olarak kapalı.
Anahtar nokta: her madde açık ve mutlak olmalı. "TypeScript'ten kaçınmaya çalış" değil, "TypeScript yok" yazın. Belirsiz olan, Claude tarafından pazarlık edilebilir kabul edilir.
CLAUDE.md'nin son büyük bloğu "Claude Code kullanım kuralları":
### "X'e başla" dediğimde
1. Önce CLAUDE.md kısıtlarının bu yaklaşıma izin verip vermediğini kontrol et
2. Mevcut kodda ilgili bir gerçekleme var mı diye bak (tekerleği yeniden icat etme)
3. Kod yazmadan önce yeni bir branch aç
4. Gerçekleme tamamlandıktan sonra testleri çalıştır
5. Otomatik commit yapma — kod yazıldı ve testler yeşil olduktan sonra dur
ve raporla. Açıkça "commit" diyene kadar bekle
### "Bir fikrim var" dediğimde
Hemen kod yazma. Önce:
1. Anlamayı doğrula (kendi cümlenle özetle)
2. CLAUDE.md kısıtlarına karşı değerlendir
3. Olası sorunları veya daha iyi alternatifleri belirt
4. Onayımı bekle, sonra hareket et
### Teknik bir çatalla karşılaşıldığında
CLAUDE.md belirtmediğinde:
1. Daha "Rails-native" seçeneği varsayılan olarak seç
2. Daha az bağımlılığı olan seçeneği varsayılan olarak seç
3. Tek başına geliştiricinin daha hızlı iterate etmesini sağlayan seçeneği seç
4. Tereddüt edersen dur ve sor
Bu kısım "snake_case kullan"dan on kat önemli.
Kod stilini Claude kodu okuyarak öğrenir. Ama "ne zaman durup soracağını", "'bir fikrim var' duyunca önce parafraze etmesini, hemen kod yazmamasını" — bunlar davranış kalıpları. Sadece kodu okuyarak öğrenilmez.
En kritik satır: çatalda hangi yöne varsayılan olarak gideceği. O tek kural, siz ortamda yokken (sadece "X'e başla" deyip çıktığınızda) Claude'un ne yapacağını belirler. Bunu net yazın, gözetimsiz çalışmasına güvenirsiniz.
CLAUDE.md'nin başında şu satır var:
Bu doküman projenin "birincil kaynağı"dır. Her Claude Code oturumunun başında otomatik yüklenir. Teknik kararları değiştirirken önce burayı değiştirin; kod sonra gelir.
Bu bir iş akışı sözleşmesi. Bir teknik tercihi değiştirmeye karar verdiğimde — diyelim ki ana AI modelini gpt-5-mini'den gpt-5'e yükselteceğim — ilk adım initializer'a dokunmak değil. İlk adım CLAUDE.md'deki şu parçayı düzenlemek:
ai:
fast: gpt-5-mini # önce
fast: gpt-5 # sonra
Sonra Claude'a CLAUDE.md'yi yeniden okutup kodu eşitletiyorum.
Neden? Çünkü kodda bir değeri değiştirip CLAUDE.md geride kalırsa, Claude CLAUDE.md'yi bir sonraki okuyuşta eski değeri görür ve "iyilik olsun diye" kodunuzu geri alır. Çatışmanın kökü tek bir hata noktasıdır — CLAUDE.md'nin senkronu kaybetmesi. Anayasanın gerçeklikten geride kalması iç savaşların başlama biçimidir.
CLAUDE.md'yi anayasa olarak ele almak şu demektir: her zaman koddan önce koşar.
smarts.md, 5 gün, 92 commit:
Ortalama PR ömrü: 30 dakika. Büyük refactor yok. "Dur, o yön yanlıştı, geri alalım" yok.
Claude sihirli olduğu için değil. Çünkü her oturumda 565 satırlık bir ray üzerinde koştu. TypeScript çekmemeyi biliyordu, Solid Queue'nun varsayılan kuyruk olduğunu biliyordu, view fonksiyonlarının 60 saniye önbelleklendiğini biliyordu, her servisin bir call sınıf metodu uygulaması gerektiğini biliyordu, commit etmeden önce onayımı beklemesi gerektiğini biliyordu.
Bu kısıtların yarısını çıkarın, şunu elde edersiniz: günde 30 dakika "neden X kullanmıyoruz" açıklaması, 5 dakika "fırsattan istifade" eklenen bağımlılığı gözden geçirme, ve yavaş yavaş çürüyen bir Gemfile.
Boş dosyadan başlamayın. Son canınızı yakan karardan başlayın.
Son zamanlarda Claude "her seferinde yeni bağımlılık çekiyor" dediğiniz şeyse, yasaklar listesini yazın.
"Sürekli mimari değiştiriyor" ise, mimari diyagramı + "yeni mikroservis, DB değişimi vb. onay gerektirir" yazın.
"Test yazmıyor" ise, "zorunlu birim testi gereken bölümler" yazın.
"Çok agresif commit ediyor" ise, "otomatik git commit yok, açık talimat bekle" yazın.
Her acıya bir madde. Diğerlerini şimdilik yazmayın.
Üç ay sonra 500 satırlık bir CLAUDE.md'niz olacak; her satırın arkasında somut bir "bunu bir daha yapmasını istemiyorum" var. Bu doküman herhangi bir şablondan üstündür, çünkü tam olarak sizin projenize, iş akışınıza, ekibinize (tek kişi olsanız bile) göre kalibre edilmiştir.
Anayasa bir oturuşta yazılmaz. Somut çatışmalardan, tek tek kristalleşir.
Kaynak: github.com/defi-io/smarts