Kodlama Asistanınızı Manuel Yönlendirmeyin, Onu Otomatik Yönlendiren Döngüyü Oluşturun

Artık kodlama ajanlarına komut vermemeniz gerekiyor. Ajanlarınıza komut veren döngüler tasarlamalısınız. Bu kulağa önemsiz bir ifade gibi gelse de, iyi mühendislerin yapay zeka ile çalışma şeklindeki en büyük değişime işaret ediyor. Yapay zeka kodlama ajanlarından gerçek fayda sağlayan kişiler, ajanı bir sohbet ortağı olarak görmeyi bıraktılar. Onu, kendilerinin oluşturduğu bir döngünün içindeki bir işçi olarak görüyorlar.

düğme

ÖZET

Bir kodlama ajanı döngüsü, bir ajanı tekrar tekrar çalıştıran bir kontrol yapısıdır: bir değişiklik oluştur, çalıştır, sonucu kesin bir sinyale göre kontrol et, hatayı geri besle, kontrol geçene veya bir sınıra ulaşılana kadar tekrarla. Zor kısım ajan değil. Doğrulama kapısıdır. Belirsiz bir kapıya sahip ("iyi görünüyor, tekrar dene") bir döngü sürüklenir ve "bitti" yanılgısına kapılır. Deterministik bir kapıya sahip (başarısız bir test, şema uyuşmazlığı, bozuk bir sözleşme) bir döngü yakınsar. API ve arka uç çalışmaları için, otomatik test paketiniz ve sözleşme kontrolleriniz bu kapıdır, bu yüzden API testi, ajantik bir iş akışının merkezinde yer alır, sonradan eklenmiş bir parça değildir.

Komut Vermekten Döngü Tasarlamaya

Çoğu insan yapay zeka kodlamasıyla bir sohbet kutusu aracılığıyla tanışır. Bir istek yazarsınız, cevabı okursunuz, işe yarayanı kopyalar ve tekrar yazarsınız. Bu, komut verme işidir. Tek seferlik bir fonksiyon veya hızlı bir açıklama için uygundur. Ancak çoğu gerçek iş gibi, görevin doğru hale gelmesi birden fazla geri bildirim döngüsü gerektirdiğinde bu yöntem çöker.

Elle komut vermenin sorunu şudur. Döngü sizsiniz. Çıktıyı okursunuz, hatayı tespit edersiniz, bir sonraki ne söyleyeceğinize karar verirsiniz, hatayı geri yapıştırırsınız. Her yineleme bir insanı bekler. Ajan saniyeler içinde kod üretebilir, ardından siz bağlam değiştirip kaydırıp yazarken dakikalarca boşta bekler. Hızlı bir sistemin yavaş parçası haline gelirsiniz.

Bir döngü tasarlamak bunu tersine çevirir. Çıktıyı okuyan ve bir sonraki komuta karar veren kişi olmak yerine, bunu otomatik olarak yapan bir koşum takımı (harness) oluşturursunuz. Ajan kod yazar. Bir betik onu çalıştırır. Sonuç yakalanır. Başarısız olursa, hata bir sonraki komut olarak doğrudan ajana geri gider. İç döngüde insan yoktur. Sadece uç noktalarda devreye girersiniz: görevi belirlemek, sonucu onaylamak, iş yanlış giderse durdurmak için. Anthropic'in etkili ajanlar oluşturma hakkındaki kendi yazısı da aynı noktayı farklı kelimelerle ifade eder. Kazanım, modelin etrafına kurduğunuz ortamdan gelir, daha akıllı tek bir komuttan değil.

Zihinsel model değişimi küçük ama toplamdır. "Ajana ne söylemeliyim?" diye sormayı bırakın. "Ajanın kendisine söylemesini sağlayacak hangi döngüyü tasarlamalıyım?" diye sormaya başlayın.

Kodlama Ajanı Döngüsü Gerçekte Nedir?

Abartıyı bir kenara bırakırsak, bir kodlama ajanı döngüsünün beş kısmı vardır. Birini kaçırırsanız, döngü ya hiç sonlanmaz ya da yanlış sonlanır.

