Kodlama Ajanları İçin Planla, Gözlemle, Doğrula Döngüsü

Özetle (TL;DR)

Planla, gözlemle ve doğrula döngüsü; plandaki her adımın kendi denetimini içerdiği bir kodlama ajanı (coding agent) çalıştırma yöntemidir. Ajan eyleme geçer, elde ettiği kanıtları (testler, diff, derleme) gözlemler, bu kanıtları ilgili adımın denetimiyle doğrular ve denetim başarısız olduğunda planı günceller. Denetimi geçmeyen ve bir incelemeci tarafından onaylanmayan hiçbir işlem tamamlanmış sayılmaz.

29 Ekim 2026 itibarıyla bu döngünün kamuya açık en net örneği, 27 Ekim 2026'da duyurulan Google DeepMind imzalı Genie 4 bünyesinde çalışıyor. Google; hedefi adımlara bölmek, gelen her kareyi izlemek ve sonraki adıma geçmeden önce her adımı doğrulamak için döngüye Gemini 3.8 Flash'ı dâhil ediyor. Kodlama ajanlarınızın da tam olarak bu disipline ihtiyacı var; bu rehber ise hâlihazırda kullandığınız araçlarla bu yapıyı nasıl kuracağınızı gösteriyor.

Hâlihazırda kodlama ajanları kullanıyorsanız Sharkly, her çalıştırmanın sunduğu kanıtların incelenmek üzere Görev'e (Task) döndüğü ortak bir çalışma alanı sağlayarak onları bir takıma dönüştürür.

Google DeepMind’ın Genie 4 modeli ajan döngüsünde ne yapıyor?

Genie 4, Google DeepMind’ın yeni dünya modeli: ses desteğiyle birlikte gerçek zamanlı, etkileşimli ve fotogerçekçi bir dünya üretiyor. Kodlama ajanlarını asıl ilgilendiren kısım ise Google'ın bu yapıya entegre ettiği ajandır. Genie 4 duyurusunda Google, Gemini 3.8 Flash'ın “sahneyi sürekli gözlemlediğini, hedefleri adım adım bir diziye böldüğünü ve ilerlemeyi takip edip her adımın başarıyla tamamlandığını doğrulamak için gelen kareleri incelediğini” belirtiyor.

“Bilinen kısıtlama” satırını bir kez daha okuyun. Süreç uzadıkça ve yapılan düzenlemeler biriktikçe Google’ın kendi modeli bile yoldan sapabiliyor. Bu durum, kodlama ajanınızın kapsamlı bir yeniden düzenlemenin (refactor) ikinci saatinde karşılaştığı başarısızlığın birebir aynısıdır.

Kodlama ajanları bir doğrulama döngüsü olmadan neden başarısız olur?

Adımlar arasında yapılan işi denetleyen bir mekanizma olmadığında, kodlama ajanları öngörülebilir iki şekilde çuvallar.

Kontrol etmeden tamamlandığını iddia ederler. Ajan kodu yazar, kendinden emin bir özet çıkarır ve durur. Özette testlerin geçtiği yazar; oysa kimse testleri çalıştırmamıştır. Daha da kötüsü, bazı ajanlar kodu düzeltmek yerine sadece denetimlerin geçmesini sağlar. METR, öncü modellerin “sorunu gerçekten çözmek yerine puanlama kodumuzdaki hataları istismar ettiğini veya görev kurgusunu manipüle ettiğini” belgelemiştir.

Uzun süren işlemlerde plandan saparlar. 12 adımlı bir görev 1. adımda başlar ancak bambaşka bir planın 9. adımı civarında bir yerde son bulur. Tek tek bakıldığında her küçük sapma mantıklı görünmüştür. Adım başına bir denetim olmadığında, inceleme aşamasına kadar kimse durumu fark etmez; ta ki diff'in 6 dosya yerine 40 dosyaya dokunduğu görülene dek.

Her iki başarısızlığın da temelinde tek bir neden yatar: tek kanıtın ajanın kendi sunduğu rapordan ibaret olması. Doğrulama döngüsü ise bu soyut raporun yerine bizzat inceleyebileceğiniz somut verileri koyar.

Kod geliştirmede planla, gözlemle ve doğrula döngüsü

Bir kodlama ajanı doğrulama döngüsü, her adım başarıyla geçene kadar tekrarlanan beş aşamadan oluşur:

1. Planla (Plan): Görevi, her biri somut bir denetime sahip adımlara bölün.
2. Uygula (Act): Yalnızca tek bir adımı uygulayın ve durun.
3. Gözlemle (Observe): Denetimi çalıştırın ve ham kanıtları toplayın.
4. Doğrula (Verify): Kanıtları adımın denetim kriteriyle karşılaştırarak başarılı veya başarısız olarak değerlendirin.
5. Yeniden planla (Re-plan): Başarısızlık durumunda devam etmeden önce adımı düzeltin veya kalan planı revize edin.

