Yapay zeka kodlama ajanları artık gerçek arayüzleri yayına alıyor: butonlar, yerleşimler, metinler, sayfaların tamamı. Bu çıktının sizin markanız gibi mi yoksa sıradan bir bootstrap çorbası gibi mi görüneceği tek bir şeye bağlı: ajanın işe başlamadan önce ne bildiği. Bu bilgi CLAUDE.md dosyasında durur. Bu yazı, tasarım ekipleri için böyle bir dosya yazma rehberidir.

CLAUDE.md dosyası nedir?

CLAUDE.md, bir projenin reposunda tutulan ve Claude Code ile benzeri yapay zeka ajanlarının her oturumun başında otomatik olarak okuduğu düz metin bir talimat dosyasıdır. Onu kalıcı bir brief gibi düşünün: Ajan tek bir dosyaya dokunmadan önce kurallarınızı okumuş olur.

Mühendisler, ajan tabanlı kodlama araçları ortaya çıktığından beri bu dosyaları build komutları ve mimari notlar için kullanıyor. Ancak formatta mühendisliğe özgü hiçbir şey yok. Bu bir Markdown dokümanı. Test komutlarını barındırdığı kadar kolaylıkla renk token'larını, tipografi kurallarını, ses tonu yönergelerini ve erişilebilirlik gereksinimlerini de barındırabilir.

CLAUDE.md, Claude Code'un konvansiyonudur ama kardeşleri de var. AGENTS.md, birden fazla kodlama ajanının okuduğu, araçlar arası, yeni yeni yerleşen bir standarttır. Cursor kuralları (.cursor/rules ya da .cursorrules) Cursor için aynı işi görür. GitHub Copilot'ta ise copilot-instructions.md var. İsimler farklı, fikir aynı: Repoda duran ve yapay zekaya bu projenin nasıl işlediğini ve çıktısının nelere uyması gerektiğini söyleyen bir dosya. Pek çok ekip tek bir ana doküman yazar ve bunu sembolik bağlantı (symlink) ya da kopyalama yoluyla farklı konvansiyonlara yansıtır.

Genel amaçlı design.md dosyalarını anlatan tamamlayıcı yazımızı okuduysanız aradaki farka dikkat edin: O yazı, herhangi bir araca ya da kişiye verebileceğiniz bağımsız tasarım spesifikasyonu dokümanlarını ele alıyor. Bu yazı ise ajan bağlam dosyasının kendisiyle, yani kimsenin yapıştırmayı hatırlamasına gerek kalmadan, her oturumda otomatik olarak okunan dosyayla ilgili.

Tasarım ekipleri neden bir kod reposundaki dosyayı önemsemeli?

Çünkü yapay zeka ajanları ürününüzde zaten tasarım kararları veriyor ve brief almamış bir ajan bu kararları kötü veriyor. Bir mühendis bir ajana "bir ayarlar sayfası ekle" ya da "boş durum metnini yaz" dediği her seferde ajan renkleri, boşlukları, tipografiyi ve kelimeleri kendisi seçer. Marka kurallarınız yalnızca bir Figma kütüphanesinde ve kimsenin açmadığı bir PDF'te duruyorsa ajan onları göremez. Varsayılan olarak Tailwind mavisine, sıradan bir sans-serif hiyerarşisine ve diğer tüm SaaS ürünlerine benzeyen metinlere yönelir.

Tasarımcıların CLAUDE.md yazmak için kod yazmayı bilmesi gerekmez. Dosya düz yazı ve listelerden oluşur. Onu yazmak, programlamaktan çok marka kılavuzu yazmaya benzer; tek bir farkla: Bu versiyon gerçekten uygulanır, çünkü üretim anında doğrudan aracın görüş alanında durur.

İkinci bir neden daha var: kaldıraç. Bir marka sunumu, onu okuyan insanları ikna eder. Bir CLAUDE.md ise brifingi asla atlamayan bir makineye talimat verir. Kelime başına bakıldığında ekibinizin yazabileceği en yüksek kaldıraçlı marka dokümanıdır, çünkü her bir üretimde okunur.

CLAUDE.md'de hangi tasarım bilgileri yer almalı?

