Unutmayan AI Ajanları Nasıl Oluşturulur (Bellek Dosyaları Kullanarak)

Çoğu AI ajanı model kötü olduğu için başarısız olmaz.

Her oturumda hafızasını kaybetmiş gibi uyandıkları için başarısız olurlar.

Claude'a "pnpm kullanıyoruz, npm değil" dersiniz.

Sonraki oturum: yine npm dener.

"Burada default export yok" dersiniz.

Sonraki oturum: default export yazar.

Yaptığınız her düzeltme, oturum bittiği an buharlaşır.

Bunun tek dosyalık bir çözümü var.

Bunu bulmam için üç ay boyunca kendimi tekrarlamam gerekti.

İşte öğrendiğim her şey.

Çoğu AI ajanı neden başarısız oluyor

Sorun modelde değil.

Sorun modelin altındaki eksik katman.

→ Bir prompt yazarsınız

→ Ajan görevi yapar

→ Oturum biter

→ Hafıza kaybolur

→ Sonraki oturum: aynı hatalar

→ Aynı talimatları tekrarlarsınız

→ Sonsuza kadar

Bu döngü, AI kodlamasında zaman kaybının en büyük tek kaynağıdır.

Kötü kod değil. Halüsinasyon değil.

Tekrar.

Eksik katman: hafıza

Herkes hangi modelin en zeki olduğuna takıntılı.

Yanlış katman.

Gerçek yükseltme daha zeki bir model değil.

Modele öğrendiklerini depolayabileceği bir yer vermektir.

→ Promptlar → ajana şu an ne yapması gerektiğini söyler

→ Ajanlar → görevi yürütür

→ Hafıza → bağlamı oturumlar arasında kalıcı kılar

→ Kalıcı bağlam → tekrarlanan düzeltmeler olmaz

→ Öğrenme sistemi → ajan zamanla gerçekten gelişir

Bu, bir araç ile bir takım arkadaşı arasındaki farktır.

Bir araç ne derseniz onu yapar, her seferinde sıfırdan başlar.

Bir takım arkadaşı dünü hatırlar.

Her AI ajanının ihtiyaç duyduğu 5 hafıza dosyası

Hafızanın eksik katman olduğunu kabul ettiğinizde, sıradaki soru şu: nerede duruyor?

Beş dosya. Her birinin farklı bir görevi var.

→ CLAUDE.md — Claude'un kişisel brifing belgesi

→ AGENTS.md — evrensel standart, her büyük araç tarafından okunur

→ CLAUDE.local.md — kişisel tercihleriniz, asla git'e eklenmez

→ MEMORY.md — AI'ın kendisi hakkında otomatik olarak yazdığı notlar

→ README.md — ajanlar için değil, insanlar için

Her birine göz atalım.

CLAUDE.md — her şeyi başlatan dosya

Bunu proje kök dizinine ekleyin.

Claude her oturumun başında onu okur.

Bunu, hafıza kaybı olan yeni bir ekip üyesi için bir brifing belgesi olarak düşünün.

İyi bir CLAUDE.md dört bölümden oluşur:

→ Proje bağlamı — tek satır. "Stripe ve Postgres ile Next.js e-ticaret uygulaması."

→ Kod stili — "kodu düzgün biçimlendir" değil, "ES modülleri, named export, 2 boşluklu girinti kullan."

→ Komutlar — tam dizeler. "testleri çalıştır" değil, pnpm test:integration.

→ Mimari — "API rotaları /src/api/[resource]/route.ts dosyasına gider. DB erişimi için repository pattern."

1# CLAUDE.md
2
3## Proje Bağlamı
4Next.js 14 e-ticaret uygulaması. Postgres + Stripe entegrasyonu.
5
6## Kod Stili
7- Yalnızca ES modülleri
8- Named export, asla default export yok
9- 2 boşluklu girinti
10- TypeScript strict modu
11
12## Komutlar
13- Kurulum: pnpm install
14- Geliştirme: pnpm dev
15- Test: pnpm test:integration
16- Lint: pnpm lint:fix
17
18## Mimari
19- API rotaları: /src/api/[resource]/route.ts
20- DB erişimi: yalnızca repository pattern
21- Bileşenler: /src/components, her bileşen için bir dosya

