Kuralları AI'a öğretmek: 1.000 satırlık bir CLAUDE.md neden işe yarıyor?
Prototype to Code serisi · Bölüm 3
Her ekipte bir «tasarım kuralları» dokümanı vardır. Çoğu zaman kimse okumaz. Okuyan da üç ay sonra unutur.
Bizim kurallarımız da yazılı. Fark şu: onları her işe başlamadan önce baştan okuyan biri var. O da AI.
CLAUDE.md: projenin tek doğru kaynağı
Claude Code bir repoda çalışmaya başladığında kök klasördeki CLAUDE.md dosyasını otomatik olarak okur. Bizimki bugün 1.000 satırı aşıyor. İçinde renk token'larından ikon seçimine, dosya adlarından kalıcı veri modüllerine, aday sayfalarının nasıl kurulacağına kadar her şey var.
Bu dosyanın tek bir görevi var: tek doğru kaynak olmak. Skill'ler dahil diğer her şey ondan türüyor. Bir skill ile CLAUDE.md çelişirse CLAUDE.md kazanıyor ve skill güncelleniyor. Böylece «hangi kural geçerli?» sorusu hiç doğmuyor.
Hangi kuralları neden yazdık
Kurallarımızın çoğu bir soruya cevap: AI burada en kolay neyi yanlış yapar?
- Ürüne özel varyant önceliklidir. Tasarımcı kütüphanedeki tarih seçicinin metinlerini ve davranışını beğenmediği için kendi PbDatePicker'ını yazdı. Kural der ki: ürüne özel bir varyant varsa kütüphanenin ham hali kullanılmaz. Bu sayede tasarımcının bir kez verdiği karar o günden sonra yazılan her sayfaya kendiliğinden yayılıyor. AI bunu ezberindeki bir listeden değil, klasörün o anki halinden kontrol ediyor. Çünkü varyant listesi her hafta büyüyor.
- Yalnızca semantik renkler. text-gray-900 yerine text-primary yazılıyor. Açık ve koyu temada doğru renk kendiliğinden geliyor, marka rengi değiştiğinde tek bir dosya güncelleniyor.
- Ham HTML yok. Hiçbir buton, input ya da seçim kutusu elle yazılmıyor, hepsi kütüphaneden geliyor. Klavye ve ekran okuyucu desteği de böylece kendiliğinden geliyor. Kuralın hemen yanında, ihlali bulan kısa bir kontrol komutu da duruyor.
- İkon kaynağının sırası sabit. Önce Untitled UI ikonlarına bakılıyor. Orada yoksa Tabler'a, o da yoksa elle çizime geçiliyor. Tek bir görsel dil korunuyor.
- Metin de bir kural. Aynı component bazen hem adayın görev ekranında hem de görevin tasarlandığı ekranda kullanılıyor. Tasarım ekranında «Görevi Bitir» butonu da, «Değişkenler adayın verisiyle dolduruldu» cümlesi de olmamalı. Yanlış ekranda kalan bir cümle kullanıcıya doğru olmayan bir şey söyler. Bu yüzden kural yalnızca kontrolleri değil, metni de kapsıyor.
Skill: kuralları iş akışına çeviren rehber
CLAUDE.md neyin doğru olduğunu söylüyor. Skill ise işin nasıl yapılacağını. Tasarımcının kullandığı skill, o «yeni sayfa», «filtre ekle», «bu tasarımı kodla» dediğinde ya da bir Figma linki paylaştığında kendiliğinden devreye giriyor. Tasarımcı komut ezberlemiyor, kendi cümlesiyle konuşuyor.
Skill on adımlık bir akış izliyor. Bunların en önemlisi, kod yazılmadan önce gelen adım.
Kod yazılmadan önce bir tablo
AI tasarımdaki her öğeyi bir component'le eşleştiren bir tablo hazırlıyor ve tasarımcıya sunuyor. Tablodaki «PB Kontrolü» sütunu, her satır için ürüne özel bir varyant olup olmadığını gösteriyor. Tasarımcı tabloyu onaylamadan tek satır kod yazılmıyor.
Bu sayede tasarımcı kodu okumak zorunda kalmadan kararların sahibi oluyor. «Burada hangi tarih seçici kullanılacak?» sorusunun cevabını kodda değil, tabloda görüyor.
Eski kodu örnek almamak
Kurallar zamanla yazıldığı için bazı eski sayfalar hâlâ kütüphanenin ham halini kullanıyor. Skill bu sayfaları adıyla sayıyor ve açıkça «bunları örnek alma, dokunuyorsan güncelle» diyor.
AI'ın en kolay hatası, repoda gördüğü ilk örneği kopyalamak. Bu tek uyarı o hatayı kapatıyor.
Kısacası
Kural dokümanını kimse okumuyordu. Biz de onu her seferinde okuyacak birini bulduk ve son kararı yine tasarımcıya bıraktık.
Bir sonraki bölümde tasarımcının bir gününü anlatacağım: tek bir zincirde çalışan dört skill, Figma linkinden açılan PR'a kadar.
Musa Turan, PeopleBox'ta AI Software Engineer olarak LLM ve AI sistemleri üzerinde çalışıyor. «Prototype to Code» serisinde, PeopleBox Onyx'te tasarımcının çalışan kod teslim ettiği akışı anlatıyor.