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ı açıklayan 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 okuyup düzenleyen bir kodlama aracı, varsayılan olarak özgüvenli hareket eder. Tanımadığı bir kalıp bulduğunda bu kalıbı iyileştirmeye çalışır. Elle yazılmış bir önbellek, Redis (bellek içi bir veri deposu) haline dönüşebilir; çü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ı oluşturmadıysanız, oradan başlayın. AGENTS.md ve yanındaki HUMAN.md dosyası, formatı ve her aracın bu dosyayı nerede aradığını açıklar. Aşağıdaki bölüm, 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 aldığından, 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 konu değil, 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 kurallardan meydana gelir:

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. Bu başlığın 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. Dosya, kendine güvenen 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 listeyi temsil eder.

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

Topluluk bu konuda öncü oldu. awesome-design-md deposu, halka 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 faydalı olsa da hala birer tahminden ibaret. Şirketlerden hiç kimse bu dosyaları 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 listeyi izlemeye değer. Bunlar, ön uç (front-end) kodları diğer geliştiriciler tarafından en çok kopyalanan şirketlerdir ve dosyaları, bir DESIGN.md dosyasının ne olduğuna dair işlenmiş örnekler haline gelmektedir. 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'a ait. Aracıların okuyabileceği dosyalara yönelik kurallar hızla yerleşiyor ve bu yerleşme yukarıdan aşağıya doğru gerçekleşiyor.

Kullanıcı arayüzü olmayan bir projede DESIGN.md dosyasına neler 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 varlığını hak eder. Dosyanın amacı, kendinden emin bir düzenleyicinin fark etmeden ihlal edebileceği kısıtlamaları kayıt altına almaktır.

Değişmezler (Invariants). Herhangi bir düzenlemeden sonra doğru kalması gereken bir durumu belirten, tek cümlelik ifadeler. "Her yazma işlemi queue.enqueue() üzerinden gerçekleşir. Doğrudan veritabanı yazma işlemi denetim günlüğünü (audit log) atlar; oysa uyumluluk dışa aktarma aracı denetim günlüğünü okur." Gerekçesiyle birlikte sunulan bir değişmez, öngöremediğiniz bir görevle karşılaştığında bile varlığını korur. Tek başına bırakılan bir değişmez ise tercih gibi algılanır ve tercihler optimizasyon sürecinde göz ardı edilebilir.

Reddedilen alternatifler. İlk akla gelen seçenek ve neden elendiği. "Önbellekleme için Redis kullanmıyoruz. Servis tek bir VPS üzerinde çalıştığı için süreç içi (in-process) harita daha hızlıdır ve ayakta tutulması gereken bir daemon daha eksilmiş olur. İkinci bir uygulama sunucusu eklendiğinde bu kararı tekrar değerlendirin." Bu paragraf olmadan, önbelleği hızlandırması istenen bir görevli Redis ekleyecektir ve bunu yapmakta haklıdır; çünkü ona bu kısıtlamadan bahsetmediniz. Dosyanın tüm maliyetini çıkaran bölüm burasıdır.

Sınırlar (Boundaries). Küçük bir değişikliğin büyük bir etki alanına (blast radius) sahip olduğu yerler. Veritabanı şeması. Müşterilerin halihazırda betiklerinde kullandığı genel yol öneki (route prefix). Uygulama başlamadan önce dağıtım aracının 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.

Kelime dağarcığı (Vocabulary). Kod tenant ifadesini kullanıyor ancak ekip customer diyorsa, bu eşleşmeyi yazılı hale getirin. Burada yanlış tahminde bulunan bir görevli, kodun düzgün görünmesine rağmen yanlış bir modeli temsil eden bir yapı oluşturur; 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.

Değişmezler (Invariants)

• Sistem, her zaman tek bir root kullanıcısı ile yapılandırılmalıdır.
• Ağ trafiği, yalnızca 443 numaralı port üzerinden şifreli olarak kabul edilir.
• Tüm servisler, systemd tarafından yönetilen bağımsız container birimleri olarak çalışır.
• Yapılandırma dosyaları, /etc/ dizini altında merkezi olarak tutulur.

Reddedilen Alternatifler

• Her servis için ayrı bir TLS sertifikası yönetimi, operasyonel yükü artırdığı için reddedilmiştir.
• iptables yerine nftables kullanımı, mevcut otomasyon araçlarıyla uyumsuzluk nedeniyle elenmiştir.

Mimari Kararlar

