Claude Code ile büyük ölçekli kod geçişlerini nasıl gerçekleştirdik

• Anthropic geliştiricileri, Claude Fable 5, Claude Opus 4.8 ve dinamik iş akışlarını kullanarak son bir ayda on binlerce ila yüz binlerce satır ölçeğinde 10 paketi taşıdı; tek tek kodları düzeltmek yerine kodu üreten yinelemeli süreci iyileştirdiler
• Bun’ın Zig→Rust geçişi 2 haftadan kısa sürede 1 milyon satır üretti ve birleştirme öncesinde mevcut testlerin %100’ünü geçti; Python→TypeScript projesi ise hafta sonu boyunca 165.000 satırı taşırken yüzlerce ajan, 8 aşamalı kapı ve 3 kez karşıt inceleme kullandı
• Büyük ölçekli geçişler; işlerin paralelleştirilebilmesi, mevcut kodun şartname ve doğru cevap rolü görmesi, derleme·test hatalarının otomatik olarak sonraki iş kuyruğunu üretmesi sayesinde nesnel bir doğrulama döngüsü kurmaya elverişlidir
• Değerlendirme ölçütlerini hazırlamaktan kural kitabı·bağımlılık haritası·fark listesi yazmaya, kural stres testine, tam çeviriye, derlemeye, çalıştırmaya ve davranış karşılaştırmasına kadar aşamalı ilerlenir; tekrarlayan hatalar dosya dosya düzeltilmez, üst düzey kurallar düzeltilip yeniden üretilir
• Maliyet hâlâ on binlerce ila yüz binlerce doların üzerindedir; ancak başarısız dallar atılıp yeniden denenebilir. Bun geçişi API fiyatlarına göre yaklaşık 165.000 dolar harcadıktan sonra bellek kullanımında düşüş, ikili dosya boyutunda %19 küçülme ve gerçek iş yüklerinde %2–5 performans artışı elde etti

---

Kodu değil, üretim döngüsünü iyileştirme yaklaşımı

• Yapay zeka kod geçişi, ajanların üretim kod tabanını yeni bir dile veya framework’e taşımasıdır
  • Mühendisler dosyaları doğrudan çevirmek yerine geçiş kuralları ve doğrulama döngüleri yazar
  • Ajan, yeni kodun davranışı kaynakla eşleşene kadar çeviri·derleme·test döngüsünü tekrarlar
  • Geçmişte yıllar süren projeleri haftalar düzeyine indirebilir
• Anthropic’te Claude Fable 5, Claude Opus 4.8 ve dinamik iş akışları kullanılarak bir ay içinde on binlerce ila yüz binlerce satırlık 10 kod paketi taşındı
• Temel operasyon ilkesi, üretilen kodu doğrudan onarmak değil o kodu oluşturan döngüyü düzeltmektir

Gerçek geçiş örnekleri

• Bun’ın Zig→Rust geçişi

  • Jarred Sumner, Claude Code ile Bun’ı Zig’den Rust’a taşıdı
  • 2 haftadan kısa sürede 1 milyon satır kod üretti
  • Birleştirme öncesi CI’da Bun’ın mevcut test paketinin %100’ünü geçti
  • Birleştirme sonrası bulunan 19 regresyonun tamamı düzeltildi
  • Rust portu haziranda Claude Code’a dahil edildi
  • Bun’ın aylık indirme sayısı 10 milyonu aşıyor ve Claude Code içinde de yaygın olarak kullanılıyor

• Python→TypeScript geçişi

  • Mike Krieger, hafta sonu boyunca Python kod tabanını 165.000 satırlık TypeScripte taşıdı
  • Yüzlerce ajan, 8 aşamalı kapı ve 3 karşıt inceleme kullandı
  • Tüm komutların çıktısını Python kaynağıyla karşılaştıran nihai eşdeğerlik kontrolü yaptı
  • Tüm geçiş sonucunu atıp kuralları ve iş akışını düzeltme sürecini tekrarladı; üçüncü çalıştırmanın sonucunu benimsedi

Dil geçişini yeniden değerlendirme koşulları

