agent, loop, graph. bilmen gereken her şey tek yerde

claude'a bir şey soruyorsun, cevabı okuyorsun, düzeltiyorsun, tekrar soruyorsun. bu çalışıyor. ama bu ai'ı kullanmanın en yavaş yolu ve çoğu insan başka bir mod olduğunu hiç denemiyor.

daha hızlı bir kurulum var ve üç parçadan oluşuyor. adım adım elinden tutulmadan plan yapıp iş yapan bir agent. iş gerçekten çıtayı geçene kadar dönen bir loop. tek promptun asla kaldıramayacağı işi paralel işçilere bölen bir graph.

claude üçünü de çalıştırıyor. sorun karmaşık olması değil, üçünü aynı yerde anlatan bir şey olmaması.

bu yazımda anlattıklarım ile o boşlukları biraz kapatalım. her biri ne demek, hangisi hangisinin üstüne biniyor, ne zaman işe yarıyor ve ne zaman tuzak. bugün kopyalayıp yapıştırabileceğin promptlarla.

agent

bu bir agent değil

claude'a "şu makaleyi özetle" demek agent değil. o chat.

"bu konudaki en çok atıf almış üç makaleyi bul, her birinden ana iddiaları çıkar, birbirleriyle çapraz kontrol et, bana tek sayfalık bir brief yaz" diyip aradaki hiçbir adıma dokunmadan işin bitmesini beklemek, o agent.

fark modelde değil. modelin etrafındaki yapıda.

bir agentte chatte olmayan üç şey var.

kendi başına çağırabildiği tool'lar. arama, dosya sistemi, kod çalıştırma, dış api'ler. bilgiyi senin getirmeni beklemiyor, gidip alıyor.

görevler arası taşınan context. neyi denediğini, neyin çalıştığını, daha önce neye karar verdiğini biliyor. claude code'da bunun somut karşılığı CLAUDE.md dosyası, sihirli bir hafıza değil.

tek cevap üretince değil, iş bitince duran bir loop. her adımda topu sana geri atmıyor.

üçü birden yerindeyse claude konuştuğun bir şey olmaktan çıkıp iş yapan bir şeye dönüşüyor.

dört seviye

herkesin ilk günden tam otonom bir agente ihtiyacı yok. bilmeye değen şey seviyeler olduğu ve her biri çoğu insanın kullandığından zaten güçlü.

seviye 1, chat. sen sorarsın, claude cevaplar, oturum biter. tool yok, hafıza yok, süren bir hedef yok. motor sensin.

seviye 2, tool'lu claude. cevap vermeden önce web'de arıyor, dosya okuyor, işini kontrol etmek için kod çalıştırıyorsa zaten biraz agentic. bunları adım adım sen söylemedin, kendi karar verdi.

seviye 3, çok adımlı workflow. hedefi veriyorsun. claude adımlara bölüyor, her birini çalıştırıyor, sonucu kontrol ediyor, bitmiş çıktıyı veriyor. adımlar arasında sen yoksun.

seviye 4, otonom. agent bir zamanlayıcıyla ya da bir tetikleyiciyle çalışıyor, girdileri izliyor, dış servisleri çağırıyor. hedefi bir kere kuruyorsun, çıktıya bakıyorsun.

1 ile 4 arasındaki fark farklı bir model değil. modelin etrafına eklenen şey. tool, context, loop. birer birer ekle, birer seviye çık.

bugün kurabileceğin bir agent

agent tipi ona vereceğin system promptu belirliyor. en çok işe yarayanı research agent, doğrudan yapıştır ve detayları kendine göre değiştir.

sen bir research agentsın. görevin var olanı değil, gerçekten önemli olanı bulmak.

bir araştırma görevi aldığında
1. bunu cevaplamaya değer 3-4 alt soruya böl
2. her birini ayrı ayrı ara
3. her bulgu için sor. bu soruyu doğrudan cevaplıyor mu, yoksa sadece ilgili mi
4. sadece doğrudan cevaplayanı tut. gerisini at
5. yapılandırılmış özet ver. ana bulgular, her birinin kaynağı ve bulamadıkların

