Çalışmayı birden fazla uygulayıcı arasında bölme

Küçük bir alışveriş listesi uygulamanız var ve iki özelliğe ihtiyaç duyuyor: öğe filtresi ve listenin CSV olarak dışa aktarılması. Görevler birbirine pek bağlı değil; insanın aklına hemen şu geliyor: işi ikiye bölelim, iki parçayı da bir saat yerine yarım saatte bitirelim. Bir uygulayıcı filtreyi, diğeri dışa aktarmayı üstleniyor; değişiklikler karışmasın diye her birine ayrı bir çalışma klasörü veriliyor. İki parçanın listedeki bir öğeyi nasıl yorumlayacağı ise önceden konuşulmamış. Kendiliğinden anlaşılır sanılmış.

Yarım saat sonra iki parça da hazır. Her birinin kendi kontrolleri başarılı, birleştirme tek bir çatışma bile çıkarmadan tamamlanmış. Ama uçtan uca senaryo çalışmıyor: ekranda filtre üç satır gösterirken dışa aktarılan dosyadaki sütun boş. Nedeni pek heyecan verici değil. Uygulayıcılardan biri bu arada, daha okunaklı olduğunu düşündüğü için completed alanını done olarak yeniden adlandırmış, diğeri de bunu bilmiyormuş.

Ayrı klasörler dosyaları ayırdı, ama kararları ortaklaştırmadı. Konuyu üç adımda ele alalım: önce işi bölmeye gerçekten değip değmediğine karar vereceğiz, sonra değişiklik alanlarını ve ortak anlaşmaları paylaştıracağız, son olarak da böyle bir sürpriz sona kadar taşınmasın diye birleştirilen sonucu kontrol edeceğiz.

Bağımlılıkları kontrol edin

İşi bölmek için genellikle iki neden vardır. İlki, farklı alanlarda birbirinden bağımsız araştırmadır: listenin nasıl gösterildiğini ve dışa aktarımın nasıl oluşturulduğunu aynı anda bulmak. İkincisi, sınırları ve doğrulanabilir sonuçları belli parçalar üzerinde eş zamanlı çalışmaktır. "Burada plan, burada uygulama, burada kontrol" diye ayırmak tek başına üç katılımcı gerektirmez; bir oturum bunları sırayla yapabilir. Küçük bir görev için tek uygulayıcıyla başlamak mantıklıdır.

Bölmek için bir neden varsa, sıradaki soru şudur: A'nın sonucu henüz belli değilken B'nin işinin hangi kısmı ilerleyebilir? B tamamen A'ya bağlıysa, bu adımlar sırayla yürür. B bazen bağımsız bir kısmı önceden hazırlayabilir; yine de sonuçları birleştirmek için A'yı beklemek gerekir.

Aynı alışveriş listesi örneğinden üç durum:

Üçüncü satır en sık karşılaşılan tuzaktır. Filtre src/filter.js dosyasında, dışa aktarım da src/export-csv.js dosyasında olduğuna göre parçalar bağımsızmış gibi görünür: sonuçta dosyalar farklı. Ama ikisi de aynı öğeyi ve aynı completed alanını okur. Makalenin başındaki senaryo tam da bu yüzden bozuldu; farklı dosyalar işe yaramadı. Bağımsızlık, kodun kaç dosyada bulunduğuyla değil, davranış ve ortak anlaşmalarla ilgilidir.

Parçalara ayırma işini, uygulayıcıları başlatmadan, ajana verebilirsiniz:

Görevi parçalara ayır. Her parça için girdileri, sonucu,
bağımlılıkları ve nasıl doğrulanacağını belirt. Hangi parçaların şimdi başlayabileceğini işaretle.
Henüz hiçbir uygulayıcıyı başlatma.

Böyle bir yanıtı başlamadan önce kontrol edebilirsiniz. Çözülmemiş bağımlılığı olmayan parçalar aynı anda başlamak için adaydır. Bağımlılıklar sütunu boşsa bunu projeyle karşılaştırın: ajan ortak bir modeli ya da ayarı gözden kaçırmış olabilir.