• İlk geliştirmeden sonra teknoloji ortamı değiştiyse, eski ödünler kısıta dönüştüyse, daha iyi yaklaşımlar ortaya çıktıysa veya asıl ekosistem küçüldüyse geçiş değerlendirilebilir
• Zig, C düzeyinde performans ve sadelik sunduğu için Bun’ın tek kişiyle geliştirildiği ilk dönemlere uygundu; ancak bu sadeliğin bilinen ödünleri vardı
• Geçmişte dil geçişi için yol haritasını durdurmak ve birkaç çeyreklik kaynak ayırmak gerekirdi
  • İki kod tabanını birkaç çeyrek veya yıllarca paralel sürdürmek gerekebilirdi
  • Nihai davranış eşleşmesi %90’da kalırsa başlangıçtan daha büyük bir bakım sorunu doğabilirdi
  • Artık başarısız bir dalı silip yeniden çalıştırma seçeneği var
• 1 milyon satırlık geçiş artık 4 yıllık mühendislik maliyeti olarak 3–4 milyon dolar gerektirmese de hâlâ on binlerce ila yüz binlerce doların üzerine çıkabilir
  • Bun geçişi önbelleğe alınmamış 5,9 milyar giriş token’ı ve 690 milyon çıkış token’ı tüketti
  • API fiyatlarına göre maliyet yaklaşık 165.000 dolardı
  • Mike’ın portunda çekirdek bölüm 27 milyon token kullandı
• Geçişin iş gerekçesinin artık şirketin varlığını belirleyecek kadar kritik olması gerekmiyor; bir yıl boyunca tekrarlanan bellek hatası düzeltmeleri veya kronik tek bir darboğaz bile yeterli olabilir

• Python build darboğazını çözme

  • Mike’ın dahili aracı kullanıcılara tek bir ikili dosya olarak sunuluyordu; ancak Python araç zinciriyle platform başına ikili dosya üretmek yaklaşık 8 dakika sürüyordu
  • Tüm build matrisi için her release’te yaklaşık 30 dakika beklemek gerekiyordu
  • TypeScript geçişinden sonra derleme yaklaşık 2 saniyeye indi, ikili dosya başlangıcı 6 kat hızlandı ve ayrı dağıtım pipeline’ı da kaldırıldı

Yapay zeka ajanlarının geçişe uygun olma nedenleri

• Paralel çalışma mümkündür
  • Dosyalar ve crate’ler gibi binlerce bağımsız birime bölünüp birden çok ajan tarafından aynı anda işlenebilir
• Mevcut kod açık ve kapsamlı bir şartname rolü görür
  • Çeviri ajanları için talimat oluştururken temel referans olarak da kullanılabilir
• Test paketi yerleşik bir hakem rolü oynar
  • Doğrulama nesnelse, insanın kaliteyi sürekli arabuluculuk etmesine gerek kalmadan model doğru cevaba göre günlerce yineleme yapabilir
• Derleme veya test hataları otomatik olarak sonraki iş kalemi hâline geldiği için ayrı bir iş kuyruğu yazma ihtiyacı azalır
• Tutarlılık ve istisna işleme döngüye dahil edilebilir
  • İnceleyen kişi her sorunu ihlal edilen kuralla ilişkilendirir
  • İstisnanın nasıl çözüldüğü, daha sonra tüm ajanların izlediği kurala dönüşür
  • Sessiz davranış uyuşmazlıkları yerine kural ihlalleri açık iş kalemleri olur
• Fable ve Opus 4.8, alt ajanların paralel çalışmalarını devretmek·yönetmek·doğrulamak ve hedefe ulaşacak birden çok yol bulmak için kullanıldı
• Birden çok model sınıfını birleştiren danışma deseni ile token kullanımı optimize edildi

Ön koşul: Kaynak ve portu eşdeğer değerlendirme

• Geçişe başlamadan önce kaynak ve hedef kodu aynı ölçüte göre değerlendirecek güçlü bir hakem gerekir
  • Hakem yoksa başarı ölçütü ve bitiş koşulu da yoktur
  • Kaynak dilin iç fonksiyonlarına dayanan testler hedef kodda aynen çalışmayabilir
• Mevcut testler, dış çağrılarla ifade edilebilen testler ve porta taşınmayacak iç uygulama bağımlı testler olarak sınıflandırılır
• Dış davranış testleri, hem kaynakta hem portta çalıştırılabilecek assertion’lar olarak yeniden yazılır
  • Karşıt bir ajan, yeniden yazım sırasında assertion’ların zayıflamadığını doğrular
