Prompt Yazmak Yetmiyor: Yapay Zekâ Ajanları İçin Döngü Tasarlamak

Bir yapay zekâ ajanına ne yapacağını söylemek prompt tasarımıdır. Ne zaman yeniden deneyeceğini, neyin başarı sayılacağını ve hangi koşulda duracağını belirlemek ise döngü tasarımıdır. Ajanların gerçek gücü tek seferde iyi cevap vermelerinden değil; gözlemleyip eyleme geçebilmeleri, sonucunu kontrol etmeleri ve gerektiğinde yeniden çalışabilmelerinden gelir.

Fakat “ajanı döngüye alalım” demek tek başına bir tasarım değildir. Sınırı çizilmemiş bir döngü daha çok düşünür, daha çok araç çağırır ve daha çok token harcar; buna rağmen daha doğru bir sonuca ulaşmak zorunda değildir. İyi bir döngü, tekrar sayısını değil tekrarın nedenini ve durma kanıtını tanımlar.

Döngünün amacı ajanı sürekli çalıştırmak değil, doğrulanabilir bir sonuca kadar kontrollü biçimde çalıştırmaktır.

Ajan döngüsü nedir?

Claude Code ekibinin kullandığı tanım oldukça yalın: Döngü, bir ajanın durma koşulu karşılanana kadar çalışma çevrimlerini tekrarlamasıdır. Bu çevrim genellikle beş parçadan oluşur:

Tetikle → Bağlamı topla → Eyleme geç → Sonucu doğrula
  ↑                                           │
  └──────── devam koşulu karşılandı ──────────┘
                              │
                        durma koşulu
                              ▼
                             Bitir

Bu şemada model yalnızca eylem üretmez. Bir sonraki adımı seçmek için dünyanın yeni hâlini de okur: test sonucu, pull request yorumu, hata kaydı, performans skoru veya kullanıcının cevabı yeni bağlama dönüşür.

Bu nedenle bir döngü dört soruya cevap vermelidir:

1. Ne tetikleyecek? İnsan mesajı mı, hedef değerlendirmesi mi, zaman mı, haricî bir olay mı?
2. Her turda ne yapılacak? Aynı prompt mu çalışacak, yoksa sonuçlara göre plan mı değişecek?
3. Kim doğrulayacak? Ana ajan, ayrı bir değerlendirici, test komutu veya insan mı?
4. Ne zaman duracak? Hedef sağlandığında mı, süre dolduğunda mı, ilerleme kesildiğinde mi?

Döngü, otomasyon ve ajan aynı şey değildir

Her tekrar eden iş ajan gerektirmez. Bir dosya adını standartlaştırmak, aynı form alanlarını doldurmak veya belirli bir komutu çalıştırmak tamamen deterministikse bunu bir script daha ucuz, hızlı ve güvenilir yapar.

Ajan, adımların önceden bütünüyle yazılamadığı yerde değerlidir. Hangi dosyanın değişeceğine, hangi hatanın önce çözüleceğine veya kanıtların yeterli olup olmadığına çalışma sırasında karar verir. Döngü ise bu karar verme çevrimini hangi sınırlar içinde tekrarlayacağını düzenler.

İyi mimaride bu üçü birbirinin rakibi değildir. Ajan belirsiz kararı verir, script deterministik işi yapar, döngü de ikisinin ne zaman yeniden çalışacağını yönetir.

Dört temel döngü türü

Gönderiye bağlı “Getting started with loops” makalesi döngüleri tetiklenme ve durma biçimlerine göre dört grupta ele alıyor. En faydalı ayrım, insanın sisteme hangi kararı devrettiğine bakmaktır.

1. Tur bazlı döngü: Bir sonraki adımı insan başlatır

Günlük ajan kullanımının büyük bölümü aslında tur bazlı bir döngüdür. Siz görev verirsiniz; ajan kodu okur, değişikliği yapar, testleri çalıştırır ve sonucu sunar. Sonraki turu yeni bir mesajla siz başlatırsınız.