kurallar
- her iddianın kaynağı olacak. istisna yok
- iki kaynak çelişiyorsa işaretle, taraf tutma
- güvenilir cevap bulamıyorsan boşluğu doldurmak yerine bunu açıkça söyle

aynı iskeleti data analysis ve code agent için de kullanabilirsin. değişen tek şey adımların içeriği ve kuralların sertliği.

hafıza nerede kopuyor

agentler en çok burada patlıyor ve üç şekilde oluyor.

iş uzuyor, agent başlangıcı kaybediyor. orijinal hedef, alınan kararlar, koyduğun kısıtlar, hepsi context window'dan düşüyor. agent çalışmaya devam ediyor ama neye doğru çalıştığını sessizce unutmuş oluyor.

oturumu kapatıp yenisini açıyorsun. sıfırdan başlıyor.

iş ortasında kesiliyor. geri döndüğünde nerede kaldığının, neyi denediğinin, neyin battığının kaydı yok.

üçünün de tek çözümü var. agente kendi hafızasını yazdır.

devam etmeden önce bir checkpoint yaz
1. şu ana kadar neyi bitirdin
2. hangi kararlar alındı ve neden
3. daha ne yapılması gerekiyor
4. bunu yeni bir oturumda kaldığın yerden sürdürmek için neye ihtiyacın olurdu

150 kelimeyi geçme. spesifik ol, muğlak checkpoint işe yaramaz

düzenli çalıştırdığın her agent için bir şey daha yap. her seferinde ihtiyaç duyduğu sabit bilgileri doğrudan system prompta koy. claude system promptu her oturumun başında okuyor, orada duran şey konuşma ne kadar uzarsa uzasın context'te kalıyor.

loop

loop nedir

prompt claude'a tek bir talimat verir ve sonra ne olacağına senin karar vermeni bekler. loop hedefi verir ve oraya nasıl varacağını ona bırakır.

pratikte farkı şu. prompt claude bir şey ürettiğinde durur. loop iş gerçekten bittiğinde durur.

her loop aynı çevrimi döner.

PLAN     işin gerçekten ne gerektirdiğini çıkar
EXECUTE  işi yap
CHECK    sonucu hedefe karşı ölç
ITERATE  geçmediyse en zayıf yeri bul ve düzelt
STOP     geçtiğinde ya da sert limite çarptığında dur

beş adımdan ikisi loop'un yaşayıp ölme yeri.

check gerçek olmalı. çıktıya uygulanan gerçek bir test yoksa elinde loop yok, taslak üretip bitti diyen bir claude var. check tekrarı ilerlemeye çeviren şey. gerçekten fail edebilmeli. geçen ya da geçmeyen bir test, eşiği aşan bir skor, sert kriterli bir rubrik. yumuşak check, check değil.

stop condition sonsuza kadar dönmesini engelleyen şey. her loop'un iki çıkışı olmalı. ya iş bitti ya sert limite çarpıldı. "8 denemeden sonra dur ve ne olduğunu raporla" opsiyonel değil, çözemediği bir problemin üstünde dönerken sessizce fatura kesmesini engelleyen şey o.

herhangi bir prompta üç şey ekle ve elinde loop olsun. fail edebilen gerçek bir test, ne çalıştığının kaydı ve kaç deneme hakkı olduğunun tavanı. birini eksik bırakırsan loop gibi görünen ama loop gibi para yakan bir şey olur.

gerçekten değer mi

çoğu yazı loop'u ne zaman hata olduğunu söylemeden satıyor. dürüst hali şu. bir loop ancak dört şey aynı anda doğruysa kurmaya değer.

• tekrar çalıştıracaksın. bir gün değil, düzenli. bir kere yaptığın iş loop hak etmiyor
• iş kendi kendini notlayabiliyor. senin gözüne ihtiyaç duymayan, geçen ya da kalan bir koşul var
• hedefi verip sonucu alıyorsun. ortada bir yerde senin girmen gerekiyorsa o loop değil
• bitiş çizgisi bir gerçek, bir his değil. çıktının yeterince iyi olup olmadığına karar vermek yorum gerektiriyorsa loop bu çağrıyı yapamaz

dördünden biri eksikse loop kazandırdığından fazlasına mal oluyor.

tek promptla loop

