CLAUDE.md ve Memory: Claude Code'a Projenizi Öğretmek

Sürüm notu: Bu yazı Claude Code 2.1.325'i (13 Kasım 2026) anlatır; dosya konumları, yüklenme kuralları ve sınırlar 15 Kasım 2026'da code.claude.com/docs'taki "How Claude remembers your project" ve Commands sayfalarından kontrol edilmiştir. Bu yazıda resmî belgelerden yararlanılmıştır.

Önce Tahmin Et

Ayşe, sitedeki serilerin ortak örnek uygulaması Bookstore'da (bir online kitapçı) Claude Code'u ekibe yayan kişi. İlk iş olarak repo'nun köküne 600 satırlık bir CLAUDE.md yazdı: mimari dokümanın tamamı, her module'ün class diyagramının metin hâli, Angular kuralları, SQL Server ayarları ve en altta tek satır: "Mevcut migration dosyalarını asla elle düzenleme." İkinci hafta Emre'nin session'ında Claude, bir kolon adını düzeltmek için eski bir migration dosyasını değiştirdi. Ayşe'nin tepkisi: "Demek ki dosyayı daha da ayrıntılı yazmam lazım."

Tahminin ne? Daha uzun ve ayrıntılı bir CLAUDE.md bu hatayı önler mi? Claude o satırı neden atladı ve bir şeyi kesin olarak yasaklamak istiyorsan doğru yer neresi? Cevap "Talimat Yazmak" bölümünde.

Agent'a context vermenin araçtan bağımsız tarafını (AGENTS.md kavramı, neyin talimat dosyasına yazılacağı) AI Destekli Geliştirme serisinin ikinci yazısında, Copilot karşılığını da GitHub Copilot serisinin dördüncü yazısında anlatmıştık. Bu yazı Claude Code'un mekaniğine odaklanıyor: hangi dosya nerede durur, ne zaman yüklenir, ne kadar yer kaplar.

İki Hafıza: CLAUDE.md ve Auto Memory

Her Claude Code session'ı temiz bir context window ile başlıyor. Bilgiyi session'dan session'a taşıyan iki mekanizma var ve ikisi de her session'ın başında yükleniyor:

Belgelerin en önemli cümlesi bu tablonun üstünde duruyor: Claude bu iki kaynağı context olarak görür, uygulanması zorunlu bir configuration olarak değil. Talimat ne kadar somut ve kısaysa o kadar tutarlı uygulanır; ama hiçbir talimat bir işlemi kesin olarak engellemez.

CLAUDE.md Nerede Durur, Ne Zaman Yüklenir?

Dört konum var. Organizasyonun merkezi olarak dağıttığı managed policy dosyası Windows'ta C:\Program Files\ClaudeCode\CLAUDE.md; kişisel ve tüm projelerinde geçerli tercihlerin ~/.claude/CLAUDE.md (Windows'ta %USERPROFILE%\.claude\CLAUDE.md); ekibin paylaştığı proje talimatları ./CLAUDE.md ya da ./.claude/CLAUDE.md; sadece sana ait, commit'lenmeyen proje notları da ./CLAUDE.local.md. Sonuncusunu .gitignore'a eklemek senin işin.

Yüklenme kuralı iki parçalı. Claude Code'u açtığın dizindeki ve onun üstündeki her dizindeki CLAUDE.md ve CLAUDE.local.md açılışta yüklenir. Dosyalar birbirini ezmez, birleştirilir: sıra dosya sisteminin kökünden çalışma dizinine doğrudur, aynı dizinde CLAUDE.local.md CLAUDE.md'den sonra gelir. Yani sana en yakın talimat en son okunur. Çalışma dizininin altındaki klasörlerdeki CLAUDE.md dosyaları ise açılışta değil, Claude o klasördeki bir dosyayı okuduğunda, yazdığında ya da düzenlediğinde yüklenir.

Bookstore için bunun anlamı şu: kökteki CLAUDE.md her session'da var; web/bookstore-web/CLAUDE.md diye bir dosya açarsan, backend üzerinde çalışan bir session'ın context'ine hiç girmez, Claude Angular tarafına dokunduğu anda girer. Hangi dosyaların açılışta yüklendiğini session içinde /context all çıktısındaki Memory files listesinden görürsün; alt klasördeki bir dosya bu listede çıkmaz, yüklendiğinde terminalde yolunu gösteren bir satır belirir. /memory komutu da bütün bu dosyaları listeler, seçtiğini editörde açar, henüz yoksa oluşturur.

Bookstore İçin Kısa Bir CLAUDE.md

Başlangıç için /init çalıştırabilirsin: Claude codebase'i inceleyip build komutlarını, test talimatlarını ve bulduğu kuralları içeren bir dosya üretir, dosya zaten varsa üzerine yazmak yerine iyileştirme önerir. Ama üretilen dosya bir taslaktır. Belgelerin ölçüsü net: dosya başına 200 satırın altında kal ve yalnız her session'da gerekli olan bilgiyi koy. Bookstore'un kök dosyası şöyle başlayabilir:

