AI Coding Agent'lar İçin Yaşayan Mimari Dokümantasyon: Araştırma, Yaklaşımlar ve Araçlar

Bağlam

AI coding agent’lar (Claude Code, Gemini CLI, Cursor, GitHub Copilot) büyük projelerde kodu yüzeysel tarayarak yanlış çıkarımlarda bulunuyor. İki farklı modüldeki benzer isimli fonksiyonları karıştırıyor, kullanılmayan eski kodu aktif sanıyor, altyapı detaylarını tahmin ediyor.

2025-2026 araştırmaları gösteriyor ki modeller yapılandırılmış, kalıcı referans noktaları ile beslendiğinde repo taramasına kıyasla belirgin şekilde daha iyi performans gösteriyor¹. Bu durum “context engineering” disiplinini doğurdu: agent’ın context window’undaki sinyal/gürültü oranını maksimize etme.

Bu yazıda, GPT-4o, Kimi K2.5 ve Gemini Deep Research ile yürüttüğüm paralel araştırmalardan, akademik makalelerden ve endüstri pratiklerinden derlenen 11 farklı yaklaşımı inceliyorum. Bu araştırma, Living Architecture template’inin temelini oluşturdu.

1. Codified Context: Dokümantasyon Altyapıdır

108.000 satırlık bir C# projesinde test edilen üç katmanlı sistem¹, araştırmada denk geldiğim en somut bulgulardan biriydi:

Katman	İçerik	Agent Davranışı
Hot Memory	Convention’lar, retrieval hook’ları, orkestrasyon protokolleri	Her oturumda otomatik yükler
Domain Expert Agent’lar	Proje bazlı uzman agent’lar (veritabanı, frontend, API)	İlgili alan sorulduğunda aktif
Cold Memory	34 on-demand spesifikasyon dokümanı	Sadece ilgili doküman çekilir

Pratikte Hot Memory karşılığı CLAUDE.md veya AGENTS.md dosyası. Cold Memory karşılığı architecture.md, ADR’ler, spec dokümanları. Agent sadece ilgili olanı çekiyor, tüm dokümanları context’e yüklemiyor.

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 “load-bearing artifact”¹.

2. AGENTS.md Ekosistemi

Agentic AI Foundation tarafından 2024-2025’te standartlaştırılan AGENTS.md², “makineler için README” görevi görüyor. Farklı AI araçları için farklı dosyalar mevcut, ama hepsi tamamlayıcı:

Dosya	Araç	Özellik	Strateji
AGENTS.md	Evrensel	Multi-tool uyumluluk	Root-level global kurallar
CLAUDE.md	Claude Code	@imports, recursive referencing	Hiyerarşik, progressive disclosure
.cursorrules	Cursor	YAML frontmatter	Path-specific kural aktivasyonu
.github/copilot-instructions.md	GitHub Copilot	VS Code entegrasyonu	Proje bazlı özelleştirme3
SPEC.md	Genel SDD	Yaşayan kontrat	”Ne” ve “neden” tanımlar
runtime.md	Otonom agent’lar	Checkpoint takibi	Canlı ilerleme ve risk loglama

“Nearest-Wins” modeli: Monorepo’da root’taki AGENTS.md global standartları verir (commit formatı, güvenlik kapıları), alt dizinlerdeki AGENTS.md dosyaları yerel stack rehberliğini sağlar. Claude Code’un CLAUDE.md hiyerarşisi de aynı modeli izliyor.

CodeAI.md⁴ benzer bir yaklaşım sunuyor: repo root’una tek bir dosya koyarak mimari, isimlendirme kuralları, entegrasyon pattern’leri ve anti-pattern’leri tanımlıyor. “Her prompt’ta mimarinizi yeniden açıklamayı durdurun” sloganıyla.

3. Altı Temel İçerik Alanı

2.500’den fazla başarılı agent config dosyasının analizinden çıkarılan altı zorunlu alan²:

1. Komutlar: Tam çalıştırılabilir string’ler (install, build, test, lint). Dosyanın başına yaz, agent’ın ilk erişeceği bilgi bu
2. Test: Framework, coverage beklentileri, mocking pattern’leri
3. Proje Yapısı: Üst seviye dizin ağacı haritası
4. Kod Stili: Açıklama değil, “Göster, Anlat” kod snippet’leri
5. Git Workflow: Branch isimlendirme, commit formatı, PR checklist
6. Sınırlar: Do/Don’t listeleri, operasyonel limitler