sunucu, zamanlayıcı ya da özel kurulum gerekmiyor. ilk loop'un tek prompta sığıyor.

aşağıdaki her kriteri geçene kadar loop halinde çalış. erken durma

HEDEF
[tam olarak ne üretilmesini istiyorsan yaz]

KRİTERLER, spesifik ol, yumuşak geçiş yok
- [iyi neye benziyor, ölçülebilir]
- [iyi neye benziyor, ölçülebilir]
- [iyi neye benziyor, ölçülebilir]

HER TURDA
1. DRAFT, işi üret ya da iyileştir
2. SCORE, her kritere göre 1-10 arası puanla, sert ol
3. GAPS, hala zayıf olan tam olarak ne, listele
4. CALL, bütün skorlar 8 ve üstündeyse DONE yaz ve dur
   değilse NEXT PASS yaz ve önce en zayıf boşluğu düzelt

KURALLAR
- her kriter 8'i geçmeden asla bitti deme
- her tur bir önceki turun en zayıf skorunu düzeltir
- soru sorma. makul bir varsayım yap, not düş, devam et

claude taslak yazıyor, kendi çıktısını senin kriterlerine göre puanlıyor, en zayıf noktayı buluyor, yeniden yazıyor ve gerçekten çıtayı geçene kadar devam ediyor. makul görünen bir şey ürettiğinde değil. geçtiğinde.

fark etmeye değer bir şey var. tetikleyici hala sensin. chat'i sen açtın, promptu sen yapıştırdın. sekmeyi kapatırsan duruyor. zamanlama yok, "bunu her sabah çalıştır" yok. onun için bir katman daha lazım ve çoğu insan ya orada tam sürümü kuruyor ya da aslında ihtiyacı olmadığını fark ediyor.

sıra ve maliyet

loop'ların production'da kopmasını engelleyen belirli bir sıra var ve neredeyse herkes bir adımı atlıyor.

önce elle çalıştır. hiçbir şeyi otomatikleştirmeden önce görevi tek bir konuşma içinde elle bitir. orada güvenilir çalışmıyorsa zamanlamayla da çalışmaz, sadece daha hızlı ve daha pahalı patlar.

çalışanı şablona kilitle. talimatları, kriterleri ve kuralları yeniden kurmadan çağırabileceğin bir şey olarak sakla. tek chat'in içinde yaşayan loop, chat kapanınca ölüyor.

gate ve stop condition'ı ekle. çıktıyı fail edebilen check ve kaç kere deneyeceğinin sert limiti. ikisi de yoksa elinde loop değil, otomatik para harcama yöntemi var.

maliyet tarafı. loop'lar ucuz değil. her iterasyon bütün context'i modele geri yolluyor. hedef, önceki çıktı, skor, neyin battığı. o yığın her turda büyüyor. on kere dönen bir loop on prompta mal olmuyor, her seferinde uzayan on prompta mal oluyor.

takip edilecek sayı harcanan toplam token değil. gerçekten sakladığın çıktı sayısı. on tur dönüp altısını çöpe atıyorsan dördü almak için ona ödedin. burada dolaşan "%50 altına düşerse bırak" eşiği ölçülmüş bir sayı değil, pratikten çıkmış bir kural. kendi işinde kendi oranını çıkar.

graph

node ve edge

grafik değil. görselleştirme değil. ai işinde graph, hangi işlerin olması gerektiğinin ve her birinin neye bağlı olduğunun haritası.

yapıyı iki şey kuruyor.

node tek birim iş. bir agent, bir görev, tanımlı bir girdi ve tanımlı bir çıktı. "şu konuyu araştır, özetle, sonra taslak yaz" değil. bunlardan sadece biri. iş ne kadar küçük ve sınırlıysa node o kadar kullanışlı.

edge bir bağımlılık. iki node'u ancak ikincisi gerçekten birincinin ürettiğine ihtiyaç duyuyorsa bağlar. sadece biri diğerinden sonra geliyor diye değil. bu ayrım kulağa geldiğinden daha önemli.

bir node'u kullanılabilir yapan şey tanımlı çıktı şekli. serbest metin dönen node'u sadece insan okuyabiliyor. sabit çıktısı olan node'u bir sonraki node okuyabiliyor, arada insana gerek kalmıyor.