Ortak sonuca ulaşma süresini hesaplayın

Hızlanma genellikle tek bir sayıyla ölçülür: işin kendisi ne kadar sürdü? Oysa hesaplamanız gereken, kabul edilen ortak sonuca ulaşma süresidir. İşin yanı sıra her uygulayıcı için görev tanımı hazırlama, her birinin projeyi yeniden okuması, bekleme, iki sonucu kontrol etme ve tek bir sonuçta birleştirme de buna dahildir.

Örneğimiz için yaklaşık bir hesap. Sayılar yalnızca hesabı göstermek için seçildi, performans ölçümü değildir:

Görevin genel hazırlığı her iki seçenekte de gerektiğinden hesaplamaya dahil değil. Tek bir parçanın yeniden yapılması on dakikalık kazancı siler; birleştirme ne kadar zahmetliyse eş zamanlı çalışmanın da o kadar çok zaman kazandırması gerekir.

Zamanın yanı sıra, unutulması kolay iki maliyet daha vardır. Her ek uygulayıcı projeyi baştan okur ve bu kaynak harcar; ayrıca geri dönen ayrıntılı özetler ortak konuşmada yer kaplar. İkinci maliyet daha önemlidir: sizin dikkatiniz. İki sonucu da okumalı, karşılaştırmalı ve karar vermelisiniz. Gelenleri okumaya yetişemiyorsanız hız artık size ait değildir.

Az ek yükü olan, karşılaştırılabilir ve bağımsız iki parçayla neredeyse iki kat hızlanmak mümkündür. Ama uygulayıcı sayısı tek başına bunu vaat etmez.

Tekrar mı, çapraz kontrol mü?

Tekrar, raporlarda görünmez. İki uygulayıcı sessizce aynı dosyaları açar, ikisi de listedeki bir öğenin nasıl çalıştığını araştırır ve her biri dürüstçe kodu incelediğini yazar. Ama bazen ikinci bir inceleme bilerek yapılır: varsayım kritiktir ve ilk kişinin akıl yürütmesini görmemiş birinin bunu doğrulamasını istersiniz. Böyle bir çapraz kontrolü kazara tekrardan ayıran şey, kapsamının, nedeninin ve yanıtlar farklı çıkarsa ne yapacağınızın önceden belirlenmiş olmasıdır. Sonuncusu yoksa kontrol, fikir toplamaya dönüşür.

Şimdi tersini düşünelim. İki uygulayıcıya listedeki completed alanının ne anlama geldiği soruluyor. İkisi de aynı yanıtı veriyor: öğenin satın alındığını gösteren işaret. İki taraftan doğrulanmış gibi duruyor.

Oysa ikisi de bir yıl önce yazılmış aynı README.md satırını okumuş; kodda bu alanın anlamı çoktan değişmiş. Örtüşen, vardıkları sonuç değil, kaynaklarıydı.

Buradan birkaç işe yarar alışkanlık çıkıyor:

• yanıtın dayanağını göstermelerini isteyin: dosya, satır, kod parçası. Bir anlatım değil, sizin de açıp görebileceğiniz bir şey;
• ortak varsayımı ayrıca ve gerçek anlamda kontrol edin: kod ne yapıyor, senaryoda ne oluyor? Herkes hemfikir olsa bile.

Ayrı oturumlar hataların bağımsız olacağını garanti etmez: ortak kaynak, ortak hataya yol açar. Yanıtlar farklıysa oy saymak yerine dayanakları inceleyin; biri güncel koda, diğer ikisi eski bir nota bakıyor olabilir.

Alanın kodda doğrulanmış anlamı, başlamadan önce üzerinde anlaşılan ortak modelin temeli olur. Üç kontrolün ardından bölmek hâlâ kazançlı görünüyorsa, iş dağılımına geçin.

Her alan için bir sorumlu belirleyin

