Bir kahve alın, biraz uzun bir hikaye bu.

Geçenlerde fark ettim ki uzun zamandır bir değişkene isim vermemişim. Ciddiyim. Eskiden userList mi users mı diye beş dakika düşünen ben, son aylarda neredeyse hiç kod satırı yazmadım. Ama işim azalmadı, başka bir yere kaydı. Hatta tam tersi oldu: Ortaya çıkan kod miktarı arttığı için zihinsel yorgunluk da arttı.

Bu yazıda o kaymayı, ekipte yapay zekayı kullanmaya başlarken yaşadıklarımı ve en beklemediğim şeyi, dokümantasyonu nasıl ciddiye almaya başladığımı anlatmak istiyorum.

Çok basit bir iş, yanlış yazılmış bir kod⌗

İlk ders çok basit bir işten geldi. Ajana bir görev verdim, kodu yazdı, gayet temiz ve kendinden emin görünüyordu. Ama yanlıştı.

Sebebine baktığımda sorun modelde değil, ona verdiğim dokümandaydı. Anlatılmak istenen şey aslında basitti ama doküman o kadar dolambaçlı ve kurumsal bir dille yazılmıştı ki, ne istendiğini bir insanın bile çözmesi zaman alırdı. Model de çözmeye çalışmış ve kendi yorumuyla gayet makul görünen ama yanlış bir şey üretmişti.

O an şunu anladım: Model bana yalan söylemiyordu. Ona ne verdiysem onu okuyup ona inanıyordu. İnsan kötü yazılmış bir dokümanı okurken "herhalde şunu demek istemiş" diye boşlukları kendi tecrübesiyle dolduruyor. Ajan da dolduruyor, ama kendi tahminiyle. Bazı yerlerde buna "confident fiction" diyorlar, yani özgüvenli kurgu. Bence çok yerinde bir isim.

Kod değil, bağlam yazmak⌗

Bir süre sonra çalışma şeklim tamamen değişti. Artık işim kod yazmaktan çok, gerekli dokümanların içinde doğru noktaları bulup ajana vermek oldu.

Akışım kabaca şöyleydi:

  1. İşle ilgili dokümanlar, Jira kaydı, ilgili kod parçaları arasından gerçekten önemli olan yerleri buluyorum.
  2. Bunları ajanın anlayacağı sade bir dille bir TASK.md dosyasına yazıyorum: ne yapılacak, sınırlar nerede, neye dokunulmayacak.
  3. Görevi ajana yaptırıyorum.
  4. Sonra yazılan kodu yine bir ajana review ettiriyorum, en son ben bakıyorum.

Fark ettiğim şey şu: TASK.md iyi yazıldığında sonuç da iyi oluyor. Kötü yazıldığında, ya da kaynak doküman o kurumsal sisin içinde kaybolmuşsa, sonuç da öyle. Yani kafamı yoran şey artık kodun kendisi değil, ne istendiğini doğru tarif etmek.

Bir noktada kendimi yazılımcıdan çok analist gibi çalışırken buldum. Ama burada analistlerin yükünü hafife almamak lazım. Ben hazır dokümanların içinden bağlam topluyordum. Onlar ise o dokümanlar ortada yokken, ekipler arasında koşturup doğru bağlamı ve gerçek ihtiyaçları toplamaya çalışıyor. Benim yaptığım işin zor kısmını aslında onlar çoktan yapmış oluyor.

Hız arttı, yorgunluk da⌗

İşin bir de pek konuşulmayan tarafı var. Üretim hızı artınca iş bitmiyor, iş çoğalıyor. Bir görev eskisinden çok daha kısa sürede bitince sıradaki hemen geliyor, sonra bir sonraki. Gün içinde elimden geçen görev sayısı arttı ve her biri ayrı bir bağlam demek.

Sabah bir servisin hatasına bakıyorum, öğlen başka bir projenin TASK.md'sini yazıyorum, akşamüstü üçüncü bir işin review'undayım. Kodu ben yazmıyorum ama hepsinin kafamda doğru oturması gerekiyor. Bu sürekli context switch, eskiden bir fonksiyonla saatlerce boğuşmaktan çok daha yorucu olabiliyor. Ajan hızlı, ama arkasındaki insanın kafası aynı kafa.

Ajanlar göremiyorsa, göstermek lazım⌗

Bizde her şey ekip içinde erişime izin verilen VS Code üzerinde dönüyor. GitHub Copilot yetkimiz var, Claude da kullanıyoruz. Ama MCP kapalıydı. Yani ajan kodu görüyor, ama işin geri kalanını, yani Jenkins'te ne patladığını, lokalde hangi hatanın düştüğünü, Jira'da ne yazdığını görmüyor.

