> ## Documentation Index
> Fetch the complete documentation index at: https://harness.lokomotif.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 12 — Temiz Teslim

> Entropi varsayılan. Düzenek Mühendisliği (Harness Engineering) uzun vadeli güvenilirliği işletim disiplinine bağlar. Temiz state, tamamlanma tanımının parçasıdır.

## 30 dakika kaybı

Pazartesi sabahı projeyi açıyorsun. Geçen Cuma "yarın temizlerim" diyerek bıraktığın dal hâlâ kirli: yorum içine alınmış üç fonksiyon, kalkanı düşmüş bir `.env.local`, makinede çalışıp CI'da düşen bir test, ne yaptığını anlatmayan bir `PROGRESS.md`. İlk 30 dakika ajanın değil senin. Çünkü ajana hangi state'ten devam edeceğini sen söyleyemiyorsun — ve ajan o state'i kendi başına çıkaramıyor.

Aynı senaryo 12 hafta üst üste tekrar ederse, proje şu hale gelir:

| Metrik                | Hafta 1 | Hafta 12 (temizliksiz) | Hafta 12 (temizlikli) |
| --------------------- | ------- | ---------------------- | --------------------- |
| Build başarı oranı    | %100    | %68                    | %97                   |
| Test geçme oranı      | %100    | %61                    | %95                   |
| Açılış süresi         | 5 dk    | 60+ dk                 | 9 dk                  |
| Bayat artefakt sayısı | 0       | 103                    | 11                    |

Aynı kod tabanı, aynı görev tipi, aynı ajan. Tek değişken: oturum sonunda **temiz state** bırakma disiplini.

## Tez

Uzun vadeli güvenilirlik tek koşumun başarısına değil, **işletim disiplinine** dayanır. Bir oturumun çıktısı yalnız üretilen değişiklik değil, aynı zamanda **bıraktığı durumdur**. Düzenek Mühendisliği (Harness Engineering) "temiz state"i tamamlanma tanımının (DoD) parçası kabul eder; aksi halde yarınki oturum bugünkünün hatalarını miras alır.

## Beş boyut

