/goal: Uzun Süre Çalışan Agent'ların Kullanım Kılavuzu

Kıvılcım: prompttan hedefe geçiş

Bu yazının çıkış noktası David Kundel'in X'te paylaştığı /goal referansı. X içeriği web üzerinden her zaman tam okunabilir gelmediği için burada asıl teknik iddiaları resmi Codex dokümanlarıyla doğruladım; fakat paylaşımın işaret ettiği ana fikir çok net: agent deneyimi, “bir cevap daha ver” noktasından “bu işi tamamlanabilir bir hedefe çevir ve üzerinde çalış” noktasına kayıyor.

OpenAI Codex dokümanları bu modu, Codex'in uzun süren bir işte doğrulanabilir bir durma koşuluna doğru çalışması için öneriyor.1 Benim pratik çevirim şu: /goal, “bir sonraki cevabı ver” komutu değil; “bu sonuca ulaşana kadar ilerle, kanıtla ve nerede duracağını bil” sözleşmesidir.

Buradaki kırılma küçük görünür ama derindir. Normal promptta agent bir tur çalışır ve durur. Sen bakarsın, yeni prompt atarsın, o yine çalışır. /goal bu ritmi tersine çevirir: önce başarı koşulunu ve hareket alanını yazarsın, sonra agent o koşula doğru birkaç tur boyunca ilerler. Artık ana beceri “iyi prompt yazmak” değil, iyi bir iş sözleşmesi kurmak olur.

/goal nedir?

/goal, Codex içinde bir slash command. CLI'da /goal Finish the migration and keep tests green gibi bir hedef yazarsın; /goal ile mevcut hedefi görürsün; /goal pause, /goal resume ve /goal clear ile duraklatır, sürdürür veya kaldırırsın.2 Codex app tarafında ise aynı fikir composer üzerinde başlatılır; hedef aktifken ilerleme satırı görünür, oradan pause, resume, edit ve clear kontrolleri yapılır.3

Dokümanlardaki en kritik fikir şu: goal metni hem başlangıç yönlendirmesi hem de tamamlanma kriteri gibi çalışır.1 Yani /goal aslında “şunu yap” komutundan fazlasıdır. Bir mini sözleşmedir:

• Ne yapılacak?
• Nereye dokunulmayacak?
• Başarı nasıl kanıtlanacak?
• Hangi durumda durulacak veya kullanıcıya dönülecek?

Bir goal 4.000 karakteri geçmemeli; daha uzun talimat için detayları dosyaya koyup hedefin o dosyayı işaret etmesi öneriliyor.2 Bu ayrıntı önemli, çünkü iyi /goal kullanımı çoğu zaman tek satırlık büyülü cümle değil, küçük bir çalışma protokolüdür. Goal metni backlog listesi gibi değil, koşu kontratı gibi yazılmalıdır: amaç tek, sınır görünür, kanıt denetlenebilir.

Neden önemli?

Benim için /goalun açtığı kapı, agent'ların “yardımcı araç” olmaktan “iş akışı taşıyıcısı” olmaya başlaması. Çünkü yazılım işi çoğu zaman tek hamlelik değildir. Migration, refactor, test düzeltme, görsel QA, deploy denemesi, performans iyileştirmesi, dokümantasyon üretimi: bunların hepsi küçük gözlem-aksiyon-doğrulama döngülerinden oluşur.

Normal promptla çalışırken bu döngünün yapıştırıcısı insandır. Agent test sonucunu getirir, sen “şimdi şunu dene” dersin. Sonra başka hata çıkar, sen tekrar yönlendirirsin. /goal ile yapıştırıcının bir kısmı agent'a geçer. Sen yine sorumlusun; ama her mikro adımı elle taşımak zorunda kalmazsın.

Bu nokta özellikle önemli: /goal “agent'a sınırsız yetki ver” demek değildir. Hatta iyi goal yazımı tam tersini gerektirir. Yetkiyi değil, hedefin sınırlarını ve kanıtını netleştirir.

İyi hedef nasıl yazılır?

OpenAI dokümanları iyi hedeflerin spesifik bir sonuç, ölçülebilir hedef veya test kriteri içermesini öneriyor.1 Bu kulağa basit gelir ama pratikte farkı yaratan şey tam burada saklıdır. “Projeyi düzelt” zayıftır. “Auth migration'ını tamamla; npm test -- auth ve npm run lint temiz geçsin; ödeme modülüne dokunma” çok daha iyidir.

Ben burada “Definition of Done” yani bitti tanımı gibi düşünmeyi seviyorum. İyi goal, agent'a yalnızca hedefi değil, hedefin çevresindeki dört şeyi de verir: kapsam dışı kalan işler, kabul kanıtı, onay gerektiren eşikler ve bloke olma protokolü. Bu dördü yoksa uzun çalışma kolayca uzun bir tahmine dönüşür.

Ben iyi /goal metnini altı parçaya ayırıyorum:

1. Tek amaç: Aynı goal içinde hem migration hem landing page hem deploy hem pazar araştırması isteme. Büyük hedefi parçalara böl.
2. Bağlam: Okunacak dosyaları, issue'yu, ekran görüntüsünü, mevcut planı veya hata çıktısını göster.
3. Sınır: Hangi modüllere dokunmamalı, hangi tasarım korunmalı, hangi davranış değişmemeli?
4. Doğrulama: Hangi komut, ekran, rapor veya artifact “bitti” dedirtecek?
5. Durma koşulu: Ne zaman complete, ne zaman blocked, ne zaman kullanıcı onayı gerekir?
6. Status disiplini: Uzun koşuda hangi aralıkta veya hangi checkpoint'te kısa kanıt özeti verilecek?

Ne zaman kullanılır, ne zaman kullanılmaz?

/goal, her promptun daha havalı hali değil. Tek seferlik cevap, küçük metin düzenleme, hızlı komut çıktısı veya net bir dosya değişikliği için normal çalışma daha hızlıdır. /goal en çok, işin içinde iterasyon ve kanıt varsa parlar.

Çok uygun işler

• Migration: JavaScript'ten TypeScript'e geçiş, eski routing yapısından yenisine taşıma, framework upgrade.
• Test temizliği: Bir test ailesinin tamamını yeşile döndürme, flaky testleri izole etme.
• Görsel QA: Bir web uygulamasını desktop ve mobile görünümde açıp taşma, boş ekran, overlap ve state sorunlarını yakalama.
• Performans hedefi: Belirli bir metriği düşürmek, build süresini azaltmak, bundle analiziyle tekrar denemek.
• Dokümantasyon paketi: Kod, toplantı notu ve müşteri bağlamından kaynaklı bir rehber veya rapor üretmek.

Uygun olmayan işler

• Belirsiz vizyon: “Bana harika bir ürün çıkar” gibi durma kriteri olmayan işler.
• Yüksek riskli canlı aksiyon: Üretim verisi, ödeme, hesap silme, geri dönüşsüz deploy gibi insan onayı gerektiren adımlar.
• Kaynağı doğrulanmamış iddialar: Güncel ürün davranışı, fiyat, hukuk, güvenlik veya müşteri verisi içeren işlerde goal başlamadan önce kaynak ve onay hattı net olmalı.
• Tek cevaplık düşünme: “Bu cümleyi düzelt”, “şu hatanın anlamı ne?” gibi küçük işler.

Uzun süre çalışan agent'ın işleyiş döngüsü

Uzun süreli agent çalışmasında asıl değer kod yazmasından değil, döngüyü taşımasından gelir. Bir hedefi küçük checkpoint'lere böler, her checkpoint'te bir şey değiştirir, kanıt üretir, sonucu okur ve sonraki hamleyi seçer. Bu ritim doğru kurulursa agent saatlerce “meşgul” değil, saatlerce “ölçerek ilerleyen” hale gelir.

Bu döngü, yazılım ekiplerinde eskiden insanın taşıdığı birçok “küçük ama yorucu” adımı agent'a devreder. Özellikle büyük refactorlarda bu bir hız artışı değil sadece; işin biçimini değiştirir. İnsan artık her terminal çıktısının bekçisi değil, hedefin sahibi ve sınırların tasarımcısı olur.

Riskler: otonomi sarhoşluğu

Uzun süre çalışan agent fikri heyecan verici olduğu kadar yanıltıcı da olabilir. Çünkü “çalışmaya devam ediyor” hissi kolayca “doğru çalışıyor” hissine dönüşür. Bu yüzden /goal kullanırken dört risk akılda kalmalı.

Pratik reçete: ilk /goalünü böyle yaz

Başlamak için aşağıdaki şablon yeterli. Bunu tek satırda yazmak zorunda değilsin; hatta büyük işlerde GOAL.md, PLAN.md veya issue açıklaması kullanmak daha iyi olur.

/goal [Tek cümlelik amaç]

Bağlam:
- Önce [dosya/issue/log/screenshot] oku.
- Mevcut davranış: [kısa açıklama].

Kapsam:
- Şunlara dokunabilirsin: [modül/dosya/akış].
- Şunlara dokunma: [sınır].
- Şu adımlar için önce onay iste: [deploy/veri silme/ödeme/secret].

Doğrulama:
- [komut 1] temiz geçmeli.
- [komut 2] veya [artifact] sonucu kanıtlamalı.

Durma koşulu:
- Başarı kanıtlandıysa complete.
- Aynı blokere 3 kez takılırsan status ver ve bekle.

Üç hazır örnek

“Bu kod tabanını JavaScript'ten TypeScript'e taşı; strict mode derlensin ve açık any kalmasın.” OpenAI dokümanındaki örneğin Türkçeleştirilmiş hali1

“Ana sayfanın time to interactive değerini 1 saniyenin altına indir.” OpenAI dokümanındaki örneğin Türkçeleştirilmiş hali1

“Yeni blog yazısını üret, blog indeksine ekle, HTML doğrulamasını çalıştır ve yerel tarayıcıda bağlantıları kontrol et.” Bu yazı için kullanılabilecek pratik goal örneği

Benim kısa kuralım şu: Eğer işi bir stajyere veya ekip arkadaşına veriyor olsan “bittiğini nasıl anlayacağız?” diye sorardın. /goal metnini de aynı ciddiyetle yaz. Hedef bir komut değil, küçük bir çalışma anlaşmasıdır.