Ben de oturdum, ajanların erişebilmesi için birkaç VS Code eklentisi yazdım:

  • Hawk: Jenkins takibi için. Build'de ne olduğunu ajan kendisi görebiliyor.
  • Falcon: Lokalde çalışırken VS Code output'unu akış halinde toplayıp lmtools olarak dışarı açıyor. Böylece hata loglarına ajan doğrudan erişebiliyor, benim kopyala yapıştır yapmama gerek kalmıyor.
  • Owl: OpenShift'te aktif-aktif çalışan cluster'lara deploy edilmiş pod'ların loglarına erişim sağlıyor.
  • Wildgoose: Jira, Confluence, Graylog ve Bitbucket'ın Data Center sürümlerine erişim için.

Bunların hepsinin çıkış noktası aynıydı: Ajan neyi görüyorsa onu biliyor. Görmediği şey hakkında tahmin yürütüyor, ve tahmin yürüttüğü yerde hata yapıyor.

Ekibe yaymak: herkes aynı hızda gelmiyor⌗

Araçları yazmak işin yarısıydı. Diğer yarısı, ekipteki arkadaşların bunları gerçekten kullanabilmesiydi.

Ekip içinde yapay zeka adaptasyonu için epey vakit harcadım. Bana gelen arkadaşların bilgisayarlarına oturup VS Code'u birlikte kurduk, eklentileri yükledik, ajanla nasıl çalışılır, Hawk'tan Jenkins durumuna, Owl'dan pod loglarına nasıl bakılır, tek tek gösterdim. Kimisi bir kez gösterince kaptı, kimisi birkaç kez geldi. İkisi de normal. Yeni bir çalışma şekline alışmak, yeni bir araç öğrenmekten daha uzun sürüyor.

Burada ilginç bir tablo çıktı. Developer'lar çok hızlı adapte oldu. Bunda şaşılacak bir şey yok aslında: Bu araçlar bizim dünyamıza daha yakın, üstüne Claude'a ve Copilot'a analistlerden daha erken erişim hakkımız oldu. Analistler ise erişimi daha geç aldı, o yüzden biraz geriden geldiler.

Ama asıl düşündüren kısım şu: Kod üretmenin maliyeti bu kadar düşünce, developer'ın zamanının önemli bir kısmının teknik dokümantasyona gitmesi gerektiğini düşünüyorum. Çünkü ajanın en çok ihtiyaç duyduğu şey o. Bu değişim olunca analistlerin de developer tarafına yaklaşması gerekiyor. İki rol birbirine doğru kayıyor ve ortada buluşacakları yer, iyi yazılmış, güncel ve sade bir doküman.

Hayalimdeki dokümantasyon⌗

Açık konuşayım, henüz Docs-as-Code'a geçmiş değiliz. Ama yönümüzü o tarafa çevirmek için uğraşıyoruz. Benim için bunun en önemli kısmı araçlar değil, kafa yapısı. "Doküman, ajanın da okuduğu bir girdi" düşüncesini ekip arkadaşlarıma aktarmaya, developer'ı da analisti de aynı düzleme çekmeye çalışıyorum. Kimin erişimi önce geldiyse o önde başlamasın, herkes aynı yerden yürüsün istiyorum.

Docs-as-Code kısaca şu: Dokümanı Word'den, Confluence'ın unutulmuş köşelerinden çıkarıp kodla aynı yerde ve aynı disiplinle yönetmek. Markdown olarak repoda durması, değişikliklerin PR'dan geçmesi, CI'ın kırık linkleri ve derlenmeyen sayfaları yakalaması, ve dokümanı güncellenmemiş bir özelliğin "bitti" sayılmaması.

Kafamda şöyle bir şey var: Docusaurus tabanlı, Bitbucket'ta kodla birlikte yaşayan, ama Confluence'tan da kopmayan bir dokümantasyon. Yani ekip alıştığı yerden okumaya devam edebilsin, ama kaynağı repoda olsun ve kodla birlikte değişsin. Böylece hem insanlar hem de ajanlar aynı, güncel kaynağa bakar.

Yeni yapılandırmaya başlıyoruz. Nasıl gittiğini ayrıca yazarım.

Son söz⌗

Yapay zeka ile çalışmaya başlamadan önce dokümantasyon benim için projenin sonunda "vakit kalırsa" yapılan bir işti. Şirkette developer'dan teknik analiz dokümanı beklenmediği için de o vakit hiç gelmezdi. Şimdi kodun önüne geçti. Çünkü kodu artık büyük ölçüde ajan yazıyor ve ajan ancak ona anlattığım kadarını biliyor.

Eğer siz de ajanlarla çalışıyorsanız ve "bu neden bu kadar emin bir şekilde saçmalıyor" dediğiniz anlar oluyorsa, bir de dokümanınıza bakın. Benim tecrübemde sorun çoğu zaman oradaydı.

Kahveniz soğumadan bitirdiyseniz ne mutlu.