CLAUDE.md ve AGENTS.md: 42 projeden öğrendiklerim

Güncelleme (9 Kasım 2026): Claude Fable 5.2 ve Mythos 5.2 çıktı - fiyatlar, erişim ve benchmark sonuçları Claude Fable 5.2 rehberimde.

👁 111 okunma

Diskimde yapay zekâ ajanları için hazırlanmış 42 talimat dosyası var: farklı projelerin klasörlerinde 16 CLAUDE.md ve 26 AGENTS.md. En kısası tek satır, en uzunu 402 satır. En uzun dosya, Anthropic’in önerdiğinin iki katından da uzun. Gerçekte böyle bir dosyaya neler girdiğini iyi gösterdiği için önce ondan başlayacağım.

CLAUDE.md nedir?

Bu, Claude Code’un her oturumun başında okuduğu sıradan bir Markdown dosyasıdır. Ajanla her konuşma boş bir bellekle başlar; bu nedenle koddan çıkaramayacağı bilgileri ona yeniden vermeniz gerekir. CLAUDE.md bunu sizin yerinize yapar: test komutları, proje kuralları, ajanın yapmaması gerekenler ve daha önce karşılaştığınız tuzaklar.

Claude Code belgeleri, bu dosyanın kesin bir yapılandırma değil, bağlam olduğunu açıkça belirtiyor. Ajan genellikle dosyadaki kurallara uyar ama uymak zorunda değildir. Dosya silmek veya sunucuya dağıtım yapmak gibi bir şeyin her zaman engellenmesi gerekiyorsa CLAUDE.md’ye yazmak yerine ayarlardaki kancaları ve izinleri kullanın.

Dosya nerede bulunur, hangileri okunur?

Aynı anda birden fazla dosya kullanılabilir. Claude Code tek bir dosya seçmek yerine bulduğu dosyaları en genelden çalıştığınız klasöre en yakın olana doğru birleştirir.

Ajanı başlattığınız konumun üst klasörlerindeki dosyalar hemen okunur. Alt klasörlerdeki dosyalar ise ajan o klasörlerde dosya okumaya veya değiştirmeye başladığında yüklenir. Böylece büyük bir depoda ajan veritabanı üzerinde çalışırken arayüz talimatları bağlamı gereksiz yere doldurmaz.

İlk sürümü /init komutuyla oluşturabilirsiniz. Claude kodu inceler ve bulduğu komutları ve kuralları dosyaya yazar. İyi bir başlangıçtır, ancak ben geri kalanını her zaman elle eklerim; çünkü en değerli satırlar koddan çıkarılamayanlardır.

En uzun dosyam: 402 satır

Belgeler, bağlamı tükettiği ve ajanın talimatlara uyma olasılığını düşürdüğü için tek bir CLAUDE.md dosyasının 200 satırdan kısa tutulmasını öneriyor. Jantaris projemdeki dosyam 402 satır ve 46.095 bayt. 16 CLAUDE.md dosyamdan yalnızca bu eşik değeri aşıyor; ortanca uzunluk 35 satır.

Dosya bir anda bu hâle gelmedi. Her hatadan sonra yeni bir tuzak eklenerek büyüdü: sunucunun görselleri nasıl önbelleğe aldığı ve aynı adla değiştirilen dosyanın kullanıcılara neden ancak bir hafta sonra ulaştığı, güvenlik mekanizmasının saatte kaç kayda izin verdiği ve testlerin bunu nasıl sıfırlaması gerektiği, sunucunun nerede olduğu ve e-postaların nasıl gönderildiği. Her satır belirli bir sorunun izini taşıyor. Sonunda hepsi birikerek fazla uzun bir dosya oluşturdu.

Benim yaklaşımım şu: CLAUDE.md bir proje dokümantasyonu değil, mayın haritasıdır. Uygulamanın nasıl çalıştığını ajan koddan ve README’den bulabilir. CLAUDE.md’de kodda görünmeyen ama daha önce sorun çıkarmış bilgiler yer almalı. Dosya 200 satırı aştığında içeriği .claude/rules/ altındaki konu bazlı dosyalara ayırıyorum. @dosya.md biçimindeki içe aktarma yalnızca düzen sağlar; içe aktarılan dosya yine bütünüyle yüklenir.

Kursumda gösterdiğim dosya: 34 satır