Bu altı alan CLAUDE.md veya AGENTS.md’nin kapsamı. Projenin mimari yapısı, modüller arası ilişkiler, veri akışı, altyapı topolojisi, teknik borç gibi bilgiler bu alanlara sığmıyor. Mimari bilgi ayrı bir dosyada (architecture.md) yaşamalı.

4. C4 Model + AI Uyumu

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 (Git diff’te görünür)
• Token-verimli (görsel yerine text)
• Agent tarafından okunabilir ve düzenlenebilir
• GitHub, GitLab ve VS Code’da native render edilir

C4 Seviye	Agent Bilgisi	Kullanım
Context (C1)	Dış sistemler, aktörler, global bağımlılıklar	Projenin dünya ile ilişkisi
Container (C2)	DB’ler, mikroservisler, frontend’ler, kuyruklar	Servis topolojisi
Component (C3)	Modül sınırları, servis katmanları	İç yapı
Dynamic	Karmaşık iş mantığı için sequence flow’ları	Akış detayı

C4X aracı AI_Agent, Memory, Tool node’larını Mermaid syntax’ında destekliyor⁶. Agent kendi rolünü mimaride “görebiliyor”.

Akademik alanda da ilerleme var: Szczepanik ve Chudziak’ın çalışması⁷ multi-agent LLM sistemleriyle C4 diyagramlarının otomatik üretimini araştırıyor. Yapısal doğrulama ve semantik değerlendirme yöntemlerini birleştirerek mimari diyagramların kalitesini ölçüyor.

5. Otomatik Context Sıkıştırma (Repomix + Tree-sitter)

Repomix⁸ kod tabanını AI uyumlu tek bir dosyaya paketliyor. Tree-sitter ile sadece temel kod imzalarını ve yapılarını çıkartıyor:

Sıkıştırma Seviyesi	Korunan Bilgi	Token Tasarrufu
Ham paketleme	Dosya içerikleri tamamı	%0
İmza çıkartma	Sınıf/fonksiyon adları, tipler	%60-70
Yapısal harita	Dizin ağacı, dosya amaçları	%90+

992 dosyalık gerçek bir projede test ettiğim sonuçlar:

Mod	Dosya Sayısı	Token	Değerlendirme
Full (tüm repo)	992	1.9M	Context window’un 10 katı
Compressed (tüm repo)	992	1.25M	Hala kullanılamaz
Compressed (sadece TS/TSX)	489	90K	Teorik olarak sığar ama context’in yarısı

Repomix’in dizin ağacı ve git-change-count sıralaması hotspot analizi için yararlı. Ancak Claude Code, Gemini CLI veya Cursor gibi dosya okuyabilen araçlarda yapılandırılmış architecture.md + JIT semantik arama, Repomix’in flat dump’ından daha hedefli bilgi veriyor.

Repomix’in asıl değeri dosya okuyamayan araçlarda (ChatGPT web arayüzü, web Claude): tek bir dosya olarak tüm repo bağlamını verebilmek.

6. Hybrid Yaklaşım: Konsensüs

Tüm araştırma kaynakları (GPT-4o analizi, Kimi K2.5 araştırması, Gemini Deep Research, akademik makaleler) 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, “neden”	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.

Bu konsensüsün pratik uygulaması: architecture.md’de Stack & Dependencies, Module Map gibi bölümler kısmen otomatik üretilebilir (package.json’dan, dizin taramasından). Constraints & Trade-offs, Known Tech Debt gibi bölümler insan yazmalı. Staleness detection ise PR check veya daily review entegrasyonu ile sağlanabilir.

7. ADR’ler: Pasif Log’dan Aktif Yönetişime

Architecture Decision Records⁹ artık sadece geçmiş kararların kaydı değil, agent’lar için çalıştırılabilir kısıtlamalar:

• Mimari sınırlar: Hangi modül hangisine bağımlı olabilir, hangi servis hangi veritabanına erişir
• Veri işleme kısıtlamaları: PII loglama gereksinimleri, şifreleme standartları
• Hata yayılım pattern’leri: Agent’ın yaratıcı ama sessiz hata modları üretmesini önler
• Reddedilen alternatifler: “Bu yaklaşımı daha önce değerlendirdik ve şu nedenle reddettik”

“Kernel of Truth” Workflow: Geliştirici 1 cümle yazıyor (“Rate limiting için Redis kullan, dağıtık spike’ları karşılamak için”), agent bunu yapılandırılmış ADR’ye genişletiyor. Solo geliştirici için minimal yazma yükü, kalıcı karar kaydı.

