CLAUDE.md ve AGENTS.md: nedir, içine ne yazılır ve ajan kuralı neden görmezden gelir

CLAUDE.md ve AGENTS.md nedir

Bunlar, depo kökünde duran ve oturum başında ajan tarafından otomatik olarak context'e yüklenen sıradan Markdown dosyalarıdır. Bu dosyalarla ajana, kendi başına koddan öğrenemeyeceği şeyleri anlatırsınız: ortamın nasıl açılacağı, işin hangi komutlarla kontrol edileceği, hangi proje kurallarının tartışılmayacağı ve ayrıntılı belgelerin nerede olduğu.

CLAUDE.md, Claude Code'un okuduğu dosyadır. AGENTS.md ise aynı fikri taşıyan açık bir formattır ve birçok kodlama ajanı tarafından desteklenir. Ekipte farklı ajanlar kullanılıyorsa ana içeriği AGENTS.md'de tutup CLAUDE.md içinde ona başvurmak pratiktir. Claude Code, bir dosyayı @ ile içe aktarmayı destekler:

# CLAUDE.md
@AGENTS.md

Böylece kurallar tek bir yerde durur ve iki dosya arasında ayrışmaz.

Ajan bu dosyaları nasıl okur

Talimat dosyasının içeriği sistem prompt'uyla birlikte modelin context penceresine girer ve oturum boyunca orada kalır. Bundan üç önemli sonuç çıkar.

• Her satır context'te yer kaplar. Dosya her başlangıçta baştan sona okunur, o anki görev için yalnızca onda biri gerekse bile.
• Bunlar zorunlu kurallar değil, metindir. Model bunları diğer context ile birlikte dikkate alır ve yüzde yüz uyulacağının garantisi yoktur. Kesin yasaklar kontrol, hook'lar veya erişim hakları ile desteklenmelidir.
• Dosyalar iç içe konulabilir. Claude Code, proje kökündeki ve ~/.claude/ içindeki CLAUDE.md dosyalarını yükler; alt dizinlerdeki dosyaları ise ajan o dizindeki dosyalarla çalışırken yükler. Böylece bir modülün kuralları modülün yanında durabilir.

CLAUDE.md ve AGENTS.md içine ne yazılmalı

İyi bir talimat dosyası bir ders kitabı değil, bir haritadır. İlk gün deneyimli bir meslektaşa soracağınız soruların cevaplarını içerir.

1. Proje nasıl kurulur ve kontrol edilir

En değerli bölüm budur. Ajanın "hazır" demeden önce mutlaka çalıştırması gereken somut komutlar: testler, linter, tip kontrolü, ortamın açılması. Bunlar olmadan ajan işini "göz kararı" ile kontrol eder.

2. Sert sınırlar

Hiçbir koşulda çiğnenmemesi gereken kısa bir liste: güvenlik ve veri değişmezleri. Bunları uygulama talimatı gibi değil, değişmez kural gibi yazın: "tüm SQL sorguları parametreli olsun", "şu dosyadaki şu fonksiyonu kullan" değil.

3. Proje haritası

Neyin nerede olduğu: dizin yapısı hakkında birkaç satır ve ayrıntıların nerede bulunacağı. Her büyük konu için ayrı bir belgeye bağlantı verin. Ajan bu belgeyi yalnızca o konuda çalışacağı zaman açacaktır.

4. İşin durumunun nerede tutulduğu

Önceki oturumun kaldığı yerden devam etmek için nereye bakılacağı: plan dosyası, ilerleme günlüğü, backlog. Bu, ajanın oturumlar arası "unutkanlığını" giderir.

Nelerin yazılmaması gerekir

• Ajanın koddan öğrendiği şeyler. Bağımlılıkların listesi package.json veya pyproject.toml içinde, sınıfların yapısı kodun kendisinde.
• Genel tavsiyeler. "Temiz kod yaz", "dikkatli ol" davranışı değiştirmez, yalnızca yer kaplar.
• Projenin geçmişi ve tek seferlik notlar. "Mart ayında MySQL 5.7'den geçtik" mevcut görevde işe yaramaz.
• Nadir görevlerin ayrıntılı talimatları. Deploy veya veri migration'ı süreci haftada bir gerekir; bunu ayrı bir belgeye ya da skill'e taşıyın.
• Gizli bilgiler. Dosya depoda durur ve tamamen modele gider. Token'lar ve parolalar yalnızca ortam değişkenlerinde olmalıdır.

Ajan dosyadaki kuralı neden görmezden gelir

Tipik bir hikâye: ajan bir hata yaptı, dosyaya bir kural eklendi. Bir hata daha, bir kural daha. Birkaç ay sonra dosyada yüzlerce satır var ve kritik bir güvenlik kuralı, sanki hiç yazılmamış gibi çiğneniyor. Bunun genellikle dört nedeni vardır ve dördü birlikte çalışır.

Şişmiş dosya

600 satırlık bir dosya kabaca 10 ila 20 bin token'dır. Context penceresi büyük görünür, ama içinde kod, komut çıktıları ve konuşma geçmişi de yer alır. Talimatlar ne kadar yer kaplarsa, her kurala o kadar az dikkat kalır ve görevin kendisi için o kadar az yer kalır.

Ortada gömülü kural

Dil modelleri uzun bir metnin ortasındaki bilgiyi başından ve sonundan belirgin biçimde daha zayıf kullanır. Altı yüz satırlık bir dosyada üç yüzüncü satırdaki kural en zayıf noktada kalır.

Öncelik yok

Pazarlık konusu olmayan bir yasak ile üslup hakkında geçici bir not, listede aynı biçimde tek satır olarak yazılmıştır. Ajanın hangisinin daha önemli olduğunu anlamasının bir yolu yoktur. Dosyada birbiriyle çelişen üç üslup kuralı varsa, davranış her çalıştırmada değişir.