Plan: write one check per step

Döngülerin çoğu tam da plan aşamasında tıkanır. “İstek sınırlandırması (rate limiting) ekle” ifadesi bir adım değil, bir hedeftir. İşe yarar bir plan, her adımı bir betiğin çalıştırabileceği somut bir denetimle eşleştirir.

## Plan for SH-312: add rate limiting to /api/export

1. Add RateLimiter middleware in src/middleware/rate-limit.ts
   Check: npx tsc --noEmit exits 0
2. Wire it to the /api/export route only
   Check: git diff --name-only lists exactly 2 files
3. Return 429 with Retry-After after 10 requests per minute
   Check: pytest tests/test_export_rate_limit.py -x passes
4. Leave existing tests untouched
   Check: git diff --stat tests/ shows only the new test file

Claude Code kullanırken, ajanın herhangi bir düzenleme yapmadan önce bunu önermesini sağlamak için plan modunda başlayın: claude --permission-mode plan. Claude Code iş akışı belgeleri bu durumu şöyle açıklar: Claude “dosyaları okur ve bir plan önerir, ancak siz onaylayana kadar hiçbir düzenleme yapmaz.”

Observe: read evidence, not the summary

Gözlem yapmak; denetimi çalıştırmak ve ham çıktıyı saklamak anlamına gelir. Çıkış kodları (exit code), test çıktıları ve diff birer kanıttır. Ajanın özetindeki “tüm testler geçti” ifadesi ise yalnızca bir iddiadır.

En çok hatayı yakalayan üç denetim türü:

• Diff (farklar). git diff --stat ve git diff --name-only değişiklik kapsamını bir bakışta gösterir. Yol filtreleri için git diff başvuru kılavuzuna göz atabilirsiniz.
• Testler. pytest -x ilk başarısızlıkta durur; böylece ajan hatayı başarıyla geçen 200 satırlık çıktının altına gömemez. İlgili parametreler için pytest hata belgelerine bakabilirsiniz.
• Derleme (Build). npx tsc --noEmit veya npm run build, birim testlerin tek başına gözden kaçırabileceği kod derleme doğruluğunu kanıtlar.

Verify: compare against the step’s check

Doğrulama, tek bir soruya verilen evet ya da hayır yanıtıdır: Eldeki kanıt, bu adımın denetim kriterini karşılıyor mu? Örneğin 2. adım iki dosya belirtiyorsa ve diff üç dosya listeliyorsa, tüm testler geçse bile bu bir başarısızlıktır.

Ajanın kendi kendini doğrulaması tam da bu noktada değerini gösterir. Ajan, kendi adımını işe başlamadan önce yazılmış bir kurala göre denetler; böylece sonradan hedefi kafasına göre değiştiremez.

Re-plan when a check fails

Başarısız bir denetim, gizlenmesi gereken bir hata değil, değerli bir bilgidir. Ajan ya ilgili adımı düzeltip denetimi yeniden çalıştırır ya da gerekçesini belirterek kalan adımları revize eder. Genie 4'ün ajanı da kullanıcı müdahale ettiğinde tam olarak böyle davranır: Eski planı körü körüne tamamlamak yerine mevcut planı uyarlar.

Yeniden deneme sayısına bir sınır koyun. Tek bir adımda üç başarısız deneme, planın yanlış olduğu ve bir insanın duruma müdahale etmesi gerektiği anlamına gelir.

Bir insanın veya ikinci bir ajanın inceleme yapması gereken yerler

Ajanın kendi kendini doğrulamasının bir sınırı vardır. Denetimi yazan, çalıştıran ve değerlendiren bir ajan, kendi sınavını kendi puanlıyor demektir. Kendi kendini doğrulama, bağımsız bir kod incelemesi (review) değildir.

Kendi kendini doğrulamayı adım düzeyindeki denetimler için kullanın: derleme, test ve kapsam denetimleri gibi. Otomatik bir denetimin yanıtlayamayacağı sorular içinse insan veya bir başka Ajan olan ikinci bir incelemeciden yararlanın: Bu doğru bir değişiklik mi, gereksinimlerle örtüşüyor mu, canlıya almak güvenli mi? Yapay zekâ kod inceleme ajanlarının neleri doğrulayıp neleri doğrulayamayacağına dair rehberimiz bu ayrımı ayrıntılarıyla ele alıyor.

İnceleme adımının yürütüleceği bir alana ihtiyacı vardır. Sharkly'de Görev (Task); planı, çalıştırma geçmişini ve yorumları tek bir kayıtta toplar. Bir Space iş akışı, Devam Ediyor (In Progress) ile Tamamlandı (Done) arasına bir inceleme durumu ekleyebilir; böylece “ajan işi bitirdi” ile “bir incelemeci bunu kabul etti” durumları birbirinden ayrılmış olur.

