AI ajan iş akışı nasıl kurulur? Plan, uygula, incele döngüsü

Ajan iş akışı nedir, neden döngü?

Bir yapay zekâ ajanına terminal erişimi ve dosya yazma yetkisi verdiğinizde en büyük tehlike, modelin tek bir uzun komutla projenin onlarca dosyasını aynı anda değiştirmeye kalkışmasıdır. Ajan tek seferde büyük bir özellik geliştirmeye çalıştığında bağlam penceresi hızla kirlenir, yapılan hatalar birbirine eklenir ve birkaç adım sonra hangi satırın neden değiştirildiğini takip etmek imkânsız hâle gelir. Denetimsiz bir ajan, çalışan testleri geçersiz kılabilir ya da sessizce mimari kararları bozabilir.

2000’den beri yazılım geliştiriyorum; son yıllarda vaktimin büyük bölümünü yapay zekâ destekli geliştirmeye ayırıyorum. Bu uzun süreçte öğrendiğim temel kural şudur: İnsan yazılımcılar için geçerli olan disiplin kuralları, yapay zekâ ajanları için katbekat daha katı uygulanmalıdır.

Ajan iş akışı, karmaşık bir geliştirme görevini birbirinden yalıtılmış üç aşamaya bölen öngörülebilir bir süreçtir: planlama, uygulama ve inceleme. Bu yapı bir döngüdür çünkü inceleme aşamasında ortaya çıkan her eksiklik ya da kırılan test, ajanı doğrudan kod yazmaya değil, planı güncelleyip yeniden onay almaya zorlar. İlk bakışta tek satırlık bir prompt yazıp arkanıza yaslanmaktan daha zahmetli görünür; ancak hata ayıklama süresini kısaltır ve kod tabanında geri alınabilir, temiz bir geçmiş bırakır.

Plan aşamasında ne yazılır, ne onaylanır?

Plan aşaması, ajanın kod tabanını yalnızca okuduğu, hiçbir dosyaya yazma işlemi yapmadığı keşif evresidir. Ajan depodaki mevcut mimariyi, paket bağımlılıklarını ve stil rehberlerini inceler. Ardından görevi küçük, mantıksal parçalara bölen tarihli bir plan belgesi üretir. Bu aşamada ajanın görevi kod üretmek değil, neyi neden değiştireceğini gerekçelendirmektir.

İyi yapılandırılmış bir plan belgesinde şu başlıklar mutlaka yer almalıdır:

• Girdi ve ön koşullar: Değişikliğin hangi mevcut sözleşmelere ve veri yapılarına dayandığı.
• Etkilenecek dosyalar: Oluşturulacak, güncellenecek veya silinecek dosyaların kesin listesi.
• Kabul kriterleri: Hangi testlerin yazılacağı, hangi komutların hatasız çalışması gerektiği.
• Riskler ve geri alma yolu: Olası bir uyumsuzluk durumunda değişikliğin sisteme zarar vermeden nasıl geri çevrileceği.

Geliştirici olarak sizin rolünüz planı satır satır okumak, gereksiz dosya değişikliklerini budamak ve sınırları onaylamaktır. Ajanın sunduğu plan dosyasında açık uçlu veya belirsiz ifadeler varsa onay vermemeli, planı daraltmasını istemelisiniz. Plan onaylanmadan tek bir satır kod yazılmasına izin verilmez. CLAUDE.md nasıl yazılır yazımda anlattığım gibi, bu kuralı doğrudan projenin talimat dosyasına ekleyerek ajanın onay almadan kod yazmasını baştan engelleyebilirsiniz.

Uygulama aşaması nasıl küçük tutulur?

Plan onaylandıktan sonra uygulama aşamasına geçilir. Bu aşamada ajan, onaylanmış plandaki adımları sırayla yürütür. Her adım tek bir dosya grubunu veya tek bir işlevsel değişikliği hedeflemelidir. Büyük refactor hareketleri yerine, her adımın sonunda projenin derlenebilir ve test edilebilir kalması sağlanır.

Uygulamanın küçük ve kontrollü kalması için izlediğim kurallar şunlardır:

1. Tek görev, tek dosya kümesi: Ajan aynı oturumda hem veritabanı şemasını hem de arayüz bileşenlerini değiştirmemelidir. Önce veri katmanı kurulur ve doğrulanır, ardından arayüze geçilir.
2. Yerel test çalıştırma: Her kod yazımından hemen sonra ajan ilgili birim testini (vitest run veya pytest) yerel olarak çalıştırır. Test geçmiyorsa bir sonraki adıma geçemez.
3. Her mantıksal adımda tek commit: Başarıyla tamamlanan her adım, açık ve açıklayıcı bir commit mesajıyla depoya işlenir. Bu sayede beklenmedik bir hatayla karşılaşıldığında tüm çalışmayı çöpe atmak yerine yalnızca son adımı geri almak (git revert veya git reset) yeterli olur.