Bir görev tanımı. Tamamlanmış işin nasıl göründüğüne dair açık, yazılı bir açıklama. "Çalışmasını sağla" değil, "POST /orders uç noktası oluşturulan siparişle birlikte 201 döndürür, gövdeyi şemaya göre doğrular ve eksik alanları 422 ile reddeder."
Ajan. Model ve araçları: dosyaları oku, dosyaları yaz, kabuk komutlarını çalıştır. Bu, herkesin takıldığı ve en az kontrol edebildiğiniz kısımdır.
Bir eylem adımı. Ajan bir değişiklik yapar, sonra bir şey onu gerçekten çalıştırır. Testler, bir derleme, bir tür kontrolü, canlı bir uç noktaya karşı bir istek.
Bir doğrulama kapısı. Somut bir nedenle başarılı veya başarısız döndüren deterministik bir kontrol. Bu, direksiyon simididir. Bu yazının çoğunu burada harcayacağız.
Bir sonlandırma koşulu. Döngü ne zaman durur? Kapı geçerse veya maksimum yineleme sayısına ulaşırsanız veya bir maliyet bütçesini aşarsanız. Çıkışı olmayan bir döngü, bir iş akışı değil, kontrolden çıkmış bir durumdur.

Sözde kodda tüm bu desen birkaç satıra sığar:

task = load_spec("orders-endpoint.md")
for attempt in range(MAX_ITERATIONS):
    agent.run(task, feedback=last_result)   # generate
    result = run_verification()             # run + check the gate
    if result.passed:
        break                               # terminate: success
    last_result = result.failures           # feed failure back
else:
    escalate_to_human(last_result)          # terminate: gave up

Bu döngü, tüm fikrin temelidir. Ajan üretir, kapı yargılar, hata bir sonraki komut haline gelir ve her şey yeşil olana veya deneme hakkı bitene kadar çalışır. İnsanların internette "Ralph" tekniği olarak paylaştığı varyant, MAX_ITERATIONS yüksek ayarlanmış ve tanım sıkı yazılmış olanıdır. Ajan koşum takımı mimarisi hakkındaki analizimizi okuduysanız, bu, koşum takımının en küçük ve dürüst halidir.

Tek Atışlık Komut Vermenin Neden Sınıra Takıldığı

Tek bir komut, modelin ilk seferde doğru yapacağını veya sizin yanlış olanı yakalayacağınızı varsayar. Her iki varsayım da ölçeklendirmede bozulur.

Modeller, makul kod üretmede güçlü, ancak bu kodun doğru olup olmadığını bilmede zayıftır. Doğru görünen, derlenen ve bir uç durumda sessizce yanlış durum kodunu döndüren bir uç nokta yazacaklardır. Bir sohbette, üretime geçene kadar fark etmeyebilirsiniz. Modelin, uç durumun bozulduğunu söyleyen bir geri bildirimi yoktur, bu yüzden kendinden emin bir şekilde başarı bildirir. "Yapılmış görünüyor" ile "yapıldı" arasındaki bu boşluk, döngülerin asıl değerini ortaya koyduğu yerdir.

Bir döngü, modelin kendi işi hakkındaki görüşünü kabul etmeyerek bu boşluğu kapatır. Ajan işinin bittiğini söyleme hakkına sahip değildir. Kapı söyler. Testleri çalıştırın; eğer kırmızı ise, görev bitmemiştir, nokta, ve kırmızı çıktı ajanın okuyacağı bir sonraki şeydir. Modelin güveni önemli olmaktan çıkar. Sadece sinyal önemlidir.

Bir de verimlilik açısı var. Elle komut verme, çıktınızı aktif olarak izlediğiniz tek bir ajanla sınırlar. Döngüler, aynı anda birkaçını çalıştırmanıza olanak tanır; her biri kendi kapısına karşı kendi görevinde çalışır, çünkü hiçbiri iç döngüde size ihtiyaç duymaz. Bu, dinamik, paralel ajan iş akışları hakkındaki yazımızın değindiği sıçramadır: döngü otomatize edildikten sonra, daha hızlı yazarak değil, döngüler ekleyerek ölçeklendirirsiniz.

Herkesin Eksik Bıraktığı Kısım: Doğrulama Kapısı

Rahatsız edici gerçek şu ki, başarısız ajan iş akışlarının çoğu modelin çok zayıf olmasından kaynaklanmaz. Geri bildirim sinyalinin çok zayıf olmasından kaynaklanır.

Kapının ne yaptığını düşünün. Her yinelemede, ajana iki şeyden birini söyler: geçtin, dur; veya başarısız oldun, işte tam nedeni. "İşte tam nedeni" ifadesinin kalitesi, bir sonraki yinelemenin iyileşip iyileşmeyeceğini veya sapıp sapmayacağını belirler. Ajana 42. satırı ve patlayan iddiayı işaret eden kesin bir yığın izi beslerseniz, doğru şeyi düzeltir. Eğer "bir şeyler yanlış görünüyor, lütfen incele" derseniz, tahmin yürütür ve genellikle daha kendinden emin görünürken kodu daha da kötüleştirir.

