AGENTS.md ve CLAUDE.md: Yapay Zeka Kodlama Ajanları İçin Proje Kural Dosyası Nasıl Yazılır?

Neden gerekli?

Yapay zeka ajanı projenize ilk kez bakan, çok hızlı okuyan ama hafızası oturumla sınırlı bir geliştirici gibidir. Ona her seferinde "testleri php artisan test ile çalıştır, veritabanını sıfırlama, değişken adları Türkçe" demek yerine bunları bir dosyaya yazarsınız. Dosya oturum başında otomatik okunur; siz de ekibiniz de aynı kuralları aynı biçimde aktarmış olur.

Fark somuttur: kural dosyası olmayan projede ajan test komutunu tahmin eder, yanlış dizine dosya açar, projede olmayan bir kütüphaneyi kurmaya çalışır. İyi yazılmış bir dosyayla bu hataların büyük kısmı ilk denemede kaybolur.

Hangi araç hangi dosyayı okur?

Ortak nokta AGENTS.md'dir. Önerimiz: kuralları AGENTS.md'de tutun, CLAUDE.md içine tek satır yazın:

@AGENTS.md

Claude Code bu söz dizimiyle dosyayı içe aktarır. Böylece Claude Code, Codex ve Antigravity aynı kuralları okur, güncelleme tek yerde yapılır.

Dosyanın bölümleri

1. Proje nedir: İki cümle. "robotem.net'in Laravel 13 üzerinde yeniden yazımı; 3D yazıcı ve STEM ürünleri e-ticareti." Sürümler: PHP, framework, veritabanı.
2. Komutlar: Kur, çalıştır, test, lint, derle. Tam komut, tahmin yok.
3. Standartlar: Adlandırma dili, katman kuralları ("Controller ince, mantık Service'te"), biçimlendirici.
4. Yasaklar: Geri alınamaz işlemler. "migrate:fresh çalıştırma", "push yapma", "yeni bağımlılık ekleme, önce sor".
5. Mimari ve tuzaklar: Klasör haritası, "şu guard'ı değiştirme çünkü..." gibi gerekçeli notlar. Gerekçe önemlidir; ajan nedenini bilince benzer durumlara da uygular.
6. Terimler: Alan terimi ile koddaki karşılığı. "Kalem = sipariş satırı = SiparisKalemi".

Örnek şablon

# PROJE ADI

Laravel 13 · PHP 8.4 · MariaDB · Node 24. Konya merkezli bir e-ticaret sitesi.

## Komutlar
- Test: `php artisan test --compact`
- Biçim: `vendor/bin/pint --dirty`
- Statik analiz: `vendor/bin/phpstan`
- Ön yüz: `npm run dev`

## Standartlar
- Sınıf, metot, değişken ve tablo adları Türkçe (`fiyatHesapla`, `siparis_kalemleri`).
- Controller yalnızca doğrulama + servis çağrısı + yanıt. Karar mantığı `app/Services`.
- Her değişiklik testle gelir; test üretimle aynı veritabanı motorunda koşar.

## Yasaklar
- `migrate:fresh`, `db:wipe`, `TRUNCATE` çalıştırılmaz; şema değişikliği yeni migration ile.
- `git push` ve yeni dal açma yalnızca açık istekle.
- Kart verisi (PAN, CVV) hiçbir yere yazılmaz, loglanmaz.

## Tuzaklar
- `User::$guard_name = 'web'` kaldırılmaz: API guard'ında izinler yanlış yerde aranır.
- Önbelleğe model nesnesi yazılmaz; yalnızca id listesi.

## Terimler
| Alan terimi | Kodda |
|---|---|
| Kalem | `SiparisKalemi` |
| Kâr oranı | `kar_orani` (yüzde, ondalık) |

Sık yapılan hatalar

• Genel bilgi yazmak: "Temiz kod yaz, SOLID uygula" satırları yer kaplar, bilgi vermez. Model bunları zaten bilir.
• Çok uzun dosya: Her oturumda okunur; 10 bin kelimelik dosya bağlamı yer ve dikkat dağıtır. Uzun ayrıntıyı ayrı dosyaya alın, gerektiğinde işaret edin.
• Gerekçesiz yasak: "Şunu yapma" yerine "Şunu yapma çünkü üretim verisi silinir" yazın; ajan benzer riskleri de tanır.
• Güncellenmeyen dosya: Komut değişti, dosya kaldı. Ajanın yaptığı her tekrar eden hata dosyaya bir satır olarak girsin.
• Kopya dosyalar: CLAUDE.md ve AGENTS.md'de aynı metnin iki kopyası zamanla ayrışır. Birini diğerine işaret ettirin.

Kural yetmez: test ve kanca

Kural dosyası ajana söyler; uyma oranı yüksektir ama yüzde yüz değildir. Pazarlıksız kurallar için iki araç daha var:

• Mimari test: "Controller'da sorgu yazılmaz" kuralını, controller sınıflarını tarayıp DB:: çağrısı bulan bir testle koruyun. Ajan kuralı delerse test kırmızı yanar.
• Kanca (hook): Claude Code'da PreToolUse kancası tehlikeli komutu çalışmadan engeller. Ayrıntı ileri seviye yazısında.

İyi tarif edilmiş görev ile iyi kural dosyası birlikte çalışır; görev tarafı için kodlama ajanları için prompt yazma rehberine bakın.