Plan, subagent ve review döngüsü

Bu sitenin landing sayfasını ve ardından iki dilli blog altyapısını Claude Code ile geliştirdim. İkisinde de aynı süreci kullandım: önce yazılı bir spec, sonra adım adım bir plan, sonra her görev için ayrı bir subagent ve her görevin arkasından bağımsız bir review.

Bu yazı süreci, gerçekte neleri yakaladığını ve neleri kaçırdığını anlatıyor.

Süreç

1. Spec. Birkaç soru ve cevapla neyin yapılacağı yazıya dökülüyor: kapsam, kararlar, kapsam dışı olanlar. Kod yok.
2. Plan. Spec, sıralı görevlere bölünüyor. Her görevde dosya listesi, yazılacak test, kodun kendisi ve commit mesajı var. Plan o kadar somut ki, uygulamak neredeyse kopyalamaya dönüşüyor.
3. Uygulama. Her görev, önceki konuşmayı hiç görmemiş taze bir subagent’a gidiyor. Subagent önce başarısız olan testi yazıyor, sonra kodu, sonra commit ediyor ve bir rapor dosyası bırakıyor.
4. Review. Başka bir subagent, görevin diff’ini planla karşılaştırıyor ve iki karar veriyor: spec’e uygun mu, kalitesi yeterli mi.
5. Düzeltme. Bulgu varsa aynı implementer’a geri gidiyor. Düzeltmeden sonra sadece değişen kısmı kapsayan kısa bir review daha yapılıyor.
6. Son review. Bütün görevler bitince tüm branch, en güçlü modelle bir kez daha inceleniyor.

Koordinasyonu yapan ana oturum kod yazmıyor. Görev dağıtıyor, review sonuçlarını okuyor ve bir kayıt dosyasına ne olduğunu ve hangi kararı verdiğini yazıyor. Bağlam sıkıştırıldığında bile nerede kaldığı bu dosyada duruyor.

Neden taze bağlam

Uzun bir oturumda model, bir süre sonra kendi önceki kararlarını sorgulamayı bırakıyor. Her görevi temiz bir bağlamla başlatmak bunu engelliyor. Subagent sadece kendi görevini, dokunduğu arayüzleri ve genel kuralları görüyor. Daha az bağlam, daha az sapma demek.

Plan somut olduğu için uygulama görevlerinde ucuz modeller yetiyor. Review’larda orta seviye, son review’da en güçlü model kullanılıyor.

Review’ların yakaladıkları

Hepsi gerçek, hepsi testleri geçen kodda bulundu:

• Görünmez olması gereken liste görünüyordu. Landing’deki “Son yazılar” bölümü iki dil için iki ayrı liste üretiyor ve birini hidden ile gizliyor. Liste için yazılan display: grid kuralı hidden’ı eziyordu, iki liste birden görünüyordu. Bunu yakalaması gereken test ise hiçbir şey test etmiyordu: regex ilk iç içe </ul>’de durduğu için kart sayısı hep birdi.
• İmplementer arayüzü değiştirerek testi geçirdi. Bir link kontrol testi, data-lang-href özniteliğinin içindeki href= metnini de link sanıyordu. İmplementer özniteliğin adını değiştirdi ve test geçti. Ama o ad, bir sonraki görevin JavaScript’inin okuyacağı arayüzdü. Karar: arayüz geri alındı, bozuk olan regex düzeltildi.
• Sessiz başarısız olacak bir deploy. Belgedeki FTP kurulum talimatı, deploy’un yanlış klasöre gitmesine yol açacaktı. Pipeline yeşil bitecek, site değişmeyecekti.
• Olmayan sayfaya işaret eden link. Etiket sayfaları, diğer dildeki karşılığı olmasa bile ona hreflang linki veriyordu.
• Hiç çalışmamış kod yolu. Tek dilde yazılmış yazılar için yazılan “sadece Türkçe” notu vardı ama hiçbir örnek yazı tek dilde değildi. Kod ilk kez canlıda çalışacaktı. Tek dilli bir örnek yazı eklendi.
• Küçük ama gerçek. Kıvrık kesme işaretlerinin düz olanlarla değiştirilmesi, JavaScript kapalıyken boş kalan bio paragrafları, HTML’e de uygulanan bir günlük cache.

Kaçırdıkları

• Ortam farkı. Yerelde Node 20, CI’da Node 22 vardı. node --test tests/ komutu Node 22’de çalışmıyor. Hiçbir review bunu görmedi, ilk deploy düştü. Ders: CI ile aynı sürümü yerelde de kullan.
• Görsel kontrol. Tarayıcısı olmayan subagent’lar “sayfaya bak” adımını atladı. Bunu koordinatör oturum tarayıcıda kendisi yaptı.

Ne zaman değer, ne zaman değmez

Bu tören ucuz değil. Her görev bir implementer, bir reviewer, çoğu zaman bir düzeltme turu ve kısa bir review daha demek. Birden fazla dosyaya dokunan ve arayüzleri birbirine bağlı görevler için buna değiyor. Blog altyapısında son review’un yakaladığı hidden hatası, tek başına bütün süreci haklı çıkardı.

Tek satırlık bir düzeltme, bir metin değişikliği ya da bir ayar için değmez. Onları doğrudan yapmak daha hızlı ve daha ucuz.

Dersler

1. Önce yazılı spec. Plan ondan türüyor, review’lar ona göre karar veriyor.
2. Plan ne kadar somutsa, uygulama o kadar ucuz.
3. Yazan ile inceleyen ayrı olsun. Yazarın testleri, yazarın varsayımlarını test ediyor.
4. Test için arayüz değiştirilmez. Önce testin kendisini sorgula.
5. Son review’u en güçlü modele ver. Görevler arası hatalar sadece bütün diff’e bakınca görünüyor.
6. Review ortamı test etmez. CI ile yerel ortamı aynı tut.
7. Kararları kaydet. Koordinatörün verdiği her kararın listesi, işin sonunda sana kalan tek iz.