Deterministik kapılar yakınsar. Belirsiz kapılar sürüklenir. Tüm oyun budur.

İyi bir kapıyı ne oluşturur?

İkili ve tekrarlanabilirdir. Aynı girdi, her seferinde aynı sonuç. "Modelin bugün nasıl hissettiğine bağlı" yok.
Bir neden ile gürültülü bir şekilde başarısız olur. Bir test adı, beklenen ile gerçek arasındaki fark, bir satır numarası, bir hata kodu. Neden bir sonraki komuttur, bu yüzden belirli olması gerekir.
Ajan onu sessizce düzenleyemez. Eğer ajan testi geçmek için değiştirebilirse, kapı sadece bir tiyatrodur. Kapıyı koruyun. Onu ajanın sahip olduğu bir kod olarak değil, bir şartname olarak kabul edin.
Döngü için yeterince hızlı çalışır. 20 dakika süren bir kapı, yineleme hızınızı sınırlar. Sıkı döngüler hızlı kontroller gerektirir.

İyi kapılar her olgun kod tabanında zaten mevcuttur. Birim testleri. Tip denetleyicileri. Linter'lar. Derleyiciler. Şema doğrulayıcılar. Sözleşme testleri. Bunlar deterministik oracle'lardır. İnsanlara "bu yanlış ve nedeni bu" demek için inşa edildiler, ki bu tam da bir ajan döngüsünün ihtiyaç duyduğu sinyaldir. Kapıyı icat etmek zorunda değilsiniz. Döngüyü zaten güvendiğiniz kapılara yöneltmeli ve kapsamın yetersiz olduğu yerlerde yenilerini yazmalısınız. Eğer bu katmanı hiç resmileştirmediyseniz, otomatik testin aslında ne olduğuna dair rehberimiz, bunu bir döngüye bağlamadan önce iyi bir temel sağlayacaktır.

API ve Arka Uç Çalışmaları İçin Test Paketiniz Döngüdür

Soyut fikrin hizmetler inşa eden herkes için somutlaştığı yer burasıdır. Bir ajan bir API uç noktası yazdığında, çalıştığını söyleyen kesin doğru nedir? Modelin özeti değil. Test edilen uç noktanın gerçek davranışı: doğru durum kodları, şemaya uygun yanıt gövdesi, uygulanan kimlik doğrulama, kötü girişin reddedilmesi, sözleşmeye uyulması.

Bunların her biri, otomatik olarak, deterministik bir sonuçla kontrol edilebilir. Bu da API test paketinizin, bir ajan döngüsünün ihtiyaç duyduğu doğrulama kapısı şeklinde zaten tasarlandığı anlamına gelir. Kapıyı başından beri inşa ediyordunuz; sadece buna test diyordunuz.

Uç nokta çalışmaları için somut bir döngü şöyle görünür:

Ajan, görev tanımını ve OpenAPI tanımını okur, ardından uç noktayı yazar veya düzenler.
Koşum takımı, çalışan hizmete karşı API test paketini çalıştırır: durum onaylamaları, her yanıtta JSON şema doğrulaması, spesifikasyona karşı sözleşme kontrolleri.
Hatalar yapılandırılmış olarak geri gelir. "Eksik customer_id için 422 bekleniyordu, 500 alındı." "Yanıt alanı total bir dizge, şema sayı diyor." "Spesifikasyondaki /orders/{id} uç noktasının uygulaması yok."
Bu yapılandırılmış hata, ajanın bir sonraki komutu haline gelir. Belirli boşluğu düzeltir.
Paket yeşil olana kadar tekrarla, ardından inceleme için bir insana devret.

Buradaki anahtar, 3. adımdaki geri bildirimin kesin ve makine tarafından üretilmiş olmasıdır, bir hissiyat değil. Döngüyü sapmak yerine yakınlaştıran da budur. Şema odaklı ve sözleşme testi burada her zamankinden daha önemlidir, çünkü OpenAPI spesifikasyonu hem ajanın hem de kapının okuduğu ortak doğruluk kaynağı haline gelir. Kod ve spesifikasyon arasındaki kayma yavaş bir dokümantasyon sorunu olmaktan çıkar ve anında kırmızı bir kapıya dönüşür.

