Yapay Zekâ Kodlama Ajanlarını Rayında Tutmak: Gerçekten İşe Yarayan Bağlam, İzinler ve Koruma Bantları

Yapay zekâ kodlama ajanlarından aldığım en iyi sonuçlar zekice yazılmış komutlardan (prompt) gelmiyor. Belirsizliği azaltmaktan geliyor. Bir ajanı, kısıtlı bir ortamda çalışan hızlı bir junior-orta seviye mühendis gibi ele almaya başladığınızda, çıktının kalitesi anında artıyor. En etkili çalışma; görev net biçimde kapsamlandığında, izinler sıkı tutulduğunda ve beklenen kanıt daha ilk komut çalışmadan önce belli olduğunda ortaya çıkıyor.

Komutlarla Değil, Sınırlarla Başlayın

Bir ajana fazla özgürlük tanındığında, verimli hissettiren ama inceleme borcu (review debt) yaratan geniş kapsamlı değişiklikler yapmaya eğilim gösterir. Varsayılan yaklaşımım; dokunması gereken sistemin tam kısmını, başarı koşulunu ve değişmeden kalması gerekenleri tanımlamaktır. Bu tek adım şaşırtıcı miktarda gereksiz değişikliği önler.

İyi bir görev özeti, girdiler ve kısıtlar konusunda nettir. İlgili dosyaları veya alt sistemi adlandırır, bozuk ya da eksik olan davranışı açıklar ve sonucun nasıl doğrulanacağını belirtir. Zayıf bir özet bir özellik ister. Güçlü bir özet ise bilinen bir test yoluyla somut bir davranış değişikliği ister.

Gerçekten Yardımcı Olan Bir Görev Özeti

İşte genellikle kullanılabilir bir ilk taslak üreten türden bir talimat bloğu:

md
Task: Fix stale cart totals after coupon removal

Scope:
- app/cart/cart-summary.tsx
- app/cart/actions.ts

Do not change:
- checkout flow
- pricing API contract
- existing analytics events

Expected result:
- cart total updates immediately after coupon removal
- tax and grand total recalculate without a full page reload

Verify:
- pnpm test cart-summary
- remove a coupon in the browser and confirm totals update

Bu tür bir özet ajana bir hedef, bir sınır ve bir kanıt yolu verir. Bu, "sepet mantığını temizle" gibi belirsiz bir istekten çok daha kullanışlıdır.

Bağlam Kalitesi Bağlam Miktarını Yener

Birçok ekip, daha fazla bağlamın her zaman daha iyi olduğunu varsayar. Pratikte, yanlış bağlam eksik bağlamdan daha kötüdür; çünkü ajanı alakasız düzenlemelere doğru iter. Ben; aktif modülü, ekip stiline zaten uyan yakındaki bir örneği ve doğrulama için kullanılan tam komutları içeren daha küçük bir bağlam penceresini tercih ederim.

Depoda yakında zaten doğru bir kalıp varsa, ajanı açıkça oraya yönlendiriyorum. Küçük bir örnek, bir paragraflık mimari yorumdan daha kullanışlıdır:

ts
export function recalculateCart(lines: CartLine[]) {
  return lines.reduce(
    (acc, line) => {
      acc.subtotal += line.price * line.quantity
      acc.tax += line.tax * line.quantity
      acc.total = acc.subtotal + acc.tax
      return acc
    },
    { subtotal: 0, tax: 0, total: 0 },
  )
}

Bu, en çok olgun depolarda önem kazanır. Büyük kod tabanlarında genellikle geçerli görünen birden fazla kalıp bulunur, ama bunlardan yalnızca biri günceldir. Ajan eski uygulamaları, eski migration'ları veya ölü yardımcıları görürse, yanlış yaklaşımı kendinden emin biçimde kopyalayabilir. Bağlamı özenle seçmek bir kolaylık adımı değil, mühendislik işinin bir parçasıdır.

İzinler Davranışı Şekillendirir

Ortam, ne yapabileceklerine dair açık olduğunda ajanlar farklı davranır. Bir görev yalnızca dosya düzenlemeleri ve yerel testler gerektiriyorsa, kullanılabilir olmasını istediğim tek şey budur. Dağıtım (deployment) erişimi gerekiyorsa, bu daha sonra ve yalnızca diff anlaşılır hale geldikten sonra gelmelidir.

Bu kısıtları kompakt bir blokta görünür kılmayı seviyorum:

yaml
permissions:
  filesystem: write
  network: none
rules:
  - do not edit migrations
  - do not rename exported APIs
  - run pnpm test cart-summary before finishing

Bu yalnızca güvenlikle ilgili değil. Karar kalitesini de iyileştirir. Kısıtlı bir ortam, ajanı geniş kapsamlı düzeltmeler yerine geri alınabilir, incelenebilir değişikliklere doğru yönlendirir. İzinler ne kadar sıkı olursa, çıktının orijinal istekle hizalı kalma olasılığı o kadar artar.

Görevleri Doğrulanabilecek Kadar Küçük Tutun

Ajan çıktısını güvenilir kılmanın en kolay yolu, her görevin boyutunu küçültmektir. Değişiklik birden fazla özelliğe, birden fazla servise ve birden fazla bilinmeyene yayılıyorsa, temiz bir ilk taslak olasılığı keskin biçimde düşer. Bu işi, bağımsız olarak incelenebilen dilimlere bölüyorum.

Örneğin, tam bir refactor istemek yerine önce veri şekli temizliğini, sonra render değişikliğini, ardından test güncellemelerini istiyorum. Her dilimin dar bir hata yüzeyi vardır. Bu da regresyonları daha hızlı yakalamamı ve yamayı insan incelemesi için okunabilir tutmamı sağlar.

Doğrulama Görevin Bir Parçası Olmalı

Doğrulamayı asla isteğe bağlı bir temizlik adımı olarak ele almıyorum. İstek, hangi kanıtın geçerli sayıldığını zaten belirtmelidir. Bazen bu bir birim testidir. Bazen odaklı bir build komutu, elle yapılan bir tarayıcı yolu ya da tek bir API yanıtıdır. Önemli olan, başarının gözlemlenebilir olmasıdır.

Bir ajan işi nasıl doğruladığını açıklayamıyorsa, işin eksik olduğunu varsayarım. Bu standart katı görünebilir, ama zaman kazandırır. Kötü yamaların çoğu, doğrulama yolu somut olduğunda kendini hızla ele verir.

Koruma Bantları Bir Üretkenlik Aracıdır

Koruma bantlarını sürtünme olarak görme eğilimi vardır. Ben onları kaldıraç olarak görürüm. İyi depo talimatları, açık düzenleme kuralları ve dar görev sahipliği, sonradan yapılacak temizlik işini azaltır. Ayrıca paralel çalışmayı daha güvenli kılar; çünkü her ajan ya da mühendis çalışma kısıtlarını en baştan bilir.

Yapay zekâ kodlama araçlarından en çok yararlananlar, daha büyük çıktılar isteyen ekipler değil. Daha iyi raylar inşa edenler: daha temiz bağlam, daha küçük görevler, daha net kanıt ve daha sıkı izinler. Bunlar yerine oturduğunda, ajana güvenmek çok daha kolay hale gelir.