Yapay zekâ ile kod kalitesi: Fabien Sanglard'ın agent.md kuralları

Programcı Fabien Sanglard, 21 Ağustos 2026'da "My agent.md to improve LLM-assisted code quality" başlıklı bir yazı yayımlayarak kodlama araçlarının oturum başında otomatik yüklediği agent.md dosyasını paylaştı.

Başarısız bir denemeden işleyen bir akışa

Sanglard ilk denemesini 2025 ortasında yaptığını hatırlıyor: Rust ile yazılmış bir mDNS uygulaması olan libadbmdns üzerinde çalışıyordu ve üretilen kod derlenmiyordu bile. Ocak 2026'da LLM'lere geri döndü; bu kez model karmaşık bir indeksli ikili yığın sınıfı yazdı ve polling paketinde Windows IOCP uygulamasından kaynaklanan gizli bir hatayı bile tespit etti.

Ancak kod kalitesi berbattı: yorumsuz ve yapısız spagetti kod. Mart 2026'da Antigravity ve VS Code'un Claude Code eklentisi gibi ajan tabanlı IDE'lere geçti; bu, kod üzerinde yinelemeli çalışmayı mümkün kıldı. Kalite çarpıcı biçimde arttı ve elle yazdığına çok yaklaştı, fakat her yeni oturumda aynı önerileri tekrarlamak yorucuydu.

Dosyanın içeriği

agent.md projenin kök dizinine konur; gemini.md veya claude.md ona sembolik bağla bağlanarak kuralların her yerde geçerli olması sağlanabilir. Sanglard'ın kuralları arasında şunlar var: İnsan için üretilen her metinde mümkün olduğunca az kelime kullanmak; övgüden kaçınıp "bana soğuk gerçeği söylemek"; sihirli sayılar yerine açıklayıcı sabitler veya enum kullanmak; girintiyi azaltıp erken return ile ok anti-deseninden kaçınmak; fonksiyon adlarını 30 karakterin altında tutmak; parametrelerde boolean yerine enum kullanmak; mantıksal bloklar arasına boş satır koymak; ne ve neden yaptığını anlatan kısa yorumlar yazmak, gerektiğinde ASCII şemalar eklemek; görünürlük değişikliğini tasarımı bozan bir adım sayıp bir alanı public yapmadan önce onay istemek; soyutlama katmanlarına göre programlamak; ilgisiz bloklara dokunmamak ve değişen satır sayısını en aza indirmek; katman hiyerarşisine saygı gösterip katmanları delmemek; tek satırlık if'lerde bile süslü parantez kullanmak.

Commit mesajları ve testler

Dosya ayrıca commit mesajları için yedi kural içeriyor: Konu satırını gövdeden boş satırla ayırmak; konuyu 50 karakterle sınırlamak (72 kesin üst sınırdır); ilk harfi büyük yazmak; sonuna nokta koymamak; emir kipi kullanmak ve "If applied, this commit will..." cümlesini tamamladığını kontrol etmek; gövdeyi 72 karakterde sarmak; gövdede nasıl değil ne ve neden sorusunu yanıtlamak. Hata düzeltmelerinde ise kural şu: önce testi yaz, başarısız olduğunu gör, sonra düzeltmeyi yap ve testin geçtiğini izle.

Sınırlar: halüsinasyon ve bağlam seyrelmesi

Sanglard bunun sihirli bir değnek olmadığını vurguluyor. Modeller sürekli halüsinasyon görür ve güvenilemez; bu yüzden kodu yine de doğrulamak ve yinelemek gerekiyor — yalnızca artık kod stilinden çok mimariye ve tasarıma odaklanıyor. İkinci sorun, Lost in the Middle makalesinde tanımlanan bağlam ya da dikkat seyrelmesi: Bağlam büyüdükçe model ortadaki talimatlara daha az, baştaki ve sondaki talimatlara daha çok dikkat ediyor.

Etkiyi azaltmak için iki yol buldu: Her özellik için yeni bir oturum açarak bağlamı kısa tutmak ve kalite düştüğünde araçtan açıkça agent.md'yi yeniden yüklemesini istemek — "Reload agent.md" ifadesi yeterli. Yeni bir kural eklemek için editör açması gerekmiyor: ajanın agent.md'yi kendisinin güncellemesini istiyor.