DESIGN.md dosyası nedir ve nasıl kullanılır?

DESIGN.md nedir ve AGENTS.md neleri kapsamaz

DESIGN.md, deponuzun kök dizininde bulunan ve bir yapay zeka kodlama aracına kodun neden bu şekilde yapılandırıldığını anlatan bir markdown dosyasıdır. AGENTS.md ise farklı bir soruya yanıt verir: burada nasıl çalışılır? Bu, derleme komutu, test komutu, geçilmesi gereken lint aracı ve dokunulmaması gereken yollar anlamına gelir. DESIGN.md, halihazırda karara bağlanmış olan tercihleri ve bunlardan biri geri alındığında nelerin bozulacağını kaydeder.

Claude Code veya Cursor gibi deponuzu kendi başına okuyan ve düzenleyen bir kodlama aracı, varsayılan olarak kendine güvenir. Tanımadığı bir desen bulduğunda bu deseni iyileştirmeye çalışır. Elle yazılmış bir önbellek, Redis (bellek içi bir veri deposu) haline getirilebilir; çünkü modelin okuduğu çoğu kodda önbellek bu şekilde görünür. AGENTS.md bunu engellemez, çünkü make test her iki durumda da geçer. İhlal edilen kural, aracın okuyabileceği hiçbir yerde yazılı değildir.

Eğer henüz ilk dosyayı yazmadıysanız, oradan başlayın. AGENTS.md ve yanındaki HUMAN.md dosyası, formatı ve her aracın onu nerede aradığını kapsar. Aşağıdakiler, bu bölümden sonra gelen kısımdır.

Yayınlanmış bir DESIGN.md dosyasının içeriği

Formatı öğrenmenin en hızlı yolu, şirketlerin kendileri hakkında yayınladıkları dosyaları okumaktır. official-design-md deposu yalnızca bu dosyaları takip eder. Depoya dahil edilme kuralı tek bir satırdan oluşur ve bu satır, koleksiyonun tüm amacını özetler:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

Ağustos 2026 itibarıyla listede yedi adet dosya bulunmaktadır: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel ve VoltAgent. Her dosya sabit bir genel URL üzerinde yer alır, bu sayede bir terminal üzerinden hemen okuyabilirsiniz.

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

Bunların her ikisi de tasarım sistemi belgeleridir. Bir ürünün nasıl görünmesi gerektiğini; renk, tipografi, boşluk ve hareket gibi unsurlarla tanımlarlar. Konu başlığının ötesine geçerek okuyun; çünkü burada faydalı olan kısım, ele alınan konudan ziyade yazım biçimidir.

Nuxt dosyası yaklaşık 2.100 kelimeden oluşur ve içeriğinin büyük bir kısmı, gerekçesiyle birlikte sunulan kurallardır:

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

Vercel dosyası daha uzundur; Ağustos 2026 itibarıyla yaklaşık 6.500 kelimedir ve bir adım daha ileri gider. Başlıklarından biri Reject generated-design reflexes şeklindedir. Bunun altında, yetenekli bir üreticinin (generator) aksi belirtilmediği sürece başvurduğu yöntemlerin listesi yer alır:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

Bu cümle, dosya türünü tanımlar. Kendinden emin bir modelin ürettiği varsayılan değerlerin yazılı bir listesidir ve modelin bu değerleri üretmeyi bırakması amacıyla yayınlanmıştır. Commit edilmeye değer her DESIGN.md dosyası, belirli bir alan için bu tür bir listedir.

Şirketler neden kendi DESIGN.md dosyalarını yayınlıyor?

Topluluk bu konuda öncü oldu. awesome-design-md deposu, herkese açık web sitelerinden tersine mühendislik ile elde edilmiş 73 dosya barındırıyor. Her biri aynı dokuz bölümlü formatta yazılmış; böylece bir aracı (agent) bu dosyalardan birine yönlendirildiğinde, o görünüme yakın bir sonuç üretebiliyor. Bu dosyalar yararlı olsa da hala birer tahminden ibaret. Şirketlerden hiç kimse bunları incelemedi.

Birinci taraf (first-party) bir dosya ise farklıdır; çünkü çıktının bir okuması değil, kaynağın kendisidir. Vercel tipografi ölçeğini değiştirdiğinde, vercel.com/design.md de onunla birlikte değişir. Mart ayında kopyalanmış bir dosya, aracınıza eski ölçeği öğretmeye devam eder ve deponuzdaki hiçbir şey size bu kopyanın güncelliğini yitirdiğini söylemez.

