Çıkar, Hizala, Kanıtla: AI Ajanlarının Reponuzu Spagettiye Çevirmesini Önleyen Üç Beceri

Kodlama ajanlarına her gün gerçek ticket’lar veriyoruz ve neredeyse her zaman çalışan bir şey teslim ediyorlar. Endişemiz hiç bu olmadı. Endişe nasıl çalıştıkları: halihazırda o işi yapan üç tanesinin yanına eklenen yeni bir yardımcı fonksiyon, tek bir çağıran için taze bir soyutlama, ticket’ta adı geçen tek yolu yamalayıp dört kardeşini bozuk bırakan bir düzeltme, hiçbir kanıtı olmayan “muhtemelen bir hata” şeklinde bir bulgu. Her değişiklik yerel ölçekte makul. Toplamda ise entropi.

Kısaca: Ajan orkestrasyon çekirdeğimizdeki beş Tier-3 pull request boyunca, bir arada kullanılabilen üç beceri — ponytail (çıkar), grain (hizala) ve review-proof (kanıtla) — beş özelliği yayına alırken 821 satırı kaldırdı, sadece makul görünmeye dayanarak birleştirilecek sessiz bir sözleşme ihlalini yakaladı ve her değişikliğin mevcut mimarinin damarı yönünde ilerlemesini sağladı. Aşağıda her birinin ne yaptığı ve bunu destekleyen gerçek diff’ler var.

Korkulukları kaldırın, bir kodlama ajanı makul görünen yükümlülükleri çok hızlı üreten bir makineye dönüşür. Bu yüzden ters yöne iten üç küçük beceriye yaslanıyoruz — her biri tek bir içgüdü: çıkar, hizala, kanıtla.

• ponytail — gerçekten işleyen en tembel şeyi yaz. Eklemeden önce sil. (Bunu biz yazmadık — Dietrich Gebert’in açık kaynak becerisi ve biz onu kendi stack’imize uyarladık.)
• grain / grain-review — kodu, kod tabanının zaten karar verdiği yere koy. İkinci bir yol icat etme.
• review-proof — bir bulgu, başarısız bir test olarak yeniden üretilene kadar ona inanma.

grain ve review-proof becerilerini de ponytail ile aynı ruhla, mimarimiz için ayarlayarak geliştirdik. Aşağıdaki beş PR’ın her biri, repodaki en pahalı yer olan ajan orkestrasyon çekirdeğimize dokunuyor — ve hepsi Tier 3 olarak sınıflandırıldı: otomatik inceleyicinin üstüne ek test kapsamı ve insan incelemesi, istisnasız.

Üç beceri bir bakışta: ponytail çıkarır, grain hizalar, review-proof kanıtlar.

Bölüm 1 · NE — varsayılan durum entropidir

Bir repoyu AI ajanlarına teslim ettiğinizde kimsenin sizi uyarmadığı şey şu: her ajan yerel ölçekte optimize eder ve hiçbir şey hatırlamaz. Ticket’ı görür, ekibinizin aylar boyunca üzerinde uzlaştığı konvansiyonları değil. Mevcut e-posta servisinizi yeni bir tanesine tercih etmesi için bir sebebi yok, yönlendirme durum kodları kümesinin üç dosya ötede zaten tanımlı olduğuna dair bir hafızası yok, “düzeltme bu tek çağırana değil, paylaşılan fonksiyona gider” diye bir içgüdüsü yok. Kendi hâline bırakıldığında N ajan, aynı şeyi yapmanın N tane azıcık farklı yolunu üretir. Bu, lint ile temizleyebileceğiniz bir kod kalitesi sorunu değil — katlanarak büyüyen yapısal bir sapmadır.

Üç becerinin her biri bu sapmanın bir eksenini hedefler.

ponytail — işleyen en tembel şey

Ponytail, gece 3’te başkasının zekice soyutlaması yüzünden çağrılmış ve bir sonrakini yazmayı reddeden kıdemli bir geliştiricidir. Bir merdiven işletir ve tutan ilk basamakta durur: buna gerçekten ihtiyaç var mı (YAGNI) → zaten bu kod tabanında var mı → standart kütüphane bunu yapıyor mu → yerel platform özelliği → hâlihazırda kurulu bağımlılık → tek satıra indirilebilir mi → ancak ondan sonra, işleyen minimum kod.

Ajanlar için en önemli basamak “zaten bu kod tabanında var mı?” sorusudur. Birkaç dosya ötede var olan bir şeyi yeniden yazmak, ajan savrukluğunun en yaygın biçimidir. Ponytail’in hata düzeltme kuralı da diff’leri dürüst tutar: semptomu değil, kök nedeni düzelt. Dokunmak üzere olduğunuz fonksiyonun her çağıranını grep’leyin; paylaşılan fonksiyondaki tek bir koruma, her çağırandaki bir korumadan daha küçük bir diff’tir — ve kardeşleri bozuk bırakmaz.