Apidog'un ajantik bir iş akışındaki rolü budur. Tasarımın, şemanın, sahte sunucunun ve otomatik testlerin tek bir yerde bulunduğu hepsi bir arada bir API platformudur; bu da kapı ve spesifikasyonun varsayılan olarak senkronize kalması anlamına gelir. Döngüyü bir Apidog test senaryosuna yönlendirirsiniz, ajan her yinelemede şema doğrulamalı geçiş/başarısızlık alır ve sahte sunucu henüz oluşturulmamış bağımlılıkların yerini alır, böylece ajan sabit bir hedefe karşı çalışabilir. Bu deseni zaten uygulayan ekipler, ajanın araç erişimini Apidog AI ajan hata ayıklayıcısı gibi bir şey aracılığıyla bağlarlar, böylece ajan insan bir test uzmanının yaptığı gibi uç noktalara ulaşabilir ve bunları inceleyebilir. Test çalıştırıcısını elle yazmak yerine kapıyı görsel olarak oluşturmak isterseniz Apidog'u indirin.

Bugün Minimum Kendi Kendini Düzelten Bir API Döngüsü Oluşturun

Başlamak için bir çerçeveye ihtiyacınız yok. Bir spesifikasyona, bir test komutuna ve birkaç satır yapıştırıcıya (glue code) ihtiyacınız var. İşte gerçek işi yapan en küçük sürüm.

Adım 1: Spesifikasyonu kapının amacı olarak yazın. Sözleşmeyi bir OpenAPI dosyasına, davranışı ise test senaryolarına koyun. Ajan her ikisini de okur. Bu aynı zamanda dokümantasyon görevi de görür, bu yüzden boşa giden bir iş değildir.

Adım 2: Başarısızlık durumunda sıfır olmayan bir çıkış koduyla biten bir test komutu seçin. Çıkış kodu dürüst olduğu sürece her şey çalışır. Bir pytest paketi, bir Newman çalıştırması, bir Apidog CLI test senaryosu. Döngü yalnızca geçiş/başarısızlık ve yakalanan çıktı ile ilgilenir.

# kapı, tek bir komut olarak
apidog run ./tests/orders-suite --reporter json > result.json

Adım 3: Döngüyü bağlayın. Ajanı çalıştırın, kapıyı çalıştırın, sonuca göre dallandırın.

MAX_ITERATIONS = 8
feedback = None
for attempt in range(MAX_ITERATIONS):
    run_agent(task="implement orders API per spec", feedback=feedback)
    gate = subprocess.run(["apidog", "run", "./tests/orders-suite",
                           "--reporter", "json"], capture_output=True)
    if gate.returncode == 0:
        print(f"Deneme {attempt + 1} başarılı")
        break
    feedback = parse_failures(gate.stdout)   # bir sonraki komut kendini yazar
else:
    print("8 deneme, hala kırmızı; bir insana yönlendiriliyor")

Adım 4: Kapıyı koruyun. Test dosyalarını ve spesifikasyonu, ajanın düzenlemesine izin verilen dosyaların dışında tutun. Eğer testi geçecek şekilde yeniden yazabiliyorsa, ilerlemeyi sahte göstermek için bir makine inşa etmiş olursunuz.

Adım 5: Maliyeti sınırlayın. Yinelemeleri sınırlayın. Harcamayı sınırlayın. Her denemeyi günlüğe kaydedin, böylece döngünün yakınsayıp yakınsamadığını veya boşa harcayıp harcamadığını görebilirsiniz. Token harcamasını izliyorsanız, ajan token maliyetlerini azaltma hakkındaki notlarımız doğrudan geçerlidir, çünkü yakınsamayan bir döngü bütçeyi hızla tüketir.

İşte çalışan, kendi kendini düzelten bir döngü. Ajan yazar, paket yargılar, hatalar yönlendirir ve kendinden emin bir yalan yerine yeşil bir uç nokta veya temiz bir yönlendirme (escalation) elde edersiniz.

İyi Döngüler Tasarlamak: Isıran Hatalar

Çalışan döngüleri, sessizce para israf eden döngülerden ayıran birkaç desen vardır.

