Agentic Engineering Patterns

• Claude Code ve Codex gibi kodlama ajanları çağındaki geliştirme yaklaşımını derleyen bir rehber; ajanlarla işbirliği yapmaya yönelik yeni mühendislik kalıpları sunuyor
• Kod yazma maliyetinin keskin biçimde düştüğü bir ortamda geliştirme alışkanlıkları ve iş akışlarının nasıl değişmesi gerektiğini çeşitli kalıplarla açıklıyor
• İlkeler, test, kodu anlama, prompt tasarımı gibi ajan merkezli geliştirmenin temel alanlarını yapısal olarak düzenliyor
• Her kalıp; gerçek kod örnekleri, çalışma biçimleri ve prompt kullanım örneklerini içeren pratik odaklı kalıp belgeleri biçiminde sunuluyor
• Kodlama ajanları çağında geliştiricilerin ajan tabanlı kodlama ortamını sistemli biçimde tasarlayıp kaliteyi koruması için somut bir başvuru kaynağı

---

Agentic Engineering Patterns genel bakış

• Kodlama ajanlarıyla (Claude Code, OpenAI Codex vb.) birlikte geliştirme yaparken etkili mühendislik yöntemlerini derleyen bir rehber
• Writing about Agentic Engineering Patterns tanıtım yazısına bakın
  • Klasik “Design Patterns” formatı gibi, zaman içinde birden fazla kalıbın (chapter) eklendiği bir belge yapısı
  • Kod yazma maliyetinin büyük ölçüde düştüğü ortamda geliştiricinin iş akışı ve karar verme biçimindeki değişimi ana tema olarak ele alıyor
  • Blog yazısı değil, güncellenebilir bir rehber formatında içerik olarak yürütülüyor ve zamanla genişletilmesi planlanıyor

1. İlkeler

• Writing code is cheap now

  • Yapay zeka kodlama ajanlarının ortaya çıkışıyla ilk kod yazma maliyeti neredeyse sıfıra yakın seviyeye indi
  • Geçmişte kod yazmak pahalı olduğu için geliştirme tasarım ve planlama merkezliydi; artık fikri doğrudan kodla deneme yaklaşımı mümkün
  • Kod üretim maliyeti düşse de iyi kodun (test, bakım yapılabilirlik vb.) hâlâ bir maliyeti var

• Hoard things you know how to do

  • Geliştiricinin önemli varlıklarından biri, “nelerin mümkün olduğunu bilme bilgisinin birikimi”
  • Farklı problem çözme örneklerini ve küçük kod deneylerini saklanıp yeniden kullanılabilecek şekilde biriktirme alışkanlığını vurguluyor
  • Bu şekilde biriken kod ve örnekler, kodlama ajanına yeni özellikler geliştirmesini söylerken güçlü bir girdi materyali olarak kullanılabiliyor

• Anti-patterns: things to avoid

  • Ajanın ürettiği kod olsa bile inceleme yapmadan paylaşmak veya PR göndermek kaçınılması gereken bir anti-pattern
  • Ajanın yazdığı PR açıklamalarının da insan tarafından doğrudan doğrulanıp düzeltilmesi gerekiyor
  • Kod inceleyicisinin zamanını boşa harcamamak için testler, doğrulama süreci ve uygulama tercihinin gerekçeleri birlikte sunulmalı

2. Testing and QA

• Red/green TDD

  • Test güdümlü geliştirme (TDD), kodlama ajanlarıyla birlikte kullanıldığında özellikle etkili bir geliştirme kalıbı
  • Testler önce yazıldığında ajan, testleri karşılayacak yönde kod üretebilir
  • En az düzeyde prompt ile bile doğru ve güvenilir kod üretimine yardımcı olur

• First run the tests

  • Kodlama ajanlarıyla çalışırken otomatik testler bir seçenek değil, zorunlu bir unsur
  • Test yazma maliyetinin düştüğü ortamda ajan testleri hızlıca üretebilir ve düzeltebilir
  • Kod gerçekten çalıştırılana kadar çalışıp çalışmadığı garanti edilemeyeceği için testler kritik önem taşır

3. Kodu anlama