İyi bir örnek, sıfırdan geliştirdiğimiz bir oto tamir atölyesi uygulaması olan “Baza napraw” projesinin CLAUDE.md dosyası. Proje, Claude Code ile bir hafta sonunda SaaS geliştirme kursumda yer alıyor. Dosyanın tamamı şöyle:

# Baza napraw - ajan için notlar

Ürün, ekranlar ve kurallar: @SPEC.md
Yalnızca ZAKRES.md içindeki YAPILMALI bölümünü oluştur. Kapsam dışı fikirleri
dönüş koşuluyla birlikte DAHA SONRA bölümüne ekle ve bana sor.

## Teknoloji yığını
- Node 22.13+, npm bağımlılığı yok: node:http, node:sqlite, node:test, fetch.
- SQLite: data/app.db; geçişler: migrations/NNN_ad.sql.
- HTML sunucuda oluşturulur; tarayıcıda yalın JS kullanılır.

## Komutlar
- npm run dev                 8080 numaralı bağlantı noktasında sunucu; dosya değişince yeniden başlat
- npm test                    node --test "test/*.test.js" (glob tırnak içinde)
- npm run reset               Sıfırdan veritabanı + test verileri + test hesapları
- python tools/zrzuty.py URL  data/shots/ konumuna 1440 px ve 390 px görüntüler

## Kurallar
- Tutarları en küçük para biriminde INTEGER olarak sakla. Kayan noktalı sayı kullanma.
- Plan sınırlarını (R1-R3) sunucu denetler. Tarayıcı yalnızca gösterir.
- SPEC.md içindeki her R kuralının, adında kural numarası bulunan bir testi olmalı.
- Metin dosyalarını LF satır sonlarıyla kaydet.
- Metinlerde yalnızca "-" kullan. Test tüm şablonları denetler.

## Yasaklar
- .env dosyasını okuma. Dağıtım yapma. git push, git reset veya git clean çalıştırma.
- Testleri data/app.db üzerinde çalıştırma (testler bellekteki veritabanını kullanır).
- Üretici verilerini (Autodata, HaynesPro, üretici portalları) içe aktarma:
  AB’de üretici lisansları ve veritabanı koruması geçerlidir.

## Ortam tuzakları
- Git Bash yolları dönüştürür: /... ile başlayan komutlardan önce MSYS_NO_PATHCONV=1 kullan.
- Düzenli ifade içeren dosyaları bash heredoc ile değil, dosya aracıyla yaz
  (heredoc ters eğik çizgileri kaybedebilir).

Her bölümün bir nedeni var:

• Şartnameye yönlendirme. Ürün açıklaması SPEC.md içinde duruyor; CLAUDE.md yalnızca bu dosyayı içe aktarıyor. YAPILMALI bölümünü belirten satır, ajanın kapsamın dışına çıkmasını engelliyor. Bu satır olmazsa bir saat sonra kimsenin istemediği özelliklerle karşılaşabilirsiniz.
• Kesin sözdizimine sahip komutlar. Test komutundaki tırnak içindeki glob, kolayca gözden kaçan bir ayrıntı. Bütün test dosyalarının çalışıp çalışmayacağını bu belirliyor.
• Denetlenebilir kurallar. Tutarların en küçük para biriminde saklanması, sınırların sunucu tarafında denetlenmesi ve her kurala bir test yazılması. “Temiz kod yaz” gibi doğrulanması mümkün olmayan talimatlara yer yok.
• Yasaklar. Dosya yalnızca bir istek niteliğinde olduğu için en önemli yasakları izin ayarlarında da tekrarlıyorum.
• Ortam tuzakları. Windows ve Git Bash, eğik çizgiyle başlayan yolları bozabiliyor. Ajan, komut başarısız olana kadar bunu bilmez.

Bir düzenleme turuna mal olan satır

Bir örnekle daha iyi anlaşılır. 30 Ekim’de DYGOT dergisi için metinleri düzenlerken sunucudaki güncel durumu alan bir komut dosyası, düzeltmelerle yükleme arasında çalıştırıldı. Yerel değişikliklerin üzerine yazdı ve ilk düzenleme turu kayboldu. O günden beri bu projenin talimat dosyasında şu cümle yer alıyor: “Yalnızca çalışmaya başlamadan önce çalıştır - düzenleme ile yükleme arasında çalıştırırsan değişikliklerinin üzerine yazar.” Koddan komut dosyasının ne zaman çalıştırılabileceği anlaşılamayacağı için hiçbir otomatik üretici bu satırı yazamazdı.

AGENTS.md: diğer ajanlar için aynı yaklaşım

