Bir ajan için dört görev türü

"Portalın ana sayfasını tamamlayın" deyince aslında birkaç ayrı iş birden kastediliyor olabilir. Kampanya listesinde filtre eksik. Banner düğmesi yanlış yere gidiyor. Liderlik tablosunun verilerini hazırlayan kod iki kez yazılmış; bu yüzden her düzeltme iki kat zaman alıyor. Kampanya adresinin nereden geldiğini de kimse tam hatırlamıyor.

Böyle bir isteği alan biri muhtemelen ne demek istediğinizi sorar. Claude Code da sorabilir ama çoğu zaman boşlukları kendi doldurur: kulağa makul gelen, ama kimsenin istemediği bir işle. Üstelik her görev türünde eklenen şey farklıdır: filtreye arama, bağlantı düzeltmesine yeni bir tasarım eklenir; refactoring sırasında sıralama da "düzeltilir", araştırma ise dosyalarda değişiklik yapılarak biter.

Neler değişmeli?

Görev türlerini ayırt etmenin en kolay yolu, iş bittiğinde neyin farklı olacağına bakmaktır:

• daha önce olmayan bir davranış eklenir - feature, yani yeni bir özellik;
• davranış beklenene uygun hâle getirilir - bugfix, yani hata düzeltme. Önceden geliştirilmiş olsa da en başından beri üzerinde anlaşıldığı gibi çalışmayan şeyler de buna girer;
• dışarıdan bakınca her şey aynı kalır, kodun iç yapısı değişir - refactoring;
• proje hakkında sorunuza yanıt alırsınız, kaynak dosyalar değişmez - research, yani araştırma.

Görev türü, istekte neleri netleştirmeniz ve neleri kontrol etmeniz gerektiğini gösterir. Ajana ne kadar serbestlik tanıyacağınızı hatanın bedeli ve görevin kapsamı da belirler: insanların kullandığı koddaki bir değişiklik, eğitim amaçlı bir projeye yeni sayfa eklemekten daha fazla dikkat ister. Araştırmanın ardından düzeltme yapmak gibi karma görevler de olur. Böyle durumlarda her aşamanın sonucu ve sınırı ayrı olmalı.

Yeni bir özellik

Kampanya listesine yalnızca aktif kampanyaları gösteren bir anahtar eklememiz gerekiyor. Koşulları baştan belirleyelim: active: true değeri olan kampanya aktiftir; A ve C kampanyalarında bu alan açık, B'de kapalı. Buradaki veriler eğitim amaçlı; aşağıdaki istek örneklerini kendi projenize uyarlayabilirsiniz.

Ajan, "Aktif kampanyalar için filtre ekle" isteğini muhtemelen yerine getirir, hem de fazlasıyla. Şöyle görünür: anahtar eklenmiştir, yanında "madem filtreliyoruz" diye bir arama alanı, bir de bitiş tarihine göre sıralama. Bu eklemelerin her biri tek başına makul görünebilir. Ama birlikte, kimsenin istemediği ve artık kontrol etmeniz gereken küçük bir alt sisteme dönüşürler.

Fazladan eklemeleri en azından sayfada görebilirsiniz. Daha kötüsü, ajanın sizin vermediğiniz bir kararı sessizce almasıdır. Andrej Karpathy, kendi MenuGen projesi hakkında yazmıştı: giriş Google üzerinden, ödeme Stripe üzerinden yapılıyordu ve ajan satın almayı e-posta adresiyle hesaba bağlamıştı. İki serviste farklı adres kullananların ödemesi hesaplarına ulaşmıyordu. Kayıtları hangi ölçüte göre eşleştireceğinize ve projedeki mevcut kayıtlarla ne yapacağınıza siz karar verirsiniz; bunu istekte açıkça belirtmeniz iyi olur. Bizim sorumuz daha basit: active alanı hiç olmayan bir kampanyaya ne yapacağız?

Ajanın kendi başına iş çıkarmasının bir başka nedeni de örnek koddur. Ajan projede benzer bir kod bulup onu tekrarlar; ama benzer görünen yer, herkesin uzun zamandır değiştirmek istediği kısım olabilir. Projede iyi bir örnek varsa hangisi olduğunu siz belirtin.

Yeni bir özellik için tek bir kullanıcı senaryosu ve görev kapsamına girmeyenlerin açık listesi gerekir:

Ana sayfadaki kampanya listesine "Yalnızca aktifler" anahtarı ekle.
active: true olan kayıt aktiftir; bu alanı olmayan kayıt aktif değildir.
Mevcut verilerde kontrol: açıkken A ve C, kapalıyken A, B ve C görünür.
Arama, sıralama ve başka filtreler ekleme; bunlar ayrı görevler.
Projede benzer bir anahtar varsa aynı şekilde yap
ve hangi örneği kullandığını belirt.
Önce yapacağın senaryoyu tek cümleyle söyle,
sonra yanıtımı bekle. Şimdilik dosyaları değiştirme.

Son iki satır fazla zahmetli değil, ama işe yarar: ajan senaryoyu sizin amacınızdan farklı anlarsa bunu değişikliklerden önce fark edersiniz. Ajan planı gösterince kısa bir soru sorun: çözüm gereğinden karmaşık mı, yoksa eksik mi kalmış ve neden böyle düşünüyor? Bu soru her plan için geçerli, ama özellikle feature görevlerinde önemli; gereksiz eklemeler en çok burada gizlenir. Sonuç hazır olduğunda anahtarın iki durumunu da kontrol edin ve sayfaya başka gereksiz şeyler eklenip eklenmediğine bakın.

Bir hatayı düzeltme

Ana sayfadaki banner düğmesi kampanya koşullarını gösteren /campaign/ sayfasını açmalı, ama /old/ adresine gidiyor.

Ajan için en kısa yol, /campaign/ adresini doğrudan düğmenin bağlantısına yazmaktır. Adres zaten bağlantıda tutuluyorsa bu yeterli olur. Ancak adres başka düğmelerin de kullandığı ortak veriden geliyorsa bu değişiklik yalnızca belirtiyi gizler: bu düğme çalışır, ama verideki hata kalır. Sık görülen bir başka hamle de dosya zaten açıkken bannerın boşluklarını ve rengini yenilemektir.

Hangi durumla karşı karşıya olduğunuzu düğmeye bakarak anlayamazsınız; bunu ancak kod gösterir.

Bir şey istemeden önce hatayı kendiniz tekrarlayın: düğmeye basıp nereye gittiğine bakın. Hata sizde tekrarlanmıyorsa görevi hemen kapatmayın; önce hatanın görüldüğü adımları ve verileri netleştirin. Sorunu yeniden oluşturduktan sonra nedenini bulmak gerekir. Düğmenin adresi nereden aldığını bilmiyor musunuz? Sorun değil, ajana soracağınız ilk soru bu:

Ana sayfadaki banner düğmesi /old/ adresine gidiyor, /campaign/ adresine gitmeli.
Önce düğmenin adresi nereden aldığını bul ve ilgili yeri göster.
Şimdilik dosyaları değiştirme.
Onayımın ardından adresi tanımlandığı yerde düzelt.
Bannerın tasarımına dokunma.

Düzeltmeden sonra ilk işlemi yeniden yapın: düğmeye basın, adresi kontrol edin ve kampanya koşullarının sayfada göründüğünden emin olun. Ortak adres verisini değiştirdiyseniz onu kullanan başka bir yeri de kontrol edin.

Kodun iç yapısını değiştirme

Liderlik tablosunun verilerini hazırlayan kod neredeyse aynı hâliyle iki kez yazılmış; her değişikliği iki yerde yapmak gerekiyor. Amaç, tabloyu değiştirmeden tek bir sürüm bırakmak.

Değişiklik sırasında korunması gereken şeye invariant (değişmez) denir. Burada aynı verilerle katılımcıların sırası ve tablodaki sayılar korunmalı.

Refactoring sırasında ortaya çıkan bozulmalar genellikle sessizdir. Eşit puanlıların sırası değişir, yuvarlama farklılaşır; hata mesajı gelmez, tablo yalnızca yanlış şeyi gösterir. Ajan iki sürümü birleştirip hiçbir şey çalıştırmadan "davranış değişmedi" diye rapor verebilir. Ya da eski sıralama ona tuhaf göründüğü için arada "iyileştirebilir".

Şu sıradaki bir veri kümesini ele alalım: A 10 puan, C 20, B 20, D 15.5. Bugün tablo C: 20, B: 20, D: 15.5, A: 10 gösteriyor. Refactoring için referans, siz başka türlü tercih etseniz bile mevcut kodun tam olarak bu çıktısıdır. Veri kümesi özellikle böyle seçildi. C, B'den önce geldiği için yeni sürüm eşit puanları ada göre sıralarsa B öne geçer. Ondalıklı değer de yuvarlamanın değişip değişmediğini gösterir.

İki sorunu da önleyen bir istek şöyle olabilir:

Liderlik tablosunun verilerini hazırlayan kod iki yerde tekrarlanıyor, tek sürüm bırak.
Tablonun davranışını değiştirme, bir şey tuhaf görünse bile;
böyle yerleri ayrıca listele.
Değişiklikten önce mevcut kontrolleri çalıştır ve şu veri kümesi
ile tabloyu yazdır: A: 10, C: 20, B: 20, D: 15.5. İki çıktıyı da kaydet.
Değişiklikten sonra aynı işlemi tekrarla ve karşılaştır.
Raporda veri hazırlığının artık nerede olduğunu göster.

Kaydedilen çıktıları yalnızca rapordaki "aynı" satırına bakarak değil, kendiniz karşılaştırın. Sonuçların eşleşmesi, yalnızca bu verilerde davranışın korunduğunu gösterir. İsteğin son satırı da asıl görevi kontrol eder: tablolar aynı olsa bile tekrar eden kod gerçekten kaldırılmış olmayabilir.

Burada yarım bırakmak hiçbir şey yapmamaktan da kötü. Diyelim ki kopyalardan biri kaldı, bazı çağrılar yeni sürüme geçti. Tablo aynı görünür ama veriyi hazırlamanın iki yolu vardır; sonraki istekte ajan hangisinin doğru olduğunu bilmediğinden eski yolu kullanabilir. Birleştirmeye başladıysanız işi tek sürüme kadar tamamlayın. Yetiştiremeyecekseniz daha erken durun ve nerede kaldığınızı not edin.

Düzeltme yapmadan araştırma

Research diğerlerinden en çok ayrılır: sonuç, değiştirilmiş bir proje değil, bir yanıttır. Portalımızdaki soru şu: kampanya düğmesinin gittiği adres nerede seçiliyor? Bu, hata düzeltmeye başlarken sorduğumuz sorunun aynısı; tek fark, burada herhangi bir değişiklik istenmiyor. Karma görev de böyle görünür: önce araştırma, ardından ayrı bir aşamada düzeltme.

Ajanın burada sık yaptığı iki hata var. İlki, araştırma sırasında düzeltmeye başlamak: hatalı bir bölüm bulur ve düzeltmek, açıklamaktan daha kolay görünür. Böylece araştırma, tanımlanmamış ve kontrol edilmemiş bir değişikliğe dönüşür. İkincisi daha ince. Ajan kodu okur ve sayfayı çalıştırmadığı hâlde nasıl çalıştığını kendinden emin biçimde anlatır. Dışarıdan bakınca okuduğunu aktarmak, gözlem yapmakla aynı gibi görünür.

Üçüncü hata isteğin kendisinde başlar. Sonra ne yapmayı planladığınızı yazarsanız ajan yanıtını bu hedefe göre şekillendirir: sayfanın şu an nasıl çalıştığı yerine, nasıl çalışmasının daha iyi olacağına dair bir görüş alırsınız. Bu nedenle research görevinde mevcut durumu sorun, niyetinizi sonraki aşamaya bırakın. Aşağıdaki istekte adresi daha sonra düzelteceğimize dair tek kelime yok.

Ana sayfadaki banner düğmesinin adresi nereden aldığını bul. Hiçbir şeyi düzeltme.
Yanıtta dosyaları ve koddaki ilgili yerleri, aralarındaki bağlantıyı,
okuyarak neyi belirlediğini, çalıştırarak neyi gözlemlediğini
ve henüz neleri bilmediğini belirt.

Bu isteğe iyi bir yanıt şöyle olabilir: "pages/home.html dosyasında düğmenin adresi promo.url değerinden alınıyor; /old/ değeri data/promo.json içinde tanımlı. Bunu iki dosyayı okuyarak belirledim. Sayfayı çalıştırmadım ve scriptlerin adresi değiştirip değiştirmediğini kontrol etmedim." Bağlantıyı doğrulayabilir, bilginin sınırını da açıkça görürsünüz.

Yolda şüpheli bir bölüm bulursa, gördüklerini ve sonuca varmak için nelerin eksik olduğunu ayrı bir satırda yanıtına eklesin. Düzeltme ise kendi tanımı olan sonraki aşamadır.

İlk soru ve sınırlar

Hepsini tek tabloda görelim.

Üçüncü sütundakileri istekte özellikle sınırlandırmanız iyi olur. Dördüncü sütundakileri ise kendiniz kontrol edin veya yanıtta göstermesini isteyin.

Öte yandan, görev türünün adı tek başına hiçbir şeye izin vermez. "Alt tarafı refactoring" demek modülün yarısını yeniden yazmak için gerekçe değildir; "bugfix" de tasarımı değiştirme hakkı vermez. Tür, hangi soruyu soracağınızı ve neyi kontrol edeceğinizi gösterir; sınırları yine siz belirlersiniz.

Altı isteği yeniden yazın

