Yapay zeka ajanının oturumlar arası hafızası: ilerleme dosyası, karar günlüğü, git ve init betiği

Ajan neden hiçbir şeyi hatırlamaz

Model, çalıştırmalar arasında durum tutmaz. Ajanın görevinizle ilgili «bildiği» her şey mevcut oturumun bağlam penceresinde durur: okunan dosyalar, komut çıktıları, sizinle olan diyalog. Oturum kapanır ya da bağlam taşarsa yeni oturum sıfırdan başlar ve yalnızca diske yazılmış olanı görür.

Faydalı bir benzetme: her sabah hafızası silinmiş olarak işe gelen deneyimli bir mühendis. Kodu hızla kavrar, ama dün hangi mimari seçeneğin seçildiğini, diğerlerinin neden reddedildiğini ve testlerin hangi durumda olduğunu hatırlamaz. Kayıt yoksa on beş yirmi dakikasını keşfe harcar ve büyük olasılıkla bilerek reddettiğiniz şeyi yeniden yapar.

Bu yüzden yapay zeka ajanı hafızası modelin bir özelliği değil, harness'in bir parçasıdır: sizin tasarladığınız dosyalar ve kurallar. İyi haber, bunun için vektör veritabanlarına ve özel servislere ihtiyaç olmamasıdır. Birkaç Markdown dosyası, git ve disiplin yeter.

Büyük bağlam penceresi neden sorunu çözmez

Daha büyük pencereli bir modelin çıkmasını beklemek cazip gelebilir. Ama karmaşık bir görev her pencereyi doldurur: ajan kod tabanını okur, karar geçmişi biriktirir, testlerden gelen uzun çıktıyı işler ve tüm diyaloğu tutar. İhtiyaçlar pencereyle birlikte büyür. Bu bir hacim sorunu değil, mimari bir sorundur.

İkinci bir etki de vardır. Pencerenin sınırına yaklaşınca birçok model işi bitirmeye acele etmeye başlar: doğrulamayı atlar, doğru çözüm yerine basit çözümü seçer. Anthropic bu gözlemi kendi modelleri için anlatır, ama etkinin büyüklüğü modelden modele değişir. Sınırdaki uzun bir oturum yalnızca bilgi kaybetme riski değil, işin kalitesinin düşme riskidir.

Bağlam sıkıştırma: neyi korur, neyi kaybeder

Sıkıştırma (compaction), aynı oturumda yer açmak için diyaloğun erken kısmının kısa bir özete çevrilmesidir. Claude Code'da bunu /compact komutu yapar ve sınıra yaklaşıldığında otomatik olarak da gerçekleşir. /clear ise tersine geçmişi temizler ve konuşmayı baştan başlatır.

Sıkıştırmanın sorunu, özetin genellikle «ne»yi korumasıdır ama «neden»i kaybetmesidir. Hazır kod dosyalarda kalır, ama gerekçeler — neden B seçeneği seçildi, neden bir kütüphane alınmadı, neden bir optimizasyon bilerek atlandı — birkaç kelimeye sıkışır ya da tamamen kaybolur. Ajanın bir sonraki adımı bilinçli bir kararı, artık nedenini görmediği için «iyileştirir».

Karmaşık metrikler olmadan pratik bir kural: görev bağlam penceresinin yaklaşık %60'ını doldurduğunda kod yazmayı bırakın ve devir hazırlığı yapın. Bağlam yalnızca %40 doluysa ve görevin sonu yakınsa, sıkıştırma yeterlidir.

Ajan hafızasını oluşturan dört yapı

Modelin hafızasına güvenmek yerine bir bordo günlüğü tutun. Dört parçası vardır ve her birinin rolü farklıdır.

1. PROGRESS.md — şu an neredeyiz.
2. DECISIONS.md — neden böyle, başka türlü değil.
3. Git commit'leri — durumun ücretsiz kontrol noktaları.
4. AGENTS.md içindeki vardiya protokolü — gelirken ve giderken ne yapılacağı.

PROGRESS.md: ilerleme dosyası

Tek bir soruya cevap verir: proje şu anda hangi durumda. Ajan oturumun başında onu ilk okur, ayrılmadan önce en son günceller. Dosya kısa olmalıdır; sürekli eklenmek yerine yeniden yazılır, çünkü geçmiş git'te yaşar.

# PROGRESS.md

## Mevcut hedef
Ürün kataloğunda arama (özellik search-01)

## Durum
- HEAD: 4f2a9c1
- make check: yeşil, 142/142 test
- Yapılan: PostgreSQL'de indeks (tsvector), GET /search uç noktası
- Doğrulandı: birim testleri + 3 sorguyla elle curl

