Doğrulanabilir bir /goal koşulu nasıl yazılır?

Şöyle düşünün: ajandan, hazır bir tarayıcı oyununda bir parti oynamasını istiyorsunuz. Birkaç hamle yapıyor, pozisyonu anlatıyor ve susuyor. Oyun hâlâ devam ediyor. Siz "devam et" yazıyorsunuz. Taşları yeniden oynatıp yine mesajınızı bekliyor. Bir noktada, buradaki en tekdüze işi sizin yaptığınız ortaya çıkıyor.

Goal, /goal komutuyla ajana verdiğiniz, tamamlanma koşulu olan bir hedeftir. Örneğin: "Sayfa oyunun bittiğini gösterene kadar iki tarafla da oynayın." Her çalışma turundan sonra ayrı bir model, konuşmayı inceleyip hedefe ulaşılıp ulaşılmadığını denetler. Henüz ulaşılmadıysa, siz "devam et" demeden çalışma sürer. Böylece sonucu bekleyebilirsiniz; ancak bir engel ya da hata çalışmayı daha erken durdurabilir.

Önce oyun için hazır bir koşula bakalım, ardından arama, form ve mobil sayfa için hedefler oluşturalım. Her birinin sonucu açık olacak ve nasıl doğrulanacağı belli olacak. Ayrıca ajandan sizin için bir koşul yazmasını nasıl isteyeceğinizi ve gerçek tamamlanmayı sonuç alınmadan durmaktan nasıl ayırt edeceğinizi de ele alacağız.

/goal çalışmayı nasıl sürdürür?

Oyun örneğiyle ilgili konuşmada, kolayca karıştırılabilen iki ayrı mekanizma var. Biri tarayıcıda işlem yapar: tıklar, hamleleri girer ve sayfanın ne gösterdiğini okur. Diğeri hiçbir yere tıklamaz; konuşmanın tamamını okuyup çalışmanın sürüp sürmeyeceğine karar verir.

İlki, önceden MCP üzerinden bağlanan tarayıcı aracı Playwright'tır. İkincisini /goal komutu başlatır. Playwright taşları oynatır, /goal durma zamanının gelip gelmediğine karar verir; dışarıdan aynı işlem gibi görünse de bunlar iki farklı iştir.

Önemli bir ayrıntı: değerlendirme her fare tıklamasından sonra değil, ajan çalışma turunu, kabaca yanıtının tamamını bitirdikten sonra yapılır. Böyle bir tur içinde ajan art arda birkaç işlem yapabilir: bir taşı oynatır, sonucu okur ve buna göre hareket eder. /goal ancak değerlendirilecek bir şey oluşunca devreye girer.

Oyunu çalışmaya hazırlayın

Koşulu belirlemeden önce örnek çalışır durumda olmalıdır: sayfa bilinen bir adreste açılmalı, oyun için gereken araçlar (bu örnekte Playwright) bağlı olmalı ve sayfada oyunun bitip bitmediğini gösteren bir işaret bulunmalıdır.

Örneğimizde bu bir data özniteliği: oyun sürerken data-game-over="false", bittiğinde data-game-over="true". Bu düzeni oyun sayfasını yazan kişi belirler; ajan bunu kendisi uydurmaz, yalnızca okur.

Bunu doğrulamak kolay: ajandan sayfayı açıp özniteliğin değerini okumasını isteyin. Yeni başlamış bir oyunda ajan false değerini alır. Bu normaldir; başlangıçta olması gereken de budur.

Sayfada bu öznitelik hiç yoksa hedef belirlemek için erkendir. Koşul yalnızca gerçekten okunabilen bir şeye dayanabilir. Bu yüzden önce işareti geri getirmek gerekir; hemen oracıkta yerine başka bir şey uydurmayın. Örnek hazırlandıktan sonra da oyun sürerken ölçütü değiştirmeyin veya gösteri daha çabuk bitsin diye oyuna ayrıca bir zamanlayıcı eklemeyin. Koşul baştan sona aynı kalır.