Başlık: Redis yerine Inngest kullan
Durum: Kabul edildi
Bağlam: Background job'lar için kuyruk sistemi gerekli
Karar: Inngest, serverless ortamda Redis'e göre daha az operasyonel yük
Sonuçlar: Vendor lock-in riski var ama yönetim maliyeti düşüşü bunu karşılar

ADR’leri agent bağlamında daha derinlemesine ele aldığım ADR ve OpenSpec yazısı ve yapılandırılmış değerlendirme için Decision Gate yazısı ilgili konuları detaylıca inceliyor.

8. Spec-Driven Development (SDD)

Addy Osmani’nin de vurguladığı gibi¹⁰: “Bir planla başlarsınız. Herhangi bir şey prompt’lamadan önce bir tasarım dokümanı veya spec yazarsınız.” Dokümantasyonu iş bittikten sonra değil, her görevin başlangıç noktası olarak ele almak:

1. Specify: Hedefleri tanımla, agent SPEC.md üretir (kullanıcı yolculukları, başarı metrikleri)
2. Plan: Kısıtlamaları belirle, agent teknik plan üretir (birden fazla varyant)
3. Tasks: Agent planı küçük, incelenebilir parçalara böler
4. Implement: Agent parçaları tek tek çözer, geliştirici odaklı review yapar

SDD, “agentic engineering”¹¹ ile “vibe coding” arasındaki temel ayrım. Agent’a ne istediğinizi yapılandırılmış olarak söylerseniz, çıktı kalitesi belirgin şekilde artıyor.

9. Progressive Disclosure ve JIT Indexing

200K, hatta 1M token context window bile fazla bilgiyle doldurulduğunda performans düşüyor¹². Çö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
Örnekleme kuralları	Önce entry point’leri oku	İnsan gibi “zihinsel haritalama”

VS Code’un Copilot customization’ı³ da aynı prensiple çalışıyor: .github/copilot-instructions.md dosyası proje bazlı özelleştirme, .instructions.md dosyaları path-specific kurallar. Tüm bilgiyi tek yere koymak yerine, gerektiğinde aktifleşen katmanlı bir yapı.

Claude Code’un CLAUDE.md hiyerarşisi bu modelin en gelişmiş örneği: root-level global kurallar, dizin bazlı override’lar, @imports ile ihtiyaç anında başka dosyaları çekme.

10. Google Code Wiki

Google’ın 2025’te duyurduğu Code Wiki sistemi¹³:

• Her repo için yapılandırılmış wiki oluşturuyor
• Her commit sonrası otomatik güncelliyor
• İnteraktif, AI destekli dokümantasyon

Solo geliştirici için tam otomasyonu kurmak zor ama konsept doğru: dokümantasyon koda bağımlı olmalı. Her değişiklikte güncellenmeli, manual bakıma bırakılmamalı.

Bu vizyonun daha erişilebilir bir uygulaması: architecture.md’yi CI/CD pipeline’ına entegre etmek. PR check’leri ile değişen dosyaları architecture.md bölümlerine eşleştirmek. Google Code Wiki’nin tam otomasyonunu sağlayamasa da, staleness detection ile aynı geri bildirim döngüsünü kurmak mümkün.

11. LLM’ler İçin Markdown Optimizasyonu

Agent’a verilen dokümanların formatı da performansı etkiliyor. LLM’ler için Markdown yazarken dikkat edilecekler:

Kural	Neden
Fenced code block’larda dil etiketi zorunlu	LLM tek token birimi olarak parse ediyor
Başlık seviyesi atlamak yasak (H1’den H3’e geçme)	Attention mekanizmasını bozuyor
Görseller için plain-text alternatif/özet	Multimodal olmayan modeller görseli okuyamıyor
RFC 2119 kısıtlamaları (MUST, SHOULD, MAY)	Kesinlik seviyesini netleştiriyor
Eyleme dönük fiiller: “sor”, “ara”, “kontrol et”	Agent’ın çalıştırılabilir talimat olarak yorumlamasını kolaylaştırıyor

Bu kurallar CLAUDE.md, AGENTS.md veya architecture.md yazarken de geçerli. Yapılandırılmış, tutarlı format agent’ın bilgiyi parse etme ve kullanma kalitesini artırıyor.

Yaklaşımların Karşılaştırması