• Hakemin kaynak kodda çalışıp başarılı olduğu doğrulandıktan sonra, kasıtlı olarak bozulan kodda başarısız olup olmadığı da kontrol edilir
• Jarred’ın üçüncü bir dil olan TypeScript ile yazılmış büyük bir test paketi vardı
• Mike, 7 gerçek kullanım senaryosuyla bir eşdeğerlik harness’i oluşturdu ve tüm davranış değişikliklerini düzeltilmesi gereken bug olarak ele aldı

1. aşama: Kural kitabı·bağımlılık haritası·fark listesi

• Temel çıktılar basit çeviri sonucu değil; refactor edilecek yerlerin listesi, çeviri yöntemi için kural kitabı ve çalışma sırasını belirleyen bağımlılık haritasıdır
• Yazım sırası önemlidir
  • Önce kural kitabının varsayılanları belirlenmelidir; böylece bu varsayılanlarla işlenemeyen öğeler fark listesi olarak tanımlanabilir
  • Kural kitabı ve fark listesi ortak denetimle birlikte doğrulanır

• Kural kitabı

  • Kural kitabının biçimi, yeni kodun mevcut yapıyı koruyup korumayacağına veya tamamen yeniden tasarlanıp tasarlanmayacağına göre değişir
  • Jarred gibi yapıyı korursanız merkezde diller arası tip ve idiom eşleme tablosu olur; çevrilmesi zor bileşenler için fark listesine başvurulur
  • Mike gibi yeniden tasarlarsanız kural kitabı tasarım dokümanı rolü görür
  • Jarred, Claude ile konuşarak her belirsiz alan için politika oluşturdu ve beklenen 8 hata kategorisinin her birini incelemesi için 8 alt ajan yapılandırdı

• Bağımlılık haritası

  • Paralel geçişte hangi dosyanın önce taşınacağını ve hangi dosyaların aynı batch’e alınacağını belirlemek için dosya bağımlılıklarını anlamak gerekir
  • Açık manifest’i olmayan legacy kodlarda ve C/C++, Python gibi kod tabanlarında bağımlılıkların doğrudan keşfedilip haritalanması gerekir
  • Claude Code ajanı, deterministik betikler yazma·çalıştırma ve inceleyip düzeltme döngüsüyle harita üretebilir
  • Genelleştirilmiş örnek bağımlılık haritası prompt’unda görülebilir

• Dil fark listesi ve şüpheci inceleyici

  • Fark listesi, mevcut kodda örtük olarak bulunan ancak hedef dilde açıkça belirtilmesi gereken bilgiyi kaydeder
  • Zig→Rust’ta bellek yönetimi biçimi başlıca farktı
  • Zig’de bir buffer’ın çağıran tarafından serbest bırakılması gerektiği yalnızca yorumlarda bulunabilir; serbest bırakma unutulsa da kod derlenir ve sızıntı çalışma sırasında bulunur
  • Rust’ta sahiplik çağırana geçer ve bellek otomatik serbest bırakılır; taşıma sonrası kullanım veya çift serbest bırakma derlenmez
  • Python→TypeScript’te arayüzler ve sözleşmeler başlıca farktı
  • Python’da alınan nesnenin ve dönüş değerinin biçimini bildirmek gerekmez
  • TypeScript’te derlenebilmesi için method, argüman ve dönüş biçimi sözleşmelerinin yazılması gerekir
  • Jarred çeviri öncesinde farkları listeledi, Mike ise önce çevirip denetim sürecinde liste oluşturdu; projeye göre iki yaklaşım da kullanılabilir
  • Genelleştirilmiş örnek fark listesi oluşturma prompt’unda görülebilir

2. aşama: Kural stres testi

• Tam geçişten önce küçük ölçekli bir deneme geçişi ile kural kitabı zorlanır ve sorunlar bulunur
• Jarred üç ajan çalışmasını karşılaştırdı
  • İlk ajan kural kitabına göre 3 dosyayı çevirdi
  • İkinci ajan aynı ölçeği deneyimli bir Rust mühendisi gibi çevirdi
  • Üçüncü ajan iki sonucun farklarına dayanarak yeni çeviri kuralları yazdı