Yedi yayıncı küçük bir sayı ve depo da bunu belirtiyor: standart yeni ve resmi benimsenme oranı artıyor. Her iki koleksiyon da kendi dosyasını yayınlayan açık kaynaklı bir aracı çerçevesi olan VoltAgent tarafından sürdürülüyor; bu yüzden listeyi tarafsız bir nüfus sayımı olarak değil, bir takip aracı olarak okuyun. Yine de bu yedi şirketin kim olduğu nedeniyle izlemeye değer. Bunlar, ön uç kodları diğer geliştiriciler tarafından en çok kopyalanan şirketler ve dosyaları, bir DESIGN.md dosyasının ne olduğuna dair işlenmiş örnekler haline geliyor. AGENTS.md dosyasının izlediği yolu karşılaştırın: agents.md şu anda bu formatı kullanan 60.000'den fazla açık kaynak projesini içeriyor ve yönetimi Linux Foundation bünyesindeki Agentic AI Foundation'da bulunuyor. Aracıların okuyabileceği dosyalara yönelik kurallar hızla yerleşiyor ve bu yerleşme tepeden aşağıya doğru gerçekleşiyor.

Kullanıcı arayüzü olmayan projelerde DESIGN.md dosyasına ne yazılmalı

Bir VPS üzerinde çalışan çoğu yazılımın belirtilmesi gereken görsel bir dili yoktur. Bu dosya, mekanizmanın renklerle hiçbir ilgisi olmamasına rağmen yine de yerini hak eder. Dosyanın amacı, kendine güvenen bir editörün fark etmeden ihlal edebileceği kısıtlamaları yazıya dökmektir.

Değişmezler (Invariants). Her biri, herhangi bir düzenlemeden sonra doğru kalması gereken bir durumu belirten tek cümlelik ifadelerdir. "Her yazma işlemi queue.enqueue() üzerinden gerçekleşir. Doğrudan veritabanı yazma işlemi denetim günlüğünü (audit log) atlar ve uyumluluk dışa aktarımı denetim günlüğünü okur." Nedeniyle birlikte belirtilen bir değişmez, hiç öngörmediğiniz bir görevle karşılaştığınızda varlığını korur. Tek başına bırakılan bir değişmez ise tercih gibi algılanır ve tercihler optimizasyon sürecinde elenir.

Reddedilen alternatifler. Bariz seçenek ve neden elendiği. "Önbellekleme için Redis kullanmıyoruz. Servis tek bir VPS üzerinde çalışıyor, bu nedenle süreç içi (in-process) bir harita daha hızlıdır ve canlı tutulması gereken bir daemon daha azdır. İkinci bir uygulama sunucusu olduğunda bunu tekrar değerlendirin." Bu paragraf olmadan, önbelleği hızlandırması istenen bir temsilci Redis ekleyecektir ve bunu yapmakta haklıdır: ona kısıtlamayı söylemediniz. Bu bölüm, dosyanın tüm maliyetini karşılayan kısımdır.

Sınırlar (Boundaries). Küçük bir düzenlemenin büyük bir etki alanına sahip olduğu yerler. Veritabanı şeması. Müşterilerin halihazırda betiklerinde kullandığı genel rota öneki. Bir dağıtımın (deploy) uygulama başlamadan önce okuduğu yapılandırma dosyası. Yalnızca bir kopyasının çalıştığını varsayan cron girdisi. Bunları adlandırın ve her birinde yapılacak bir değişikliğin maliyetini belirtin. Eğer temsilci açık web'e de erişebiliyorsa, bunu arama arka ucu olarak yapılandırılmış self-hosted bir SearXNG örneği üzerinden yapıyorsa, bu da yazılmaya değer bir sınırdır; çünkü dosya, hangi getirilen metnin koda etki etmesine izin verildiğini ve hangisinin yalnızca size alıntılanacağını belirtmelidir.

Kelime dağarcığı (Vocabulary). Eğer kod tenant diyorsa ve ekip customer diyorsa, bu eşleştirmeyi yazın. Burada yanlış tahminde bulunan bir temsilci, okunduğunda mantıklı gelen ancak yanlış şeyi modelleyen kodlar üretir; bu da inceleme sırasında tespit edilmesi en zor hata türüdür.

Bugün kopyalayabileceğiniz bir DESIGN.md

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

Bugün hafızanızdan yazabileceğiniz iki bölümü (değişmezler ve reddedilen alternatifler) doldurun, geri kalanını başlık olarak bırakın. Dört dürüst satırdan oluşan bir dosya iş görür. Tahminlerle dolu kırk satırlık bir dosya ise işe yaramaz.

