Yapay zeka ajanlarının gözlemlenebilirliği: ajanın ne yaptığını nasıl anlarsınız ve neyi loglamalısınız

Yapay zeka ajanı gözlemlenebilirliği nedir

Yapay zeka ajanlarında gözlemlenebilirlik, ajanın sözlerine ya da hafızasına değil artefaktlara bakarak üç soruyu yanıtlayabilmektir: ne yaptı, neden tam olarak öyle yaptı ve sonucun doğru olduğu neyle kanıtlanıyor. Yirmi dakikalık çalışmanın ardından ajan "tamam, ama iki test düşüyor, belki zamanlama yüzündendir" diyorsa ve "hangi yollara dokundun" sorusuna "kodu görmem lazım" diye cevap veriyorsa, gözlemlenebilirlik yoktur. Ajan aptal değildir; sadece gösterecek bir şeyi yoktur.

Sorun sistematiktir. Aynı ajan bir hafta içinde on kez dürüstçe "tamam" diyebilir ve her seferinde bu ifade farklı bir şey demek olabilir: bir yerde tüm testler çalıştırılmıştır, bir yerde yalnızca biri, bir yerde hiçbiri. Proje ne kadar yaşlanırsa, her yeni oturum o kadar pahalı olur, çünkü her oturum kazı ile başlar.

İki katman: çalışma zamanı ve süreç

Gözlemlenebilirlik çoğu zaman loglarla karıştırılır, ama loglar yarısıdır.

Yalnızca çalışma zamanı: neyin çöktüğü görünür, ama neyin hedeflendiği belli olmaz. Yalnızca süreç: neyin istendiği bellidir, ama neden başarısız olunduğu görünmez. İkisi de gerekir.

Ajan bunu kendi kendine neden yapmaz

Ajana "daha iyi logla" demek üç nedenle işe yaramaz.

• Neyi bilmediğini bilmez. Ajan, önemini kestiremediği bir sinyali loglamaz.
• Format kayar. Bir oturumda ayrıntılı, diğerinde tek satır yazar. Oturumları karşılaştırmak ve toplam almak imkânsız olur.
• Süreç loglarla kapanmaz. "Neden böyle yapıldı" sorusunun cevabı, komut çıktılarında değil, iş başlamadan önce yazılmış belgelerde yaşar.

Bu yüzden gözlemlenebilirlik harness'e, yani ajanın çevresine yerleştirilir: şablonlar, hook'lar, betikler, zorunlu rapor formatı.

Ne loglanmalı: asgari küme

İyi bir günlük, her şeyin dökümü değil, çalışmanın akışını yeniden kurmaya ve istatistik çıkarmaya yetecek gerçeklerin kümesidir.

• Tanımlayıcılar: oturum kimliği, görev ya da özellik kimliği, ajan modeli.
• Yan etkisi olan eylemler: hangi komutlar çalıştırıldı, hangi dosyalar değişti. Dosya okumaları genelde yazılmaz.
• Kontrol sonuçları: hangi doğrulama komutu, çıkış kodu, kaç test geçti ve kaç test düştü.
• Yeniden denemeler: bir adım için kaç deneme yapıldı ve denemeler neyde farklıydı.
• Harcama: araç bunları veriyorsa token ve süre.
• Sonuç: görev kabul edildi, reddedildi ya da terk edildi, ve neden.

Neyin yazılmaması gerektiği: sırlar, erişim token'ları, komut çıktısındaki kişisel veriler. Günlük paylaşılabilir ya da yeniden model bağlamına girebilir.

Claude Code hook'larıyla eylem günlüğü

Claude Code'da günlüğü hook'larla tutmak uygundur: bunlar aracın kendisi tarafından çalıştırılır, model tarafından değil, bu yüzden her zaman tetiklenirler. Hook, olayın açıklamasını içeren bir JSON alır: oturum kimliği, araç adı ve parametreleri. Aşağıda, her Bash, Edit ya da Write çağrısından sonra günlüğe bir satır ekleyen bir .claude/settings.json yapılandırması ve betik var:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — eylem başına bir JSON satırı
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

JSONL biçimi (her satırda bir JSON kaydı) jq ile kolay filtrelenir ve herhangi bir analiz sistemine yüklenebilir. Ayrıca Claude Code oturumların tam geçmişini yerel olarak ~/.claude/projects/ dizininde saklar; akıl yürütmeyi ve çıktının tamamını görmek istediğinizde buradan bakabilirsiniz, ama istatistik için kendi kompakt günlüğünüz daha uygundur.

İzleme: oturum başına iz, görev başına span

Ajan sayısı arttığında ya da zamanlanmış çalıştığında metin günlükleri yetmez: toplulaştırılmış veri gerekir. Burada dağıtık izleme araçları ve OpenTelemetry standardı işe yarar.

• İz (trace) — tek bir ajan oturumu.
• Span — oturum içindeki tek bir görev.
• İç içe span'lar — doğrulama adımları: derleme, testler, e2e.

Her span için asgari öznitelikler: özellik ve oturum kimliği, model, kontrol sonucu, token sayısı, yeniden deneme sayısı. Bu veriler Jaeger, Grafana Tempo, Honeycomb gibi araçlarda okunur ve tek bir oturumda görünmeyen sorulara cevap verir: hangi görev türü daha çok yeniden deneme gerektiriyor, ajan token'ı nerede en çok harcıyor, harness'te hangi değişiklikten sonra kabul edilen görevlerin oranı düştü. Claude Code'un ortam değişkenleriyle açılan, OpenTelemetry üzerinden metrik ve olay dışa aktarma özelliği de vardır; ayrıntılar aracın belgelerinde.

