Kodlama Aracıları için DESIGN.md Nedir?

Kodlama aracıları, siz aksini söyleyene kadar kod tabanınız hakkında kendine güvenli, hızlı ve mimari açıdan bilgisizdir. Claude Code veya Codex'e belirsiz bir talimat verin; derlenen, hızlı bir testi geçen ve alan katmanınız ile HTTP katmanınız arasındaki sınırı sessizce ihlal eden kodlar yazmaktan mutluluk duyacaktır. Aracı, tasarım belgelerinizi okumadı. Gördüğü dosyaları okudu, desen eşleştirmesi yaptı ve tahminde bulundu. Bir DESIGN.md dosyası, mimari niyetinizi bir aracının her zaman baktığı tek yere, yani deponun kendisine yazarak tahmin sorununu çözer.

TL;DR

DESIGN.md, bir kod tabanının mimari niyetini, kısıtlamalarını ve tasarım kararlarını basit Markdown formatında kaydeden bir topluluk-konvansiyon deposu dosyasıdır, böylece kodlama aracıları (Claude Code, Codex, Cursor) sistemle mücadele etmek yerine ona uyan kodlar üretir. AGENTS.md "nasıl derleyip test ederim" sorusunu yanıtlarken, DESIGN.md "kod neden bu şekilde" sorusunu yanıtlar.

Giriş

Kodlama araçlarını benimseyen her ekibin bir hafta içinde karşılaştığı başarısızlık modu şudur: Bir aracıdan bir ödeme hizmetine iade uç noktası eklemesini istersiniz. Aracı, veritabanını doğrudan denetleyiciden çağıran, ağ geçidi hatasını yutan ve zaten bir tane olduğunu fark etmediği için yeni bir para türü icat eden çalışan bir işleyici döndürür. Fark temizdir. Testler geçer. Ancak mimariyi bilen bir gözden geçirenin yakalayabileceği üç yönden de yanlıştır. Aracı kodlama konusunda kötü değildir; sadece sizin kafanızda, bir Notion sayfasında veya sekiz ay önceki bir Slack yazışmasında yaşayan kararlara kördür.

DESIGN.md, giderek artan sayıda ekibin üzerinde anlaştığı yanıttır. Bu, deponun köküne işlenmiş tek bir Markdown dosyasıdır ve herhangi bir aracıya sisteminizle ilgili temel gerçekleri, yani katmanlama kurallarını, asla bozulmaması gereken değişmezleri, bilerek seçtiğiniz kalıpları ve reddettiğiniz kalıpları anlatır. Bu bir satıcı şartnamesi değildir ve ona sahip bir komite yoktur; bu, ARCHITECTURE.md ve CONTRIBUTING.md'nin birer konvansiyon olduğu gibi bir konvansiyondur. Ancak araçların zaten okuduğu araca özgü talimat dosyalarıyla doğal olarak eşleşir ve API ve arka uç çalışmaları için yazabileceğiniz en yüksek kaldıraçlı belgelerden biridir.

DESIGN.md aslında nedir?

DESIGN.md, kodunuzun neden bu şekilde göründüğünün düz metin bir kaydıdır. Ne yaptığını değil (bu README), nasıl çalıştırılacağını değil (bu AGENTS.md), ancak deneyimli bir mühendisin önemli bir şeye dokunmasına izin vermeden önce yeni bir çalışana ilk günden itibaren anlatacağı mantıktır.

Herhangi bir dosyada olmayan konuşmaları düşünün. "Ödeme ağ geçidini istek iş parçacığından çağırmıyoruz; ağ geçidi yük altında zaman aşımına uğradığı için her şey giden kutusu tablosundan geçer." "Para her zaman küçük birimlerin tam sayı sayımıdır; yuvarlama olayından sonra ondalık sayıları yasakladık." "Account toplamı bakiye mutasyonlarının sahibidir; başka hiçbir şey deftere yazmaz." Bunlar tasarım kararlarıdır. Kaynak kodu okuyan bir aracı için görünmezdirler, çünkü kaynak, kararın kendisini veya mantığını değil, kararın sonucunu gösterir. Bir aracı Account.debit()'in var olduğunu görebilir. Ancak bunu kasıtlı olarak tek yazma yolu yaptığınızı göremez, bu yüzden neşeyle ikinci bir tane ekleyecektir.