Bazı araçlar depo kök dizinindeki tüm markdown dosyalarını yüklerken, bazıları yalnızca belirtilen dosyayı yükler; bu yüzden varsayımda bulunmayın. AGENTS.md dosyasına bir işaretçi ekleyin:

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

Değişmezler

• Sistem, root yetkisi gerektirmeden çalışmalıdır.
• Tüm yapılandırmalar versiyon kontrolüne uygun, düz metin formatında olmalıdır.
• Servisler arası iletişim yalnızca yerel ağ veya Unix socket üzerinden gerçekleşmelidir.

Reddedilen Alternatifler

• Merkezi bir veritabanı kullanımı: Karmaşıklığı artırdığı ve tek hata noktası oluşturduğu için reddedilmiştir.
• Otomatik yapılandırma yönetimi araçları: Kurulum sürecini şeffaf olmayan bir hale getirdiği için tercih edilmemiştir.

Mimari Kararlar

Veri Akışı

Güvenlik Modeli

Ölçeklendirme Stratejisi

AGENTS.md dosyasındaki ilgili tanımlara bakınız.

Anti-pattern: README dosyasını tekrarlayan bir DESIGN.md

En yaygın hatalı sürüm, akıcı bir dille yazılmış ancak hiçbir şey öğretmeyen sürümdür. Projenin ne işe yaradığını anlatarak başlar, özellikleri listeler, kurulumu açıklar ve lisans bilgisiyle biter. Bu satırların tamamı zaten README dosyasında mevcuttur ve hiçbiri, bir şeylerin neden o şekilde tasarlandığına dair bilgi vermez.

Bunun size iki maliyeti vardır. Birincisi bağlam maliyetidir. Bir ajanın her görevin başında okuduğu bir dosya, her görevde maliyet yaratır; tekrarlanan bir kurulum bölümü ise sabit bir pencere için safi yüktür. Bu pencereyi yönetmek başlı başına bir beceridir ve Claude Code içinde bağlam penceresini yönetme konusunda ele alınmıştır. Kısa özet: Otomatik olarak yüklenen her şey, depodaki en yüksek değerli metin olmalıdır.

İkinci maliyet ise daha kötüdür. Aynı ifadenin iki kopyası zamanla birbirinden kopar. README servisin 8080 portunu dinlediğini söylerken, DESIGN.md hala 3000 portunu söylüyorsa ve ajanın hangisinin doğru olduğuna karar verecek bir yolu yoksa, rastgele birini seçer ve kodu ona göre yazar. Bazen yanlış bilgi içeren bir dosya, her zaman doğru olan bir dosyayla aynı güvenle referans alınır.

Testi basittir. Eğer bir paragraf README dosyasında sırıtmıyorsa, onu DESIGN.md dosyasından çıkarın. Geriye kalan kısım, bir kod incelemesi sırasında sesli olarak söyleyeceğiniz, "bunu zaten denedik" diye başlayan kısım olmalıdır.

Dosyanın çalıştığından nasıl emin olunur?

Bunun için bir linter bulunmamaktadır. Bir dakika içinde çalıştırabileceğiniz bir kontrol mevcuttur.

Ajanınıza, doğrudan bir değişmeze (invariant) çarpan bir görev verin. "Eski satırları süresi dolmuş olarak işaretleyen bir arka plan işi ekle." Görevini yapan bir dosya, herhangi bir koddan önce cevapta kendini belli eder: Ajan, işin queue.enqueue() üzerinden yazması gerektiğini size söylemelidir; çünkü doğrudan bir yazma işlemi denetim günlüğünü (audit log) atlayacaktır. Eğer bir veritabanı bağlantısı açıp yazıyorsa, iki durumdan biri geçerlidir. Dosya hiç okunmuyordur ya da değişmez, tartışmaya açık olacak kadar gevşek ifade edilmiştir.

Bu dosya her adımda yüklendiği için token sayısını da takip edin. DESIGN.md dosyasını ekledikten sonra bağlam kullanımı artıyor ancak cevaplar iyileşmiyorsa, dosya ajanın zaten sahip olduğu metinleri taşıyor demektir. Claude Code içindeki token sayaçlarını okuma kısmı, bu bütçenin nereye harcandığını gösterir.

Bu durum, ajan dizüstü bilgisayarınız yerine bir sunucuda çalıştığında daha da önem kazanır. tmux ile bir VPS üzerinde Claude Code çalışma alanı kurulumunda olduğu gibi, uzun süreli bir oturumda çalışan ajanın dünkü konuşmaya dair bir hafızası yoktur. Depo (repository), hafızanın kendisidir. Sohbet içinde açıkladığınız ve hiçbir zaman commit etmediğiniz her şey bir sonraki oturumda kaybolur; DESIGN.md, bu açıklamaların hayatta kalmasını sağlayan yerdir.