<div className="lesson-diagram" style={{background:'#F0F0EB',border:'1px solid rgba(14,20,23,0.08)',borderRadius:'20px',padding:'36px 44px',color:'#0E1417',fontFamily:'ui-sans-serif,system-ui,-apple-system,sans-serif',margin:'24px 0'}}>
  <div style={{display:'flex',justifyContent:'space-between',alignItems:'flex-start',gap:'18px'}}>
    <div>
      <div style={{fontSize:'10px',letterSpacing:'0.2em',fontWeight:'700',color:'#80807A'}}>BEŞ BOYUT · 12 HAFTA SONU</div>
      <div style={{fontSize:'19px',fontWeight:'600',marginTop:'6px'}}>Entropi her boyutu eşit yemiyor — en zayıf halkadan başlıyor.</div>
    </div>

    <div style={{display:'flex',gap:'10px'}}>
      <div style={{display:'flex',alignItems:'center',gap:'6px',fontSize:'11px',color:'#80807A'}}>
        <span style={{width:'14px',height:'2px',background:'#A5A59F',borderTop:'1px dashed transparent'}} />

        temizliksiz
      </div>

      <div style={{display:'flex',alignItems:'center',gap:'6px',fontSize:'11px',color:'#0E1417'}}>
        <span style={{width:'14px',height:'3px',background:'#0E1417'}} />

        temizlikli
      </div>
    </div>
  </div>

  <div style={{display:'grid',gridTemplateColumns:'1fr 1fr',gap:'10px 24px',marginTop:'24px',alignItems:'center'}}>
    <div style={{fontSize:'10px',letterSpacing:'0.16em',fontWeight:'700',color:'#A5A59F',textTransform:'uppercase'}}>Temizliksiz · hafta 12</div>
    <div style={{fontSize:'10px',letterSpacing:'0.16em',fontWeight:'700',color:'#0E1417',textTransform:'uppercase'}}>Temizlikli · hafta 12</div>
  </div>

  <div style={{marginTop:'10px',display:'flex',flexDirection:'column',gap:'12px'}}>
    <div style={{display:'grid',gridTemplateColumns:'90px 1fr 1fr',gap:'14px',alignItems:'center'}}>
      <div style={{fontSize:'13px',fontWeight:'600',color:'#0E1417'}}>Build</div>

      <div style={{position:'relative',height:'22px',background:'rgba(14,20,23,0.04)',borderRadius:'4px'}}>
        <div style={{width:'68%',height:'100%',background:'repeating-linear-gradient(45deg,#C5C5C0,#C5C5C0 5px,#D8D8D3 5px,#D8D8D3 10px)',border:'1px solid #A5A59F',borderRadius:'4px',boxSizing:'border-box'}} />

        <div style={{position:'absolute',top:'50%',left:'calc(68% + 8px)',transform:'translateY(-50%)',fontSize:'12px',color:'#80807A',fontWeight:'600',fontVariantNumeric:'tabular-nums'}}>%68</div>
      </div>

      <div style={{position:'relative',height:'22px',background:'rgba(14,20,23,0.04)',borderRadius:'4px'}}>
        <div style={{width:'97%',height:'100%',background:'#0E1417',borderRadius:'4px',position:'relative'}}>
          <div style={{position:'absolute',right:'0',top:'0',bottom:'0',width:'8px',background:'#E5FF59'}} />
        </div>

        <div style={{position:'absolute',top:'50%',left:'calc(97% + 8px)',transform:'translateY(-50%)',fontSize:'12px',color:'#0E1417',fontWeight:'700',fontVariantNumeric:'tabular-nums'}}>%97</div>
      </div>
    </div>

    <div style={{display:'grid',gridTemplateColumns:'90px 1fr 1fr',gap:'14px',alignItems:'center'}}>
      <div style={{fontSize:'13px',fontWeight:'600',color:'#0E1417'}}>Test</div>

      <div style={{position:'relative',height:'22px',background:'rgba(14,20,23,0.04)',borderRadius:'4px'}}>
        <div style={{width:'61%',height:'100%',background:'repeating-linear-gradient(45deg,#C5C5C0,#C5C5C0 5px,#D8D8D3 5px,#D8D8D3 10px)',border:'1px solid #A5A59F',borderRadius:'4px',boxSizing:'border-box'}} />

        <div style={{position:'absolute',top:'50%',left:'calc(61% + 8px)',transform:'translateY(-50%)',fontSize:'12px',color:'#80807A',fontWeight:'600',fontVariantNumeric:'tabular-nums'}}>%61</div>
      </div>

      <div style={{position:'relative',height:'22px',background:'rgba(14,20,23,0.04)',borderRadius:'4px'}}>
        <div style={{width:'95%',height:'100%',background:'#0E1417',borderRadius:'4px',position:'relative'}}>
          <div style={{position:'absolute',right:'0',top:'0',bottom:'0',width:'8px',background:'#E5FF59'}} />
        </div>

        <div style={{position:'absolute',top:'50%',left:'calc(95% + 8px)',transform:'translateY(-50%)',fontSize:'12px',color:'#0E1417',fontWeight:'700',fontVariantNumeric:'tabular-nums'}}>%95</div>
      </div>
    </div>

    <div style={{display:'grid',gridTemplateColumns:'90px 1fr 1fr',gap:'14px',alignItems:'center'}}>
      <div style={{fontSize:'13px',fontWeight:'600',color:'#0E1417'}}>Progress</div>

      <div style={{position:'relative',height:'22px',background:'rgba(14,20,23,0.04)',borderRadius:'4px'}}>
        <div style={{width:'35%',height:'100%',background:'repeating-linear-gradient(45deg,#C5C5C0,#C5C5C0 5px,#D8D8D3 5px,#D8D8D3 10px)',border:'1px solid #A5A59F',borderRadius:'4px',boxSizing:'border-box'}} />

        <div style={{position:'absolute',top:'50%',left:'calc(35% + 8px)',transform:'translateY(-50%)',fontSize:'12px',color:'#80807A',fontWeight:'600',fontVariantNumeric:'tabular-nums'}}>%35</div>
      </div>

      <div style={{position:'relative',height:'22px',background:'rgba(14,20,23,0.04)',borderRadius:'4px'}}>
        <div style={{width:'93%',height:'100%',background:'#0E1417',borderRadius:'4px',position:'relative'}}>
          <div style={{position:'absolute',right:'0',top:'0',bottom:'0',width:'8px',background:'#E5FF59'}} />
        </div>

        <div style={{position:'absolute',top:'50%',left:'calc(93% + 8px)',transform:'translateY(-50%)',fontSize:'12px',color:'#0E1417',fontWeight:'700',fontVariantNumeric:'tabular-nums'}}>%93</div>
      </div>
    </div>

    <div style={{display:'grid',gridTemplateColumns:'90px 1fr 1fr',gap:'14px',alignItems:'center'}}>
      <div style={{fontSize:'13px',fontWeight:'600',color:'#0E1417'}}>Artifact</div>

      <div style={{position:'relative',height:'22px',background:'rgba(14,20,23,0.04)',borderRadius:'4px'}}>
        <div style={{width:'18%',height:'100%',background:'repeating-linear-gradient(45deg,#C5C5C0,#C5C5C0 5px,#D8D8D3 5px,#D8D8D3 10px)',border:'1px solid #A5A59F',borderRadius:'4px',boxSizing:'border-box'}} />

        <div style={{position:'absolute',top:'50%',left:'calc(18% + 8px)',transform:'translateY(-50%)',fontSize:'12px',color:'#80807A',fontWeight:'600',fontVariantNumeric:'tabular-nums'}}>%18</div>
      </div>

      <div style={{position:'relative',height:'22px',background:'rgba(14,20,23,0.04)',borderRadius:'4px'}}>
        <div style={{width:'90%',height:'100%',background:'#0E1417',borderRadius:'4px',position:'relative'}}>
          <div style={{position:'absolute',right:'0',top:'0',bottom:'0',width:'8px',background:'#E5FF59'}} />
        </div>

        <div style={{position:'absolute',top:'50%',left:'calc(90% + 8px)',transform:'translateY(-50%)',fontSize:'12px',color:'#0E1417',fontWeight:'700',fontVariantNumeric:'tabular-nums'}}>%90</div>
      </div>
    </div>

    <div style={{display:'grid',gridTemplateColumns:'90px 1fr 1fr',gap:'14px',alignItems:'center'}}>
      <div style={{fontSize:'13px',fontWeight:'600',color:'#0E1417'}}>Startup</div>

      <div style={{position:'relative',height:'22px',background:'rgba(14,20,23,0.04)',borderRadius:'4px'}}>
        <div style={{width:'15%',height:'100%',background:'repeating-linear-gradient(45deg,#C5C5C0,#C5C5C0 5px,#D8D8D3 5px,#D8D8D3 10px)',border:'1px solid #A5A59F',borderRadius:'4px',boxSizing:'border-box'}} />

        <div style={{position:'absolute',top:'50%',left:'calc(15% + 8px)',transform:'translateY(-50%)',fontSize:'12px',color:'#80807A',fontWeight:'600',fontVariantNumeric:'tabular-nums'}}>%15</div>
      </div>

      <div style={{position:'relative',height:'22px',background:'rgba(14,20,23,0.04)',borderRadius:'4px'}}>
        <div style={{width:'94%',height:'100%',background:'#0E1417',borderRadius:'4px',position:'relative'}}>
          <div style={{position:'absolute',right:'0',top:'0',bottom:'0',width:'8px',background:'#E5FF59'}} />
        </div>

        <div style={{position:'absolute',top:'50%',left:'calc(94% + 8px)',transform:'translateY(-50%)',fontSize:'12px',color:'#0E1417',fontWeight:'700',fontVariantNumeric:'tabular-nums'}}>%94</div>
      </div>
    </div>
  </div>

  <div style={{marginTop:'22px',paddingTop:'16px',borderTop:'1px solid rgba(14,20,23,0.08)',display:'flex',justifyContent:'space-between',alignItems:'center',gap:'12px',flexWrap:'wrap'}}>
    <div style={{fontSize:'11.5px',color:'#80807A',fontStyle:'italic'}}>Lehman'ın yasası: kullanılan bir sistem, korunmadıkça çürür.</div>

    <div style={{display:'inline-flex',alignItems:'center',gap:'8px',background:'#E5FF59',border:'1.4px solid #1A2300',borderRadius:'999px',padding:'4px 12px',fontSize:'11px',fontWeight:'700',color:'#1A2300'}}>
      <span style={{display:'inline-flex',width:'14px',height:'14px',borderRadius:'50%',background:'#1A2300',color:'#E5FF59',alignItems:'center',justifyContent:'center',fontSize:'10px'}}>✓</span>
      günlük + haftalık disiplin
    </div>
  </div>