Bu konvansiyonun kökleri daha eski, köklü uygulamalara dayanmaktadır. ARCHITECTURE.md kalıbı (Alex Kladov'un geniş çapta alıntı yapılan yazısıyla popüler hale gelmiştir), bir deponun kod tabanının yapısını ve değişmezlerini, kodla satır satır senkronize kalmaya çalışmadan açıklayan yüksek seviyeli bir harita taşıması gerektiğini savunur. Mimari Karar Kayıtları (ADR'ler) bireysel kararları ve bunların zaman içindeki mantığını yakalar. DESIGN.md, bu tür bir belgeyi kodlama aracısını içeren bir kitle için yazdığınızda elde ettiğiniz şeydir: kısa, bildirimsel, karar odaklı ve aracının gerçekten yükleyeceği bir yere park edilmiş.

İki özellik çalışmasını sağlar. Depoda bulunur, böylece aracı kodu okuduğu aynı araçlarla okur; bir eklentiye veya API çağrısına ihtiyacınız yoktur. Ve niyetle ilgilidir, bu nedenle dosyalar taşınsa bile kullanışlı kalır. Bir paketi yeniden adlandırdığınızda README ekran görüntüleri çürür; "alan mantığı asla web çerçevesini içe aktarmaz" kuralı hala geçerlidir.

DESIGN.md vs AGENTS.md vs CLAUDE.md vs README

Bu dosyalar insanları karıştıracak kadar örtüşmekle birlikte, tek bir dosyada birleştirmek hata olacak kadar farklıdır. Kısa versiyonu: README yeni başlayan insanlar içindir, AGENTS.md aracılar için operasyonel sözleşmedir, CLAUDE.md Claude'a özel talimat dosyasıdır ve DESIGN.md hepsinin faydalandığı mimari gerekçedir.

AGENTS.md artık gerçek, geniş çapta benimsenmiş bir formattır; agents.md projesi bunu "kodlama aracılarını yönlendirmek için basit, açık bir format" olarak tanımlar, on binlerce projede kullanılır ve Linux Vakfı'nın Agentic AI Vakfı tarafından denetlenir. İşi operasyoneldir: derleme adımları, test komutları, kod stili, commit kuralları, yeni bir takım arkadaşınıza engelleri kaldırması için söyleyeceğiniz şeyler. Anthropic'in Claude Code bellek belgelerine göre, CLAUDE.md özellikle Claude için aynı talimat rolünü oynar; belgeler hatta zaten bir AGENTS.md dosyanız varsa, her iki aracın da tek bir doğru kaynaktan okuması için onu @AGENTS.md ile içe aktaran bir CLAUDE.md oluşturmanızı önerir.

Bu açıklamalarda neyin eksik olduğuna dikkat edin: derin mimari mantık. AGENTS.md ve CLAUDE.md kısa olacak şekilde ayarlanmıştır. Claude Code belgeleri, daha uzun dosyaların bağlam tükettiği ve modelin onları ne kadar güvenilir bir şekilde takip ettiğini azalttığı için CLAUDE.md'yi 200 satırın altında tutmayı açıkça önermektedir. Gerçek bir mimari açıklama, sınırlar, değişmezler, reddedilen alternatifler, veri modeli kuralları, onu şişirmeden oraya sığmaz. Bu yüzden onun yerine ona atıfta bulunursunuz. DESIGN.md derin belge haline gelir; AGENTS.md / CLAUDE.md tek bir satırla ona işaret eder.

