Denetçili AI agent düzeni

İşlerimizin çoğunu AI agent'larla yürütüyoruz: araştırma, kod, içerik, tasarım. Agent'lar hızlı. Ama yanlış bir şeyi kendinden emin biçimde "bitti" diye getirdikleri de yeterince oluyor; o yüzden "bitti" sözünü olduğu gibi kabul etmeyi bıraktık. Aşağıda her gün kullandığımız düzeni yazdık; işinize yarayan parçasını alabilirsiniz. Düzen Claude Code'un alt agent'ları ve sade git üzerine kurulu, ama roller başka araçlara da taşınabilir.

Kim ne yapar?

Dört rol var. Aynı işte hiç kimse iki rolü birden üstlenmiyor.

Şef ana oturumdur. İnsanla konuşmayı ve genel planı o tutar, gerisini dağıtır. Şef kendisi iş üretmediği için kendi işini onaylama durumuna da düşmez.

Her agent kısa bir rol tarifi ve araç listesi içeren bir Markdown dosyası. Claude Code her alt agent'ın kullanabileceği araçları ayrı ayrı sınırlamaya izin veriyor; biz bunu denetçide kullanıyoruz. Denetçi okuyabilir, arayabilir, komut çalıştırabilir, ama düzenleme aracı yok. Bulduğu hatayı sessizce kendisi düzelten denetçi, sonunda kendi yaptığı değişikliği onaylamış olur.

Brifte neler yazar?

Agent'lar sohbeti görmez, birbirini de görmez. Bildikleri tek şey briftir. Her brif aynı yedi başlıkla yazılır:

1. Görev: ne yapılacak ve neden. Nedeni bilen agent belirsiz durumda daha doğru karar verir.
2. Senin dosyaların: agent'ın değiştirebileceği dosyalar.
3. Dokunma: başka agent'ın çalıştığı dosyalar, başka projeler, riskli yerler.
4. Önce oku: kuralların ve bağlamın yazılı olduğu belgeler.
5. Bağlam: agent'ın bilemeyeceği şeyler: insanın ne dediği, daha önce denenip olmayan, ilgili eski karar.
6. Bitti tanımı: ölçülebilir olmalı. "Testler geçiyor", "kaynaksız rakam yok".
7. Rapor: her seferinde aynı alanlar: dosyalar, özet, testler, açık sorunlar, öneriler ve yol üstünde görülen fırsatlar.

Brifi yazarken uyduğumuz kural kısa: sınırı çiz, yolu çizme. Agent'a neye dokunabileceğini ve işin ne zaman bitmiş sayılacağını söyle; nasıl yapacağını ona bırak.

Her agent neden kendi dalında çalışır?

Dosya değiştiren agent kendi git worktree'sinde, kendi dalında çalışır. Worktree, tek bir reponun her biri ayrı dalda duran birkaç çalışma klasörü olmasını sağlar; böylece aynı anda çalışan agent'lar birbirinin yarım kalmış dosyasına basmaz. Agent sık commit atar, hiç push etmez.

Bazı git komutları agent'lara yasak: stash, reset --hard, rebase ve push --force. Hepsi işi saklayabilir ya da silebilir; bir agent bunları yanlışlıkla çalıştırırsa sonradan fark etmek zor olur. Birçok işin dokunduğu dosyalar da aynı anda yalnız bir agent'a verilir. Bunu, iki paralel agent aynı dosyayı değiştirip birleştirmede çakıştığında öğrendik.

Denetçi nasıl çalışır?

Denetçi, işi yazmamış ayrı bir agent'tır. Brifi ve değişikliği okur, sabit bir listeden geçer:

1. İstenen yapılmış mı, dışına taşılmış mı?
2. Brifin dışında bir dosya değişmiş mi? (git diff --stat)
3. Testler geçiyor mu, düzeltme olmasa kırılırlar mıydı?
4. Uydurma rakam, tarih ya da kaynak var mı?
5. Kalıcı kurallara uyulmuş mu?
6. Bir sır koda ya da kayda yazılmış mı?
7. Metin doğru dilde ve sade mi?
8. Bir projenin verisi başka bir projeye karışmış mı?

