Cursor Rules ve CLAUDE.md ve AGENTS.md: Tek Bir Yapılandırmayı Üçünde de Denedik (2026)

Cursor Rules ve CLAUDE.md ve AGENTS.md: Tek Bir Yapılandırmayı Üçünde de Denedik (2026)

cursor rules vs claude md sorusunun içinde bir tuzak var: bunlar aralarından seçim yapacağınız iki alternatif değil. İki farklı araç tarafından okunan, tesadüfen aynı işi yapan iki ayrı dosya. Bir Cursor projesine CLAUDE.md bırakın, Cursor onu yok sayar. Claude Code'a bir AGENTS.md bırakın, yine hiçbir şey olmaz. Bu bizi de şaşırttı. AGENTS.md artık Linux Foundation çatısı altındaki Agentic AI Foundation tarafından yürütülen açık standart olarak 60.000'den fazla depoda yer alıyor, ama Claude Code hâlâ onu kendiliğinden okumuyor. İşte kendi deponuzda test ettiğimiz uyumluluk haritası.

Öne Çıkan Bulgular

• Cursor .cursor/rules/*.mdc ve AGENTS.md dosyalarını okur, CLAUDE.md dosyasını okumaz.
• Claude Code yalnızca CLAUDE.md dosyasını okur, AGENTS.md dosyasını doğal olarak okumaz.
• Tek dosyayı paylaşmak için: AGENTS.md'yi CLAUDE.md'ye sembolik bağlantı (symlink) yapın veya @AGENTS.md ile içe aktarın.
• AGENTS.md üzerinde standartlaşın (açık standart, 60 bin+ depo), ardından yalnızca gerekli yerlerde araca özgü ek kurallar ekleyin.

Hangi Yapılandırma Formatını Kullanmalısınız? 30 Saniyelik Karar

Formatınızı popülerliğe göre değil, ekibinizin yapısına göre seçin. Tek bir araç kullanıyorsanız o aracın kendi dosyasını kullanın. İki veya daha fazla araç kullanıyorsanız AGENTS.md'yi tek gerçek kaynak olarak benimseyin ve yalnızca bir aracın diğerlerinde olmayan bir ihtiyacı varsa araca özgü ek kural ekleyin. Kafa karışıklığının çoğu bu tek kuralla çözülüyor.

Yapılandırmasından önce hangi asistanı çalıştıracağınıza hâlâ karar veremediyseniz en iyi yapay zeka kodlama ajanlarını inceleyen rehberimizle başlayın, sonra dosya kurulumuna geri dönün.

Burada asıl önemli olan eksen taşınabilirlik. Bir .cursor/rules dosyası Cursor içinde güçlü, her yerde işe yaramaz. Bir AGENTS.md ise her yere gidebilir. Yani sonsuza kadar tek bir araca bağlı kalmayacaksanız, araçtan bağımsız dosya daha güvenli bir bahis.

Her Format Aslında Ne? (Her Biri 30 Saniyede)

Bu üç dosyanın tamamı tek bir şey yapıyor: bir yapay zeka kodlama aracına, kod yazmaya başlamadan önce projenizin kurallarını, konvansiyonlarını ve tuzaklarını aktarmak. Fark, bu dosyaları kimin okuduğu ve kapsamlarının nasıl belirlendiği. İşte kısa versiyonu. Her biri için ayrıntılı nasıl-yapılır rehberi kendi yazısında.

Cursor Rules, .cursor/rules/ içindeki .mdc dosyalarıdır. Cursor dört kural türünü destekler (her zaman aktif, ajan-tarafından-istenen, glob kapsamlı ve manuel @ ile bahsedilen), yani bir kuralı yalnızca *.tsx dosyalarınıza veya yalnızca migrasyonlarınıza bağlayabilirsiniz. Frontmatter, globlar ve token bütçesi için .cursor/rules dosyalarını nasıl yazacağınızı anlatan rehberimizi okuyun.

CLAUDE.md, Claude Code'un hafıza dosyasıdır. Claude, çalıştığınız klasörden dizin ağacında yukarı doğru yürür ve bulduğu her CLAUDE.md dosyasını birleştirir. Düz Markdown'dır, frontmatter gerekmez. Yapısı ve Claude'un onu göz ardı etmesini engelleyen kurallar için Claude'un göz ardı etmeyeceği bir CLAUDE.md nasıl yazılır yazısına bakın.

AGENTS.md açık standarttır. Depo kökünde tek bir düz Markdown dosyası olup Cursor, Codex, Copilot, Windsurf, Zed, Aider ve daha onlarca araç tarafından doğal olarak okunur. Agentic AI Foundation tarafından yürütülür ve zaten 60.000'den fazla projede yer alır.

İşte hatırlamaya değer özet: AGENTS.md, CLAUDE.md ve .cursor/rules birbirinin rakibi değil, aynı talimatın farklı okuyuculara hitap eden versiyonları.

Cursor Rules ve CLAUDE.md ve AGENTS.md: Kapsamlı Karşılaştırma

Farkı görmenin en hızlı yolu yan yana koymak. Belirleyici sütun taşınabilirlik: dosyayı ek kurulum yapmadan hangi araçların okuduğu. AGENTS.md erişimde önde, Cursor Rules kapsam hassasiyetinde önde, CLAUDE.md ise tamamen Claude Code'a bağlı kalanlar için en avantajlısı.

.cursorrules satırına dikkat edin. Bu tek kök dosya Cursor'da hâlâ çalışıyor, ama resmi dokümantasyondan çıkarıldı, dolayısıyla artık eski (legacy) kabul edin. Yeni projeler .cursor/rules/*.mdc veya AGENTS.md kullanmalı.

Hangi Araç Hangi Dosyayı Okuyor? (AGENTS.md Efsanesini Çürütüyoruz)

İnternetin yarısının yanlış bildiği gerçek şu: Claude Code AGENTS.md dosyasını doğal olarak okumaz, Cursor da CLAUDE.md dosyasını okumaz. Cursor .cursor/rules/*.mdc ile birlikte AGENTS.md dosyasını da okur. Claude Code ise yalnızca CLAUDE.md dosyasını okur, başka hiçbir şeyi okumaz. Her iki yönde de otomatik bir geri dönüş (fallback) yoktur, bu da tek bir standart dosyanın her şeyi kapsayacağını varsayan ekiplerin ayağına dolanır.

Bu soru sürekli sorulduğu için net konuşalım. Bir Claude Code projesine AGENTS.md bırakmak tek başına hiçbir şey yapmaz. Claude Code yalnızca ve sadece CLAUDE.md'yi okur. Anthropic'in Claude Code hafıza dokümantasyonu dosya yükleme davranışını AGENTS.md'den hiç bahsetmeden anlatıyor, AGENTS.md spesifikasyonu Cursor ve Codex'i doğal okuyucular arasında sayıyor ama Claude Code'u saymıyor, Cursor'ın kendi kurallar dokümantasyonu bu ayrımı doğruluyor ve Claude Code GitHub issue'ları tam olarak bu duvara çarpan geliştiricilerle dolu.

Peki Cursor claude.md dosyasını okur mu? Hayır. Claude Code agents.md dosyasını okur mu? Yardım almadan okumaz. İşte bu yazının var olma sebebi tam olarak o "yardım" ve az sonra göreceğiniz iki kısa komuttan ibaret.

Öncelik ve İç İçe Geçme Nasıl İşliyor?

Her araç çakışmaları farklı şekilde çözüyor ve bunu yanlış anlamak "kuralım neden yok sayılıyor?" sorusunun en büyük kaynağı. Cursor, kuralları kaynak önceliğine göre birleştiriyor. Claude Code, dizin derinliğine göre birleştiriyor. AGENTS.md ise ağaçtaki en yakın dosyayı seçiyor. İyi bir claude md yönetimi, hangi zihinsel modelde olduğunuzu bilmekle başlar.

Bizim kurulumumuzda pratik sonuç basit: geniş kuralları yukarıda (depo kökünde), özel kuralları aşağıda (bir paket klasörünün içinde) tutun. Hem Claude Code hem de AGENTS.md için, çalıştığınız yere en yakın dosya önceliklidir, yani packages/api/AGENTS.md o klasörün içindeki her şey için kök dosyayı geçersiz kılar. Cursor burada istisna; klasör derinliğine göre değil, kaynak katmanına göre çözüyor.

Tek Yapılandırmayı Cursor + Claude Code'da Çalıştırdık, İşte Her Aracın Gerçekte Yüklediği

Bunu canlı bir Techsy müşteri deposunda (Next.js 15 backend), Cursor 3.7 (17 Haziran 2026 sürümü) ve Claude Code v2.1.x (Temmuz 2026 başı) kullanarak test ettik. Tek bir AGENTS.md, üç farklı paylaşım kurulumu, iki araçta da açılan aynı prompt. İşte her birinin tam olarak neyi yüklediği.

Minimal bir dosyayla başladık:

# AGENTS.md
- Package manager: pnpm, never npm.
- Tests: Vitest. Run `pnpm test` before any commit.
- DB access goes through `lib/db.ts` only, no inline SQL.

Kurulum 1: Tek başına AGENTS.md. Cursor bunu hemen algıladı. Dosya bağlamında göründü ve doğru şekilde npm install önerisinde bulunmayı reddetti. Claude Code onunla hiçbir şey yapmadı. Claude Code'da /memory komutunu çalıştırdığımızda sıfır proje hafıza dosyası listelendi: CLAUDE.md bulunamadı, AGENTS.md ise hiç fark edilmedi bile. Doğrulandı: doğal bir geri dönüş yok.

Kurulum 2: symlink. CLAUDE.md'yi aynı dosyaya yönlendirdik:

ln -s AGENTS.md CLAUDE.md

Artık Claude Code'da /memory, ./CLAUDE.md dosyasını bir Proje hafızası olarak listeledi ve yüklenen içerik AGENTS.md ile bayt bayt aynıydı. Cursor ise AGENTS.md'yi doğrudan okumaya devam etti. Tek bir fiziksel dosya, iki araç da memnun. Windows'ta bunun çalışması için Yönetici veya Geliştirici Modu'nun etkin olması gerekiyor, aksi halde ln/mklink sessizce başarısız oluyor.

Kurulum 3: @import. Symlink'i sildik ve bunun yerine gerçek bir CLAUDE.md dosyasının en üstüne tek bir satır ekledik:

@AGENTS.md

/memory bu kez CLAUDE.md'yi yüklenen dosya olarak gösterdi, altında da içe aktarılmış referans olarak AGENTS.md yer alıyordu. Bu, Anthropic'in fiilen belgelediği yol ve özel bir işletim sistemi izni gerektirmiyor.

Testimizden çıkan hüküm: symlink, Claude Code'un AGENTS.md'yi bayt bayt okumasını sağlıyor; @AGENTS.md içe aktarma ise Anthropic'in gerçekten önerdiği Windows-güvenli versiyon. İkisi de size tek bir gerçek kaynak veriyor. Sıfır dolaylılık için macOS/Linux'ta symlink'i, ekipte Windows kullanan biri varsa import satırını tercih edin.

Formatlar Arasında Geçiş: .cursorrules → .cursor/rules → AGENTS.md

Çoğu ekip buraya eski bir .cursorrules dosyasıyla geliyor ve tek dosya tuzağından çıkmak istiyor. Her iki yöndeki geçiş de kısa ve adımlar kopyala-yapıştır seviyesinde. İnsanları çarpan tek tuzak şu: .cursor/rules içindeki frontmatter'sız bir .md dosyası sessizce yok sayılır, bu yüzden uzantı mutlaka .mdc olmalı.

Eski bir .cursorrules dosyasını modernize etmek için iki temiz yol var:

• .cursor/rules/*.mdc'ye geçiş: .cursor/rules/general.mdc dosyasını oluşturun, frontmatter ekleyin (genel bir kural için alwaysApply: true) ve eski içeriğinizi altına yapıştırın. Doğruladıktan sonra .cursorrules'ı silin.
• AGENTS.md'ye geçiş (çoklu araç kullanan ekipler için önerilir): cursorrules'ı agents.md'ye dönüştürmek için .cursorrules dosyasının gövdesini depo kökünüzde yeni bir AGENTS.md'ye kopyalayın. Frontmatter gerekmiyor, düz Markdown. Ardından Claude Code'un da onu okuması için symlink veya @AGENTS.md içe aktarmayı ekleyin.

Cursor'da kalıp ondan daha fazla verim almak istiyorsanız, Cursor'ı günlük kullanımda daha verimli kullanma rehberimiz pratikte kural kapsamlamayı ele alıyor.

Ters yönde gitmek (AGENTS.md → CLAUDE.md) bir önceki bölümdeki symlink veya import işleminin aynısı. Kayıplı bir dönüşüm yok, çünkü üçü de altta yatan yapı olarak Markdown.

SKILL.md ve Copilot Talimatları Nereye Oturuyor?

Bu konuşmada iki format daha karşımıza çıkıyor ve skills md şu anda popülerlik kazanan bir arama terimi, dolayısıyla kısaca yerlerini belirtmekte fayda var. İkisi de üç ana dosyanın yerini almıyor; onların yanında duruyorlar.

SKILL.md, Anthropic'in Skills formatıdır: .claude/skills/*/SKILL.md içinde paketlenmiş, göreve özel talimatlardır ve CLAUDE.md gibi her zaman aktif olmak yerine, bir görev eşleştiğinde Claude tarafından talep üzerine yüklenir. Bunu Claude'un ihtiyaç duyduğunda başvurduğu özel bir el kitabı gibi düşünün, proje genelinde geçerli bir hafıza dosyası değil. Kapsamı hâlâ gelişiyor, o yüzden şimdiden fazla yatırım yapmayın. Gerçek bir iş akışına nasıl oturduğu için CLAUDE.md'nin gerçek bir Claude Code iş akışına nerede oturduğunu anlatan yazımıza bakın.

