Yazılımda Koddan Önce Plan Yazmanın Gücü: 4 Kritik Dönüşüm

Günümüzde yazılım geliştirme dünyası köklü bir değişimin eşiğinde. AI ajanlarının devreye girmesiyle birlikte, kod yazmanın yerini planlama almaya başladı. Claude Code’un yapımcısı Boris Cherny’nin bile demo yapmadan önce 30 dakika boyunca proje planını anlatması boşuna değil. Peki, neden kodun önüne plan yazmak bu kadar kritik hale geldi?

Ben AI ajanlarıyla çalışan küçük bir geliştirici ekibine liderlik ediyorum. Ekibimiz, insanlarla ajanların yan yana çalıştığı hibrit bir modele geçti. Bir yılın ardından anladım ki: AI ajanları kod yazmayı ucuzlatabilir, ancak doğru düşünmeyi yönetmek hâlâ insanlara ait. İşin ağırlığı, uygulama detaylarından proje spesifikasyonlarına, arayüzlerden hata tanımlarına taşındı. Ve bu değişime ayak uydurmak için geleneksel çevik (Agile) yöntemler yetersiz kalıyor. Yerine, daha yavaş, daha titiz ve daha disiplinli bir yaklaşım gerekiyor — buna da "anti-çevik" diyebiliriz.

İşte yeniden başlasaydım uygulayacağım dört temel dönüşüm:

1. Planlar artık kodun yerini alıyor

AI ajanları, onlara verdiğiniz spesifikasyonu birebir yansıtır. Tek satırlık bir görev tanımıyla ajanlara yaptırdığınızda, farklı yorumlamalarla karşılaşmanız kaçınılmaz. Ancak elli satırlık detaylı bir planla — sistemin sınırlarını, hata koşullarını, entegrasyon noktalarını ve örnekleri belirterek — aynı anda birçok ajanın paralel çalışmasını sağlayabilirsiniz.

Hız, sözleşme olmadan sadece daha hızlı sapmadır.

Bu plan, yüzlerce sayfalık bir Word belgesi değil. Aksine, sistemin parçaları arasındaki belirsizlikleri ortadan kaldıran küçük ama güçlü bir dizi belgeden oluşuyor:

• Numaralandırılmış, modüler spesifikasyon bölümleri — diğer belgelerin ve ajanların doğrudan bağlantı verebileceği şekilde.
• Mimari karar kayıtları — makul mühendislerin farklılaşabileceği noktalarda alınan kararların ve sonuçlarının kalıcı olarak belgelenmesi.
• Paket bazlı README dosyaları — kod tabanının belirli bir köşesindeki kısıtlamaların ayrıntılı olarak açıklanması.
• Kod yorumları — sıradışı durumların, geçici çözümlerin ve varsayımların netleştirilmesi.

Her katman farklı bir soruya cevap verir: Nedir? Neden bu seçildi? Burada nasıl çalışılır? Bu döngü neden var? Planları karmaşıklaştırmak yerine katmanlı hale getirmek, belgelerin bozulmasını engeller. Önemli olan hacim değil, bu katmanlı yapıdır.

Ve göz ardı edilen bir ayrıntı: Planlar, repo içinde Markdown formatında yaşar. OneDrive, Confluence ya da tek tıkla girilmesi gereken bir portala değil, ajanın doğrudan erişebileceği bir dosya sistemine ihtiyaç var. Planınız ajanın doğrudan okuyamayacağı bir yerdeyse, insan müdahalesi gerekecek demektir. Markdown, metin tabanlı, sürüm kontrollü ve tüm modeller tarafından kolayca okunabilir olmasıyla ideal bir format.

Planın içeriği nelerden oluşmalı? Tüm uygulayıcılar arasında tutarlılık gerektiren unsurlar: şemalar, arayüz sınırları, hata biçimleri, rol ve izin matrisleri, izlenebilirlik sözleşmeleri, dağıtım sıralaması. İç detaylar — algoritmalar, özel yardımcı fonksiyonlar, pixel bazlı tasarımlar — planın dışında kalmalı. Önemli olan arayüzleri sabitlemek; iç kısmın keşfedilebilir olmasına izin vermek.

Bu yaklaşım suflöz değildir. Planlar evrilir, ancak sözleşmeler sabit kalır — bu da paralel çalışmaların çatışmadan ilerlemesini sağlar. Dünyayı baştan tanımlamak yerine, arayüzleri belirleyerek arka plandaki geliştirmeyi hızlandırırsınız.

