Yapay zeka ajanına görev nasıl verilir: seferde bir özellik, özellik listesi ve tamamlanma kriterleri

Ajan neden her şeyi bir arada yapmaya çalışır

Ajana kayıt işlemini yaptırdığınızı düşünün. Birkaç saat sonra diffte on iki değiştirilmiş dosya ve sekiz yüz yeni satır vardır: kullanıcı modeli, e-posta doğrulaması, bağlanmış bir e-posta servisi, parola hashleme, yeniden düzenlenmiş middleware ve taşınmış testler. Her şey birbirine sıkı bağlıdır ve hiçbir senaryo baştan sona çalışmaz. Bir sonraki oturum bu koda baktığında nereden başlayacağını bilemez.

Sorun «kötü bir model» değil. İnsanın «bugünlük yeter» hissi ve doğal yorgunluğu vardır; bunlar iş kapsamını kendiliğinden sınırlar. Ajanda bunların hiçbiri yoktur. «Bu arada hata yönetimini de düzelteyim» demek ajan için birkaç düzine token tutar, ama proje için bedeli gerçektir: dikkat dağılır, bağımlılık artar, bitmiş bir şey kalmaz.

Basit bir aritmetik de vardır. C bağlamın faydalı kapasitesi, k ise ajanın aynı anda tuttuğu görev sayısı olsun. Her göreve yaklaşık C/k akıl yürütme kaynağı düşer. Bu değer tek bir görevi bitirmek için gereken miktarın altına indiğinde, hiçbir görev bitmez. Bu yüzden yapay zeka ajanına görev nasıl verilir sorusunun cevabı prompt'un formülasyonuyla değil, bir kısıtla başlar: aynı anda tek bir görev.

Tek özellik kuralı (WIP=1)

WIP, work in progress, yani devam eden iş sayısıdır. Ajan için bunu bire eşitlerler: her an yalnızca bir özellik aktiftir ve sonraki özellik, mevcut olan kontrolden geçtikten sonra başlar. Kural, ajanın her oturumda görmesi için proje talimat dosyasına (AGENTS.md veya CLAUDE.md) yazılır:

## Çalışma kuralları
- Herhangi bir anda `active` durumunda TAM OLARAK BİR özellik bulunur.
- Sonraki özelliğe, mevcut olan `passing` durumuna geçtikten sonra başlanır.
- «Bu arada» yeniden düzenlemek, yeniden adlandırmak, dizinleri yeniden
  organize etmek ve ilgisiz hataları düzeltmek YASAKTIR. Sorun görürseniz
  `BACKLOG.md` dosyasına yazın ve devam edin.
- Aktif özelliğin kapsamı dışındaki değişiklikler, yararlı olsalar bile ihlal sayılır.

Son madde göründüğünden daha önemlidir. Ajan kendi «bu arada» değişikliklerini yararlı sayar ve çoğu zaman haklı da olabilir. Ama kapsam dışı yararlı bir düzeltme yine de iki görevi tek bir diff içinde karıştırır; artık bunları ayrı ayrı geri almak ya da doğrulamak mümkün değildir.

BACKLOG.md: «bu arada» düşüncelerinin gideceği yer

«Bu arada düzelteyim» dürtüsü yalnızca yasaklanamaz; ona meşru bir çıkış yolu gerekir. Bu yol BACKLOG.md dosyasıdır: ajan fark ettiği sorunu bir ya da iki satırla oraya yazar ve mevcut özelliğine geri döner. Bilgi kaybolmaz, kapsam da büyümez. Backlog olmadan tek özellik kuralı zamanla atlatılır, çünkü ajana «sorunu sessizce bırakmak», kuralı ihlal etmekten daha kötü görünür.

# BACKLOG.md
- [ ] middleware/errors.py: /auth ve /orders için farklı hata formatı
- [ ] tests/: kullanıcı fixture'ları üç dosyada tekrar ediyor
- [ ] kayıtta e-posta doğrulaması gerekli mi? — sor

