Claude · Gelişmiş · 203 Ölçekle ve otomatikleştir · Konu 5 / 7
4.10 Worktree ve paralel iş
Aynı anda iki iş yürüt, birbirinin dosyasını bozmasın.
Bu sayfada ne öğreneceksin
- Aynı depoda iki Claude oturumunu
claude --worktreeile ayrı kopyalarda çalıştırmayı - Paralel çalışmanın yollarını (subagent, agent view, agent teams) ve hangisini ne zaman seçeceğini
- Dosya çakışması riskini ve temizlik sırasında işini kaybetmemenin yolunu
Kısaca
Aynı klasörde iki Claude oturumu açıp ikisine de dosya düzenlettirirsen birbirinin değişikliğini ezebilirler. Çözüm, her oturuma kendi dosya kopyasını vermek. Git'in bunun için bir özelliği var: worktree (çalışma ağacı). Resmî dokümana göre worktree, ana klasörle aynı depo geçmişini ve uzak adresi paylaşan ama kendi dosyaları ve kendi dalı olan ayrı bir çalışma klasörüdür. Her oturum kendi worktree'sinde çalışınca biri yeni özellik yazarken öteki hata düzeltebilir. Git tarafını 3.10'da görmüştün.
Doküman worktree'nin paralel çalışmanın tek yolu olmadığını da söylüyor. Claude Code'da aynı anda birden çok iş yürütmenin beş yolu sayılıyor: subagent'lar, agent view, agent teams, dinamik workflow'lar ve projeler. Worktree'ler bunlardan biri değil; dosya düzenlemelerini yalıtan destek aracı. Subagent'ları 4.2'de görmüştün.
Bu sayfada yalnız dokümanda anlatılan yolları ve işine en çok yarayacak olanları göreceksin. Birkaç oturumu aynı anda çalıştırmanın kullanım maliyetini çarpacağını doküman açıkça yazıyor; sayıları ve limitleri Costs sayfasından kontrol et.
Adım adım
- Projeyi git deposu olarak aç. Worktree'ler git gerektirir. İlk kez çalıştırıyorsan önce o klasörde bir kez
claudeyazıp güven (trust) iletişim kutusunu kabul et; yoksa--worktreehata verip çıkar. - Worktree'de bir oturum başlat. Dokümana göre
--worktree(kısaca-w) bir ad ile yalıtılmış bir worktree oluşturur ve Claude'u içinde başlatır. Varsayılan konum depo kökündeki.claude/worktrees/<ad>/, dal adıworktree-<ad>:
Ad vermezsen Claude kendisi bir ad üretir (dokümandaki örnek:claude --worktree feature-authbright-running-fox). - İkinci işi başka terminalde, başka adla başlat. Aynı komutu farklı adla ikinci bir terminalde çalıştır; ikinci yalıtılmış oturum açılır.
Doküman, worktree içeriğinin ana klasörde izlenmeyen dosya gibi görünmemesi içinclaude --worktree bugfix-login.claude/worktrees/satırını.gitignore'a eklemeni öneriyor. - Ortamı hazırla. Worktree temiz bir kopyadır. Doküman, bağımlılıkları kurmayı Claude'a söylemeni ya da proje kurulumunu worktree klasöründe kendin çalıştırmanı söylüyor.
.envgibi git'in izlemediği dosyaları her yeni worktree'ye otomatik kopyalamak için proje köküne.worktreeincludedosyası koy (.gitignoresözdizimiyle). Yalnız hem eşleşen hem de gitignore'daki dosyalar kopyalanır. Örnek içerik:.env .env.local - Oturum içinden de isteyebilirsin. Oturumda Claude'a "bir worktree'de çalış" dersen
EnterWorktreearacıyla bir tane oluşturur. Bir işi subagent'lara paylaştırıyorsan "agent'ların için worktree kullan" demen yeter; kalıcı yapmak için özel subagent dosyasının üst bilgisineisolation: worktreeyazılır. Her subagent geçici bir worktree alır; değişiklik yapmadan biterse Claude Code onu kendiliğinden siler. - Çıkarken ne olduğunu bil. Oturumdan çıkınca Claude Code worktree'de kaybolacak iş olup olmadığına bakar. Temizse ve oturumun adı yoksa worktree ve dalı silinir (adlı oturumda önce sorar). İş varsa tut ya da sil diye sorar; silmek klasörü, dalı ve içindeki tüm işi siler. Tutarsan sonra dönmek için Claude Code'un çıkışta yazdığı
claude --worktree <ad> --resumekomutunu kullanırsın.-pile çalıştırdığın etkileşimsiz oturumlarda çıkış sorusu yoktur ve worktree otomatik temizlenmez. - Gerekirse worktree'yi git ile kendin yönet. Belirli bir mevcut daldan başlamak ya da klasörü depo dışına koymak için doküman şu komutları veriyor (dal ve yol adları kurgusal):
git worktree add ../project-feature-a -b feature-agit worktree listgit worktree remove ../project-feature-a - Çok oturumu tek ekrandan yönet (agent view). Terminalde
claude agentsyazarsan tüm arka plan oturumların tek ekranda listelenir: hangisi çalışıyor, hangisi senden girdi bekliyor, hangisi bitti. Alttaki kutuya bir görev yazıpEnter'a basınca yeni bir arka plan oturumu başlar; her yeni istem ayrı bir oturumdur. Bir satırdaSpaceson çıktıyı (peek) gösterir ve yanıt yazabilirsin;Enterya da→oturuma girer, boş istemde←tabloya döndürür. Açık bir oturumu arka plana almak için içinde/bgyazarsın. Agent view araştırma önizlemesindedir (research preview); arayüz ve kısayollar değişebilir. Agent view'dan başlattığın oturum, git deposundaysa, dosya düzenlemeden önce kendiliğinden.claude/worktrees/altında yalıtılmış bir worktree'ye geçer (dokümandaki istisnalar var, örneğin zaten bir worktree'nin içindeysen geçmez).
Hangisini ne zaman seçmeli
Doküman beş yolu şöyle karşılaştırıyor (özetledim):
| Yol | Ne verir | Ne zaman |
|---|---|---|
| Subagent'lar | Tek oturumun içinde, kendi bağlamında yan iş yapıp özet döndüren yardımcılar | Yan iş ana konuşmanı arama sonuçları ve log'larla doldururdu |
Agent view (claude agents) | Arka plan oturumlarını tek ekrandan başlat ve izle. Araştırma önizlemesi | Birbirinden bağımsız birkaç görev var, devredip arada bakmak istiyorsun |
| Agent teams | Ortak görev listesi ve mesajlaşmayla birlikte çalışan oturumlar, bir lider yönetir. Deneysel, varsayılan olarak kapalı | Claude'un bir projeyi parçalara bölüp dağıtmasını ve çalışanları eşgüdümde tutmasını istiyorsun |
| Dinamik workflow'lar | Çok sayıda subagent çalıştıran ve sonuçları çapraz doğrulayan bir betik | İş birkaç subagent'ı aşıyor (ör. kod tabanı genelinde denetim) |
| Projeler | claude.ai/code ya da masaüstü uygulamasında tek sohbetten başlayan paralel oturumlar (Pro, Max ve Ultra planlarında genel beta) | İş günlerce sürüyor ve makinen kapalıyken de ilerlemeli |
Agent teams'i kullanmak istersen dokümana göre CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 ayarı gerekir; bu ayar olmadan takım kurulmaz. Dokümanın tavsiyesi, önce daha hafif bir seçeneğin işi görüp görmediğine bakmak: subagent'lar tek oturumda çalışır, oturum arası mesajlaşma ise kendi çalıştırdığın oturumlar arasında bulgu taşır.
Oturumlar arası mesajlaşmada Claude, açık oturumlarını listeleyip birine mesaj gönderebilir. Dokümanın örneği: iki oturum aynı depoda ayrı worktree'lerde çalışıyorsa biri değişikliğini öbürüne bildirebilir. Mesaj yalnız yazılı bir metindir; konuşma geçmişi ya da dosya taşımaz.
Çalışan işi nereden göreceğin de farklı: arka plan oturumları için claude agents, o anki oturumun arka planındakiler için /tasks, workflow'lar için /workflows. Doküman, oturum içindeki /agents komutunun claude agents ile adı benzer olsa da ayrı bir şey olduğunu özellikle belirtiyor.
Çakışma riski ve yapılacaklar
- Aynı dosyalara dokunan işler için worktree kullan. Doküman bu durumda worktree ile yalıtmayı öneriyor. Agent teams çalışanları worktree'lerde yalıtmaz; orada işi öyle böl ki her çalışan farklı dosya setinin sahibi olsun.
- Worktree her şeyi yalıtmaz. Dokümana göre worktree ana klasörle
.gitdizinini, proje kapsamında kurulu plugin'leri ve "Evet, bir daha sorma" ile verdiğin Bash izin kurallarını paylaşır. Yani bir worktree'de verdiğin izin ana klasörde ve depodaki diğer tüm worktree'lerde de geçer. - Yalıtım kontrolü sınırlıdır. Claude Code, worktree'deki oturumun ana klasöre düzenleme yapmasını ve git'i ana klasöre yönlendirmesini engeller. Ama doküman, bu kontrollerin bir kabuk komutunun hangi dosyaları yazdığını izlemediğini söylüyor: örneğin
cpya da yönlendirmeyle ana klasöre yazan bir komut bu kontrollere takılmaz, yalnız normal izin ve sandbox kurallarına tabidir. - Git deposu değilse yalıtım yok. Doküman, git dışındaki klasörlerde agent view oturumlarının doğrudan çalışma klasörüne yazdığını ve birbirinden yalıtılmadığını, bu yüzden aynı dosyaları düzenleyen paralel oturumlardan kaçınmayı söylüyor. SVN, Perforce, Mercurial gibi sistemler için
WorktreeCreateveWorktreeRemovehook'ları var (hook'lar için 4.4). - Yeni worktree varsayılan olarak uzaktaki varsayılan daldan başlar. Henüz göndermediğin commit'ler ya da üzerinde çalıştığın dal worktree'de olmaz. İstersen ayarlarda
worktree.baseRefdeğerini"head"yaparsın; o zaman worktree yerelHEAD'inden başlar. - Silmeden önce commit et. Agent view'da Claude'un oluşturduğu worktree, oturumu silince birlikte silinir. Dokümanın uyarısı: dosya düzenleyen bir oturumu silmeden önce değişiklikleri commit et.
Hazır prompt
Bir oturumun içindeyken işi yalıtmak için (köşeli parantezleri doldur):
Bu işi ayrı bir worktree'de yap: [görevi bir iki cümleyle anlat]. Bitince değişiklikleri commit et ve hangi dalda olduklarını söyle. Ana klasördeki dosyalara dokunma.
Üç bağımsız işi subagent'lara paylaştırmak için dokümandaki "agent'ların için worktree kullan" ifadesine dayanan istem:
Şu üç işi birbirinden bağımsız subagent'larla yap ve agent'ların için worktree kullan: 1) [birinci iş], 2) [ikinci iş], 3) [üçüncü iş]. Her biri bitince ne değiştirdiğini ve testlerin sonucunu özetle. İki iş aynı dosyaya dokunacaksa bana önce haber ver.
Claude yanılabilir. Bitince git worktree list ve git status ile gerçekten ne olduğuna kendin bak.
Sık yapılan hata
- İki oturumu aynı klasörde açıp ikisine de düzenleme yaptırmak. Biri öbürünün değişikliğini ezebilir. Her oturuma ayrı ad ile
claude --worktreever. - Çıkışta "sil"i körü körüne seçmek. Silmek worktree klasörünü ve dalını, içindeki işle birlikte kaldırır. İş değerliyse tut ya da önce commit et.
- Worktree'de
.envyok diye şaşırmak. Worktree temiz bir kopyadır..worktreeincludeekle ya da bağımlılıkları ve ayar dosyalarını worktree'de hazırla. - Agent view'u bitmiş ürün sanmak. Araştırma önizlemesi; arayüz ve kısayollar değişebilir. Çok sayıda oturumu aynı anda açmak kullanımını da çarpar.
- Hook'ta
${CLAUDE_PROJECT_DIR}worktree'yi gösterir sanmak. Claude oturum içinde bir worktree'ye girdikten sonra bile bu değişken oturumun başladığı proje kökünü gösterir; worktree yolu hook'a giden girdi JSON'ununcwdalanıyla gelir. Hook yazarken bunu bil.
Video
Video: yakında.
Kaynak
- Claude Code dokümanı: Run parallel sessions with worktrees (
--worktree, temizlik,.worktreeinclude, subagent yalıtımı, paylaşılanlar, git dışı sistemler) - Claude Code dokümanı: Run agents in parallel (beş yolun karşılaştırması, çalışan işi izleme)
- Claude Code dokümanı: Manage multiple agents with agent view (
claude agents, peek,/bg, yalıtım, sınırlamalar; araştırma önizlemesi) - Claude Code dokümanı: Orchestrate teams of Claude Code sessions (deneysel, varsayılan kapalı)
- Claude Code dokümanı: Message your other Claude Code sessions (oturumlar arası mesajlaşma)
- Claude Code dokümanı: Desktop application (masaüstü uygulamasında paralel oturumlar ve Worktree seçeneği, 4.11'de ayrıntı)
Son doğrulama: 2026-11-12