AI Kodlama Ajanlarıyla Git Worktree'leri Nasıl Kullanılır

İki yapay zeka kodlama ajanını aynı checkout'a yönlendirin, sonunda koca bir öğleden sonrayı heba ederler. Biri, diğerinin tam da üzerinde düzenleme yaptığı dosyayı baştan yazar. Biri, diğerinin altından branch'i değiştiriverir. İkisi de aynı node_modules üzerinde npm install çalıştırır ve ortada kimsenin yazmadığı bir lockfile bırakır. Arıza sessizce ilerler, ta ki sessiz kalmayana kadar; sonra iki ajanın da açıklayamadığı bir karmaşayı bisect etmeye başlarsınız.

Standart çözüm git worktree'lerdir. Bir worktree, her ajana tek bir paylaşılan depo üzerinde kendi çalışma dizinini ve kendi checkout edilmiş branch'ini verir; böylece paralel çalışma çakışmayı bırakır. Bu rehber gerçek komutları, pratikte canınızı yakan tuzakları ve kimsenin size söylemediği temizlik disiplinini adım adım ele alıyor. Ardından elle yazılmış worktree script'lerinin nerede ölçeklenmeyi bıraktığını ve Sharkly'nin her Task'ı otomatik olarak kendi worktree'sinde nasıl çalıştırdığını, böylece sonuçların terminal ekranlarına dağılmak yerine tek bir paylaşılan kayda nasıl döndüğünü gösteriyor.

Tek bir ajan çalıştırıyorsanız, henüz bunların hiçbirine ihtiyacınız yok. İki ajan çalıştırmaya başladığınız anda izolasyon opsiyonel olmaktan çıkar.

TL;DR

Bir git worktree, aynı depoya bağlı, kendi branch'i ve index'i olan ikinci bir çalışma dizinidir. Her yapay zeka kodlama ajanına kendi worktree'sini verin; birbirlerinin üzerine yazmadan, mevcut branch için kavga etmeden paralel olarak düzenleyebilir, derleyebilir ve test edebilirler. Komutlar basittir; büyüyen şey operasyonel maliyettir (worktree başına kurulumlar, temizlik, disk, koordinasyon). Sharkly bu maliyeti, her Task için otomatik olarak izole bir worktree hazırlayarak ve her sonucu inceleme amacıyla Task'a geri döndürerek yönetir.

Tek bir checkout neden iki ajanı barındıramaz

Normal bir git checkout'ta tam olarak bir çalışma dizini, bir index ve bir HEAD bulunur. Tek bir kişinin tek bir iş yapması için bu gayet iyidir. Ama iki ajan aynı anda çalışmaya başladığı anda bu düzen çöker, çünkü bu üçünün hepsi paylaşılan durumdur.

Aynı depo üzerinde çalışan iki ajan düşünün. Ajan A, auth-refactor adlı bir branch'te auth modülünü refactor ediyor. Ajan B'den bir logging hatasını düzeltmesi isteniyor ve git checkout -b fix-logging komutunu çalıştırıyor. Bu tek komut, tüm checkout için HEAD'i taşıyor. Ajan A'nın commit edilmemiş değişiklikleri artık yanlış branch'in üzerinde duruyor, bir sonraki commit'i yanlış yere düşüyor ve build'i, yirmi dakikasını "debug" yaparak geçireceği sebeplerle başarısız olmaya başlıyor. Hiçbir şey çökmedi. Durum sessizce yanlış gitti.

Dosyalar söz konusu olduğunda iş daha da kötüleşiyor. İki ajan tek bir çalışma dizinini paylaşıyor; dolayısıyla Ajan B bir config dosyasını yeniden ürettiğinde ya da bir formatter'ı yeniden çalıştırdığında, Ajan A'nın açık düzenlemeleri diskte ezilip gidiyor. Kodlama ajanları "diğeri şu an bir işin ortasında" gibi bir zihinsel modele sahip değiller. Dosyayı okur, işlem yapar ve geri yazarlar. İki yazıcı, tek dosya, kilit yok. Klasik lost-update (kayıp güncelleme) problemiyle karşılaşırsınız; tek fark, yazıcıların otonom ve hızlı olması.

"git worktrees" anahtar kelimesinin sürekli ortaya çıkardığı sıkıntı tam da bu. İnsanlar worktree'leri branching ilginç olduğu için aramıyor. Ajanları paralel çalıştırmayı deneyip yandıkları için arıyorlar. Siz de o kişiyseniz, paralel çalıştırma tarafı birden fazla Claude Code ajanını paralel çalıştırma rehberimizde ayrıntılı olarak ele alınıyor; bu makale ise onun altındaki izolasyon primitifi.