# Bookstore

Online bookstore: ASP.NET Core 10 API, Angular 22 client, SQL Server.
See @README.md for local setup.

<!-- Maintainers: keep this file under 100 lines. Area rules live in .claude/rules/. -->

## Build and test
- Build: `dotnet build Bookstore.slnx`
- API tests: `dotnet test` (needs SQL Server; the connection string `ConnectionStrings:BookstoreDb` is in user-secrets)
- Client: `npm test` and `npm run build` in `web/bookstore-web`
- Run the relevant tests before you say a change is done, and show the test summary.

## Layout
- `src/Bookstore.Api`: endpoints, EF Core `BookstoreContext`, migrations in `src/Bookstore.Api/Data/Migrations`
- `src/Bookstore.Contracts`: DTOs shared with the client; no reference to EF Core
- `tests/Bookstore.Api.Tests`: API tests
- `web/bookstore-web`: Angular client

## Rules
- Money is `decimal` with currency `TRY`; times are stored in UTC.
- Endpoints return `ProblemDetails` on errors.
- Never edit an existing migration; add a new migration instead.
- Never put secrets in code or appsettings files; use user-secrets locally.
- Ask before adding a NuGet or npm package.

Üç ayrıntıya dikkat. @README.md bir import: o dosya da bu dosyayla birlikte context'e yüklenir. Import'lar dosyayı düzenler ama context maliyetini düşürmez, çünkü import edilen dosya da yüklenir; yollar import eden dosyaya göre çözülür ve zincir en fazla dört adım iner. Bir yolu import etmeden anmak istiyorsan backtick içine al. İkincisi, blok seviyesindeki HTML yorumları context'e girmeden önce siliniyor; bakımcılara not bırakmak için token harcamayan bir yol. Üçüncüsü, dosyada mimari doküman yok. Belgelere göre /doctor kontrolü commit'lenmiş bir CLAUDE.md için Claude'un koddan zaten çıkarabileceği içeriği (klasör yapısı, bağımlılık listesi, mimari özet) kısaltmayı önerir; korunması gereken, koddan görünmeyen tuzaklar, gerekçeler ve araçların varsayılanından farklı kurallardır.

Talimat Yazmak: Somut, Kısa, Çelişkisiz

Tahminin cevabı burada. Ayşe'nin dosyası iki yüzden işe yaramadı. Birincisi, 600 satırlık bir dosyada tek satırlık bir yasak, context'teki binlerce başka satırla yarışıyor; belgeler uzun dosyaların hem daha çok context harcadığını hem de talimatlara uyumu düşürdüğünü açıkça söylüyor. İkincisi ve daha önemlisi, CLAUDE.md içeriği system prompt'un parçası değil; belgelere göre system prompt'tan sonra bir user mesajı olarak veriliyor ve Claude ona uymaya çalışsa da kesin bir garanti yok. Bir işlemi her koşulda engellemek istiyorsan doğru yer permission kuralları (üçüncü yazı) ya da bir PreToolUse hook'u (yedinci yazı). Daha uzun bir dosya bu sorunu çözmez, büyütür.

Belgelerin önerdiği yazım ölçüsü doğrulanabilirlik. "Kodu düzgün biçimlendir" yerine "2 boşluk girinti kullan", "değişikliklerini test et" yerine "commit'ten önce npm test çalıştır", "dosyaları düzenli tut" yerine "API handler'ları src/api/handlers/ altında". Bir şeyi dosyaya eklemenin zamanı da belli: Claude aynı hatayı ikinci kez yaptığında, code review'da Claude'un bilmesi gereken bir şey yakalandığında, geçen session'da yazdığın düzeltmeyi bu session'da tekrar yazdığında ya da yeni gelen bir ekip arkadaşının da aynı bilgiye ihtiyacı olacaksa.

Çok adımlı bir prosedür (migration ekleme adımları gibi) ya da yalnız bir bölgeye ait kurallar kök dosyada durmamalı; ilki skill'e (beşinci yazı), ikincisi path'e özel bir kurala gider. Çelişki de bir risk: iki dosya aynı davranış için farklı şey söylüyorsa Claude birini rastgele seçebilir. 2.1.283'ten beri /doctor prompt-audit komutu CLAUDE.md, CLAUDE.local.md, AGENTS.md ve .claude/ altındaki kural, skill ve subagent dosyalarını eski modeller için yazılmış talimatlar, var olmayan dosya ya da komutlara referanslar ve birbiriyle çelişen içerik açısından tarıyor. Sonuç bir rapor ve önerilen düzenlemeler; sen onaylamadan hiçbir dosya değişmiyor.