JOB   tek bir rakibin fiyatlandırmasını araştır, başka hiçbir şey değil
IN    { competitor, url }
OUT   { price, plan, source, date }
RULE  çıktı bu şekle uymuyorsa reddet ve tekrar dene

o kontrat graph'ın her devir teslimi senin yönetmen olmadan çalışmasını sağlayan şey.

sahte edge testi

ayrım sıra ile bağımlılık arasında. sıra senin yazdığın düzen. bağımlılık bir işin öncekinin ürettiği bir şey olmadan gerçekten başlayamaması. sırayı sen uydurdun. bağımlılıklar zaten vardı, graph sadece görünür kılıyor.

test zaten çalıştırdığın herhangi bir workflow'da beş dakika sürüyor. her adımı bir kutu olarak yaz. ardışık her çiftin arasına ok çiz. sonra her okta tek soruyu sor. bu adımın ürettiği veri gerçekten sonrakine akıyor mu.

akıyorsa oku bırak, o gerçek bağımlılık. akmıyorsa oku sil, o iki adımın birbiriyle işi yok ve aynı anda çalışabilirler.

hiç gelen oku olmayan her şey hemen başlayabilir. hiç giden oku olmayan her şey nihai çıktı.

çizdiğin neredeyse her workflow'da iki üç sahte edge bulacaksın. her biri bedavaya verdiğin zaman.

diamond

sahte edge'leri temizlemeye başlayınca bir şekil diğerlerinden daha çok çıkıyor.

iş aynı anda çalışan birkaç bağımsız işe bölünüyor. o işlerin hepsi çıktılarını bir araya getiren tek bir son adıma akıyor. çizdiğinde elmasa benziyor. ortası geniş, iki ucu dar.

resmi adı fan out, sonra converge.

üç rakip araştırdığını düşün. lineer sürüm birini bitirir, ikinciyi başlatır, onu bitirir, üçüncüyü başlatır. diamond sürümü üçünü aynı anda çalıştırır ve sentez adımına geçmeden önce sadece en yavaş olanı bekler. aynı girdi, aynı çıktı, süreç bir kesiri.

diamond edge yapısı yüzünden çalışıyor. sentez adımının üç araştırma çıktısına gerçek bağımlılığı var, o edge'ler var. ama üç araştırma işinin birbirine bağımlılığı yok, o edge'ler yok. yani paralel dönüyorlar ve tek bekleme sonda, beklemenin zaten kaçınılmaz olduğu yerde.

tutması için iki şey doğru olmalı. paralel işler gerçekten bağımsız olacak. gizli paylaşılan kaynak yok, sahte bağımsızlık yok. ve converge adımı hepsine gerçekten ihtiyaç duyacak. sadece birine ihtiyaç duyuyorsa diğerleri boşa yanmış iş.

# diamond, tek pattern, her iş için

angles = [
    "ilk 3 rakibe karşı fiyatlandırma",
    "yorumlarda alıcıların şikayet ettiği şeyler",
    "pazarın hala doldurmadığı boşluklar",
]

# FAN OUT, her açı için bir worker, hepsi aynı anda
raw = run_in_parallel([
    agent(task=f"araştır {a}. her iddianın kaynağı ve tarihi olacak.")
    for a in angles
])

# REDUCE, düz kod. model yok, token yok
findings = deduplicate(filter(None, raw))

# VERIFY, her bulgu için taze bir şüpheci
survivors = [
    f for f, verdict in zip(findings, run_in_parallel([
        agent(task="bunu çürütmeye çalış. keep ya da drop dön.",
              input=f,
              fresh_context=True)
        for f in findings
    ]))
    if verdict == "keep"
]

# SYNTHESIZE, hayatta kalanlardan tek rapor
return agent(task="tek rapor, güvene göre sıralı, kaynaklar ekli.",
             input=survivors)

checker

çıktıyı yazan agent onu yargılamak için en kötü aday.

dürüst olmadığı için değil, kendi kör noktasını göremediği için. hatayı üreten akıl yürütmenin aynısı, hatayı aramak için kullanılıyor.