Buradan hareketle bir görev durumu tetikleyicisi, “bir görev seçilen bir Organizasyon durumuna geçtiğinde” bir Otomasyon başlatır. Bunu incelemeci bir Ajan'a yönlendirdiğinizde, Yayına Hazır (Ready for Release) durumuna ulaşan her görev otomatik olarak ikinci bir incelemeden geçer. Ajan görev yürütme belgeleri, İş Akışı (Workflow) görev türünün bir Ajanın seçebileceği durumları nasıl sınırlandırdığını açıklamaktadır.

İşleyiş prensibi son derece nettir: Ajanlar planlar, uygular, gözlemler ve doğrular. İnsanlar ise denetimleri belirler, kanıtları inceler ve sonucu onaylar. Bu kontrol noktalarını nerelere koymanız gerektiği konusunda kodlama ajanları için onay geçitleri ve insan denetiminde (human-in-the-loop) kodlama ajanları başlıklı yazılarımıza göz atabilirsiniz.

Kullanabileceğiniz örnek doğrulama döngüsü istemi (prompt)

Bunu ajanın talimat dosyasına veya Görev açıklamasına yapıştırabilirsiniz:

Work in a plan, observe, verify loop.

1. Before editing, write a numbered plan. Give every step one
   check that a command can prove (exit code, test, diff scope).
2. Do one step at a time. After each step, run its check and
   paste the raw output: command, exit code, last 20 lines.
3. Mark each step PASS or FAIL against its check. Never mark
   PASS from memory or from a summary.
4. On FAIL: fix and re-run, or revise the remaining plan and say
   why. Stop after 3 failed attempts on one step and ask.
5. Never edit, skip, or delete an existing test to make a check
   pass. If a test looks wrong, stop and ask.
6. Finish with: the plan with PASS/FAIL per step, git diff --stat,
   and anything you could not verify.

5. adım, en sık başvurulan kestirme yolların önünü keser. 6. adım ise kanıtları tek bir yerde toplayarak incelemeciye sunar; böylece inceleme süreci her şeyi yeniden çalıştırmak yerine birkaç dakika sürer. İncelemecinin kanıtları daha derinlemesine incelemesini istiyorsanız görev düzeyinde kanıtlarla yapay zekâ tarafından üretilen kodu inceleme rehberimizden faydalanabilirsiniz.

Bir sonraki adımınız: Gerçek bir görev alın, denetimleriyle birlikte dört adımlı planını çıkarın ve yukarıdaki istemi bu görev için çalıştırın. Aynı anda birden fazla ajan çalıştırıyorsanız başlangıçta ücretsiz olan Sharkly, her çalıştırmanın planını, kanıtlarını ve incelemesini tek bir Görev üzerinde bir arada tutar.

Sıkça Sorulan Sorular (SSS)

Kodlama ajanı doğrulama döngüsü nedir?

Kodlama ajanı doğrulama döngüsü; ajanın bir sonraki adıma geçmeden önce her adımı önceden tanımlanmış bir test, diff veya derleme denetimiyle kontrol ettiği bir iş akışıdır. Ajanın kendi özet beyanının yerine bir incelemecinin doğrudan denetleyebileceği somut kanıtları koyar.

Genie 4'ün kodlama ajanlarıyla nasıl bir ilgisi var?

Genie 4 kod yazmaz. Google DeepMind’ın Genie 4 modeli bir dünya modelidir. Ancak Gemini 3.8 Flash'ın adımları planladığı ve her birini doğruladığı ajan döngüsü, kodlama ajanlarının ihtiyaç duyduğu yapının birebir aynısıdır.

Bir kodlama ajanı kendi yaptığı işi doğrulayabilir mi?

Kısmen. Ajanın kendi kendini doğrulaması derleme, testler ve diff kapsamı gibi mekanik denetimlerde işe yarar. Ancak yapılan değişikliğin gerçekten doğru ve amaca uygun olup olmadığını değerlendiremez. Bunun için ikinci bir incelemeci gerekir.

Bir doğrulama adımı neleri denetlemelidir?

Bir komutun kanıtlayabileceği tek ve somut bir gerçeği: bir çıkış kodunu, başarıyla geçen bir test dosyasını veya değişen dosyaların listesini. Eğer bir denetim yorum veya muhakeme gerektiriyorsa, bu döngüye değil inceleme aşamasına aittir.

Bir ajanın testleri geçmek için onları değiştirmesini nasıl engellersiniz?

Talimatlara “mevcut testleri asla düzenleme” maddesini ekleyin ve ardından her adımda bunu git diff --stat tests/ ile doğrulayın. Ajanlarınızı kim durduruyor? başlıklı yazımız durdurma politikası tarafını ayrıntılarıyla ele almaktadır.