## Engeller
- Kazakça için morfoloji verisi yok — karar bekleniyor

## Sonraki adım
GET /search'e sayfalama ekle, kriter: 2. sayfa için test

Devir için yeterli olan dört alana dikkat edin: commit hash'i, geçen testlerin oranı, engeller ve sonraki adım. Yeni bir oturum bu dosyaya bakarak işi tereddütsüz sürdüremiyorsa, şablonda bir alan eksiktir.

DECISIONS.md: karar günlüğü

Sıkıştırmada kaybolan «neden»i tutar. Kayıt biçimi: karar, gerekçe, reddedilenler ve nedenleri, kısıtlar.

## 2026-03-14 — Kullanıcı ayarları için Redis önbelleği
- Karar: Redis, TTL 5 dakika, yazmada aktif geçersiz kılma.
- Gerekçe: her istekte okunuyor, veri hacmi çok küçük.
- Reddedildi: PostgreSQL materialized view — değişiklikler çok sık,
  bakımı getirisini karşılamıyor.
- Kısıt: ödeme ayarları önbelleğe alınmaz.

Buradaki en değerli satır «Reddedildi»dir. Bu satır, sonraki oturumun daha önce ele alınıp atılmış bir seçeneğe geri dönerek kararı «optimize etmesini» engeller. Karar günlüğü, ilerleme dosyasının aksine yalnızca büyür: eski kayıtlar silinmez, yenileriyle değiştirildiği işaretlenir.

Git geçmişi kontrol noktası olarak

Commit'ler, işin doğal bir parçası olan sürümlenmiş durum anlık görüntüleridir. Ajan git log ve git diff ile neyin değiştiğini okuyup yeniden kurabilir. Geçmişin hafıza gibi işlemesi için commit mesajı diff'i yeniden anlatmak yerine niyeti açıklamalıdır.

# kötü
git commit -m "update search.py"

# iyi
git commit -m "search: LIKE yerine tsvector indeksi

LIKE '%q%' indeksi kullanmıyor, 200 bin üründe sorgu 1.8 sn sürüyor.
Sayfalama henüz yok, bkz. PROGRESS.md."

Her yeşil test çalıştırmasından sonra yapılan küçük ve sık commit'ler ayrıca bir geri dönüş noktası sağlar. Oturum yanlış yola sapmışsa, yarım kalmış düzeltmeleri ayıklamak yerine son doğrulanmış duruma dönmek daha kolaydır.

AGENTS.md içinde vardiya protokolü

Durum dosyaları ajan onları bilmediği sürece işe yaramaz. Bu yüzden giriş talimat dosyasına (AGENTS.md veya CLAUDE.md) kısa bir protokol yazılır: gelirken ve giderken ne yapılacağı.

## Vardiyaya geliş
1. PROGRESS.md ve DECISIONS.md dosyalarını oku.
2. .agent/feature_list.json içinde aktif görevi bul.
3. make check çalıştır — repo tutarlı mı doğrula.
4. «Sonraki adım»dan devam et, çözülmüş bir konuyu yeniden açma.

## Vardiyadan çıkış
1. make check çalıştır, yeşil durumu commit et.
2. PROGRESS.md dosyasını güncelle: HEAD, testler, engeller, sonraki adım.
3. Yeni kararları DECISIONS.md dosyasına ekle.
4. Çalışma ağacında yarım iş bırakma.

Protokolü kısa tutun: giriş dosyasında birkaç satır olmalı, ayrı bir uzun metin olmamalı.

Init betiği: oturum başlangıcını hızlandırmak

Ajanın resmi elle toplamasını önlemek için ortamı kontrol edip durumu yazdıran tek bir betik verin. Betik idempotent olmalıdır — istenildiği kadar çalıştırılabilmeli — ve açık bir hazır olma mesajıyla bitmelidir.

#!/usr/bin/env bash
set -euo pipefail

echo "== 1. Ortam =="
command -v uv >/dev/null || { echo "FAIL: uv kurulu değil"; exit 1; }
uv sync --frozen

echo "== 2. Depo =="
if [ -n "$(git status --porcelain)" ]; then
  echo "WARN: çalışma ağacı kirli"
else
  echo "OK: temiz"
fi
echo "HEAD: $(git log -1 --oneline)"

echo "== 3. Kontrol =="
make check

echo "== 4. Durum =="
cat PROGRESS.md

echo "Çalışmaya hazır"