grain / grain-review — damarın yönünde git

Ponytail ne kadar az yazacağınızı yönetiyorsa, grain de nereye gideceğini ve hangi biçimi alacağını yönetir. Tek kuralı: en yakın mevcut örneği bul, biçimini kopyala, kopyaladığın şeyi adlandır. Yeni kod, sanki yanındaki dosyayı yazan kişi bunu da yazmış gibi okunmalıdır.

Grain aynı zamanda mimarinin uygulandığı yerdir. Backend’imiz oldukça standart bir vertical-slice + hexagonal düzen: sunum katmanı uygulamayı, uygulama alanı (domain) çağırır, altyapı içe doğru bağımlıdır ve alan katmanı asla dışa uzanmaz. “Bu route controller’ını atlayıp servisi doğrudan çekiyor” gibi bir bulgu kılı kırk yarma değil — bir kod tabanının gelecek ay ajan tarafından gezilebilir olmasıyla olamaması arasındaki farktır. grain-review tam da bunların peşine düşer: tekrarlanmış yardımcı fonksiyonlar, aşılmış katman sınırları, başka bir özelliğin iç işleyişine uzanma, zaten tek bir şekilde yapılan bir şey için ikinci bir konvansiyon.

review-proof — bulguyu hak et

Standart AI kod incelemesi makul görünen bulgular üretir. Bazıları gerçektir; bazıları kendinden emin saçmalıktır; dışarıdan bakınca ikisi ayırt edilemez. review-proof kendine güvenmeyi reddeder: inceler, sonra her doğruluk bulgusunu gerçek bir başarısız test ya da çalıştırılabilir bir yeniden üretim olarak ortaya koymaya zorlar ve bunu yapamayan her şeyi düşürür. Yapısal uyum için bir grain-review geçişiyle kapanır. Ortaya çıkan şey, her maddesi çalıştırılabilir kanıtla gelen bir incelemedir — bir hissiyat değil.

Bu işe yarıyorsa görmemiz gerekenler

• H1 — Silme, özellik PR’larında görünür. Ponytail + grain çalışıyorsa, bir özellik eklemek sık sık net yapıyı azaltmalı, yalnızca eklememeli.
• H2 — Düzeltmeler bir kez, paylaşılan yerde konuşlanır. Kök neden düzeltmeleri, çağrı noktalarının çoğunu tek bir korumada toplamalı; çağıran başına koruma serpiştirmemeli.
• H3 — İnceleme, insanın gözden kaçırdığı sözleşme ihlallerini yakalar. Kanıta dayalı inceleme, “iyi görünüyor” incelemesinin kaçırdığı hataları ortaya çıkarmalı — özellikle sessiz olanları.

Bölüm 2 · E HALİDE NE — beş PR, her birinde bir içgüdü

Ajan çekirdeğimizde yapılmış beş gerçek değişiklik. İç işleyişi bilinçli olarak belirsiz bırakıyoruz — repo özel — ama sayılar gerçek diff’lerden hesaplandı ve aktarılabilir kısım da dersler.

Çıkar: bir düzine fetch noktası için tek koruma

Bir akış adımı ailesi, kullanıcı tarafından sağlanan URL’leri DNS çözümleyen bir güvenlik kontrolü olmadan çekiyordu; dolayısıyla iç bir adrese çözülen bir hostname, backend’den bulut metadata’sına ulaşabiliyordu. Cazip düzeltme, bir düzineden fazla fetch noktasının her birine bir kontrol eklemekti. Ponytail’in cevabı tam tersiydi: her yerde kullanılan tek, korumalı bir paylaşılan fetch yardımcısı — ve bir wildcard-DNS hilesinin kolayca atladığı el yapımı özel ağ tablosunu, üç kopyalanmış yönlendirme döngüsünü ve birkaç dosyaya kopyala-yapıştır yapılmış bir ağ kontrolünü sildik.

Diff, paylaşılan yardımcıyı ekledi ve 22 dosyada ~90 satır tekrarı kaldırdı. Hikâye bu silmede: bu, canlı hâliyle H2 — kök neden düzeltmesi, ticket’ta adı geçen tek yolu yamamak yerine her çağıranı tek bir korumadan geçirdi.

Kök neden düzeltmesi: bir düzine doğaçlama fetch noktası tek bir paylaşılan, korumalı yardımcıda birleşiyor. Tembel düzeltme ile güvenli düzeltme aynı düzeltme.

Çıkar + kanıtla: gerçek çalışma zamanında kanıtlanmış tek biçim koruması

