Kısım II · İnşaat · Bölüm 46

Agent'larla Geliştirme

Yapay zekâ agent'larıyla geliştirme (Developing with AI agents)

1. Kat 10Bizim uygulamamızAgent'ların yazdığı ve senin yönettiğin ürün. Bu bölümün odağı: Kat 10'u üretme biçimi.
2. Kat 9Web ve tarayıcıAgent'ın dokunduğu istemci kodu; hata ayıklarken her katı gözünün önünde tut.
3. Kat 8Ağ ve internetAgent bir API'yi çağırırken ya da sunucu kurarken bu katla uğraşır.
4. Kat 7İşletim sistemiAgent terminali kullanır; dosya, süreç ve izinler bu katın işi. Bölüm 13–18.
5. Kat 5Diller ve araçlarAgent kod yazar, derleyiciyi ve testleri çalıştırır. Bölüm 9–11, 21, 29–30.
6. Kat 3–4İşlemci ve bellekAgent'ı çalıştıran model de sonunda ekran kartlarında ve işlemcilerde koşar; Kısım III bu kata uzanır.

Bu bölümde altı şey var. Agent'ın ne olduğu (46.1), projenin kurallarını anlatan AGENTS.md dosyası (46.2), iyi bir görev tarifi (46.3), git worktree ile paralel çalışma (46.4), agent'ın ürettiği kodu okuyup incelemek (46.5) ve agent'ın sınırları (46.6). Her alt bölümde somut bir şey yapacağız; iki küçük deneyi (bir oyuncak agent döngüsü, gerçek bir git worktree oturumu) bu bölüm yazılırken gerçekten çalıştırdım ve çıktısını aşağıya koydum.

46.1 Kodlama agent'ı nedir

"Yapay zekâ agent'ı" dendiğinde kafa karışıklığı büyüktür; çünkü kelime çok farklı şeyler için kullanılıyor. Anthropic'in "Building effective agents" yazısı bunu şöyle düzenler: bütün bu varyasyonlara agentic sistem (agentic system) denir ve aralarında önemli bir mimari ayrım yapılır. İş akışları (workflows), LLM'lerin ve araçların önceden yazılmış kod yollarıyla yönetildiği sistemlerdir. Agent'lar ise LLM'in kendi sürecini ve araç kullanımını dinamik olarak yönettiği, bir işi nasıl yapacağının kontrolünü elinde tuttuğu sistemlerdir.¹ Yani iş akışında yolu sen çizersin; agent'ta yolu model seçer.

Bu tanımın içindeki iki yeni kelimeyi, kitapta daha önce görmediğin için, yavaşça açalım. LLM (large language model, büyük dil modeli), metin alıp metin üreten bir yapay zekâ modelidir; Kısım III'ün sonunda (Bölüm 58) içini açacağız. Şimdilik onu "kendisine verilen metne bakıp en uygun devam metnini yazan bir sistem" olarak düşün. Araç (tool) ise modelin metin üretmenin ötesinde bir şey yapmasını sağlayan işlevdir: bir dosyayı okumak, bir dosyaya yazmak, terminalde komut çalıştırmak, internette aramak. Model araca doğrudan dokunmaz; "şu aracı şu argümanlarla çağırmak istiyorum" diye yazar, çevresindeki program (genellikle harness ya da çatı denir) aracı gerçekten çalıştırır ve sonucu modele metin olarak geri verir.

Anthropic'in yazısındaki temel yapı taşı genişletilmiş LLM (augmented LLM)'dir: arama (retrieval), araçlar ve bellek gibi eklerle güçlendirilmiş bir LLM.¹ Kodlama agent'ı bunun en tanıdık örneğidir: LLM + dosya okuma + dosya yazma + terminal. Yazının agent tarifi şu cümlede sıkışır: agent'lar tipik olarak araç kullanan LLM'lerin, çevreden gelen geri bildirimle bir döngü içinde çalışmasından ibarettir.¹ Yazı ayrıca, yürütme sırasında agent'ın her adımda çevreden "gerçek zemin" (ground truth) alması gerektiğini söyler: araç sonuçları ya da kod çalıştırma gibi; ilerlemeyi bununla değerlendirir. Görev bitince durur ya da bir durdurma koşuluna (en çok şu kadar tur gibi) ulaşır.

Bir döngüyü gözünle gör

