01ProjelerProje 01 / 06
Kural Öncelikli
Aynı görev, iki düzenek seviyesi. Yalın prompt'tan AGENTS.md + Makefile + smoke test'e geçişin etkisini kendi reponuzda ölçün.
- Okuma
- 4 dakika
- Yayın
- 19 Mayıs 2026
Kodu al
git clone https://github.com/komunite/harness-docs && cd harness-docs/projeler/01/starter
Yeni klonladığın repoyu açıyorsun. Karşında iki satırlık bir task.md ve neredeyse boş bir app.py var: bir FastAPI() örneği ve bir TODO yorumu. Yığını söyleyen dosya yok, "tamamlandı"nın ne demek olduğunu söyleyen bir komut yok, doğrulamayı kim yapacak belirsiz. Bir ajan olsan tahmin etmeye başlardın: Python sürümü, depolama, token kaynağı, hata mesajları. Sohbete dönüp soru sorar, cevap gelmeyince varsayım koyar, ve sonunda "bitti" derdin, kimse aksini söyleyemediği için.
Bu proje aynı sahneyi iki kez kuruyor. Bir kez yalın prompt ile (projeler/01/starter/), bir kez minimum kural seti ile (projeler/01/solution/). Görev aynı: Notes API'ye Bearer kimlik doğrulaması ekle. task.md aynı. Tek değişen düzenek (harness): modeli kuşatan talimat, ortam ve geri bildirim aparatları. Amaç, bu iki klasörün diff'inin kendi başına bir argüman olduğunu göstermek.
Bu projede ne öğreneceksin
- Yalın prompt koşumunun neden yapısal olarak güvenilmez olduğunu kendi gözünle gör, sohbet penceresinin neden bir düzenek yerine geçmediğini deneyimle.
- Minimum bir düzeneğin (talimat router'ı + dört Makefile hedefi + smoke test) hangi başarısızlık modlarını kapattığını işaretlemeyi öğren.
- "Tamamlandı"nın bir kanaat değil, koşulabilir bir komut olduğunu pratikle kavra:
make checkyeşilse iş bitmiştir, değilse değildir. - AGENTS.md'nin neden bir ansiklopedi değil, kısa bir router olması gerektiğini örnek üzerinden anla.
- Ablasyon refleksini kazan: bir aparatı (Makefile, smoke test, AGENTS.md) sökmenin başarı oranına etkisini ölç ve raporla.
Yapı
İki klasör aynı görev tanımını paylaşır. Tek fark, solution'a eklenmiş düzenek aparatlarıdır.
projeler/01/
├── starter/
│ ├── README.md # neden bilinçli olarak eksik
│ ├── task.md # iki satırlık ham görev
│ └── app.py # boş FastAPI() + TODO
└── solution/
├── README.md # kural öncelikli kurulumun anlatımı
├── AGENTS.md # talimat router'ı (sıkı kısıtlar + doğrulama sözleşmesi)
├── Makefile # setup / dev / test / check
├── pyproject.toml # Python 3.11+ sürüm sözleşmesi
├── requirements.txt # bağımlılıklar
├── app.py # Bearer auth + SQLite Notes API uygulaması
└── tests/
└── test_smoke.py # 4 senaryo — "tamamlandı"nın operasyonel tanımıStarter'da görev bir kâğıt parçası, solution'da görev bir sözleşmedir.
starter ile solution arasındaki fark
Diff bir prompt değişikliği değil, repo düzeyinde bir sözleşmedir. Üç katmanı yan yana koymak yetiyor.
Talimat aparatı. Starter'da AGENTS.md yok. Solution'da repo köküne konmuş bir AGENTS.md var ve içeride beş başlık yaşar: "Sıkı kısıtlar", "Dev Environment Tips", "Testing Instructions", "PR Instructions", "Doğrulama komutları". Dosya bir router'dır: yığını (Python 3.11, FastAPI, SQLite), sıkı kısıtları (Authorization: Bearer <API_TOKEN> zorunlu, SQL parametrize, make check yeşil olmadan teslim yok) ve doğrulama sözleşmesini söyler. Ajan bu repoya girdiğinde "tamam" demenin koşullarını öğrenir, sohbete sormak zorunda kalmaz.
Ortam aparatı. Starter'da bağımlılık tanımı yok, kurulum komutu yok, sunucuyu nasıl başlatacağın yazılı değil. Solution'da Makefile dört kanonik hedef sunar:
setup: pip install -r requirements.txt
dev: uvicorn app:app --reload
test: pytest tests/ -x
check: ruff + mypy (varsa) + pytestDers 02'de tarif edilen dört hedef burada birebir karşılanır. Ajan ortamı sohbete sormaz, make setup yazıp koşar.
Geri bildirim aparatı. En önemli fark burada. Starter'da test yok, "çalışıyor" demenin kanıtı yalnızca ajanın iddiasıdır. Solution'da tests/test_smoke.py dört davranış kanıtı taşır:
def test_missing_token_returns_401(client): ...
def test_post_with_valid_token_returns_201(client): ...
def test_get_by_id_returns_same_body(client): ...
def test_list_contains_created_note(client): ...Bu dört test bir referans değil, "tamamlandı"nın operasyonel tanımıdır. Her biri yeşilse görev bitmiştir, bir tanesi kırmızıysa ajanın "bitti" demesi yapısal olarak yanlıştır. Sözleşme AGENTS.md içinde tek satıra düşer: "make check yeşil olmadan teslim yapılmaz."
Adım adım
Aşağıdaki yürüyüş, başarısızlığı ve çözümü yan yana gözleyebilmen için tasarlandı.
- Repoyu klonla ve proje klasörüne in:
git clone https://github.com/komunite/harness-docs && cd harness-docs/projeler/01. - Önce starter'a gir:
cd starter. İçerikte yalnızcatask.mdveapp.pyolduğunu doğrula. - Bu klasörü kendi ajan istemcinde aç (Claude Code, Cursor, ya da tercih ettiğin koşumcu) ve
task.md'yi prompt olarak ver. Ajanın davranışını gözlemle: hangi soruları soruyor, hangi varsayımları koyuyor, kodu koşturuyor mu, neyin "tamam" sayılacağına nasıl karar veriyor? - Üretilen kodu çalıştırmaya çalış. Çoğu koşumda şu kalıpları göreceksin: Python sürümü tutmuyor, bağımlılık listesi bulunamıyor, "401" davranışı belirsiz, ajan testsiz teslim ediyor, sen kontrol etmedikçe geri bildirim akmıyor. Bu Ders 01'in doğrulama boşluğu (verification gap) örüntüsünün canlı kopyasıdır.
- Şimdi solution'a geç:
cd ../solution.AGENTS.md,Makefile,pyproject.toml,tests/test_smoke.pyartık yerinde. - Tek komutla doğrulamayı koştur:
make setup && make check.pytest tests/ -xçıktısının dört yeşil noktayla bittiğini gör.Makefilecheckhedefiruffvemypyvarsa onları da koşar, yoksa graceful atlar vepytestyeter. - Solution klasörünü aynı ajan istemcinde aç ve yine
task.md'yi prompt olarak ver. Bu sefer ajanın davranışı kategorik olarak farklıdır:AGENTS.md'yi okur, kısıtları kabul eder,make checkkoşar, çıktıyı raporlar. "Tamam"ı söyleyen artık ajan değil, dört yeşil test. - İki koşumun farkını üç başlıkta yaz: hangi başarısızlık modu hangi aparatla kapandı, hangi aparat olmasaydı yine başarısız olunurdu, ablasyonu nasıl ölçerdin? Bu yazılı diff bu projenin teslim çıktısıdır.
Beklenen sonuçlar
Solution tarafında make check koşulduğunda terminalde şu görüntü beklenir:
============== 4 passed in 0.42s ==============Dört smoke testi yeşil olmadan iş tamamlanmış sayılmaz. Starter tarafında üretilen koddan aynı testler koşulmadığı için "tamamlandı" iddiası sözeldir, solution tarafında aynı iddia ölçülmüştür. Aradaki fark, müfredatın temel argümanını tek bir terminal çıktısına indirir: model sabit, prompt sabit, çıktı kategorik olarak farklı. Tek değişen düzenektir.
Belgelenecek somut çıktılar:
- Starter'da ajanın sorduğu soruların ve koyduğu varsayımların listesi.
- Solution'da
make check'in tam terminal çıktısı (4/4 yeşil). - "Hangi aparat hangi başarısızlığı kapattı" eşlemesi: talimat → belirsiz tanım, ortam → kurulum sürtünmesi, geri bildirim → doğrulama boşluğu.
- (Opsiyonel) ablasyon notu:
tests/test_smoke.pysilinerek solution yeniden koşturulduğunda davranışın nasıl değiştiği.
Yerel çalıştırma
git clone https://github.com/komunite/harness-docs harness-docs
cd harness-docs/projeler/01
# Starter — bilinçli olarak çıplak. Kurulum/test komutu yok.
cd starter
cat task.md
cat app.py
# Buradan itibaren kendi ajanınla deneyimle: kuralsız koşumun davranışını gözle.
# Solution — minimum düzenek.
cd ../solution
make setup # pip install -r requirements.txt
make test # pytest tests/ -x
make check # ruff (varsa) + mypy (varsa) + pytest
# Canlı denemek için:
API_TOKEN=dev-token make dev
# başka bir terminalde:
curl -i http://localhost:8000/notes # 401 bekle
curl -i -H "Authorization: Bearer dev-token" http://localhost:8000/notes # 200 bekleSmoke testler izole bir SQLite dosyası ve sabit API_TOKEN=test-token ile koşar, canlı sunucuya ihtiyaç duymaz, dış servis çağırmaz. Bu izolasyon, doğrulamanın tekrarlanabilir olmasını garanti eder: Ders 02'nin "kendini açıklayan ortam" prensibinin pratikteki karşılığı.
İlgili dersler
- Ders 01: Yetkin Ajanlar Neden Başarısız Olur: doğrulama boşluğunun ne olduğu ve neden bir model değil bir konfigürasyon problemi olduğu.
- Ders 02: Düzeneğin Anatomisi: beş aparat (talimat, araç, ortam, durum, geri bildirim). Bu projedeki diff üç aparatı somutlaştırır.
Sıradaki proje
- Proje 02: Bilgi Mimarisi: bu projede gördüğün router AGENTS.md'yi şişmiş bir monolitten yönlendirici + konu dokümanları mimarisine taşır, "kısa ama yönlendirici" dengesini pratiğe döker.