Copilot talimatları, GitHub Copilot için .github/copilot-instructions.md içinde yaşar. İyi haber: Copilot ayrıca AGENTS.md'yi de okuyor, yani açık standartta standartlaştıysanız Copilot ayrı bir dosyaya gerek kalmadan zaten kapsanmış oluyor.

Hangisini Kullanmalısınız? (Ekip Yapısına Göre)

Formatı ekibinizin gerçekte nasıl çalıştığına göre eşleştirin:

• Tek başına Claude Code kullanan biri: yalnızca CLAUDE.md kullanın. İleride Cursor veya Codex'i devreye almayı planlamıyorsanız AGENTS.md eklemeye gerek yok.
• Tek başına Cursor kullanan biri: glob kapsamlama için .cursor/rules/*.mdc, veya baştan taşınabilirlik istiyorsanız tek bir AGENTS.md.
• Karma araç kullanan ekip: tek gerçek kaynak olarak bir AGENTS.md, symlink veya import ile CLAUDE.md'ye bağlanmış. Yalnızca Cursor'a özgü davranışlar için küçük bir .cursor/rules dosyası ekleyin.
• Monorepo: kökte AGENTS.md artı paket başına iç içe dosyalar, böylece her alt proje kendini tanımlar ve en yakın dosya kazanır.

Techsy'de karma araç kullanan ekipler arasında yapay zeka kodlama yapılandırmasını standartlaştırıyoruz; genellikle tek gerçek kaynak olarak bir AGENTS.md ve bir aracın ihtiyaç duyduğu yerlerde araca özgü ek kurallar. Ekibiniz elle üç yapılandırma dosyasıyla uğraşıyorsa, ücretsiz bir danışmanlık alın, sizin için haritasını çıkaralım.

Son bir not: bu yazı yapılandırma dosyalarını karşılaştırıyor. Asıl araçlar arasında seçim yapmaya çalışıyorsanız, asistanların kendisini, yapılandırmalarını değil karşılaştıran yazımızı okuyun.

Sık Sorulan Sorular

Cursor CLAUDE.md dosyasını okur mu?

Hayır. Cursor .cursor/rules/*.mdc ve AGENTS.md dosyalarını doğal olarak okur, ama CLAUDE.md Cursor'ın dokümantasyonunda hiç geçmez ve yüklenmez. Cursor kullanıyorsanız ve Claude Code kullanıcılarıyla yapılandırma paylaşmak istiyorsanız, kurallarınızı CLAUDE.md yerine (Cursor'ın da okuduğu) AGENTS.md'ye koyun.

Claude Code AGENTS.md dosyasını okur mu?

Doğal olarak okumaz. Claude Code yalnızca CLAUDE.md dosyasını okur, AGENTS.md'ye otomatik bir geri dönüş yoktur. Bunu çalıştırmak için ya dosyaları symlink yapın (ln -s AGENTS.md CLAUDE.md) ki Claude AGENTS.md'yi bayt bayt okusun, ya da bir CLAUDE.md'nin 1. satırına @AGENTS.md ekleyerek içe aktarın. İçe aktarma, Anthropic'in önerdiği, Windows-güvenli seçenek.

Üç araç için de tek bir dosya kullanabilir miyim?

Evet. AGENTS.md'yi tek gerçek kaynağınız olarak benimseyin, Cursor ve Codex onu doğrudan okur. Claude Code için tek bir köprü ekleyin: ya AGENTS.md'yi CLAUDE.md'ye symlink yapın, ya da bir CLAUDE.md'nin en üstüne @AGENTS.md bırakın. Tek bir dosyayı sürdürürsünüz ve her araç aynı kuralları yükler. Tek yapılandırma paylaşma tarifi tam olarak bu.

.cursorrules kullanımdan mı kaldırıldı?

Yumuşak biçimde kaldırıldı. Depo kökündeki tek dosyalı .cursorrules Cursor'da hâlâ çalışıyor, ama artık resmi dokümantasyonda yer almıyor, bu da genellikle bir formatın tasfiye edildiğinin işaretidir. Yeni projeler kapsamlı kurallar için .cursor/rules/*.mdc, taşınabilirlik için AGENTS.md kullanmalı.

.cursorrules'ı AGENTS.md'ye nasıl dönüştürürüm?

.cursorrules dosyanızın gövdesini depo kökünüzde yeni bir AGENTS.md'ye kopyalayın. Düz Markdown olduğu için frontmatter veya yeniden biçimlendirme gerekmez. Ardından Claude Code'un da onu okuması için bir symlink veya @AGENTS.md içe aktarma ekleyin ve Cursor'ın yeni dosyayı aldığını doğruladıktan sonra eski .cursorrules'ı silin.

CLAUDE.md ile AGENTS.md arasındaki fark nedir?

CLAUDE.md, yalnızca Claude Code tarafından okunan, Claude Code'a özel bir hafıza dosyasıdır. AGENTS.md ise Cursor, Codex, Copilot ve 20'den fazla araç tarafından okunan açık bir standarttır, ama Claude Code tarafından doğal olarak okunmaz. Aynı Markdown formatı, aynı iş. Fark erişimde. AGENTS.md araçlar arasında dolaşır; CLAUDE.md ise Claude Code'un içinde kalır.

Birden fazla yapay zeka aracı kullanan bir ekip hangi formatta standartlaşmalı?

AGENTS.md. Çoğu araç tarafından doğal olarak okunan açık standart bu ve zaten 60.000'den fazla depoda kullanılıyor. Ortak kurallarınızı orada standartlaştırın, symlink veya import ile Claude Code'a köprüleyin ve yalnızca bir aracın diğerlerinde olmayan bir davranışa ihtiyacı varsa (.cursor/rules gibi) küçük araca özgü dosyalar ekleyin.

İç içe geçmiş yapılandırma dosyalarım olduğunda öncelik nasıl işler?

Hem Claude Code hem de AGENTS.md için, çalışma dizininize en yakın dosya kazanır, yani packages/api/AGENTS.md içindeki bir kural, o klasörün içindeki her şey için depo-kökü dosyasını geçersiz kılar. Cursor farklıdır: Takım, Proje ve Kullanıcı kurallarını klasör derinliğine göre değil kaynak katmanına göre birleştirir ve çakışmaları önceki kaynaklar kazanır.

SKILL.md nereye oturuyor?

SKILL.md, Anthropic'in gelişmekte olan Skills formatıdır: .claude/skills/*/SKILL.md içinde göreve özel talimatlardır ve CLAUDE.md gibi her zaman aktif olmak yerine, bir görev eşleştiğinde Claude tarafından talep üzerine yüklenir. CLAUDE.md'nin yerini almak yerine onu tamamlar. Kapsamı 2026'da hâlâ gelişiyor, dolayısıyla her projenin ihtiyaç duyduğu dördüncü bir dosya değil, özel bir ek olarak değerlendirin.