Ajan için görev tanımı: bir fikir nasıl göreve dönüşür

Ajana art arda iki istek. Birincisi: "SPEC_LANDING.md dosyasındaki görev tanımına göre sayfayı yap". Birkaç dakika sonra klasörde index.html beliriyor ve tam tasarlandığı gibi görünüyor. İkincisi, aynı akşam: "2048 oyununu yap". Bu sefer ajan ya art arda beş soru soruyor ya da hiçbir şey demeden 5×5'lik bir tahta yapıyor, üstüne de kimsenin istemediği bir hamle geri alma düğmesi ekliyor.

Fark ajanda değil. Fark, ajanın girdi olarak ne aldığında. Bu makalede küçük bir iş için görev tanımının nelerden oluştuğunu, içine yazılacak özü nereden bulacağınızı, elinizde sadece bir yön varken ne yapmanız gerektiğini ve "bitti" dendikten sonra sonucu neden işe başlamadan önce yazdığınız satırların aynısıyla kontrol ettiğinizi ele alacağız.

1. Fikir henüz bir görev değil

"2048 istiyorum". "Güzel bir sayfa yap". "Yeni bir oyun yap, daha ilginç olsun". Bunların hepsi fikir ve hepsinin ortak bir derdi var: kafanızda koca bir resim duruyor, metinde ise iki kelime. Ajan ise sadece metni görür.

İstekte bir boşluk kaldığında ajanın önünde iki yol vardır. Birincisi sormak. İkincisi boşluğu kendisi doldurmak: bir tahta boyutu seçmek, bir kural uydurmak, bir düğme eklemek. İkinci yol daha sessizdir ve bu yüzden daha tehlikelidir. sizin yerinize karar verildiğini sonucu görene kadar fark etmezsiniz. İstekteki her boş yer, birinin vereceği bir karardır ve varsayılan olarak bu kararı veren siz olmayacaksınız.

"2048'in nasıl oynandığını herkes bilir" düşüncesi sizin kafanızda. Ajan bu "herkes bilir"i okumaz. Tahta kaça kaç? Yeni taşlar nereden ve ne zaman gelir? Hangileri birleşir ve neye dönüşür? Oyun ne zaman kazanılır, ne zaman biter? Sizin için tek bir kelime, onun içinse kurallara dökülene kadar boş bir alan. Sohbette bu şöyle görünür:

Siz:   2048 oyununu yap
Ajan:  Başlamadan önce birkaç şeyi netleştireyim:
       1. Tahta 4×4 mü olsun?
       2. Neyi kazanma sayalım?
       3. Hamle geri alma gerekli mi?

Bu iyi bir sonuç. Aynı isteğin başka bir sonucu da olabilir:

Siz:   2048 oyununu yap
Ajan:  Bitti. Oyun index.html dosyasında:
       - 5×5 tahta
       - son hamleyi geri alma düğmesi
       - localStorage'da rekor tablosu

Bu, ajanın hatası değil. Bunlar sizin üç boşluğunuz, siz olmadan doldurulmuş.

Fikirden güvenilebilecek bir sonuca giden yol böyle görünür. Makale bu yolu soldan sağa takip ediyor. Son adım ise sizi üçüncüye geri götürür: kontrol ettiniz, bir açık buldunuz, görev tanımına bir satır eklediniz ve ajana yeniden verdiniz.

2. Öz nereden gelir

Bir sayfanın ya da oyunun iskeletini ajan dakikalar içinde kurar ve bu gerçekten işin en zor kısmı değildir. Zor olan, sayfada ne olması gerektiğini ve aslında neyi oynadığımızı bilmektir. Bu kodda yazmaz. İnsanların kafasındadır, bazen sizin kafanızda, bir kısmını da ajan bilir. Sorularla ortaya çıkarılır ve üç kaynağı vardır: insanlar, siz, ajan.

İnsanlar, işi isteyen kişi ve onu kullanacak olanlardır. Onlara soruları toplu halde sormak daha iyidir. Her gün bir soru yerine tek seferde beş-altı maddelik bir liste. Toplu soru listesi rahatsız edici görünür, biliyorum. Gerçekte ise herkesi bir haftalık yazışmadan kurtarır.