• Bu süreçte 1.448 dosyanın tamamına yayılmadan önce 2 ciddi sorun bulundu
• Bu yöntem, aynı dosyanın iki çeviri sonucunun satır satır karşılaştırılabildiği yapı koruyan geçişlerde çalışır
• Mike gibi yeniden tasarım durumunda karşıt inceleyici tasarım dokümanına saldırmalı ve atılabilir uçtan uca çalıştırmalarla doğrulama yapılmalıdır
• Denemede çevrilen tüm dosyalar atılmalıdır; amaç kademeli kod ilerlemesi değil, kuralları iyileştirmektir
• Genelleştirilmiş görev örneği stres testi prompt’unda görülebilir

3. aşama: Tüm kodu çevirme

• Sonraki aşamaların tamamı uygulama→inceleme→düzeltme şeklinde çok ajanlı döngü kullanır
• Toplu uygulama küçük modele verilebilir, incelemeyi büyük model üstlenebilir
  • Mike, çekirdek geçişi paralelleştirirken 12 Claude Sonnet alt ajanı kullandı
• İş kuyruğu mekanik olarak yönetilir
  • Batch betiği, çeviri dosyasının diskte bulunup bulunmamasına göre tamamlanma durumunu belirler
  • Kalan dosyaları uygulama ajanları için batch’lere böler
  • Her çalıştırmada kuyruğu disk durumundan yeniden kurduğu için temelde durdurup devam ettirilebilir
• Ajan fazla temkinli davranıp çok az işliyorsa, bir sonraki aşamada derleyicinin hataları yakalayacağı bağlamıyla birlikte daha doğrudan talimat verilebilir
• Güvenle işlenemeyen öğeler // TODO(port): <reason> ile işaretlenir ve 4. aşamada çözülür
• Sonraki iş listesi derleme hatalarından, smoke test çakılmalarından ve test başarısızlıklarından otomatik üretilir

• Karşıt inceleme ve kural güncelleme

  • Bağımsız bağlama sahip 2 karşıt inceleyici uygulama sonucunu değerlendirir; görüş ayrılığı varsa üçüncü ajan karar verir
  • Aynı hata birden çok dosyada tekrarlanırsa dosyalar tek tek düzeltilmez
  • Kural kitabına bir cümle eklenir ve etkilenen batch yeniden üretilir
  • Çeviri aşamasında da kural kitabı genişlemeye devam eder; kurala aykırı kod elle yamalanmaz

• Derleyicinin batch içindeki konumu

  • Derleme süresi kısaysa çeviri döngüsünün içine dahil edilebilir
  • Mike, TypeScript derlemesi birim başına saniyeler içinde bittiği için her döngüde çalıştırdı
  • Derleme uzun sürüyorsa bir sonraki aşamaya ertelenir
  • Jarred, cargo çalıştırması dakikalar sürdüğü için çeviri döngüsünde derleyici kullanımını yasakladı
  • Bu aşamadan itibaren prompt’lar kısalır; örnek çeviri başlangıç prompt’unda görülebilir

4–6. aşamalar: Derleme·çalıştırma·davranış eşleşmesi

• Üç aşama aynı döngü yapısını paylaşır; ilerledikçe gereken insan yargısı azalır
• Dil ve proje ölçeğine bağlı olarak derleme aşaması tüm çeviri aşamasına dahil edilebilir

• 4. aşama: Derleme

  • Jarred, orkestratör betiğinin tüm workspace’te derleyiciyi bir kez çalıştırmasını sağlayacak şekilde yapılandırdı
  • Düzeltme ajanları hata listesini paralel işleyip karşıt incelemeden geçtikten sonra yeniden build etme sürecini tekrarladı
  • Hata listesi incelemesi tek tek hataları değil, sistemik sorunları bulmak için kullanıldı
  • Zig’in gecikmeli derlemesinin izin verdiği döngüsel import’lar düzeltildikten sonra binlerce Rust modül hatası ortaya çıktı
  • Hangi bağımlılığın silineceğini·taşınacağını veya sınırların nasıl yeniden yapılandırılacağını sınıflandıran mantık döngüye eklendi

• 5. aşama: Çalıştırma ve smoke test

  • Smoke testlerde oluşan çakılmalar derleme hata listesi gibi mekanik doğru cevap rolü görür
  • Sorunlar tek tek ele alınmaz; kök neden kategorilerine gruplanır ve karşıt alt ajanlar tarafından incelenir