Worker çalışma zamanımız bir çalıştırmanın sonucunu serileştirilmiş bir string olarak, bazen tek elemanlı bir listeye sarılı şekilde saklıyor. Düz bir nesne bekleyen tüketiciler bunda çöküyordu. Yanlış düzeltme, her tüketiciye savunmacı tip kontrolleri serpiştirir. Bunun yerine: tek bir küçük biçim normalleştirme yardımcısı ve her tüketici ona yönlendirildi — disiplinsiz bir ajanın yazacağı N doğaçlama korumanın yerini alan, neredeyse saf bir tek koruma eklemesi (+558 / −24, 7 dosya).

Bunu bir review-proof hikâyesi yapan kısım test. Varsayılan bir serileştirme biçimine karşı doğrulama yapmak yerine, gerçek çalışma zamanı ve depolama üzerinden gerçek bir iş akışı çalıştırdık — hiç mock yok — ve çalışma zamanının gerçekte hangi biçimi kalıcılaştırdığını kanıtladık. Ticket’taki açık soru kelimenin tam anlamıyla çalışma zamanı burada neyi serileştiriyor? idi — ve tek dürüst cevap çalıştırabildiğiniz cevaptır.

Kanıtla: inceleme sessiz bir sözleşme ihlalini yakaladı

Özellik: düğüm başına yedek model, böylece tek bir sağlayıcıya sabitlenmiş bir akış kesinti sırasında zarifçe geriler. İlk bariz kesit, modeli framework’ün yerleşik fallback birleştiricisiyle sarıyordu.

Mutlu yolda çalıştı. Aynı zamanda somut model tipini isinstance ile kontrol eden iki sağlayıcı özelliğini sessizce kapattı — sarılmış bir nesne artık o tip değildir, dolayısıyla yerel yapılandırılmış çıktı ve prompt önbellekleme sessizce devre dışı kaldı. Hata yok. Başarısız bir mutlu yol testi yok. Tam olarak insan incelemesinin gözden kaçırdığı ve “iyi görünüyor” diyen bir ajanın onayladığı türden bir şey.

review-proof bunu onaylamadı — her iki ihlali de başarısız testler olarak yeniden üretti, bu da yeniden tasarımı zorladı: fallback’i daha aşağıda, yürütme anında uygula, böylece her model somut tipinde kalsın ve tipe bağlı özellikler çalışmaya devam etsin. H3, kesin biçimde doğrulandı: kanıt, makul görünmenin yayına alacağı bir hatayı yakaladı.

Hizala: iki kopya değil, tek seçici

İkinci bir bildirim kanalı eklemek, kanal seçici arayüzünün artık iki evi olması anlamına geldi — bir oluşturma sihirbazı ve bir ayarlar modalı. Varsayılan ajan hamlesi, yeni dalı ikisine de ekleyip aynı durum makinesinin iki kopyasını büyütür. grain dedi ki: bunun biçimlenmesi için zaten tek bir yol var — onu paylaşılan hâle getir. Tek bir seçici hook’u çıkardık ve her iki ekranı da onun üzerinden sürdük, yeni kanalı mevcut config union’a yerleştirdik ve yeni gönderim mekanizması eklemek yerine mevcut e-posta servisini yeniden kullandık.

24 dosyada +1.735 / −340. Bu büyüklükte bir özelliğin 340 satırı kaldırması, görünür hâle gelmiş H1’dir: iki seçici kopyasının tek kopyaya indirilmesi, yeni kanalın hatırı sayılır bir kısmını karşıladı.

Hizala + kanıtla: endpoint’i yeniden kullan, yolu aynala

Kullanıcıların issue oluştururken dosya eklemesine izin vermek, yeni bir yükleme endpoint’i, yeni bir dağıtım mekanizması, yeni bir prompt yolu anlamına gelebilirdi. grain neredeyse tamamını mevcut raylara yönlendirdi: mevcut yükleme endpoint’i, backend beyaz listesini tam olarak aynalayan bir frontend kabul listesi ve planlanmış işlerin zaten kullandığı uygunluk mekanizmasını yeniden kullanan ertelenmiş dağıtım düzeltmesi. Kanıta dayalı düzeltmelerle yayına alındı; bunlardan biri, paralel yüklemeler altında veri kaybına yol açacak gerçek bir işlem izolasyonu hatasıydı. 27 dosyada +1.776 / −218 — yeni dilimler icat etmek yerine mevcut dilimlere katılarak yine de 218 satır silmeyi başaran büyük bir özellik.

Skorboard

Beş Tier-3 PR: her birinin ne eklediği, ne kaldırdığı ve arkasındaki içgüdü.

