Problem: Eksik Olan Katman
AI coding agent’larla çalışırken her araç bir sorunu çözüyor:
| Doküman | Ne Yapar | Ne Yapmaz |
|---|---|---|
| README.md | Kullanıcıya projeyi tanıtır | Teknik yapıyı anlatmaz |
| CLAUDE.md / AGENTS.md | Agent’a talimat verir (kurallar, komutlar, sınırlar) | Projenin yapısını anlatmaz |
| ADR’ler | Kararları ve gerekçelerini kaydeder | Güncel durumu anlatmaz |
| Kod | Gerçeğin kendisi | Yüzlerce dosyaya dağılmış, taranması pahalı |
Agent her oturumda projeyi sıfırdan taramak zorunda kalıyor. Glob, grep, dosya okuma. Context window tool output’larıyla doluyor. Yüzeysel tarama yanlış çıkarımlara neden oluyor: iki farklı modüldeki benzer isimleri karıştırmak, kullanılmayan eski kodu aktif sanmak, altyapı detaylarını tahmin etmek.
Bu problemi kendi projelerimde yaşadım. 992 dosyalık bir monorepo’da agent’ın Inngest proxy worker yapısını araştırması ~20 dakika sürüyordu: SSH denemeleri, API endpoint tahminleri, port taramaları. Cevap aslında basit: container adı, portlar, tunnel route’ları, env var’lar. Ama bu bilgi hiçbir yerde yapılandırılmış halde yoktu. Bu kısmen benim sorunum; aklıma gelmemiş, gelmişse de göz ardı etmiş olabileceğim bir durum, katlıyorum. Ancak, bu durumu projedeki tüm servisler, yapılandırma kararları, vb. için düşünüldüğünde her bir parçayı hatırlamak ya da iş akışı içerisinde durum o konu için paralel bir düzenleme yapmak pek de olası değil. Haliyle, vakit kaybettiren, karar akışını sekteye uğratan ve/veya yanlış kararları temel alan bu durumu çözmek için statik olmayan (olabildiğince) bir yol bulmak gerkeliydi.
architecture.md bu boşluğu dolduruyor: projenin gerçek yapısını, tek bir dosyada, yapılandırılmış formatta anlatan “yaşayan” bir doküman.
Araştırma Temeli
Living Architecture’ı bir template olarak formalize etmeden önce, AI agent’lar için dokümantasyon konusunda kapsamlı bir araştırma yürüttüm. GPT-4o, Kimi K2.5 ve Gemini Deep Research ile paralel araştırmalar, akademik makaleler ve endüstri pratikleri.
Codified Context Yaklaşımı
108.000 satırlık bir C# projesinde test edilen üç katmanlı sistem1 denk geldiğim temel bulgulardan biriydi:
- Hot Memory: Convention’lar, retrieval hook’ları, orkestrasyon protokolleri. Pratikte CLAUDE.md veya AGENTS.md dosyası
- Domain Expert Agent’lar: Proje bazlı uzman agent’lar. Her biri belirli bir alanın kurallarını ve pattern’lerini biliyor
- Cold Memory: On-demand spesifikasyon dokümanları. Agent sadece ilgili olanı çekiyor
Kritik bulgu: dokümantasyon altyapıdır. Kod gibi sürekli bakımı gereken, agent’ların doğru çıktı üretmesi için zorunlu olan bir yapı.
AGENTS.md Ekosistemi ve Altı Temel Alan
Agentic AI Foundation tarafından standartlaştırılan AGENTS.md, farklı AI araçları için farklı dosyalar (CLAUDE.md, .cursorrules, SPEC.md) ama aynı amaca hizmet ediyor: agent’a yapılandırılmış bağlam vermek.
2.500’den fazla başarılı agent config dosyasının analizinden çıkarılan altı zorunlu alan2:
- Komutlar: Tam çalıştırılabilir string’ler (install, build, test, lint)
- Test: Framework, coverage beklentileri, mocking pattern’leri
- Proje Yapısı: Üst seviye dizin ağacı haritası
- Kod Stili: “Göster, Anlat” kod snippet’leri
- Git Workflow: Branch isimlendirme, commit formatı, PR checklist
- Sınırlar: Do/Don’t listeleri, operasyonel limitler
Bu altı alan CLAUDE.md veya AGENTS.md’nin kapsamı. Ancak projenin mimari yapısı, modüller arası ilişkiler, veri akışı, altyapı topolojisi, teknik borç gibi bilgiler bu alanlara sığmıyor. architecture.md’nin varoluş sebebi bu.
Hybrid Yaklaşım Konsensüsü
Tüm araştırma kaynakları aynı noktada birleşiyor:
| Katman | İçerik | Yöntem |
|---|---|---|
| Auto-generate | Schema, tipler, dependency graph, API imzaları | Repomix/CI hook ile kod değiştiğinde güncelle |
| Human-write | Tasarım kararları, kısıtlamalar, trade-off’lar | ADR formatı, “Kernel of Truth” workflow |
| Staleness detect | Doküman güncelliği takibi | Git hook veya CI check |
“What” otomatik üretilir, “why” insan yazar. İkisi birlikte agent’a tam resmi veriyor.
C4 Model ve Mermaid.js
C4 modeli (Context, Containers, Components, Code) AI agent’lar için ideal bir hiyerarşi sunuyor. Mermaid.js ile text-based diyagramlar olarak uygulandığında: version-control edilebilir, token-verimli, agent tarafından okunabilir ve düzenlenebilir.
Progressive Disclosure
200K token context window bile fazla bilgiyle doldurulduğunda performans düşüyor3. Çözüm: bilgiyi tümüyle yüklemek yerine, sadece ihtiyaç anında açmak.
| Teknik | Mekanizma | Fayda |
|---|---|---|
| Jump-to pointer’lar | Dosyalara path ile referans, içerik değil | Token tasarrufu |
| Çalıştırılabilir arama | AGENTS.md’de rg/grep komutları | Just-in-time keşif |
| Nested override’lar | Modül bazlı yerel AGENTS.md | Sadece ilgili kurallar yüklenir |
Bu araştırma bulguları, Living Architecture template’inin tasarım kararlarını doğrudan şekillendirdi.
Living Architecture: Tasarım Kararları
Araştırma bulgularını bir template’e dönüştürürken birkaç temel karar aldım.
Tek Dosya, Yapılandırılmış Bölümler
Mimari bilgiyi birden fazla dosyaya dağıtmak yerine tek bir architecture.md dosyasında toplamayı tercih ettim. Sebebi: agent oturum başında tek dosyayı referans olarak yükleyebiliyor. Birden fazla dosya arasında navigasyon, context window’da ek maliyet yaratıyor. Başlık hiyerarşisi sayesinde agent ihtiyacı olan bölüme atlayabiliyor.
Bölüm Bazlı Derinlik
Tüm projeye tek bir derinlik seviyesi atamak yerine, bölüm bazlı derinlik belirleme yaklaşımını benimsedim. 50 dosyalık bir projede Stack bölümü L1 yeterli olabilir ama 15 veritabanı tablosu varsa Data Model bölümü L2’ye çıkmalı.
Opsiyonel Modüller
Her projenin monorepo yapısı, background job’ları veya i18n desteği yok. 11 opsiyonel modülü “tetikleyici koşullar” ile tanımladım: pnpm-workspace.yaml varsa Monorepo Structure modülünü ekle, yoksa sil. Bu, template’in şişmesini önlüyor.
Gerçek Projelerden Türetme
Template’i soyut olarak tasarlayıp sonra uygulamak yerine, üç gerçek üretim projesini (50, 180, 1200+ dosya) belgeleyerek pattern’leri çıkardım. Her bölümün gerekçesi somut bir ihtiyaçtan doğdu.
Template Yapısı
10 Temel Bölüm
Her proje, büyüklüğünden bağımsız olarak bu 10 bölümü içerir:
| # | Bölüm | Ne Anlatır |
|---|---|---|
| 1 | Stack & Dependencies | Paketler, versiyonlar, hangi katmanda ne kullanılıyor |
| 2 | Module Map | Dizin yapısı, dosya sorumlulukları |
| 3 | Data Flow | Verinin sistemde nasıl aktığı |
| 4 | Route / API Structure | Endpoint’ler, sayfalar, middleware |
| 5 | Data Model | Tablolar, sütunlar, ilişkiler |
| 6 | Configuration & Environment | Env var’lar, secret’lar, deploy config |
| 7 | Security | Validation kuralları, auth akışı, header’lar |
| 8 | Constraints & Trade-offs | Mimarinin neden bu şekilde olduğu |
| 9 | Known Tech Debt | Neyin düzeltilmesi gerektiği, öncelik sırasıyla |
| 10 | Code Hotspots | En çok değişen, en yüksek riskli dosyalar |
11 Opsiyonel Modül
Sadece projeye uyan modüller eklenir, geri kalanı silinir:
| Modül | Ne Zaman Ekle |
|---|---|
| Monorepo Structure | 2+ paket/workspace |
| Background Jobs | Inngest, BullMQ, cron, kuyruklar |
| i18n | Çok dilli içerik veya UI |
| Membership / Access Control | Tier veya role bazlı erişim |
| Webhook Processing | Dış servis webhook’ları |
| Caching Strategy | KV, Redis, CDN, Cache API |
| Search | Pagefind, Algolia, Meilisearch |
| Content Collections | CMS, MDX, Astro collections |
| Design System | Tanımlı görsel dil, token’lar |
| Infrastructure Topology | Çoklu servis deployment’ları |
| Dependency Graph | Karmaşık iç bağımlılıklar |
3 Derinlik Seviyesi
Her bölüm L1, L2 veya L3 derinlikte yazılır. Aynı projede farklı bölümler farklı derinliklerde olabilir.
| Seviye | Ne Zaman | Örnek |
|---|---|---|
| L1 | < 30 kaynak dosya | Düz tablolar, tek satır açıklamalar, tek diyagram |
| L2 | 30-200 dosya | Katman gruplandırması, akış bazlı diyagramlar, sütun detayları |
| L3 | > 200 dosya | Dosya seviyesi detay, edge case’ler, metrikler, sorgu pattern’leri |
Bölüm bazlı override’lar varsayılanı yükseltir, asla düşürmez:
| Koşul | Bölüm | Minimum |
|---|---|---|
| DB tabloları > 10 | Data Model | L2 |
| DB tabloları > 30 | Data Model | L3 |
| API endpoint’leri > 20 | Route / API Structure | L2 |
| Env var’lar > 15 | Configuration | L2 |
| Background job’lar > 5 | Background Jobs | L2 |
| Component’ler > 30 | Module Map | L2 |
Örneklerle Uygulama
Template’i üç farklı boyutta kurgusal ama gerçekçi projelerle örnekledim:
L1: Küçük Statik Site (Bella’s Kitchen)
Astro ile geliştirilmiş bir kurumsal web sitesi. ~50 kaynak dosya, Cloudflare Pages’ta host ediliyor. architecture.md ~180 satır.
Stack bölümü düz tablo:
| Package | Version | Purpose |
| ------------------- | -------- | ------------------------- |
| astro | ^5.16.11 | Framework (static output) |
| @astrojs/cloudflare | ^12.6.12 | Cloudflare Pages adapter |
| tailwindcss | ^4.1.18 | CSS framework |Module Map tek seviye dizin ağacı. Data Flow tek bir ASCII diyagram. Bu kadar yeterli.
L2: Orta Boy Membership (LearnHub)
Next.js + Stripe + Neon ile 3 tier’lı kurs platformu. ~180 dosya. architecture.md ~450 satır.
Stack bölümü katman gruplandırmalı (Runtime, Infrastructure, Dev Dependencies). Data Flow auth, ödeme ve içerik erişimi için ayrı diyagramlar. Data Model sütun detayları ve foreign key’lerle.
L3: Büyük Monorepo (Bazaar)
pnpm monorepo, NestJS + Kafka + BullMQ + AWS. ~1200 dosya. architecture.md ~500 satır (yoğunlaştırılmış).
Monorepo Structure, Background Jobs, Infrastructure Topology opsiyonel modülleri aktif. Dosya seviyesi sorumluluklar, edge case’ler, metrikler.
Güncel Tutma Stratejileri
architecture.md ancak güncelliğini korursa değerli. Üç strateji:
1. Değişiklik Anında Güncelleme
Yeni bir dependency, route veya tablo eklediğinizde ilgili bölümü güncelleyin. 2 dakika sürüyor. En basit ve en etkili yöntem.
2. PR Check (GitHub Action)
Değişen dosyaları glob pattern’lerle architecture.md bölümlerine eşleştiren bir GitHub Action. PR’a bilgilendirme yorumu bırakıyor:
## architecture.md Staleness Check
The following sections may be outdated based on changed files:
- **Stack & Dependencies** - package.json modified
- **Route / API Structure** - 2 files added in src/pages/
Run `/architecture --section "Stack & Dependencies"` to update.Blocker değil, advisory. Geliştirici karar veriyor. ADR oluştururken paralelde ele alınabilir.
3. Daily Review Entegrasyonu
daily-code-review gibi araçlar architecture.md’yi review context’i olarak kullanabiliyor. Review bulguları Tech Debt ve Hotspots bölümlerine geri besleniyor. Geri bildirim döngüsü.
Context Engineering Ekosistemindeki Yeri
Living Architecture, tek başına çalışan bir araç olmaktan çok daha geniş bir ekosistemin temel taşı. Context engineering ekosistemi yazısında anlattığım dört katmanlı yapıda architecture.md birinci katmanın yarısını oluşturuyor:
Katman 1: Statik referanslar → CLAUDE.md + architecture.md
Katman 2: JIT arama → mcp-code-search + dnomia-knowledge
Katman 3: Karar yönetişimi → /court + ADR'ler
Katman 4: Öğrenme döngüsü → forge retroCLAUDE.md agent’a “nasıl çalış” diyor. architecture.md “neyle çalışıyorsun” diyor. İkisi birlikte agent’ın ilk saniyeden itibaren doğru bağlamla başlamasını sağlıyor.
İlişkili Araçlar
| Proje | İlişki |
|---|---|
| decision-gate | /court kararları ADR olarak kaydedilir, architecture.md Constraints bölümünü besler |
| daily-code-review | architecture.md’yi review context’i olarak kullanır, bulgular Tech Debt’e döner |
| forge | Retro adımı architecture.md’yi günceller |
| mcp-code-search | architecture.md’deki jump-to pointer’larla tamamlayıcı |
İlişkili Yazılar
- AI Destekli Codebase Audit: architecture.md ve domain dictionary’nin 6 track’li audit sürecinde nasıl kullanıldığı
- Context Engineering Ekosistemi: Dört katmanlı ekosistemin tam anlatımı
Kendi Projelerimde Uygulama
Template’i formalize etmeden önce kendi projelerimde architecture.md yazıyordum. 992 dosyalık ana projem için ~3.600 satırlık bir architecture.md var. Bu dosyadan önce agent’ın altyapı sorularına cevap bulması deneme-yanılma süreciydi. Dosyadan sonra agent doğrudan ilgili bölümü okuyor.
“Neden Neon’a geçtik?” sorusuna eskiden 155 ADR’yi taramak gerekiyordu. Şimdi architecture.md’deki Mimari Kararlar bölümünde ADR-127 referansıyla özet var. Agent özetten başlıyor, gerekirse ADR dosyasını açıyor.
Template, bu deneyimlerin genelleştirilmiş hali. Kendi projelerime özgü detayları çıkardım, farklı boyut ve karmaşıklıktaki projelere uygulanabilir bir yapı bıraktım.
Başlarken
Derinlik seviyeleri, örnekler ve SSS için proje sayfasına bakın: lab.ceaksan.com/architecture. Template’i doğrudan indirmek için:
curl -sL https://raw.githubusercontent.com/ceaksan/living-architecture/main/TEMPLATE.md -o architecture.md- DEPTH_GUIDE.md’ye bakarak her bölümün derinliğini belirleyin
- Projenize uymayan opsiyonel modülleri silin
- Her bölümü doldurun. AI aracınız yardımcı olabilir: kod tabanını tarayıp modül haritası çıkarabilir, package.json’dan stack tablosu oluşturabilir
- AI tool config’inizde architecture.md’ye referans verin
Proje açık kaynak olarak GitHub’da yayınlandı4.
Footnotes
- “Codified Context: Infrastructure for AI Agents in a Complex Codebase” (arxiv.org/html/2602.20478v1). 108.000 satırlık bir C# projesinde test edilen üç katmanlı sistem. ↩
- AGENTS.md Standard (aihero.dev). Agentic AI Foundation tarafından standartlaştırılan, 2.500+ agent config dosyasının analizine dayanan içerik alanları. ↩
- “Lost in the Middle: How Language Models Use Long Contexts” (Liu et al., 2023). Context window doluluk oranı arttıkça model performansının düştüğünü belgeleyen çalışma. ↩
- Living Architecture GitHub deposu ↩
- 01 architecture.md, projenin gerçek yapısını anlatır: modül haritası, veri akışı, kısıtlamalar, teknik borç. CLAUDE.md veya AGENTS.md'nin işi bu değil.
- 02 Derinlik seviyesi proje boyutuna göre bölüm bazlı belirlenir. 50 dosyalık bir site için L1, 1200 dosyalık monorepo için L3.
- 03 11 opsiyonel modül (monorepo, background jobs, i18n, membership, webhook, cache, search, content collections, design system, infra topology, dependency graph) sadece gerektiğinde eklenir.
- 04 Template, gerçek üretim projelerinden türetildi. Üç farklı boyutta (50, 180, 1200 dosya) uygulandı ve doğrulandı.
+ Living Architecture nedir?
AI coding agent'lar için proje agnostik bir architecture.md template'i. 10 temel bölüm (stack, modül haritası, veri akışı, API yapısı, veri modeli, konfigürasyon, güvenlik, kısıtlamalar, teknik borç, kod hotspot'ları) ve 11 opsiyonel modül içerir. Proje büyüklüğüne göre L1, L2 veya L3 derinlikte yazılır.
+ CLAUDE.md veya AGENTS.md varken neden architecture.md gerekli?
CLAUDE.md agent'a talimat verir: 'barrel import kullanma', 'testleri böyle çalıştır'. architecture.md projenin gerçekliğini anlatır: hangi modül nerede, veri nasıl akıyor, hangi kararlar neden alındı. Biri 'nasıl çalış', diğeri 'neyle çalışıyorsun'. İkisi farklı amaçlara hizmet eder ve birbirinin yerine geçemez.
+ Derinlik seviyelerini nasıl belirliyorum?
Kaynak dosya sayısına göre varsayılan belirlenir: 30'dan az L1, 30-200 arası L2, 200'den fazla L3. Bölüm bazlı override'lar var: 10'dan fazla veritabanı tablosu varsa Data Model en az L2, 20'den fazla API endpoint varsa Route yapısı en az L2. Override'lar sadece yukarı yönlü çalışır, asla düşürmez.
+ architecture.md güncelliğini nasıl koruyacağım?
Üç strateji: (1) Değişiklik anında, yeni bir dependency, route veya tablo eklediğinizde ilgili bölümü güncelleyin (2 dakika). (2) PR check ile değişen dosyaları architecture.md bölümlerine eşleştiren GitHub Action (advisory, blocker değil). (3) daily-code-review gibi araçlarla architecture.md'yi review context'i olarak kullanarak geri bildirim döngüsü.
+ Template'i nasıl kullanmaya başlıyorum?
curl ile TEMPLATE.md'yi projenize indirin, DEPTH_GUIDE.md'ye bakarak her bölümün derinliğini belirleyin, doldurun. AI tool config'inizde (CLAUDE.md, .cursorrules) architecture.md'ye referans verin. Projenize uymayan opsiyonel modülleri silin.