Bu yaklaşım, Claude Code ile ilk projeni kur rehberinde vurguladığım “küçük adımlarla ilerleme” prensibinin kurumsal yazılım disiplinine uyarlanmış hâlidir.

İnceleme adımı neden ayrı oturumda?

Uygulamayı yapan ajan ile kodu inceleyen oturum mutlaka birbirinden ayrılmalıdır. Kodu yazan oturum, kendi ürettiği varsayımlara karşı bilişsel bir körlük geliştirir; bağlam belleğinde biriken sohbet geçmişi nedeniyle önceden yaptığı hataları görmezden gelme eğilimindedir. Dahası, uzun oturumlarda bağlam kirlendikçe ajan gereksiz dosyaları diff içerisine katmaya başlar.

İnceleme adımı için tertemiz bir terminal oturumu açılır ya da bağımsız bir inceleme ajanı çağrılır. Bu oturuma yalnızca iki girdi verilir:

• Onaylanmış plan dosyasının yolu.
• Git üzerinde oluşan fark (git diff veya git status).

İnceleyici oturumun temel görevi şunları denetlemektir:

• Planda yer almayan gereksiz bir satır veya dosya değişikliği var mı?
• Var olan testler kırıldı mı veya yeni eklenen kodlar için test yazıldı mı?
• Kod tabanının stil, tip güvenliği ve dokümantasyon standartlarına uyuldu mu?
• Proje pnpm verify veya derleme komutundan sıfır hata ve sıfır uyarıyla çıkıyor mu?

İnceleyici oturum bir hata tespit ederse kodu kendisi düzeltmeye çalışmaz; hatayı açık bir gerekçeyle raporlar. Böylece geliştirici, düzeltmenin yine kontrollü bir adım olarak yürütülmesini sağlar.

Döngü gerçek bir projede nasıl işledi?

Bu sitenin (hasancelik.com) kurulum sürecini tamamen bu plan, uygula ve incele döngüsüyle inşa ettim. Sitede kullanılan Astro, TypeScript, Cloudflare Workers ve Tailwind altyapısının her fazı depodaki docs/superpowers/plans/ dizini altında tarihli plan dosyalarıyla kayıt altına alındı.

Örneğin içerik ve lansman aşamasını yöneten 2026-09-26-06-faz-f-icerik-lansman.md plan dosyasında her görev, girdi ve çıktı dosyalarıyla önceden tanımlandı. Bir görevde uygulayıcı oturumun yalnızca ilgili bileşeni değiştirmesine izin vermek ve testleri bağımsız bir oturuma koşturmak iyi bir kuraldır. İnceleme oturumunun işi, planda öngörülmeyen stil kaymalarını ve tip uyumsuzluklarını ana dala girmeden önce raporlamaktı.

Aynı döngü içerikte de işledi: bu sitenin 29 Eylül 2026 tarihli editoryal incelemesinde ajanlar 250 ham bulgu çıkardı; ayrı bir çürütme turundan sonra 66’sı onaylandı, 51’i düzeltildi, 15’i karar için bana bırakıldı.

Yazılım & AI alanındaki bu pratik deneyim şunu gösteriyor: AI ajanları bir sihirli değnek değil, yüksek hızlı birer uygulayıcıdır. Onları verimli ve güvenli kılan şey modellerin zekâsından ziyade, sizin kurduğunuz iş akışı mimarisi ve onay mekanizmasıdır.

Kaynaklar

• Anthropic Dokümantasyonu, “Sub-agents in Claude Code”: https://docs.anthropic.com/en/docs/claude-code/sub-agents (erişim: 2026-09-28)
• Anthropic Dokümantasyonu, “Common workflows”: https://docs.anthropic.com/en/docs/claude-code/common-workflows (erişim: 2026-09-28)

Anahtar çıkarımlar

• Plan yazılmadan uygulama başlamaz; plan dosyası depoda kalır.
• Uygulayan ile inceleyen ayrı oturumlardır.
• Her adım bir commit; geri alma maliyeti düşük tutulur.

Sık sorulan sorular

Ajanın yazdığı plan dosyası nerede saklanmalı?

Kodla aynı depoda, tarihli bir Markdown dosyası olarak saklanmalı; böylece plan, uygulama commit'leri ve inceleme notları aynı geçmişte durur. Plan dosyası sohbet penceresinde kalırsa bir sonraki oturum onu göremez ve karar gerekçeleri kaybolur.