İşi isteyen siz olduğunuzda (kendi oyununuz, kendi sayfanız) soruları kendinize sorarsınız ve buradaki en büyük tuzak "bu zaten belli" diye cevap vermektir. Belli olan da belli olmayan gibi yazıya dökülür. "4×4 tahta" yazmak iki saniye sürer, ama ajan için koca bir yol ayrımını kapatır.

Üçüncü kaynak ajandır ve burada önceden bilinmesi gereken bir tuzak var: bilmediğiniz bir şeyi soramazsınız. Hiçbir şeyi kaydırmayan bir hamle, hamle sayılır mı? Telefonda kaydırma hareketi gerekli mi? Skor gösterilsin mi? Bu sorular oyunu karşınızda görene kadar aklınıza gelmez. Ajan ise bu tür oyunlardan binlercesini görmüştür ve genellikle nerede tökezlendiğini bilir. Bu yüzden bazen "yap" yerine "hadi konuşalım" diye başlamak daha faydalıdır:

Tarayıcıda çalışan bir 2048 oyunu yapmak istiyorum. Şimdilik hiçbir şey yazma.
Başlayabilmek için bilmen gereken soruları sor. Hepsini birden, liste halinde.
Ben cevaplayacağım, sonra görev tanımını SPEC_2048.md dosyasında toplayacağız.

Böyle bir konuşma için iki kural var, yoksa hiç bitmez. Birincisi: konuşma, bir sonraki bölümdeki dört dayanak tamamlandığında biter ve sonucu sohbet değil, bir dosyadır. İkincisi: ajanın soruları seçeneklerdir, gereksinim değil. "Rekor tablosu da yapalım mı?" diye seve seve sorar ve "hayır" gayet normal bir cevaptır. Böyle bir "hayır" da görev tanımında bir satırdır, sadece "yapmıyoruz" kısmında.

Ve her durumda, soran siz olun ya da ajan, cevap sohbette bir mesaj olarak kalmaz, görev tanımı dosyasına yazılır. Yoksa bir sonraki istek aynı açıkla başlar.

Solda üç kaynak, sağda tek bir varış noktası. Aşağı inen kesikli ok, cevapların en sık gittiği yoldur: sohbette kalırlar ve on mesaj sonra artık bulunamazlar. Şemada ok var, ama ucunda dosya yok.

Ajandan daha fazlasını da isteyebilirsiniz: sadece soru sormasını değil, cevaplarınıza göre görev tanımının bir taslağını da çıkarmasını ve söylemediğiniz yerleri kendisinin doldurmasını. Onun kendi eklediği kısımlarla sonra ne yapılacağı 4. bölümde. Önce görev tanımının nelerden oluştuğuna bakalım.

3. Görev tanımının dört dayanağı

Küçük bir iş için görev tanımı altı-sekiz satırdır. Bu satırlar dört dayanak üzerinde durur: hedef, ne olması gerektiği, ilk sürümde neyin olmayacağı, nasıl kontrol edeceğimiz. Oyun için tamamı şöyle:

# Görev tanımı: 2048

HEDEF:      tarayıcıda çalışan 2048 oyunu, dosyadan açılır, kurulum gerektirmez.
            HTML, CSS ve JavaScript, derleme adımı yok

KURALLAR:   4×4 tahta
            başlangıçta ve her hamleden sonra yeni bir taş çıkar: 2 ya da 4
            ok tuşları tüm taşları tek bir yöne, gidebildikleri yere kadar kaydırır
            çarpışan iki aynı taş, toplamlarıyla tek bir taşa dönüşür
            kazanma: tahtada 2048 taşı belirdi
            kaybetme: hamle kalmadı, tahta dolu, birleştirilecek bir şey yok

YAPMIYORUZ: rekor tablosu, animasyonlar, hamle geri alma

KONTROL:    index.html dosyasını tarayıcıda aç, tahtayı ve başlangıç taşlarını gör
            ok tuşlarıyla üç hamle yap, her birinden sonra yeni bir taş çıkıyor
            iki 2'yi birleştir, bir 4 elde et
            oyunu sonuna kadar oyna, kaybetme ekranını gör

Şimdi dayanakları tek tek ele alalım, her birini iki örnek üzerinden: oyun ve bir masa oyunları kulübünün buluşmasına davet sayfası.

Hedef

İlk satır. Onu okuyan kişi kodu değil, sonucu gözünün önüne getirmeli. "Tarayıcıda çalışan 2048 oyunu, dosyadan açılır, kurulum gerektirmez". "Kulüp buluşmasına davet sayfası: kişi buluşmanın ne olduğunu anlar ve bir düğmeyle kaydolur".