Cevabı da sabit biçimde verir: ONAY ya da DÜZELT kararı, ardından engeller, küçük cilalar ve uydurma veri ya da boş test gibi gerçeklik hataları. Engel düzelmeden iş bitmiş sayılmaz.

Denetçi bir kez bakar. DÜZELT derse iş kısa bir brifle agent'a döner, düzeltmeyi şef okur. İkinci denetçi turu açılmaz. Üç düzeltme turundan sonra şef durur ve insana sorar.

Her iş denetçiye gitmez. Tek dosyalık, mekanik, kabaca 30 satırdan küçük bir değişikliği tek agent yapar, farkı şef kendisi okur. Orta boy işe bir agent ve bir denetçi verilir. Büyük iş, dosyaları ayrı bağımsız parçalara bölünür ve her parçanın kendi denetçisi olur.

Yeşil test neden kanıt sayılmaz?

Düzeltmeyle de düzeltmesiz de geçen bir test hiçbir şey kanıtlamaz. Bu kolayca olur: az şey ölçen bir test, yeşile giden en kısa yoldur.

Kuralımız şu: düzeltmeden sonra onu geri al ve testi yeniden koş. Test kırılmalı. Hâlâ geçiyorsa düzeltmeyi test etmiyordur. Denetçi bu soruyu her düzeltme için sorar.

Yeşil testler gerçek ölçekte önemli olanı da kaçırabilir. Bir projede yeni bir bileşen, tek bir sonucu göstermek için bütün veritabanını belleğe yüklüyordu. Testler yeşildi. Denetçi gerçek veri boyutunda ölçtü ve sayfanın 20 saniye donacağını buldu. Bundan çıkan kural: denetçi, gerçek veri boyutunda ölçmeden onay vermez.

Kendi sitemizde testleri de test ediyoruz. Herhangi bir iç bağlantı yönlendirmeye düşerse hata veren bağlantı testimizin yanında ikinci bir test var; ona bilinen hatalı bağlantıları verip gerçekten yakaladığını doğruluyor.

İnsan nerede devreye girer?

Agent önerir ve uygular, son kararı insan verir. Bunun için birkaç sabit kapı var:

• Birleştirme. Yalnız şef birleştirir; o da testler geçtikten ve denetçi onay verdikten sonra. Birleştirmede git merge --no-ff kullanılır: her seferinde bir birleştirme commit'i oluşur, her agent'ın işi geçmişte tek parça olarak görünür. Ana dala değişiklik yalnız insanın istediği bir pull request ile girer.
• Görünür değişiklik. Görünür bir şey yayına girmeden önce insan, telefon (390 piksel) ve masaüstü (1280 piksel) genişliğinde ekran görüntüsünü görür.
• Para. Ücretli bir servis açılmadan önce aylık tutarı yazılır, insan onaylar.
• Sır. Anahtar, şifre ve token hiçbir dosyaya ya da kayda yazılmaz.

Bu kapılar, agent'lar gerçekleşmemiş başarıyı bildirdiği için var. Ana sayfamızda kendi işlerimizden genelleştirilmiş sekiz örnek sıraladık. Birinde agent "Değişiklik yapıldı, işlem başarılı" dedi; sayfa açıldığında hiçbir şey değişmemişti. Bir başkasında hatalı cümle düzeltildi, ama yerine yazılan cümle de uydurmaydı.

Bunun bedeli ne?

Tek bir agent'ı serbest bırakmaktan yavaş. Her işe brif gerekiyor, çoğuna denetçi, bazıları insanı bekliyor. Denetçi de bir şeyleri kaçırabilir. Bu bedeli kabul ediyoruz, çünkü yanlış bir "bitti"yi sonradan bulmak, şimdi yakalamaktan pahalı.

Bir alışkanlık daha: "bitti" demeden önce canlı sonuca bak. Sayfayı aç, değişen satırı oku. Bir bulgu başkasına gidecekse önce gerçek tarayıcıda doğrula.

Benzer bir düzen kuruyorsanız ve notlarımızı karşılaştırmak isterseniz bize yazın.

Kaynaklar

• Claude Code, alt agent'lar (ayar, araç sınırlama): code.claude.com/docs/en/sub-agents
• Git, git-worktree: git-scm.com/docs/git-worktree
• Git, git-merge (--no-ff): git-scm.com/docs/git-merge