Kodlama Ajanlarınız İçin Markdown Dosyaları Yazmayın, Betikler Yazın

Yapay zeka destekli kodlama ajanlarının (coding agents) tam olarak istediğiniz şeyi yapmasını istiyorsanız, onları deterministik (kesin sonuçlu) eylemler içine nasıl hapsedeceğinizi öğrenmeniz gerekir. Ne yazık ki mevcut kodlama ajanları bu konuda doğal olarak başarılı değildir; çünkü keşfetmeye ve açık uçlu çalışmaya göre tasarlanmışlardır. Belirsiz bir istem (prompt) alır, makul bir yama üretir, testleri çalıştırır ve birkaç döngü boyunca bunu tekrarlarlar.

Bu yaklaşım prototip oluşturma ve sıfırdan geliştirilen (greenfield) projeler için harikadır. Ancak güvenilirliğe ihtiyaç duyduğunuzda —aynı komutun her seferinde aynı etkiyi yaratmasını, aynı kod yeniden yapılandırmasının (refactoring) yirmi dosyaya eksiksiz uygulanmasını veya aynı dağıtım (deploy) sürecinin aynı sırayla çalışmasını istediğinizde— belirsiz istemler ve "lütfen dokümanları oku" yaklaşımı birer yüke dönüşür.

Markdown Belgeleri Kısıtlama Değil, Tavsiyedir#

Sürekli yeni kurallar ekleyerek ajanınıza okuması için onlarca .md dosyası (CONTRIBUTING.md, AGENTS.md, CLAUDE.md, stil rehberleri) bıraktığınızda yanlış yerde durmuş olursunuz. Markdown belgeleri birer kısıtlama değil, yalnızca tavsiyedir. Ajanlar bu belgeleri okuyup özetleyebilir ve "Dokümanları okudum, uymak için elimden geleni yapacağım" diyebilir. Ancak metin tabanlı kurallar, ayrıştırılması ve yorumlanması gereken belirsiz alanlar yaratır:

• "Depodaki mevcut loglama standartlarını kullan." — Hangisini ve nerede?
• "Küçük fonksiyonlar yaz." — Ne kadar küçük?
• "Kod göndermeden önce testleri çalıştır." — Hangi testleri, hangi komutla ve hangi ortamda?

Ajan tüm bunları işlemek, birbiriyle çelişen yönergeleri dengelemek ve muhakeme (yargı) yürütmek zorunda kalır. Ajanların yoldan çıktığı yer tam olarak bu muhakeme aşamasıdır. Örneğin dokümanda snake_case yazarken mevcut bir dosyada camelCase gören ajan, "Belki doküman eskidir" diyerek kendi inisiyatifini kullanmaya çalışır. Yardımcı olmaya çalışırken deterministik olmaktan uzaklaşır.

Tercihleri Deterministik Eylemlere Dönüştürmek#

Muhakeme gerektirmeyen deterministik eylemler, tasarım paradigmasını "ajana ne tercih ettiğinizi öğretmekten", "tercihlerinizi çalıştırılabilir eylemlere dönüştürmeye" taşır. Bir Markdown belgesini çalıştıramazsınız; ancak bir betiği (script), bir Makefile hedefini veya bir GitHub Action iş akışını çalıştırabilirsiniz:

• "Dokümanları oku ve kod stiline uy" ifadesi, ./scripts/lint.sh, ./scripts/format.sh ve ./scripts/test.sh betiklerini çalıştırmaya dönüşür. Ajan bunları çalıştırır ve net bir başarılı/başarısız sonucu alır. Hata varsa tahmin yürütmek yerine doğrudan hatayı görür.
• "Refactoring yap" ifadesi, dönüşümü uygulamak için ast-grep, jscodeshift veya sed aracını çalıştırmaya dönüşür. Hangi dosyaların güncelleneceğine ajan değil, tasarım gereği betiğin kendisi karar verir.
• Makefile hedefleri kullanmak (make setup, make lint, make test, make build), ajanın kodlama felsefenizi anlaması gerekliliğini ortadan kaldırır; yalnızca make lint komutunu çalıştırıp sonuca göre aksiyon alması yeterlidir.

Yazılım Geliştirme ve Öğrenme İçin Pratik Çıkarımlar#

Buradaki temel amaç ajanı aptallaştırmak değil, çalışma ortamını belirsizlikten arındırmaktır. Ajan, deterministik eylemler kümesini yürütürken yine zekasını kullanabilir; hataları okuyup düzeltmeler yapabilir ve testleri yeniden çalıştırabilir. Sadece çizilen kutunun dışına çıkamaz.

• Kural yazmak yerine araç yazın: Yeni bir .md kuralı eklemeden önce "Bunu bir linter kuralı veya bash betiği olarak nasıl otomatikleştirebilirim?" sorusunu sorun.
• Geri bildirim döngüsünü ikili (pass/fail) hale getirin: Ajanların ve geliştiricilerin en hızlı öğrendiği ve en güvenilir çalıştığı ortam, yoruma kapalı hata mesajları üreten otomatik doğrulama adımlarıdır.
• Ajanın kendi betiklerini değiştirmesine dikkat edin: Topluluk yorumlarının da uyardığı gibi, ajanların sınırları belirleyen bu betikleri kendi başlarına esnetmesine veya değiştirmesine izin vermeyin.