İlişki tamamlayıcıdır, rekabetçi değildir. Bir Claude + Codex mağazası için temiz bir kurulum şöyle görünür: İnsanlar için README.md; derleme/test/stil içeren tek bir AGENTS.md; sadece @AGENTS.md ve iki Claude'a özgü satırdan oluşan bir CLAUDE.md; ve mimariyi barındıran, AGENTS.md'den bağlantılı DESIGN.md, böylece her aracı onu talep üzerine yükler. Çoğaltma yok, her dosyanın tek bir işi var. Bu dosyalar arasında Claude'un bağlamını yapılandırma konusunda daha derinlemesine bir tur istiyorsanız, Claude Code iş akışları bellek modelini pratikte inceler.

DESIGN.md'ye ne koymalı (bir şablonla)

DESIGN.md, bir aracının koddan çıkaramayacağı soruları yanıtlamalıdır: sistemin şekli, tek bir dosyada görünmeyen kurallar ve kasıtlı olarak aldığınız kararlar. Bildirimsel tutun. Her bölüm, bir denetleyicinin uygulayacağı bir kural gibi okunmalı, bir deneme gibi değil.

Bunları ele alın:

• Sistem şekli: katmanlar veya modüller ve bağımlılıkların hangi yöne aktığı. Her sınır için bir cümle.
• Değişmezler (Invariants): her zaman doğru olması gereken şeyler. Bunları mutlaklar olarak belirtin. "Yetkili bir aşım dışında bakiyeler asla eksiye düşmez." "Her harici çağrı, istek anahtarı tarafından idempotenttir."
• Anahtar kararlar ve gerekçeleri: nedenini öğrenene kadar keyfi görünen seçimler. Nedenini ekleyin; gerekçe, bir aracının bunu "düzeltmesini" engelleyen şeydir.
• Reddedilen alternatifler: kasıtlı olarak yapmadığınız şeyler, böylece bir aracı bunu yeni bir fikir olarak önermez. Bu tek bölüm, büyük bir kötü öneri sınıfını önler.
• Veri ve alan kuralları: para temsili, zaman/saat dilimi yönetimi, tanımlayıcılar, soft-delete (yumuşak silme), çoklu kiralama (multi-tenancy).
• API sözleşmesinin doğru kaynağı: OpenAPI belirtiminin nerede olduğu ve el yazısıyla yazılmış türler üzerinde yetkili olduğu kuralı.
• Yeni kodun nereye gittiği: aracılar mantığı dağıtmayı bıraksın diye, kısa bir "X ekliyorsanız, Y'ye aittir" haritası.
• Kapsam dışı / dokunulmaması gerekenler: oluşturulan dosyalar, geçiş halindeki eski modüller, bir aracının yalnız bırakması gereken her şey.

İşte gerçekçi bir ödeme API hizmeti için yazılmış tam bir şablon. Kopyalayın, geçerli olmayanları silin, gerisini doldurun.

# DESIGN.md: Payments API Service

This file records architectural intent and the decisions behind it.
Read this before generating or modifying code. If a change conflicts
with a rule here, stop and flag it instead of working around it.

## System shape

Layered, dependencies point inward only:

  http (handlers, DTOs)  ->  app (use cases)  ->  domain (entities,
  invariants)  <-  infra (db, gateway clients)

- `domain/` has zero imports from `http/`, `app/`, or any framework.
- `infra/` implements interfaces declared in `domain/` or `app/`.
- `http/` never touches the database or the payment gateway directly.
  It calls a use case in `app/`.

## Invariants (must always hold)

- A ledger entry is immutable once written. Corrections are new
  compensating entries, never updates or deletes.
- Account balance is derived from ledger entries, not stored as a
  mutable field that code can set directly.
- Money is an integer count of minor units (cents) plus an ISO-4217
  currency code. Never a float. Never mix currencies in one operation.
- Every call to an external payment gateway is idempotent, keyed by
  `idempotency_key`. Retries must not double-charge.
- Balances never go negative unless an explicit `OverdraftPolicy`
  authorizes it for that account.

## Key decisions and rationale

- **Outbox pattern for gateway calls.** Handlers write an intent row
  in the same DB transaction as the business change, then a worker
  calls the gateway. Rationale: the gateway times out under load;
  doing it inline made request latency and failure handling unowned.
  Do not call the gateway from a request handler.