Tamamlanma kriterleri: «tamam» bir komuttur

Sorunun ikinci yarısı, ajanın görevin bittiğine kendisinin karar vermesidir. «Kod normal görünüyor», «fonksiyon mevcut», «derleme hatası yok» gibi ifadeler hislerdir, gerçek değildir. Ajan için bir görevin tamamlanma kriteri, sonucu net olan çalıştırılabilir bir komut olmalıdır: geçer ya da geçmez.

F01: kullanıcı kaydı
verification: pytest tests/e2e/test_auth.py::test_register_flow
state: active

Zayıf ve sıkı kriter arasındaki fark örneklerde net görünür:

İyi bir doğrulama komutu deterministiktir (aynı kodda aynı sonuç), insan müdahalesi olmadan çalışır ve davranışı dışarıdan, kullanıcının ya da API istemcisinin göreceği şekilde kontrol eder. Böyle bir komut yazamıyorsanız, bu görevin net tanımlanmadığının işaretidir.

Parçalama: bir özellik ne kadar büyük olmalı

Tek özellik kuralından sonra en sık gelen soru, neyin özellik sayılacağıdır. Çok geniş bir görev tek oturumda bitmez; çok dar bir görev ise başlatma, bağlam ve doğrulama giderlerinde kaybolur.

• Çok geniş: «sepeti uygula». Bu bir haftalık iş ve düzinelerce senaryo demektir.
• Tam yerinde: «kullanıcı bir ürünü sepete ekleyip orada görebilir». Tek gözlemlenebilir davranış, tek doğrulama senaryosu.
• Çok dar: «CartItem modeline quantity alanını ekle». Bu bir uygulama adımıdır, davranış değildir; ayrı doğrulamanın anlamı yoktur.

Pratik bir boyut testi: bir özellik = bir ajan oturumu = bir anlamlı commit = bir uçtan uca (E2E) senaryo. Özellik tek oturuma sığmıyorsa daha da bölün. Ona ayrı bir senaryo yazılamıyorsa çok küçüktür; komşusuyla birleştirin.

Örnek: «sepet» görevinin parçalanması

Geniş gereksinim, her biri tek bir davranışa ve kendi doğrulama komutuna sahip atomik birimlere bölünür:

1. Ürünü sepete ekle ve listede gör.
2. Ürün adedini değiştir — toplam yeniden hesaplanır.
3. Ürünü sepetten kaldır.
4. Misafir sepeti hesaba giriş yaptıktan sonra korunur.
5. Stokta olmayan ürün eklenemez — anlaşılır bir hata mesajı gösterilir.

Son kontrol: hiçbir birim diğerine «bu arada» dokunmayı gerektirmemelidir. 4. madde için 1. maddeyi yeniden yazmak gerekiyorsa, sıra ya da sınırlar yanlış seçilmiştir.

Özellik listesi: feature_list.json

Tek özellik kuralı oturum içindeki sırayı korur. Peki oturumlar arasında neyin bittiğini kim hatırlar? Sohbete «auth ve katalog bitti, sepet neredeyse hazır ama hatalar var» yazmak yeni oturuma hiçbir şey kazandırmaz: «neredeyse» ne demek, hangi testler geçti, ödemeyi neyin engellediği belli değildir. Her yeni oturum aynı arabayı süren yeni bir sürücü gibidir: notlar yalnızca önceki sürücünün kafasındaysa, yeni sürücü hiçbir şey bilmez.

Bu yüzden durum dışarı, makine tarafından okunabilir bir dosyaya taşınır. Kursta bu .agent/feature_list.json dosyasıdır:

[
  {
    "id": "F01",
    "behavior": "Kullanıcı e-posta ve parolayla kaydolur ve hemen giriş yapar",
    "verification": "pytest tests/e2e/test_auth.py::test_register_flow",
    "state": "passing",
    "evidence": "a3f9c12: 1 passed in 2.31s"
  },
  {
    "id": "F02",
    "behavior": "Kullanıcı ürünü sepete ekler ve listede görür",
    "verification": "pytest tests/e2e/test_cart.py::test_add_item -q",
    "state": "active"
  },
  {
    "id": "F03",
    "behavior": "Siparişin kartla ödenmesi",
    "verification": "pytest tests/e2e/test_payment.py -q",
    "state": "blocked",
    "blocker": "ödeme geçidinin test anahtarları yok"
  }
]

Her kaydın üç zorunlu alanı vardır: dışarıdan gözlemlenebilen davranış tanımı, insan gerektirmeden çalışan doğrulama komutu ve durum. İsteğe bağlı dördüncü alan evidence alanıdır: commit hash'i ve doğrulama çıktısı, yani passing durumuna geçişin gerçekten yaşandığının kanıtı.

Neden Markdown listesi değil de JSON? Bu dosyayı yalnızca ajan değil, betikler de okur: planlayıcı not_started durumundaki bir sonraki özelliği seçer, doğrulayıcı kontrol komutunu alır, oturum raporu otomatik toplanır ve durum dağılımı projenin sağlık metriklerini verir. Özellik listesi harness'in omurgasıdır, bir hatırlatma notu değil.

Dört durum ve izin verilen geçişler

Başka geçiş yoktur. Özellikle doğrulamayı atlayarak passing durumuna geçmenin bir yolu yoktur ve «neredeyse bitti» diye bir durum da yoktur.

passing kapısı: ajan talep edebilir, ilan edemez

Bu şemanın merkezi kuralı: ajan state alanını elle düzenlemez. Doğrulamayı çalıştırabilir, ama sonucu kendisi ilan edemez; bunu betik yapar. «Ajan bildirdi» ile «betik doğruladı» arasındaki fark, metin ile gerçek arasındaki farktır. Kuralları da talimat dosyasına yazılır:

## Özellik listesi kuralları
- Dosya: `.agent/feature_list.json`. Kapsam için tek doğruluk kaynağı budur.
- Tam olarak bir özellik `active` durumunda olmalı.
- `state` alanını ELLE DEĞİŞTİRMEZSİN. Bunu `scripts/verify.sh` değiştirir.
- Bir özelliği `passing` yapmak için `./scripts/verify.sh F02` çalıştır ve 0 kodu al.
- Özellik engellenmişse `blocked` yap ve mutlaka `blocker` belirt.
- Yeni özellikler yalnızca `not_started` durumunda ve doğrulama komutuyla eklenir.

Betik iki seviyede kontrol eder: önce projenin genel çalıştırması (özellik diğer her şeyi bozmamalı), sonra o özelliğin kendi komutu. Genel bir gerilemede yerel bir başarı başarı sayılmaz.

#!/usr/bin/env bash
# passing durumunu atama hakkına sahip tek bileşen.
set -uo pipefail
FID="$1"
FILE=".agent/feature_list.json"

CMD=$(jq -r --arg id "$FID" '.[] | select(.id==$id) | .verification' "$FILE")
if [ -z "$CMD" ] || [ "$CMD" = "null" ]; then
  echo "FAIL: $FID için doğrulama komutu yok"; exit 2
fi

echo "== genel kontrol =="
make check || { echo "FAIL: genel kontrol kırmızı, $FID passing olamaz"; exit 1; }

echo "== özellik kontrolü: $CMD =="
if OUT=$(eval "$CMD" 2>&1); then
  SHA=$(git rev-parse --short HEAD)
  LAST=$(printf '%s\n' "$OUT" | tail -n 1)
  TMP=$(mktemp)
  jq --arg id "$FID" --arg ev "$SHA: $LAST" \
    'map(if .id==$id then .state="passing" | .evidence=$ev else . end)' \
    "$FILE" > "$TMP" && mv "$TMP" "$FILE"
  echo "PASS: $FID"