Bir git worktree aslında nedir

İşte ezberlemeye değer tanım:

Bir git worktree, aynı depoya bağlı, kendi checkout edilmiş branch'i, index'i ve HEAD'i olan ve tek bir nesne veritabanını paylaşan ek bir çalışma dizinidir.

İşin bütün sırrı son cümlede. Bir worktree, clone değildir. Clone'lar tüm nesne deposunu kopyalar: her commit, her blob, her tag ikinci bir .git'e kopyalanır. Worktree'ler tek bir nesne deposunu paylaşır ve yalnızca hafif ikinci bir çalışma dizini ekler. Commit'leriniz, atıldıkları anda her worktree'den görünür, çünkü altta tek bir tarihçe vardır. Worktree başına değişen şey checkout'tur: hangi branch dışarıda, ne stage edilmiş, diskte ne kirli.

Ajanlar açısından bu, problemin üzerine tam oturuyor. Her ajan bir worktree alır. Her worktree'nin kendi branch'i ve kendi dosyaları vardır. Birbirlerinin üzerine yazamazlar, çünkü kelimenin tam anlamıyla farklı dizinlerdeler; birbirlerinin altından branch'i çekip alamazlar, çünkü her worktree kendi HEAD'ini sabitler. Çakışmalar ait oldukları yere taşınır: kazara düzenleme ortasında değil, bilinçli olarak merge zamanına, inceleme altına.

Gerçekten kullanacağınız worktree komutları

Normal bir depoda başlayın. Aşağıdaki her komut onun içinden çalıştırılır.

Yeni bir branch ile worktree oluşturma. En çok kullanacağınız komut bu:

git worktree add -b fix-logging ../myproject-fix-logging main

Bu komut ../myproject-fix-logging konumunda bir dizin oluşturur, main'den başlayan yeni bir fix-logging branch'i yapar ve orada checkout eder. Bir ajanı o dizine yönlendirin; temiz, izole bir çalışma alanına sahip olur.

Mevcut bir branch için worktree oluşturma:

git worktree add ../myproject-auth auth-refactor

Açık olanları listeleme:

git worktree list

/Users/you/myproject              9f3c1a2 [main]
/Users/you/myproject-fix-logging  9f3c1a2 [fix-logging]
/Users/you/myproject-auth         3b7e0d4 [auth-refactor]

Her worktree için bir satır: yolu, checkout edilmiş commit'i ve branch'i. Bir ajan filosu çalıştırdığınızda, kimin nerede olduğuna dair tek doğru kaynak bu liste olur.

İş merge edildiğinde ya da terk edildiğinde worktree'yi kaldırma:

git worktree remove ../myproject-fix-logging

Bir worktree dizinini elle sildikten sonra bayat metadata'yı prune etme (ajanlar ve script'ler bunu tahmin ettiğinizden çok daha sık yapar):

git worktree prune

Bütün yüzey alanı bu kadar. Beş komut. Zorluk komutlarda değil.

Gerçekten canınızı yakan tuzaklar

Komutlar basit. Öğleden sonraların gittiği yer operasyonel gerçeklik. Bunlar, gerçek ajanlar gerçek worktree'lerde çalışmaya başladığında ortaya çıkan arıza modları.

Takip edilmeyen ve gitignore'lanmış dosyalar sizinle gelmez. Bir worktree, istediğiniz branch'te takip edilen dosyaları checkout eder. node_modules'unuzu, .env'inizi, venv'inizi, build cache'inizi ya da git'in yok saydığı başka bir şeyi kopyalamaz. Bu yüzden bir Node projesi için yeni bir worktree, içinde install çalıştırmadığınız sürece çalıştırılabilir değildir. Her worktree kendi bağımlılık kurulumunun, kendi environment dosyasının, kendi build'inin bedelini öder. "Depo zaten kurulu" varsayımıyla hareket eden ajanlar, siz kurulumu açıkça halledene kadar yeni bir worktree'deki ilk komutlarında başarısız olur.

Aynı branch'i iki kez checkout edemezsiniz. Git, bir branch'in aynı anda iki worktree'de checkout edilmesini reddeder ve bunda haklıdır. İki ajanın da main'i checkout etmesi gerekiyorsa, biri yeni bir branch açmak zorundadır. Bu bir kısıtlama değil, bir özellik; ama worktree'lerin serbest dolaşan kopyalar olduğunu bekleyenleri şaşırtıyor.