Bu yapı keşif, karar verme ve tek seferlik kısa işler için uygundur. Döngünün tamamını devretmezsiniz; fakat doğrulama adımlarını bir skill veya proje talimatı hâline getirerek ajanın kendi turu içinde daha güvenilir çalışmasını sağlayabilirsiniz.

Görev: Profil sayfasına tema seçici ekle.

Teslimden önce:
1. Tip kontrolünü çalıştır.
2. Sayfayı açık ve koyu temada aç.
3. Kontrole tıkla ve durumun değiştiğini doğrula.
4. Konsolda yeni hata bulunmadığını kontrol et.
5. Başarısız bir adım varsa düzeltip baştan doğrula.

Burada “bitti” kararı yalnızca kodun yazılmasına bağlı değildir. Ajanın görebileceği ve ölçebileceği bir kontrol listesine bağlanmıştır. Bu listeyi her promptta tekrar etmek yerine bir SKILL.md içine koymak, doğrulama davranışını yeniden kullanılabilir hâle getirir.

2. Hedef bazlı döngü: Durma koşulunu sisteme devredersiniz

Bazı işler tek turda bitmez ama başarı ölçütü nettir. Testlerin tamamının geçmesi, Lighthouse skorunun 90’ı aşması veya taşınacak eski API çağrısının kalmaması buna örnektir.

Hedef bazlı döngüde ajan çalışır; her turun sonunda ayrı bir kontrol hedefin sağlanıp sağlanmadığını değerlendirir. Hedef karşılanmadıysa sonuç, bir sonraki turun bağlamına dönüşür.

/goal Ana sayfanın Lighthouse performans skoru en az 90 olsun;
beş denemeden sonra hâlâ sağlanmadıysa dur ve engelleri raporla.

Bu örnek Claude Code’un /goal komutunu kullanıyor. Aynı desen başka bir ajan sisteminde de kurulabilir: bir orchestrator ana ajanı çalıştırır, bağımsız değerlendirici başarı koşulunu kontrol eder ve tur sınırına kadar yeniden çağırır.

Buradaki kritik nokta “siteyi hızlandır” gibi yoruma açık bir hedef yerine ölçülebilir bir çıkış tanımlamaktır. Ayrıca her hedefin ikinci bir freni olmalıdır: maksimum tur, zaman, maliyet veya ilerleme sınırı.

3. Zaman bazlı döngü: Tetikleyiciyi sisteme devredersiniz

Bazen çalışma bir önceki turun bitmesiyle değil, dış dünyanın değişmesiyle devam eder. Pull request’e yeni yorum gelmesi, CI çalışmasının tamamlanması veya dağıtımın hazır hâle gelmesi bekleniyorsa ajan belirli aralıklarla durumu kontrol edebilir.

/loop 5m Pull request durumunu kontrol et;
yeni inceleme yorumlarını ele al ve başarısız CI adımlarını düzelt.

Claude Code’daki /loop açık oturumda ve yerel makinede çalışır. Resmî dokümana göre sabit veya dinamik aralık kullanılabilir; sabit döngüler kullanıcı durdurana kadar, görev tamamlanana kadar veya yedi günlük süre dolana kadar devam eder. Makine ve oturumdan bağımsız kalıcı işler için bulut rutinleri ya da başka bir scheduler gerekir.

Zaman bazlı döngünün en yaygın hatası gereğinden sık sorgulamadır. Bir CI çalışması ortalama on dakika sürüyorsa her otuz saniyede aynı durumu modele okutmak sonucu hızlandırmaz; yalnızca maliyet ve gürültü üretir. Sistem olay gönderebiliyorsa webhook gibi event tabanlı tetikleyici çoğu zaman polling’den daha iyidir.

4. Proaktif döngü: İyi tanımlanmış işi sisteme devredersiniz

Proaktif döngüde o anda görev veren bir insan yoktur. Zaman, API çağrısı veya GitHub olayı yeni bir çalışma başlatır. Her çalışmanın kendi hedefi ve durma koşulu vardır; rutin ise kapatılana kadar yeni işleri kabul etmeyi sürdürür.

Örneğin bir destek akışı şu parçalardan oluşabilir:

