Bir AI coding agentın büyük bir kod tabanını “anlaması”, bütün repository’yi tek seferde modele yüklemesi anlamına gelmez. Gerçek projelerde binlerce dosya, yıllara yayılan commit geçmişi, dokümantasyon, testler, generated code, bağımlılıklar ve farklı ekiplerin geliştirdiği modüller bulunabilir. Modelin context window’u çok büyük olsa bile bütün bu bilgiyi aynı anda vermek çoğu zaman ne ekonomik ne de güvenilir bir yaklaşımdır.
15 Temmuz 2026 itibarıyla güncel coding agent sistemlerinin ortak yaklaşımı, büyük kod tabanını tek bir dev prompt olarak ele almak yerine keşfetmek, haritalamak, ilgili parçaları seçmek, dışarıda tutulan bilgiyi gerektiğinde yeniden bulmak ve görev ilerledikçe context’i yönetmek üzerine kuruludur. OpenAI, agent-first bir mühendislik projesinde context management’ı büyük ve karmaşık görevlerin en önemli zorluklarından biri olarak tanımlıyor ve agente “bin sayfalık talimat kitabı” yerine bir harita verilmesini öneriyor OpenAI – Harness Engineering. Bu yazı, büyük repository’lerde bu yaklaşımın nasıl çalıştığını açıklar.
AI agent büyük kod tabanını gerçekten nasıl “anlar”?
Bir insan geliştirici de büyük bir repository’ye ilk kez girdiğinde bütün dosyaları sırayla okumaz. Önce klasör yapısına bakar, giriş noktalarını bulur, ilgili modülü keşfeder, veri akışını takip eder ve görev için gereken dosyalara odaklanır. Coding agentın etkili çalışması da benzer bir keşif stratejisine ihtiyaç duyar.
OpenAI’ın “Understand large codebases” rehberi, unfamiliar bir kod tabanında önce mimari haritanın çıkarılmasını, önemli modüllerin ve veri akışının anlaşılmasını ve düzenleme yapmadan önce okunması gereken sonraki dosyaların belirlenmesini önerir OpenAI Codex – Understand Large Codebases. Buradaki temel fikir, doğrudan kod değiştirmeye geçmek yerine önce görev için gerekli zihinsel modeli oluşturmaktır.
Bir agentın “anlaması” bu nedenle tek bir iç temsil değildir. Genellikle şu mekanizmaların birleşimidir:
- Repository yapısını ve dosya ağacını keşfetme.
- İsim, sembol, referans veya semantik arama ile ilgili kodu bulma.
- Seçilen dosya ve kod parçalarını aktif context’e alma.
- Proje talimatları ve mimari dokümantasyonu kullanma.
- Çalıştırılan komutlar, testler ve loglardan gerçek geri bildirim alma.
- Uzun görevlerde ara sonuçları dosya, not veya başka dış durumlarda saklama.
Context window neden bütün repository anlamına gelmez?
Context window, modelin belirli bir anda işleyebildiği toplam bilgi alanıdır. Kullanıcı talimatı, sistem talimatları, proje kuralları, okunan dosyalar, tool sonuçları, önceki mesajlar ve modelin çalışma çıktıları aynı bütçeyi paylaşabilir. Bu alan büyük olsa bile sınırsız değildir.
Anthropic’in context window dokümantasyonu, daha büyük context’in daha uzun ve karmaşık girdileri işleyebildiğini ancak “daha fazla context her zaman daha iyi” olmadığını açıkça belirtir Anthropic – Context Windows. İlgisiz dosyaların ve eski konuşma ayrıntılarının context’e yığılması, modelin önemli sinyalleri ayırt etmesini zorlaştırabilir.
Bu nedenle büyük repository’lerde amaç context’i maksimum doldurmak değil, yüksek sinyal yoğunluğu oluşturmaktır. Görev authentication modülündeyse alakasız raporlama kodunun binlerce satırını aktif context’e taşımak yarar sağlamayabilir. Buna karşılık authentication akışının giriş noktası, veri modeli, middleware, ilgili testler ve API sözleşmeleri kritik olabilir.
İlk adım: Repository haritası çıkarmak
Agent büyük bir kod tabanına doğrudan “bu özelliği ekle” komutuyla girdiğinde, yanlış klasörde çözüm üretme veya mevcut mimariyi tekrar etme riski artabilir. İlk aşamada repository haritası oluşturmak daha güvenilir bir başlangıçtır.
Bu harita ayrıntılı bir ansiklopedi olmak zorunda değildir. Amaç şu sorulara cevap vermektir:
- Ana uygulama veya servisler nerede?
- Giriş noktaları hangileri?
- Domain, veri erişimi ve dış servis katmanları nasıl ayrılmış?
- Testler ve fixture’lar nerede?
- Generated veya vendor kodu hangi alanlarda?
- Görev hangi modüller ve veri akışlarıyla ilişkili?
OpenAI’ın kendi Codex kullanım rehberi de codebase onboarding sırasında modülleri, data flow’u ve okunması gereken sonraki dosyaları haritalamayı önerir OpenAI Codex – Understand Large Codebases. Bu yaklaşım özellikle büyük yazılım geliştirme projelerinde yanlış kapsamla işe başlamayı azaltabilir.
İkinci adım: İlgili bağlamı arama ile seçmek
Büyük repository’lerde context management’ın merkezinde retrieval bulunur. Agent bütün kodu okumak yerine görev için ilgili dosya, sembol ve kod parçalarını bulmalıdır. Bu süreç klasik metin araması, sembol araması, referans takibi, semantic search veya ürünün kendi codebase indexing mekanizmasıyla yapılabilir.
Cursor’ın resmî codebase indexing dokümantasyonu, kod tabanının AI context’i için aranabilir hale getirilmesini açıklar Cursor – Codebase Indexing. Bu, bütün indekslenmiş kodun her istekte modele gönderildiği anlamına gelmez; indeksin amacı ilgili parçaları bulmaya yardımcı olmaktır.
Retrieval kalitesi için dosya adları ve kod yapısı da önemlidir. Anlamlı modül isimleri, tutarlı klasör yapısı ve açık sembol adları yalnız insan geliştiricilere değil agent aramasına da yardımcı olur. Kötü adlandırılmış ve birbirine dolanmış kod tabanı, büyük context window ile otomatik olarak anlaşılır hale gelmez.
Context’e hangi bilgiler alınmalı?
Göreve göre değişmekle birlikte aktif context içinde en yüksek değeri taşıyan bilgi türleri genellikle şunlardır:
- Görev ve kabul kriterleri: Ne yapılacağı ve neyin başarı sayılacağı.
- İlgili proje kuralları: Test, mimari ve güvenlik sınırları.
- Değişecek kodun yakın çevresi: Fonksiyon, sınıf, modül ve doğrudan bağımlılıklar.
- Davranışı tanımlayan testler: Mevcut beklentilerin en somut kaynaklarından biri.
- Veri ve API sözleşmeleri: Şema, tipler ve entegrasyon sınırları.
- Gerçek tool geri bildirimi: Test çıktısı, hata logu, diff ve build sonucu.
Bu sıralama evrensel bir kural değildir; görev türüne göre değişir. Ancak temel ilke aynıdır: context’e bilgi eklemek, yalnız kapasite kullanmak değil modelin karar ortamını değiştirmektir. Her parça “bu görevde bir karar vermeye gerçekten yardım ediyor mu?” sorusuyla değerlendirilmelidir.
AGENTS.md ve repository dokümantasyonu context yönetiminde ne işe yarar?
AGENTS.md gibi proje talimat dosyaları, agentın her görevde aynı bilgiyi yeniden keşfetmesini azaltabilir. Ancak tek bir dev talimat dosyasına bütün kurumsal bilgiyi yığmak iyi bir çözüm değildir. OpenAI’ın 2026 harness engineering yazısı, büyük bir AGENTS.md yaklaşımının tahmin edilebilir biçimde başarısız olduğunu ve agente bir “harita” vermenin daha etkili olduğunu anlatır OpenAI – Harness Engineering.
Bu yaklaşımda kök talimat dosyası önemli giriş noktalarını ve dokümantasyon haritasını gösterir; ayrıntılı bilgi ise repository içinde ilgili dokümanlarda tutulur. Agent gerektiğinde doğru belgeye gider. Böylece bütün mimari açıklama her görevde aktif context’i doldurmaz.
Bir özel yazılım projesinde iyi repository bilgisi şu katmanlarda tutulabilir:
- Kısa ve kalıcı agent talimatları.
- Mimari karar ve sistem sınırı dokümanları.
- Modüle yakın README veya teknik açıklamalar.
- Çalışan testler ve tip tanımları.
- Kod ile birlikte versiyonlanan operasyonel runbook’lar.
Buradaki kritik nokta, repository’nin yalnız kod deposu değil agentın yeniden başvurabileceği sistem kaydı haline gelmesidir.
Context taşması olduğunda ne yapılır?
Uzun görevlerde konuşma geçmişi, okunan dosyalar ve tool sonuçları birikerek context bütçesini tüketebilir. Bu durumda eski bütün ayrıntıları aynı biçimde taşımak yerine önemli durumun sıkıştırılması veya dışarıya yazılması gerekir.
OpenAI’ın Codex prompting rehberi, context büyüdüğünde /compact kullanılarak yeni ve sıkıştırılmış bir context oluşturulabildiğini açıklar OpenAI Codex Prompting Guide. Anthropic’in büyük kod tabanı workflow önerileri ise geniş keşif işlerini subagentlara devrederek ana context’e yalnız bulguların dönmesini önerir Claude Code – Common Workflows.
Genel olarak dört yöntem kullanılabilir:
- Compaction: Uzun konuşmayı kritik karar ve durum özetine dönüştürmek.
- Externalized state: Plan, bulgu veya ilerlemeyi repository içindeki dosyalarda tutmak.
- Subagent delegation: Geniş keşfi ayrı context’te yaptırıp yalnız sonucu ana agente taşımak.
- Yeni görev oturumu: Bağımsız bir iş aşamasına temiz context ile başlamak.
Externalized state neden önemli?
Uzun görevlerde yalnız modelin kısa süreli context’ine güvenmek kırılgan olabilir. Planın, yapılan araştırmanın veya tamamlanan adımların repository dışında kaybolmaması gerekir. OpenAI’ın uzun süreli Codex görevleri rehberi; repository, dosyalar, dokümanlar, worktree’ler ve çıktılar gibi dış durumların uzun görevlerde tutarlılığı desteklediğini vurgular OpenAI – Run Long Horizon Tasks with Codex.
Örneğin bir refactor görevinin hangi modülleri etkilediği, hangi varsayımların doğrulandığı ve hangi testlerin hâlâ başarısız olduğu yalnız sohbet geçmişinde tutulursa context sıkıştırıldığında ayrıntı kaybolabilir. Bu bilgiler uygun bir görev dosyası veya plan çıktısında saklandığında agent gerektiğinde tekrar okuyabilir.
Bu durum insan ekiplerindeki issue, ADR, runbook ve task listelerine benzer. Uzun süreli çalışma için hafızayı yalnız çalışan kişinin zihninde tutmamak nasıl önemliyse agent sistemlerinde de kalıcı durum önemlidir.
Subagent kullanmak context sorununu nasıl azaltır?
Büyük kod tabanında araştırma yapmak çok sayıda dosya okuması gerektirebilir. Bütün bu ham dosya içerikleri ana agent context’ine taşındığında asıl implementasyon için kullanılacak alan azalabilir. Subagent yaklaşımı, belirli keşif görevlerini ayrı bir context içinde çalıştırıp yalnız bulguları geri döndürür.
Anthropic’in Claude Code common workflows dokümantasyonu, büyük kod tabanı keşfinin context’i dosya okumalarıyla doldurabileceğini ve bu araştırmanın subagenta devredilerek ana oturuma yalnız sonuçların döndürülmesini önerir Claude Code – Common Workflows.
Bu yaklaşım özellikle şu görevlerde işe yarayabilir:
- Bir özelliğin bütün çağrı zincirini araştırmak.
- Belirli bir domainin test yapısını çıkarmak.
- Eski ve yeni implementasyonları karşılaştırmak.
- Bir güvenlik veya performans riski için repository taraması yapmak.
Ancak subagent kullanımı otomatik olarak kalite artırmaz. Araştırma görevi belirsizse dönen özet kritik ayrıntıları atlayabilir. Ana agentın ihtiyaç duyduğu çıktı formatı ve sorular açık tanımlanmalıdır.
Indexleme tek başına kod tabanını anlamaya yeter mi?
Hayır. Indexleme veya semantic search ilgili kodu bulmayı kolaylaştırır; fakat bulunan parçaların doğru yorumlanması için runtime davranışı, testler ve sistem ilişkileri hâlâ önemlidir. Bir sembol semantik olarak ilgili görünebilir ancak gerçek execution path içinde hiç kullanılmıyor olabilir.
Bu nedenle retrieval sonucu genellikle doğrulanmalıdır:
- Referansları ve çağrı zincirini kontrol etmek.
- İlgili testleri okumak.
- Uygulamayı veya testleri çalıştırmak.
- Log ve hata çıktısını incelemek.
- Yapılan değişikliğin diff’ini değerlendirmek.
Agentın kod tabanını “anlaması” yalnız doküman okuması değil, çalışma sisteminden gerçek geri bildirim almasıdır.
Test ve tool sonuçları context’in en değerli parçalarından biri neden?
Model repository hakkında tahminde bulunabilir; fakat çalışan test ve komut sonuçları sistemin gerçek davranışı hakkında doğrudan sinyal verir. Bir dosyanın nasıl çalışması gerektiğiyle ilgili açıklama eski olabilir, ancak failing test veya runtime log mevcut davranışı gösterir.
OpenAI’ın uzun süreli agent görevleri rehberi de errors, diffs ve logs gibi gerçek geri bildirimlerin uzun görevlerde agentın tutarlı kalmasına yardımcı olduğunu belirtir OpenAI – Run Long Horizon Tasks with Codex.
Bu yüzden context management yalnız “hangi dosyaları modele vereceğiz?” problemi değildir. Hangi gerçek dünya sinyallerinin modele geri döneceği de aynı derecede önemlidir.
Büyük kod tabanlarında en sık yapılan context hataları
| Hata | Neden sorun olur? | Daha iyi yaklaşım |
|---|---|---|
| Bütün repository’yi context’e yüklemeye çalışmak | İlgisiz bilgi ve maliyet artar | Haritala, ara ve ilgili parçaları seç |
| Tek dev talimat dosyası kullanmak | Kritik kurallar gürültü içinde kaybolabilir | Kısa harita ve gerektiğinde okunacak ayrıntılı dokümanlar |
| Uzun keşfi ana oturumda yapmak | Dosya okumaları aktif context’i tüketebilir | Gerekirse subagent ile keşif yapıp bulguyu döndür |
| Yalnız semantik aramaya güvenmek | Gerçek execution path gözden kaçabilir | Referans, test ve runtime sonucu ile doğrula |
| Bütün ilerlemeyi sohbet geçmişinde tutmak | Compaction veya oturum değişiminde bilgi kaybı olur | Plan ve kritik durumu dışsallaştır |
| Eski context’i sürekli taşımak | Geçersiz varsayımlar yeni kararları etkileyebilir | Görev aşamalarında context’i temizle veya sıkıştır |
Context management için pratik çalışma akışı
- Görevi sınırlandırın: Beklenen sonucu ve başarı kriterlerini açık yazın.
- Repository haritası çıkarın: İlgili servis, modül ve giriş noktalarını bulun.
- İlk hipotezi oluşturun: Değişikliğin hangi alanları etkileyebileceğini belirleyin.
- İlgili dosyaları seçin: Kod, test, tip ve sözleşmeleri aktif context’e alın.
- Gerçek sistemden geri bildirim alın: Test, log, build ve diff kullanın.
- Görev uzuyorsa durumu dışsallaştırın: Plan ve bulguları kalıcı bir yerde tutun.
- Context gürültülendiyse sıkıştırın: Geçersiz veya artık gerekli olmayan ayrıntıları taşımayın.
- Değişiklikten sonra yeniden haritalayın: Varsayılan etki alanının dışına çıkan sonuç olup olmadığını kontrol edin.
Bu akış, agentın her görevi aynı biçimde yürütmesi gerektiği anlamına gelmez. Küçük bir bug fix ile sistem çapında migration aynı keşif maliyetine sahip değildir. Ama temel prensip, context’i kontrolsüz büyütmek yerine göreve göre yönetmektir.
Büyük repository’lerde insan geliştiricinin rolü ne?
Agent kod tabanını hızlı araştırabilir ancak hangi mimari bilginin kritik olduğunu ve hangi riskin kabul edilebilir olduğunu her zaman doğru değerlendirmeyebilir. İnsan geliştirici, görevin kapsamını, güvenlik sınırını ve başarı kriterini belirleyerek context seçim sürecini daha doğru hale getirir.
Özellikle birden fazla iş sistemi ve entegrasyon içeren projelerde teknik olarak yakın görünen dosyalar gerçek iş kuralında farklı sorumluluklar taşıyabilir. Bir iş süreci otomasyonu veya kurumsal uygulamada domain bilgisi yalnız koddan çıkarılamayabilir; iş kuralı dokümantasyonu ve insan açıklaması gerekebilir.
En iyi sonuç, agentın geniş tarama ve tekrar eden keşif yeteneği ile insanın sistem amacı ve risk bilgisi birleştirildiğinde ortaya çıkar.
Context yönetimi için kontrol listesi
- Agent göreve başlamadan önce ilgili modülleri haritaladı mı?
- Aktif context içindeki her büyük bilgi parçası görev için gerçekten gerekli mi?
- Testler, tipler ve veri sözleşmeleri yalnız implementasyon kodu kadar dikkate alındı mı?
- Uzun araştırma ana context’i dolduruyorsa ayrı keşif görevi kullanılmalı mı?
- Plan ve kritik bulgular yalnız sohbet geçmişinde mi tutuluyor?
- Eski veya artık geçersiz varsayımlar context içinde kalmaya devam ediyor mu?
- Yapılan değişiklik gerçek test, log veya build sonucu ile doğrulandı mı?
- Repository dokümantasyonu agente harita sunuyor mu, yoksa tek dev bilgi yığını mı?
Sonuç: Büyük kod tabanını anlamanın sırrı daha fazla context değil, doğru context
AI agentın büyük bir kod tabanında başarılı olması, bütün repository’yi tek seferde okumasına bağlı değildir. Etkili sistemler kod tabanını haritalar, ilgili parçaları arar, yalnız yüksek değerli bağlamı aktif context’e taşır ve geri kalan bilgiyi repository, index, dokümantasyon veya başka dış durumlarda tutar.
Context window büyüklüğü önemlidir ancak tek başına çözüm değildir. Gereksiz context modelin dikkatini dağıtabilir; uzun görevlerde eski bilgi birikebilir; ham keşif sonuçları implementasyon alanını tüketebilir. Compaction, externalized state, subagent araştırması ve gerçek tool geri bildirimi bu nedenle büyük repository çalışmalarında önem kazanır.
İyi context management, agente mümkün olan en fazla bilgiyi vermek değildir. Doğru anda doğru bilgiyi bulmasını, yaptığı varsayımları gerçek sistem sonuçlarıyla kontrol etmesini ve uzun görevlerde kritik durumu kaybetmeden ilerlemesini sağlamaktır.
Sıkça Sorulan Sorular
AI agent büyük bir kod tabanını nasıl anlar?
AI agent genellikle bütün repository’yi tek seferde context window’a yüklemez. Önce klasör ve modül yapısını keşfeder, ilgili dosya ve sembolleri arar, görev için gerekli kod parçalarını aktif context’e alır ve test, log ve komut sonuçlarından geri bildirim toplar. Uzun görevlerde plan ve bulgular repository veya başka dış durumlarda saklanabilir. Bu nedenle anlayış, retrieval, context seçimi ve doğrulamanın birleşimidir.
Büyük context window bütün kod tabanını anlamak için yeterli mi?
Hayır. Büyük context window daha fazla bilgi taşımaya izin verir ancak daha fazla context her zaman daha iyi sonuç anlamına gelmez. İlgisiz dosyalar, eski konuşma ayrıntıları ve gereksiz tool çıktıları önemli sinyalleri seyreltebilir. Büyük repository’lerde amaç context’i tamamen doldurmak değil, görev için en yüksek değerli kod, test, sözleşme ve gerçek sistem geri bildirimlerini seçmektir.
Codebase indexing ne işe yarar?
Codebase indexing, büyük kod tabanındaki ilgili dosya ve kod parçalarını aramayı kolaylaştırabilir. Semantic veya başka arama yöntemleriyle görevle ilişkili bölümlerin bulunmasına yardımcı olur. Ancak indekslenen bütün kod her istekte modele gönderilmek zorunda değildir ve indexleme tek başına gerçek sistem davranışını kanıtlamaz. Bulunan kod referans, test, build ve runtime sonuçlarıyla ayrıca doğrulanmalıdır.
Context dolduğunda AI coding agent ne yapabilir?
Uzun görevlerde context sıkıştırılabilir, kritik durum harici dosyalara yazılabilir, bağımsız keşif işleri ayrı subagentlara devredilebilir veya yeni bir görev oturumu temiz context ile başlatılabilir. Amaç bütün geçmişi kelimesi kelimesine taşımak değil; görev için gerekli kararları, doğrulanmış bulguları ve mevcut durumu korumaktır. Compaction sırasında kritik bilgilerin dışsallaştırılmış olması bilgi kaybı riskini azaltır.
Subagent kullanmak büyük kod tabanlarında neden yararlı olabilir?
Geniş repository keşfi çok sayıda dosya okuması gerektirerek ana agent context’ini doldurabilir. Ayrı bir subagent belirli araştırmayı kendi context’inde yapıp ana agente yalnız yapılandırılmış bulguları döndürebilir. Bu yöntem özellikle çağrı zinciri, test yapısı veya belirli bir domainin araştırılmasında yararlı olabilir. Ancak araştırma sorusu ve beklenen çıktı net değilse önemli ayrıntılar özet sırasında kaybolabilir.
Büyük kod tabanında AI agent için en önemli context kaynakları nelerdir?
Görev ve kabul kriterleri, ilgili proje kuralları, değişecek kodun yakın çevresi, testler, tip ve veri sözleşmeleri ile gerçek tool sonuçları en değerli context kaynakları arasındadır. Hangi kaynağın öncelikli olduğu göreve göre değişir. Temel amaç modele mümkün olan en fazla bilgiyi vermek değil, vereceği kararları gerçekten etkileyen doğru ve güncel bilgiyi seçmektir.