- **Single write path per aggregate.** Only `Account.post_entry()`
  writes to the ledger. Rationale: a second write path caused the
  Mar-2025 balance drift. Add new behavior as methods on the
  aggregate, not new queries.
- **Event sourcing for the ledger only.** The rest of the system is
  CRUD. Rationale: we need a perfect audit trail for money and
  nothing else, and full event sourcing was too costly elsewhere.

## Rejected alternatives (do not reintroduce)

- ORM lazy-loading across aggregates; caused N+1s and unclear
  transaction boundaries. Repositories return fully-loaded aggregates.
- Storing balance as a column updated in place; see balance drift
  incident. Balance is always derived.
- A generic `Money` library pulled from the registry; we have our
  own `domain/money.py`; use it.
- Synchronous webhooks to merchants from the request thread; they
  block and fail silently. Use the notification queue.

## Data and domain rules

- All timestamps are UTC, stored as timestamptz, formatted RFC 3339
  at the edge. No naive datetimes cross a function boundary.
- IDs are ULIDs generated in the app layer, never DB autoincrement.
- Soft delete is not used. Records are either active or moved to an
  archive table by an explicit use case.
- Multi-tenant: every query is scoped by `tenant_id`. A repository
  method without a tenant scope is a bug.

## API contract source of truth

- The OpenAPI 3.1 spec in `api/openapi.yaml` is authoritative.
  Request/response types are generated from it; do not hand-edit the
  generated types in `http/generated/`.
- New or changed endpoints: update `api/openapi.yaml` first, then
  regenerate, then implement. The spec is designed and reviewed in
  Apidog before code changes.
- Error responses follow RFC 9457 (problem+json). Use the shared
  `problem()` helper; do not invent ad-hoc error shapes.

## Where new code goes

- New endpoint: route in `http/routes/`, DTO in `http/dto/`, use
  case in `app/usecases/`, domain logic in `domain/`.
- New external integration: client in `infra/clients/`, interface
  in `app/ports/`.
- Cross-cutting concern (auth, logging, idempotency): middleware in
  `http/middleware/`, never inline in handlers.

## Out of scope / do not touch

- `http/generated/`: regenerated from OpenAPI, edits are lost.
- `legacy/billing_v1/`: frozen, under migration. Do not extend.
- `migrations/`: never edit an applied migration; add a new one.

## When in doubt

If a requested change requires breaking a rule above, the right move
is to say so and propose the smallest design-consistent alternative,
not to silently work around the rule.

Bu son bölüm göründüğünden daha önemlidir. Bir istek tasarımla çeliştiğinde bir aracıya ne yapacağını söylemek, dosyayı pasif bir belgeden aktif bir koruyucu bariyere dönüştürür. Bu olmadan, bir kısıtlamaya çarpan bir aracı, etrafından dolaşma eğilimindedir ve geçici çözümü gönderir.

Kodlama aracıları DESIGN.md'yi aslında nasıl tüketir?

Aracıların özel bir DESIGN.md ayrıştırıcısı yoktur. Herhangi bir dosyayı tükettikleri gibi tüketirler: dosya araçlarıyla okuyarak ve içeriği bağlam olarak ele alarak. Bu nedenle, yüklenmesinin mekaniği önemlidir ve araca göre biraz farklılık gösterir.

Güvenilir desen, DESIGN.md'yi her aracının başlangıçta yüklediği talimat dosyasından referans almaktır. Claude Code için bu CLAUDE.md'dir; bellek belgeleri, @DESIGN.md'nin oturum başlangıcında dosyayı bağlama genişlettiği bir @path içe aktarma sözdizimini açıklar. AGENTS.md ekosistemi için, AGENTS.md dosyasına onu işaret eden bir satır eklersiniz ("Mimari ve tasarım kuralları: DESIGN.md'ye bakın; yapısal değişikliklerden önce okuyun"). Dizin ağacında dolaşan aracılar en yakın AGENTS.md'yi bulacak, işaretçiyi görecek ve çalışma mimariye dokunduğunda DESIGN.md'yi çekecektir. Her iki durumda da içerik kopyalamıyorsunuz; kısa operasyonel dosyayı kısa tutuyor ve derin dosyanın derin olmasına izin veriyorsunuz.