else
  printf '%s\n' "$OUT"
  echo "FAIL: $FID"; exit 1
fi

Metinde yazılı «state'i düzenleme» kuralı hâlâ bir istektir. Bunu bir kısıta dönüştürmek için dosyaya yazmayı mekanik olarak kapatabilirsiniz: evidence alanını commit geçmişiyle karşılaştıran bir CI kontrolüyle ya da aracınızdaki ajan izinlerini kısıtlayarak. İlke harness'in her yerinde aynıdır: önemli kural mekanizmayla desteklenir.

Ajanın görevleri bitirdiğini nasıl ölçersiniz

Cazip bir metrik, oturum başına kod hacmidir. Pratikte tersini gösterir: büyük bir diff çoğunlukla ajanın birkaç yöne dağıldığı anlamına gelir. Satır sayısı yerine passing durumundaki özellikleri sayın.

Kursta kullanılan faydalı bir metrik VCR (Verified Completion Rate): doğrulanmış görev sayısının aktifleştirilen görev sayısına bölümü. Kural basittir: VCR bire ulaşmadan yeni görev aktifleştirilemez. Bu, harness'in ajana uyguladığı geri basınçtır ve yarım kalan işi bir his değil, görünür bir sayı yapar.

Ajana görev verirken sık yapılan hatalar

• Doğrulama komutu olmayan görev. Senaryosuz «kayıt işlemini yap» demek, ajanın nerede duracağına kendisinin karar vermesi ve bunu yanlış vermesi demektir.
• Tek istekte birden fazla özellik. «Sepeti ve ödemeyi yap» iki aktif görev demektir ve hiçbiri sonuna kadar götürülmez.
• Durumun yalnızca sohbette tutulması. Yazışmaya kaydedilen ilerleme oturum bittiğinde kaybolur. Dosyada yaşamalıdır.
• Doğrulama yerine öz bildirim. «Ajan testlerin geçtiğini söyledi» ile betiğin 0 çıkış kodu aynı şey değildir.
• Backlog yokluğu. «Bu arada» yasağına, fark edilenlerin yazılacağı bir yer eklenmezse ajan bu yasağı atlatır.

Tek özellik bile yetmediğinde

«Bir özellik — bir oturum — bir doğrulama» şeması tek ajanın tek döngüsünde iyi çalışır. Görev sayısı arttığında ve bağımsız dallar ortaya çıktığında, bu şema birden fazla döngüden oluşan bir sisteme genişletilir: ayrı bir planlama düğümü, uygulama düğümleri, bir doğrulama düğümü ve aralarındaki kenarlar. Kenarlar paralel, koşullu olabilir ve doğrulama geçmezse uygulamaya geri dönebilir. Ama orada da her uygulama düğümü aynı kuralla çalışır: tek görev, çalıştırılabilir tamamlanma kriteri ve durumun ajanın kafası dışında tutulması. Grafik tek özellik disiplinini ortadan kaldırmaz, onun üzerine kurulur.

Aynı analizdeki önemli bir uyarı: döngü, kendisine verilen metriği dürüstçe optimize eder. Tamamlanma kriteri kötü seçilmişse, örneğin «iş açıldı» yerine «sorun çözüldü» yerine «bilet kapatıldı» gibi, ajan görevi değil kriteri yerine getirmeyi öğrenir. Bu yüzden davranış ve doğrulama komutunun formülasyonu göründüğünden daha fazla emek ister.

Özet

Kısaca, yapay zeka ajanına görev nasıl verilir: birer birer, gözlemlenebilir davranış ve çalıştırılabilir doğrulama komutuyla, yolda fark edilen her şey için bir backlog ile ve «tamam» geçişini ajanın değil betiğin yaptığı bir özellik listesiyle. Frene ajanın kendisi basmaz; onu harness koyar. WIP=1 kuralı, feature_list.json ve verify.sh, kursta uçtan uca bir proje üzerinde uygulamalı olarak işlenir.