Disk hızla büyür. Nesne deposu paylaşıldığı için tarihçe ucuzdur. Çalışma dizinleri ve kurulumları değildir. 900 MB'lık bir node_modules'a sahip bir projenin on worktree'si, 9 GB kopyalanmış bağımlılık demektir. Birkaç ajan çalıştıran bir dizüstü bilgisayarda bunu öğle yemeğine kadar hissedersiniz.

Kirli worktree'ler kaldırılmaya direnir. Worktree'de commit edilmemiş değişiklikler varsa git worktree remove reddeder; bu da bir ajanın bitirmediği işi çöpe atmanızı engeller. Gerçekten gitmesini istediğinizde git worktree remove --force. Ama artık o commit edilmemiş işin önemli olup olmadığına dair kararı, her worktree için, elle siz veriyorsunuz.

Silinen dizinler hayalet bırakır. Bir worktree klasörünü rm -rf ile silin; git worktree prune çalıştırana kadar git onu listelemeye devam eder. Worktree'leri temizlediklerinden daha hızlı oluşturan script'ler bayat kayıtlar biriktirir ve bu kayıtlar, branch adlarının yeniden kullanılmasını engelleyen kilitleri tutar. Temizlik opsiyonel değil; sadece git worktree list bir mezarlığa dönene kadar unutması kolay.

İç içe ajan cache'leri sizin silmeniz için değil. Bazı runtime'lar kendi worktree cache'lerini tutar, örneğin ~/.claude/worktrees altında. Kendi temizlik script'lerinizi bunlara yöneltmeyin. Bir cache'e sahip olan aracın onu yönetmesine izin verin.

Bunların hiçbiri tek başına zor değil. Sorun, birikerek çoğalmaları. İki worktree'yi elle yönetirsiniz. Beş olunca bir script yazarsınız. İki depoda on iki ajan çalıştırmaya başlayınca o script, kendi hataları olan küçük bir altyapı parçası haline gelir ve nöbetçisi siz olursunuz.

Script'lerin ölçeklenmeyi bıraktığı nokta

Dürüst hikâye şöyle görünür. git worktree add komutunu saran, yeni dizine bir ajan bırakan ve kurulumu çalıştıran bir shell fonksiyonuyla başlarsınız. Çalışır. Dizinler çakışmasın diye bir adlandırma şeması eklersiniz. Bir temizlik komutu eklersiniz. Sonra gereksinimler üst üste yığılır.

Şu anda hangi ajanın hangi worktree'de olduğunu ve branch'inin ne durumda olduğunu bilmek istersiniz. git worktree list ajanları bilmez; dizinleri bilir. Üzerine bir eşleme dosyası eklersiniz. Worktree başına bağımlılık kurulumlarının diskinizi ezmemesini istersiniz, bu yüzden cache mantığı eklersiniz. Bir ajanın çıktısının, diff'inin ve test sonuçlarının, kapanan bir terminalde sıkışmak yerine bir insanın inceleyebileceği bir yere düşmesini istersiniz. Artık bir sonuç toplayıcı yazıyorsunuz. İki ajanın kuyruktan aynı görevi kapmamasını istersiniz. Artık bir kilit yazıyorsunuz.

Bir noktada shell script'lerinden bir orkestrasyon katmanını yeniden yazmış olursunuz ve onu bakımda tutmak kimsenin işi değildir. vibe kanban alternatifi tartışmasının tam olarak yaşadığı dikiş bu ve ekiplerin ajan sayısı bir eşiği aştığında gerçek bir yönetim katmanına uzanmasının sebebi de bu. Zor kısım hiçbir zaman worktree değildi. Zor olan, birçok izole çalıştırmayı koordine etmek ve sonuçlarını tek bir yere geri getirmek.

Sharkly her Task'ı kendi worktree'sinde nasıl çalıştırır

Sharkly, hepsi bir arada bir Agent komuta ve yönetim platformudur. Claude Code'u, Codex'i ya da ajanlarınızın hâlihazırda kullandığı diğer yürütme araçlarını değiştirmez; onların etrafına paylaşılan Task, Computer, context ve inceleme katmanını ekler. Worktree izolasyonu bu katmanın içine gömülüdür, böylece elle yazmayı bırakırsınız.

Mekanizma doğrudan. Her Task izole bir dizin alır. Depo destekli işlerde Sharkly, cache'lenmiş depo verisinden her çalıştırma için yepyeni bir worktree hazırlar; böylece birkaç Task, tek bir paylaşılan checkout'a hiç yazmadan aynı kaynak üzerinde çalışabilir. git worktree add çalıştırmazsınız. Bir adlandırma şeması, bir temizlik işi ya da bir eşleme dosyası yazmazsınız. Bir Task atarsınız ve izolasyon zaten oradadır.