Bu araçların davranışlarından üç pratik not:

Birincisi, aracı dosyayı bağlam olarak ele alır, uygulanmış kurallar olarak değil. Claude Code belgeleri, CLAUDE.md içeriğinin modelin izlemeye çalıştığı bir rehberlik olduğunu, katı bir kısıtlama olmadığını açıkça belirtir. Bu, ondan referans aldığınız her şey için de geçerlidir. Bu yüzden şablon her şeyi test edilebilir mutlaklar olarak ifade eder ve açık bir "şüpheye düştüğünüzde" talimatı ekler; belirsiz metin baskı altında göz ardı edilir, keskin kurallar daha sık takip edilir.

İkincisi, uzunluk ve yapı bağlılığı değiştirir. Başlıklar ve madde işaretleri paragraflardan daha iyidir çünkü model yapıyı bir okuyucunun yaptığı gibi tarar. 3 sayfalık bir mimari felsefe duvarı gözden geçirilecek; açık bir başlık altındaki on net değişmez kullanılacaktır. Nesir için değil, geri çağırma için yazın.

Üçüncüsü, dosya sadece üretim değil, inceleme ekonomisini de değiştirir. Bir aracı kısmen göz ardı etse bile, bir gözden geçiren ihlal edilen kuralı işaret edebilir ve aracı tek seferde düzeltir ("bu, DESIGN.md'deki tek yazma yolu kuralını bozar"). Bu geri bildirim döngüsü, düzeltmeyi yazılı karara dayandırarak gerçek değerin çoğunun sağlandığı yerdir. Kendi aracı sistemlerini kuran ekipler tam da buna dayanır; bu döngünün otonom akışlara nasıl bağlandığını kendi Claude Code'unuzu oluşturun makalesinde görebilirsiniz.

Anti-pattern'lar ve çürümesini önleme

DESIGN.md'yi değersiz hale getirmenin en hızlı yolu, onu bir wiki sayfası gibi yazmaktır. Çürümüş bir tasarım dosyası, hiç olmamasından daha kötüdür, çünkü hem aracılar hem de insanlar ona güvenir ve yanıltılır. Bunlardan kaçının.

Kodu yeniden belirtmek. "UserService sınıfı kullanıcıları yönetir" cümlesi, bir aracıya user_service.py dosyasından okuyamayacağı hiçbir şey söylemez. Eğer bir cümle dosyayı okuyarak doğruysa, kesin. Yalnızca kodun size söyleyemediği şeyleri tutun: gerekçe, değişmezler, reddedilen yollar.

Eğitim sürünmesi. Adım adım "nasıl özellik eklenir" kılavuzları CONTRIBUTING.md'ye veya bir beceriye aittir, buraya değil. DESIGN.md'de kabuk komutları ve kopyala-yapıştır parçacıkları olduğu an, yanlış bir belgedir ve araç hızıyla eskimeye başlar.

Arzuyu gerçek olarak sunmak. Sistemin yarısı kullanmadığı halde "sistem CQRS kullanıyor" yazmak, aracıları bir kurguya uygun kod üretmeye yönlendirir. Şimdi neyin doğru olduğunu ve kasıtlı olarak nereye gittiğinizi belgeleyin ve farkı etiketleyin. "Hedef: tüm yazma işlemleri kullanım senaryolarından geçer. Mevcut: legacy/ bunu atlıyor; genişletmeyin."

Sahipsiz, inceleme tetikleyicisi yok. Kimsenin sorumlu olmadığı bir tasarım dosyası bir çeyrek içinde sürüklenir. Bunu bir tetikleyiciye bağlayın: bir modül ekleyen, bir katman sınırını değiştiren veya yeni bir harici bağımlılık tanıtan herhangi bir PR'da DESIGN.md'yi inceleyin. Bu kuralı PR şablonuna koyun. Bazı ekipler bir kontrol listesi öğesi ekler: "bu, DESIGN.md'deki bir kararı değiştiriyor mu? Eğer öyleyse, aynı PR'da güncelleyin."