• Linear walkthroughs

  • Ajanın oluşturduğu kodu veya projeyi baştan sona sırayla okuyarak yapıyı anlama kalıbı
  • Basit bir projede bile kod akışını takip ederek yeni teknikleri ve yapıları öğrenmek mümkün
  • Yapay zeka ile kod üretiminin öğrenme hızını düşürdüğü endişesine karşı, kod keşfinin kendisi bir öğrenme fırsatı olabilir

• Interactive explanations

  • Kod veya sistemi anlamak için ajanla konuşarak açıklama isteme yöntemi
  • Soruları yineleyerek kodun çalışma prensibini ve yapısını kademeli olarak kavrama
  • Kod anlama sürecini etkileşimli öğrenme yaklaşımına genişleten bir kalıp

4. Açıklamalı promptlar

• GIF optimization tool using WebAssembly and Gifsicle

  • WebAssembly ve Gifsicle tabanlı bir GIF optimizasyon aracı oluşturmaya yönelik prompt örneği içeriyor
  • HTML, JavaScript, CSS içeren tek sayfalık araç uygulama yaklaşımını sunuyor
  • Gerçek prompt ve kod örnekleri üzerinden kodlama ajanlarının nasıl kullanılacağını açıklıyor

5. Ek

• Prompts I use

  • Gerçekte kullanılan kodlama ajanı prompt örneklerinden oluşan bir derleme
  • Farklı işlerde kullanılabilen pratik prompt kalıplarını düzenliyor
  • Ajanla işbirliği yaparken kullanılabilecek uygulanabilir şablonlar sunuyor

[GN⁺]

Hacker News görüşleri

• Yine aynı şeyi tekrarlamaya çalışıyor gibiyiz
  "Önce testi yaz", "küçük ve birleştirilebilir modüller kur" gibi basit ve makul fikirleri karmaşık isimlerle paketleyip bunun üzerinden bir danışmanlık sektörü çıkaracak gibiyiz
  Ama bu kez hedef "konuşan makineler". Sadece konuşarak komut verilebildiği bir dünyadayız

  • COBOL da benzer bir vaatte bulunmuştu. İnsanların kolay okuyabildiği bir dil olduğu için programcılara gerek kalmayacağı söylenmişti, ama sonunda problemleri parçalara ayırıp çözmek için insanların yine programcı gibi düşünmesi gerekti. Yani dil insan dostu diye programcılar ortadan kalkmıyor
  • Bu kez de AI patlaması döngüsü tekrarlanacak gibi görünüyor. Şu an eleştirince "anlamıyorsun" tepkisi geliyor, ama yakında sorunlar patlak verecek. Özellikle de "AI'ın o kadar çok kod üretmesi ki ne insanların ne de AI'ın bunu yönetememesi" gibi bir durum ortaya çıkacak. O noktada yine pattern ve anti-patternlar, bir de bunları çözdüğünü söyleyen danışmanlar çıkacak
  • AI İngilizce konuşup anladığı için arayüz netliği düşüyor. CLI kadar güçlü ama hangi yaklaşımın etkili olduğu belirsiz. Bu yüzden "neyi nasıl istemek iyi sonuç veriyor" bilgisini belgeleyip paylaşmak önemli. Yalnız bunun tekrar bir OOP koçluk sektörüne dönüşmesine izin vermemek gerek
  • Evet. Yine öyle olacak ve bu kez çok daha hızlı ilerleyecek. Blog yazarı → konuşmacı → kitap → danışman → sertifikasyon kurumu şeklindeki 10 yıllık döngü birkaç yıla sıkışacak
  • Yazı başlığının karmaşık olduğu eleştirisine katılmıyorum. Ama sorun "sadece konuşarak yaptırmak yeter" yanılgısı. Gerçekte insanlar arasında sonuçlar çok değişiyor. Sonunda ortaya çıkan ders şu: "İnsan için iyi olan geliştirme alışkanlıkları AI için de iyidir." AI insana benziyor ama insan değil. Bu yüzden daha fazla açıklama gerekiyor