Her şeyi sakinleştiren şey bu sorumluluklar ayrımı. Agent, işin nasıl ele alınacağını tanımlar. Computer, host'u ve yerel kaynakları sağlar. Runtime, gerçek ajan oturumunu yürütür. Task, ekibin paylaşılan kaydı olarak kalır. Her çalıştırma kendi worktree'sinde olduğu için frontend, backend, bir hata düzeltmesi ve yeni test kapsamı, birbirlerinin üzerine basmadan aynı anda ilerleyebilir; elle yapılan yaklaşımın peşinde olduğu paralellik tam olarak budur.

Ve sonuçların gidecek bir yeri var. Yürütme, engeller, sonuçlar ve takip tartışmaları Task zaman çizelgesine döner. Bir ajanın diff'inin, kontrol etmeyi hatırlamanız gereken bir terminalde yaşaması yerine değişiklik özeti, doğrulama çıktısı ve bilinen sınırlar Task'a geri döner; burada bir kişi onları kabul eder, değişiklik ister ya da merge kararını verir. Context, ilerleme, engeller, sonuçlar ve insan incelemesi, özel prompt'lara ve terminal oturumlarına bölünmek yerine tek bir paylaşılan yerde, talepten sürüme kadar görünür kalır. Bu modele yeniyseniz, ilk Task'ınızı bir yapay zeka kodlama ajanına atamak en kısa giriş yoludur.

Hâlihazırda kullandığınız araçları korursunuz. Model kullanımı, o araçlarda yapılandırılmış abonelikler ya da API anahtarları üzerinden devam eder; Sharkly bunların etrafına izolasyon, koordinasyon ve incelemeyi ekler.

Elle yönetilen worktree'ler ile yönetim katmanı

İki yaklaşım da aynı primitifi kullanır. Fark, operasyonel yükü kimin taşıdığıdır.

Tek bir geliştirici olarak bir ya da iki ajan çalıştırıyorsanız ve shell üzerinde tam kontrole sahip olmak istiyorsanız elle worktree kullanın. Bu kurulum gerçekten sorunsuzdur ve öğrenmeye değerdir, çünkü mekanik size üstteki herhangi bir katmanın ne yaptığını öğretir. Sayı arttığında, işi birden fazla kişinin görmesi gerektiğinde ya da kapalı bir terminalde bir ajanın sonuçlarını kaybetmek size gerçekten bir şeye mal olduğunda bir yönetim katmanı kullanın. Bu, AI ajan orkestrasyonu rehberimizdeki dürüst karar kuralını yansıtıyor: paralel çalışma gerçek olana kadar koordinasyon makinesi eklemeyin ve gerçek olduktan sonra da onu elle yazmaya devam etmeyin.

İnsan-ajan sözleşmesi hâlâ geçerli

İzolasyon, işin nerede yapıldığını değiştirir, kimin karar verdiğini değil. Worktree'ler ajanların çakışma olmadan paralel olarak araştırmasını, yürütmesini, test etmesini ve raporlamasını sağlar. Yönü hâlâ insanlar belirler, yetkiyi insanlar verir ve sonucu insanlar kabul eder. Otomasyon, ekip muhakemesinin gerektiği yerde durur. Ajan başına yeni bir worktree, bu sınırı uygulanabilir kılan şeydir: her ajanın işi, paylaşılan bir checkout'a karışmış izlenemez bir düzenleme olarak değil, kendi branch'inde ayrı ve incelenebilir bir değişiklik olarak gelir. Kaosu değil, branch'leri incelersiniz. Bu değişimin günlük hayatta ne anlama geldiğine dair daha geniş bir resim için agentic coding açıklamamız bağlamı kuruyor, What is Sharkly ise platformu baştan sona ele alıyor.

Elle worktree kullanımı için birkaç kanıtlanmış yaklaşım

Şimdilik elle devam edecekseniz, bu alışkanlıklar sıkıntının çoğunu önler:

• Worktree dizinlerini sırayla değil, branch'e ya da göreve göre adlandırın. myproject-auth-refactor ne olduğunu söyler; myproject-wt3 söylemez.
• Worktree'leri ana checkout'un içine iç içe değil, kardeş dizinler olarak konumlandırın. İç içe yerleştirme, ağacı gezen araçları şaşırtır ve ignore kurallarınızı şişirir.
• Worktree başına kurulumu, ajanın ilk çalıştırdığı tek bir script olarak otomatikleştirin; böylece yeni bir worktree eksik kurulum yüzünden başarısız olmak yerine tek adımda çalıştırılabilir hale gelir.
• Canınız istediğinde değil, bir programa göre prune edin. Günlük bir git worktree prune ve git worktree list incelemesi, hayalet kayıtları azaltır.
• ~/.claude/worktrees gibi iç içe bir runtime cache'ini kendi script'lerinizden asla silmeyin. Ona runtime sahip olsun.
• Kaldırmadan önce commit edin ya da stash'leyin. --force, emin olduğunuz anlar için vardır, varsayılan olarak değil.