Aşağıda sık kullanılan biçimleriyle altı istek var. Her birinin türünü belirleyin ve ajanın daha az varsayım yapacağı şekilde yeniden yazın: sonuç, sınır ve kontrol. Çözüm hemen arkasından geliyor; önce kendiniz deneyin.

1. "Liderlik tablosunu CSV olarak dışa aktarın".
2. "Liderlik tablosunda bazen aynı katılımcı iki kez görünüyor, düzeltin".
3. "pages/home.html dosyasını parçalara ayırın, çok büyük".
4. "Ana sayfa neden bu kadar yavaş yükleniyor?"
5. "Bağlantıyı düzeltin, tasarımı da yeniden yazın".
6. "Portalı daha iyi hâle getirin".

Olası bir çözüm aşağıda. Sizin ifadeleriniz farklı olabilir; önemli olan aynı dayanakları içermeleri.

1. Liderlik tablosunu dışa aktarma.
Feature. Senaryo eksik: dosyaya hangi sütunlar girecek, satırlar hangi sırada olacak, dışa aktarma düğmesi nerede bulunacak? Kolayca gözden kaçan bir veri sorusu da var: henüz puanı olmayan katılımcılar dosyaya girecek mi? Buna siz karar verin, yoksa ajan karar verir. Ayrıca yapılmayacakları da ayrı yazın: içe aktarma, sütun seçimi, başka formatlar. Kontrolü basit: A, B, C, D veri kümesini dışa aktarın ve satırları ekrandaki tabloyla karşılaştırın.

2. Katılımcı iki kez görünüyor.
Bugfix, ama buradaki kilit sözcük "düzeltin" değil, "bazen". Kopyanın ne zaman oluştuğu bilinmedikçe ajanın düzeltebileceği bir şey yok; en olası hamlesi, tabloyu göstermeden önce tekrarları kaldırmak olur. Gizli belirti tam da budur. Önce hangi işlemden sonra ve hangi verilerde satırın iki kez göründüğünü bulun, sonra değişiklik yapmadan bunun kodda nerede olduğunu bulmasını isteyin. Kontrol, kopyanın oluştuğu senaryoyu tekrarlamaktır.

3. Büyük dosyayı bölmek.
Refactoring, ama invariant belirtilmemiş; "hiçbir şey bozulmadı" demeyi kontrol edecek bir dayanak da yok. Şunu ekleyin: banner, kampanya listesi ve liderlik tablosu eskisi gibi görünmeli ve çalışmalı; değişiklikten önce kontrollerin sonuçları kaydedilmeli. Bir de şu cazibeyi sınırlandırın: ajan HTML'yi dosyalara bölerken kolayca boşlukları da düzeltebilir veya class adlarını değiştirebilir.

4. Yavaş sayfa.
Research: bu, hızlandırma talebi değil bir soru. Ama ajan bunu kolayca "daha hızlı yap" diye anlayabilir; "hiçbir şeyi değiştirme" demezseniz gelişigüzel bir optimizasyonla yanıt verebilir. Yanıtta ölçülenlerle yalnızca koddan anlaşılanları ayırmasını isteyin: "görseller birkaç megabayt yer kaplıyor", ajan bunu kontrol ettiyse bir gerçektir; "muhtemelen script yavaşlatıyor" ise tahmindir. Nedeni bulduktan sonra düzeltmeyi ayrı bir aşama olarak ele alın.

5. Bağlantıyı düzeltip tasarımı yeniden yazmak.
Tek istekte iki sonuç var. Bağlantıyı düzeltmek bugfix'tir. Yeni tasarım ise dört türden hiçbirine tam uymaz: davranış değil, görünüm değişiyor. En yakını feature; yalnızca sonuç bir senaryoyla değil, taslak ya da ekran görüntüsü gibi bir örnekle tarif ediliyor. Önce bugfix bölümündeki istekle bağlantıyı düzeltin, kontrol ettikten sonra tasarımı ele alın:

Şimdi bannerı @banner-mockup.png taslağına göre düzenle.
Düğmenin adresini ve metinleri değiştirme.

6. Portalı iyileştirmek.
Türü belirleyemeyiz, tahmin etmek de gerekmez. İsteği verene şu soruyu yöneltin: Şu anda sizi tam olarak ne zorluyor? İsteği kendiniz verdiyseniz bu soruyu kendinize sorun. Bunu ajana da bırakabilirsiniz:

Herhangi bir şeyi değiştirmeden önce,
tam olarak neyi iyileştirmem gerektiğini anlamak için
bana en fazla beş soru sor.
Dosyaları değiştirme.

Yanıtlardan görev türü genellikle kendiliğinden belli olur.