</div>

## Entropi varsayılandır — Lehman yasaları

Manny Lehman'ın yazılım evrimi yasaları nettir: **kullanılan bir sistem, korunmadıkça çürür.** İkinci yasa (artan karmaşıklık): bir sistem evrildikçe karmaşıklığı artar, ancak aktif olarak azaltılırsa azalır. Yedinci yasa (azalan kalite): aktif bakım yapılmayan bir sistemin algılanan kalitesi zamanla düşer.

Bu fizik kuralı kadar serttir. Düzenek üzerine kurduğun her şey — talimat, araç, ortam, durum, geri bildirim — aynı çürümeye tabi. **Aktif temizlik olmadan, çalışan düzenek dahi 12 haftada açılış maliyetinin 12 katına bakar.**

Martin Fowler'ın düzenek mühendisliği yazısı bu fikri operasyonel bir alışkanlığa indirger: ekiplerin sürdürmesi gereken şey, *"recurring 'garbage collection' that scans for drift and has agents suggest fixes"*. Yani düzenek, entropiye karşı yürüyen bir çöp toplayıcıdır. Sen toplamazsan, kimse toplamaz.

## "Sonra temizlerim" tuzağı

> "Sonra temizlerim" pratikte **asla temizlemem** demektir.

Eve geç gelen bir misafirin tabağı sabaha bırakmasıyla aynı dinamik. Sabah olduğunda tabakları yıkamanın maliyeti iki katına çıkar; yorgunluk birikir; bir gün bulaşık makinesi hiç koşmaz.

