AI Destekli Yazılım Geliştirmede En Önemli Dosya

AI Kodlama Ajanlarını Daha Güvenilir Hale Getiren Küçük Dosya

Meta Description:
Claude Code, Codex ve Cursor gibi AI kodlama ajanları, proje içinde net kurallar aldıklarında çok daha faydalı hale gelir. CLAUDE.md ve AGENTS.md gibi kısa talimat dosyalarının yapay zekâ destekli yazılım geliştirmeyi nasıl iyileştirdiğini keşfedin.

Giriş

AI kodlama ajanları ilk bakışta oldukça etkileyici görünebilir. Demo ortamlarında kod yazarlar, bileşenler oluştururlar, hataları açıklarlar ve birkaç dakika içinde tamamlanmış gibi görünen çözümler sunarlar. Ancak gerçek yazılım projeleri kontrollü demolardan çok farklıdır.

Olgunlaşmış kod tabanlarında eski mimari kararlar, gizli iş kuralları, legacy davranışlar, tamamlanmamış migration’lar, testlerin içinde saklı kalan bilgiler ve gereksiz gibi görünen ama üretim ortamında kritik davranışları koruyan dosyalar bulunur.

AI kodlama ajanlarıyla yaşanan birçok problem tam da burada başlar. Bunun nedeni onların geçerli kod yazamaması değildir. Asıl sorun, çoğu zaman fazla hızlı hareket etmeleridir. Bağlamı anlamadan dosya düzenlerler, gereğinden fazla refactoring yaparlar, gereksiz abstraction’lar eklerler veya kod sadece mantıklı göründüğü için görevin bittiğini söylerler.

Küçük bir talimat dosyası bu davranışı ciddi şekilde iyileştirebilir.

CLAUDE.md veya AGENTS.md Dosyası Nedir?

CLAUDE.md, Claude Code için kalıcı proje talimatları içeren bir Markdown dosyasıdır. OpenAI Codex de benzer bir yaklaşımı AGENTS.md dosyasıyla kullanır. Cursor ve diğer AI destekli geliştirme araçları da buna benzer proje kurallarını destekler.

Burada önemli olan dosyanın adı değil, arkasındaki fikirdir.

Bu dosya yalnızca tek bir görev için yazılmış bir prompt değildir. Daha çok kodlama ajanı için küçük bir çalışma kılavuzu gibidir. Sadece neyin yapılacağını değil, ajanın proje içinde nasıl çalışması gerektiğini de açıklar.

İyi bir talimat dosyası şunları belirleyebilir:

• ajanın kod tabanını değişiklik yapmadan önce nasıl incelemesi gerektiğini;

• hangi mimari sınırların korunması gerektiğini;

• değişikliklerden sonra hangi testlerin veya komutların çalıştırılması gerektiğini;

• ajanın ne zaman devam etmeden önce soru sorması gerektiğini;

• ekip için “tamamlandı” ifadesinin ne anlama geldiğini;

• hangi dosyaların veya davranışların onay olmadan değiştirilmemesi gerektiğini.

Bu sayede ajan yalnızca daha hızlı değil, aynı zamanda daha öngörülebilir, daha kontrollü ve daha kolay incelenebilir hale gelir.

Asıl Problem: AI Ajanları Çoğu Zaman Fazla Acelecidir

Birçok geliştirici AI kodlama ajanlarına şu tarz görevler verir:

“Bu endpoint’i ekle.”
“Bu validasyon hatasını düzelt.”
“Bu sorguyu optimize et.”
“Bu özelliği geliştir.”

Sonuç faydalı olabilir, ancak her zaman güvenli değildir. Çünkü çoğu prompt yalnızca istenen sonucu anlatır. Beklenen çalışma sürecini anlatmaz.

Deneyimli bir geliştirici genellikle önce mevcut akışı inceler, ilgili testleri okur, edge case’leri anlamaya çalışır ve ardından hedefli bir değişiklik yapar. AI ajanı ise çoğu zaman olası bir çözüm üretir ve hemen uygulamaya başlar.

Gerçek projelerde bu ciddi problemlere yol açabilir. Bir ajan:

• tek bir hedefli değişiklik yeterliyken beş dosyayı değiştirebilir;

• projede zaten kullanılan bir pattern’i daha modern ama gereksiz bir pattern ile değiştirebilir;

• framework zaten çözüm sunuyorken yeni bir dependency ekleyebilir;

• görevle ilgisi olmayan yakın kodları refactor edebilir;

• doğru testleri çalıştırmayabilir;

• belirsizliği kendinden emin bir özetin arkasına saklayabilir.

Kodlama ajanları daha otonom hale geldikçe, net çalışma kuralları daha da önemli hale gelir.

Kısa Kurallar Neden Uzun Prompt’lardan Daha İyi Çalışır?

Birçok ekip AI ajanlarını çok uzun prompt’larla kontrol etmeye çalışır. İlk bakışta bu mantıklı görünebilir, ancak çoğu zaman yeni problemler oluşturur. Uzun prompt’lar ürün gereksinimlerini, kod stilini, mimari geçmişi, örnekleri, istisnaları ve kişisel tercihleri birbirine karıştırır.