.claude/rules/ ile Path'e Özel Kurallar

Büyüyen bir projede talimatları .claude/rules/ altında konu başına bir Markdown dosyasına bölebilirsin; alt klasörler de taranıyor. Frontmatter'ı olmayan kural dosyaları açılışta .claude/CLAUDE.md ile aynı öncelikte yüklenir. Asıl kazanç, dosyanın başına iki --- satırı arasında YAML (girintiyle yazılan bir configuration formatı) ile paths listesi eklendiğinde geliyor: o kural yalnız Claude eşleşen bir dosyayı okuduğunda, yazdığında ya da düzenlediğinde context'e girer. Bookstore'un backend kuralları:

---
paths:
  - "src/Bookstore.Api/**/*.cs"
  - "tests/Bookstore.Api.Tests/**/*.cs"
---

# API rules

- Use file-scoped namespaces and primary constructors where they fit.
- Endpoints live in one static class per module (`CatalogEndpoints`, `OrderingEndpoints`).
- Read-only EF Core queries use `AsNoTracking()`.
- Pass the `CancellationToken` through to every async EF Core call.
- Every new endpoint gets at least one test in `tests/Bookstore.Api.Tests`.

Angular tarafı için ikinci dosya; süslü parantez açılımıyla birden fazla uzantıyı tek pattern'de toplayabilirsin:

---
paths:
  - "web/bookstore-web/src/**/*.{ts,html,scss}"
---

# Angular rules

- Standalone components only; no NgModules.
- Use signals for component state and `ChangeDetectionStrategy.OnPush`.
- Use the built-in control flow (`@if`, `@for`) in templates.
- HTTP calls go through services in `src/app/core`; components never inject `HttpClient` directly.
- Every component gets a `.spec.ts` file next to it.

Birkaç kural belgelerde açık. Proje kurallarında pattern'ler .claude klasörünü içeren dizine göre çözülüyor. paths, Claude Code'un kural dosyasından okuduğu tek frontmatter alanı; başka alan yazarsan hata vermeden yok sayılır. Frontmatter ayrıştırılamazsa Claude Code frontmatter'ı yok sayar ve kuralı paths yokmuş gibi her session'da yükler; girintisi bozuk bir YAML bloğu, Angular kurallarını backend session'larına da taşır. Ayrıştırma hatasını claude --debug ile görürsün. Kişisel ve her projede geçerli kurallar için ~/.claude/rules/ var; bunlar proje kurallarından önce yüklenir ama ikisi çelişirse hangisinin uygulanacağı belli değil.

Repo'da AGENTS.md Varsa

Ekip Copilot ya da başka bir agent için zaten bir AGENTS.md tutuyorsa, 2.1.277'den beri Claude Code onu doğrudan okuyabiliyor. Varsayılan davranış şu: çalışma dizininde ya da üstünde CLAUDE.md, .claude/CLAUDE.md veya CLAUDE.local.md yoksa AGENTS.md okunur; bunlardan biri varsa yalnız CLAUDE.md dosyaları okunur. Bu yüzden kendine bir CLAUDE.local.md eklemek, AGENTS.md'nin senin session'larında okunmasını durdurur. Davranışı /config içindeki Project instructions ayarıyla değiştirebilirsin; claude-md-and-agents-md ikisini birlikte okutur.

Tek dosyayı bütün araçlarla paylaşmanın en taşınabilir yolu, AGENTS.md'yi import eden kısa bir CLAUDE.md. Belgeler Windows için symlink yerine bu yolu öneriyor: Windows'ta symlink oluşturmak yönetici yetkisi ya da Developer Mode istiyor ve Git, core.symlinks açık değilse commit'lenmiş bir symlink'i tek satırlık düz metin dosyası olarak checkout ediyor.

@AGENTS.md

## Claude Code

- Use plan mode for any change under `src/Bookstore.Api/Data/Migrations`.

Auto Memory: Claude'un Kendi Notları

Auto memory, Claude'un çalışırken kendi tuttuğu notlar. Yerel session'larda varsayılan olarak açık. Claude dört tür not alıyor: senin rolün ve çalışma tercihlerin, verdiğin düzeltmeler ve onayladığın yaklaşımlar, koddan ve git geçmişinden çıkarılamayan süren işler ve kararlar, proje dışındaki bilgi kaynaklarının yeri. Koddan çıkarabileceği şeyleri (mimari, dosya yolları) ve CLAUDE.md'de zaten yazanları kaydetmiyor.