Hedefin kontrolü: onu okurken bir insanın göreceği şeyi değil de kodu görüyorsanız, bu artık hedef değildir. "Taş birleştirme fonksiyonunu yaz" bir hedef değil, işin bir parçası.

Buraya tek satırla "neyle yapıyoruz" da eklenir: HTML, CSS ve JavaScript, derleme adımı yok. Bu satır olmazsa ajan kendisi seçer ve seçtiği şeyi sizin çalıştırabileceğiniz kesin değildir.

"Güzel yap" ise hedef olamaz. Kime göre güzel ve bunu nerede göreceğiz, belli değil.

Ne olması gerektiği

En uzun dayanak ve oyun için yukarıda zaten yazıldı. Tek bir kural var: bir satır, çalıştırdıktan sonra ona bakıp "evet" ya da "hayır" diyebiliyorsanız iyidir. "4×4 tahta": evet ya da hayır. "İki aynı taş toplamlarıyla tek bir taşa dönüşür": evet ya da hayır. "Daha ilginç olsun": ne evet ne hayır, böyle bir satırın görev tanımında yeri yok.

Her satırda tek bir düşünce. "Taşlar çıkar ve birleşir" iki kontroldür, yani iki satır.

Sayfa için de aynısı geçerli, sadece kurallar yerine sayfada ne olduğu yazılır: "kulübün adını ve tarihi içeren bir başlık", "üç blok: ne olacak, kimler için, nerede", "Kaydol düğmesi form adresine gider". Her birini açıp görebilirsiniz.

Böyle bir liste fikrin yanında sıkıcı görünür. Sıkıcı olması iyi bir şey. sıkıcı olan kontrol edilebilir.

İlk sürümde ne olmayacak

Genellikle unutulan tek dayanak ve bu yüzden en değerlisi. Ajan boşluğu kendisi doldurur ve bunu en çok bir şey ekleyerek yapar. Rekor tablosu, taş animasyonu, hamle geri alma düğmesi, karanlık tema. Hepsi faydalı ve hiçbirini siz istemediniz.

Tek tek adıyla yazılır. "Gereksiz bir şey olmasın" yazılmaz: bu bir sınır değil, bir dilek. Onun yerine: "yapmıyoruz: rekor tablosu, animasyonlar, hamle geri alma". Sayfa için: "yapmıyoruz: kayıt formunun kendisi, ödeme, fotoğraf galerisi". Genellikle üç isim yeterlidir, on tane zaten kimse yazmaz.

Bu neden ajan için değil de sizin için önemli? Ne kadar az şey yapılırsa, o kadar az şey kontrol edersiniz. Bir şey bozulduğunda nereden geldiği de o kadar anlaşılır olur: altı satırda aramak altı ekranda aramaktan kolaydır. Sınır olmadığının işareti: isteğinizde ya da ajanın cevabında "hazır başlamışken" ifadesi sıklaşmıştır.

Nasıl kontrol edeceğiz

"Ne olması gerektiği" kısmındaki her satır, ajan "bitti" dedikten sonra yapılacak bir kontroldür. Oyunu açtınız: 4×4 tahta, evet. Bir ok tuşuna bastınız: taşlar kaydı, yenisi çıktı, evet. İki 2'yi birleştirdiniz: 4 oldu, evet. Kontrol listesini ayrıca yazmıyorsunuz, o zaten yazılmış durumda.

Buna ek olarak görev tanımının içinde iki-üç satırlık bir "kontrol" kısmı: tam olarak elle ne yapılacağı. "Dosyayı tarayıcıda aç, üç hamle yap, sonuna kadar oynayıp kaybet". Bu satırlar istekten önce yazılır, sonra değil. Sonuç geldikten sonra yazılırlarsa fark ettirmeden çıkan sonuca uydurulurlar. Bu kendiliğinden olur, sizin başınıza da gelecek.

Ajanın "bitti" demesi bir mesajdır, kontrol değil. Kontrol sizindir ve sizin satırlarınıza göre yapılır.

Şimdi pratik. "Masa oyunları kulübünün buluşması için güzel bir sayfa yap" isteğini alın ve her birine bir-iki satır düşecek şekilde dört dayanağa ayırın. Cevap hemen aşağıda, karşılaştırın:

# Görev tanımı: davet sayfası

HEDEF:        masa oyunları kulübünün buluşmasına davet sayfası:
              kişi buluşmanın ne olduğunu, ne zaman ve nerede olduğunu anlar ve bir düğmeyle kaydolur.
              tek bir HTML dosyası, stiller içinde

SAYFADA:      kulübün adını ve buluşma tarihini içeren bir başlık
              üç blok: ne olacak, kimler için, nerede
              "Kaydol" düğmesi form adresine gider

YAPMIYORUZ:   kayıt formunun kendisi, ödeme, fotoğraf galerisi

KONTROL:      tarayıcıda aç, başlığı ve üç bloğu gör
              düğmeye bas, form adresine git

Dikkat edin, "güzel" kelimesi görev tanımına hiç girmedi. Kontrol edilemez. Güzellik gerçekten önemliyse, diğer her şey gibi satırlara ayrılır: "başlıkta tek bir görsel", "en fazla iki renk", "her şey telefon ekranına sığıyor". Bunu artık açıp bakabilirsiniz.

İki örnekte blokların adları farklı: oyun için "kurallar", sayfa için "sayfada". Bunun önemi yok, istediğiniz gibi adlandırın. Önemli olan, her birinde dört dayanağın bulunması:

4. Bu kimin kararı

Görev tanımında kimsenin onaylamadığı kararlar belirir ve bu iki şekilde olur. Birincisi: taslağı salıya kadar cevap beklemeden hemen almak için ajanın boşlukları "makul bir şeyle" doldurmasına izin verdiniz. İkincisi: soracak kimse ya da vakit olmadığı için iş sahibi adına kararı kendiniz verdiniz.

İki durum da normal. Normal olmayan, bunun bir varsayım olduğunu unutmak. Bir hafta sonra düğmenin forma değil de e-postaya gideceğini kimin uydurduğunu kimse hatırlamaz ve tartışma tam olarak bunun üzerine çıkar.

Birinci durum için ajana istek şöyle görünür:

Bu cevaplara göre davet sayfası için bir görev tanımı taslağı hazırla.
Cevabın olmadığı yerlerde makul bir şey uydur ve ayrı bir liste halinde
kendi uydurduklarını say. SPEC_INVITE.md dosyasına yaz.

Uydurulanlar listesini ilk önce, görev tanımının kendisinden önce okursunuz. Bunlar sizin yerinize verilmiş kararlardır: her biri ya konuya hakim birine onaya gider ya da görev tanımında bir işaretle kalır.

İkinci durum için işaret doğrudan dosyanın içine konur. Kararın önüne bir "varsayım:" satırı ya da satırın sonuna basitçe bir soru işareti: "düğme kulübün e-posta adresine gider (?)". Cevap geldiğinde neyin değişeceği hemen görünür. ve bunun nereden çıktığını hatırlamaya çalışmanız gerekmez.

İşaret iki yönlü çalışır. Soru işaretli bir görev tanımı alan ajan genellikle ilk iş olarak onları sorar: onun için de bu sizin için olduğu kadar net bir sinyaldir.

5. Sorular yerine sandbox

Bazen ne kadar uğraşırsanız uğraşın dört dayanak bir türlü yazılmaz. "2048 gibi bir şey istiyorum ama skor gerekli mi, kaydırma hareketi gerekli mi, hatta 4×4 mü olacak, bilmiyorum". Bu bir görev tanımı değil, alışıldık anlamda bir fikir bile değil. Bu bir yön: nereye gidileceği belli, sonuç belli değil. Burada sorular işe yaramaz: cevaplar ne sizde var ne de iş sahibinde ve ajanın önerilerini karşılaştıracak bir şeyiniz yok.

Böyle bir durumda en ucuzu bakmaktır. Bir sandbox kurun: bakabileceğiniz, kurcalayabileceğiniz ve aslında ne istediğinizi anlayabileceğiniz en basit sürüm. Ajanla bu on dakika sürer ve on dakikalık bir iş için sonucu çöpe atmak insanın içini acıtmaz.

Sandbox da dört dayanaklı bir görev tanımıdır, sadece hedefi farklıdır:

# Görev tanımı: 2048 sandbox

HEDEF:      2048'in tarayıcıda nasıl oynandığını görmek ve ne istediğimi anlamak.
            HTML, CSS ve JavaScript, derleme adımı yok