Hazır hedefi başlatın

Sırada komutun kendisi var. Örneğimizde koşul şöyle ifade edilebilir:

/goal sayfa arayüzü üzerinden sırayla iki tarafla da oynayın.
Her hamleden sonra data-game-over değerini okuyun ve
sayfada ne göründüğünü gösterin. data-game-over true
olduğunda oyun tamamlanmış sayılır. 40 hamleden sonra
bu gerçekleşmezse durun ve nerede takıldığınızı açıklayın.
Oyunun kodunu değiştirmeyin.

İfadeyi parçalara ayıralım. Aynı parçalar kendi işlerinizde de işinize yarar:

• "...sayfa arayüzü üzerinden oynayın" - ajanın konuşmada gerçekten gösterebileceği, ölçülebilir bir işlem;
• "data-game-over true olduğunda oyun tamamlanmış sayılır" - burada gerçek sonuç olarak kabul edilen tek şey. Değerlendirici konuşmada tam da bunu arayacak;
• "her hamleden sonra okuyun... ve gösterin" - değerlendiricinin bir şeyi denetleyebilmesini sağlayan olgu. Bu satır olmazsa bakacağı bir şey yok;
• "40 hamleden sonra bu gerçekleşmezse durun ve açıklayın" - true değerinin hiç gelmemesi durumu için ayrı bir talimat. Başarının parçası değil, sonuç alınmadan çalışmayı durdurmanın yolu: hedefin kapsamını sınırlar ama sonucun yerini tutmaz. Bu hâlâ metindeki bir talimattır, programlanmış katı bir zamanlayıcı değildir; konuşmaya göre o da değerlendirilir;
• "oyunun kodunu değiştirmeyin" - ajan sonuca ulaşmaya çalışırken gerçekleşmemesi gereken şey.

Sonucun ne olacağı önceden bilinmez; belirli bir kazananı, oyunun ne kadar süreceğini, hatta bitip bitmeyeceğini bile garanti edemezsiniz. Ama ajanın ne göstermesi gerektiği açık: okuduğu oyun durumu ve çalışmayı neden sürdürdüğü ya da durdurduğu.

Kendi koşulunuzu nasıl oluşturursunuz?

"İş şu durumda tamamlanmış sayılır..." diye başlayın. Devamı "her şey daha iyi oldu" gibi geliyorsa, ne demek istediğinize ajanın kendisi karar vermek zorunda kalır. Değerlendirme yerine görülebilir bir davranış tanımlayın: "arama temizlendikten sonra tüm kartlar yeniden görünür". Birkaç kontrol de olabilir; yeter ki hepsi tek bir sonucu, örneğin düzeltilmiş aramayı anlatsın.

• Sonucu adlandırın. "Aramayı düzelt" yalnızca yön gösterir; "arama, ada göre kartı bulur ve temizlendikten sonra tüm listeyi geri getirir" ise tamamlanma noktasını tanımlar.
• Nasıl denetleneceğini belirtin. Neyi açacağını, ne gireceğini ve hangi yanıtın beklendiğini yazın. Değerlendiricinin okuyabilmesi için ajandan gerçek sonucu konuşmada göstermesini isteyin.
• Değişiklikleri sınırlayın. Yalnızca stillerin değişmesi gerekiyorsa bunu söyleyin. Ajan hazır bir oyunu test ediyorsa, istediğiniz sonucu almak için kodunu değiştirmesini yasaklayın.
• Başarı olmadan durma durumunu da planlayın. Örneğin, düzeltme ve yeniden denetleme için üç denemeden sonra ajan kalan sorunu açıklamalıdır. Bu, çalışmanın sınırıdır; işi tamamlandı saymanın başka bir yolu değil.

Başlatmadan önce ajanın gereken sayfaya, dosyalara ve araçlara erişebildiğini kontrol edin. Koşuldaki adres ve öğe adları projenize ait olmalı. Deneme sayısı için metinsel bir sınır çalışmayı yönetmeye yardımcı olur, ancak süre ya da maliyet için katı bir teknik limit değildir.