Senkronizasyon tiyatrosu. Kodla satır satır senkronize tutmaya çalışmayın; bu kaybeden bir oyundur ve mimari belgelerin terk edilmesinin nedenidir. Haftalık değişen fonksiyon imzaları seviyesinde değil, yılda birkaç kez değişen karar seviyesinde tutun. Matklad ARCHITECTURE.md rehberliği burada doğru içgüdüdür: yalnızca sık sık değişme olasılığı düşük olanı yazın.

Diğer talimat dosyalarıyla çelişmek. Eğer AGENTS.md hata yönetimi hakkında bir şey söylüyor ve DESIGN.md başka bir şey söylüyorsa, aracılar keyfi olarak birini seçer. Operasyonel kuralları AGENTS.md / CLAUDE.md'de, mimari kuralları ise DESIGN.md'de tutun ve çakışmalarına izin vermeyin. Birbirlerine atıfta bulunmaları gerektiğinde, biri diğerine işaret eder; ikisi de aynı gerçeği iddia etmez.

Sağlıklı bir DESIGN.md kısa, yoğun, bildirimsel, sahiplenilmiş ve bir tetikleyici üzerinde incelenmiştir. Sizinki uzun, anlatımcı ve son bir yıl önce dokunulmuşsa, aracılar kurgu okuyor demektir.

API ve arka uç kod tabanları için DESIGN.md

Dosyanın kendini amorti ettiği yer burasıdır. API ve arka uç hizmetleri, aracıların en kötü olduğu görünmez, yüksek maliyetli kısıtlamalara sahiptir: sözleşme sınırları, işlem semantiği, eşsizlik (idempotency), veri bütünlüğü, katmanlama. Bunların hiçbiri tek bir dosyadan belli değildir ve yanlış yapmak, üretime ve paraya mal olan hatalara yol açar.

Bu API'ye özgü şeyleri DESIGN.md'ye koyun, arka uç görevlerinde aracı çıktısının kalitesi artacaktır:

Sözleşme doğruluk kaynağıdır ve nerede olduğunu belirtin. OpenAPI belirtiminin yetkili olduğunu ve oluşturulan türlerin elle düzenlenmemesi gerektiğini açıkça belirtin. Aracılar, bir derlemeyi geçirmek için oluşturulan bir türü "yardımsever bir şekilde" değiştirmeyi severler; DESIGN.md'deki tek bir satır bunu durdurur. Belirtim dosya yolunu işaret edin. Eğer sözleşmeyi önce Apidog'da tasarlar ve OpenAPI belgesini depoya aktarırsanız, DESIGN.md'niz bu dosyayı her uç noktanın uyması gereken şey olarak adlandırabilir ve aracının belirsiz olmayan bir hedefi olur. Koddan önce sözleşmeyi tasarlama argümanı AI aracıları için API tasarlama makalesinde ele alınmıştır; tasarıma öncelik veren bir sözleşme, aracı tarafından oluşturulan işleyicileri kabul edilebilir kılan şeydir.

İşlem ve tutarlılık sınırları. Bir işlem nerede başlar ve biter? İçinde neye izin verilir? "Harici çağrılar asla bir DB işlemi içinde gerçekleşmez; giden kutusunu kullanın." Dosya bunu yasaklamazsa, aracılar her zaman saf satır içi çağrıya başvurur.

Eşsizlik ve yeniden denemeler. Eşsizlik stratejisini bir değişmez olarak belirtin. Ödeme, sipariş ve sağlama uç noktaları, eksik bir eşsizlik anahtarının iki kez ücretlendirmeye yol açtığı yerlerdir. Aracı bunu bir işleyiciyi okuyarak çıkaramaz.

Hata modeli. Tek cümle: "tüm hatalar problem() yardımcı işlevi aracılığıyla problem+json'dur; asla geçici hata biçimleri icat etmeyin." Bu olmadan, her uç nokta için farklı bir hata zarfı elde edersiniz, bu da her istemciyi bozar.