Geliş protokolünde o zaman tek satır yeter: «scripts/init.sh çalıştır». Claude Code'da bu çalıştırma, oturum başlangıcındaki SessionStart olayına bağlı bir hook ile otomatikleştirilebilir; hook olmasa bile ajan, dosyadaki talimata göre betiği çalıştırır.

Ajanın hafızasına ne konur, ne konmaz

Asıl hata, hafızayı çöplüğe çevirmektir. Ajanın başlangıçta okuduğu her satır bağlamda yer kaplar ve gereksiz şeyler önemli olanı boğar.

Yaşam süresine göre de ayırın. Proje kuralları nadir değişir ve tüm görevleri ilgilendirir — yeri giriş talimat dosyasıdır. Durum her oturumda değişir — yeri ilerleme dosyasıdır. İkisi karışırsa giriş dosyası kısa sürede eski notlarla şişer.

İlk oturum: başlatma ayrı bir aşama olarak

İlk oturum kaosa dönerse, oturumlar arası hafıza bunu kurtaramaz. Tipik durum şöyle: temiz bir depoda «arama ekle» dersiniz, yarım saat sonra test çatısının yanlış kurulduğu ve migration formatının uymadığı ortaya çıkar. Arama eklenmiştir, ama temel çatlaktır.

Nedeni, uygulama ve başlatmanın farklı şeyleri optimize etmesidir: birincisi bu oturumda biten özellik sayısını, ikincisi sonraki tüm oturumların hızını ve güvenilirliğini. Ajan görünür sonuca, yani kodaya, doğru eğilim gösterir. Bu yüzden başlatmayı dört koşullu net bir kabul kriteriyle ayrı bir oturuma almak gerekir.

• Çalışabilmeli: temiz bir klondan make setup ve make dev çalışır.
• Kendini doğrulayabilmeli: make test vardır ve en az bir gerçek, geçen test içerir.
• İlerlemeyi görebilmeli: durum dosyası vardır ve okunabilir.
• İşi devralabilmeli: kabul kriterli bir görev listesi vardır.

Sık sık yeni proje başlatıyorsanız bir depo şablonu hazırlayın: Makefile, test çatısı, AGENTS.md iskeleti, .agent/ klasörü, scripts/init.sh, linter ve CI. O zaman başlatma yalnızca projeye özgü kısma iner.

Hafızanın çalıştığını nasıl kanıtlarsınız

En dürüst metrik, yeni bir oturumun başlangıcından ilk anlamlı kod değişikliğine kadar geçen süredir. Artefakt yoksa bu genellikle on beş yirmi dakikalık keşiftir; iyi bir devirle iki üç dakikaya iner. Bir kez önce ve sonra ölçün; disiplinin karşılığını verip vermediği netleşir.

İkinci yol, soğuk başlangıç testidir. Yeni bir oturum açın, «devam et» yazın ve beş soru sorun: mevcut hedef nedir, testler hangi durumda, ana konuda hangi karar alındı ve neden, neyin engellediği, sonraki adım nedir. Ajan beşine de dosyalardan, tahmin etmeden cevap veriyorsa hafıza doğru kurulmuştur. Her emin olmayan cevap, şablondaki eksik bir alandır.

Sık yapılan hatalar

• İlerleme dosyası yalnızca büyür. Bir ay sonra yüzlerce satır geçmiş birikir. Dosyayı mevcut duruma göre yeniden yazın; geçmiş git'te yaşar.
• «Reddedildi» satırı yok. Reddedilen seçenekler yazılmayan bir karar günlüğü, tekrarlayan tartışmalara karşı koruma sağlamaz.
• Ajan durumu «gözle» günceller. Nasıl doğrulandığını yazdırın: komut ve sonuç, «her şey çalışıyor» değil.
• Bağlam sınırında devir. Sınıra yakın ajan zaten acele eder; devri erken, yaklaşık %60'ta başlatın.
• Çıkışta kirli çalışma ağacı. Commit edilmemiş yarım düzeltmeler bir sonraki oturumu şaşırtır.

Özet

Oturumlar arası yapay zeka ajanı hafızası modele değil dosyalara dayanır: PROGRESS.md mevcut durumu tutar, DECISIONS.md nedenleri ve reddedilen seçenekleri, git commit'leri gerekçeli kontrol noktalarını, AGENTS.md'deki vardiya protokolü ise bunların okunup güncellenmesini sağlar. Init betiği başlangıcı tek komuta indirir; soğuk başlangıç testi kayıtların yeterli olup olmadığını gösterir. Ajanın bordo günlüğü ve bootstrap sözleşmesi kursta harness mühendisliği üzerinden uygulamalı olarak işlenir.