• 6. aşama: Kaynakla davranış karşılaştırması

  • Çeviri·derleme·smoke test tamamlanmış kod bölünür ve ön aşamada hazırlanan test paketi kaynak ve porta çalıştırılır
  • Düzeltme ajanı başarısız testi ve iki kod tabanını birlikte inceler; karşıt inceleyici düzeltme sonucunu doğrular
  • Yalnızca build daemon ikili dosyayı yeniden build edebilecek şekilde sınırlandırılır
  • Düzeltme ajanı patch yazar, daemon patch’leri toplayıp yalnızca bir kez yeniden build eder
  • Etkilenen testler yeniden çalıştırılır ve sonuç döndürülür
  • Birden çok ajanın pahalı build’i ayrı ayrı çalıştırmaması için işler serileştirilir
  • Aynı başarısızlık birden çok testte tekrarlanırsa bug’ı oluşturan üst düzey kural düzeltilir ve yalnızca o kuralın etkilediği dosyalar yeniden üretilir

• Test paketi yoksa

  • Mike, 7 gerçek senaryoyu kaynak Python koduna ve yeni porta çalıştırıp sonuçları karşılaştıran küçük bir betiği Claude’a ürettirdi
  • Başarısız olan her senaryo için ayrı düzeltme ajanı atandı ve 7’si de geçene kadar tekrarlandı
  • Claude kendi uçtan uca test paketini de tasarlayıp gece boyunca otonom çalıştırdı
  • Hataları düzeltip yeniden çalıştırma işi dört gece boyunca tekrarlandı
  • Önceden yazılmış senaryo listesiyle tahmin edilmesi zor küçük kullanılabilirlik sorunları bile bulundu
  • Mevcut testler olmasa da kaynak kod tabanı doğru cevap alınarak Claude bir hakem oluşturabilir

Tekrarlı çalıştırmalarda doğrulanan operasyon ilkeleri

• Kılavuzu aynen izlemek yerine proje özelliklerine göre Claude ile geçiş planı yapıp sonra başlamalısınız
• Tekil hataları düzeltme ajanlarına bırakmalı, insanlar tekrarlayan hata kalıplarına odaklanmalıdır
• İnceleme karşıt, doğrulama mekanik olacak şekilde kurulmalıdır
  • Karşıt inceleme uzun süreli işlerde yararlıdır ve ek token tüketimine değebilir
  • Derleyici, diff ve test paketi gibi betikler nihai hakem olarak kullanılmalıdır
• Her iş için en büyük model kullanılmaz
  • Küçük modeller toplu uygulamayı paralelleştirmek için kullanılır
  • En büyük model incelemeye ve diğer ajanların izleyeceği kuralları yazmaya odaklanır
• İnsan çalışma zamanı kural kitabı ve stres testine önden yatırılmalıdır; sonraki süreç çoğunlukla kuyruğu tüketmektir
• Tamamlanma durumu “çıktı dosyası diskte var” gibi mekanik olarak ayırt edilebilmelidir ve kuyruk devam ettirilebilir olmalıdır

Bun geçişinin sonucu ve kısıtları

• Bun’ın Rust portu production’da çalışıyor; ancak Rust kodunun yaklaşık %4’ü unsafe blokları içinde
  • Çoğu C/C++ sınırındaki tek satırlık pointer işlemleridir
• Araçlarla tespit edilebilen tüm bellek sızıntıları düzeltildi
  • Build’in 2.000 kez tekrarlandığı benchmark’ta bellek kullanımı 6.745MB’den 609MB’ye düştü
• Linux ve Windows ikili dosya boyutu %19 küçüldü
• Diller arası optimizasyonla HTTP servisleri ve next build, tsc gibi gerçek iş yüklerinde performans %2–5 arttı
• Büyük ölçekli geçişlerde üretilen kodun her satırından çok döngünün ürettiği sonuçlar ve yineleme kalıpları incelenmelidir

İlgili kaynaklar

• Migration starter kit: Metindeki prosedürü genelleştiren şablondur; gerçek iki port bu kit ile çalıştırılmış değildir
• Code-modernization plugin: Dil portu değil, legacy modernizasyonu ve framework yükseltmeleri için plugin
• Dynamic workflows in Claude Code: Claude Code’un dinamik iş akışlarına giriş