Döngünün şeklini görmek için, gerçek bir model olmadan çalışan bir oyuncak yazdım. "Model" burada önceden yazılmış kurallarla bir sonraki eylemi seçen basit bir fonksiyondur; amaç zekâ göstermek değil, döngünün anatomisini göstermektir. Senaryo: puan() fonksiyonu yanlış cevapta 1 puan veriyor, oysa 0 olmalı; bir test bunu yakalıyor.

gecmis = []
for tur in range(1, 8):            # durdurma koşulu: en çok 7 tur
    karar = model(gecmis)          # MODEL: geçmişe bakıp sıradaki eylemi seçer
    if karar.get("bitti"): break   # model "bitti" derse döngü sona erer
    sonuc = ARACLAR[karar["arac"]](*karar["arg"])   # ÇATI: aracı gerçekten çalıştırır
    gecmis.append({"karar": karar, "sonuc": sonuc})  # sonuç modele geri döner

Programı çalıştırınca çıktı şu oldu (programın tamamı otuz küsur satır: iki dosya, üç araç, bir döngü):

[tur 1] araç=testi_calistir -> 'AssertionError: yanlış cevap 0 puan olmalı'
[tur 2] araç=dosya_oku -> 'def puan(dogru):\n    return 10 if dogru else 1\n'
[tur 3] araç=dosya_yaz -> 'yazıldı'
[tur 4] araç=testi_calistir -> 'testler geçti'
[tur 5] BİTTİ: puan() yanlış cevapta 0 döndürüyor; test geçti.

Döngünün her turunu oku: önce testi çalıştırıp başarısızlığı görüyor (gerçek zemin), sonra dosyayı okuyor, düzeltmeyi yazıyor, sonra testi tekrar çalıştırıp geçtiğini görüyor, ve ancak o zaman bitti diyor. Gerçek kodlama agent'larının yaptığı budur; farkı, "modelin" sabit kurallar yerine bir LLM olması ve araç setinin çok daha geniş olmasıdır (dosya arama, git, tarayıcı, veritabanı...). İlkesel olarak bütün bir kodlama oturumu, bu on satırlık döngünün çok uzun sürümüdür.

Bir de Anthropic'in basitlik tavsiyesi var, çünkü kitabın geri kalanında "agent her şeyi çözer" izlenimine kapılmanı istemiyoruz: yazıya göre en iyi çözüm çoğu zaman bulunabilecek en basit çözümdür; karmaşıklık yalnızca gerektiğinde artırılmalıdır, çünkü agentic sistemler daha iyi görev performansı için gecikme ve maliyetten ödün verir.¹ Bizim için çıkarım: küçük, tek dosyalık bir düzeltme için karmaşık çok-agent'lı bir kurulum gereksizdir; ama "Kısım II'deki bütün bu parçalardan oluşan bir uygulamayı yan yana yürütmek" gerçek bir orkestrasyon işidir.

46.2 AGENTS.md: projenin kuralları, agent için

Bir agent her oturuma sıfır hafızayla başlar: dün konuştuğunuz kararları, ekibinizin kurallarını, projenin tuhaflıklarını bilmez. Kod okuyarak çoğunu çıkarabilir; ama hepsini değil. Bu boşluğu AGENTS.md (AGENTS.md) doldurur: projenin kökünde duran, agent'lara projeyi nasıl çalıştıracağını ve hangi kurallara uyacağını anlatan düz bir Markdown dosyası. agents.md sitesi gerekçeyi şöyle verir: README.md dosyaları insanlar içindir (hızlı başlangıç, proje tanımı, katkı kuralları); AGENTS.md ise kodlama agent'larının ihtiyaç duyduğu ek, bazen ayrıntılı bağlamı (derleme adımları, testler, kurallar) barındırır; README'yi kısa ve insan katkıcılara odaklı tutmak için ayrı bir dosyadır.²

Format ve kurallar

agents.md sitesine göre AGENTS.md, Linux Foundation çatısındaki Agentic AI Foundation tarafından yönetilen açık bir biçimdir, yani tek bir şirkete ait değildir.² Zorunlu alan yoktur: AGENTS.md sıradan Markdown'dır, istediğin başlıkları kullanırsın, agent verdiğin metni ayrıştırır. Popüler bölümler: proje genel bakışı, derleme ve test komutları, kod stili, test talimatları, güvenlik notları; ek olarak commit mesajı ve pull request kuralları, güvenlik tuzakları, yayın adımları, yani yeni bir ekip arkadaşına söyleyeceğin her şey.² Dosya nerede olmalı? Depo kökünde. Büyük bir monorepo (birden çok projenin tek depoda durması) için her alt projeye ayrı bir AGENTS.md konabilir: agent'lar ağaçtaki en yakın dosyayı okur ve en yakın olan önceliklidir; talimatlar çakışırsa düzenlenen dosyaya en yakın AGENTS.md kazanır, kullanıcının sohbette açıkça yazdığı istem ise her şeyin üstündedir.²