Çürüme

Kural eklemek bedavadır, silmek korkutucudur: "acaba başka bir şey buna bağlı mı?" Bu yüzden dosya sürekli büyür ve faydalı satırların oranı düşer. Bunu sinyal/gürültü oranı olarak ölçmek faydalıdır: tipik bir görev için gerçekte kaç satıra ihtiyaç var, kaçı gereksiz?

Çözüm: yığın yerine yönlendirici

Tek bir nedeni düzeltmek yetmez: dosyayı kısaltsanız ama yapısını düzeltmeseniz, kurallar yine iç içe kalır. İşe yarayan çözüm birkaç önlemin birleşimidir.

1. Giriş dosyasını bir yönlendiriciye çevirin. 50 ila 150 satır: kontrol komutları, sert kurallar, proje haritası ve konu belgelerinin bağlantıları.
2. Konuları ayrı dosyalara taşıyın. Örneğin docs/agents/deploy.md, docs/agents/database.md. Ajan bunları ihtiyaç duyduğunda açar. Claude Code'da tekrarlanan süreçler için skills kullanışlıdır; yalnızca ihtiyaç olduğunda yüklenirler.
3. Kritik olanı yukarı taşıyın. Sert kurallar dosyanın başında, MUST işaretiyle kısa bir blokta olsun.
4. Çelişkileri kaldırın. Her konu için tek bir kural. İstisna varsa, onu kuralın hemen yanına yazın.
5. Kuralı mekanizmayla destekleyin. İhlal kabul edilemezse metin yetmez. Onu yakalayan bir kontrol gerekir: linter, test, pre-commit hook'u, ajanın hook'u veya erişim haklarıyla getirilen bir yasak.
6. Düzenli gözden geçirin. Satır sınırı koyun ve her eklemede neyin silinebileceğini veya dışarı taşınabileceğini sorun.

Kural mı, kontrol mü?

Kompakt AGENTS.md örneği

# AGENTS.md — ödeme backend'i (FastAPI, PostgreSQL)

## MUST — çiğnenmez
- Para tutarları kuruş cinsinden int, asla float değil
- SQL yalnızca parametreli, f-string yok
- Uygulanmış migration'lar değiştirilmez, yalnızca yenileri eklenir
- Gizli bilgiler yalnızca ortam değişkenlerinden okunur

## "Hazır" demeden önce kontrol
docker compose up -d     # ortam
make lint                # ruff + mypy
make test                # pytest
make e2e                 # sipariş akışı senaryosu
e2e olmadan yeşil unit testler "hazır" değildir.

## Harita
- app/payments/   — tutar hesaplama, indirimler, sağlayıcı webhook'ları
- app/api/        — HTTP uç noktaları
- tests/e2e/      — kullanıcı senaryoları
Ayrıntılar: docs/agents/architecture.md, docs/agents/database.md

## İşin durumu
- PLAN.md      — mevcut hedef, bitiş ölçütleri, sonraki adım
- PROGRESS.md  — ne yapıldı ve nasıl doğrulandı, çıkmaz yollar
- BACKLOG.md   — yol üstünde fark edilenler: buraya yaz, şimdi düzeltme

Oturum sonunda PROGRESS.md ve PLAN.md içindeki sonraki adımı güncelle.

Dikkat edin, burada olmayan şeyler de var: kütüphane listesi, stil tavsiyeleri, proje geçmişi. Bunların hepsi ya koddan anlaşılır, ya kontrollerle sabitlenmiştir ya da konu belgelerinde durur.

Oturumlar arası unutkanlık: talimat dosyası ve plan dosyası

Talimat dosyası projede nasıl çalışılacağını anlatır, ama şu anda neyin olduğunu anlatmaz. Bunun için ajanın başta okuyup oturum sonunda güncellediği ayrı bir durum dosyası gerekir. Burada hedef, yapılanlar ve nasıl doğrulandığı, alınan kararlar ve gerekçeleri, reddedilen seçenekler ve tek bir sonraki adım bulunmalıdır. Kalite kontrolü basittir: yeni bir oturum açın, "devam et" yazın ve ajanın soru sormadan faydalı işe başlayıp başlamadığına bakın.

İki dosyayı karıştırmayın. Talimatlar seyrek değişir ve tüm görevleri ilgilendirir. Plan her oturumda değişir ve yalnızca mevcut görevi ilgilendirir. İkisi birleşirse talimat dosyası eski notlarla hızla şişer.

Dosyanın çalıştığını nasıl doğrularsınız

Talimat dosyasının da doğrulanması gerekir. Birkaç tipik görev seçin (hata düzeltme, küçük bir özellik, refactoring) ve ajanın ipucu olmadan ne yaptığına bakın: doğru komutları çalıştırıyor mu, doğru konu belgesini açıyor mu, sert kurallara uyuyor mu? Bir kural çiğneniyorsa önce şunu sorun: görünür mü, bir çelişkisi var mı, yerine otomatik bir kontrol konabilir mi? Yeni bir satır eklemek son çaredir.

Sonuç

CLAUDE.md ve AGENTS.md, ajanın projeye giriş kapısıdır. Kısa bir harita olarak kaldıklarında işe yararlar: kontrol komutları, üstte sert kurallar, ayrıntılara ve plan dosyasına bağlantılar. Bir kural yok sayılıyorsa neden çoğu zaman şişmiş, yapısız bir dosyadır; gerçekten kritik kurallar ise kontrollerle ve hook'larla desteklenmelidir. Talimat ve durum yapısının nasıl kurulacağı, gerçek bir görev üzerinde uygulamalı bir kursta anlatılmıştır.