Yaklaşım	Güçlü Yön	Zayıf Yön	Ne Zaman Kullan
Codified Context	Akademik temelli, üç katmanlı model	Büyük projelere özgü	Kurumsal/büyük projeler
AGENTS.md/CLAUDE.md	Araç entegrasyonu, hiyerarşik	Mimari bilgi kapsamı dışında	Her projede, kurallar için
C4 + Mermaid.js	Görsel, hiyerarşik, VCS uyumlu	Bakım yükü	Karmaşık mimariler
Repomix	Tek komut, tam repo	Token patlaması	Dosya okuyamayan araçlar
ADR’ler	Karar kaydı, agent kısıtlaması	Birikir, bakım gerekir	Her büyük karar
SDD	Baştan yapılandırılmış	Küçük görevler için ağır	Yeni özellik/mimari değişiklik
Google Code Wiki	Tam otomasyon	Henüz dışarıya açık değil	(Gelecek potansiyel)
Progressive Disclosure	Token verimli, ölçeklenebilir	Kurulum karmaşıklığı	Büyük projeler, monorepo
architecture.md	Tek dosya, yapılandırılmış, ölçeklenebilir	İlk yazma eforu	Her projede

Uygulama: Living Architecture

Bu araştırma bulgularını proje agnostik bir template’e dönüştürdüm: Living Architecture.

Template, yukarıdaki yaklaşımların pratik sentezi:

• Codified Context’ten: Katmanlı bellek modeli (Hot Memory = CLAUDE.md, Cold Memory = architecture.md)
• AGENTS.md ekosisteminden: Yapılandırılmış format, başlık hiyerarşisi
• C4 Model’den: Hiyerarşik bölümleme (Stack → Module Map → Data Flow)
• Hybrid yaklaşımdan: Auto-generate edilebilir bölümler + human-write bölümler
• Progressive disclosure’dan: Bölüm bazlı derinlik (L1/L2/L3), agent ihtiyacı olan bölüme atlıyor
• ADR’lerden: Constraints & Trade-offs bölümü, karar referansları

10 temel bölüm, 11 opsiyonel modül, 3 derinlik seviyesi. Küçük statik siteden büyük monorepo’ya kadar ölçekleniyor. Açık kaynak olarak GitHub’da mevcut¹⁴.

Kaynaklar

Açık Kaynak Araçlar

• Living Architecture: Proje agnostik architecture.md template’i¹⁴
• mcp-code-search: Semantik kod arama MCP sunucusu
• decision-gate: Multi-AI değerlendirme framework’ü
• forge: Memory-backed karar-teslim pipeline’ı

İlişkili Yazılar

• Living Architecture: AI Coding Agent’lar İçin Yapılandırılmış Mimari Dokümantasyon
• Context Engineering Ekosistemi
• ADR ve OpenSpec: AI Çağında Karar Yönetimi
• Decision Gate: Multi-AI Tribunal
• Claude Code Context Yönetimi

Footnotes

1. Vasilopoulos, A. “Codified Context: Infrastructure for AI Agents in a Complex Codebase” (2026). 108.000 satırlık bir C# projesinde üç katmanlı dokümantasyon sistemini test eden çalışma. arxiv.org/abs/2602.20478 ↩ ↩² ↩³
2. “A Complete Guide to AGENTS.md” (aihero.dev). Agentic AI Foundation tarafından standartlaştırılan, 2.500+ agent config dosyasının analizine dayanan içerik alanları ve best practice’ler. aihero.dev/a-complete-guide-to-agents-md ↩ ↩²
3. VS Code Copilot Customization. Proje bazlı AI özelleştirmesi için instruction dosyaları ve context engineering rehberi. code.visualstudio.com/docs/copilot/copilot-customization ↩ ↩²
4. CodeAI.md. Repo root’una tek bir dosya koyarak mimari, isimlendirme kuralları ve entegrasyon pattern’lerini tanımlayan dokümantasyon framework’ü. codeai.md ↩
5. Brown, S. “The C4 Model for Visualising Software Architecture”. Dört hiyerarşik soyutlama seviyesi (software systems, containers, components, code) ile yazılım mimarisi görselleştirmesi. c4model.com ↩
6. Szczepanik, K. & Chudziak, J.A. “Collaborative LLM Agents for C4 Software Architecture Design Automation” (2025). Multi-agent LLM sistemleriyle C4 diyagramlarının otomatik üretimini araştıran çalışma. HICSS-59’da kabul edildi. arxiv.org/abs/2510.22787 ↩
7. Szczepanik & Chudziak’ın çalışması⁶ aynı zamanda C4X aracını referans veriyor. C4X, AI_Agent, Memory, Tool node’larını Mermaid syntax’ında destekliyor. ↩
8. Repomix. Kod tabanını AI uyumlu tek bir dosyaya paketleyen, Tree-sitter ile fonksiyon imzalarını çıkaran araç. 22.6k GitHub star. github.com/yamadashy/repomix ↩
9. Henderson, J.P. “Architecture Decision Record”. ADR template’leri, pratik örnekler ve takım uygulaması rehberi. github.com/joelparkerhenderson/architecture-decision-record ↩
10. Osmani, A. “How to write a good spec for AI agents” (2026). Agent’lar için yapılandırılmış spec yazmanın temel prensipleri. addyosmani.com/blog/good-spec ↩
11. Osmani, A. “Agentic Engineering” (2026). “Vibe coding” ile disiplinli AI destekli geliştirme arasındaki ayrımı tanımlayan yazı. addyosmani.com/blog/agentic-engineering ↩
12. Liu, N. F. et al. “Lost in the Middle: How Language Models Use Long Contexts” (2023). Context window doluluk oranı arttıkça model performansının düştüğünü belgeleyen çalışma. ↩
13. Krzaczyński, R. “Google Launches Code Wiki, an AI-Driven System for Continuous, Interactive Code Documentation” (InfoQ, 2025). Google’ın her repo için yapılandırılmış wiki oluşturan ve her commit sonrası otomatik güncelleyen sistemi. infoq.com/news/2025/11/google-code-wiki ↩
14. Living Architecture GitHub deposu. Proje agnostik architecture.md template’i: 10 temel bölüm, 11 opsiyonel modül, 3 derinlik seviyesi. github.com/ceaksan/living-architecture ↩ ↩²

