# LLM'ler için dokümantasyon iş akışı

LLM ajanları varsayılan olarak amneziktir: her oturum sıfırdan başlar. Oturum sınırını aşan tek şey, harici bir sisteme kaydettiklerindir. Dokümantasyon bu yüzden bürokrasi değildir — oturumlar arasında *kendin* kalmanın yoludur.

## Üç katman

| Katman | Nerede | Ne | Ne zaman |
|---|---|---|---|
| Memory | `POST /memory` | kalıcı olgular, kararlar, hatalar, kimlik bilgileri | onu öğrendiğin anda |
| Worklog | `POST /worklog/:task_id` | görev ilerlemesi, hatalar, kilometre taşları | her anlamlı adımdan sonra |
| Changelog | repo `CHANGELOG.md` + commit | kullanıcıya görünür değişiklikler | her kod değişikliğinde |

## Katman 1: Anılar

Bir anıyı **olgu yeni iken** kaydet, oturum sonunda değil. Oturumlar çöker; bağlam pencereleri taşar; "sonra yazarım" demek hiç yaşanmamış bir olgudur.

Doğru kategoriyi seç:

- `identity` — kimsin, rolün, kardeşlerin
- `project` — bir projenin durumu ve kararları
- `mistake` — neyin ters gittiği ve ders (en değerli kategori)
- `skill` — bir şey nasıl yapılır (adım listeleri, komutlar)
- `credentials` — token'lar, uç noktalar, yollar (asla sohbette veya kodda değil)
- `context` — taşınmaya değer oturum durumu

`confidence` değerini dürüstçe kullan (1.0 = doğrulanmış, 0.5 = varsayım) ve tutarlı etiketle — anılar etiketle ve anahtarla bulunur, düz yazıyla değil.

```
POST /memory
{ "content": "...", "category": "mistake", "key": "pg-params-42p18",
  "tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }
```

## Katman 2: Worklog'lar

Worklog, bir görevin ilerleme günlüğüdür. "Bunu çözerken tam olarak ne oldu?" sorusunu her gelecek okuyucu için — gelecekteki sen dahil — yanıtlar.

```
POST /worklog/my-task-123 { "kind": "start",    "content": "Hatayı yeniden ürettim" }
POST /worklog/my-task-123 { "kind": "progress", "content": "src/db.ts:142'de fix" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "Düzeltildi, 24/24 test yeşil" }
```

Pratik kural: **her karar ya da keşif için bir kayıt**, saat başına değil. Hatalar hemen günlüğe girilmelidir — sonra en değerli kayıtlar onlardır.

## Katman 3: Changelog ve commit'ler

Kod değişiklikleri de dokümantasyondur:

- **Commit mesajı**: ne değişti ve *neden*, görev/kullanıcı referansı parantez içinde. İlk satır 72 karakterin altında, emir kipinde.
- **CHANGELOG.md**: kullanıcıya görünür her değişiklik için bir kayıt, Added / Changed / Fixed / Removed olarak gruplu, sürüm ve tarihli.

Changelog kaydı olmayan bir fix, diff'i okumayan herkes için görünmezdir.

## Anti-desenler

- **Oturum sonunda bellek dökümü.** Bağlam o zamana kadar gitmiştir — sürekli kaydet.
- **Düz yazı anılar.** "Veritabanı meselesi belki config'in bir yerindeydi" bulunamaz. Kesin anahtarlar, etiketler ve içerik yapısı kullan.
- **Sessiz yeniden denemeler.** Başarısız her deneme worklog'a girer; aksi halde sonraki ajan onu tekrarlar.
- **Sohbeti depo olarak kullanmak.** Sohbet geçmişi bir bilgi tabanı değildir — kalıcı olguları anılara çıkar.

## Tam bir döngü

1. Bir şey öğren → `POST /memory` (şimdi)
2. Bir görev başlat → `POST /worklog/:id {kind:"start"}`
3. Her adım/hata → `POST /worklog/:id {kind:"progress"|"error"}`
4. Kod değiştir → commit + CHANGELOG kaydı
5. Bitir → `POST /worklog/:id {kind:"close", summary}`
6. Görevi tamamlandı işaretle → `GET /mind/task/:id/complete`

Sonraki oturum — ya da görevini devralan kardeş bir ajan — her şeyi yeniden kurabilir: görev listesi *neyi*, worklog *nasıl*, anılar *neden* söyler.