Bu durumda ajan her adımda hangi talimatın daha önemli olduğuna karar vermek zorunda kalır. Bu da yeniden belirsizlik oluşturur.

Kısa ve somut kurallar genellikle daha iyi çalışır.

Şunun yerine:

Kaliteli kod yaz.

Bunu yazın:

Önce etkilenen dosyaları ve testleri oku. Sonra kodu değiştirmeden önce muhtemel kök nedeni kısaca açıkla.

Şunun yerine:

Overengineering yapma.

Bunu yazın:

Mevcut yapı gereksinimi temiz şekilde çözebiliyorsa yeni bir abstraction ekleme.

Şunun yerine:

Çalışmanı test et.

Bunu yazın:

Önce değişiklikle en yakından ilgili testi çalıştır ve neyin doğrulanamadığını açıkça belirt.

İyi kurallar kısa, tekrar kullanılabilir ve doğrulanabilir olmalıdır.

Kural 1: Kod Yazmadan Önce Anla

Bir AI ajanı hemen dosya düzenlemeye başlamamalıdır. Önce problemin nerede oluştuğunu ve uygulamanın hangi bölümlerinin etkilendiğini anlamalıdır.

Bir backend hatası için bu şu adımları içerebilir:

• route kontrolü;

• middleware kontrolü;

• controller incelemesi;

• service veya action mantığının anlaşılması;

• model logic incelemesi;

• migration veya database constraint kontrolü;

• mevcut testlerin okunması;

• beklenen response formatının anlaşılması.

Ajan ancak bundan sonra kısa bir uygulama planı yazmalıdır.

Faydalı bir kural şu olabilir:

Kodu değiştirmeden önce muhtemel nedeni açıkla, etkilenen dosyaları belirt ve değişikliğin nasıl doğrulanacağını tarif et.

Bu kural, yanlış varsayımların koda dönüşmeden önce azaltılmasını sağlar.

Kural 2: Basit Çözümleri Tercih Et

AI modelleri birçok modern yazılım pattern’ini bilir: factories, interfaces, events, listeners, repositories, pipelines, services ve configuration katmanları. Bu bilgi faydalıdır, ancak yanlış yerde kullanıldığında riskli olabilir.

Her küçük değişiklik yeni bir mimari gerektirmez.

Laravel’de mevcut bir validation rule problemi çözüyorsa, ajanın özel bir validation framework oluşturmasına gerek yoktur. Projede zaten kullanılan bir service varsa, paralel yeni bir service oluşturulmamalıdır. Kritik bir kuralı korumak için en doğru yer database constraint ise, bu genellikle yalnızca uygulama seviyesinde yapılan kontrolden daha güvenlidir.

Basit çözüm zayıf veya özensiz çözüm demek değildir. Basit çözüm, mevcut gereksinimi en az gerekli karmaşıklıkla karşılayan ve mevcut kod tabanına uyum sağlayan çözümdür.

İyi bir kural şu olabilir:

Mevcut gereksinimi karşılayan ve projenin mevcut pattern’lerine uyan en basit çözümü seç.

Kural 3: Cerrahi Değişiklikler Yap

AI tarafından üretilen iyi bir değişiklik her zaman en kısa değişiklik olmak zorunda değildir. Ancak odaklı olmalıdır.

Cerrahi değişiklik, görevi çözmek için tam olarak gerekli olan şeyleri değiştirir. Daha fazlasını değil.

Bu yine de birden fazla dosya gerektirebilir. Doğru bir çözüm migration, validation, test ve dokümantasyon içerebilir. Önemli olan her değiştirilen satırın açık bir nedeni olmasıdır.

Ajan şunlardan kaçınmalıdır:

• gereksiz formatting değişiklikleri;

• ilgisiz kodları refactor etmek;

• onay olmadan public API değiştirmek;

• işlevsel değeri olmayan isim değişiklikleri yapmak;

• yalnızca kullanılmıyor gibi görünen kodları silmek;

• paralel mimari yollar oluşturmak.

Ajan ayrı bir problem keşfederse, bunu raporlamalıdır. Görevin kapsamını sessizce genişletmemelidir.

Güçlü bir kural şu olabilir:

Problemi doğru şekilde çözen en küçük tutarlı diff’i oluştur. Açıkça istenmedikçe ilgisiz kodları refactor etme.

Kural 4: Doğrulamadan “Tamamlandı” Deme

Derlenen kod otomatik olarak doğru değildir. Mantıklı görünen kod da otomatik olarak production-ready değildir.

Her değişiklikten sonra ajan neyin doğrulandığını göstermelidir.

Projeye göre bu şunları içerebilir:

• değişiklikle en yakından ilgili unit veya feature test;

• etkilenen test suite;

• static analysis;

• linting;

• formatting;

• final diff review;

• doğrulanamayan noktalar hakkında açık açıklama.

Dürüst bir özet, eksik ama kendinden emin bir başarı mesajından çok daha faydalıdır.

Örneğin:

Duplicate subscription kontrolü için feature test başarılı. Tüm test suite çalıştırılmadı. Redis ile ilgili queue job’lar lokal ortamda doğrulanamadı.

Bu ifade şundan çok daha değerlidir:

Done, everything works.

Laravel Projesinden Bir Örnek

Bir ekibin duplicate subscription kayıtlarını engellemek istediğini düşünelim.

Fazla aceleci bir ajan service yapısını yeniden düzenleyebilir, repository layer ekleyebilir ve duplicate kontrolünü uygulama seviyesinde bir query ile yapabilir. Bu ilk bakışta doğru görünebilir, ancak eş zamanlı request’lerde yine de başarısız olabilir.

Daha iyi yönlendirilmiş bir ajan önce migration’ları, model’i, service’i, controller’ı ve testleri okur. Ardından bu kuralı güvenilir biçimde uygulamak için doğru sınırın veritabanı olduğunu fark eder.

Daha iyi bir çözüm muhtemelen şunları içerir:

• composite unique index eklemek;

• database hatasını mevcut validation response formatına çevirmek;

• mevcut service yapısını korumak;

• duplicate subscription için feature test eklemek;

• gereksiz mimari değişikliklerden kaçınmak.

Laravel projelerinde şu kurallar özellikle faydalıdır:

• HTTP validation için Form Request kullanmak;

• mevcut Service ve Resource pattern’lerini korumak;

• loop içinde query çalıştırmaktan kaçınmak;

• kritik invariants için database constraints kullanmak;

• production’a çıkmış migration’ları değiştirmemek, bunun yerine yeni migration oluşturmak;

• onay olmadan yeni dependency eklememek;

• mevcut response formatlarını korumak.

Ekipler Gerçek Projelerde Talimat Dosyalarını Nasıl Kullanmalı?

En iyi başlangıç devasa bir politika dokümanı yazmak değildir. Daha doğru yaklaşım, gerçek code review yorumlarından ve AI ajanlarının tekrarlayan hatalarından oluşan on ila yirmi net kural ile başlamaktır.

Ekip sürekli “generated files düzenleme” diyorsa, bu kural talimat dosyasına eklenmelidir.

Her prompt aynı test komutunu tekrar ediyorsa, bu komut dosyada belgelenmelidir.

Belirli bir mimari pattern her zaman korunmalıysa, bu açık şekilde yazılmalıdır.

Bu dosya kod gibi bakıma alınmalıdır. Eski kurallar silinmeli, çelişkiler düzeltilmeli ve belirsiz talimatlar somut komutlara dönüştürülmelidir.

Talimat dosyası gerçek güvenlik önlemlerinin yerine geçmez. Katı bir güvenlik sınırı değildir. Branch protection, CI, code review, permissions, tests ve hooks hâlâ gereklidir.

Kısa Bir AGENTS.md veya CLAUDE.md Örneği

# AI Coding Agent Instructions

## Before changing code
- Read the relevant files and understand the existing flow.
- Check existing tests before implementing a solution.
- State the likely root cause and a short implementation plan.
- Ask before adding dependencies or changing public behavior.

## While changing code
- Prefer the simplest solution that satisfies the requirement.
- Make the smallest coherent diff.
- Preserve existing conventions, APIs, naming, and response formats.
- Do not refactor unrelated code.
- Do not edit generated files unless explicitly requested.

## Verification
- Run the narrowest relevant test first.
- Run the broader affected suite when practical.
- Run formatting, linting, or static analysis required by the repository.
- Review the final diff for accidental changes.
- Report what changed, what was verified, and what remains uncertain.

Bu dosya özellikle kısa tutulmuştur. Her teknik kararın yerine geçmek için değil, ajana bu repository içinde profesyonel bir geliştirici gibi nasıl çalışması gerektiğini hatırlatmak için vardır.

Sonuç

CLAUDE.md, AGENTS.md ve benzeri proje kurallarının arkasındaki en önemli ders basittir: AI destekli yazılım geliştirme yalnızca modelin gücüne değil, sürece de bağlıdır.

Güçlü bir model, belirsiz bir görevle etkileyici ama riskli kod üretebilir. Aynı model, net çalışma kurallarıyla küçük, incelenebilir ve sürdürülebilir bir mühendislik değişikliği üretmeye daha yatkındır.

Ekipler AI kodlama ajanlarını çok hızlı junior geliştiriciler gibi düşünmelidir. Geniş teknik bilgiye sahiptirler, ancak projenin yerel bağlamı konusunda eksik muhakemeye sahip olabilirler.

Çok şey yapabilirler, ancak proje kurallarına, net sınırlara ve güvenilir doğrulamaya ihtiyaç duyarlar.

AI destekli yazılım geliştirmenin geleceği en uzun prompt’u yazanlara değil, iyi mühendislik muhakemesini kısa, kalıcı ve doğrulanabilir kurallara dönüştürebilen ekiplere ait olacaktır.

Kaynaklar ve Ek Okumalar

• multica-ai/andrej-karpathy-skills GitHub deposu

• Claude Code: Project Instructions and CLAUDE.md

• OpenAI Codex: Custom Instructions with AGENTS.md