CLAUDE.md ve AGENTS.md Arasındaki Fark Nedir?
AI coding agent kullanmaya başladığımızda projelerin içerisinde CLAUDE.md ve AGENTS.md gibi dosyalarla karşılaşmaya başlayabiliyoruz.
İlk bakışta ikisi de aynı işi yapıyor gibi görünüyor. Aslında temel amaçları gerçekten birbirine oldukça yakın. İkisi de AI coding agent'a proje hakkında bilgi vermek ve belirli kurallara uymasını sağlamak için kullanılıyor.
Ancak aralarında önemli bir fark var. CLAUDE.md özellikle Claude Code için kullanılan bir dosyayken, AGENTS.md farklı AI coding agent'lar arasında kullanılabilecek daha genel bir format.
CLAUDE.md Nedir?
CLAUDE.md, Claude Code'un projeyi daha iyi anlaması için kullanılan bir Markdown dosyasıdır.
Bu dosyanın içerisinde Claude Code'a projenin nasıl çalıştığını ve kod yazarken hangi kurallara uyması gerektiğini anlatabiliriz.
Örneğin projemizde pnpm kullanıyorsak, testleri nasıl çalıştıracağımızı veya belirli bir kodlama standardımız varsa bunları CLAUDE.md içerisine yazabiliriz.
Basit bir örnek vermek gerekirse:
# Project This project uses React and TypeScript. ## Package Manager Use pnpm instead of npm. ## Development pnpm install pnpm dev ## Tests pnpm test ## Rules * Use TypeScript. * Reuse existing components. * Do not add unnecessary dependencies.
Claude Code çalışırken bu bilgileri proje talimatları olarak kullanabilir.
AGENTS.md Nedir?
AGENTS.md ise belirli bir AI aracına bağlı olmayan, coding agent'lara proje hakkında bilgi vermek için kullanılan daha genel bir Markdown formatıdır.
Yani burada amacımız sadece Claude'a değil, farklı AI coding agent'lara da projemizin kurallarını anlatabilmek.
Örneğin yine aynı bilgileri AGENTS.md içerisinde tutabiliriz:
# AGENTS.md ## Project This project uses React and TypeScript. ## Package Manager Use pnpm instead of npm. ## Development pnpm install pnpm dev ## Tests pnpm test ## Rules * Use TypeScript. * Reuse existing components. * Do not add unnecessary dependencies.
AGENTS.md formatı bugün farklı coding agent'lar tarafından destekleniyor. Bu nedenle projeye özel talimatları tek bir dosyada tutup farklı araçlarla paylaşmak mümkün.
Temel Fark Nedir?
En basit şekilde şöyle düşünebiliriz:
| Dosya | Odak Noktası |
|---|---|
CLAUDE.md |
Claude Code için proje talimatları |
AGENTS.md |
Farklı AI coding agent'lar için ortak proje talimatları |
Yani CLAUDE.md daha çok Claude Code'un kendi proje hafızası ve talimat dosyası gibi düşünülebilirken, AGENTS.md daha genel ve araçlar arasında paylaşılabilir bir yapı sunuyor.
CLAUDE.md Nereye Konur?
Claude Code, proje içerisindeki CLAUDE.md dosyalarını belirli bir hiyerarşi içerisinde okuyabiliyor.
En basit kullanımda dosyayı projenin ana dizinine koyabiliriz:
my-project/ ├── CLAUDE.md ├── package.json ├── src/ └── tests/
Claude Code ayrıca alt klasörlerde bulunan CLAUDE.md dosyalarını da kullanabiliyor. Bu özellikle büyük projelerde işe yarıyor.
Örneğin:
my-project/ ├── CLAUDE.md ├── frontend/ │ ├── CLAUDE.md │ └── src/ └── backend/ ├── CLAUDE.md └── src/
Burada ana dosyada tüm proje için geçerli kuralları, frontend ve backend altında ise sadece o bölüme özel kuralları tutabiliriz. Anthropic'in dokümantasyonunda Claude Code'un çalışma dizininden başlayarak ilgili CLAUDE.md dosyalarını hiyerarşik olarak yüklediği belirtiliyor.
AGENTS.md Nereye Konur?
AGENTS.md için de en basit kullanım projenin ana dizinine bir dosya koymaktır.
my-project/ ├── AGENTS.md ├── package.json ├── src/ └── tests/
Büyük projelerde alt klasörlere de ayrı AGENTS.md dosyaları eklenebilir.
Örneğin bir monorepo içerisinde:
project/ ├── AGENTS.md ├── apps/ │ ├── frontend/ │ │ └── AGENTS.md │ └── backend/ │ └── AGENTS.md └── packages/
Bu şekilde genel kurallar üst seviyede, belirli uygulamalara özel kurallar ise ilgili klasörde tutulabilir. AGENTS.md formatının resmi sitesinde de özellikle büyük monorepo projelerinde iç içe AGENTS.md dosyalarının kullanılabileceği belirtiliyor.
İçerikleri Aynı Olabilir mi?
Evet, olabilir.
Hatta iki dosyanın içerisinde büyük ölçüde aynı bilgileri bulundurabiliriz.
Örneğin:
## Package Manager Use pnpm. ## Development pnpm install pnpm dev ## Tests pnpm test
gibi bilgiler hem Claude Code hem de diğer coding agent'lar için anlamlıdır.
Ancak iki farklı dosyayı aynı anda kullanıyorsak burada dikkat etmemiz gereken bir nokta var. Aynı konu hakkında iki dosyada farklı kurallar yazmak kafa karışıklığına neden olabilir.
Bu nedenle ortak kuralları mümkün olduğunca tek bir yerde tutmak daha temiz bir yaklaşım olacaktır.
Hangisini Kullanmalıyız?
Burada aslında kullandığımız araçlara göre karar verebiliriz.
Eğer sadece Claude Code kullanıyorsak CLAUDE.md kullanmak oldukça doğal bir tercih.
Ancak projede Claude Code'un yanında Codex, Cursor, Gemini CLI veya başka coding agent'lar da kullanılıyorsa AGENTS.md kullanmak daha genel bir çözüm sağlayabilir. AGENTS.md'nin amacı zaten proje talimatlarını farklı coding agent'lar arasında paylaşılabilecek ortak bir formatta tutmak.
CLAUDE.md ve AGENTS.md Birlikte Kullanılabilir mi?
Evet, aynı projede ikisini birden kullanmak mümkün olabilir.
Örneğin:
my-project/ ├── AGENTS.md ├── CLAUDE.md ├── package.json ├── src/ └── tests/
Burada AGENTS.md içerisinde farklı coding agent'lar için ortak kuralları tutabiliriz.
CLAUDE.md içerisinde ise sadece Claude Code'a özel kurallar veya Claude Code'un çalışma şekliyle ilgili ek bilgiler bulunabilir.
Örneğin ortak kural:
pnpm kullan. Testlerden sonra lint çalıştır.
Claude Code'a özel bir kural ise:
Claude Code kullanırken bu proje için belirtilen özel çalışma akışını takip et.
gibi olabilir.
README.md ile Farkı Nedir?
Burada bir de README.md dosyasını unutmamak gerekiyor.
Üç dosyanın amacı birbirinden biraz farklı:
| Dosya | Temel Amaç |
|---|---|
README.md |
Projeyi insanlara tanıtmak |
AGENTS.md |
AI coding agent'lara ortak proje talimatlarını vermek |
CLAUDE.md |
Claude Code'a proje talimatlarını ve çalışma kurallarını vermek |
Örneğin README içerisinde projenin ne yaptığını ve nasıl kurulacağını anlatabiliriz. AGENTS.md içerisinde ise agent'ın kod yazarken bilmesi gereken kuralları ve test komutlarını tutabiliriz.
Claude Code kullanıyorsak CLAUDE.md ile Claude Code'a özel talimatları ayrıca verebiliriz.
Ben Hangisini Kullanırdım?
Eğer sadece Claude Code kullandığım küçük bir proje olsaydı CLAUDE.md kullanmak benim için yeterli olurdu.
Ancak farklı AI coding agent'ları da kullanabileceğim bir proje geliştiriyorsam ortak kuralları AGENTS.md içerisinde tutmayı tercih ederdim.
Böylece yarın Claude Code yerine başka bir coding agent kullandığımda proje kurallarını baştan oluşturmak zorunda kalmam.
Claude Code'a özel bir ihtiyacım varsa da bunu CLAUDE.md içerisinde ayrıca belirtebilirim.
Sonuç
Kısaca toparlamak gerekirse CLAUDE.md ve AGENTS.md birbirine oldukça benzeyen ancak kullanım alanları farklı olan iki dosya.
CLAUDE.md daha çok Claude Code'un proje talimatlarını ve hafızasını yönetmek için kullanılıyor. AGENTS.md ise farklı AI coding agent'ların kullanabileceği ortak ve açık bir format olarak karşımıza çıkıyor.
Benim için en kolay ayrım şu şekilde:
CLAUDE.md → Claude Code'a özel AGENTS.md → Coding agent'lar için genel
AI coding agent'ları projelerimizde daha fazla kullanmaya başladıkça bu tarz dosyaların önemi de artıyor. Çünkü yapay zekâya her görev verdiğimizde projenin kurallarını tekrar tekrar anlatmak yerine, bu bilgileri doğrudan projenin içerisine koyabiliyoruz.
