Bir yazılım sistemi tek repository’den oluşmak zorunda değildir. Frontend, backend, mobil uygulama, ortak kütüphane, altyapı kodu ve entegrasyon servisleri ayrı repository’lerde tutulabilir. Böyle bir yapıda AI coding agentın yalnız bir kod tabanını anlaması yeterli olmaz; değişikliğin birden fazla repository’ye yayıldığı durumlarda doğru sürümleri, sözleşmeleri, branch’leri ve release sırasını da koordine etmesi gerekir.
15 Temmuz 2026 itibarıyla bazı coding agent ürünleri tek oturum veya workspace içinde birden fazla repository’ye erişebiliyor. Cursor 3, multi-repo layout ve multi-root workspaces ile cross-repo değişiklikleri desteklediğini duyurdu Cursor 3 Cursor Multi-root Workspaces. Claude Code, ek çalışma dizinlerini --add-dir veya /add-dir ile okuyup düzenleyebiliyor Claude Code CLI Reference. GitHub Copilot CLI, ortak bir üst klasörden başlatıldığında altındaki birden fazla repository üzerinde çalışabilen multi-repository workflow sunuyor GitHub Copilot CLI Best Practices. OpenAI Codex changelog’u da 2026’da bir proje içinde repository’ler arasında çalışma özelliğini duyurdu OpenAI Codex Changelog. Ancak “erişebiliyor” ile “tek işlem gibi güvenle değiştirebiliyor” aynı şey değildir.
AI agent birden fazla repository ile gerçekten çalışabilir mi?
Evet. Güncel araçların bir bölümü birden fazla klasör veya repository’yi aynı çalışma bağlamına ekleyebiliyor. Agent böylece frontend’de kullanılan bir API çağrısını, backend’deki endpoint’i ve ortak tip paketini birlikte inceleyebilir. Bazı araçlarda tek agent session birden fazla root üzerinde çalışırken, bazı cloud agent akışları görevi repository bazında sınırlar.
Örneğin GitHub Copilot cloud agentın resmî dokümantasyonu, tek bir run içinde yalnız görevin başlatıldığı repository’de değişiklik yapabildiğini ve birden fazla repository’de aynı run içinde değişiklik yapamadığını açıkça belirtir GitHub Copilot Cloud Agent. Buna karşılık GitHub Copilot CLI’nin resmî best practices rehberi, bir üst dizinden çalıştırıldığında altındaki farklı repository’lere aynı oturumda erişebilen workflow’u anlatır GitHub Copilot CLI Best Practices.
Dolayısıyla “bu ürün multi-repo destekliyor mu?” sorusuna tek kelimelik cevap vermek yanıltıcı olabilir. Aynı ürünün CLI, IDE veya cloud agent yüzeyi farklı sınırlar taşıyabilir.
Çoklu repository çalışmasının üç temel modeli
Multi-repo agent mimarisi tek bir yöntemden oluşmaz. Pratikte üç temel model bulunur.
1. Tek agent, birden fazla repository
Agent aynı session içinde frontend, backend ve ortak library gibi birden fazla repository’ye erişir. Cross-repo değişikliğin bağlamını tek yerde görebilir ve dosyaları birlikte düzenleyebilir.
Cursor’ın 2026 multi-root workspace özelliği cross-repo changes kullanımını doğrudan hedefler Cursor Multi-root Workspaces. Claude Code’da ek çalışma dizinleri dosya erişim alanını genişletebilir; ancak ek dizinlerin proje yapılandırmalarının otomatik yüklenme davranışı ayrıca yönetilmelidir Claude Code Large Codebases.
Bu model küçük ve güçlü biçimde ilişkili repository setlerinde verimli olabilir. Ancak agentın yazma yetkisi genişledikçe yanlış repository’ye değişiklik yapma ve bağımsız branch durumlarını karıştırma riski artar.
2. Her repository için ayrı agent
Her repository bağımsız çalışma alanı ve branch ile ele alınır. Bir coordinator, insan veya üst seviye plan hangi repository’de hangi değişikliğin yapılacağını belirler.
Bu model repository bazlı cloud agent ürünleri için doğal olabilir. GitHub Copilot cloud agent tek run içinde bir repository ile sınırlı olduğundan, cross-repo iş ayrı görev ve pull requestlere bölünebilir GitHub Copilot Cloud Agent.
Ayrı agent yaklaşımı güvenlik ve review sınırlarını daha net tutabilir; fakat repository’ler arasındaki koordinasyon ayrıca çözülmelidir.
3. Hibrit coordinator modeli
Bir ana agent veya insan geliştirici cross-repo planı çıkarır; alt görevler repository bazında ayrı agentlara verilir. Son aşamada contract testleri ve entegrasyon kontrolleri bütün değişiklikleri birlikte doğrular.
Bu model büyük mikroservis yapılarında daha ölçeklenebilir olabilir. Her agent yalnız kendi repository’sinde çalışırken coordinator değişiklik sırasını, bağımlılıkları ve release planını yönetir.
| Model | Avantaj | Temel risk |
|---|---|---|
| Tek agent, çoklu repo | Cross-repo bağlam tek oturumda görülebilir | Geniş yazma alanı ve branch karmaşası |
| Repo başına ayrı agent | Net güvenlik ve review sınırları | Koordinasyon ve bağımlılık yönetimi |
| Coordinator + alt agentlar | Merkezi plan ile izole uygulama birleşir | Plan ve durum senkronizasyonu gerekir |
Multi-repo ile monorepo aynı problem mi?
Hayır. Monorepo, birden fazla uygulama veya paketin aynı Git repository içinde tutulduğu organizasyon modelidir. Multi-repo ise ilişkili parçaların ayrı Git geçmişlerine, branch’lere ve çoğu zaman ayrı release süreçlerine sahip olmasıdır.
Bir agent monorepo içinde birçok proje üzerinde çalışabilir; fakat Git açısından yine tek repository vardır. Multi-repo çalışmada ise agentın birden fazla bağımsız Git durumu vardır. Bir repository’de commit oluşturulurken diğerinde hâlâ unstaged değişiklik olabilir. Bir PR merge edilmişken diğerinin review’u devam edebilir.
AI agent kullanabilmek için mevcut sistemi monorepo’ya çevirmek zorunlu değildir. Repository stratejisi organizasyon, sahiplik, release bağımsızlığı ve erişim sınırlarıyla verilmelidir. Coding agent yalnız bu mimariye uyum sağlamalıdır.
En zor konu: Cross-repo değişiklik neden atomik değildir?
Tek repository’de bir commit, birden fazla dosyayı tek Git değişikliği olarak taşıyabilir. Fakat üç ayrı repository’de yapılan değişiklikler tek bir Git commit altında atomik biçimde merge edilemez. Bu durum AI agent için de geçerlidir.
Örneğin tamamen hipotetik bir senaryoda, backend API yeni bir alan döndürmeye başlıyor, ortak client library bu alanı modele ekliyor ve frontend yeni alanı kullanıyor olabilir. Üç repository aynı anda production’a çıkmazsa geçiş dönemi oluşur. Bu gerçek bir müşteri vakası değil, cross-repo release problemini açıklamak için kullanılan hipotetik örnektir.
Bu nedenle agentın yalnız üç repository’de doğru kod üretmesi yeterli değildir. Şunlar da planlanmalıdır:
- Hangi değişiklik önce merge edilecek?
- Eski ve yeni sürümler geçici olarak birlikte çalışabilir mi?
- Breaking change var mı?
- Feature flag veya backward-compatible geçiş gerekiyor mu?
- Rollback yapılırsa diğer repository’ler ne olacak?
Repository’ler arasındaki sözleşme nasıl yönetilmeli?
Çoklu kod tabanında en güvenilir sınır, açık sözleşmedir. API şeması, event formatı, protobuf tanımı, database contract veya ortak type package gibi artefactlar repository’ler arasındaki beklentiyi görünür hale getirir.
Bir API entegrasyonu değişikliğinde agent önce producer ve consumer taraflarını haritalamalıdır. Yalnız endpoint implementasyonunu değiştirmek, tüketici repository’lerin davranışını otomatik olarak güvenli hale getirmez.
Cross-repo görev başlamadan önce şu sorular cevaplanmalıdır:
- Sözleşmenin source of truth’u hangi repository’de?
- Breaking change nasıl tanımlanıyor?
- Consumer eski sürümle ne kadar süre çalışabilmeli?
- Contract test veya schema validation var mı?
- Versiyon numarası ve release notu kim tarafından güncellenecek?
Branch ve pull request koordinasyonu nasıl yapılmalı?
Multi-repo değişikliğin her repository’de ayrı branch ve pull request üretmesi yaygın bir modeldir. Bu durumda PR’ların birbirine bağlı olduğu açıkça belirtilmelidir.
Agent için görev planı repository bazında ayrılabilir:
- Değişiklik planı ve compatibility stratejisi hazırlanır.
- Her repository için ayrı branch adı veya issue bağlantısı oluşturulur.
- Bağımlı PR’lar birbirine referans verir.
- Her repository kendi testlerini çalıştırır.
- Cross-repo integration veya contract testleri ayrıca çalıştırılır.
- Merge ve deployment sırası önceden belirlenir.
Burada “agent üç PR açtı” başarı kriteri değildir. PR’ların hangi sırayla merge edilmesi gerektiği ve ara durumda sistemin çalışıp çalışmadığı bilinmelidir.
Worktree çoklu repository problemi çözer mi?
Hayır. Git worktree, aynı repository’nin farklı branch veya çalışma kopyalarını paralel biçimde yönetmek için kullanılır. OpenAI Codex worktrees dokümantasyonu, aynı proje içinde bağımsız görevlerin birbirini etkilemeden çalışmasını bu amaçla açıklar OpenAI Codex Worktrees.
Worktree, aynı repository’de paralel agent görevleri için çok değerlidir; fakat frontend ve backend iki ayrı repository ise bunları tek repository haline getirmez. Multi-repo koordinasyon ile multi-agent worktree koordinasyonu farklı problemlerdir.
Bir projede ikisi birlikte de kullanılabilir: Her repository ayrı kalırken, her repository içinde farklı agent görevleri ayrı worktree’lerde yürütülebilir.
Çoklu repository’de context nasıl sınırlandırılmalı?
Bir agente on repository açmak, on repository’nin tamamını sürekli aktif context’e taşımak anlamına gelmemelidir. Agent önce hangi kod tabanlarının görevle gerçekten ilişkili olduğunu belirlemelidir.
Çoklu repo çalışmada iyi başlangıç sırası şöyledir:
- İş değişikliğini tek cümlede tanımlayın.
- Producer, consumer ve ortak sözleşme repository’lerini belirleyin.
- Her repository’nin ilgili giriş noktalarını bulun.
- Bağımlılık yönünü çıkarın.
- Yalnız aktif görev için gerekli repository’lere yazma yetkisi verin.
Bu yaklaşım, 213 numaralı büyük kod tabanı context probleminden farklı bir noktaya odaklanır: Burada yalnız bilgi hacmi değil, bağımsız repository sınırları ve değişiklik koordinasyonu vardır.
Proje kuralları her repository’de ayrı mı tutulmalı?
Genellikle repository’ye özgü build, test ve mimari kurallar kendi kod tabanına yakın tutulmalıdır. Frontend’in test komutları backend repository’sinin talimat dosyasında merkezi olarak kopyalanırsa zamanla güncellik sorunu oluşabilir.
Claude Code’un additional directories dokümantasyonu, ek dizine dosya erişimi verilmesinin o dizini otomatik olarak tam bir configuration root yapmadığını açıklar; ek dizinlerdeki bazı proje talimatlarının yüklenmesi ayrı yapılandırma gerektirebilir Claude Code Large Codebases. Bu ayrıntı, multi-repo session açıldığında “agent bütün repository kurallarını otomatik biliyor” varsayımının neden kontrol edilmesi gerektiğini gösterir.
Ortak kurallar merkezi bir ekip dokümanında veya reusable skill yapısında tutulabilir; repository’ye özel kurallar ise yerel kalabilir.
Güvenlik açısından çoklu repo erişimi nasıl yönetilmeli?
Bir agentın birden fazla repository’yi okuyabilmesi, hepsinde yazma yetkisine ihtiyaç duyduğu anlamına gelmez. Özellikle production altyapısı, secret yönetimi veya güvenlik politikası taşıyan repository’ler daha dar izin gerektirebilir.
En düşük yetki yaklaşımı multi-repo agentlarda şu şekilde uygulanabilir:
- Görevle ilgisiz repository’leri çalışma alanına eklememek.
- Gerekli yerde read-only erişim kullanmak.
- Yazma yetkisini yalnız değişecek repository’lerle sınırlamak.
- Secret ve deployment credentiallarını agent workspace’inden ayırmak.
- Her repository’nin approval ve branch protection kurallarını korumak.
GitHub Copilot cloud agentın tek repository per run sınırı bazı cross-repo işlerde operasyonel kısıt olabilir; fakat aynı zamanda görev erişiminin repository sınırında tutulmasına yardımcı olan bir izolasyon biçimi olarak da değerlendirilebilir GitHub Copilot Cloud Agent.
Cross-repo test stratejisi nasıl kurulmalı?
Her repository’nin kendi testlerinin geçmesi bütün sistemin birlikte çalıştığını kanıtlamaz. Producer ve consumer ayrı ayrı yeşil olabilir ancak birbirleriyle uyumsuz olabilir.
Bu nedenle çoklu repo değişikliklerinde üç test seviyesi yararlı olabilir:
| Test seviyesi | Ne doğrular? | Nerede çalışır? |
|---|---|---|
| Repository içi testler | Yerel implementasyon ve regresyonlar | Her repository’nin kendi CI süreci |
| Contract testleri | Producer ve consumer sözleşmesi | Sözleşme veya entegrasyon pipeline’ı |
| End-to-end entegrasyon | Birlikte çalışan sürümlerin gerçek akışı | Ortak test ortamı |
Her sistem bu üç seviyeyi aynı biçimde kullanmak zorunda değildir. Ancak cross-repo değişikliğin yalnız repository-local unit testlerle doğrulanması çoğu zaman yetersizdir.
AI agent multi-repo değişiklik planını nasıl hazırlamalı?
Kod yazmadan önce plan, repository bazında açık olmalıdır. İyi bir plan şu yapıyı kullanabilir:
- Repo A: Sözleşme veya producer değişikliği.
- Repo B: Consumer uyumluluk değişikliği.
- Repo C: Ortak package veya deployment konfigürasyonu.
- Compatibility: Eski ve yeni sürümlerin birlikte çalışma kuralı.
- Merge order: PR’ların uygulanma sırası.
- Validation: Repository içi ve cross-repo testler.
- Rollback: Kısmi deployment durumunda geri dönüş planı.
Bu planın agent conversation içinde kaybolması yerine issue, task dokümanı veya başka kalıcı bir yerde tutulması uzun görevlerde daha güvenlidir.
Tek agent mı, birden fazla agent mı kullanılmalı?
Repository sayısı az ve değişiklik güçlü biçimde birbirine bağlıysa tek agentın multi-root workspace içinde çalışması hızlı olabilir. Repository sayısı arttıkça veya ekip sahipliği ayrıştıkça repo başına ayrı agent ve merkezi coordinator modeli daha kontrollü hale gelebilir.
Seçim şu kriterlere göre yapılabilir:
- Kaç repository değişecek?
- Değişiklikler ne kadar bağımsız?
- Farklı ekipler ayrı review sorumluluğuna sahip mi?
- Repository’lerin güvenlik seviyeleri farklı mı?
- Release sırası karmaşık mı?
- Cross-repo sözleşme testleri var mı?
Bir özel yazılım sisteminde agent topolojisi mevcut ekip ve repository topolojisine göre seçilmelidir. Her işi tek dev agenta vermek de, her dosya için ayrı agent açmak da otomatik olarak doğru değildir.
Multi-repo çalışmada en sık yapılan hatalar
- Birden fazla repository’yi aynı klasöre açınca koordinasyon probleminin çözüldüğünü sanmak.
- Hangi repository’nin sözleşmenin source of truth’u olduğunu belirlememek.
- Breaking change’i tek seferde bütün consumerların güncelleneceği varsayımıyla yapmak.
- PR’ları birbirine bağlamadan bağımsız merge etmek.
- Her repository’nin testinin geçmesini sistem entegrasyonunun kanıtı saymak.
- Agentın bütün repository’lerde yazma yetkisine sahip olmasını varsayılan yapmak.
- Release ve rollback sırasını kod tamamlandıktan sonra düşünmek.
- Monorepo ve multi-repo problemlerini aynı şey gibi değerlendirmek.
Çoklu repository için pratik karar kontrol listesi
- Değişiklik gerçekten kaç repository’yi etkiliyor?
- Bu repository’ler aynı anda mı, farklı sırada mı release ediliyor?
- Aralarında açık API, event veya package sözleşmesi var mı?
- Tek agentın hepsine yazması gerekli mi, yoksa bazıları read-only olabilir mi?
- Her repository için ayrı branch ve PR planı var mı?
- Cross-repo compatibility nasıl doğrulanacak?
- Kısmi merge veya deployment durumunda sistem çalışmaya devam eder mi?
- Rollback sırası tanımlı mı?
- Agent ürününün kullandığınız yüzeyi gerçekten multi-repo değişiklik destekliyor mu?
Sonuç: Çoklu repo desteği erişim değil koordinasyon problemidir
AI coding agentlar artık birden fazla repository veya çalışma diziniyle çalışabiliyor. Cursor multi-root workspaces, Claude Code additional directories, GitHub Copilot CLI multi-repository workflows ve Codex’in proje içi cross-repository desteği bu yönelimin güncel örnekleridir. Bununla birlikte bazı cloud agent akışları hâlâ görev başına tek repository ile sınırlı olabilir.
Asıl mühendislik problemi agentın dosyaları görebilmesi değildir. Ayrı Git geçmişleri, branch’ler, pull requestler, API sözleşmeleri, test pipeline’ları ve release sıraları arasında tutarlı değişiklik üretmektir. Cross-repo değişiklikler tek commit gibi atomik olmadığı için backward compatibility ve deployment planı özellikle önemlidir.
En iyi yaklaşım, repository topolojisini agenta körlemesine açmak değil; görev için gerekli kod tabanlarını belirlemek, yazma yetkisini sınırlamak, değişiklik planını repo bazında ayırmak ve bütün sistemi contract ile entegrasyon testleri üzerinden doğrulamaktır.
Sıkça Sorulan Sorular
AI coding agent birden fazla repository ile çalışabilir mi?
Evet. Bazı güncel coding agent araçları tek workspace veya session içinde birden fazla repository ya da çalışma dizinine erişebilir. Ancak destek ürün yüzeyine göre değişebilir. Örneğin bir CLI multi-repo çalışabilirken aynı ürünün cloud agent modu görev başına tek repository ile sınırlı olabilir. Bu nedenle yalnız ürün adına değil, kullanılan IDE, CLI veya cloud çalışma modunun güncel dokümantasyonuna bakılmalıdır.
Multi-repo ile monorepo arasındaki fark nedir?
Monorepo birden fazla uygulama veya paketi tek Git repository içinde tutar. Multi-repo mimarisinde ise parçalar ayrı Git geçmişlerine, branch’lere ve çoğu zaman bağımsız release süreçlerine sahiptir. Bir agentın monorepo içinde çok sayıda klasörü değiştirmesi ile üç ayrı repository’de koordineli PR üretmesi aynı problem değildir. Multi-repo çalışmada merge sırası, compatibility ve cross-repo testleri ayrıca yönetilmelidir.
Birden fazla repository için tek agent mı kullanılmalı?
Repository sayısı az ve değişiklikler güçlü biçimde bağlıysa tek agentın multi-root workspace içinde çalışması verimli olabilir. Repository sayısı, ekip sahipliği veya güvenlik sınırları arttığında repo başına ayrı agent ve merkezi coordinator yaklaşımı daha kontrollü olabilir. Doğru model; bağımlılık yapısı, review sorumluluğu, release sırası ve kullanılan agent ürününün yeteneklerine göre seçilmelidir.
Cross-repo değişiklikler neden daha risklidir?
Ayrı repository’lerdeki değişiklikler tek bir Git commit gibi atomik değildir. Bir PR merge edilirken diğer repository’nin değişikliği bekleyebilir veya farklı zamanda production’a çıkabilir. Bu nedenle eski ve yeni sürümlerin geçici olarak birlikte çalışabilmesi, API ve event sözleşmelerinin korunması, merge sırası ve rollback planı önemlidir. Agentın bütün repository’lerde doğru kod yazması tek başına güvenli deployment sağlamaz.
Worktree birden fazla repository ile çalışmayı sağlar mı?
Worktree temel olarak aynı Git repository’nin farklı branch veya çalışma kopyalarını paralel yönetmek için kullanılır. Bu nedenle iki ayrı repository’yi tek repository haline getirmez. Multi-repo koordinasyon farklı bir problemdir. Bununla birlikte her repository kendi içinde worktree kullanabilir; böylece aynı repository’de birden fazla agent görevi izole çalışırken repository’ler arası koordinasyon ayrı katmanda yönetilebilir.
Çoklu repository değişikliği nasıl test edilmelidir?
Her repository önce kendi unit, integration, lint ve build kontrollerini çalıştırmalıdır. Bunun yanında producer ve consumer arasındaki API, event veya package sözleşmesini doğrulayan contract testleri gerekebilir. Son olarak birlikte deploy edilecek sürümlerin gerçek akışını kontrol eden end-to-end veya ortak entegrasyon testi yararlı olabilir. Yalnız her repository’nin kendi testinin yeşil olması, cross-repo uyumluluğunu garanti etmez.