Eş zamanlı çalışma süresince geçerli kural basittir: her değişiklik alanının tek bir sorumlusu olur. "Bu dosyaya iki kişi birden dokunamaz" değil, "bu iki görev sürerken buraya şu kişi yazacak". Bu, projenin kalıcı bir özelliği değil, belirli bir süre için yapılan anlaşmadır.

Kuralın ikinci yarısı daha önemlidir ve daha sık unutulur. Ortak sonucun da bir sorumlusu olmalı: parçaları bir araya getirip bütünün hazır olup olmadığını söyleyecek kişi. Birleştirme işi kimseye verilmezse en son bitirene kalır; o kişi de diğer parçayı en az bilen kişidir.

Başlamadan önce projeye bakıp gereken parçaların bir şekilde ayrılmış olduğunu kontrol edin. Değillerse, sırf paralel çalışabilmek için büyük bir refactoring başlatmak gerekmez: günün en büyük işi o olur ve bölünecek bir şey kalmaz.

Alışveriş listemiz için dağılım şöyle:

Tablo, erişim haklarını değil değişiklik sorumluluğunu paylaştırır: ortak dosyaları ihtiyacı olan herkes okuyabilir.

package.json satırı keyfi olarak eklenmedi: npm install iki dosyayı birden değiştirir. Bu yüzden iki eş zamanlı kurulum gereksiz bir çatışma çıkarır; aynı kütüphanenin iki farklı sürümü de derlemede sürpriz yaratır. İki uygulayıcı da bir kütüphaneye ihtiyaç duyarsa, ne gerektiğini ve nedenini bildirir. Kararı bir kişi verir ve değişikliği bir kez yapar.

Başlamadan önce ortak model üzerinde anlaşın

Dosya sınırları, ortak bir anlaşma olmadan pek işe yaramaz. Filtre de dışa aktarım da aynı öğe modeline dayanır. Aşağıda arayüzlerinin taslağı var; çalıştırılabilir bir örnek değil, işlevlerin uygulamaları gösterilmiyor. Başlamadan önce öğelerin sırasını korumayı, özgün diziyi değiştirmemeyi ve CSV'de boolean değerleri true/false olarak yazmayı da kararlaştırdık. CSV kaçış kuralları aynı kalıyor.

// listedeki bir öğe: bu üç alan başlangıçtan önce kararlaştırılır ve yeniden adlandırılmaz
const item = { id: 41, title: "oat milk", completed: false };

// filter.js hazır bir öğe kümesi döndürür; biçimlendirme ya da dışa aktarma yapmaz
filterItems(items, mode);   // mode: "all", "active", "completed"

// export-csv.js önceden filtrelenmiş kümeyi alır ve kendi başına seçim yapmaz
exportCsv(items);           // id,title,completed sütunlarıyla bir CSV dizgesi döndürür

Buradaki anlaşmanın dosya adlarıyla değil, girdi ve çıktıyla ilgili olduğuna dikkat edin. "Dışa aktarım, önceden filtrelenmiş listeyi alır" önemsiz bir ayrıntı gibi görünebilir; oysa bu tek satır, öğeleri seçme sorumluluğunun ikisinden hangisinde olduğunu belirler. Bu anlaşma olmazsa ikisi de seçimi kendi tarafının yapacağını makul biçimde varsayabilir ve dosyaya ya her şey ya da iki kez filtrelenmiş öğeler gider.

Sonucun nasıl kabul edileceği konusunda da önceden anlaşılır. Örneğimizin uçtan uca senaryosu şöyle: 41 ve 43 numaralı öğelerde completed: true, 42 numaralı öğede false var. "completed" modu 41 ve 43'ü özgün sıralarında göstermeli; CSV'de de aynı iki öğe, id,title,completed başlığı ve son sütunda true değeriyle yer almalı. Senaryo iki parçadan birden geçer ve makalenin başındaki hatayı tam olarak yakalar.