1. Her saat veya yeni kayıt olayında hata bildirimlerini topla.
2. Her bildirimi önem, tekrar üretilebilirlik ve etkilenen alan açısından sınıflandır.
3. Uygun olanları farklı çalışma alanlarında paralel ajanlara ver.
4. Ayrı bir inceleme ajanıyla değişiklikleri eleştirel biçimde kontrol et.
5. Testler geçmeden ve yanıt gönderilmeden çalışmayı tamamlanmış sayma.

Bu desen güçlü olduğu kadar risklidir. İnsan başlatmadığı için kaynak erişimi, izinler, bildirim sınırı ve geri alınabilirlik baştan tanımlanmalıdır. Claude Code’un bulut rutinleri bu tür zaman, API ve GitHub tetikleyicilerini destekliyor; fakat 16 Temmuz 2026 tarihli dokümantasyonda hâlâ research preview olarak işaretleniyor.

Döngünün kalitesi doğrulayıcının kalitesini geçemez

Ajanın aynı işi beş kez denemesi, her turda aynı zayıf ölçüte bakıyorsa güvenilirlik üretmez. Doğrulama “kod güzel görünüyor” gibi öznel bir model kararıysa döngü yalnızca bu öznel kararı tekrarlar.

Doğrulama kanıtlarını güç sırasına koyabiliriz:

1. Deterministik kontrol: Derleme tamamlandı, 148 test geçti, şema doğrulandı.
2. Ölçülebilir eşik: Performans skoru 90’ın üzerinde, hata oranı yüzde 1’in altında.
3. Bağımsız model incelemesi: Yeni bağlama sahip ikinci ajan değişikliği eleştirel değerlendiriyor.
4. İnsan onayı: Ürün, güvenlik veya geri dönüşü zor kararlar yetkili kişiye sunuluyor.

En iyi döngüler bu kanıtları birlikte kullanır. Testlerin geçmesi gerekli olabilir ama ürün davranışının doğru olduğunu tek başına kanıtlamaz. Görsel bir değişiklikte tarayıcı etkileşimi, ödeme akışında sandbox işlemi, veri göçünde satır sayısı ve örnek kayıt kontrolü gerekir.

Durma koşulu nasıl yazılır?

Bir durma koşulu üç parçadan oluşmalıdır:

Başarı kanıtı + güvenlik sınırı + başarısızlık raporu

Örnek:
Tüm testler geçtiğinde bitir;
en fazla 6 tur çalış;
aynı hata 3 kez tekrarlanırsa dur ve kök nedeni raporla.

Bu yapı iki kötü uçtan korur. Ajan ilk makul sonuçta erken duramaz; çünkü başarı kanıtı eksiktir. Sonsuza kadar da deneyemez; çünkü tur ve ilerleme sınırı vardır.

Token ve maliyet sınırı sonradan eklenmez

Döngü tasarımında maliyet, çalışma bittikten sonra bakılan bir rapor değil mimarinin parçasıdır. Özellikle paralel ajan kullanan dinamik iş akışları tek konuşmadan çok daha fazla token tüketebilir.

• En basit primitive ile başlayın: Tek tur yeterliyse hedef veya workflow kurmayın.
• Deterministik işi script’e verin: Aynı dönüşümü modele her tur yeniden düşündürmeyin.
• Modeli göreve göre seçin: Sınıflandırma ve kontrol için hızlı model, belirsiz mimari karar için güçlü model kullanın.
• Küçük örnekle pilot yapın: Yüz dosyalık göçten önce beş dosyada maliyet ve hata biçimini görün.
• Aralığı değişim hızına uydurun: Dış sistem saatte bir değişiyorsa dakikalık polling kurmayın.
• Kullanımı görünür yapın: Tur, token, araç çağrısı ve paralel ajan sayısını kaydedin.

En sık yapılan altı döngü hatası

1. “Daha iyi olana kadar devam et” demek

“Daha iyi” ölçülemediği için ajan ya erken durur ya da küçük değişikliklerle gereksiz turlar üretir. Ölçütü kullanıcı davranışı, test veya puan eşiğine çevirin.

2. Yapan ve onaylayanı aynı bağlama kapatmak