• Simon'a şunu sormak isterim — "Kodun ucuzladığı bir dünyada" code review nasıl yapılmalı?
  Ekiptekiler yapıyı anlamadan "çalışıyor ya, yeter" diye yaklaşıyor. Review'lar giderek büyüyor ve ben darboğaz haline geliyorum. Vekil olarak AI reviewer kullanma fikrini de düşündüm ama işin insani tarafının kaybolmasını istemiyorum

  • Gerçekten ilginç bir konu. Kod üretim hızı artınca review darboğaz haline geliyor. Kod ucuzsa review çıtasını düşürmek mümkün olabilir ama ben tersine daha iyi kalite isterim. Özellikle güvenlik incelemesi asla atlanamaz. Büyük organizasyonlardaki güvenlik ekipleri gibi sistematik bir yaklaşım gerekebilir
  • Ajan tabanlı review kullanacaksan bağlamı kurmak çok önemli. Plan → uygulama → test/düzeltme → review/refactor → QA rehberi üretimi döngüsünü kurarsan, sadece kod değil dokümantasyon ve test yönergeleri de birlikte evrilir
  • "Çalışıyor ya, yeter" teknik bir sorun değil, organizasyon kültürü sorunu. Bazı şirketler hâlâ okunabilir kodu önemser. Bu da rekabet avantajı olabilir
  • Ben statik ve dinamik analiz otomasyonuna yatırım yapıyorum. Özel lint kuralları, güçlü tip denetimi, mutation testing gibi kalite araçlarını aktif kullanıyorum. Sadece review yavaş ve verimsiz olduğu için asıl mesele erken geri bildirim otomasyonu
  • Bu tutum kolay kolay değişmez. Belki de yazılım kalitesine önem veren bir takıma geçmek daha iyi olabilir

• Ben AI'ı daha çok boilerplate kod ya da dokümantasyon sorunlarını çözmek için kullanıyorum
  Ajan tarzı işleri de denedim ama çıkan sonuçlara hâlâ güvenmek zor. Buna rağmen bazı insanlar "artık neredeyse hiç kod yazmıyorum" diyor. Aradaki fark ilginç

  • Benim için çoğu zaman doğrudan kod yazmak AI'dan daha hızlı. Plan yapma, çalıştırma ve doğrulama süreci bazen daha yavaş kalıyor. Ama büyük çaplı refactor işlerinde AI çok daha hızlı
  • Son birkaç ayda ajan performansı ciddi biçimde yükseldi. Artık basit otomatik tamamlama düzeyini aşıp tam özellik geliştirme yapabiliyor
  • Bunu, AI koduna bakınca "bu AI tarafından yazılmış" hissi veren bir yabancılık (eww) duyan geliştiricilerle duymayanlar arasındaki farkla açıklamak mümkün olabilir
  • Sonuçta AI'ın uygun olup olmaması işin türüne göre çok net biçimde ayrışıyor
  • Ben de ilk çıktıyı genelde beğenmiyorum ama review döngüsünü birkaç kez çalıştırınca kalite belirgin biçimde artıyor. AI'lara birbirlerinin işini review ettirmek ya da test kriterlerini netleştirmek ciddi fayda sağlıyor

• Son dönemde ajan tabanlı coding loop deniyorum
  Örneğin fesh projesinde hedefim "Linux binary'lerini daha küçük sıkıştırmak" oldu. Testi net olan bir problem olduğu için AI döngüsüne uygundu
  Çıkardığım dersler şunlar:

  • Her şey test harness ile ilgili. Doğrulama döngüsü yoksa yön kayıyor
  • AI'ın deneysel denemeler yapmasına izin vermek önemli
  • Oturumlar arasında .md scratchpad bırakmak, öğrenmenin devam etmesini sağlıyor
  • Test gerçekten çok önemli. AI tuhaf şekillerde başarısız olduğu için otomatik test üretimini agresif biçimde kullanmak gerekiyor
  • Test olmadan döngünün sonucuna güvenilemez. Deterministik doğrulama süreci şart
  • Karar günlüğü ile ret günlüğünü ayrı tutmak faydalı oldu. Özellikle rejections.md daha değerliydi. "Bu yaklaşım neden terk edildi?" bilgisini bırakmak, AI'ın aynı hatayı tekrar etmesini engelliyor
  • Tarayıcı otomasyonunda da benzer durum var. Sadece işlevsel doğrulama değil, davranışsal doğrulama (insan gibi görünüyor mu) da eklenince faydalı oluyor. Ayrıca .md log'ları sonraki oturumun kalitesini ciddi biçimde artırıyor

