Claude Code artık AGENTS.md okuyor: Tüm ajanlar için tek talimat dosyası

Ajanlara talimat dosyası nedir?

Bir yapay zekâ kodlama ajanı projeni ilk kez açtığında hiçbir şey bilmez: Paket yöneticin hangisi, testler nasıl çalışır, hangi klasöre dokunmamalı? Bunları her seferinde anlatmamak için projenin köküne bir Markdown dosyası koyarsın. Ajan her oturumun başında bu dosyayı okur ve kurallarını buna göre belirler.

Sorun, her aracın bu dosyaya farklı bir ad vermesiydi. Claude Code CLAUDE.md dosyasını okuyordu. OpenAI’ın Codex’i, Cursor, Gemini CLI, GitHub Copilot’un ajanı ve daha pek çoğu ise AGENTS.md adında ortak bir biçimde buluştu. AGENTS.md, kendini “ajanlar için README” olarak tanımlayan açık bir biçim. Zorunlu bir alanı yok, sade Markdown. Bugün Linux Foundation çatısı altındaki Agentic AI Foundation tarafından yönetiliyor ve sitesine göre 60 binden fazla açık kaynak projede kullanılıyor.

Aynı fikrin tasarım kuralları için olanını, Google’ın DESIGN.md biçimini, yapay zekâ ve tasarım yazımızda anlattık.

Ne değişti?

Anthropic, 18 Eylül’de çıkan Claude Code 2.1.277 sürümüyle AGENTS.md desteği ekledi. Kural basit: Çalıştığın klasörde ya da üstündeki klasörlerde CLAUDE.md yoksa Claude artık AGENTS.md dosyasını okuyor.

Birkaç ayrıntı önemli:

• Bu bir birleştirme değil, yedek. İki dosya da varsa varsayılan olarak sadece CLAUDE.md okunuyor, AGENTS.md görmezden geliniyor.
• CLAUDE.local.md de sayılıyor. Kendi kişisel notların için bu dosyayı eklersen, ekibin AGENTS.md dosyası senin oturumunda okunmaz hâle geliyor.
• Ayar değiştirilebiliyor. /config içindeki “Project instructions” ayarıyla iki dosyayı birlikte okutabilir, AGENTS.md’yi tamamen kapatabilir ya da sadece şirketin merkezi kurallarını yükletebilirsin.
• Alt klasörler de destekleniyor. Büyük bir monorepo’da her paketin kendi AGENTS.md’si olabilir. Claude o klasördeki bir dosyayı açınca oradaki talimatları da okuyor.
• Her yerde çalışmıyor. Değişiklik günlüğüne göre Amazon Bedrock, Google Vertex ve Microsoft Foundry’de henüz yok. Belgelere göre telemetriyi kapattıysan ya da güncellemeden sonraki ilk oturumdaysan da AGENTS.md okunmuyor.
• AGENTS.override.md, AGENTS.local.md ve .agents/ klasörü okunmuyor. Codex gibi araçlar bunlardan bazılarını kullanıyor.

Neden bu kadar uzun sürdü?

Bu destek için GitHub’da açılan istek, Ağustos 2025’ten beri Claude Code deposunun en çok tepki alan isteğiydi. Geliştiriciler bu arada kendi çözümlerini bulmuştu: CLAUDE.md dosyasını AGENTS.md’ye bağlayan bir sembolik bağlantı (symlink) ya da içinde tek satır @AGENTS.md yazan bir CLAUDE.md. Yeni sürümle birlikte bu küçük ama can sıkıcı işe çoğu durumda gerek kalmıyor.

Senin için ne anlama geliyor?

• Sadece AGENTS.md kullanıyorsan: Artık ek bir şey yapmana gerek yok, yeter ki herkes 2.1.277 veya sonrasını kullansın.
• İçinde @AGENTS.md olan bir CLAUDE.md’n varsa: Dokunma. Bu yöntem her ortamda çalışmaya devam ediyor ve altına sadece Claude’a özel kurallar ekleyebiliyorsun.
• İki dosyada farklı kurallar varsa: Dikkat. Claude sadece CLAUDE.md’yi görür. Ortak kuralları AGENTS.md’ye taşı ve CLAUDE.md’den içe aktar.
• Yeni proje başlatıyorsan: Tek bir AGENTS.md makul bir başlangıç.

Unutma: Talimat dosyası, projeyi açan her ajanın her oturumda okuduğu bir komut listesi. Artık daha fazla araç aynı dosyayı okuduğu için, onu da kod gibi incelemek (pull request’te gözden geçirmek) gerekiyor.

Düşün

• Projende ajanlara verdiğin kurallar kaç farklı dosyaya dağılmış durumda?
• Bir ajana özel talimat ile tüm ajanlar için geçerli talimatı nasıl ayırırsın?

Kendi cümlelerimizle yazılmış bir özettir, çeviri değildir. Tüm kaynaklar yukarıda.