Anlaşmanın kendisini değiştirmekle ilgili bir nokta daha var. Çalışma sırasında ortak biçimin değişmesi gerektiği anlaşılırsa, bu tek dosyada yapılacak küçük bir düzenleme değildir. Biçime bağlı tüm görevleri yeniden gözden geçirmek gerekir; çünkü tamamlanmış işlerin bir kısmı önceki sürüme dayanıyor olabilir.

Ayrı çalışma klasörleri (git worktree) anlaşmanın yerini tutmaz. Değişiklikleri fiziksel olarak ayırırlar ve bu yararlıdır: ortak bir klasörde kontrol, komşu görevin tamamlanmamış değişikliklerini de içerebilir ve hiçbir uygulayıcının tek başına kontrol etmediği bir durumu doğrulayabilir. Ama klasörler öğe biçimi üzerinde anlaşamaz; ayrıca bağlantı noktaları, yerel veritabanları ve diğer harici kaynaklar ortak kalır. İzlenmeyen .env dosyası ise yeni klasörde varsayılan olarak hiç yoktur: onu kopyalarlar, örneğin .worktreeinclude ile.

Herkese kısa bir görev verin

Görev tanımının uzun olması gerekmez. Genellikle şu yedi madde yeterlidir: amaç, hangi sürümden başlanacağı, kendi dosyaları, ortak anlaşmalar, doğrulanabilir sonuç, yanıtta ne döndürüleceği ve başka birinin alanına ihtiyaç duyulursa ne yapılacağı.

Amaç: liste filtresi tüm öğeleri, yalnızca tamamlanmamışları ya da yalnızca tamamlananları gösterir.
Şuradan başlayın: öğe modelinin kararlaştırıldığı ana daldaki son commit.
Dosyalarınız: src/filter.js ve tests/filter.test.js.
Ortak anlaşma: completed alanı boolean kalır, alan adlarını değiştirmeyiz;
filtre bir öğe dizisi döndürür ve hiçbir şeyi dışa aktarmaz.
Sonuç: filtre testleri geçer; üç öğelik bir kümede her mod
beklenen listeyi verir.
Yanıtta verin: gerçekten değiştirilen dosyaların listesi, test çalıştırma çıktısı,
testlerin çalıştırıldığı sürüm ve açık kalan sorular.
src/item-model.js veya src/app.js dosyasını değiştirmek gerekirse durun,
gereken değişikliği ve nedenini açıklayın, yanıtı bekleyin.

İkinci uygulayıcıya verilen görev de aynı şekilde düzenlenir: kendine ait bir dosya çifti, aynı öğe biçimi, doğrulanabilir bir sonuç ve sınır aşıldığında aynı adımlar. Burada tümünü baştan yazmaya gerek yok.

Şimdi yanıta gelelim. Gerçekten değiştirilen dosyaların listesi ve kontrollerin gerçek çıktısı yanıtta bulunmalı. "Başkalarının dosyalarına dokunulmadı" cümlesini yazmak kolaydır; siz bunu ne kadar ısrarla istediyseniz yanıtta görünme olasılığı da o kadar artar. İfadeye değil, değişiklik listesine bakın. Görev tanımındaki sınır bir anlaşmadır, yasak değil: istem metni ajanın dosyaya yazmasını engellemez; erişim izinleri ayrıca ayarlanır.

Kesişen alanı yeniden kararlaştırın

Er ya da geç biri başka bir uygulayıcının sınırına takılır. Uygulayıcı B, src/app.js dosyasını düzenlemeden dışa aktarımı bağlayacak bir yer olmadığını fark eder: dışa aktarma düğmesi hiçbir işlevi çağırmıyor.

İyi bir yanıt nedeni, gereken değişikliği ve bağımlılığı açıklar. src/app.js dosyasındaki bağlantı işi zaten birleştirme sorumlusuna verilmiştir; bu nedenle B kendi modülünü tamamlayıp bağlantı isteğini iletebilir. Ortak değişiklik olmadan kendi parçasına devam edemiyorsa, bağımlı iş duraklatılır.