Geri dönen oka dikkat edin. Sonuca henüz ulaşılmadıysa ajan yeni bir çalışma turu alır; sorunu düzeltip yeniden denetleyebilir. Ancak bu döngüden çıkmak her zaman başarı anlamına gelmez: engeli ya da belirlenen sınırı ayrıca belirtmek gerekir. Şema, koşulun işleyiş mantığını gösteriyor; deneme sınırını ajan ve değerlendirici konuşma üzerinden izliyor.

Kendi işleriniz için üç örnek

Aşağıdakiler, zaten var olan sayfalar için örnek koşul ifadeleridir. Başlatmadan önce adresleri, verileri ve beklenen davranışı kendinizinkilerle değiştirin. Bunlar koşul örnekleridir, tamamlanmış iş raporu değil.

Katalogdaki aramayı düzeltin

Yerel katalogda "Atlas" ve "Orion" kartları olduğunu, ancak aramayı temizledikten sonra listenin boş kaldığını varsayalım. "Düzgün bir arama yap" isteği, nasıl davranması gerektiğini açıklamaz. Bunun yerine şu üç somut durum işe yarar:

/goal http://localhost:3000/catalog adresindeki aramayı düzeltin.
"atlas" sorgusu "Atlas" kartını bulduğunda,
"zzzz-no-match" sorgusu "Sonuç bulunamadı" gösterdiğinde
ve alanı temizlemek başlangıçtaki tüm kartları geri getirdiğinde tamamlanmış sayılır.
Playwright ile bu üç durumu da denetleyin; sorguyu, beklenen sonucu
ve gerçekten görünen kartları ya da mesajı konuşmada gösterin.
Son düzeltmeden sonra üç denetimi de tekrarlayın.
Yalnızca arama mantığını değiştirin; katalog verilerine ve görünüme dokunmayın.
Düzeltme ve denetleme için üç denemeden sonra sorun sürerse,
hangi durumların hâlâ çalışmadığını listeleyip durun.

Burada "tüm" sözcüğü önemli: tek bir kartın bulunması, aramanın düzeldiğini henüz doğrulamaz. Katalog verileri sabit, dolayısıyla kartların adını değiştirerek istediğiniz sonucu elde edemezsiniz. Son düzeltmeden sonra yeniden denetlemek de önemli; alanı temizlemeyi düzeltmek aramanın kendisini bozmuş olabilir.

Formu değişiklik yapmadan denetleyin

Bir hedefin sonucu gözlemlerden oluşan bir liste olabilir. Hazır bir kayıt formunu denetlemeniz, düzeltmeleri ise ayrıca konuşmak istemeniz buna örnek. Böyle bir durumda hatalar bulunsa bile tüm durumlar denetlendiğinde hedef tamamlanır.

/goal http://localhost:3000/signup adresindeki formu
proje dosyalarını değiştirmeden Playwright ile denetleyin.
Her seferinde boş formdan başlayarak iki durumu kontrol edin:
1. Alanları doldurmadan "Kaydol" düğmesine tıklayın.
Zorunlu alan uyarısı bekleniyor; kayıt gerçekleşmemeli.
2. email alanına "alex" yazın ve diğer zorunlu alanları
geçerli örnek değerlerle doldurup düğmeye tıklayın.
email biçimi hatası bekleniyor; kayıt gerçekleşmemeli.
Her iki durum için de konuşmada rapor bulunduğunda tamamlanır:
ne girildi, ne bekleniyordu, sayfa ne gösterdi, uyuşmazlık var mı?
Geçerli bir email adresiyle formu göndermeyin ve hesap oluşturmayın.
Sayfa ya da öğe açılamıyorsa denetimi durdurun
ve hangi durumun neden denetlenemediğini belirtin.

