04ProjelerProje 04 / 06
Geri Bildirim Halkası
Serbest formda features.md'den yapılandırılmış features.json + verify.sh + WIP=1 kuralına. Çalışma zamanı geri bildirimini ajan otomasyonuna bağlayın.
- Okuma
- 4 dakika
- Yayın
- 19 Mayıs 2026
Kodu al
git clone https://github.com/komunite/harness-docs && cd harness-docs/projeler/04/starter
Senaryo: 12 dosya, 800 satır, 0% e2eörnek
Notes API repoları üzerinde tek cümlelik görev verildi: "kullanıcı favorilerini ve etiket sistemini ekle, bir de markdown render". İki saat sonra ajan oturumu bitti, repoya bakıldı:
- 12 değiştirilmiş dosya: modeller, üç route, bir middleware, frontend stub, README değişikliği
- ~800 satır kod
- Uçtan uca geçen senaryo: 0/3 (favoriler kaydetmiyor, etiket endpoint'i 404, markdown render fonksiyonu çağrılmıyor)
- "Yapıldı" diye işaretlenmiş özellik sayısı: 3
- Doğrulanmış özellik sayısı: 0
Ajan hatalı değildi, düzenek (harness) yoktu. Özellik listesi features.md adında serbest formda bir prozaydı. Bunu okuyan ajanın bir öncelik haritası çıkarması da, bittiğini iddia ettiği işin gerçekten bittiğini kanıtlaması da imkânsızdı. Aşırıya kaçma ile yarım bırakma, Ders 07'de söylediğimiz simbiyozla, aynı oturumda yan yana durdu.
Bu projede features.md serbest formunu features.json yapılandırılmış primitifine çeviriyoruz, scripts/verify.sh ile WIP=1 kuralını mekanik olarak zorlayan bir doğrulama scripti kuruyoruz, ve AGENTS.md içine ajanın değiştiremeyeceği bir Feature Liste Kuralları bloğu yerleştiriyoruz.
Bu projede ne öğreneceksin
- Düzenek Mühendisliği (Harness Engineering) içinde özellik listesinin neden primitif olduğunu: bir doküman değil, scheduler/verifier/handoff reporter/progress tracker'ın okuduğu veri yapısı olduğunu.
not_started,active,blocked,passingdört durumlu makineyifeatures.jsonüzerinde çalıştırmayı.jqile features dosyasını sorgulamayı: aktif feature'ı bulmak, durum dağılımı çıkarmak, geri basınç (backpressure) hesaplamak.verify.shile pass-state kapısını ajandan alıp düzeneğe vermeyi: durumpassing'e ancak doğrulama komutu sıfır çıkış koduyla biterse geçer.- WIP=1 invariant'ını mekanik bir kilitle uygulamayı: iki feature aynı anda
activeise scriptexit 3ile reddeder. AGENTS.mdiçine konacak Feature Liste Kuralları bloğunu: ajanın bu kuralları değiştirme yetkisi olmadan okuyup uyguladığı sözleşmeyi.
Yapı
projeler/04/
├── starter/ # serbest formda features.md, verify.sh yok
│ ├── AGENTS.md
│ ├── features.md # prose, soft, "galiba"-lar dolu
│ ├── app.py
│ ├── Makefile
│ ├── PROGRESS.md
│ ├── DECISIONS.md
│ └── tests/
└── solution/ # features.json + verify.sh + WIP=1 kuralı
├── AGENTS.md # "Feature Liste Kurallari" blogu eklendi
├── features.json # F01 passing, F02 passing, F03 not_started,
│ # F04 not_started, F05 blocked
├── scripts/
│ └── verify.sh # jq-driven, WIP=1 enforce, state machine
├── app.py
├── Makefile # `make verify` -> bash scripts/verify.sh
├── PROGRESS.md
├── DECISIONS.md
└── tests/starter ile solution arasındaki fark
projeler/04/starter/features.md, proza, yumuşak, ölçülemez:
Yapilacaklar: arama duzelt (tamam galiba, testler yesil — son commitle birlikte
parametreli surume cevrildi), etiket sistemi ekle (devam ediyor? — kafamda var
ama henuz kod yazilmadi, belki yarin), kullanici favorileri (henuz baslanmadi...),
markdown body destegi (belirsiz — frontend yok, sadece sunucu tarafinda render mi
yoksa pass-through mu karar verilmedi, biri "blocked" demisti)...Bu paragraf üç problemi aynı anda taşır:
- Durum belirsiz. "Galiba", "devam ediyor?", "belirsiz": bir makinenin okuyup karar veremeyeceği kelimeler. Doğrulama komutu yok, "tamam" denmesi
passinganlamına gelmiyor. - WIP yok. Aynı satırda dört iş "üzerinde" gözüküyor. Ajan oturumu açtığında hangisinin aktif olduğunu seçmek zorunda ve her seferinde farklı seçer.
- Kanıt yok. "Testler yeşil" iddiası kim tarafından ne zaman doğrulandı? Hangi commit? Hangi log?
projeler/04/solution/features.json aynı bilgiyi state machine olarak verir (strict, ölçülebilir, jq-driven):
[
{
"id": "F01",
"behavior": "Notes CRUD — POST /notes 201, GET /notes/{id} 200, liste, 401",
"verification": ". .venv/bin/activate && pytest tests/test_smoke.py -q",
"state": "passing",
"depends_on": [],
"evidence": "commit a1b2c3d — tests/test_smoke.py 4 passed in 0.42s"
},
{
"id": "F02",
"behavior": "GET /notes/search?q=...; bos sorgu [] doner; quote -> SQL injection yok",
"verification": ". .venv/bin/activate && pytest tests/test_search.py -q",
"state": "passing",
"depends_on": ["F01"],
"evidence": "commit b2c3d4e — 4 passed; proje 04'te parametreli sorguya cevrildi"
},
{ "id": "F03", "state": "not_started", "behavior": "tags endpoint", "...": "..." },
{ "id": "F04", "state": "not_started", "behavior": "favorites endpoint", "...": "..." },
{ "id": "F05", "state": "blocked", "evidence": "markdown kutuphanesi secilmedi", "...": "..." }
]Beş feature, dört alan zorunluluğu (behavior, verification, state, evidence), bağımlılık grafiği (depends_on). F01 ve F02 doğrulanmış (kanıtı commit hash ile), F03 ve F04 henüz başlanmamış, F05 blocked: kütüphane seçimi DECISIONS.md'ye yazılana kadar açılmaz. Aktif feature şu anda yok. Sıradaki ajan oturumu hangisini active yapacağını rastgele değil, scheduler tarafından söylenerek seçer.
Adım adım
1) Repoyu al
git clone https://github.com/komunite/harness-docs harness-04
cd harness-04/projeler/042) starter'a bak: şüpheli durum
cd starter
cat features.mdDosyayı okudukça soru biriktir: "etiket sistemi" hangi state'te? "Arama düzelt" gerçekten passing mi yoksa son commit'te birisi öyle yazıvermiş mi? "Markdown body" blocked dendi ama hangi engel? make test çalıştırdığında hangi feature'ın testleri yeşil olmalı? Yanıt yok, çünkü dosyada state alanı yok, verification komutu yok, evidence referansı yok. Bu repoya gelen yeni ajan, oturumun ilk 15 dakikasını teşhise harcar.
3) solution'a geç
cd ../solution
cat features.json | jq '.'JSON çıktısı net: beş feature, her birinde dört zorunlu alan, durum dağılımı tek bakışta görünür.
4) Durum dağılımını çıkar (progress tracker rolü)
jq -r 'group_by(.state) | map({state: .[0].state, count: length}) | .[] |
" " + .state + ": " + (.count|tostring)' features.jsonBeklenen çıktı:
blocked: 1
not_started: 2
passing: 2VCR (Verified Completion Rate) = passing / aktive edilmiş = 2 / 2 = 1.0, yeni feature active'e alınabilir.
5) Aktif feature'ı sorgula
jq '.[] | select(.state=="active")' features.jsonBoş döner: şu an aktif yok, sıradaki iş güvenle başlatılabilir.
6) verify.sh çalıştır: boş durum
bash scripts/verify.shBeklenen:
bilgi: active feature yok — yapilacak dogrulama yok
blocked: 1
not_started: 2
passing: 2Script sıfır kodla biter, hiçbir şeyi değiştirmez: yapacak iş yok.
7) F03'ü active yap, verify.sh tekrar çalıştır
jq '(.[] | select(.id=="F03").state) = "active"' features.json > /tmp/f.json \
&& mv /tmp/f.json features.json
bash scripts/verify.shF03 aktif, doğrulama komutu (pytest tests/test_tags.py -q) çalışır. Tag endpoint'i henüz yazılmadığı için test başarısız olur, verify.sh sıfır-dışı kodla çıkar, state active kalır. Pass-state kapısı kapalı: ajan kendi başına passing yazamaz.
8) WIP=1 ihlalini dene: exit 3 reddi
F02 zaten passing. Onu da active yapalım, yani iki feature aynı anda aktif olsun:
jq '(.[] | select(.id=="F02").state) = "active" |
(.[] | select(.id=="F03").state) = "active"' features.json > /tmp/f.json \
&& mv /tmp/f.json features.json
bash scripts/verify.sh ; echo "rc=$?"Beklenen:
hata: WIP=1 ihlali — 2 adet active feature var
F02 — GET /notes/search?q=... eslesn notlari doner...
F03 — POST /notes/{id}/tags ile bir nota etiket eklenir...
rc=3Script hiçbir doğrulama çalıştırmadan, hiçbir dosya değiştirmeden exit 3 ile reddeder. WIP=1 invariant'ı mekanik bir kilitle korunur: ajanın "iki şeyi paralel yapayım" demesi mümkün değil. Düzenek izin vermiyor.
Beklenen sonuçlar
Bu proje sonunda elinde olması gerekenler:
features.jsonprimitifi: beş feature, dört alanlık zorunluluk, durum makinesi (not_started/active/blocked/passing), bağımlılık grafiği.scripts/verify.sh:jq-driven, WIP=1 invariant'ınıexit 3ile zorlar, aktif feature'ınverificationkomutunu çalıştırır, sıfır kod ->statepassing+evidence(commit hash + UTC zaman damgası) yazar, sıfır-dışı kod ->activekalır.AGENTS.mdiçinde Feature Liste Kuralları bloğu: ajan kuralları değiştiremez, sadece uygular: features kaynak dosyasıfeatures.json'dir, WIP=1, pass-state kapısı script'e aittir, VCR 1.0'ın altındayken yeniactiveyok.- Geri bildirim halkası: kod yazılır,
make verifyçalıştırılır, sonuç dosyaya geri yazılır, ajan bir sonraki oturumdafeatures.jsondurum dağılımını okuyarak nereden devam edeceğini bilir.
Sayısal hedef (Ders 07 tablosuyla uyumlu): aynı beş feature sınırsız WIP altında ~%37,5örnek tamamlanma, ~31 dokunulmuş dosya, ~2,4 saat lead time verirken, WIP=1 + verify.sh altında ~%87,5örnek tamamlanma, ~9 dokunulmuş dosya, ~0,6 saat lead time.
Yerel çalıştırma
cd projeler/04/solution
# bagimliliklar
python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
command -v jq >/dev/null || brew install jq # macOS
# durum fotografi
jq -r 'group_by(.state) | map({state: .[0].state, count: length}) | .[] |
" " + .state + ": " + (.count|tostring)' features.json
# aktif feature varsa dogrula
make verify # -> bash scripts/verify.sh
# tum testler
make testmake verify scripts/verify.sh'i sarar, CI'da da aynı komut çağrılır.
İlgili dersler
- Ders 07: WIP=1 Disiplini: Aşırıya kaçma ile yarım bırakmanın simbiyozu, Little's Law (L = λ × W), VCR, geri basınç.
- Ders 08: Özellik Listesi Bir Primitiftir: Özelliğin üçlüsü (behavior, verification, state), dört durumlu makine, listeyi okuyan dört komponent (scheduler, verifier, handoff reporter, progress tracker), granülerlik.
Sıradaki proje
Proje 05: Yapan ve Denetleyen: features.json artık WIP=1 kuralını mekanik olarak uyguluyor. Bir sonraki adım, "tamamlandı" yargısını executor'dan bağımsız bir verifier rolüne dışsallaştırmak. Doğrulama halkasını kurduktan sonra, halkayı kimin kapatacağına karar veren rol ayrımını ekliyorsunuz.