Aynı formatı farklı araçlar farklı ayrıntılarla uygular. OpenAI Codex belgeleri bunu adım adım anlatır: Codex herhangi bir işe girişmeden önce AGENTS.md dosyalarını okur; önce kullanıcının Codex ev dizinindeki genel dosyaya (~/.codex), sonra proje kökünden bulunduğu dizine kadar inerek her dizindeki dosyaya bakar, dosyaları kökten aşağıya doğru birleştirir; çalışma dizinine daha yakın dosyalar daha sonra gelir, dolayısıyla önceki talimatları geçersiz kılar. Birleşik boyut, varsayılan olarak 32 KiB sınırına (project_doc_max_bytes) ulaşınca dosya eklemeyi bırakır.³ Bu detay önemli bir ders içerir: agent'ın dikkati ve belleği sınırlıdır; kuralların uzunluğu da sınırlıdır.

Kısa tutmak: Anthropic'in tavsiyesi

Claude Code'un kendi talimat dosyasının adı CLAUDE.md'dir; en iyi uygulamalar belgesinin bu dosya için tavsiyesi AGENTS.md için de geçerli mantıktır: dosya her oturuma yüklenir, yani içindeki her satır, ilgili olsun olmasın, her görevde modelin dikkatinden bir pay alır. Bu yüzden dosyaya yalnızca koddan çıkarılamayacak şeyler yazılır: repoyu doğrulamanın tam yolu (test, tip denetimi, lint komutları; tek bir test dosyası nasıl çalıştırılır), kodun yanıltıcı olduğu yerler (her yerde olan ama yeni kodda kopyalanmaması gereken eski bir kalıp), repoda olmayan kararlar (hangi hata yardımcısı seçildi, yayın nasıl yapılır) ve iki kez düzeltmek zorunda kaldığın her şey.⁴ Belge basit bir sınama önerir: bir şey yazmadan önce sor: "Bunu kodu okuyarak bulabilir mi? Gerçekten gidip bakar mı?" İkisinin cevabı da evetse, yazma.⁴

Aynı belge ikinci bir ayrım yapar ve bu ayrım hayati: talimat dosyaları ve sohbet istemleri belirsizcil (non-deterministic) yönergelerdir; model onları okur ve ne yapacağına kendisi karar verir, genellikle uyar ama garanti yoktur. Hiç istisnası olmaması gereken kurallar ise belirlenimci (deterministic) mekanizmalara aittir: çatının kendisinin her seferinde uyguladığı kancalar (hooks), yasak kuralları ve ayarlar.⁴ Bir kuralın sonuna "ÇOK ÖNEMLİ" yazmak çözüm değildir; kural gerçekten istisnasızsa, onu dosyadan çıkarıp zorlayan bir mekanizmaya bağlamak gerekir.

docs/ klasörü

AGENTS.md kısa kalmalıysa, uzun bilgi nereye gider? Kendi tasarım tavsiyem (belgelerden alınmış bir kural değil, bir çalışma biçimi): uzun ve nadiren gereken bilgiyi docs/ klasöründe ayrı dosyalara koy (ör. docs/veri-modeli.md, docs/api.md, docs/yayin.md) ve AGENTS.md'de yalnızca bir satırla işaret et: "veri modeli için docs/veri-modeli.md'ye bak." Claude Code belgesi benzer bir mantığı beceriler (skills) için söyler: uzun bir yayın prosedürü bir becerinin içinde dururken, agent yalnızca ilgili göreve girince tam metni okur; her oturumda her satırı taşımaz.⁴ Böylece AGENTS.md bir içindekiler sayfası, docs/ ise kitap olur.

Bizim uygulama için örnek bir AGENTS.md. Alanların hepsi uydurma ya da tipik; gerçek komutlar projeye göre değişir:

# AGENTS.md  (örnek taslak)

## Proje
Hukuk öğrenme uygulaması. İstemci: Expo + TypeScript (app/). Sunucu: Go (server/).
Veri: Postgres (gerçeğin kaynağı), Redis (yalnızca leaderboard önbelleği).

