shadcn/lint: Ajana 'yapma' değil, 'bunu kullan' diyen linter

Sorun: Ajan tasarım sistemini bozuyor

Tailwind CSS’te stil vermek için sınıf adları yazarsın: p-4 iç boşluk, bg-pink-500 pembe arka plan gibi. shadcn/ui de bu sınıflarla yazılmış hazır bileşenler (Button, Card vb.) sunan popüler bir koleksiyon.

Bir ekibin tasarım sistemi varsa kurallar bellidir: Butonun boyutu size ile seçilir, renkler temadan gelir, kimse elle p-[13px] yazmaz. Bir yapay zekâ ajanı ise işi hızla bitirmek için tam bunları yapar. Butonun iç boşluğunu ezer, temada olmayan bir renk seçer. Sayfa çalışır ama tasarım yavaş yavaş dağılır.

Tasarım kurallarını ajanın okuyacağı bir dosyaya yazma yaklaşımını DESIGN.md yazımızda anlattık.

Çözüm: Açıklayan bir linter

Linter, kodu çalıştırmadan okuyup kurallara uymayan yerleri bildiren araçtır. @shadcn/lint, Tailwind tasarım sistemleri için yazılmış bir linter ve ESLint ya da Oxlint eklentisi olarak çalışıyor. shadcn/ui kullanman gerekmiyor; kendi Tailwind v4 bileşenlerinle de çalışıyor.

Asıl fark hata mesajlarında. Diyelim ajan şunu yazdı:

<Button className="p-4">Kaydet</Button>

TypeScript ile de padding’i yasaklayabilirsin, ama hata sadece “bu özellik izinli değil” der. @shadcn/lint ise kabaca şunu söylüyor: “Button kendi boşluğunu yönetir. Bir boyut kullan (sm, lg) ya da etrafında boşluk için margin veya üst öğede gap kullan.” Öneriler senin projendeki bileşenlerden, varyantlardan ve temadan geliyor.

Kurallar

Paketle gelen başlıca kurallar:

• no-restyle: Bir bileşenin stilini className ile ezmeyi yakalar.
• no-raw-colors: bg-pink-500 gibi temada olmayan ham renkleri yakalar.
• no-arbitrary-values: p-[13px] gibi keyfi değerleri yakalar.
• no-inline-styles: Satır içi style kullanımını yakalar.
• no-unknown-classes: Tailwind’in üretemeyeceği sınıfları yakalar.
• require-static-classes: Linter’ın okuyamayacağı, dinamik oluşturulmuş sınıfları yakalar.

Contract (sözleşme) denen ayarla her bileşene ayrı kural verebilirsin. Örneğin “Button’a sadece w-full ve üst/alt margin verilebilir” ya da “CardTitle’ın yazı boyutu değişebilir ama font kalınlığı değişemez”. Bileşenin kodunu değiştirmen gerekmiyor. Hata mesajlarını da kendin yazabilirsin: “Padding yerine size kullan” gibi.

İşe yarıyor mu?

shadcn’in kendi testlerine göre kurallar farklı modellerle 150’den fazla görevde denendi. Görevlerin neredeyse hepsi tek bir düzeltme turunda sıfır hataya indi. Claude ile yapılan karşılaştırmalarda hataları linter geri bildirimiyle düzeltmek, sadece yazılı kurallarla düzeltmekten yüzde 10 ile 48 arasında daha ucuza geldi. Bunlar şirketin kendi ölçümleri, bağımsız doğrulama değil.

Kullanımı basit: Linter’ı kurup AGENTS.md dosyana “değişiklikten sonra npm run lint çalıştır ve hataları düzelt” yazıyorsun. Ajan kendi işini kontrol ediyor.

Sınırları

Linter kodu çalıştırmadan okur, yani sadece koddaki sınıf adlarını görür. Sayfanın ekranda gerçekte nasıl göründüğünü, yani tasarımın iyi olup olmadığını değerlendiremez. Dinamik oluşturulan sınıfları da okuyamaz (bu yüzden onları yasaklayan bir kural var).

Asıl ders

Bir ajana “yapma” demek yetmez; “bunun yerine şunu yap” demek gerekir. İyi yazılmış bir hata mesajı, uzun bir kural listesinden daha etkili bir öğretmen olabilir.

Düşün

• Senin projende bir ajanın en sık bozduğu kural hangisi? Bunu otomatik kontrol edebilir misin?
• Bir hata mesajını insan için yazmakla ajan için yazmak arasında fark var mı?

Kendi cümlelerimizle yazılmış bir özettir, çeviri değildir. Tüm kaynaklar yukarıda.