Ajan çekirdeği üzerindeki beş özellik ve düzeltme PR’ı 821 satırı kaldırdı — daha az iş yaparak değil, zaten var olanı kopyalamayı reddederek ve kök neden düzeltmesinin gereksiz kıldığı semptom yamalarını tutmayarak.

Tam açıklama

• Bunlar bir çalışma değil, beceriler. Bu, bir temel kolu olan kontrollü bir deney değil; disiplinin uygulandığı beş gerçek PR. Karşı olgu — aynı ajanın beceriler olmadan neyi teslim edeceği — ölçüm değil, bilgiye dayalı bir tahmin. Sessiz sözleşme ihlali hikâyesi en temiz kanıt, çünkü incelemenin hatayı yeniden tasarımdan önce yeniden ürettiğini gördük.
• Satır sayıları vekil göstergelerdir. −821 diff’lerden gelen gerçek bir sayı, ama “kaldırılan satırlar” “önlenen tekrar ve ölü esneklik” anlamına geliyor. Bir ajanı 200 spekülatif satır yazmaktan vazgeçiren bir beceri diff’te hiç iz bırakmaz — en büyük kazanımlar burada görünmez.
• Token tasarrufu yön belirtir. Daha küçük diff’ler, daha az dokunulan dosya ve yeniden kullanılan yapılar, üretmek, incelemek ve yeniden incelemek için harcanan daha az token demek — ama PR başına kesin bir token farkı vermiyoruz.
• ponytail bize ait değil. Bu, Dietrich Gebert’in açık kaynak becerisi ; biz onu uyarladık. grain ve review-proof bize ait ve aynı ruhla geliştirildi. Üçü de Claude Code üzerinde yerel proje becerileri olarak çalışır — kurduğunuz bir ikili dosya değil, prompt ve prosedür.

İşinizi büyütmeye hazır mısınız?

Bugün ücretsiz denemenizi başlatın ve günler içinde sonuçları görün.

Demo talep et Giriş yap

Bölüm 3 · ŞİMDİ NE

Ne yayına alındı. Bir arada kullanılabilen üç beceri. ponytail ve grain yazarken çalışır; ponytail-review, grain-review ve review-proof bir diff üzerinde çalışır. review-proof, son aşaması olarak grain-review‘ı zincirler, böylece tek bir kanıtlı inceleme bedavaya bir yapısal geçiş de kazanır.

Pazartesi günü yapabilecekleriniz — bizim becerilerimizin aynısına ihtiyacınız yok:

1. “Yeniden kullan"ı onuncu basamak değil, ikinci basamak yapın. Bir ajan yardımcı fonksiyon yazmadan önce, var olanı grep’lemesini sağlayın. “Zaten bu kod tabanında var mı?” sorusu “temiz bir şekilde yazabilir miyim?“in üstünde yer alır.
2. Kök nedende düzeltin, çağıran listesiyle kanıtlayın. Her hata düzeltmesinin, dokunulan fonksiyonun her çağıranını adlandırmasını şart koşun. Paylaşılan fonksiyondaki tek koruma, çağıran başına korumayı yener — ve daha küçük bir diff’tir.
3. Yeni koda kopyalayacağı en yakın kardeşi verin. “En yakın mevcut örneği bul ve biçimini aynala” yaklaşımı, mimariyi kimsenin okumadığı bir dokümandan ajanın uyguladığı bir varsayılana dönüştürür.
4. Katman sınırlarını hisle değil, CI ile uygulayın. Yalnızca yeni katmanlar arası import’larda başarısız olan bir mandal, mevcut borcun okyanusunu kaynatmadan çizgiyi korumanızı sağlar.
5. Yeniden üretemeyeceğiniz bir bulguyu yayına almayın. Ajana önce başarısız testi yazdırın. Hatayı yeniden ürettiremiyorsa, bu bir hata değil — bir görüştür. Düşürün.
6. İnceleme silme hakkını kullansın. Bir inceleme geçişini doğruluktan ayrı olarak özellikle aşırı mühendisliğe yöneltin — “neyi kesebiliriz”. Bir diff’in en iyi sonucu, kısalmasıdır.

Deneyin, hele sizde işe yaramazsa. Gerçek bir kod tabanında kodlama ajanları çalıştırıyorsanız entropi zaten oluyor — sadece ölçmediniz. Bunlardan birini sonraki on ajan PR’ınızda bir inceleme geçişine dönüştürün ve silinen satırları sayın. Çıkar-hizala-kanıtla sizin diff’lerinizi küçültmüyorsa ya da sessiz bir ihlali yakalamıyorsa, bunu gerçekten duymak isteriz. Düzeltmeler ve karşı örnekler özellikle memnuniyetle karşılanır.

Bir ajan ekler. İş, ajana her satırı hak ettirmek.