Bir ajanın soru sormadan markaya uygun çıktı üretmek için ihtiyaç duyduğu her şey: token'lar, tipografi, boşluklar, ses tonu, bileşen kuralları, sanat yönetimi, erişilebilirlik ve açık yap/yapma kuralları. Somut olarak:

  • Gerçek hex değerleriyle renk token'ları. "Marka mavisini kullan" bir ajan için işe yaramaz. --color-primary: #1A4FD8 ise doğrudan uygulanabilir. Semantik rolleri (primary, surface, danger) ve yasak kullanımları ("birincil metni asla vurgu renginin üzerine yerleştirme") listeleyin.
  • Tipografi kuralları. Yazı karakterleri, ölçeğin tam hâli (boyutlar, ağırlıklar, satır yükseklikleri) ve kullanım kuralları: başlıkların hangi ağırlıkta olduğu, italik kullanıp kullanmadığınız, büyük/küçük harf kuralları.
  • Boşluk ölçeği. Taban birim ve izin verilen adımlar (4/8/12/16/24/32...); böylece ajan asla 13 piksellik bir margin uydurmaz.
  • Ses tonu. Tek başına kullanılan sıfatların anlamı kayar; her birini bir örnekle eşleştirin. "Kendinden emin ama övüngen değil: 'Bu işe yarıyor' deyin, 'Bu devrim niteliğindeki özellik...' değil."
  • Bileşen kuralları. İsimlendirme kalıpları, varyant sözlüğü (primary/secondary/ghost; blue/gray/outline değil), bileşenlerin nerede durduğu ve ajanların yeni bileşen oluşturmadan önce mevcut bileşenleri genişletmesi kuralı.
  • Sanat yönetimi anahtar kelimeleri. Görsel üretimi ve illüstrasyon prompt'ları için: fotoğraf stili, ışık, kompozisyon kuralları, yasak klişeler (el sıkışma yok, ampul yok, mor gradyan yok).
  • Erişilebilirlik gereksinimleri. Minimum kontrast oranları, focus durumu kuralları, dokunma alanı boyutları, alt metin beklentileri. Bunları öneri olarak değil, zorunluluk olarak yazın.
  • Yap/yapma listeleri. Bir ajan için en hızlı okunan format. İncelemede yakaladığınız ve tekrar eden her hata buraya bir "yapma" olarak girmeli.

Dosyayı derli toplu tutun. Bir ajan bağlam dosyası sınırlı bir dikkat için yarışır; 400 satırlık bir marka denemesi kendi etkisini sulandırır. Kurallar, değerler, örnekler. Gerisini çıkarın ve ajanın ihtiyaç duyduğunda açabileceği daha kapsamlı dokümanlara bağlantı verin.

Tasarım odaklı bir CLAUDE.md gerçekte neye benzer?

Kurgusal bir marka olan bitki bakım uygulaması Fernwood için açıklamalı bir kesit:

## Brand: Fernwood

### Color: use tokens only, never raw hex in components
- --color-moss: #2F5D3A (primary; buttons, links, active states)
- --color-clay: #C4552F (accent; sparingly, one accent element per view)
- --color-paper: #FAF7F0 (default background; never pure white #FFFFFF)
- --color-ink: #1C2321 (body text)
- Don't: moss text on clay, or clay at large sizes. Clay is a spice, not a base.

### Typography
- Headings: "Fraunces", weight 600, tracking -0.01em. Sentence case, never ALL CAPS.
- Body: "Inter", 400, 16px/1.6. Minimum body size: 14px.
- One weight jump max between adjacent hierarchy levels.

### Spacing
- Base unit 4px. Allowed steps: 4, 8, 12, 16, 24, 32, 48, 64. Nothing else.

### Voice
- Warm, plainspoken, lightly botanical. A knowledgeable friend, not a lab.
- Say: "Your monstera looks thirsty." Don't say: "Hydration levels suboptimal."
- Errors are calm and blame-free: "That didn't save. Try again?" No exclamation
  marks in error states, ever.

### Components
- Extend components in src/ui/ before creating new ones. New components require
  a design review; flag them in your summary instead of inventing silently.