burada dolaşan "her ciddi çalışma modellerin kendi hatalarının çoğunu kaçırdığını söylüyor" cümlesi biraz fazla iddialı. literatürün gerçekten söylediği daha dar ve daha net. kamoi ve arkadaşlarının 2024 tacl derlemesi, adil koşullarda kendi ürettiği geri bildirimle genel görevlerde başarılı self-correction gösteren bir çalışma olmadığını söylüyor. darboğazın düzeltmede değil geri bildirim üretiminde olduğunu ekliyor. kod interpreter'ı gibi dış bir doğrulayıcı devreye girdiğinde ise iş belirgin şekilde düzeliyor.

yani kural şu. işi yapan agent işi kontrol etmez ve kontrol eden şeyin dışarıdan bir sinyali olur.

worker'larınla son adım arasına ayrı bir node koyuyorsun. tek işi her bulguyu ilerlemeden önce kırmaya çalışmak. iyileştirmek değil, özetlemek değil, düşürülmesi gereken sebebi bulmak.

çoğu insanın kaçırdığı şey, o checker'ın tamamen taze bir context'e ihtiyacı olması. worker'ın konuşmasını ona verirsen bir şey kontrol etmiş olmuyor, aynı akıl yürütme zincirine başka bir pencerede kafa sallıyor.

VERIFIER NODE

INPUT     sadece bulgu, asla worker'ın konuşması değil
CONTEXT   taze ve boş, yargıladığı işi görmemiş

PARALEL ÜÇ CHECK
1. doğru mu, iddia gerçekten tutuyor mu
2. güncel mi, kaynak taze mi yoksa bayat mı
3. kaynak gerçek mi, link iddia ettiği şeye çözülüyor mu

PASS  check'lerin çoğunluğu geçerse bulguyu tut
FAIL  son adıma ulaşmadan düşür

claude code'da gerçekte nasıl kuruluyor

burada orijinal metinlerde dolaşan bir yanlış var, düzeltelim.

etrafta "promptuna workflow kelimesini yazarsan claude paralel çalışır" ve workflow: / nodes: / depends_on: şeklinde bir yaml formatı dolaşıyor. claude code'da böyle bir declarative dag formatı yok. o yaml'ı yapıştırırsan claude onu düz metin olarak okuyup yorumlar, bir çalıştırma motoru devreye girmez. bazen paralel çalışır, bazen çalışmaz. sihirli kelime yok.

gerçekte olan şey subagent. claude code dokümantasyonuna göre her subagent kendi context window'unda, kendi system promptuyla ve kendi tool izinleriyle çalışıyor. varsayılan olarak aynı anda 20 subagent çalışabiliyor ve iç içe geçme derinliği varsayılanda 3 katman.

yani graph'ı kuran şey bir yaml dosyası değil, senin açıkça paralel iş tarif etmen ve checker'ı ayrı bir subagent olarak konumlandırman.

şu üç işi paralel subagent olarak çalıştır. birbirlerini beklemesinler

1. auth.py'ı güvenlik, edge case ve kod kalitesi için incele
2. api.py'ı aynı kriterlerle incele
3. db.py'ı aynı kriterlerle incele

üçü de bitince ayrı ve taze bir subagent aç. o üç raporu okumamış olacak,
sadece bulgu listesini alacak. görevi her bulguyu çürütmeye çalışmak

en son tek bir öncelikli düzeltme listesi yaz. önce kritik, sonra orta, sonra düşük

depends_on yerine kullandığın şey bu. bağımlılık yoksa paralel, bağımlılık varsa bekle. tarifi düz cümleyle veriyorsun.

elinde ne var

üç kavram, tek model.

agent claude'a talimat yerine hedef verir ve ona doğru kendi başına çalışmasına izin verir.

loop o işi güvenilir yapar. kendini kontrol eder, neyin battığını kaydeder ve çıtayı gerçekten geçene kadar devam eder.

graph o işi hızlandırır. paralel worker'lar, bağımsız işler aynı anda, sonda tek cevaba akıyor.

her biri bir öncekinin üstüne biniyor. her görev için üçüne birden ihtiyacın yok. ama bir görevin hangisini istediğini görebilmeye başladığın anda daha çok çalışmayı bırakıp daha iyi tasarlamaya başlıyorsun.