Başlangıçta haftalarca süren planlama, ajanın ilk komutu çalıştırdığı hafta kâra geçer.

2. "Anti-çevik" temeller: Bağımlılıklar ve sözleşmeler

Geleneksel proje yönetimi araçları — iş parçalama yapıları, bağımlılık grafikleri, kabul kriterleri ilk olacak şekilde hazırlanan görevler — artık geçmişte kalmadı. Aksine, ajan tabanlı ekipler için bu araçlar güvenli otonomiyi mümkün kılan temeller haline geldi.

Bu, tepki göstermek değil, mekanik bir zorunluluktur. İnsanlar ortamından bağlamı emer: toplantılar, sohbetler, hatırlatmalar. AI ajanlarının böyle bir yeteneği yok. Bir ajanın elinde sadece sizin verdiğiniz komut ve diskten okuyabildiği belgeler var. "Zamanla çözeriz" yaklaşımı, ajanın gerçek zamanlı olarak edinemeyeceği ortak zihinsel model varsayar.

Bu tek farklılık, üç alışkanlığı yeniden şekillendiriyor:

Görev ayrıştırma, veri bağımlılıklarına odaklanmalı. Örneğin, bir backend ajanı veri tabanı şemasında değişiklik yapabilmek için migrasyonun tamamlanmış ve üretilen tiplerin yeniden oluşturulmuş olmasını beklemek zorunda. Bir frontend ajanı ise API spesifikasyonunun mevcut olmasını gerektirir. Bağımlılık grafiği, 2008’de bir proje müdürünün beyaz tahtaya çizdiği basit bir çizim gibi görünse de, artık yük taşıyan bir unsur haline geldi — çünkü ajan, var olmayan bir kolonu hayal ederek kod üretebilir.

Bu bağımlılıkları belgeye dökmek, ajanın güvenilirliğini artırır. Ajan sadece veriye bağlı olarak çalışır; tahminlere değil.

3. Ölçümleme ve hata sınırları: Ajan dostu sistemler inşa etmek

AI ajanlarıyla çalışırken en büyük risklerden biri, sisteminizin ölçümleme ve hata sınırlarını net bir şekilde tanımlamamış olmasıdır. Bir ajan, hata durumunda ne yapacağını bilmiyorsa ya durur ya da hatalı çıktı üretir.

Bu yüzden, planınızda aşağıdaki unsurları mutlaka belirtmelisiniz:

• Hata sınıfları ve yanıt biçimleri — örneğin, API yanıtlarında standart bir hata nesnesi kullanımı.
• Izlenebilirlik standartları — her bileşenin hangi metriklere sahip olması gerektiği.
• Geri bildirim döngüleri — ajanın yaptığı hataların nasıl kaydedileceği ve düzeltilmesi gerektiği.

Bu belgeler, ajanların kendi kendilerine çalışmasını sağlamanın yanı sıra, insan müdahalesine gerek kalmadan sistemin sağlığını korur. Ölçümleme ve hata sınırları, ajanın dünyasını daraltır ve tahmin edilebilirliğini artırır.

4. Geri bildirim ve sürekli iyileştirme: Planın evrimi

Planlar statik değildir. AI ajanlarıyla çalışırken, planın sürekli olarak iyileştirilmesi gerekir. Ancak bu iyileştirme, sözleşmelerin sabit kalmasını sağlayacak şekilde yapılmalıdır.

Örneğin:

• Yeni bir gereksinim ortaya çıktığında, sadece ilgili spesifikasyon bölümünü güncelleyin.
• Ajanların ürettiği çıktıları gözden geçirin ve planı buna göre revize edin.
• Sık yapılan hataları analiz edin ve planın ilgili bölümüne ekleyin.

Bu süreç, ajanın performansını sürekli olarak artırır ve insanlarla ajanlar arasındaki iş birliğini güçlendirir. Planın evrimi, ajanın öğrenme sürecini destekler ve sistemin genel verimliliğini artırır.

Dijital çağın yeni gelişmelerine ayak uydururken, kod yazmanın ötesinde düşünmek zorundayız. AI ajanlarıyla çalışan ekipler için, planlama ve spesifikasyon, kodun kendisi kadar önemli hale geldi. Bu dönüşümü benimseyenler, hem hız hem de kalite açısından rakiplerinden bir adım öne geçecekler.