Düzenek söz konusu olduğunda kuralı tek satıra sıkıştır: **bir oturum, ya commit ile ya rollback ile biter.** Veritabanı işlemi gibi. Ortada yarım kalmış dosya yığını yok.

## Temiz state — beş boyut

Bir oturumun "temiz" sayılması için **beş boyutun hepsi** aynı anda doğru olmalıdır:

| Boyut        | Anlam                               | Kanıt                                                |
| ------------ | ----------------------------------- | ---------------------------------------------------- |
| **Build**    | Derlenir                            | `npm run build` / `make build` yeşil                 |
| **Test**     | Var olan testler geçer              | `npm test` / `make test` yeşil                       |
| **Progress** | Yapıldı / sürüyor / sıradaki yazılı | `PROGRESS.md` güncel                                 |
| **Artifact** | Bayat artefakt yok                  | Debug log, geçici dosya, yorum içine alınmış kod yok |
| **Startup**  | Standart açılış yolu çalışır        | `make dev` veya `npm run dev` müdahalesiz çalışır    |

Beşi eşit önemde. Birinde çatlak diğer dördünü çürütür. Build geçer ama açılış 20 dakika sürüyorsa, ajan bir sonraki oturumda yine aynı duvarla karşılaşır. Testler geçer ama `PROGRESS.md` boşsa, ajan ne yapacağını sıfırdan çıkarmak zorunda kalır.