- Variants are named primary / secondary / ghost.

### Accessibility (non-negotiable)
- Text contrast ≥ 4.5:1 (verify moss-on-paper for small text before using).
- Every interactive element: visible focus ring (2px, --color-moss), 44px
  minimum touch target.

### Art direction (for generated imagery)
- Natural light, shallow depth of field, real homes. Never studio white.
- Don't: neon, stock-photo smiles, top-down "flat lay" clichés.

Örüntüye dikkat edin: Her kural ya somut bir değer ya da bir örnekle eşleştirilmiş bir ifade. Tek başına "Warm" (sıcak) kelimesinin anlamı kayar; "Warm" artı örnek bir cümle ise yerinde durur.

CLAUDE.md, markaya aykırı yapay zeka çıktılarını nasıl önler?

Standartlarınızı inceleme anından üretim anına taşıyarak. Bağlam olmadan bir ajan internetin ortalamasından beslenir ve internetin ortalaması herkes için markaya aykırıdır. Böylece düzeltmeler incelemede, pull request pull request, sonsuza kadar sürüp gider.

İyi bir CLAUDE.md ile ajanın ilk taslağı kısıtlarınızın içinde başlar: Boşluklar ölçeğe uygundur, hata mesajı zaten sizin gibi konuşur, kontrast kontrolü çoktan yapılmıştır. İncelemelerin gündemi "bu mavi yanlış" türünden yorumlardan gerçek tasarım muhakemesine kayar. İncelemeye yine devam edeceksiniz (dosya hata alanını daraltır, ortadan kaldırmaz); ancak başlangıç kalitesindeki fark anında hissedilir ve denediğiniz ilk hafta bariz biçimde ortaya çıkar.

Dosyayı neden kod tabanıyla birlikte versiyonlamalısınız?

Çünkü repoda yaşayan tasarım kararları, yönettikleri kod gibi kalıcıdır, her yere taşınır ve bir geçmişe sahiptir. Dosya git'te olduğunda:

  • Bir marka yenilemesi (rebrand) bir pull request'e dönüşür. Diff, değişiklik kaydının ta kendisidir: Vurgu renginin tam olarak ne zaman, kim tarafından ve neden değiştiğini görebilirsiniz.
  • Her mühendis, her ajan oturumu, her CI ortamı aynı marka bağlamını otomatik olarak alır. Güncelliğini yitirmiş PDF'ler yok, "hangi sunum güncel?" sorusu yok.
  • Anlaşmazlıklar incelenebilir hâle gelir. Biri tamamı büyük harf (ALL CAPS) kuralını gevşetmek isterse bunu önerir ve ekip, kodun tabi olduğu yönetişimin aynısıyla incelemede karar verir.

Repodaki bir marka kılavuzu yaşayan bir kısıttır. Sunum dosyasındaki bir marka kılavuzu ise yalnızca bir temennidir.

Dosyanın sahibi kim: tasarımcılar mı, mühendisler mi?

İkisi birden, bilinçli olarak. Dosya, taraflardan yalnızca biri sahiplendiğinde başarısız olur: Yalnızca mühendislerin yazdığı dosyalar build komutlarından ibarettir, markadan eser yoktur; yalnızca tasarımcıların yazdığı dosyalar ise kod tabanının gerçekte içerdiklerinden uzaklaşır.

İşe yarayan bir yapı şöyle: Marka bölümleri (renk, tipografi, ses, sanat yönetimi, yap/yapma) tasarımcılara aittir ve bu bölümlerdeki değişikliklerde tasarımcılar zorunlu inceleyicidir; bir CODEOWNERS kaydı bunu otomatik hâle getirir. Teknik bölümler mühendislere aittir; token adlarını kodla senkronize tutmak da onların işidir. İki taraf da inceleme yorumlarına bir tasarım kritiği gibi yaklaşır: Bir ajan dosyaya rağmen markaya aykırı bir şey ürettiğinde çözüm genellikle yalnızca koddaki bir düzeltme değil, dosyaya eklenen yeni bir satırdır. Bu geri bildirim döngüsü (bir hatayı bir kez yakala, kuralı dosyaya yaz, bir daha asla yakalamak zorunda kalma) işin özüdür.