Buradan sonra iki seçenek var. Birleştirme sorumlusu, kendi alanı olduğu için ortak dosyadaki değişikliği kendisi yapar. Ya da alanı açıkça uygulayıcı B'ye devreder; ancak önce önceki sorumlunun şu anda o dosyaya yazmadığından emin olur. Önceki sorumlu durdurulmadan yapılan devir, iş dağılımının önlemeye çalıştığı durumu aynen yaratır.

Yapılmaması gereken şey, uygulayıcıyı sınırın etrafından dolaşmaya zorlamaktır. "app.js dosyasına dokunma, başka bir yol bul" isteği genellikle başka birinin mantığının kendi dosyasına kopyalanmasına ya da sonradan kimsenin açıklayamayacağı ek bir katmana yol açar. Tablodaki sınıra biçimsel olarak uyulmuştur. ama gerçekte projede dışa aktarımın nasıl çalıştığına dair ikinci bir doğru oluşmuştur.

Yalnızca dosyaları değil, davranışı da birleştirin

Birleştirmeden önce sorumlu kişinin üç şeyi bilmesi gerekir: her parça hangi sürümden başladı, her uygulayıcı neyi hangi sürümde kontrol etti ve gerçekte hangi dosyalar değişti? Bunların hepsi görev yanıtlarında bulunmalı; dosya listesi de gerçek değişikliklerle karşılaştırılmalıdır.

Sonra parçalar birleştirilir. Sıradaki önemli iş, başlamadan önce üzerinde anlaşılan ortak senaryoyu çalıştırmaktır. Birbirinden çok farklı iki sorun buna engel olabilir.

Metin çatışması. Parçalar aynı bölümü farklı biçimlerde değiştirmiş, dosya silmiş ya da yeniden adlandırmıştır ve Git bunları otomatik birleştirememiştir. Çatışmayı çözdükten sonra ortaya çıkan davranışı kontrol edin.

Anlamsal uyumsuzluk. Aynı satıra iki kişi dokunmamıştır, metin sorunsuz birleşir ve çatışma mesajı çıkmaz. Alanı yeniden adlandırdığımız örnek tam da burada karşımıza çıkar: filtre done alanını okurken dışa aktarım completed alanını okur ve boş sonuç alır. İki parçanın kontrolleri de başarılı görünür; çünkü her biri kendi verisiyle kendi parçasını kontrol etmiştir.

Şemada alttaki oka bakın. Üst yarı, genellikle iş bölümü denen şeyi gösteriyor: kendi dosyalarındaki iki bağımsız parça. Hazır olup olmadığına dair sonuç ise bir kat aşağıda, iki parçadan birden geçen senaryoda ortaya çıkar. Bu ok geçilene kadar elinizde iki yerel sonuç vardır, ortak bir sonuç yoktur. Proje kuralları tüm kontrollerin yapılmasını gerektiriyorsa ortak senaryo bunların yerini tutmaz.

Ortak kararı kayda geçirin

Birleştirmeden sonra ortak sonuçtan sorumlu kişi sıradaki adımı seçer. Örneğin:

1. Ortak sonucu kabul edin: senaryo geçiyor, değişiklikler açıklanabiliyor, ölçütler karşılanmış.
2. Belirli bir parçayı düzeltmeye gönderin ve neyin neyle uyuşmadığını söyleyin. "Dışa aktarım biraz tuhaf" değil, "dışa aktarım artık modelde bulunmayan bir alanı okuyor".
3. İş bölümünü yeniden değerlendirin: uygulayıcı sayısını azaltın ya da parçaları sırayla çalıştırın.

Üçüncü seçenek başarısızlık değil, olağan bir sonuçtur. Düzeni yeniden düşünme zamanının geldiğini gösteren işaretler çabuk fark edilir:

• ortak öğe biçimi durmadan değişir ve her değişiklikten sonra iki parça da yeniden yapılır;
• uygulayıcılar birbirini bekler; demek ki bir bağımlılık vardı ama adı konmamıştı;
• sonuçlar, siz onları okuyamadan gelmeye devam eder.

