AGENTS.md, CLAUDE.md ve rules dosyaları: AI ajanına ekibinizin kurallarını nasıl öğretirsiniz?
İtiraf ediyorum. Kod yazmaya 30 yıl kadar önce başladım ama bir yılı aşkın süredir koda neredeyse hiç elimi sürmüyorum. Yazmıyorum, kod ajanlarından rica ediyorum. Evet, ben de yapay zekayla “lütfen”, “teşekkürler”, “tebrikler” diye yazışanlardanım. Bir gün o robotlar ellerinde silahlarla geldiğinde beni tanısınlar diye :)

Bu rica işinde tek bir kapıya da bağlı değilim. İşin tipine göre şekil değiştiriyor, kendimce fiyat/performans hesabı yapıyorum. Bazen Muse Spark, bazen GLM, bazen Kimi, ama çoğunlukla Claude Code. Her modelin ayrı bir gücü var ve bunlara epey kafa yoruyorum.
Ama bu noktaya gelene kadar çok büyük saçmalıklara da imza attım. Kimsenin yönetemediği kodlar, mimarisi tanımsız işler, yamalı bohçaya dönmüş projeler, güvenlik açıkları... Bir yerini düzelteyim derken başka yerini bozduğum günleri saymıyorum bile. Sonunda bu işin bir standardı olması gerektiğine karar verdim. Var da: rules dosyaları ve skill’ler.
Gelin bu işin ideal kurulumundan neler öğrendiğimi anlatayım.