## İki kademeli temizlik

Bellek yönetiminde iki klasik strateji vardır: reference counting (anlık) ve tracing GC (periyodik). Düzenek temizliği de aynı ikiliyi kullanır.

### 1) Anlık temizlik — her oturum sonu

Küçük, hızlı, idempotent. Aynı script kaç kez çağrılırsa çağrılsın aynı sonucu üretir.

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

# Geçici log'ları sil
rm -f /tmp/debug-*.log

# Yerel env dosyasını şablona döndür
git checkout -- .env.local 2>/dev/null || true

# Testleri tekrar koştur (kanıt üret)
npm test

# Build kanıtı
npm run build

# State raporu
git status --porcelain
```

İdempotans burada kritik. Temizlik script'i kendisi bir hata kaynağı olamaz; iki kez çalıştırmak hiç çalıştırmamakla aynı veya daha güvenli olmalıdır.

### 2) Periyodik temizlik — haftalık veya iki haftada bir

Tam tarama, yapısal düzeltme, benchmark. Reference counting'in yakalayamadığı döngüsel çöpü tracing GC nasıl topluyorsa, periyodik temizlik de anlık script'in göremediği bayatlığı toplar:

* Dependency güncellemesi ve security audit
* Bayat feature listesi temizliği
* Eski branch'lerin kapatılması
* **Periyodik düzenek sadeleştirme**: bir düzenek bileşenini geçici olarak kapat, benchmark koş. Sonuç bozulmuyorsa o bileşeni **kalıcı olarak kaldır**.

Düzenek bir kez kurulduktan sonra büyümeye eğilimlidir. Ama büyüme her zaman değer üretmez. Düzenli sadeleştirme, Fowler'ın "garbage collection against entropy" çerçevesinin saha karşılığıdır.

## Quality Document — modül başına sağlık

Düzeneğin izleyebileceği makine-okunur bir sağlık tablosu. Her modül için A/B/C notları:

```markdown theme={null}
# Quality Document — 2026-05-18