## Komutlar
- İstemci testi: cd app && npm test
- Tip denetimi:  cd app && npx tsc --noEmit
- Sunucu testi:  cd server && go test ./...
- Migration: server/migrations/ içinde, yalnızca ileri yönlü; eski dosyaları DEĞİŞTİRME.

## Kurallar
- Doğru cevap bilgisi istemciye ASLA gönderilmez (docs/veri-modeli.md).
- SQL'de değer birleştirme yok; her zaman parametreli sorgu.
- Puan ve seri hesabı yalnızca server/internal/scoring içinde.
- Bir değişiklikte yeni bir kütüphane eklemeden önce sor.

## Bilinen tuzaklar
- Testler DATABASE_URL ister: bkz. .env.example.
- app/legacy/ hâlâ kullanımda ama yeni kodda onun kalıbını kopyalama.

46.3 İyi görev tarifi: kapsam, kabul ölçütleri, küçük adımlar

Agent'ı kullananların yaşadığı en yaygın hayal kırıklığı şudur: "yap" dedin, bir şey yaptı, ama istediğin şey bu değildi. Claude Code'un en iyi uygulamalar belgesi bunu iki kökene bağlar: ya agent, koddan okuyamayacağı bir bilgiden yoksundu (tarif eksikti), ya da işi bitirdiğini doğrulayacak bir şeyi yoktu ("bitti" dedi ama bitmemişti).⁴ İyi bir görev tarifi bu iki boşluğu doldurur.

Kapsam: dosyayı, belirtiyi, hedefi söyle

Belgenin verdiği örnek ikilisi öğreticidir. Zayıf tarif: "giriş hatasını düzelt." Güçlü tarif: "kullanıcılar oturum zaman aşımından sonra girişin başarısız olduğunu söylüyor; src/auth/ içinde belirteç yenilemeye bak, hatayı yeniden üreten başarısız bir test yaz, sonra düzelt."⁴ Fark nedir? Güçlü tarif belirtiyi (zaman aşımından sonra), yeri (src/auth/), yöntemi (önce başarısız test) ve dolayısıyla "düzeldi"nin ne demek olduğunu söyler. Hukukçu için tanıdık: iyi bir dava dilekçesi olay, yer ve talep sonucunu açıkça yazar; "hakkım var" yazmakla yetinmez.

Bizim uygulamadan iki karşılaştırma:

Kabul ölçütleri: "bitti"nin tanımı

Kabul ölçütleri (acceptance criteria), bir işin "bitti" sayılması için sağlanması gereken, evet/hayır cevaplanabilen koşullardır. Claude Code belgesi bunun temel taşını şöyle koyar: agent'a geçti/kaldı diye dönen bir kontrol verirsen, işi kendi kendine kapatabilir: değişikliği yapar, kontrolü çalıştırır, bozulduysa çıktıyı okur, düzeltir ve yeniden çalıştırır.⁴ Kontrol hemen her şey olabilir: bir test dosyası, bir derlemenin çıkış kodu, bir lint aracı, bir betik. Belge ayrıca kanıt istemeyi öğütler: "tüm testler geçti" cümlesi tek başına çok az şey söyler; çalıştırılan komut ve çıktısı bir kanıttır.⁴

Dolayısıyla her görevin sonuna şunu eklemek iyi bir alışkanlıktır: "go test ./... ve npx tsc --noEmit geçene kadar devam et; sonunda iki komutun çıktısını göster." Bu cümle, Bölüm 42'deki testin (Bölüm 42, 42.1) ne işe yaradığını bir cümleye sığdırır: testler, agent'ın kendi işini yargılayabileceği nesnel bir hakemdir.

Küçük adımlar ve önce planlama

Büyük bir görevi tek seferde vermek, hata birikme riskini büyütür. Küçük adımlar hem agent için daha az belirsizlik hem de senin için daha okunabilir bir fark (diff) demektir. Ne yapacağını henüz tam bilmiyorsan, belge yöntem önerir: agent'tan seni röportaj yaparak sorgulamasını iste. Örnek istem: "genel API'ye hız sınırlama eklemek istiyorum ama henüz düşünmedim; spec yazabilecek hâle gelene kadar bana soru sor, sonra SPEC.md'ye yaz." Agent seçenekli sorular sorar, cevaplarınla bir şartname (spec) çıkarır; asıl işi o şartnameye göre başka bir oturumda yaptırırsın.⁴