KURALLAR:   4×4 tahta
            ok tuşları taşları kaydırır, aynı olanlar birleşir
            hamleden sonra yeni bir taş çıkar

YAPMIYORUZ: geri kalan her şey: kazanma, kaybetme, skor, kaydırma hareketi, tasarım

KONTROL:    beş dakika oyna ve neyin eksik, neyin fazla olduğunu yaz

Neyin değiştiğine bakın. Hedef bir oyun değil, anlamak. "Yapmıyoruz" en uzun satır ve içinde emin olmadığınız her şey var. Kontrol de "çalışıyor mu" değil, "artık ne biliyorum". Beş dakika oynadınız ve başta sorulamayan sorular kendiliğinden ortaya çıkıyor: kaydırma hareketi gereksiz, bilgisayarda ok tuşlarıyla oynanıyor; skor gerekli, o olmadan sıkıcı; 4×4 küçük, 5×5 denemek istiyorsunuz; kaybetme gösterilmeli, yoksa oyunun bittiği anlaşılmıyor.

Sandbox'ın sonucu işte bu. Kod değil, cevaplar. Bunlardan gerçek görev tanımı yazılır ve gerçek sürüm sıfırdan, temiz bir klasörde, tek bir cümleyle kurulur: "dosyadaki görev tanımına göre oyunu yap". Sandbox görevini tamamladı.

Bu, ilk bölümdeki zincirin aynısı, sadece buradaki "Sorular" adımının yerini bir döngü aldı: sorulacak bir şey yoksa önce bakarız, sonra yazarız. Aşağıya, görev tanımına tek bir şey iner: cevaplar. Sandbox'tan ajana ok yok ve bu bir unutkanlık değil: ajan gerçek sürümü temiz bir klasörde, sıfırdan kurar. gerisi zincirdeki gibi devam eder.

6. Görev tanımı bir dosyada yaşar

Neden yazışma değil de dosya? Yazışma kaybolur: on mesaj sonra taşların birleşmesiyle ilgili kuralı artık bulamazsınız. Dosya proje klasöründe kodun yanında durur, siz gösterdiğinizde ajan onu kendisi okur, düzeltip yeniden vermek de aynı cümleyle olur. Adı ne olursa olsun: SPEC_2048.md, SPEC_LANDING.md, hatta gorev.txt. Sıradan bir metin dosyası, özel bir formatı yok.

Tek bir cümleyle verilir. Karşılaştırın:

Önce: "2048 oyununu yap, hani anladın ya hangisi, daha ilginç olsun".

Sonra: "SPEC_2048.md dosyasındaki görev tanımına göre oyunu yap".

İkinci istek birincisinden kısa, ama içindeki bilgi on kat fazla: bilgi dosyada. Görev tanımının metnini sohbete kopyalamanıza gerek yok, ajan dosyayı kendisi açar.

Neyi dosyada değiştirmeli, neyi sözle söylemeli? Ölçüt şu: bir kural ya da sınır değiştiyse dosyayı düzeltir ve yeniden veririz ("kazanma 1024'te değil, 2048'de": bu dosyaya gider). Kuralları etkilemeyen küçük bir görünüm ayrıntısı değiştiyse sözle söylenebilir ("düğmeyi mavi yap"). Emin değilseniz dosyaya yazın: fazladan bir satır, unutulmuş bir kuraldan ucuzdur.

Uzunluk hakkında. Küçük bir iş için bu, yukarıdaki 2048 bloğu gibi altı-sekiz satırdır. Bir akşamlık oyunun görev tanımı iki sayfaya uzadıysa, büyük ihtimalle içine "yapmıyoruz" kısmına girmesi gereken şeyler girmiştir.

Son olarak, dosyayı ajana vermeden önce onu bir kez başkası yazmış gibi okuyun. Kontrol edilemeyen bir satır neredeyse her zaman çıkar. benim dosyalarımda çıkıyor.

7. Ajan görev tanımıyla ne yapar, size ne kalır

Hepsini tek bir tabloda toplayalım: bu düzende Claude Code ne yapıyor, sizin tarafınızda ne kalıyor. Çift çift.

Görev tanımının amacı ajanın anlaması değil. O iki kelimeden de bir şeyler kurar. Amaç, ne istediğinizi sizin bilmeniz ve bunu kontrol edebilmeniz.