| Modül | Doğrulama | Ajan-okunabilirlik | Test kararlılığı | Mimari sınır | Konvansiyon |
| --- | --- | --- | --- | --- | --- |
| src/api  | A | A | B | A | A |
| src/db   | A | B | B | A | B |
| src/ui   | C | C | C | B | C  ← Önce buraya gir |
| src/jobs | B | A | C | B | A |
```

Yeni oturum bu tabloya bakar, **en düşük puanlı modülden başlar**. Düzenek "nereden başlayacağım" sorusunu sezgiye değil kanıta dayandırır. 12-Factor AgentOps bunu sertçe formüle eder: *"Your agent's context is now an engineering artifact, not chat history."* Quality Document, o engineering artifact'in sağlık göstergesidir.

## Oturum çıkış kontrol listesi

`AGENTS.md` veya `docs/session-close.md` içinde **sözleşme** olarak yer alır. Tek bir kalem işaretlenmediyse oturum bitmez.

```markdown theme={null}
## Oturum Çıkış Kontrol Listesi
- [ ] Build geçer (`npm run build` / `make build`)
- [ ] Tüm testler geçer (`npm test` / `make test`)
- [ ] Feature listesi güncellendi
- [ ] Debug kod yok (console.log, debugger, yarım TODO/FIXME)
- [ ] Standart açılış yolu çalışır (`npm run dev` / `make dev`)
- [ ] PROGRESS.md son durumu yazılı
- [ ] DECISIONS.md yeni karar varsa eklendi
- [ ] CI yeşil
- [ ] Tüm değişiklikler commit edildi; çalışma dizini temiz
```

## Pause-resume — durum bilen bir düzenek

12-Factor Agents çerçevesi pause-resume'u temel bir düzenek özelliği sayar. Faktör 5 ve 6: *"unify execution state and business state"* ve *"launch/pause/resume with simple APIs"*. Tek bir olay günlüğü serileştirilebilir ve geri yüklenebilir — bu, oturumun temiz teslim edilmiş olmasını gerektirir. Kirli state, deserializable değildir; ajan onu yeniden inşa etmek için saatler harcar.

Citadel projesinin pratik karşılığı bu fikrin uygulaması: *"Multi-session work survives context compression and session boundaries. Start an architecture overhaul today, close your laptop, pick it up tomorrow — the campaign state, decisions, and progress are all preserved."* `.planning/` dizini hem Claude Code hem Codex altında aynı şekilde okunur — çünkü oturumlar **temiz commit'lerle** bitirilir, "yarım kalmış dosya yığını" ile değil.

Ralph minimal harness pattern (Geoffrey Huntley) aynı disiplini başka bir yönden test eder: `while :; do cat PROMPT.md | claude-code ; done`. Döngünün her turunda aynı `@fix_plan.md` ve şartname stack'e deterministik olarak yığılır. Tur sonunda `git add -A` ve `git commit` — *zorunlu temiz teslim*. Aksi takdirde bir sonraki turun stack'i bozulur. Ralph kanıtlıyor: en yalın düzenek bile temiz state olmadan dönmez.

## Sayılarla

| Metrik          | Hafta 1 | Hafta 12 (temizliksiz) | Hafta 12 (temizlikli) | Fark       |
| --------------- | ------- | ---------------------- | --------------------- | ---------- |
| Build pass      | %100    | %68                    | %97                   | **+29 pp** |
| Test pass       | %100    | %61                    | %95                   | **+34 pp** |
| Startup         | 5 dk    | 60+ dk                 | 9 dk                  | **6,7×**   |
| Bayat artefakt  | 0       | 103                    | 11                    | **9,4×**   |
| İlk 30 dk verim | tam     | sıfır                  | tam                   | —          |

Bu rakamlar sezgisel projeksiyonlardır; saha gözleminde nokta nokta dağılım gösterir, ama yönü değişmez. Lehman yasaları kadar tutarlı: aktif bakım olmadan eğri aşağı gider.

## Pratik kontrol listesi

* [ ] Oturum çıkış kontrol listesi `AGENTS.md`'de.
* [ ] Anlık temizlik script'i (idempotent) mevcut, CI'da koşuyor.
* [ ] Periyodik temizlik (haftalık) takvimde.
* [ ] Quality Document mevcut, son 7 gün içinde güncellendi.
* [ ] Beş boyutun (build/test/progress/artifact/startup) beşi de oturum sonunda yeşil.
* [ ] Aylık düzenek sadeleştirme planı var; en az bir bileşen geçici kapatılıp ölçüldü.
* [ ] Yarım commit'e izin yok — commit veya rollback.
* [ ] Pause-resume bir oturum boyunca test edildi: kapat, aç, devam et.

## Müfredat içindeki yeri

[Ders 11](/dersler/11-gozlemlenebilirlik-neden-duzenegin-icinde-olmali) düzeneği görünür kıldı; bu son ders onu sürdürülebilir kıldı. Beş boyutlu temiz state, iki kademeli temizlik, Quality Document ve oturum çıkış kontrol listesi — entropiye karşı yürüyen çöp toplayıcının somut parçalarıdır. Lehman yasaları kadar serttir: aktif bakım yoksa çalışan düzenek bile çürür. Müfredat burada bitiyor; disiplin buradan başlıyor.

Tüm halkalar tek bir koşumda birleşsin diye: [Proje 06 — Capstone: Bütünleşik Düzenek](/projeler/06-butunlesik-duzenek-capstone). Beş aparat, doğrulama kapısı, e2e suite, gözlemlenebilirlik ve temiz teslim aynı düzenekte toplanır. İyi bir düzeneğin ölçüsü tek koşum değildir; otuzuncu koşumda hâlâ yarı saniyede açılabilmesidir.