Ajanın kendi ödevini değerlendirmesine izin vermek. Tek kontrol "ajan, bitirdin mi?" ise, bir döngünüz değil, fazladan adımları olan bir sohbet botunuz var demektir. Kapı ajanın dışında olmalıdır.
Çok kaba bir kapı. Üç sığ testle "Testler geçti" demek, ajanın üç testi karşıladığı ve kapsanmayan her şeyde hatalar gönderdiği anlamına gelir. Döngü kalitesi, kapı kapsamı ile sınırlıdır. Yetersiz testler, yetersiz sonuçlar.
Sonlandırma koruması yok. Maksimum yineleme sayısı ve maliyet tavanı olmayan döngüler, modelin çözemeyeceği bir görev üzerinde sonsuza kadar dönebilir. Her zaman bir çıkış belirleyin ve tetiklendiğinde her zaman bir insana yönlendirin.
Yavaş kapılar. 15 dakikalık bir entegrasyon paketi iyi bir gece kontrolüdür, ancak korkunç bir iç döngüdür. Döngü için hızlı bir kapı ve birleştirme için kapsamlı bir kapı tutun. Döngünün güvenilmez bir üçüncü tarafı beklemesini önlemek için harici bağımlılıkları taklit edin.
Değiştirilebilir spesifikasyonlar. Eğer ajan, hatalı koduna uyması için OpenAPI dosyasını düzenlerse, sözleşme testi yanlış nedenle yeşile döner. Spesifikasyon anayasadır. Ajan onun altında çalışır, üzerinde değil.
Tek bir dev görev. "Tüm hizmeti inşa et" üzerinde çalışan bir döngü nadiren yakınsar. Her biri kendi kapısına sahip, uç nokta boyutunda görevlere ayırın. Küçük döngüler biter; büyük döngüler boşa harcar.

Bunların çoğu aynı disipline dayanır: komuta değil, sinyale yatırım yapın. Buradaki bağlantı kalıpları ve hata modları, ajantik iş akışı araç bağlantısı konusunda ele aldıklarımızla aynı doğrultudadır ve ajanın Claude Code, Cursor, Codex veya kendi oluşturduğunuz bir şey olup olmadığına bakılmaksızın geçerlidir.

Nereye Gidiyor?

"Komut vermeyi bırak, döngü yapmaya başla" ifadesi daha uzun bir eğilimin anlık görüntüsüdür. Değerli hale gelen beceri komut yazarlığı değil. Döngü yaparlığıdır: keskin spesifikasyonlar yazmak, deterministik kapılar oluşturmak, sonlandırma koşullarını seçmek ve ajanın neye dokunmasına izin verildiğini veya verilmediğini kararlaştırmak. Bu, komut mühendisliğinden çok sistem tasarımına daha yakındır ve zaten testler, sözleşmeler ve CI açısından düşünen mühendisleri ödüllendirir.

Aynı zamanda iyi test altyapısının değerini de değiştirir. Yıllardır otomatik testler, asla ihtiyaç duymayacağınızı umduğunuz bir sigorta idi. Ajantik bir iş akışında, hızlı ama güvenilmez bir jeneratörü doğruya yakınsayan bir sisteme dönüştüren direksiyon mekanizması haline gelirler. Halihazırda güçlü otomatik test kapsamına ve temiz sözleşmelere sahip ekipler, ajanları takıp anında kaldıraç elde edenlerdir. Buna sahip olmayan ekipler ise kendinden emin, test edilmemiş kod üretmenin hızlı bir yolunu bulurlar.

Dolayısıyla pratik hareket, daha iyi bir modeli veya daha akıllı bir komutu kovalamak değildir. Kapıyı inşa etmektir. Spesifikasyonlarınızı sıkılaştırın. API testlerinizi deterministik ve hızlı hale getirin. Şemanızı doğruluk kaynağı olarak tutun. Ardından etrafına bir döngü sarın ve kapı yeşile dönene kadar ajanın turlamasını sağlayın.

Önemli Çıkarım

Değişim, ifade etmesi basit ama içselleştirmesi zordur. Kodlama ajanıza komut verme konusunda daha iyi olmayın. Onu komut veren döngüyü ve o döngünün üzerinde çalıştığı geri bildirim sinyalini tasarlama konusunda daha iyi olun. Ajan, doğru olup olmadığına dair güvenilir bir algısı olmayan hızlı bir üreticidir. Döngü, deterministik bir kapı aracılığıyla bu algıyı sağlar. API'ler geliştiren herkes için, kapıya zaten sahipsiniz. Test paketiniz, şemanız ve sözleşmeleriniz, hevesli bir üreticiyi doğruya yakınsayan bir sisteme dönüştüren temel gerçektir.

Küçükten başlayın. Tek bir sıkı spesifikasyon yazın, bir döngüyü hızlı bir API test paketine yönlendirin, kapıyı koruyun, yinelemeleri sınırlayın ve bir ajanın iç döngüde siz olmadan kırmızı bir uç noktayı yeşile döndürdüğünü izleyin. Ardından bir sonraki döngüyü oluşturun. Kapının görsel, şema farkında ve ekibiniz arasında paylaşılabilir olmasını istiyorsanız, Apidog size tasarımı, sahteleme (mocking) ve otomatik testleri tek bir çalışma alanında sunar; indirin ve testlerinizi ajanlarınızı çalıştıran şey haline getirin.

düğme