Things bunu nasıl yapıyor?

Things'te her ürün reposu, kodun yanında ajan bağlam dosyaları da taşır ve bunlardan ikisinin sahibi tasarım ekibidir: bir sanat yönetimi dokümanı ve bir metin (copy) dokümanı. Sanat yönetimi dokümanı görsel sistemi barındırır: değerleriyle birlikte token'lar, görsel kullanım kuralları, üretim araçları için kompozisyon anahtar kelimeleri. Metin dokümanı ise sesi barındırır: örnek cümleler, yasaklı ifadeler, terminoloji, büyük/küçük harf kuralları, hatalar ve boş durumlar için yüzeye özel yönergeler.

Tasarımcılarımız bu dosyalardaki değişiklikleri arayüzleri incelerken gösterdikleri özenle inceler; yapay zeka destekli iş akışlarımız da bu dosyaları her oturumda okur. Bir ajan çıktısı hedefi ıskaladığında o ıska bir kurala dönüşür. "Design. Code. Mastery." sözünün departmanlara bölünmüş bir slogan olmamasının nedenlerinden biri de bu: Biz bir ajans değil, bir stüdyoyuz ve tasarımın kodla buluştuğu dosya da yayına aldığımız diğer her şey gibi ortak sahipliktedir.

Sıkça Sorulan Sorular

CLAUDE.md yalnızca Claude Code ile mi çalışır? Dosya adı Claude Code'un konvansiyonudur, ancak bu pratik başka araçlara da taşınabilir. AGENTS.md, Cursor kuralları ve Copilot talimatları diğer araçlarda aynı rolü üstlenir. Tek bir ana doküman yazın ve ekibinizin kullandığı konvansiyonlara yansıtın.

Katkıda bulunmak için kod yazmayı bilmem gerekir mi? Hayır. Bu bir Markdown metin dosyasıdır. Marka kılavuzu yazabiliyorsanız tasarım bölümlerini de yazabilirsiniz. Bir mühendisten size pull request akışını bir kez göstermesini isteyin; teknik engelin tamamı bu kadar.

Dosya ne uzunlukta olmalı? En sık karşılaştığınız markaya aykırı hataları önlemeye yetecek kadar, olabildiğince kısa. Düz yazı yerine kuralları, değerleri ve örnekle eşleştirilmiş ifadeleri tercih edin. Daha kapsamlı dokümanları içine yapıştırmak yerine onlara bağlantı verin.

Tasarım sistemi dokümantasyonumuzun yerini alabilir mi? Hayır. O, tasarım sisteminizin üretim anında bir yapay zekaya sunduğu yönetici özetidir. Kapsamlı dokümantasyon önemini korur; CLAUDE.md onu işler hâle getiren katmandır.

Ajan bir kuralı görmezden gelirse ne yapmalı? Bu olabilir. Durumu bir tasarım kritiği gibi ele alın: İfadeyi netleştirin, somut bir örnek ya da açık bir "yapma" ekleyin ve kuralı dosyada daha yukarı taşıyın. Net ve göz önünde olan, uzun ve gömülü olanı yener.

Araçlarınız markanızı yayına almadan önce onları eğitin

Brief almamış her ajan oturumu, marka değeri hesabınızdan çekilen küçük bir paradır. İyi yazılmış bir CLAUDE.md aynı oturumları hesabınıza yatırılan birikimlere dönüştürür ve başlamak için bir öğleden sonranızı ayırmanız yeterlidir.

Things, 2018'de kurulmuş, İstanbul ve Elazığ'dan Türkiye'nin ve dünyanın önde gelen markaları için çalışan bir dijital tasarım ve mühendislik stüdyosudur. Araştırma odaklıyız, Red Dot ödüllüyüz, 50'den fazla ürünü hayata geçirdik ve yapay zeka destekli iş akışları, tasarlama ve geliştirme biçimimizin ayrılmaz bir parçası. Markanızın yapay zeka araçlarıyla temasa geçtiğinde ayakta kalmasını istiyorsanız, onu kurallara dökmenize yardımcı olabiliriz.

Bize yazın: hello@things.ist