Belgenin bir uyarısı da önemli: bir görev için gerekli ayrıntıyı tarif ederken "düşün, daha çok düşün" ya da "dikkatli ol" gibi cümleler sıradan metindir; asıl kontrol çabadır (effort), kapsam ise yalnızca senin bildiğin bir şeydir. Agent, isteği çoğu zaman temkinli okur ve istenenin en küçük hâlini yapar; daha fazlasını istiyorsan (boş ve hata durumları, kayıt akışı, klavye gezintisi gibi) bunu açıkça söylemek gerekir.⁴

46.4 git worktree ile paralel çalışan agent'lar

Şimdi iki agent'ı aynı anda çalıştırmak istediğini düşün: biri seri kuralını, öteki leaderboard ucunu yazsın. Aynı klasörde çalışırlarsa, aynı dosyalara aynı anda dokunur, birbirlerinin yarım işini görür ve dosyalar karışır. Bölüm 28'de Git'in dal (branch) kavramını gördün: bir dal, projenin paralel bir tarihçesidir. Ama bir dalda çalışmak, klasördeki dosyaların o dala göre değişmesi demektir; aynı klasörde aynı anda iki dalı "canlı" tutamazsın. Çözüm: iki ayrı klasör, her biri farklı bir dalda, ama ikisi de aynı depoya bağlı.

Git bunu çalışma ağacı (worktree) ile sağlar. Git'in kılavuzuna göre bir depo birden çok çalışma ağacını destekler; böylece aynı anda birden fazla dalı çıkarılmış (checkout) halde tutabilirsin. Depoyla birlikte hazırlanan ilk ağaç ana (main) çalışma ağacıdır; git worktree add ile eklenenler bağlı (linked) çalışma ağaçlarıdır. İşin bitince bağlı ağacı git worktree remove ile kaldırırsın.⁵ Yeni ağaçlar depoyu paylaşır; yalnızca HEAD ve index gibi ağaca özgü dosyalar ayrıdır.⁵ Yani depoyu klonlamak gibi çoğaltma yoktur; tarihçe ve nesneler tek yerde durur.

Gerçek bir oturum

Aşağıdaki komutları geçici bir dizinde çalıştırdım. İki agent için iki dal ve iki klasör açıyoruz:

$ git worktree add -b agent-seri ../agent-seri
$ git worktree add -b agent-liderlik ../agent-liderlik
$ git worktree list
.../anaproje        cd8fac6 [main]
.../agent-liderlik  cd8fac6 [agent-liderlik]
.../agent-seri      cd8fac6 [agent-seri]

Üç klasör var; hepsi aynı cd8fac6 commit'inden başladı, her biri farklı bir dalda. Şimdi bir agent'ın agent-seri klasöründe bir satır ekleyip commit ettiğini düşün; ana klasörde farkı görelim:

$ cd ../agent-seri && echo "seri = 1" >> app.txt && git commit -qam "seri ekle"
$ cd ../anaproje && git diff main agent-seri
--- a/app.txt
+++ b/app.txt
@@ -1 +1,2 @@
 puan = 0
+seri = 1

Ana klasördeki app.txt dokunulmamış kaldı; değişiklik yalnızca agent-seri dalında. Git bir kural da uygular: aynı dalı iki çalışma ağacında birden çıkaramazsın. Denediğimde Git şunu söyledi: fatal: 'main' is already used by worktree at '.../anaproje'. Kılavuz da bunu doğrular: dal başka bir çalışma ağacında çıkarılmışsa komut, --force verilmedikçe reddedilir.⁵ Bu kural kazaen aynı dala iki agent'ı bindirmeni engeller; bir agent bir dal.

