DESIGN.md dosyası nedir ve neden gereklidir?

DESIGN.md nedir ve AGENTS.md neleri kapsamaz

DESIGN.md, depo kök dizininizde 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? Yani derleme komutu, test komutu, geçilmesi gereken lint aracı ve dokunulmaması gereken yollar. 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üzenleyebilen bir kodlama aracı, varsayılan olarak özgüvenlidir. Tanımadığı bir kalıp bulduğunda bu kalıbı iyileştirmeye çalışır. El yazısı bir önbellek, Redis (bellek içi bir veri deposu) haline getirilir; çünkü modelin okuduğu çoğu kodda önbellek böyle 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ğildi.

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ı 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 nedir

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 temel 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 barındırıldığından, bir tanesini hemen şimdi terminal üzerinden 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. 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 listeden ibarettir.

Ş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ış bu dosyalar, bir aracıya (agent) verildiğinde o görünüme yakın bir sonuç üretilmesini sağlıyor. Bu dosyalar faydalı olsa da hala birer tahminden ibaretler. Şirketlerden hiç kimse bu dosyaları incelemedi.

Birinci taraf (first-party) bir dosya ise çıktının bir okuması değil, kaynağın kendisi olduğu için farklıdır. 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 açıkça belirtiyor: standart yeni ve resmi benimsenme artıyor. Her iki koleksiyon da kendi dosyasını yayınlayan açık kaynaklı aracı çerçevesi VoltAgent tarafından sürdürülüyor; bu nedenle listeyi tarafsız bir nüfus sayımı olarak değil, bir takipçi 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'da bulunuyor. 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 projelerde DESIGN.md dosyasında neler yer almalı

Bir VPS üzerinde çalışan çoğu yazılımın tanımlanacak görsel bir dili yoktur. Bu dosya, mekanizmanın renklerle hiçbir ilgisi olmamasına rağmen yine de gereklidir. Dosyanın amacı, deneyimli bir editörün 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 maddeler. "Her yazma işlemi queue.enqueue() üzerinden gerçekleşir. Doğrudan veritabanına yapılan yazma işlemleri denetim günlüğünü (audit log) atlar ve uyumluluk dışa aktarma aracı denetim günlüğünü okur." Gerekçesiyle birlikte sunulan bir değişmez, öngörülemeyen bir görevle karşılaşıldığında bile varlığını korur. Gerekçesiz bir değişmez ise sadece bir 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) bir harita daha hızlıdır ve canlı tutulması gereken bir daemon daha azdır. İkinci bir uygulama sunucusu eklendiğinde bu kararı tekrar değerlendirin." Bu paragraf olmadan, önbelleği hızlandırması istenen bir temsilci Redis ekleyecektir ve bunu yapmakta haklıdır; çünkü ona bu kısıtlamadan bahsetmediniz. Bu bölüm, dosyanın tüm maliyetini karşılayan kısımdır.

Sınırlar (Boundaries). Küçük bir değişikliğin büyük bir etki alanına sahip olduğu noktalar. Veritabanı şeması. Müşterilerin halihazırda betiklerinde kullandığı genel yol öneki (route prefix). Uygulama başlamadan önce dağıtımın okuduğu yapılandırma dosyası. Yalnızca tek bir kopyasının çalıştığını varsayan cron girdisi. Bunları adlandırın ve her birinde yapılacak değişikliğin maliyetini belirtin. Eğer temsilci açık web'e de erişebiliyorsa, örneğin arama arka ucu olarak yapılandırılmış self-hosted bir SearXNG örneği üzerinden, bu da yazılması gereken bir sınırdır. Çünkü dosya, hangi getirilen metnin kod üzerinde etkili olabileceğini ve hangisinin yalnızca size alıntılanacağını belirtmelidir.

Sözlük (Vocabulary). Eğer kod tenant diyorsa ve ekip customer terimini kullanıyorsa, bu eşleşmeyi yazın. Burada yanlış tahminde bulunan bir temsilci, okunduğunda mantıklı görünen 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şmezleri ve reddedilen alternatifleri doldurun; gerisini 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. Eğer depo birden fazla paket içeriyorsa, tek bir kök dosya hepsine uymaz; monorepo içindeki iç içe AGENTS.md dosyaları için geçerli olan dizin bazlı ayrım burada da uygulanır: her şeyin paylaştığı kararlar için kısa bir kök dosya ve her paketin yanında kendine ait daha küçük bir dosya.

Bazı araçlar depodaki 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.

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

En yaygın kötü uygulama, akıcı bir dille yazılmış ancak hiçbir şey öğretmeyen sürümdür. Bu tür dosyalar projenin ne işe yaradığını anlatarak başlar, özellikleri listeler, kurulum talimatlarını verir ve lisans bilgisiyle biter. Bunların her satırı zaten README dosyasında mevcuttur ve hiçbiri bir şeyin neden o şekilde tasarlandığını açıklamaz.

Bu durum size iki kat maliyet getirir. İlk maliyet bağlamdır (context). Bir aracın her görev başlangıcında okuduğu bir dosya, her görevde maliyet yaratır; kopyalanmış 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öyler, DESIGN.md ise hala 3000 der; aracın hangisinin doğru olduğuna karar verme ş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 dosyayla aynı güvenle referans alınır.

Bunu test etmek kolaydır. Eğer bir paragraf README içinde sırıtmadan durabiliyorsa, 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. Ancak bir dakika içinde çalıştırabileceğiniz bir kontrol mevcuttur.

Agent'a 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: Agent, 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 doğrudan 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.

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

Bu durum, agent 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 bir agent'ı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 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 yapay zeka aracının bir insandan daha hızlı ve daha sık aynı hatayı yapacağı bir noktadır. Dosyaya, bir takvime göre değil, başarısız olduğunda ekleme yapın. Eğer hala aracıların normal bir geliştirme iş akışına nasıl dahil edileceğini çözmeye çalışıyorsanız, 2026 yapay zeka aracılarını öğrenme rehberi mantıklı bir sonraki duraktır.

FAQ

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

AGENTS.md 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ımlanmış bir spesifikasyonu yoktur. Sahip olduğu şey, birinci taraf benimsenmesidir: Vercel, Nuxt, Atlassian ve Resend dahil olmak üzere yedi şirket, halka açık bir URL'de bir DESIGN.md yayımlamaktadır ve bir topluluk koleksiyonu, halka açık sitelerden tersine mühendislikle elde edilmiş 73 örnek daha barındırmaktadır. Bunu şu an benimseyebileceğiniz ve dilediğiniz gibi genişletebileceğiniz bir gelenek olarak görün, çünkü bölüm isimlerinizi doğrulayan bir kural 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 parçanın farklı hızlarda değiştiğini fark ettiğinizde bunları ayırın. AGENTS.md, yapılandırma 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 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 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 güncel durumdur ve her görevde bütünüyle okunmak üzere yazılır. Zaten ADR yazıyorsanız her ikisini de tutun. ADR, neyin ne zaman kararlaştırıldığını söyler. 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ımlanan örnekler uzundur çünkü bütün 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ın, tek bir cümleyle önlenebilecek bir hata yapması durumunda dosyayı büyütün. Ölçüt uzunluk değildir. Her satır, ajanın aksi takdirde yanlış yapacağı bir bilgi olmalıdır.