Kimlik doğrulama ve kiralama kapsamı. "Her sorgu kiracı kapsamlıdır; kiracı kapsamı olmayan bir depo metodu bir hatadır." Bu bir güvenlik değişmezidir ve herhangi bir bireysel sorguda görünmezdir, bu yüzden yazılması gereken tam da bu tür bir kuraldır.

Sürümleme ve kırıcı değişiklik kuralları. Neyin kırıcı sayıldığı, nasıl sürümlendiği, bir minör sürümde neye izin verildiği. Aracılar bir yanıt alanını memnuniyetle yeniden adlandıracaktır; dosya onlara bunun bir süreçle birlikte kırıcı bir değişiklik olduğunu söyler.

Arka uç çalışmaları için getirisi somuttur: daha az katmanlama ihlali, sürpriz satır içi ağ geçidi çağrısı yok, tutarlı hata ve sayfalama biçimleri ve şemayı tahmin etmek yerine OpenAPI belirtimine yönlendirildiği için sözleşmeye uygun işleyiciler. Aracı icat etmeyi bırakır ve uyum sağlamaya başlar. Eğer aracının yeni yazdığı API'yi de çalıştırmasını isterseniz, sözleşme artı tasarım kombinasyonu, araçların ve aracıların bilinen bir arayüze karşı test yapmasını sağlayan şeydir; Apidog'u indirin size önce tasarımı yapacağınız çalışma alanını, DESIGN.md'nizin işaret ettiği OpenAPI dışa aktarımını ve oluşturulan uç noktaların sözleşmeyle gerçekten eşleştiğini kontrol etmek için bir MCP sunucusu ve AI-aracı hata ayıklayıcısını sunar.

Sonuç

• DESIGN.md, kodunuzun neden bu şekilde olduğunu kaydeder: bir aracının kaynaktan okuyamayacağı değişmezler, kararlar ve reddedilen alternatifler.
• AGENTS.md ve CLAUDE.md'yi tamamlar, yerini almaz: onlar kısa ve operasyonel kalır; DESIGN.md derin mimariyi tutar ve onlardan referans alınır.
• Bildirimsel olarak, test edilebilir mutlaklar artı "şüpheye düştüğünüzde, etrafından dolaşmayın, bildirin" kuralı olarak yazın, böylece pasif bir metin değil, bir koruyucu bariyer görevi görür.
• En çok API ve arka uç kod tabanlarında işe yarar, çünkü sözleşme sınırları, işlemler, eşsizlik ve kiralama kapsamı görünmezdir ve yanlış yapılması pahalıya mal olur.
• PR şablonunuza bağlı bir sahibi ve bir inceleme tetikleyicisi ile çürümesini önleyin; asla kodla satır satır senkronize etmeyin.
• En büyük arka uç kazancı, OpenAPI belirtimini yetkili olarak adlandırmaktır, böylece aracılar şema icat etmek yerine sözleşmeye uyum sağlarlar.
• Önce o sözleşmeyi tasarlayın. API'leri önce tasarıma göre oluşturmak, DESIGN.md'nizin işaret ettiği OpenAPI belirtimini dışa aktarmak ve aracı tarafından oluşturulan uç noktaların gerçekten eşleştiğini test etmek için Apidog'u indirin.

Sıkça Sorulan Sorular

DESIGN.md, AGENTS.md gibi resmi bir standart mıdır?

Hayır. AGENTS.md, şu anda Linux Vakfı'nın Agentic AI Vakfı tarafından denetlenen, tanımlanmış, geniş çapta benimsenmiş bir formattır. DESIGN.md, ARCHITECTURE.md ve ADR'lerle aynı ailede yer alan, tek bir sahibi veya belirtimi olmayan bir topluluk konvansiyonudur. Onu uyum sağlamanız gereken bir standart olarak değil, uyarlayacağınız faydalı bir kalıp olarak ele alın.