İş bittiğinde: git worktree remove ../agent-liderlik klasörü kaldırdı ve git worktree list artık iki satır gösterdi (anaproje ve agent-seri). Dalın kendisi (ve içindeki commit'ler) depoda kalır; yalnızca klasör gider. Kılavuzun uyarısı: ağaç klasörünü elle silersen, Git'in tuttuğu yönetim dosyaları bir süre sonra kendiliğinden temizlenir ya da git worktree prune ile sen temizlersin.⁵

Paralel çalışmanın tuzakları

Her yeni çalışma ağacı temiz bir çıkarımdır. Claude Code belgesinin uyarısı pratik: .gitignore'daki dosyalar (ör. .env) yeni ağaçta yoktur ve bağımlılıklar kurulu değildir; belge, gereken dosyaları .worktreeinclude ile kopyalamayı, ya da kurulum komutunu talimat dosyasına yazıp agent'ın her yeni ağaçta çalıştırmasını önerir.⁴ Bizim AGENTS.md örneğindeki .env.example notu bu yüzden anlamlı. Belgeye göre aynı aracın claude -w bayrağı bir oturumu yeni bir çalışma ağacında başlatır; yani çatılar bu Git özelliğini senin yerine yönetebilir. Bunu bilmek, arka planda neyin olduğunu anlamak için yeterli: sihir yok, klasör ve dal var.

İkinci tuzak: ayrı çalışma ağaçları dosya çatışmasını engeller ama anlam çatışmasını engellemez. İki agent aynı fonksiyonu farklı biçimde değiştirirse, dalları birleştirirken (merge) çatışma (conflict) çıkar ve birini sen çözersin. En iyi önlem, işleri baştan ayrık kapsamlarla bölmektir: biri server/internal/scoring, öteki server/internal/leaderboard. Bu, Bölüm 44'ün modüler monolit fikriyle ilgili pratik bir sonuçtur: iyi sınırlanmış modüller, paralel çalışmayı kolaylaştırır.

46.5 Agent'ın kodunu okumak ve incelemek

Agent işi bitirdiğinde elinde bir fark var: hangi dosyalarda hangi satırlar eklendi, silindi, değişti. Agent'ı yönetmenin asıl işi buradadır: okumak. Bu okuma, hukukçunun bir sözleşme taslağının bir önceki sürümden farkını "değişiklikleri izle" kipinde incelemesine benzer: bütün metni baştan okumazsın; neyin değiştiğine, değişikliğin amaca uyup uymadığına, beklenmedik başka değişiklik olup olmadığına bakarsın.

Diff'i okumak

Yukarıdaki deneyde git diff main agent-seri çıktısı bir fark (diff) idi: - ile başlayan satırlar silindi, + ile başlayanlar eklendi, boşlukla başlayanlar bağlam. @@ -1 +1,2 @@ satırı "eski dosyanın 1. satırından başlayan 1 satır, yenide 1. satırdan başlayan 2 satır" demektir. Agent'ın verdiği özeti okumak yetmez; diff gerçek değişikliği gösterir. Kendine üç soru sor: (1) Kapsam: değişen dosyalar görevle uyumlu mu, yoksa alakasız bir dosyaya mı dokunulmuş? (2) Kat: değişiklik doğru katta mı (iş mantığı katmanında olması gereken puan hesabı bir ekran dosyasında mı yazılmış?) (3) Yasaklar: AGENTS.md'deki kurallar çiğnenmiş mi (SQL'de değer birleştirme, istemciye doğru cevap gönderme)?

Test ve kanıt

Diff'i okumak niyeti yoklar; test davranışı yoklar. İkisi birbirinin yerini tutmaz. Claude Code belgesi şunu öğütler: agent'tan komutu ve çıktısını iste; "tüm testler geçiyor" sözüne değil, çıktıya bak; çıktıyı okumak, kontrolü kendin yeniden çalıştırmaktan hızlıdır.⁴ Belge ayrıca, "bitti" dedikten sonra uygulamayı gerçekten çalıştırıp sonucu görmesini isteyen bir adım da anar: bu, testlerin ve tip denetiminin kaçırdığı türden sorunları yakalar.⁴ Yani üç katman: diff (ne değişti), test (çalışıyor mu), çalıştırıp bakmak (gerçekten istenen şey mi).

Bağımsız inceleyici

Belgenin dikkat çekici bir tespiti: işi yazan oturumun yaptığı gerekçelere kapılmayan taze bir inceleyici daha iyi hata bulur. Bir oturum bir şeyi yazar; başka bir oturum, yazılışını izlememiş olarak, aynı dosyayı inceler ve bulgularını geri yapıştırırsın. Belge, bunu en kolay bağımsız inceleyici olarak tarif eder.⁴ Ayrıca, incelemeyi şartnameye göre yaptırmayı öğütler: "diff'i SPEC.md'ye göre incele, her gereksinimin uygulandığını ve listelenen kenar durumların testi olduğunu kontrol et; doğruluğu etkileyen eksikleri raporla, üslubu atla." Son kısım ("üslubu atla") belgeye göre kritik: hata bulması istenen bir inceleyici her zaman bir şey bulur; her bulguyu düzeltirsen, gereksiz soyutlama katmanları ve olması imkânsız durumlar için testler birikir.⁴

Küçük commit'ler

Agent'ın işini küçük commit'lere bölmek, incelemeyi ve geri almayı kolaylaştırır. Bölüm 28'de commit'in bir geri dönüş noktası olduğunu gördün. Agent bir seferde 40 dosyalık tek bir commit üretirse, içinde bir hata varsa bütününü geri almak zorunda kalırsın; her mantıksal adım ayrı bir commit olursa yalnızca bozuk adımı geri alırsın. Bunu AGENTS.md'ye yazabilirsin: "her mantıksal adım için ayrı commit; commit mesajı ne ve neden."

46.6 Agent'ın sınırları: uydurma, bağlam, güvenlik

Agent güçlüdür ve sınırsız değildir. Üç sınır, hepsinin kökü bir sonraki kısımda açılacak LLM'in doğasında yatar; bu yüzden burada yalnızca pratik sonuçlarını söylüyoruz.

Uydurma

Uydurma (hallucination), modelin gerçek olmayan bir şeyi inandırıcı biçimde söylemesidir: var olmayan bir fonksiyon adı, bir kütüphanenin olmayan bir seçeneği, hiç yapılmamış bir testi "geçti" diye bildirmek. Nedeni Kısım III'te (Bölüm 58) açılacak: model "doğru olanı" değil, bağlama göre olası olan devam metnini üretir. Kod dünyasında bunun iyi bir tarafı var: kod çalıştırılabilir, yani uydurmanın çoğu hemen derleyiciye ya da teste takılır. İşte bu yüzden 46.3'te kontrol (test, derleme) vermeyi bu kadar vurguladık: kontrol, uydurmaya karşı en ucuz önlemdir. Zor olan uydurma, hiçbir kontrolün yakalayamayacağı türdür: "bu kütüphane şu hukuki durumu destekler" ya da bir mantık hatası. Orada tek korunma insan incelemesidir.

Anthropic'in yazısı bunu kodlama agent'ları için doğrulayıcı bir biçimde söyler: kod çözümleri otomatik testlerle doğrulanabildiği için agent'lar yinelemeye, test sonuçlarını geri bildirim olarak kullanmaya elverişlidir; ancak otomatik test işlevselliği doğrulasa da, çözümün daha geniş sistem gereksinimleriyle uyumunu sağlamak için insan incelemesi hâlâ şarttır.¹ Bu cümle bölümün ortak noktasıdır: test gerekli, yeterli değil.

Bağlam sınırı

Bir agent her adımda yalnızca bağlam penceresi (context window)ne sığan metni "görür": talimat dosyaları, konuşma geçmişi, okuduğu dosyalar, araç çıktıları. Pencere dolunca eski şeyler kaybolur ya da özetlenir. Claude Code belgesi bugünkü durumu şöyle anlatır: güncel modellerin çoğunda çok büyük (1 milyon belirteçlik) pencere vardır ve konuşma pencere dolmadan otomatik özetlenir, dolayısıyla taşma nadirdir; yine de görevler arasında oturumu temizlemek (/clear) iyi bir alışkanlıktır, çünkü odaklı bir bağlam daha iyi cevap verir ve daha ucuzdur.⁴ Bunun bizim için sonucu: bir oturumda her şeyi yaptırmaya çalışma; küçük, odaklı oturumlar (ve dallar) daha iyi iş çıkarır. Aynı belge, bir şeyi agent'a her oturum yeniden anlatmak yerine talimat dosyasına yazmanı önerir: çünkü agent oturumlar arası hatırlamaz.

Güvenlik

Agent senin adına dosya siler, komut çalıştırır, hatta internete erişebilir. Bu yetki ona verdiğin kadar tehlikelidir. Üç ilke, Bölüm 41'deki güvenlik ilkelerinin agent'a uygulanmış hâlidir. En az yetki (Bölüm 41, 41.5): agent'a yalnızca işi için gereken izni ver; üretim veritabanı parolasını verme, geliştirme ortamında çalıştır. Sırlar repoya girmez (Bölüm 41, 41.5): .env dosyası agent'ın okuyacağı yere değil, bir ayrı yere; AGENTS.md'ye şifre yazılmaz. Yıkıcı işlemler için çatının zorladığı kurallar kullan: Claude Code belgesine göre "şu klasörü asla okuma" ya da "migration klasörüne dokunma" gibi istisnasız kurallar talimat dosyasında değil, çatının uyguladığı bir kural ya da kanca olarak kurulmalıdır; çünkü model bir yönergeyi uygulamamayı seçebilir, çatının kuralı ise her seferinde uygulanır.⁴ Anthropic'in yazısı da agent'ların kum havuzunda ve korkuluklarla test edilmesini önerir.¹

Son olarak kime güvendiğin. Agent'ın internetten okuduğu bir sayfa ya da kurduğu bir kütüphane de senin sistemine girer. Bilmediğin bir paketi agent'ın eklemesine izin vermek, bilmediğin birine evin anahtarını vermek gibidir. Bu yüzden 46.2'deki örnek AGENTS.md'ye "yeni kütüphane eklemeden önce sor" satırını koyduk.

Agent'la çalışmanın kısa ritmi

Bölümü tek bir döngüye bağlayalım. (1) Hazırla: AGENTS.md kısa ve güncel; docs/ ayrıntıyı taşıyor. (2) Tarif et: kapsam, yöntem, kabul ölçütü, kanıt isteği. (3) İzole et: her agent kendi dalında, kendi çalışma ağacında. (4) Oku: diff, test çıktısı, gerekirse bağımsız inceleyici. (5) Birleştir ya da geri çevir: kararı sen verirsin, küçük commit'ler sayesinde geri almak kolaydır. (6) Öğren: agent iki kez aynı hatayı yaparsa, o hatayı AGENTS.md'ye yaz (ya da istisnasızsa çatıya zorlat). Bu döngünün her adımı kitapta daha önce öğrendiğin bir kavrama dayanıyor: Git, test, mimari, güvenlik.

Bu bölümde neler kuruldu

Bir kodlama agent'ı, bir LLM'in araçları (dosya okuma, terminal) çevreden gelen geri bildirimle bir döngü içinde kullanmasıdır; iş akışlarında yolu sen çizersin, agent'ta modelin kendisi seçer. Projenin kurallarını anlatan AGENTS.md düz Markdown'dır, kısa tutulur, yalnızca koddan çıkarılamayan bilgiyi taşır; ayrıntı docs/'a gider; istisnasız kurallar talimat dosyasına değil çatının uyguladığı mekanizmalara bağlanır. İyi görev tarifi kapsamı, yöntemi ve kabul ölçütlerini söyler, geçti/kaldı dönen bir kontrol ve kanıt ister; belirsiz işte önce agent seni sorgulayıp bir şartname yazar. git worktree her agent'a ayrı klasör ve dal verir; aynı dal iki ağaçta açılamaz. Agent'ın işini diff, test ve çalıştırarak incelersin; bağımsız bir inceleyici ve küçük commit'ler yardımcıdır. Sınırlar: uydurma (kontrolle sınırlanır), bağlam penceresi (küçük odaklı oturumlar), güvenlik (en az yetki, sırlar, çatı kuralları).

Terimler sözlükte, Bölüm 46 başlığı altında.

Kaynaklar

1. Anthropic, Building effective agents: iş akışı ve agent ayrımı, genişletilmiş LLM, agent'ın çevreden gerçek zemin alması, durdurma koşulları, özerklik maliyeti ve hataların birikmesi, kodlama agent'ları ve insan incelemesi.
2. agents.md, AGENTS.md: neden README'den ayrı, zorunlu alan yok, en yakın dosyanın önceliği, iç içe AGENTS.md, SSS bölümü; dosya biçiminin Agentic AI Foundation tarafından yönetilmesi.
3. OpenAI, Custom instructions with AGENTS.md (Codex belgeleri): genel ve proje kapsamı, kökten aşağı birleştirme, yakın dosyanın geçersiz kılması, 32 KiB varsayılan sınır.
4. Anthropic, Best practices for Claude Code: belirlenimci ve belirlenimsiz yönergeler, CLAUDE.md'yi kısa tutmak, belirli istem, geçti/kaldı kontrolü ve kanıt isteme, bağımsız inceleyici, paralel oturumlar ve çalışma ağaçları, bağlam penceresi.
5. Git, git-worktree kılavuzu: ana ve bağlı çalışma ağaçları, add, remove, prune, aynı dalın iki ağaçta çıkarılamaması. Bölümdeki git worktree oturumu geçici bir dizinde gerçekten çalıştırıldı. Oyuncak agent döngüsü bu bölüm için yazıldı ve Python ile çalıştırıldı (gerçek bir model kullanmaz).