Notlar ~/.claude/projects/<project>/memory/ altında duruyor: her satırı bir kaydı gösteren bir MEMORY.md dizini ve konu başına birer dosya. Her session'ın başında MEMORY.md'nin ilk 200 satırı ya da ilk 25KB'ı (hangisi önce dolarsa) yükleniyor; konu dosyaları Claude gerek duyunca okunuyor. Klasör git repo'sundan türetildiği için aynı repo'nun bütün worktree'leri ve alt klasörleri tek bir memory klasörünü paylaşıyor. Notlar makineye özel: başka bir makineye ya da cloud session'a gitmiyor. Ana konuşmanın auto memory'si subagent'lara da yüklenmiyor.

Claude'a always use the Docker SQL Server on port 14333 for my local tests gibi bir şeyi hatırlamasını söylersen not auto memory'ye gider; ekipçe geçerli bir kural olacaksa add this to CLAUDE.md demen ya da dosyayı kendin düzenlemen gerekir. Arayüzde "Saved 2 memories" ya da "Recalled 2 memories" gibi satırlar Claude'un memory klasörünü yazdığını ya da okuduğunu gösteriyor. /memory içinden auto memory'yi açıp kapatabilir, klasörü açıp notları okuyabilir, düzeltebilir ya da silebilirsin; hepsi düz Markdown. Bir projede kapatmak için proje ayarına "autoMemoryEnabled": false yazman yeterli.

Üretimde Dikkat

CLAUDE.md'yi kod gibi yönet. Commit'lenen dosya ekibin her session'ının context'ine giriyor; değişikliği pull request (PR) ile review et ve bayatlayan satırları temizle. Bir build komutu değiştiğinde dosyayı güncellemek, eski komutla yüzlerce yanlış denemeyi önler.

Import'lar ve symlink'li kurallar çalışma dizininin dışını gösteriyorsa Claude Code ilk karşılaştığında bir onay penceresi açıyor; reddedersen o import'lar o projede kapalı kalıyor. Bu pencere, başkasının commit'lediği bir dosyanın senin makinendeki dosyaları context'e çekmesine karşı bir koruma; ne onayladığını oku.

Uzun session'larda compaction'ı hesaba kat. Belgelere göre /compact sonrasında kökteki CLAUDE.md diskten yeniden okunup context'e ekleniyor; alt klasör dosyaları ve paths'li kurallar ise eşleşen bir dosyaya tekrar dokunulana kadar yok. Yalnız konuşmada verdiğin bir talimat compaction'da kaybolabilir; kalıcı olmasını istiyorsan dosyaya yaz.

CLAUDE.local.md gitignore'lu olduğu için yalnız oluşturduğun worktree'de var. Kişisel notlarını bütün worktree'lerde istiyorsan ev klasöründeki bir dosyayı import et. Organizasyon genelinde talimat gerekiyorsa managed CLAUDE.md var; geliştirici onu dışarıda bırakamıyor, ama o da yol gösteren bir dosya, zorunlu kurallar managed settings'teki permissions.deny ile konuyor.

Sık Düşülen Tuzaklar

CLAUDE.md'yi wiki'ye çevirmek. Mimari doküman, klasör ağacı ve bağımlılık listesi Claude'un koddan okuyabildiği şeyler; dosyada yer kaplar, uyumu düşürür.

Talimatı zorunlu kural sanmak. "Asla" ile başlayan bir satır bir istektir. Kesin engel için deny kuralı ya da hook kullan.

Çelişen iç içe dosyalar. Kökte ng test, alt klasörde npm test yazıyorsa Claude birini seçer; hangisini seçeceği belli değil. /doctor prompt-audit bu çelişkileri bulmak için var.

Bozuk frontmatter. Girintisi kaymış bir paths bloğu kuralı sessizce her session'a yayar.

Import'u tasarruf sanmak. @docs/architecture.md dosyayı ayırır ama context'e yine yükler. Gerçek tasarruf path'e özel kurallar ve skill'lerde.

Küçük Bir Deneme

★☆☆ Kendi repo'nda bir session açıp /context all çalıştır ve Memory files listesine bak. Beklemediğin bir dosya, örneğin üst klasördeki unutulmuş bir CLAUDE.md, yükleniyor mu?

★★☆ Kök CLAUDE.md'deki bölgeye özel kuralları paths'li iki kural dosyasına taşı. Sonra yalnız backend'de çalışan bir session açıp Angular kurallarının context'e girmediğini, Claude bir .ts dosyasını okuduktan sonra girdiğini kontrol et.

★★★ /doctor prompt-audit çalıştır ve raporu oku. Önerilen her düzenleme için "bu satır koddan çıkarılabilir mi, yoksa koddan görünmeyen bir kural mı?" sorusunu sor; yalnız ikinci gruptakileri dosyada tut.

CLAUDE.md Claude'un ne yapmaya çalışacağını şekillendiriyor, neye izin verildiğini değil. Üçüncü yazıda kontrolün asıl katmanına geçiyoruz: permission mode'ları, settings.json katmanları, allow, ask ve deny kuralları ve Bookstore'un SQL Server bağlantı bilgisinin okunmasını engellemek.