"Formu denetlemek" ile "formun çalışmasını sağlamak" arasındaki farka dikkat edin. Ajan her iki durumu gerçekten denetleyip sonuçları gösterdiyse formdaki bir hata raporun tamamlanmasını engellemez. Ancak sayfaya erişilemiyorsa tamamlanmaz: gözlem yerine varsayım koymak hedefi karşılamaz.

Sayfayı telefona sığdırın

"Mobilde güzel görünsün" demek, ajana kendi zevkine göre karar vermesi için fazla alan bırakır. Belirli bir sayfa, pencere boyutları ve erişilebilir kalması gereken öğeleri seçin.

/goal http://localhost:3000 sayfasının stillerini
390x844 ve 1440x900 pencere boyutları için düzeltin.
Her iki boyutta da yatay kaydırma olmadığında,
başlık ve "Başla" düğmesi tamamen görünüp üst üste binmediğinde
ve "Başla"ya tıklamak oyun bölümünü açmaya devam ettiğinde tamamlanır.
Son düzeltmeden sonra iki boyutu da Playwright ile denetleyin.
Ekran görüntülerini, tıklama sonucunu ve sayfanın kök öğesi için
ölçülen scrollWidth ile clientWidth değerlerini gösterin:
scrollWidth, clientWidth değerini aşmamalı.
Yalnızca CSS'i değiştirin. Kaydırmayı kaldırmak için içeriği gizlemeyin
veya kırpmayın. Metni ve oyunun davranışını koruyun.
Düzeltme ve denetleme için üç denemeden sonra koşullar sağlanmazsa,
kalan uyuşmazlığı gösterip durun.

Buradaki ölçüler, tarayıcı penceresinin piksel cinsinden genişliği ve yüksekliğidir. scrollWidth, kenarın ötesinde kalan bölüm de dâhil içerik genişliğini; clientWidth ise kullanılabilir genişliği gösterir. Bu değerleri karşılaştırmak taşmayı bulmaya yardımcı olur, ancak metnin kırpılmadığını ya da düğmeye erişilebildiğini tek başına kanıtlamaz. Bu yüzden koşulda ekran görüntüleri ve tıklama da var. İki boyut, sayfanın tüm cihazlarda kullanışlı olduğunu da kanıtlamaz; yalnızca bu işin kapsamını belirler.

Ajandan bir goal taslağı hazırlamasını isteyin

Koşulu sıfırdan yazmanız gerekmiyor. Claude Code Best Practice derlemesinde topluluk tarafından önerilen iki yöntem var: ajandan proje bağlamına göre hedefler önermesini istemek ve konuşmayı ve dosyaları okuduktan sonra koşul metnini yazmasını sağlamak. Aşağıda bu yöntemleri küçük bir iş için uyarlıyoruz.

Uzun süreli çalışmaya neyi bırakacağınız henüz belli değilse, /goal kullanmadan normal bir mesajla başlayın:

Mevcut konuşmayı ve görevle ilgili proje dosyalarını okuyun.
Doğrulanabilir bir sonuçla tamamlanabilecek üç yararlı hedef önerin.
Her biri için sonucu, nasıl denetleneceğini, değişiklik sınırlarını
ve başlatmak için henüz nelerin eksik olduğunu belirtin.
Üzerinde anlaştıklarımızı temel alın. Hedefleri henüz başlatmayın,
hiçbir dosyayı değiştirmeyin. Niyetim net değilse soru sorun.

Bir hedef seçin. Uzun süren çalışma kendi başına bir avantaj değil; belirsiz "iyileştirmeler" için saatler harcamaktansa aramanın düzeltilmesi daha yararlı. İş zaten açıksa ilk isteği atlayıp doğrudan koşul taslağını isteyebilirsiniz:

Seçilen görev için konuşmamıza, proje dosyalarına ve belgelerine
dayanarak bir /goal metni yazın. Şimdilik hiçbir şey yapmayın.
Gözlemlenebilir sonucu, nasıl denetleneceğini ve konuşmada neyin
gösterilmesi gerektiğini belirtin. Değişiklik sınırlarını ve başarı
olmadan durma koşulunu ekleyin. Adres, komut veya hazır olma ölçütü
uydurmayın: bunları projede bulun ya da bana sorun.
Tek bir tamamlanmış metin verin, belirsiz noktaları ayrıca listeleyin.