• Test bölümünde LLM'in ürettiği "kendini doğrulayan testler" sorununa değinilmesini isterdim
  Bazen testler gerçekte hiçbir şeyi doğrulamıyor, hatta hardcoded değerlerle geçiyor. AI'ı katı test alışkanlıklarına yönlendirmek insanın görevi

  • Somut örnekleri merak ettim. Basit mantık hatalarından değil, dışarıdan bakınca makul görünen ama gerçekte anlamsız testlerden söz ediliyor gibi
  • Kötü test, hiç test olmamasından daha tehlikelidir. Güven bir kez kırılınca tüm test suite'ine olan inanç sarsılıyor
  • Bu yüzden mutation testing önemli. Kod değiştirilse bile test geçiyorsa o kötü bir testtir
  • AI'dan kodun bir kısmını kasıtlı olarak değiştirmesini isteyip testin fail olup olmadığına bakabilirsin. Fail olmuyorsa işe yaramayan bir testtir
  • Elbette bunu insanlara da yazdırmamak kolay değil

• Her yeni LLM nesli geldiğinde önceki derslerin tamamı geçersizleşiyormuş gibi hissettiriyor
  LangChain gibi, eski modellerin sınırlarını aşmak için kurulmuş karmaşık yapılar GPT-3.5 sonrasında gereksiz hale geldi. Yakında tek bir ajan bile her şeyi yapmaya yeterli olabilir

  • Bu yüzden ben model sürümüne bağımlı olmayan patternları toplamaya çalışıyorum. Mesela red/green TDD'yi yakında model kendi başına yapabilir ama kavramın kendisi yine de değerli kalır
  • Sonunda her şey ClaudeVM benzeri bir yapıya yakınsayabilir
    İlgili yazı

• Ajan mühendisliği tartışmalarında sık sık eksik kalan bir nokta var
  Derslerin çoğu evrensel doğrularmış gibi anlatılıyor, ama gerçekte bunlar ekip boyutuna, codebase olgunluğuna, test düzeyine ve risk toleransına göre değişiyor. Asıl önemli olan, "bu pattern hangi durumda işe yarar" sorusunu netleştirmek

  • Bu yüzden ben kitap değil, pattern'ları web sitesi formatında topluyorum. Sürekli güncelleyip geçerli oldukları kapsamı da belirteceğim
  • Danışman olarak farklı codebase'lerle çalışınca şunu görüyorsun: Claude Code'un performansı codebase kalitesine göre aşırı değişiyor. Güçlü tipler ve testler olan projelerde neredeyse kusursuz çalışırken, gevşek JavaScript ortamlarında pek iyi değil
  • Yine de bazı pattern'lar evrensel. Örneğin bağımsız bir source of truth (harness) bulundurmak her yerde geçerli. showboat, rodney gibi araçlar da buna yardımcı oluyor

• Son zamanlarda her gün onlarca ajan ekip framework'ü ortaya çıkıyor
  Tıpkı yazılım mühendisliğinin ilk dönemleri gibi kaotik bir deney aşamasındayız. Ama sonuçta birkaç pattern standart hale gelecek.
  Bizim ekipte insan takımı gibi yaklaşmak işe yaradı — önce ürün spesifikasyonu (spec) yazıyoruz, sonra bunu AI ile parlatıp, ardından rolleri ayrılmış ajan akışına veriyoruz

• Bugün lisans dersinde CPU ve GPU mimarisinin evrimini anlattım
  Eskiden Moore's Law sayesinde donanım her şeyi çözerdi, şimdi ise mesele paralellik.
  Simon'ın söylediği "kod ucuzdur" fikri de buna benzer bir paradigma değişimi.
  Paralel donanım çağında verimli kodun anlamı nasıl tamamen değiştiyse, AI çağında da geliştirme sürecinin kendisi değişecek. Bunu önce anlayanlar 10–100 kat avantaj elde edecek

• Bizim ekipte "arada insan doğrulaması eklenen döngü" en pratik yaklaşım oldu
  Tam otonom ajanlar testleri geçse bile sık sık örtük değişmezleri bozuyor.
  Bu yüzden geri döndürülemez kararlar alınmadan hemen önce insan devreye giriyor.
  Ama AI'ın "neyin geri döndürülemez olduğunu" anlamasını sağlamak da başlı başına başka bir sorun.
  CLAUDE.md gibi belgelerin ötesinde, örtük codebase kurallarını aktarmanın sistematik bir yolunu arıyoruz