Tartışmalı kararlarla başlayın

İlk sürüm yirmi dakika sürer. Bir gözden geçirenin "hayır, biz burada farklı yapıyoruz" yazdığı son birkaç pull request'i açın. Bu yorumların her biri, hiçbir yere yazılmamış bir değişmezdir ve her biri, bir ajanın bir insandan daha hızlı ve daha sık aynı hatayı yapacağı bir noktadır. Dosyaya, bir programa göre değil, sizi yarı yolda bıraktığında ekleme yapın. Ajanların normal bir geliştirme iş akışına nasıl uyum sağlayacağını hala çözmeye çalışıyorsanız, 2026 yapay zeka ajanlarını öğrenme rehberi makul bir sonraki duraktır.

FAQ

DESIGN.md resmi bir standart mıdır?

AGENTS.md'nin olduğu gibi değil. AGENTS.md, agents.md adresinde bir merkeze sahiptir, 60.000'den fazla açık kaynak projesi tarafından kullanılmaktadır ve Linux Foundation'ın bir parçası olan Agentic AI Foundation'ın yönetimi altındadır. Ağustos 2026 itibarıyla DESIGN.md'nin herhangi bir yönetim organı veya yayınlanmış bir spesifikasyonu bulunmamaktadır. Sahip olduğu şey, birinci taraf benimsemedir: Vercel, Nuxt, Atlassian ve Resend dahil olmak üzere yedi şirket, bunu herkese açık bir URL'de yayınlamaktadır ve bir topluluk koleksiyonu, herkese açık sitelerden tersine mühendislikle elde edilmiş 73 örnek daha barındırmaktadır. Bunu şu an benimseyebileceğiniz ve özgürce genişletebileceğiniz bir gelenek olarak değerlendirin, çünkü bölüm isimlerinizi doğrulayan bir otorite yoktur.

DESIGN.md, AGENTS.md'nin sadece bir bölümü mü olmalıdır?

Küçük bir depo için evet. Ajanın kesinlikle okuduğu tek bir dosya, birinin göz ardı edildiği iki dosyadan daha iyidir. AGENTS.md taranabilirliğini yitirdiğinde veya iki yarının farklı hızlarda değiştiğini fark ettiğinizde bunları ayırın. AGENTS.md, yapı (build) değiştiğinde değişir. DESIGN.md ise bir karar değiştiğinde değişir; bu daha nadirdir ve daha fazla ağırlık taşır. Ayırma işlemi yaptığınızda, AGENTS.md'ye ajana kodu düzenlemeden önce DESIGN.md'yi okumasını söyleyen bir satır ekleyin, çünkü her araç kök dizindeki her markdown dosyasını yüklemez.

DESIGN.md, mimari karar kaydından (ADR) nasıl farklıdır?

ADR (architecture decision record), tek bir kararın tarihli kaydıdır ve sağlıklı bir proje bir klasörde bunlardan düzinelerce biriktirir. Bu bir geçmiş kaydıdır ve geçmişi yüklemek maliyetlidir; çünkü bir ajanın hangilerinin hala geçerli olduğunu anlamak için hepsini okuması gerekir. DESIGN.md ise mevcut durumdur ve her görevde bütünüyle okunmak üzere yazılır. Halihazırda ADR yazıyorsanız her ikisini de tutun. ADR, neyin ne zaman kararlaştırıldığını belirtir. DESIGN.md ise bugün neyin geçerli olduğunu söyler ve ajanı yönlendireceğiniz dosya budur.

DESIGN.md ne kadar uzun olmalıdır?

Her adımda pişmanlık duymadan yüklenebilecek kadar kısa olmalıdır. Yayınlanmış örnekler uzundur çünkü tüm bir görsel dili tanımlarlar: Ağustos 2026 itibarıyla Nuxt dosyası yaklaşık 2.100, Vercel dosyası ise yaklaşık 6.500 kelimedir. Bir arka uç (backend) servisi genellikle çok daha azına ihtiyaç duyar. Tek bir sayfayla başlayın ve yalnızca bir ajan, tek bir cümleyle önlenebilecek bir hata yaptığında dosyayı genişletin. Ölçüt uzunluk değildir. Her satır, ajanın aksi takdirde yanlış yapacağı bir bilgi olmalıdır.