AGENTS.md veya CLAUDE.md dosyalarım zaten varsa DESIGN.md'ye ihtiyacım var mı?

Mimarinizde bariz olmayan kısıtlamalar varsa evet. AGENTS.md ve CLAUDE.md kısa ve operasyonel kalmak içindir; Claude Code belgeleri CLAUDE.md'yi yaklaşık 200 satırın altında tutmayı önermektedir. Derin mimari mantık, onu şişirmeden ve bağlılığı zedelemeden oraya sığmaz, bu yüzden onu DESIGN.md'ye koyar ve ondan referans alırsınız. Operasyonel dosyanın kendisi için, AGENTS.md dosyaları nasıl yazılır makalesine bakın.

DESIGN.md, ARCHITECTURE.md'den nasıl farklıdır?

Çoğunlukla amaç ve kitle açısından. ARCHITECTURE.md, kod tabanını haritalayan insan katkıda bulunanlara yönelik eski bir konvansiyondur. DESIGN.md, kodlama aracısını içeren bir kitle için yazılmış aynı fikirdir: daha bildirimsel, karar ve değişmez odaklıdır ve bağlama yüklenmesi için aracı talimat dosyalarından açıkça referans alınır. Birçok ekip tek bir dosya ve tek bir isim kullanır; ilkeler aynıdır.

DESIGN.md ne kadar uzun olmalı?

Aracıların sürekli yanlış yaptığı kararları kapsayacak kadar uzun, her satırın yerini hak ettiği kadar kısa olmalıdır. Karar yoğunluğu, kapsamlı olmaktan daha iyidir. Eğer bir eğitim gibi okunuyor veya kodu yeniden belirtiyorsa, kesin. İki ila dört sayfalık odaklanmış değişmezler ve gerekçeler, hiçbir aracının dikkatlice okumayacağı on beş sayfalık bir anlatıdan daha iyidir.

Aracının onu gerçekten okumasını nasıl sağlarım?

Aracının başlangıçta yüklediği dosyadan referans alın. Claude Code için, CLAUDE.md'den @DESIGN.md ile içe aktarın. AGENTS.md ekosistemi için, yapısal değişikliklerden önce DESIGN.md'yi okumalarını söyleyen bir işaretçi satırı AGENTS.md'ye ekleyin. Her şeyi kısa dosyaya yapıştırmayın; operasyonel dosyanın kısa kalması için referans alın.

Aracı her zaman DESIGN.md'yi takip edecek mi?

Hayır ve buna göre tasarım yapmalısınız. Aracı talimat dosyaları, modelin takip etmeye çalıştığı bir bağlamdır, uygulanan bir yapılandırma değildir. Kuralları keskin mutlaklar olarak yazın, açık bir "çelişkileri işaretleyin, etrafından dolaşmayın" talimatı ekleyin ve inceleme döngüsüne güvenin; DESIGN.md'deki ihlal edilmiş bir kuralı işaret etmek, ilk geçişte kaçırılmış olsa bile hızlı ve doğru bir düzeltme sağlar.

DESIGN.md özellikle API sözleşme sorunlarına yardımcı oluyor mu?

Çok. En değerli arka uç kullanımı, OpenAPI belirtiminin yetkili olduğunu belirtmek ve dosyayı adlandırmaktır, böylece aracılar şema icat etmek veya oluşturulan türleri elle düzenlemek yerine sözleşmeye uyum sağlarlar. Bu sözleşmeyi önce Apidog gibi bir araçta tasarlamak, aracıya DESIGN.md'nizin doğrudan işaret edebileceği belirsiz olmayan bir hedef verir.

DESIGN.md depoda nerede bulunmalıdır?

Depo kökünde, README.md ve AGENTS.md'nin yanında, böylece aracılar ve insanlar onu sıfır aramayla bulabilir. Monorepo'da, sistem çapında kurallar için bir kök DESIGN.md artı yerel mimari için pakete özgü bir tane iyi çalışır, bu da aracıların dizin ağacındaki en yakın AGENTS.md'yi nasıl okuduğunu yansıtır.