Her AI kodlama aracı proje kurallarınızla bir Markdown dosyası ister. Ama hepsi farklı bir Markdown dosyası ister.

Birden fazla AI aracı kullanıyorsanız (ve çoğu geliştirici kullanıyor), bu hızla kafa karıştırıcı hale gelir. İşte hangi dosyalara ihtiyaç duyduğunuz ve her birine neyin girdiğine dair kesin rehber.

Dosyalara Genel Bakış

Dosya	Araç	Konum	Kapsam
`AGENTS.md`	Evrensel (tüm araçlar)	Proje kökü	Tüm AI ajanları için paylaşılan kurallar
`CLAUDE.md`	Claude Code	Proje kökü	Claude’a özgü talimatlar
`.cursor/rules/*.md`	Cursor	`.cursor/rules/` dizini	Cursor’a özgü kurallar
`.github/copilot-instructions.md`	GitHub Copilot	`.github/` dizini	Copilot’a özgü talimatlar
`.windsurf/rules`	Windsurf	`.windsurf/` dizini	Windsurf’e özgü kurallar
`JULES.md`	Google Jules	Proje kökü	Jules’e özgü talimatlar

AGENTS.md: Evrensel Standart

En iyi kullanım alanı: Birden fazla AI aracı kullanan ekipler, açık kaynak projeleri

AGENTS.md, sahip olduğumuz evrensel standarda en yakın şeydir. Artık 60.000’den fazla repository tarafından kullanılmakta ve Linux Foundation’ın Agentic AI Foundation’ı (MCP ve goose ile birlikte) tarafından yönetilmektedir.

Paylaşılan talimatlarınızı buraya koyun --- her AI aracının bilmesi gereken şeyler:

Proje yapısı ve mimarisi
Build ve test komutları
Kod stili kuralları
Yaygın kalıplar ve anti-kalıplar
Bağımlılıklar ve kurulum adımları

Her büyük AI kodlama aracı AGENTS.md’yi okuyacak, bu da onu projenizin AI talimatları için tek gerçek kaynağı yapacak.

CLAUDE.md: Claude Code’un Hafızası

En iyi kullanım alanı: Claude Code kullanıcıları, Anthropic’te standardize olan ekipler

CLAUDE.md her Claude Code oturumunun başında otomatik okunur. Hafıza kalıcılığı ve oturum bağlamı gibi bazı Claude’a özgü özellikleri destekler.

CLAUDE.md’yi şunlar için kullanın:

Claude’a özgü davranış ayarlamaları
Yalnızca Claude Code’un desteklediği özellikler
Claude için AGENTS.md’yi geçersiz kılma veya genişletme

Önerilen kalıp: AGENTS.md’de paylaşılan kurallar, CLAUDE.md’de Claude’a özgü eklemeler.

.cursorrules / .cursor/rules/: Cursor’ın Yaklaşımı

En iyi kullanım alanı: Cursor kullanıcıları, Cursor’ı birincil IDE olarak kullanan ekipler

Cursor başlangıçta tek bir .cursorrules dosyası kullandı, ardından daha ayrıntılı kontrol için .cursor/rules/ dizinine geçti. Dizindeki her dosya Cursor’ın uyguladığı ayrı bir kuraldır.

Cursor kurallarını şunlar için kullanın:

Cursor’a özgü ajan davranışı
Cursor’ın Composer ve Agent modları için kurallar
Dosya türüne özgü talimatlar (örneğin .tsx ve .py için farklı kurallar)

copilot-instructions.md: GitHub’ın Kuralı

En iyi kullanım alanı: GitHub Copilot kullanıcıları, GitHub merkezli iş akışları

GitHub Copilot, proje düzeyi talimatlar için .github/copilot-instructions.md’yi okur. GitHub’ın yapılandırmayı .github/ dizinine koyma kuralını izler.

Önerilen Kurulum

Çoğu proje için en fazla iki dosyaya ihtiyaç duyarsınız:

Tek bir AI aracı kullanıyorsanız:

Sadece o aracın native dosyasını kullanın (Claude Code için CLAUDE.md, Cursor için .cursor/rules/, vb.).

Birden fazla AI aracı kullanıyorsanız:

AGENTS.md --- tüm paylaşılan kurallar (mimari, build komutları, kurallar)
Araca özgü dosya --- yalnızca o araca özgü özellikler için

Örnek yapı:

projeniz/
  AGENTS.md              # Paylaşılan: build komutları, mimari, kurallar
  CLAUDE.md              # Claude'a özgü: hafıza tercihleri, araç kullanımı
  .cursor/rules/style.md # Cursor'a özgü: composer davranışı
  .github/copilot-instructions.md  # Copilot'a özgü

Kurallarınıza Ne Eklenmeli

Binlerce repository’nin analizine dayanarak, en etkili talimat dosyaları şunları içerir:

Her zaman ekleyin:

Projeyi nasıl build edeceğiniz ve çalıştıracağınız
Testleri nasıl çalıştıracağınız
Temel mimari kararlar
Kod stili tercihleri

Genellikle yararlı:

YAPILMAYACAKLAR (negatif talimatlar şaşırtıcı derecede iyi çalışır)
Dosya yapısı açıklamaları
Yaygın hata ayıklama adımları
Bağımlılık yönetimi komutları

Atlayın:

Belirgin dil özellikleri
AI’ın zaten bildiği şeyler
Aşırı ayrıntılı kurallar (minimal başlayın, gerektiğinde ekleyin)

Web Bağlamıyla AI Kurallarınızı Oluşturma

İyi AI talimat dosyaları yazmak genellikle harici belgeler, stil kılavuzları veya mimari kalıplar referansı gerektirir. Web içeriğinin Markdown formatında olması burada yardımcı olur.

Örneğin, projeniz bir belgeleme sayfasındaki belirli bir API kalıbını izliyorsa şunları yapabilirsiniz:

O belgeleme sayfasını Markdown’a dönüştürmek için Save’i kullanın
İlgili bölümlere AGENTS.md’nizde referans verin veya alıntı yapın
AI kodlama asistanınız artık tam bağlama sahip

Aynısı framework belgeleri, stil kılavuzları, en iyi uygulama makaleleri ve Stack Overflow çözümleri için de geçerlidir. Temiz Markdown, hem sizin hem de AI araçlarınızın en verimli şekilde çalışabileceği formattır.

Sonuç

AI kodlama kuralları ekosistemi hâlâ gelişmektedir, ancak kalıp açıktır: hepsi Markdown. Bir araç veya beş araç kullanıyor olsanız da, projenizin AI talimatları sürüm kontrollü, insan tarafından okunabilir ve makine tarafından ayrıştırılabilir Markdown dosyalarında bulunur.

Evrensel kurallar için AGENTS.md ile başlayın, gerektiğinde araca özgü dosyalar ekleyin ve çözmeye değer tekrarlayan bir sorun görene kadar her şeyi minimal tutun.

Save herhangi bir web sayfasını temiz Markdown’a dönüştürür --- AI kodlama asistanlarınızın ihtiyaç duyduğu referans materyali ve belgeleme bağlamını oluşturmak için mükemmel. Save’i ücretsiz deneyin.