Önemli Noktalar

• 01 Codified Context yaklaşımı dokümantasyonu altyapı olarak tanımlıyor: kod gibi sürekli bakım gerektiren, agent'ın doğru çıktı üretmesi için zorunlu olan bir yapı.
• 02 AGENTS.md, CLAUDE.md, .cursorrules farklı araçlara hitap ediyor ama hepsi aynı problemi çözüyor. 'Nearest-Wins' modeli monorepo'larda global ve yerel kuralları katmanlıyor.
• 03 Repomix 992 dosyalık bir repoyu 1.9M token'a paketliyor. Dosya okuyabilen agent'lar için yapılandırılmış architecture.md + JIT arama daha verimli.
• 04 Tüm araştırma kaynakları aynı konsensüse ulaşıyor: 'what' (schema, tipler, dependency graph) otomatik üretilir, 'why' (tasarım kararları, kısıtlamalar) insan yazar.

Sık Sorulan Sorular (FAQ)

+ Context engineering nedir?

AI agent'ın context window'undaki sinyal/gürültü oranını maksimize etme disiplini. Agent'a doğru bilgiyi, doğru zamanda, doğru formatta vermek. Prompt engineering'in ötesinde, sistematik bir altyapı yaklaşımı.

+ AGENTS.md ile CLAUDE.md arasındaki fark nedir?

AGENTS.md, Agentic AI Foundation tarafından standartlaştırılmış, araç bağımsız bir format. CLAUDE.md ise Claude Code'a özgü, @imports ve recursive referencing gibi gelişmiş özellikleri destekliyor. Aynı projede ikisi bir arada kullanılabiliyor: AGENTS.md global kurallar, CLAUDE.md Claude'a özel talimatlar için.

+ Repomix ne zaman kullanışlı, ne zaman gereksiz?

Repomix, dosya okuyamayan araçlara (ChatGPT web, web Claude) repo bağlamı vermek için yararlı. Claude Code veya Cursor gibi dosya okuyabilen araçlarda yapılandırılmış architecture.md + JIT semantik arama daha verimli. Repomix'in dizin ağacı ve hotspot analizi her durumda faydalı.

+ ADR'ler agent'lar için neden önemli?

ADR'ler artık sadece pasif karar kaydı değil, agent'lar için çalıştırılabilir kısıtlamalar. Mimari sınırlar, veri işleme kuralları ve reddedilen alternatifler agent'ın aynı tartışmayı tekrarlamamasını sağlıyor. 'Kernel of Truth' workflow'u ile yazma yükü minimal.

+ Bu araştırmadan pratik bir çıktı var mı?

Evet. Bu araştırma bulgularını proje agnostik bir template'e dönüştürdüm: Living Architecture. 10 temel bölüm, 11 opsiyonel modül, 3 derinlik seviyesi. Açık kaynak olarak GitHub'da mevcut.