Ana ajan kendi çözümüne bağlanabilir. Kritik değişikliklerde taze bağlama sahip ikinci inceleyici veya deterministik kontrol kullanın.

3. İlerleme olmadığını fark etmemek

Aynı hata aynı çözümle tekrar ediyorsa daha fazla tur çözüm değildir. “Aynı engel üç tur sürerse dur” gibi bir ilerleme koşulu tanımlayın.

4. Polling’i olay sanmak

Sürekli “değişti mi?” diye sormak yerine dış sistem webhook veya kanal sunuyorsa değişikliği doğrudan döngüye iletin.

5. Yetkiyi görevle birlikte sınırsız vermek

Uzun süre çalışması gereken ajan, her aracı kullanmak zorunda değildir. Okuma, yazma, dağıtım, mesaj gönderme ve silme izinlerini ayrı değerlendirin.

6. Her şeyi paralelleştirmek

Bağımlı işleri aynı anda çalıştırmak hız değil çakışma üretir. Paralel ajanlar bağımsız araştırma, farklı çözüm önerileri veya ayrık dosya gruplarında değerlidir.

Intent, context ve loop tasarımı nasıl birleşiyor?

Bu serideki kavramlar birbirinin yerine geçmez; aynı sistemin farklı sorularını çözer:

• Intent engineering, neden çalıştığımızı ve başarılı sonucun ne olduğunu tanımlar.
• Context engineering, her turda hangi bilginin karar ortamına gireceğini belirler.
• Ajan tasarımı, modelin hangi araçlarla eyleme geçebileceğini düzenler.
• Döngü tasarımı, neyin yeni tur başlatacağını ve sistemin hangi kanıtla duracağını belirler.

Güvenilir ajan sistemi =
Niyet × Bağlam × Araçlar × Doğrulama × Durma koşulu

Çarpanlardan biri sıfıra yaklaştığında daha güçlü model veya daha uzun döngü sistemi kurtarmaz. Niyet belirsizse ajan yanlış hedefe hızla gider. Bağlam kötüyse her tur aynı yanlış bilgiyi büyütür. Doğrulama zayıfsa hata başarı gibi görünür. Durma koşulu yoksa maliyet kontrolsüzleşir.

İlk döngünüzü kurmak için yedi adım

1. Dar bir darboğaz seçin. Her gün yaptığınız bütün işi değil, sık tekrarlanan tek bir parçayı ele alın.
2. Girdiyi tanımlayın. Issue, PR, hata kaydı veya dosya grubu döngüye nasıl girecek?
3. Başarı kanıtını yazın. Hangi test, eşik veya insan onayı “bitti” diyecek?
4. İkinci freni ekleyin. Maksimum tur, süre, token veya maliyet koyun.
5. Yetkiyi daraltın. Ajanın okuyacağı, değiştireceği ve asla dokunmayacağı alanları ayırın.
6. Küçük ölçekte çalıştırın. Sonuçları, harcanan süreyi ve başarısızlık biçimini gözlemleyin.
7. Düzeltmeyi sisteme kodlayın. İnsan incelemesinde tekrarlanan uyarıyı skill, test veya politika hâline getirin.

Son söz

Prompt, ajana bir sonraki işi söyler. Döngü ise sistemin iş yapma biçimini tanımlar. Tetikleyici, doğrulayıcı, durma koşulu, bütçe ve yetki sınırı birlikte düşünülmediğinde ajan yalnızca daha uzun çalışan bir sohbet modeline dönüşür.

İlk hedefiniz tam otonomi olmamalı. Önce insanın darboğaz olduğu tek bir adımı bulun. Doğrulamasını yazın, dar bir sınır koyun ve döngüyü gözlemleyin. Güvenilir otonomi, insanı bir anda sistemden çıkarmakla değil; verdiği kararları tek tek görünür ve denetlenebilir hâle getirmekle kurulur.

Kaynaklar

• ClaudeDevs — Getting started with loops
• Claude Code — /goal ile hedef bazlı çalışma
• Claude Code — /loop ve zamanlanmış görevler
• Claude Code — Bulut rutinleri
• Claude Code — Skills
• Claude Code — Dinamik iş akışları