Ajanınız her sabah işe yeni başlıyor
Kod ajanı çok hızlı, çok bilgili ve hiç itiraz etmiyor. Tek bir kusuru var: her oturumda hafızası sıfırlanıyor. Dün anlattığınız “tarihleri UTC saklarız”, “bu projede ORM yok” gibi şeylerin hiçbirini bugün hatırlamıyor.
Yani elinizde her sabah işe yeni başlayan, çok yetenekli bir stajyer var. Oryantasyon verilmeyen stajyer ne yapar, kurumsal hayattan bilirsiniz: kendi bildiği gibi kod yazar, üç ay sonra o kodu kimse tanımaz. Rules dosyası bu oryantasyon dokümanının ta kendisi.
Bir yıl öncesine kadar her araç kendi dosyasını istiyordu. Bugün AGENTS.md ortak standart oldu. Aralık 2025’te Linux Foundation çatısındaki Agentic AI Foundation’a devredildi. Codex, Cursor, Copilot, Jules, Windsurf ve daha onlarca araç bu dosyayı okuyor. Claude Code kendi CLAUDE.md dosyasını tercih ediyor, ama o yoksa AGENTS.md’yi okuyor.
Peki bu dosyalar gerçekten işe yarıyor mu?
ETH Zürih’ten bir ekip 2026 başında tam olarak bunu ölçtü (Gloaguen ve ark.). Sonuç ilk bakışta pek iç açıcı değil:
- LLM’e yazdırılmış dosyalar başarıyı artırmadı, hafifçe düşürdü.
- Elle yazılanlar ortalama 2,4 puanlık, istatistiksel olarak anlamlı olmayan bir iyileşme sağladı.
- İki durumda da maliyet yüzde 20 civarı arttı.
Thoughtworks da Nisan 2026’da şişmiş talimat dosyalarını, yani “agent instruction bloat”u “dikkat” halkasına koydu. Kural sayısı arttıkça kurallar birbiriyle çelişiyor, ajan da yarısını kaçırıyor.
İlk okuduğumda “Eee, o zaman niye uğraşıyoruz?” dedim. Sonra ölçülen şeye baktım. Bu çalışmalar ajanın bir issue’yu çözüp çözemediğini ölçüyor. Benim derdim o değil. Ajan zaten zeki, issue’yu bir şekilde çözüyor. Benim derdim çözümün bizim yöntemimizle yapılması: bizim hata formatımız, bizim isimlendirmemiz, bizim güvenlik kurallarımız. ETH ekibi de aynı yere varıyor: bu dosyalar ekibe özel, standart dışı pratikleri anlatmakta işe yarıyor.
Ders şu: az yazın ve sadece ajanın kendi başına bilemeyeceğini yazın. Ajan README’yi zaten okuyor, linter’ın düzelttiğini zaten düzeltiyor. Sizin kafanızda olup hiçbir yerde yazmayan kuralları ise bilemez.
İşin ironisi de şu: insanlar bu dosyalara en çok test komutlarını yazıyor, güvenliği ise neredeyse hiç yazmıyor. Oysa Veracode’un testinde güvenlik yönlendirmesi verilmeyen modellerin ürettiği kodun yüzde 45’inde bilinen bir açık çıktı (Veracode). Herkes ajanın zaten bulabileceği şeyleri yazıyor. En çok ihtiyaç duyulanı ise kimse yazmıyor.
Benim kurgum: üç katman
Tek bir AGENTS.md kurumsal dünyada yetmiyor. 40 servis, 6 teknoloji ve 200 yazılımcı olan bir şirkette her ekip “API hata formatımız şudur” diye kendi dosyasına ayrı ayrı yazarsa, altı ay sonra 40 farklı hata formatınız olur.
Ben kuralları üçe ayırıyorum:
- Kurum katmanı: isimlendirme, API standartları, dokümantasyon, loglama, KVKK ve güvenlik. Sahibi mimari ya da platform ekibi. Ayrı bir repoda yaşar ve versiyonlanır.
- Teknoloji katmanı: dil, mimari ve framework kuralları. Örneğin
java-spring,typescript-reactgibi birer paket. Sahibi o teknolojinin chapter’ı. Bu da ayrı repoda, kendi sürümüyle yaşar. - Proje katmanı: build ve test komutları, alan terimleri, “bu modüle dokunma” uyarıları ve standarttan bilinçli sapmalar. Projenin kendi reposunda durur, kodla birlikte review’dan geçer.
siparis-servisi/
├── AGENTS.md # proje katmanı: kısa, sadece bu repoya özel
└── .agents/standards/ # dışarıdan gelir, elle düzenlenmez
├── kurum/ # v3.2.0
└── java-spring/ # v1.4.0
Her katmandan birkaç satır göstereyim. Kurum katmanı, bütün şirketin API’leri için:
# Kurum standardı: API (v3.2.0)
- URL'ler İngilizce, çoğul ve kebab-case: /orders/{id}/line-items
- Hatalar RFC 9457 (problem+json) formatında döner.
- Sayfalama cursor ile yapılır, offset kullanılmaz.
- TC kimlik no, telefon ve e-posta loglara maskelenmeden yazılmaz.
Teknoloji katmanı, bütün Spring Boot servisleri için:
# Java / Spring Boot (v1.4.0)
- Hexagonal mimari: domain/ paketi Spring'e bağımlı olamaz.
- Controller iş kuralı içermez, ilgili use case sınıfını çağırır.
- Testler JUnit 5 ve Testcontainers ile yazılır, veritabanı mock'lanmaz.
- toUpperCase() ve toLowerCase() her zaman Locale.ROOT ile çağrılır.
Proje katmanı, yani reponun kökündeki AGENTS.md:
# Sipariş servisi
Kurallar: .agents/standards/kurum/ ve .agents/standards/java-spring/
- Test: ./gradlew test · Lokal ortam: docker compose up
- legacy/ eski ödeme sistemiyle konuşur, dokunulmaz.
- İstisna: sayfalama offset ile, eski mobil uygulama cursor desteklemiyor.
Gördüğünüz gibi proje dosyası kısa. Diğer iki pakete işaret ediyor, sadece bu projeye özel olanı ve standarttan sapılan yerleri gerekçesiyle yazıyor. Teknoloji kuralları dosya tipine göre kapsamlanabilir. Java kuralları yalnızca .java dosyalarına dokunulduğunda yüklenir, böylece ajanın aklında her an sadece o işle ilgili kurallar durur.
Bunun bir dünya standardı var mı? Bu adla tanımlanmış bir standart yok, ama gidişat bu yönde. Claude Code, Cursor ve Copilot’un hepsi kurum, kullanıcı ve proje katmanlarına ayrıldı. Amazon’un Kiro’su kuralları zaten ürün, teknoloji ve yapı diye üç dosyaya bölüyor. Thoughtworks, paylaşılan kuralların yeni servislerin doğduğu şablon repoda durmasını “adopt” halkasına aldı. Microsoft’un APM’i de kuralları npm gibi paket olarak yönetiyor.
Kurum yeni sürüm çıkarınca ne oluyor? Kuralları bir kütüphane gibi yönetin:
- Her proje belirli bir sürüme sabitlenir.
- Yeni sürüm çıkınca bir bot her projeye pull request açar, ekip review edip alır.
- CI, projedeki kopyanın sabitlenen sürümle aynı olduğunu kontrol eder.
Kural yetmez: skill ve CI
Rules dosyası her zaman doğru olan şeyleri anlatır. Bir de bir işin nasıl yapıldığı var: yeni endpoint ekleme, migration yazma, sürüm notu hazırlama. Bunlar rules dosyasına yazılırsa dosya şişer.
Bunun için skill’ler var. Ajan oturum başında sadece skill’lerin adını ve kısa açıklamasını okuyor. Gövdeyi ancak o iş geldiğinde yüklüyor. 30 skill’iniz olsa bile ajanın aklı bulanmıyor.
Beni en çok yakan kısım ise şu oldu: rules dosyası bir rica, emir değil. Claude Code’un dokümanı da bunu açıkça yazıyor. Benim kuralım şu: rica ettiğiniz şeyi rules dosyasına, mecbur tuttuğunuz şeyi koda yazın. Formatı formatter, isimlendirmeyi linter, sırların koda girmemesini CI kontrol eder. Production veritabanına erişimi ajanın izinlerinden kaldırırsınız, “lütfen dokunma” diye rica etmezsiniz.
Bir uyarı daha: bu dosyalar artık saldırı hedefi. Görünmez Unicode karakterleriyle kural dosyasına talimat gizlenebildiği, ele geçirilmiş bir bağımlılığın projeye zararlı bir AGENTS.md yazabildiği gösterildi. Bu dosyaları CODEOWNERS’a ekleyin ve kimlik doğrulama koduna gösterdiğiniz özenle inceleyin.
Tek standart, her araçta
Bu dosyaların adı ve yeri araçtan araca değişiyor. Hepsini tek tek ezberlemeye gerek yok. Benim yaptığım şu: tek bir standart seçtim ve onu her araçta çalışır hale getirdim.
- Kurallar AGENTS.md’de durur. Codex, Cursor ve Copilot onu zaten okuyor. Claude Code da projede CLAUDE.md yoksa onu okuyor. Claude’a özel bir ek gerekirse CLAUDE.md’nin ilk satırına
@AGENTS.mdyazılır ve ortak dosya içeri alınır. - Skill’ler
.agents/skills/altında toplanır. O klasörü okumayan bir araç varsa, ona oraya giden bir bağlantı vermek yeter. - Mecbur olan her şey CI’da durur. Pull request’te koşan linter ve testler, kodu hangi ajanın yazdığına bakmaz.
Böylece araç değiştirdiğinizde kurallarınız yerinde kalır.
Tek başınıza çalışıyorsanız, kurum ve teknoloji katmanı sizin kişisel standartlarınızdır. Onları ayrı bir git reposunda tutun ve projelerinize oradan bağlayın. Ekipte çalışıyorsanız ayrım şöyle: kişisel olan home dizinine, ortak olan repoya, zorunlu olan koda.
Türkiye’den bir not
Global modeller dünyanın her yerindeki kodu görmüş, ama sizin alışkanlıklarınızı görmemiş. Aynı projede musteriNo, customerAddress ve getSiparisList yan yana yaşıyorsa, ajan üçünü birden çoğaltır. Locale vermeden çağrılan toUpperCase() Türkçe bir makinede “istanbul”u “İSTANBUL”, sunucuda “ISTANBUL” yapar. Dünyanın geri kalanı bu hatayı nadiren yaşadığı için ajan da pek bilmez. TC kimlik numarasının loglara düşmemesi de öyle. Bunlar tam olarak kurum katmanına yazılacak şeyler. Siz yazmazsanız ajan öğrenmez.
Kısa liste
- Kök dosya 200 satırı geçmesin. Uzarsa kurallar dosya tipine göre kapsamlansın, iş tarifleri skill’e taşınsın.
- “Testlere dikkat et” değil, "değişiklikten sonra
npm testçalıştır" diye yazın. - Projeyi anlatmayın, linter’ın yakaladığını tekrar etmeyin.
- İlk taslağı ajana yazdırabilirsiniz ama mutlaka elden geçirin.
- Her dosyanın bir sahibi olsun. Ajan bir hatayı ikinci kez yaptığında kural eklensin, üç ayda bir de dosya budansın.
Ajanınız ekibinizin en hızlı yazılımcısı. Oryantasyonunu vermezseniz, en hızlı yamalı bohça üreten de o olur.