Hedef: 300 satırın altında.

Her satır, gerçek işle dikkat çekmek için rekabet eder.

/init çalıştırın, Claude otomatik olarak bir başlangıç dosyası oluşturur.

Ardından çoğunu silin.

Varsayılan dosya, Claude'un package.json'dan zaten bildiği şeyleri içerir. Yalnızca Claude'un dosya olmadan yanlış yapacağı şeyleri tutun.

[@imports](https://x.com/@imports) sistemi — hafif tutun

CLAUDE.md her şeyi tutmak zorunda değil.

Diğer dosyaları içe aktarabilir:

Bkz.

@README .md proje genel bakışı için

Bkz.

@docs/api-patterns .md API kuralları için

Bkz.

@package .json mevcut npm script'leri için

İçe aktarmalar özyinelemeli olabilir — en fazla 5 seviye derinliğe kadar.

Bu, "tek dev dosya" sorununu çözer.

Ekipler için: ön uç ekibi docs/frontend-rules.md dosyasını yönetir.

Güvenlik docs/security.md dosyasını yönetir.

CLAUDE.md sadece hepsini içe aktarır.

Bir kök dosya. Birçok uzmanlaşmış kaynak.

AGENTS.md — evrensel standart

CLAUDE.md yalnızca Claude için çalışır.

Ekibiniz ayrıca Cursor, Copilot veya Gemini CLI kullanıyorsa — onlar asla okumaz.

AGENTS.md bunu düzeltir.

Tek dosya. Her büyük ajan onu okur.

Claude Code, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Aider, Zed, Warp ve daha fazlası tarafından desteklenir.

Standart markdown'dır. Özel bir şema gerekmez. YAML gerekmez.

1# AGENTS.md
2
3## Proje Genel Bakışı
4Next.js 14, Postgres ve Stripe ile oluşturulmuş e-ticaret platformu.
5
6## Derleme ve Test
7- Kurulum: pnpm install
8- Geliştirme: pnpm dev
9- Test: pnpm test
10- Lint: pnpm lint:fix
11
12## Kod Standartları
13- TypeScript strict modu
14- Default export yerine named export
15- API rotaları /src/api/ içinde REST kurallarına uyar
16
17## Test Gereksinimleri
18- Tüm PR'ler test içermelidir
19- Birim testleri için vitest, e2e için playwright

Bunu AI ajanları için bir README olarak düşünün.

README.md insanlar içindir. AGENTS.md, satıcıdan bağımsız olarak her ajan içindir. CLAUDE.md ise Claude'a özgü ekstraları üstüne ekler.

Tamamlayıcıdırlar. Rakip değil.

Otomatik hafıza — kendi notlarını alan AI

Bu en yeni ve en ilginç katman.

Claude Code artık sizin oturumlarınız sırasında kendi hafıza dosyalarını yazıyor.

memory/ ├── MEMORY.md ← dizin, her oturumda yüklenir ├── debugging.md ← hata ayıklama desenleri hakkında notlar ├── api-conventions.md ← API tasarım kararları └── ...

Önemli değişim:

CLAUDE.md'yi siz yazarsınız. Talimatları siz sağlarsınız.

MEMORY.md'yi Claude yazar. Öğrendiklerini kaydeder.

→ İnsan kuralları yazar

→ Ajan çalışırken desenleri keşfeder

→ Ajan kendi hafızasını yazar

→ Gelecek oturumlar daha akıllı başlar

Bunu doğrudan tetikleyebilirsiniz. Verimli bir oturumun sonunda şunu söyleyin:

"Bugün kod tabanımız hakkında öğrendiklerinle hafıza dosyalarını güncelle."

Öğrenilenler kalıcı olur. Özel ORM sarmalayıcınızı beşinci kez açıklamak zorunda kalmazsınız.

Claude'un kaydettiklerini gözden geçirmek veya düzenlemek için istediğiniz zaman /memory çalıştırın.

/init ardından silme iş akışı

Yeni bir projede hafıza dosyasını başlatmanın en hızlı yolu:

1. Proje dizininizde /init çalıştırın
2. Claude, kod tabanınıza göre bir başlangıç CLAUDE.md oluşturur
3. İhtiyacınız olmayanı silin

Çoğu insanın hata yaptığı adım 3'tür.

Oluşturulan dosya bir taslaktır, bitmiş bir ürün değil.

Genellikle dolgu içerir. "Bu proje JavaScript kullanıyor." Teşekkürler — package.json'dan görünüyor.

Makul bir taslağı düzenlemek, boş bir dosyadan yazmaktan daha iyidir.

Kurulumdan sonra organik olarak geliştirin.

Claude yanlış bir varsayım yaptığında — örneğin kullanımdan kaldırılmış bir paketi içe aktarmaya devam ediyorsa — sadece bir kez düzeltmeyin.

Şunu söyleyin: "CLAUDE.md'me ekle: her zaman @company/utils-v2'den içe aktar, @company/utils'den değil."

Talimat sonraki her oturum için kalıcı olur.

Birkaç haftada bir, Claude'dan CLAUDE.md'yi gözden geçirmesini ve temizlemesini isteyin.

Talimatlar birikir. Bazıları gereksiz hale gelir. Diğerleri çelişmeye başlar. Hızlı bir geçiş onu keskin tutar.

Gerçek kurulumum

Tüm bunları birden çok üretim projesinde test ettikten sonra, kalıcı olan şu oldu:

→ AGENTS.md proje kökünde — herhangi bir AI aracının okuyacağı paylaşılan talimatlar. Derleme komutları, kod standartları, test gereksinimleri.

→ Claude'a özgü davranışlar için [@imports](https://x.com/@imports) ile CLAUDE.md. 100 satırın altında kalır, çoğunlukla docs/ dosyalarını işaret eder.

→ Kişisel tuhaflıklar için CLAUDE.local.md — test verilerim, sandbox URL'lerim, kısayol komutlarım. Asla git'e eklenmez.

→ Otomatik hafıza etkin. Claude kendi notlarını alır. Aylık olarak gözden geçiririm.

→ Diğer her şey, AGENTS.md'yi işaret eden sembolik bağlantılarla değiştirildi. Tek gerçek kaynak.

1# Çoklu araç tutarlılığı için sembolik bağlantı kurulumu
2ln -sfn AGENTS.md .github/copilot-instructions.md
3mkdir -p .cursor/rules && ln -sfn ../../AGENTS.md .cursor/rules/main.mdc

Zarif değil.

Ancak ekipteki her araç arasında talimat kaymasını öldürür.

Daha büyük değişim

Çoğu geliştirici şöyle düşünür:

Daha iyi model = daha iyi ajan.

Yanlış.

Gerçek formül:

Model + Hafıza + Erişim + Geri Bildirim = Kullanışlı Ajan

Hafızası olmayan daha zeki bir model, yarın test komutunuzu yine unutur.

Harika hafızaya sahip mütevazı bir model, her geçen hafta daha da keskinleşir.

Hafıza bileşik getirisi olan değişkendir.

Model zekası değil.

AI iş akışımda yaptığım en büyük iyileştirme model değiştirmek değildi.

Modele bir hafıza vermekti.

Aradaki fark:

"Claude, pnpm kullanıyoruz" — her oturumda

ve:

"Claude zaten biliyor" — her oturumda

Bir araç ile bir takım arkadaşı arasındaki farktır.

Bu faydalıysa:

→ Claude'a kendini tekrarlayan her geliştiriciye ulaşması için tekrar paylaşın

→ Siz uyurken bile bileşik getiri sağlayan daha fazla sistem için @sairahul1'i takip edin

→ Bunu yer imlerine ekleyin — bu gece kurun, yarın düzeltmeyi bırakın

AI, ürün oluşturma ve siz olmadan çalışan sistemler hakkında yazıyorum.