11DerslerDers 11 / 12
Düzeneğin Gözleri
Gözlemlenebilirlik, Düzenek Mühendisliği (Harness Engineering) için sonradan eklenen bir özellik değil: runtime ve süreç olmak üzere iki paralel katmanda birlikte tasarlanan mimari bir özelliktir.
- Okuma
- 5 dakika
- Yayın
- 19 Mayıs 2026
Saat 23:47, oturum sonu
Ajan son raporunu yazar:
Görev tamamlandı. İki entegrasyon testi başarısız. Hata mesajları gevşek; sebebi kestiremedim. Yarın bakılabilir.
Ertesi sabah yeni oturum açılır. "Dün ne oldu?" sorusunun kanıt tabanlı cevabı yok. Hangi modül hangi girdiyle çağrıldı, hangi araç çağrısı kaç saniye sürdü, hangi varsayım yanlış çıktı: kayıp. İlk iki saat dünü yeniden keşfetmeye gider. Anthropic'in saha gözlemleri bu "yeniden keşif" kaybının oturum süresinin önemli bir kısmını yiyebildiğini gösteriyor. Örnek bir senaryoda kayıp yüzde otuz ila elliörnek aralığında seyreder.
Sebep tek: düzenek (harness) gözlemlenebilirlik olmadan kurulmuş. Hata gerçekleşti, iz bırakmadı.
Tez
Gözlemlenebilirlik, Düzenek Mühendisliği (Harness Engineering) için sonradan bağlanan bir eklenti değildir. Düzeneğin iki paralel katmanı olarak (runtime ve süreç) başlangıçtan itibaren birlikte tasarlanır. Bu katmanlar yoksa ajan kararları belirsizlikte alır, değerlendirme öznelleşir, tekrarlar kör atışa döner, oturum geçişleri bilgi uçurumuna dönüşür.
İki paralel katman: şema
Runtime "ne oldu"yu, süreç "neden bu yapıldı"yı taşır: ikisi birden karar üretir.
ne oldu
tracespanlogeventerror context
neden bu yapıldı
- sprint sözleşmesi
- evaluator rubriği
- karar günlüğü
- kabul kriterleri
iki katmanın
kanıt buluşması
kanıtlı karar
varyans düşer
- trace: session-2026-05-19
- └─ span: F03 cart/items
- ├─ span: lint[pass]
- ├─ span: unit_test[pass]
- └─ span: e2e[fail → retry → pass]
Dört semptom
Gözlemlenebilirliği eksik bir düzenekte dört belirti tekrarlar:
- Doğru ile "doğru görünüyor" ayırt edilemez. Test yeşil yandı, ama hangi davranış için? Hangi girdiyle? Belirsiz.
- Değerlendirme mistikleşir. Aynı çıktıya farklı değerlendiriciler farklı not verir. Rubrik yoksa kişisel zevk konuşur.
- Tekrarlar kör atışa döner. Başarısız olunca sistematik kök sebep yerine "başka bir şey deneyelim" döngüsüne girilir.
- Bilgi uçurumu. Oturum kapanır, "neden bu yolu seçtik" sorusu sonraki oturum için bir taş yığını olur.
Dördü de aynı mimari boşluktan doğar: düzeneğin gözleri yok.
İki paralel katman
Runtime gözlemlenebilirliği: "ne oldu"
Otomatik toplanan veri. Loglar, trace'ler, yaşam döngüsü olayları, kaynak desenleri, tam hata bağlamı. Bu katman beş veri ailesini kapsamalı:
- Yaşam döngüsü fazları: startup, ready, running, shutdown.
- Feature path girişleri, kontrol noktaları, çıkışları.
- Bileşenler arası veri akışı: A modülü B'ye ne gönderdi.
- Kaynak desenleri: bellek büyümesi, açık dosya sayısı, CPU eğrisi.
- Tam hata bağlamı: stack trace, env, input snapshot, output snapshot.
Süreç gözlemlenebilirliği: "neden bu yapıldı"
Manuel ya da yarı-otomatik üretilen veri. Sprint sözleşmesi, evaluator rubriği, kabul kriterleri, karar gerekçeleri. Runtime izleri kuru veridir. Gerekçe süreç katmanında durur.
İki katman birlikte: runtime "ne oldu"yu, süreç "neden bu yolu seçtim"i açıklar. Biri olmadan diğeri yarımdır. Düzenek Mühendisliği (Harness Engineering) ikisini aynı diyagrama çizer.
Üç enstrüman
Düzenek Mühendisliği (Harness Engineering) bu iki katmanı üç somut enstrümanla hayata geçirir.
Enstrüman 1: Sprint sözleşmesi
Kod yazımı başlamadan generator ile evaluator arasında müzakere edilen kısa anlaşma. Ön-tasarım kontratı: generator'ın ürettiğini evaluator'ın hemen reddetmesini önler.
Enstrüman 2: Evaluator rubriği
Değerlendirmeyi öznel yargıdan kanıt tabanlı puanlamaya çevirir. A/B/C/D dört sütun, her sütun ölçülebilir bir bant.
Enstrüman 3: Standardize trace
Her oturum için tek bir trace, her görev için bir span, her doğrulama adımı için alt span. Tercih edilen standart: OpenTelemetry GenAI Semantic Conventions. Span, metric, event, attribute ve exception ailelerini bir arada tarifler. Anthropic, OpenAI, AWS Bedrock, Azure AI Inference için teknolojiye özel uzantılar sunar. Spesifikasyon hâlâ "Development" statüsünde. Geçiş için OTEL_SEMCONV_STABILITY_OPT_IN opt-in mekanizması mevcut. Bu üç enstrüman olmadan düzeneğin gözleri kapalıdır.
Pratik
Sprint sözleşmesi şablonu
# Sprint Contract: Dark Mode Desteği
## Kapsam
- Theme toggle bileşeni
- Global CSS değişkenleri güncellemesi
- Dark mode regresyon testleri
## Doğrulama standartları
- Her bileşen için görsel regresyon testi geçer
- Ana akış e2e testleri geçer
- FOUC (Flash Of Unstyled Content) yok
## Dışında bırakılanlar
- Print stil desteği yok
- Üçüncü parti bileşen dark mode'u yokÜç başlık: kapsam, doğrulama standartları, dışlananlar. Daha fazlası sözleşmeyi değil tasarımı şişirir.
Evaluator rubriği
| Boyut | A | B | C | D |
|---|---|---|---|---|
| Kod doğruluğu | Tüm testler geçer | Yüzde doksan beş üstü geçer | Yüzde seksen ila doksan beş bandı | Yüzde seksenin altı |
| Mimari uyum | Sınır ihlali yok | Bir küçük ihlal | İki ila üç ihlal | Üçten fazla ihlal |
| Test kapsamı | E2E ve birim | E2E var | Sadece birim | Test yok |
| Doküman | Güncel | Çoğunlukla güncel | Eksik | Yok |
Aynı çıktı, farklı değerlendiriciler: benzer puanlar. Değerlendirme varyansı düşer, mistisizm tükenir.
OTel span ve trace yapısı
trace: session-2026-05-18-001
span: feature F03 cart/items
span: code_write
span: lint [pass]
span: unit_test [pass]
span: integration [pass]
span: e2e [fail, retry sonrası pass]Bir oturumun tüm akışı tek bir DAG. Hata noktası tek tıklamayla bulunur. OpenTelemetry GenAI semconv altında her span standart attribute kümesi taşır. Bu sayede AgentOps, Inspect AI gibi araçlar arasında trace'ler portatif kalır.
Hangi aracı seçmeli
- OpenTelemetry GenAI semconv (yeni sekmede açılır): Portatif span, metric, event, attribute standardı. Tüm zinciri OTel uyumlu tutarsanız tek satır bağımlılık değişikliği ile araç değiştirebilirsiniz.
- Inspect AI (yeni sekmede açılır): UK AISI ve Meridian Labs üretimi açık çerçeve. Solver, scorer, dataset, sandboxing, MCP entegrasyonu ve web tabanlı Inspect View log-viewer'ı bir arada sunar.
- AgentOps (yeni sekmede açılır): Python SDK. Session replay, LLM maliyet takibi, otomatik trace yakalama. CrewAI, AG2, OpenAI Agents SDK, LangChain, Anthropic entegrasyonları hazır.
- OpenAI Trace Grading (yeni sekmede açılır): Uzun çok adımlı görevlerde sadece nihai çıktıyı değil, ajan trace'inin tamamını doğrudan puanlamak için resmi kılavuz.
Sıfırdan yazmanız gereken çok az şey kaldı. Standartları benimseyin. Özel olan tek şey rubriğiniz ve sözleşmeniz.
Sayılarla
Anthropic'in "Quantifying infrastructure noise in agentic coding evals" çalışması, çalışma zamanı yapılandırma farklarının çoğu kişinin sandığından çok daha gürültülü olduğunu sayılarla gösterir. Terminal-Bench iki nokta sıfır üzerinde en katı ve en gevşek kaynak tahsisi arasındaki fark altı puan1 ölçülmüş, istatistiksel anlamlılık p küçüktür sıfır nokta sıfır bir. Strict yapılandırmadan uncapped yapılandırmaya geçince altyapı hata oranı yüzde beş nokta sekizden yüzde sıfır nokta beşe1 düşmüş. Yazarların önerisi açık: lider tablosunda üç puanın altındaki farklara1 altyapı yapılandırması belgelenmeden güvenmeyin.
Düzenek seviyesinde tercüme: trace toplamadan ne regresyon tespiti, ne performans karşılaştırması, ne model seçimi güvenilirdir. Gözlemlenebilirlik, model karşılaştırmasının bile ön koşuludur.
Dark mode vaka karşılaştırması (aynı feature, iki kuruluş):
| Kuruluş | İterasyon | Süre | Kalite |
|---|---|---|---|
| Gözlemlenebilirlik yok | Üç ila dört kör deneme | Kırk beş dakika | "Tam iyi değil" |
| Tam gözlemlenebilirlik | Tek iterasyon | On beş dakika | Yüksek |
Üç kat verimlilikörnek. Tek değişen: sprint sözleşmesi, evaluator rubriği, standardize trace.
Pratik kontrol listesi
- Tek trace ID. Her oturum başında tek bir trace ID üretilir. Tüm spanlar bu trace altına bağlanır.
- Span hiyerarşisi. Her feature için bir span, her doğrulama adımı için alt span. Hata noktası ağaç içinde tek tıklamayla bulunur.
- OTel uyumu. Trace'ler OpenTelemetry GenAI semantic conventions uyumlu, attribute isimleri standart.
- Sprint sözleşmesi. Kapsam, doğrulama standartları, dışlananlar: üç başlık yazılı.
- Rubrik tablosu. Evaluator rubriği A, B, C, D bantlarıyla görev başlamadan hazır.
- Tam hata bağlamı. Hata trace'inde input snapshot, output snapshot, stack trace, env birlikte yer alır.
- Oturumlar arası erişim. Trace verisi sonraki oturumdan okunabilir, "dün ne oldu" sorusu kanıt tabanlı cevaplanır.
Müfredat içindeki yeri
Ders 10 "geçti mi" sorusunu uçtan uca cevaplamıştı. Bu ders "neden geçti, neden geçmedi" sorusunu açtı. Sprint sözleşmesi, evaluator rubriği ve OTel uyumlu trace: üç enstrüman, runtime ile süreç katmanlarını aynı diyagramda buluşturur. Ders 12: Temiz Teslim müfredatın son halkasıdır: bu kadar zahmetle kurulmuş düzeneğin oturum sonunda nasıl yeniden devredilebilir bırakılacağı.
Pratik karşılığı: Proje 06 (Capstone: Bütünleşik Düzenek). Gözlemlenebilirlik birinci sınıf bileşen olarak (sözleşme, rubrik ve OTel uyumlu trace ile) inşa edilir.