Sonuç

Git worktree'ler, paralel yapay zeka kodlama ajanlarını güvenli kılan izolasyon primitifidir. Akılda tutmaya değer temel fikirler şunlar:

• Bir checkout'un bir branch'i, bir index'i, bir HEAD'i vardır ve aynı anda iki ajanı barındıramaz.
• Bir worktree, aynı paylaşılan tarihçe üzerine ikinci bir çalışma dizini ekler; böylece her ajan kendi branch'ini ve dosyalarını alır.
• Beş komut (add, list, remove, prune ve gerçekten istediğinizde --force) basittir.
• Büyüyen şey operasyonel maliyettir (worktree başına kurulumlar, disk, temizlik, koordinasyon, sonuç toplama).
• Elle worktree'ler bir ya da iki ajan için doğrudur; sayı ve risk arttıkça bir yönetim katmanı yerini hak eder.
• Sharkly her Task için otomatik olarak yepyeni bir worktree hazırlar ve her sonucu insan incelemesi için Task'a geri döndürür.

Önce elle komutları öğrenin; size üstteki herhangi bir katmanın ne yaptığını öğretirler. Defter tutma, işin kendisinden daha pahalıya gelmeye başladığında Sharkly worktree'yi, koordinasyonu ve incelemeyi sırtınızdan alır. Bir Computer bağlayın, bir Agent oluşturun ve ona sıkıcı bir iş verin.

SSS

Basitçe anlatmak gerekirse git worktree nedir? Aynı depoya bağlı, kendi checkout edilmiş branch'i ve kendi staged/unstaged değişiklikleri olan ikinci bir çalışma dizinidir. Ana checkout ile tek bir commit tarihçesini paylaşır, dolayısıyla bir clone'dan çok daha hafiftir. Yapay zeka ajanları açısından bu, her ajanın başkasının dosyalarına dokunmadan çalışabileceği özel bir alan bulması anlamına gelir.

Yapay zeka kodlama ajanları neden worktree'ye ihtiyaç duyar? Çünkü tek bir checkout'u paylaşan iki ajan birbirlerinin dosyalarının üzerine yazar ve birbirlerinin branch'ini değiştirir. Ajan başına bir worktree, çakışmaları durumu sessizce bozdukları düzenleme ortasından, görünür ve incelenebilir oldukları merge zamanına taşır. Tam paralel kurulum için birden fazla Claude Code ajanını paralel çalıştırma rehberimize bakın.

Worktree ile clone aynı şey mi? Hayır. Bir clone, tüm nesne veritabanını ayrı bir depoya kopyalar. Bir worktree ise tek bir nesne veritabanını paylaşır ve yalnızca yeni bir çalışma dizini ile branch checkout'u ekler. Herhangi bir worktree'de yapılan commit'ler hepsinden anında görünür ve disk kullanımı çok daha düşüktür.

İki worktree aynı branch'i checkout edebilir mi? Hayır. Git, aynı branch'e yapılan çakışan yazmalardan sizi korumak için bir branch'in aynı anda iki worktree'de checkout edilmesini reddeder. İki ajan da o branch'i temel olarak kullanmak istiyorsa, biri ondan yeni bir branch oluşturmak zorundadır.

Worktree'leri güvenli bir şekilde nasıl temizlerim? Önce yapılan işi commit edin ya da stash'leyin, ardından git worktree remove <path> komutunu çalıştırın. Bir worktree dizinini elle sildiyseniz, bayat metadata'yı temizlemek için git worktree prune çalıştırın. Temizlik script'lerini ~/.claude/worktrees gibi bir runtime'ın kendi cache'ine asla yöneltmeyin.

Worktree'leri elle yönetmeyi ne zaman bırakmalıyım? Birkaç ajanın üzerinde koordinasyon yapıyorsanız, işi birden fazla kişinin görmesi gerekiyorsa ya da kapalı bir terminalde kaybolan bir sonuç size zaman kaybettirdiyse. O noktada her çalıştırmayı izole eden ve takip eden bir yönetim katmanı kendi maliyetini çıkarır. AI ajan orkestrasyonu rehberimiz bu geçişin ne zaman yapılacağını ele alıyor.