Kodlama ajanının bileşenleri
(magazine.sebastianraschka.com)- Kodlama ajanı, LLM merkezli olarak kod yazma, çalıştırma ve geri bildirim döngüsünü tekrar tekrar yürüten bir kontrol döngüsü ve yazılım harness’inden oluşan sistemdir
- Ajan harness’i, bağlam yönetimi, araç erişimi, prompt oluşturma ve durum kontrolünden sorumludur; kodlama işlerine özel kodlama harness’i ise depo, test ve hata denetimini yönetir
- Kodlama ajanı, canlı repo bağlamı, prompt önbelleği, araç erişimi, bağlam yönetimi, oturum belleği ve alt ajan delegasyonu olmak üzere altı bileşenle çalışır
- Harness tasarımının kalitesine bağlı olarak aynı LLM ile bile performans ve kullanıcı deneyimi büyük ölçüde değişir; iyi tasarlanmış bir harness, sürekli ve bağlam farkındalığı yüksek bir geliştirme ortamı sunar
- Mini Coding Agent, bu yapının saf Python ile gerçekleştirilmiş en küçük örneğidir ve OpenClaw’dan, kodlamaya ne kadar odaklandığı ve çalışma kapsamı açısından ayrılır
Kodlama ajanının bileşenleri
- Kodlama ajanı, LLM’i merkeze alan bir kontrol döngüsü ve bunu saran yazılım harness’i (harness) ile oluşan bir sistemdir; kod yazma, düzeltme, çalıştırma ve geri bildirim alma süreçlerini tekrar eden bir yapıda yürütür
- LLM, temel olarak bir sonraki token’ı tahmin eden modeldir; akıl yürütme modeli (reasoning model) ise ara akıl yürütme ve doğrulamayı daha fazla yapacak şekilde eğitilmiş bir LLM’dir
- Ajan, bir hedefe ulaşmak için model çağrısı, araç kullanımı, durum güncellemesi ve sonlandırma kararı gibi işlemleri yinelemeli olarak yapan kontrol döngüsüdür
- Ajan harness’i (agent harness), bu döngüyü saran yazılım yapısıdır ve bağlam yönetimi, araç erişimi, prompt oluşturma ve durum kontrolü gibi görevleri üstlenir
- Kodlama harness’i (coding harness), bunun kod çalışmalarına özel biçimidir; depo bağlamı, kod çalıştırma, test ve hata kontrolü gibi işleri yönetir
LLM, akıl yürütme modeli ve ajan arasındaki ilişki
- LLM bir motor, akıl yürütme modeli güçlendirilmiş bir motor, ajan harness’i ise bu motoru kontrol eden sistem olarak düşünülebilir
- LLM ve akıl yürütme modeli tek başına da kodlama yapabilir; ancak gerçek geliştirme ortamlarında repo gezintisi, fonksiyon arama, test çalıştırma ve hata analizi gibi karmaşık bağlam yönetimi gerekir
- Kodlama harness’i, modelin performansını en üst düzeye çıkarır ve basit bir sohbet arayüzünden çok daha güçlü bir kodlama deneyimi sunar
Kodlama harness’inin rolü
- Modeli saran bir yazılım katmanı olarak prompt birleştirme, araçları açığa çıkarma, dosya durumunu izleme, komut çalıştırma, yetki yönetimi, önbellekleme ve bellek saklama gibi işleri yapar
- Aynı LLM kullanılsa bile harness tasarımına göre performans ve kullanıcı deneyimi büyük ölçüde değişir
- Örneğin GLM-5 gibi açık ağırlıklı bir model de Codex veya Claude Code düzeyinde bir harness’e entegre edildiğinde benzer performans verebilir
- OpenAI’nin GPT-5.3 ve GPT-5.3-Codex örneğinde olduğu gibi, harness’e özel son işleme modellerini ayrı tuttuğu durumlar vardır
Kodlama ajanının 6 temel bileşeni
-
1. Canlı depo bağlamı (Live Repo Context)
- Ajanın mevcut Git repo durumu, branch, dokümantasyon ve test komutlarını bilmesi gerekir
- “Testi düzelt” gibi bir talimat, repo yapısı ve bağlama göre değiştiği için işe başlamadan önce repo özet bilgisi toplanır
- Böylece her seferinde sıfır durumdan başlanmaz ve istikrarlı çalışma temeli (stable facts) elde edilir
-
2. Prompt yapısı ve önbellek yeniden kullanımı (Prompt Shape and Cache Reuse)
- Repo özeti, araç açıklamaları ve genel talimatlar sık değişmediğinden “istikrarlı prompt öneki (stable prompt prefix)” olarak önbelleğe alınır
- Her istekte tüm prompt’u baştan kurmak yerine yalnızca değişen parçalar güncellenir
- Tekrarlanan oturumlarda hesaplama israfı azalır ve yanıt tutarlılığı korunur
-
3. Araç erişimi ve kullanımı (Tool Access and Use)
- Model yalnızca komut önermekle kalmaz; harness’in tanımladığı araç seti üzerinden komutları gerçekten çalıştırabilir
- Her araç, net girdi-çıktı biçimlerine ve sınırlara sahiptir; çalıştırmadan önce doğrulama ve onay süreci uygulanır
- Örnek: “Bilinen bir araç mı?”, “Argümanlar geçerli mi?”, “Çalışma yolu workspace içinde mi?” gibi kontroller
- Bu sayede güvenlik ve güvenilirlik artar; modelin serbestliği azalsa da pratik kullanışlılık yükselir
-
4. Bağlam şişmesini en aza indirme (Minimizing Context Bloat)
- Uzun oturumlarda tekrarlanan dosya okumaları, log’lar ve araç çıktıları nedeniyle prompt uzunluğu sınırını aşma sorunu ortaya çıkar
- Harness bunu iki stratejiyle yönetir
- Clipping: uzun metinleri, log’ları ve notları belirli bir uzunluğa indirgeme
- Summarization: eski konuşma geçmişini sıkıştırılmış özetlere dönüştürme
- Son olaylar ayrıntılı tutulurken eski bilgiler tekrarları atılarak sıkıştırılır
- Sonuç olarak gerçek performansı, model kalitesinden çok bağlam kalitesi etkiler
-
5. Yapılandırılmış oturum belleği (Structured Session Memory)
- Ajan, durumu çalışma belleği (working memory) ve tam konuşma kaydı (full transcript) olarak ayırır
- Tam kayıt, tüm istekleri, yanıtları ve araç çıktılarını içerir; böylece oturum yeniden başlatılabilir
- Çalışma belleği ise mevcut önemli bilgileri (şu anki görev, önemli dosyalar, son notlar vb.) özet halinde saklar
- Sıkıştırılmış konuşma kaydı (compact transcript) model prompt’unu yeniden kurmak için, çalışma belleği ise görevin sürekliliğini korumak için kullanılır
-
6. Sınırlandırılmış alt ajanlarla delegasyon (Delegation With Bounded Subagents)
- Ana ajan, yardımcı işleri paralel yürütmek için alt ajanlar (subagent) oluşturur
- Örneğin belirli bir sembol tanımının yeri, ayar dosyasının içeriği veya test başarısızlığının nedeni ayrı alt görevlere bölünebilir
- Alt ajanlar yalnızca gerekli bağlamı devralır ve salt okunur, özyineleme derinliği sınırlı gibi kısıtlarla çalışır
- Claude Code ve Codex de alt ajanları destekler; sınırlar görev kapsamı ve bağlam derinliği üzerinden belirlenir
Bileşen özeti
- Bu altı bileşen birbiriyle yakından bağlantılıdır ve harness tasarımının kalitesi, modelin ne kadar verimli kullanılacağını belirler
- İyi tasarlanmış bir kodlama harness’i, basit bir LLM sohbetinden çok daha bağlam farkındalığı yüksek ve süreklilik sunan bir geliştirme destek ortamı sağlar
- Mini Coding Agent(https://github.com/rasbt/mini-coding-agent), bu yapının saf Python ile gerçekleştirilmiş en küçük örneğidir
OpenClaw ile karşılaştırma
- OpenClaw, yalnızca kodlamaya adanmış bir yardımcıdan ziyade genel amaçlı bir ajan platformuna daha yakındır
- Ortak yönler:
- Workspace içindeki prompt ve talimat dosyalarını (AGENTS.md, TOOLS.md vb.) kullanma
- JSONL oturum dosyaları, konuşma sıkıştırma ve oturum yönetimi özelliklerini içerme
- Yardımcı oturumlar ve alt ajanlar oluşturabilme
- Farklar:
- Kodlama ajanı, repo gezintisi, kod düzenleme ve yerel araç çalıştırma için optimize edilmiştir
- OpenClaw ise çok kanallı ve workspace’ler arası uzun süreli ajan işletimine odaklanır
Ek: yeni kitap duyurusu
- Build A Reasoning Model (From Scratch) yazımı tamamlandı; şu anda Early Access sürümü açık
- Yayınevi yaz aylarında çıkarmayı hedefleyerek mizanpaj çalışmasını sürdürüyor
- Kitap, LLM’lerin akıl yürütme mekanizmasını doğrudan uygulayarak anlama yaklaşımı etrafında kurgulanmış
1 yorum
Hacker News yorumları
Uzun context hâlâ pahalı ve gereksiz bilgi çok olduğunda gürültü yaratıyor
Bu yüzden ben, sohbet tabanlı kodlama yerine spec tabanlı üretimin daha iyi olduğunu düşünüyorum
Geliştirdiğim Ossature bunun tersinden giden bir yaklaşım. Önce davranışı açıklayan bir spec yazıyorsunuz; ardından kod üretiminden önce eksikler ve çelişkiler denetleniyor ve her işin hangi spec bölümlerine ve hangi dosyalara başvurduğunu belirten bir build plan TOML dosyası üretiliyor
LLM sadece gerekli kısımları görüyor ve biriken bir sohbet geçmişi olmuyor. Tüm promptlar ve yanıtlar diske kaydedildiği için izlenebilirlik otomatik olarak sağlanıyor
Yakın zamanda bu yöntemle CHIP-8 emülatörü tamamen spec üzerinden oluşturuldu; ayrıca örnek projeler de var
Eskiden ekipte herkes ne inşa edildiğini bilirdi, ama şimdi ajan her seferinde sıfırdan başlıyor
Bu yüzden bence gelecek chat → spec → code akışında. spec → code aşaması insan müdahalesi olmadan çalışmalı
Eğer spesifikasyon belirsizse, insana açıkça sorulmalı ve kod üretimi buna dayanmalı
Şu anda belirsiz istekler tekrar tekrar dönüyor ve insan da bunun nedenini öğrenemiyor. “memory” ya da agent dosyaları sadece geçici çözümler
Sohbet yerine LLM'e kodun ve spec'in yansıtılmış context'ini veriyor, her aşamada context'i farklı biçimde kuruyorum
Biriken context'in yol açtığı drift sorununu engelliyor ve workflow'u LLM değil benim kodum kontrol ediyor
TOML'ü aşamalar arası aktarılan artifact olarak kullanma fikri ilginç geldi, örnek alacağım
Kullanıcının sadece Agent A'nın ürettiği diff'i gözden geçirmesi yeterli oluyor; böylece tekrar eden kod doğrulama işinden kurtuluyor
Temel nokta, niyeti (intent) her zaman korumak. Spesifikasyon ve bağlam olduğu gibi saklanmalı
Maliyet 2-3 katına çıkabilir ama uzun vadede verimin daha yüksek olacağını düşünüyorum
spec tabanlı yaklaşımın çok daha iyi olduğunu düşünüyorum. İnsan müdahalesinin nasıl işlediğini merak ediyorum — spec ve audit düzenlemesi birlikte mi yapılıyor, kod üretim başarı oranı nasıl, mevcut koda da uygulamayı planlıyor musunuz?
Ossature'un bu yaklaşımdan nasıl ayrıldığını merak ediyorum
Sadece basit bir state machine ve bash yaklaşımıyla LLM'in potansiyelini ortaya çıkarmış olması etkileyici
Bugünün ajan ekosistemi aşırı özellik ve kötü kararlarla dolu
10 yıl önce olsa böyle araçlarda sorumluluk duygusu gerektiği söylenirdi; şimdi ise korku ve abartının karıştığı kaotik bir dönemden geçiyoruz
Model zaten bilgiye sahip, ama bunu pratik davranışa dönüştürmek için context tasarımı kritik
Kullanıcı isteğini kıdemli bir geliştiricinin adımlarına çevirmek ve gerekli araçları bağlamak umut verici bir yaklaşım
Açık kaynak modellerin de iyi optimize edilmiş bir ajan ve biraz tuning ile rahatça rekabet edebileceğini düşünüyorum
Karmaşık bir harness gerekiyor ama bu sayede LLM bir araç olarak deterministik biçimde çalışıyor
Pipeline'larla sınırlı kalmadan istediğiniz mantığı serbestçe kurabiliyorsunuz
Örnek kısa ve net
Kodlama ajanı kullanmıyorum ama bu yazı kodlama ajanlarının özünü anlamaya yardımcı oluyor
Sadece 1k LOC'lik faydalı bir kodun bile 500k LOC'lik bir karmaşaya dönüşebileceğini iyi gösteriyor
Zaten birçok kişi GLM-5 gibi açık modelleri Claude Code veya Codex CLI'a bağlayarak kullanıyor
GLM resmi belgeleri de bunu öneriyor
Yazı etkileyiciydi. Ben de e-posta tabanlı bir kod yazmayan ajan geliştirdim ve prensip benzer
Her e-posta döngüsünde context'i yeniden başlatarak biriken context sorununu doğal biçimde çözüyor
İlk prompta konacak context ile araçlara ayrılacak context arasındaki denge önemli
Caching ve token maliyeti de hesaba katılmalı
Ayrıntıları blog yazımda anlattım
“harness” kelimesini sevmiyorum. Daha iyi bir ifade yok mu diye düşünüyorum
tool output truncation, context şişmesini azaltmada çok etkili
Ben context'i SQLite tabanlı olarak bir araya getiriyorum ve gerektiğinde kesilmiş tool çağrılarını mesaj ID'siyle geri yüklüyorum
İlgili deneyleri dokümanda topladım
Claude Code'u başka modellerle çalıştırmak yaygın bir şey
Örnek dokümanda da geçiyor
Ama benim deneyimime göre Anthropic modellerinin seviyesine ulaşmıyor
Opus ise maliyetine gerçekten değdiği durumlar toplamda ancak %5 kadar
Bana göre OpenCode, Claude Code'dan çok daha iyi; bu yüzden OpenRouter API kredisi satın aldım
OpenCode, özel komutlar ve basit agent tanımlarıyla bile yeterince güçlü
AGENTS.md, ROADMAP.md gibi dosyalarla workflow tanımlandığında çoğu proje için yeterli oluyor
Karmaşık harness'ler yerine esnek bir yapının, en yeni model değişimlerine daha iyi uyum sağladığını düşünüyorum
Kodlama ajanlarındaki ilerleme, modelin kendisinden çok çevresel yapıların (scaffolding) iyileştirilmesinden geliyor
Araçlar, depo context'i ve basit durum makineleri kurulduğunda darboğaz context kalitesine kayıyor
Yazı çarpıcıydı. Ben de kodlama ajanlarını sık sık motor/araba benzetmesiyle anlatıyorum
Temel bileşenleri denemek isterseniz OpenHands software-agent-sdk'ye bakmaya değer