Son işaret en rahatsız edici olanı, çünkü dışarıdan başarı gibi görünür. Ayrıca bir kez başarılı bölmek henüz bir kural sayılmaz: ajanın sonucu her çalıştırmada değişebilir, bu nedenle önemli bir çıkarımı benzer bir görevde yeniden sınamak gerekir.

Kısmi sonuç da olağan bir sonuçtur. Filtre tamamlanıp kontrol edilmişken dışa aktarım bitmemiş olabilir; bunu olduğu gibi kaydedin: iki parçadan biri. Genel görev yine açık kalır. Yarısı çalışıyor diye görevi kapalı sayamazsınız; ne kadar özenli dağıtırsanız dağıtın bu değişmez.

Kendinizi kontrol edin

İki durum var. Önce kendiniz yanıtlayın, sonra karşılaştırın.

Hatanın nedeni henüz bulunmadı.
Dışa aktarım bazen boş dosya üretiyor ve düzeltmeyi hemen iki kişiye vermek istiyorsunuz. Önce hatayı yeniden üretip araştırın. Farklı, doğrulanabilir varsayımlar ortaya çıkarsa bunları iki uygulayıcıya verebilirsiniz. Ancak dayanağı olmayan iki düzeltme önerisi görevi henüz çözmez: her biri nedene bağlanmalı ve ilk senaryoda kontrol edilmelidir.

Dosyalar farklı, ama aynı sayı.
Filtre ürün miktarını adet olarak sayıyor, dışa aktarım ise aynı miktarı paket olarak yazıyor. İki parçanın kontrolleri başarılı, ama ekrandaki ve dosyadaki sayılar uyuşmuyor. Bu bir kod hatası değil: parçalardan hiçbiri kendi sınırını ihlal etmedi. Ölçü birimi üzerinde anlaşma eksik. Bu, başlamadan önce ortak öğe modelinde kayda geçirilir; src/item-model.js dosyasını birleştirme sorumlusu değiştirir ve ortak senaryo yeniden çalıştırılır.

Claude Code bu işin neresini üstlenebilir?

Makalenin başında gösterildiği gibi, ajan iş bölümünün taslağını çıkarabilir ve verdiğiniz maddelerden tutarlı bir görev tanımı oluşturabilir. Karar yine sizde kalmak üzere üç alanda daha yararlı olabilir:

• Alanların taslak haritası. Projeyi inceleyip hangi görev parçasında hangi dosyaların değişebileceğini yollarıyla birlikte önermesini isteyin. Bu yalnızca bir taslaktır: her alanın sorumlusunu siz belirlersiniz.
• Birleştirme ve ortak çalıştırma. Ajan parçaları birleştirir, değişikliklerin tam listesini gösterir ve ortak senaryoyu çalıştırır. Ardından değişikliklerin tümünü kendiniz inceleyin.
• Tartışmalı nokta. İki kendinden emin açıklama, kararı kesinleştirmez. Dayanakları, dosyayı ve satırı isteyin. Ortak dosyayı kimin değiştireceğini, yanıtı kimin daha ikna edici sunduğu değil, önceden belirlenen tablo söyler.

Sonuçta her şey tek bir karara ve iki görevlendirmeye dayanır. Karar, işi bölmeye değip değmediğidir: her ek uygulayıcının katkısı, hazırlık, kontrol ve birleştirme maliyetini karşılamalıdır. Görevlendirmeler ise her değişiklik alanının ve ortak sonucun sorumlusudur. Alışveriş listesi örneğinde ikisi de eksikti: completed alanı üzerinde anlaşma yoktu, filtreyle dışa aktarımı birlikte çalıştıracak biri de belirlenmemişti. Araçlar işin mekanik kısmını üstlenebilir, ancak birleştirilen davranışın gerçekten istenen şey olup olmadığına insan karar verir.