Commit'ler günlük olarak

En ucuz ve en güvenilir günlük zaten elinizde: git. Tek yapmanız gereken, onu okunabilir kılmak.

1. Bir commit — bir görev. Böylece git log yapılanların listesiyle örtüşür ve bir görevi geri almak tek bir git revert olur.
2. Mesajda — ne yapıldığı ve nasıl doğrulandığı. "fix" değil: neyin değiştiği, neden ve hangi komutla doğrulandığı.
3. Commit yalnızca yeşil kontrolden sonra. Böylece geçmişteki her nokta çalışan bir durumdur ve git bisect suçluyu bulur.

fix(payments): indirimin kuruşa yuvarlanması

İndirim float üzerinde hesaplanıyordu, 999.99 tutarında bir kuruş kayboluyordu.
Hesap, kuruş cinsinden int'e çevrildi.
Doğrulandı: make test (142 passed), make e2e checkout — tamam.
Kapsam dışı: raporlardaki yuvarlama, BACKLOG.md'ye yazıldı.

Ajan raporu: izlenim yerine kanıt

Ajanın son mesajı da sabit bir biçimi varsa gözlemlenebilirlik artefaktıdır. Şablonu AGENTS.md ya da CLAUDE.md içinde tanımlayın:

## Görev sonunda rapor
- Ne yapıldı: değişikliklerin listesi (dosya — özü)
- Nasıl doğrulandı: tam komutlar ve sonuçları
- Ne doğrulanmadı ve neden
- Görev sözleşmesinden sapmalar
- İnsana açık sorular

Ana kural: her iddia bir kanıta bağlanır — dosya ve satır, test çıktısı, günlük kaydı. "Normal görünüyor" ve "bence tamam" rapor sayılmaz. "Doğrulanmayanlar" maddesi özellikle değerlidir: güvenin sınırlarını dürüstçe gösterir.

Kapsam sözleşmesi işe başlamadan, rubrik sonra

Süreç katmanı işten önce başlar. Kısa bir görev sözleşmesi (sprint contract) kapsamı, kabul kriterlerini, "kapsam dışı" bölümünü ve insanın karar vereceği açık soruları sabitler. "Kapsam dışı" bölümü, sonuç hakkındaki anlaşmazlıkların yarısını önler.

İş bittikten sonra sonuç izlenime göre değil rubrikle değerlendirilir. Aksi halde iki deneyimli inceleyici birbirinden farklı kararlar verir ve değerlendirme piyangoya döner.

Her boyut A/B/C/D ile değerlendirilir ve kanıtı olmayan not geçersizdir. Basit karar kuralı: bir D ya da iki C — düzeltilmesi gerekenlerin listesiyle reddet. Aynı rubriği ayrı bir doğrulayıcı ajan da uygulayabilir.

Bir oturumda ajanın ne yaptığı nasıl çözümlenir

Rapor yoksa ya da ona güvenilmiyorsa, artefaktları şu sırayla gözden geçirin.

1. Çalışma ağacının durumu: git status — commit edilmemiş ne var, çöp dosya var mı.
2. Geçmiş: oturumun başından itibaren git log --stat — hangi commit'ler ve dosyalar.
3. Değişikliklerin ölçeği: git diff --stat main...HEAD, ardından önemli dosyaların tam diff'i.
4. Eylem günlüğü: hangi komutlar çalıştırıldı ve kontroller ne döndürdü.
5. Yeniden doğrulama: derlemeyi ve testleri kendiniz çalıştırın. Komut çıktısına güvenin, anlatıma değil.

# ajanın son oturumda çalıştırdığı komutlar
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# en sık düzenlenen dosyalar
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

Sık yapılan hatalar

• Her şeyi loglamak. Gigabaytlarca döküm kimse tarafından okunmaz. Yan etkisi olan eylemleri ve kontrol sonuçlarını yazın.
• Serbest biçim. Günlük formatını ajan belirlerse toplulaştırma olmaz. Formatı harness belirler.
• Komut çıktısı olmadan rapora inanmak. Çıktısız "testler yeşil" bir görüştür.
• Körü körüne yeniden deneme. Arızanın nedenini bilmeden ajan rastgele yerleri düzeltir. Önce log'a bağlı bir teşhis, sonra düzeltme isteyin.
• "Sonra temizleriz." Hata ayıklama dosyaları ve commit edilmemiş değişiklikler sonraki oturumu yanıltır: geçici ile bilerek yapılanı ayıramaz.

Sonuç

Yapay zeka ajanlarının gözlemlenebilirliği iki katmandan kurulur: çalışma zamanı (hook'larla eylem günlüğü, izler, doğrulama mesajlı commit'ler) ve süreç (işten önce görev sözleşmesi, rubrik ve kanıt bağlantılı rapor). O zaman "tamam" her oturumda aynı şeyi ifade eder ve bir ajanın işini çözümlemek dakikalar sürer. Bu konu, gerçek bir ödeme backend'i projesi üzerinde, harness engineering kursunda uygulamalı olarak ele alınır.