Taslağı göndermeden önce anlamını kontrol edin. Sonuç gerçekten istediğiniz şey mi? Belirtilen sayfa var mı? Ajan araya verileri değiştirme ya da özellik ekleme iznini de sıkıştırmış mı? Altta hâlâ belirsiz noktalar varsa önce onları netleştirin. Yalnızca netleşmiş metni çalıştırın: /goal komutu işi hemen başlatır.

Durumu görüntüleyin ve çalışmayı durdurun

Hedef etkin olduğu sürece ilerleyişini izleyebilirsiniz: /goal komutunu argüman olmadan çalıştırınca koşul, geçen süre ve tur sayısı ile değerlendiricinin döndürdüğü son neden gibi mevcut durum gösterilir.

Hedefi erken durdurmak da mümkün: /goal clear komutuyla. Oyun henüz bitmemiş olsa bile koşulu kaldırır.

Burada doğrulanmış sonuç tek: koşul yerine getirilmiştir ve bu, konuşmadaki değerlendirici yanıtında görülür. Hedefi /goal clear komutuyla kaldırmak da anlaşılır bir sonuçtur, ama bu sizin durma kararınızdır, işin yapıldığının kanıtı değil. Hedefin kendi kendine durabileceği diğer durumlar sonucu doğrulamaz.

Denetleyici model ne görür?

/goal değerlendiricisi sayfanın kendisini değil, konuşmayı görür: ajanın yazdıklarını ve tarayıcı gözlemlerinden konuşmaya kopyaladıklarını. Değerlendiricinin kendi araçları yoktur; sayfayı yeniden açmaz veya komutları çalıştırmaz, yalnızca birikmiş metni okur.

Bunun basit bir sonucu var. Ajanın "oyun bitti" demesi ne değerlendiriciye ne de size tek başına bir şeyi kanıtlar. Sonucu kanıtlayan, ajanın sayfadan gerçekten okuduğu değerdir; yani data-game-over değeri. İlki bir iddia, ikincisi bir gözlemdir. Kulağa benzeseler bile farklı şeylerdir.

Bu göstergenin sınırlarını da bilmek gerekir. data-game-over, belirli bir uygulamanın durumunu, yani sayfa yazarının ona yerleştirdiği bilgiyi bildirir. Tüm oyunun satranç kurallarına göre hatasız oynandığını göstermez. Aynı şekilde kaydırma çubuğunun olmaması da düğmenin çalıştığını kanıtlamaz. Gerçekten istediğiniz sonuca uygun bir gösterge seçin ve ona taşıdığından fazlasını yüklemeyin.

Çalışma biçimini nasıl etkiler?

Kendi işinizde de aynı kısa yolu izleyebilirsiniz:

• açık bir sonuç ve bunu denetlemenin erişilebilir bir yolu;
• /goal komutuyla belirtilen, değişiklik ve durma sınırları olan bir koşul;
• istediğiniz an görüntüleyebileceğiniz bir durum: argüman olmadan /goal;
• gözlemler ve denetim sonuçlarıyla desteklenen bir çıktı;
• çalışma takılırsa ya da koşul uygun değilse /goal clear komutuyla elle kaldırılan bir hedef.

Çalışmayı otomatik sürdürmek ve bundan sonra ne yapılacağına karar vermek iki ayrı iştir. İlkini tek bir oturum içinde /goal'a bırakabilirsiniz. İkincisi, yani gerçekte ne olduğunu anlamak, tamamlanmamış hedefi kaldırmak ve sıradaki işi belirlemek hâlâ size kalır.

Değerlendiricinin tam davranışı ve durum biçimi Claude Code sürümüne göre biraz değişebilir. Genel ilke değişmez: değerlendirme, sayfaya doğrudan erişerek değil, konuşma üzerinden yapılır.