Güvenlik Modeli

Ölçeklendirme Stratejisi

``markdown
Read DESIGN.md before editing anything under src/. It lists the invariants and
the alternatives that were already rejected.
``AGENTS.md dosyasında tanımlanan ajan yapılandırmalarına göz atın.

Anti-pattern: README'yi tekrar eden bir DESIGN.md

En yaygın kötü sürüm, akıcı bir şekilde okunur ancak hiçbir şey öğretmez. Projenin ne işe yaradığını anlatarak başlar, özellikleri listeler, nasıl kurulacağını açıklar ve lisans bilgisiyle biter. Bunların her satırı zaten README dosyasında mevcuttur ve hiçbiri bir şeyin neden o şekilde tasarlandığına dair bilgi vermez.

Bu durum size iki kat maliyet getirir. İlk maliyet bağlamdır. Bir aracın her görevin başında okuduğu bir dosya, her görevde maliyet oluşturur ve yinelenen bir kurulum bölümü, sabit bir pencere karşısında safi yüktür. Bu pencereyi bütçelemek başlı başına bir beceridir ve Claude Code içinde bağlam penceresini yönetme konusunda ele alınmıştır. Kısa hali şudur: 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 uzaklaşır. README servisin 8080 portunu dinlediğini söyler, DESIGN.md ise hala 3000 der; aracın hangisine öncelik vereceğini belirleme şansı yoktur, bu yüzden birini seçer ve kodu ona göre yazar. Bazen yanlış olan bir dosya, her zaman doğru olan bir dosya ile aynı güvenle danışılır hale gelir.

Testi basittir. Bir paragraf README içinde rahatlıkla yer alabiliyorsa, onu DESIGN.md dosyasından çıkarın. Geriye kalan kısım, bir kod incelemesinde sesli olarak söyleyeceğiniz, "bunu zaten denemiştik" 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. Ancak 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." İşini yapan bir dosya, herhangi bir koddan önce cevapta kendini belli eder: Ajan, işin queue.enqueue() üzerinden yazılması 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 yazma yapı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.

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 bölümü, bu bütçenin nereye gittiğini 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 hiçbir hafızası yoktur. Depo (repository), hafızanın kendisidir. Sohbet içinde açıkladığınız ve 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 bunu 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 temsilcinin (agent) bir insandan daha hızlı ve daha sık aynı hatayı yapacağı bir noktadır. Dosyaya, bir takvime göre değil, sizi yarı yolda bıraktığında ekleme yapın. Temsilcilerin normal bir geliştirme iş akışına nasıl uyum sağlayacağını hala çözmeye çalışıyorsanız, 2026 yapay zeka temsilcilerini öğrenme rehberi makul bir sonraki duraktır.

FAQ

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

AGENTS.md dosyasının olduğu gibi değildir. 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 topluluk tarafından oluşturulan bir koleksiyon, halka açık sitelerden tersine mühendislik ile elde edilmiş 73 örnek daha içermektedir. Bunu şu an benimseyebileceğiniz ve dilediğiniz gibi genişletebileceğiniz bir gelenek olarak değerlendirin, çünkü bölüm isimlerinizi doğrulayan bir otorite yoktur.

DESIGN.md, AGENTS.md dosyasının 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 parçanın farklı hızlarda değiştiğini fark ettiğinizde bunları ayırın. AGENTS.md, derleme süreci değiştiğinde güncellenir. DESIGN.md ise bir karar değiştiğinde güncellenir; bu daha nadirdir ve daha fazla ağırlık taşır. Ayırma işlemi yaptığınızda, AGENTS.md dosyasına ajanın kod düzenlemeden önce DESIGN.md dosyasını okumasını söyleyen bir satır ekleyin, çünkü her araç kök dizindeki tüm markdown dosyaları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ör içinde 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. Eğer halihazırda ADR yazıyorsanız her ikisini de tutun. ADR, neyin ve ne zaman kararlaştırıldığını belirtir. DESIGN.md ise bugün neyin doğru olduğunu belirtir ve ajanı yönlendireceğiniz dosya budur.

Bir 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ç servisi genellikle çok daha azına ihtiyaç duyar. Tek bir sayfa ile başlayın ve yalnızca bir ajan, tek bir cümleyle önlenebilecek bir hata yaptığında dosyayı büyütün. Uzunluk bir ölçüt değildir. Her satır, ajanın aksi takdirde yanlış yapacağı bir bilgi içermelidir.