06DerslerDers 06 / 12
Önce Temel, Sonra Duvar
Başlangıç (initialization) ayrı bir fazdır, ayrı bir optimizasyon hedefi vardır. Uygulama ile karıştırıldığında dört yerden birden çatlar. Düzenek Mühendisliği (Harness Engineering) müfredatının altıncı dersi.
- Okuma
- 5 dakika
- Yayın
- 19 Mayıs 2026
Temel kurumadan duvar örülmez
Şantiyede temel betonu döküldükten sonra usta beklemek zorundadır. Beton kürünü tamamlamadan duvar örülürse ya temel oturduğunda çatlaklar başlar, ya zemin eğri kalır, ya sıva tutmaz. Süre kısaltılırsa kalite alınır.
Yazılımda düzenek (harness) kurarken bu kuralı bilinçli olarak ihlal ediyoruz. Ajana "kullanıcı girişi ekle" diyoruz. Ajan tek oturumda hem package.json kurar, hem test çatısını yapılandırır, hem Makefile yazar, hem feature kodunu yazmaya başlar, hem de commit eder. Dördü de yarım kalır, hiçbiri sağlam olmaz.
Tez
Başlangıç (initialization) ve uygulama (implementation), farklı optimizasyon hedefleri olan farklı fazlardır. Başlangıcın hedefi "altyapı sağlam ve yeniden başlatılabilir olsun", uygulamanın hedefi "feature kabul kriterini geçsin"dir. Bu iki hedef tek pencerede aynı anda çözülmeye çalışılırsa ajan çok amaçlı bir optimizasyon problemiyle karşılaşır ve hepsini kötü çözer.
Anthropic'in Effective harnesses for long-running agents yazısında bu ayrım açıkça kurulur: ilk bağlam penceresi özel olarak "initializer agent" adıyla anılan dar kapsamlı bir ajana verilir. Bu ajanın görevi init.sh, claude-progress.txt ve "hangi dosyaların eklendiğini gösteren bir ilk git commit" üretmektir. Feature kodu daha sonraki ajanların işidir.
İki faz
Bootstrap önce. Init kabul kapısı. Sonra özellikler.
make setupsmoke testAGENTS.mdinit: bootstrap complete
- F01
- F02
- F03
- F04
- F05
init + feature aynı oturumda → her ikisi de yarım kalır
- make setup?
- F01 yarım
- Makefile…
- F02
- test?
- F03
- AGENTS.md?
- F04
- commit?
- CI…
Karıştırmanın dört maliyeti
Başlangıç ile uygulama tek oturumda yapıldığında dört tipik hata görülür.
1) Düzensiz altyapı
Feature kodu yazılırken altyapı önemsizleşir. Ajan zamanın yüzde sekseninden fazlasınıörnek feature'a, kalan sürede "şöyle bir Makefile da olsun"a ayırır. İlk gün çalışır görünür. Üçüncü oturumda make test başka bir ortamda kırılır.
2) Doğrulanamamış kod birikimi
Test çatısı yapılandırılmadan yazılan feature kodu doğrulanmadan repoya iner. Sonradan test eklendiğinde, mevcut kodun bir kısmının testi geçemediği keşfedilir. 12-factor agentops doktrini bunu Faktör VI altında "Lock Progress Forward" olarak adlandırır: yalnızca doğrulanmış iş kalıcı kontrol noktasına yazılmalıdır.
3) Örtük varsayım mayınları
Init fazında alınan kararlar yazıya dökülmediyse, ileride çelişen kararlar üretilir. "Auth için JWT mi session mi?" sorusunun cevabı DECISIONS.md dosyasında yoksa, bir hafta sonra başka bir oturum tersini seçebilir. Faktör II'nin "git'te değilse olmamıştır" kuralı bu mayınları en aza indirir.
4) Bağlam bütçesi israfı
Altyapı bağlam ister: dosyalar okunur, hata mesajları görülür, komutlar denenir. Feature aynı pencerede ele alınınca iki iş de aynı bütçeden beslenir. Pencere dolduğunda ikisi de eksik kalır.
Bootstrap Sözleşmesi: dört koşul
Bir başlangıç fazı, aşağıdaki dört koşulun tamamı sağlandığında bitmiş kabul edilir. Üçü tamam, biri eksikse iş hâlâ başlangıç fazındadır.
- Başlatılabilir: Temiz bir klonda
make setuphatasız çalışır. - Test edilebilir:
make testçalışır ve en az bir smoke testi geçer. - İlerleme görünür:
PROGRESS.mdilk satırları yazılı. Bir sonraki ajan ne yapılacağını okuyabilir. - Devamı belli: Sıralı bir feature listesi (
features.json) mevcuttur.
Bu sözleşme, Anthropic'in init.sh + claude-progress.txt + ilk commit üçlüsünün genişletilmiş halidir ve AGENTS.md formatının önerdiği üç bölümle (Dev Environment Tips / Testing Instructions / PR Instructions) doğrudan eşleşir.
Beş teslim çıktısı
Bir init fazı şu beş artefaktı teslim eder. Eksik herhangi biri, fazın bitmediği anlamına gelir.
- Çalıştırılabilir ortam. Bağımlılıklar kurulu, sürüm kısıtları net.
.nvmrc,.python-version,pyproject.toml,package-lock.jsonveyauv.lockgibi kilit dosyaları mevcut. Tek komut:make setup. - Doğrulanabilir test iskelesi. En az bir smoke testi yazılı ve geçiyor. CI (GitHub Actions veya benzeri) yeşil ilk koşusunu vermiş durumda. Anthropic'in initializer ajanının
init.shile ürettiği "çalışıyor mu" sinyalinin karşılığıdır. - Bootstrap sözleşmesi dokümanı. Başlangıç komutları (
make setup,make dev,make test,make check), bağımlılıkların güncel durumu, proje yapısıAGENTS.mddosyasında açıkça yazılı. Üç bölüm minimum: dev environment, testing, PR conventions. - Görev kırılımı (feature list). Sıralı, kabul kriterli, kısa bir liste. Anthropic'in claude.ai klonu örneğinde initializer'ın ürettiği JSON 200'den fazla feature içeriyor ve her biri başlangıçta "failing" olarak işaretleniyor. Senin projende bu, basit bir
features.jsonolabilir:[ { "id": "F01", "behavior": "POST /login JWT döner", "state": "not_started" }, { "id": "F02", "behavior": "GET /me JSON döner", "state": "not_started" }, { "id": "F03", "behavior": "GET /search?q=... eşleşmeleri döner", "state": "not_started" } ] - Git checkpoint. Init tamamlandığı anda temiz tek bir commit:
init: bootstrap complete. Bu, sonraki oturumların geri dönüş noktasıdır. 12-factor agentops'un Faktör VI'sının çıktısı: validated work, recorded checkpoint.
Pratik
Init kabul kontrol listesi
Bu liste ihlal edilemez. Listeden tek bir kalem eksikken feature çalışmaya başlanmaz.
## Init Acceptance
- [ ] `make setup` temiz bir klonda hatasız çalışıyor
- [ ] `make test` en az bir smoke testi geçiriyor
- [ ] `make check` lint + type + test'i sırayla koşturuyor
- [ ] AGENTS.md doldurulmuş (dev / test / PR bölümleri)
- [ ] PROGRESS.md ilk durumu yazılı
- [ ] DECISIONS.md "init kararları" bölümü mevcut
- [ ] features.json en az 3 sıralı feature içeriyor
- [ ] Tüm değişiklikler tek "init: bootstrap complete" commit'inde
- [ ] CI yeşilMinimal Makefile iskeleti
Düzeneğin geri kalanı bu dört hedef üzerine kurulur.
.PHONY: setup dev test check
setup:
uv sync
pre-commit install
dev:
uv run python -m app
test:
uv run pytest -q
check:
uv run ruff check .
uv run mypy .
uv run pytest -qmake check CI'da çağrılacak tek komuttur. Bu kural ileride ders 09'daki "kalite kapısı"nın temelini atar.
Sayılarla
Sıcak başlangıç (hot-start) ile soğuk başlangıç (cold-start)
İyi bir init, sonraki soğuk başlangıçları ucuzlatır. Yeni bir oturum açıldığında ajan iki şeyden birini yaşar:
- Cold-start (init'siz): oturumun ilk 10–20 dakikası "burada ne var, nasıl çalıştırılır, testler nerede?" sorularına gider. Bağlam penceresinin kayda değer bir kısmı keşif maliyetine yanar.
- Hot-start (init'li): oturum
make setup && cat PROGRESS.md && cat features.jsonile dakikalar içinde bağlam kurar. Bağlam penceresi feature işine ayrılır.
Anthropic'in çoklu-ajan ölçümleri
Anthropic'in How we built our multi-agent research system yazısında belgelenen ölçüm: rolleri ayrılmış çoklu-ajan kurulumu (lead Opus 4 + subagent Sonnet 4) tek-ajanlı Claude Opus 4'ü iç değerlendirmede yüzde 90,2 oranında1 geride bıraktı. Aynı yazı çoklu-ajan kurulumlarının sohbete kıyasla yaklaşık 15 kat1 daha fazla token tükettiğini de söyler.
Bu iki sayı birlikte okunduğunda init'in maliyeti şöyle dengelenir: init'i ayrı bir ajana ya da ayrı bir oturuma vermek pahalıdır, ama feature ajanı bu yatırımı bir sonraki üç-dört oturum içinde geri kazanır çünkü hot-start her oturumda keşif maliyetini sıfıra yakın indirir.
Initializer ajan kavramı
Anthropic vokabülerinde initializer agent, ilk bağlam penceresini tüketen, dar kapsamlı, özel promptlu bir alt ajandır. Görevi yalnızca bootstrap: init.sh üretmek, claude-progress.txt'yi başlatmak, ilk git commit'ini atmak ve feature listesini JSON olarak teslim etmek. Feature yazan ajandan bilinçli olarak ayrı tutulur, çünkü iki ajanın optimizasyon hedefleri farklıdır.
Tek ajanlı bir ortamda çalışıyorsan aynı disiplin oturum sınırlarıyla uygulanabilir: ilk oturum yalnız init yapar, başka iş yapmaz, kapanışında init: bootstrap complete commit'i bırakır, ikinci oturum yalnızca o noktadan feature'a başlar.
Pratik kontrol listesi
- İlk oturumun tek amacı init, feature kodu yok.
- Bootstrap Sözleşmesi'nin dört koşulu sağlandı.
- Beş teslim çıktısının (ortam / test / doküman / feature listesi / commit) hepsi yerinde.
- Init kabul kontrol listesinde tek bir kutu boş değil.
- AGENTS.md dosyası dev / test / PR bölümlerini içeriyor.
- Tek "init: bootstrap complete" commit'i atıldı.
- features.json en az üç sıralı kalem içeriyor.
- CI yeşil,
make checklokalde de yeşil.
Müfredat içindeki yeri
Ders 05 süreklilik artefaktlarını tanıtmıştı. Bu ders onlara bir başlangıç anı verdi. Bootstrap Sözleşmesi'nin dört koşulu sağlanmadan feature ajanı sahaya çıkmaz. Init "ilk oturum" değil, ayrı bir mühendislik fazıdır. Bu fazın çıktısı bir feature listesidir. O liste de Ders 07: WIP=1 Disiplini'nin başlangıç noktasıdır: aşırıya kaçma ve yarım bırakma simbiyozu, listenin nasıl tüketileceğiyle çözülür.
Pratik karşılığı: Proje 03: Vardiya Süreklilik. Init + devam desenini gerçek bir repoda kurarsınız. Bu dersteki dört koşul ve beş teslim, projenin kabul kapısıdır.