AGENTS.md, farklı araçların okuduğu ortak talimat dosyası adıdır. OpenAI Codex, Cursor, Gemini CLI, GitHub Copilot ajanı ve başka araçlar bu dosyayı okuyabilir. Biçimin geliştirilmesini Linux Foundation bünyesindeki Agentic AI Foundation yürütüyor. Benim 26 AGENTS.md dosyam var ve ortanca uzunlukları 8 satır; çünkü çoğu Codex için tek bir grafik görevini tarif ediyor.

Claude Code da 2.1.277 sürümünden itibaren AGENTS.md dosyalarını okuyabiliyor. Varsayılan olarak bunu yalnızca projede CLAUDE.md yoksa yapıyor. İki dosya da varsa Claude kendi dosyasını okuyor, AGENTS.md dosyasını ise atlıyor. İki araca da aynı kuralları vermenin en kolay yolu, kuralları AGENTS.md dosyasında tutup CLAUDE.md dosyasına @AGENTS.md içe aktarma satırını eklemek. Beceriler ve MCP sunucuları dâhil tüm düzeni Claude Code’dan Codex’e nasıl taşıyacağımı Claude Code’dan Codex’e geçiş yazısında anlattım.

Claude ve Codex’in sırayla çalıştığı projelerde dosyanın sonuna bir kural daha ekliyorum: iş bittikten sonra ortak ajan günlüğüne tarih, ajan adı ve değişiklik listesini yaz. Sonraki ajan başlamadan önce günlüğü okuyor ve önceki ajanın neleri değiştirdiğini görebiliyor. Bu yöntem, iki aracın belleğini eşitlemekten daha kolay.

Dosyaya neleri eklemiyorum?

• Gizli anahtarları ve parolaları. Proje dosyası sıklıkla depoya eklenir. Dosyalarımda .env içeriği yerine bu dosyanın okunmaması gerektiğini belirten bir kural bulunur.
• Klasör yapısını. Ajan bunu birkaç saniyede kendisi görebilir; dosyaya yazılan açıklama ise ilk değişiklikte eskir.
• Genel ifadeleri. “Kaliteyi önemse” hiçbir şeyi değiştirmez. “Her kuralın numarasını taşıyan bir testi olmalı” ise değiştirir.
• Birbiriyle çelişen kuralları. Belgeler, çelişen iki talimat varsa Claude’un istediğini seçebileceği konusunda uyarıyor. Dosyalarımı ara sıra okuyup artık geçerli olmayan kuralları siliyorum.
• İnsanlara yönelik notları. Bunları saklamam gerekiyorsa HTML yorumu olarak ekliyorum: <!-- -->. Claude Code dosyayı yüklemeden önce bu yorumları çıkardığı için bağlam tüketmiyorlar.

Nasıl başlayabilirsiniz?

Claude Code’u kullanmaya yeni başlıyorsanız CLAUDE.md dosyasını önceden doldurmayın. /init komutunu çalıştırın, anlamlı olanları bırakın ve ajan aynı hatayı ikinci kez yaptığında bir satır ekleyin. Bir hafta sonra elinizde bir rehberdeki projeyi değil, kendi projenizi anlatan bir dosya olur. Kurulumu ve ilk adımları Claude Code kurulumu rehberinde, planların maliyetini ise Claude Code ne kadar? yazısında anlattım.

Şartnameyi ve CLAUDE.md dosyasını Claude Code ile bir hafta sonunda SaaS geliştirme kursunda adım adım hazırlıyoruz: fikir için talebi kontrol etmekten veritabanı, giriş ve ödemelere, oradan da kendi sunucunuza dağıtıma uzanan 30 ders.

Kaynaklar ve kontrol tarihi

Bilgiler 6.11.2026 itibarıyla geçerlidir.

• Projelerimdeki CLAUDE.md ve AGENTS.md dosyaları (kopyalar ve başkasına ait depolar çıkarıldıktan sonra 42 dosya), 6.11.2026’da sayıldı
• Claude Code belgeleri: How Claude remembers your project (CLAUDE.md, AGENTS.md, içe aktarma ve 200 satır sınırı)
• AGENTS.md biçimi hakkında

// okumaya devamClaude Pro ve Max mı, API mi? Opus 5.5 maliyetiYapay zekâ araçlarıClaude Duet Türkiye’de kullanılabilir mi?RehberlerClaude Duet nedir? Anthropic’in ilk yazan ajanıYapay zekâ araçları