Geçenlerde bir yan ürünümün finansal hesaplayıcıları için karmaşık bir state machine kodu yazmam gerekiyordu ve Claude’dan ilk denememde pek de istediğim gibi bir sonuç alamadım; sorun genellikle Claude’un kendisinde değil, benim ona yeterince iyi rehberlik edemememdeydi. Claude gibi büyük dil modellerinden (LLM) kod üretimi beklerken, çoğu zaman tek bir “prompt” ile sihirli bir çözüm bekleriz, ancak gerçek dünyada bu yaklaşım genellikle yetersiz kalır ve beklenen çıktıyı vermez. Daha verimli ve tutarlı kod çıktısı almak için, LLM’leri basit bir sohbet aracı olmaktan çıkarıp, daha yapılandırılmış bir mühendislik sürecinin parçası haline getirmemiz gerekiyor. Bu yazıda, Claude’u kullanarak kod üretiminde subagent mimarileri, CLAUDE.md standardı ve etkili context yönetimi ile nasıl daha iyi sonuçlar alabileceğimizi adım adım anlatacağım.
Bu teknikler, özellikle karmaşık iş mantığına sahip veya birden fazla dosya gerektiren projelerde, Claude’un yeteneklerini tam potansiyeliyle kullanmamızı sağlar. Tek bir büyük prompt yerine, görevi daha küçük ve yönetilebilir parçalara ayırarak her bir parçayı ayrı bir “uzman” ajana devretmek, hem çıktı kalitesini artırır hem de hataları ayıklamayı kolaylaştırır.
Claude Code Üretiminde Karşılaşılan Temel Sorunlar Nelerdir?
Claude’dan kod üretimi istediğimizde karşılaştığımız en yaygın sorunlardan biri, modelin tüm gereksinimleri tek bir seferde anlayıp doğru bir şekilde uygulayamamasıdır. Tek bir prompt ile tüm detayları, kısıtlamaları ve beklenen çıktıyı aktarmaya çalışmak, genellikle modelin önemli noktaları gözden kaçırmasına veya yorumlama hataları yapmasına yol açar. Örneğin, bir API için CRUD endpoint’leri yazmasını istediğimde, autentikasyon mekanizmasını veya spesifik validation kurallarını ihmal ettiğini gördüm.
Bir diğer problem ise “context window” limitidir. Özellikle büyük projelerde veya uzun konuşmalarda, Claude’a yeterince bilgi sağlamak için context window’unu aşma riskiyle karşılaşırız. Bu durum, modelin önceki talimatları veya kod parçalarını unutmasına, tutarsız çıktılar üretmesine neden olabilir. Ayrıca, modelin bazen “hallucination” yapması, yani gerçekte var olmayan fonksiyonları veya kütüphaneleri kullanması da karşılaşılan bir durumdur; bu da üretilen kodu çalışmaz hale getirebilir. Bu sorunları aşmak için daha modüler ve kontrollü yaklaşımlara ihtiyacımız var.
Subagent Mimarisi Claude ile Nasıl Çalışır?
Subagent mimarisi, büyük ve karmaşık bir görevi, her biri belirli bir uzmanlık alanına sahip daha küçük, işbirliği yapan ajanlara bölme prensibine dayanır. Bu yaklaşım, tıpkı bir yazılım ekibindeki uzmanlar gibi çalışır: bir mimar genel yapıyı tasarlar, bir backend geliştirici API’yi yazar, bir frontend geliştirici kullanıcı arayüzünü oluşturur. Claude ile subagent kullanırken, ana görevi yöneten bir “ana agent” ve bu ana agent’ın talimatları doğrultusunda belirli alt görevleri yerine getiren “subagent”lar tanımlarız.
Ben, genellikle ana agent’ı görevin genel koordinasyonundan ve aşamalandırmasından sorumlu tutarım. Örneğin, bir web uygulaması geliştireceksem, ana agent önce gereksinimleri analiz eder, ardından bir veritabanı şeması tasarlaması için bir “Database Agent”ı, API endpoint’lerini yazması için bir “Backend Agent”ı ve UI bileşenlerini oluşturması için bir “Frontend Agent”ı görevlendirir. Her subagent, kendi uzmanlık alanına uygun, daha spesifik prompt’lar alır ve çıktılarını ana agent’a geri gönderir. Ana agent ise bu çıktıları birleştirir, tutarlılığını kontrol eder ve gerekirse düzeltmeler yapılması için subagent’lara geri bildirimde bulunur. Bu yapı, hem karmaşıklığı yönetilebilir kılar hem de her aşamada daha kaliteli ve odaklanmış çıktılar alınmasını sağlar.
graph TD;
A["Ana Agent (Görev Yöneticisi)"] --> B{"Gereksinimleri Analiz Et"};
B --> C["Database Agent'ı Görevlendir"];
C --> D["Veritabanı Şemasını Oluştur"];
D --> A;
A --> E["Backend Agent'ı Görevlendir"];
E --> F["API Endpoint'lerini Yaz"];
F --> A;
A --> G["Frontend Agent'ı Görevlendir"];
G --> H["UI Bileşenlerini Oluştur"];
H --> A;
A -- "Çıktıları Birleştir & Kontrol Et" --> I["Son Kod Çıktısı"];
Bu diyagram, subagent mimarisinin temel akışını gösterir. Her bir agent, kendi içindeki prompt ve context yönetimiyle daha verimli çalışır.
CLAUDE.md Standardı Neden Önemlidir ve Nasıl Kullanılır?
CLAUDE.md, Anthropic tarafından önerilen ve Claude’a belirli bir görevi yerine getirmesi için açık ve yapılandırılmış talimatlar vermeyi amaçlayan bir işaretleme dilidir. Bu standardı kullanarak, Claude’a sadece ne yapması gerektiğini değil, aynı zamanda çıktının formatını, kısıtlamalarını ve hatta nasıl düşünmesi gerektiğini de belirtiriz. Bu, özellikle karmaşık kod üretim görevlerinde çok işime yaradı çünkü modelin kafasındaki belirsizliği minimuma indiriyor.
CLAUDE.md’nin temel faydası, prompt’ların okunabilirliğini ve tutarlılığını artırmasıdır. Ayrıca, modelin talimatları daha iyi anlamasına ve istenen formatta çıktı üretmesine yardımcı olur. Bir CLAUDE.md dosyası, genellikle aşağıdaki bölümleri içerir:
# ROLE: Agent’ın rolünü ve uzmanlık alanını tanımlar. Örneğin, “Sen bir Python FastAPI uzmanısın.”# CONSTRAINTS: Görevin kısıtlamalarını ve kurallarını belirtir. “Sadece Python 3.10+ kullan,asynciokütüphanesinden yararlan.”# GOAL: Agent’ın ulaşması gereken nihai hedefi açıklar. “Kullanıcı tabanlı bir blog için CRUD API endpoint’leri oluştur.”# INPUT: Agent’ın girdi olarak ne beklediğini gösterir. “Kullanıcıdan JSON formatında model tanımları alacaksın.”# OUTPUT: Agent’ın çıktısının formatını ve içeriğini detaylandırır. “Çıktın, çalıştırılabilir birmain.pydosyası ve gereklirequirements.txtiçermelidir.”# STEPS: Görevi tamamlamak için izlemesi gereken adımları sıralar. “ÖnceSQLAlchemymodellerini tanımla, sonraPydanticşemalarını oluştur, ardından endpoint’leri yaz.”# EXAMPLE: Beklenen çıktı formatını gösteren bir örnek sunar. Bu kısım, modelin ne üretmesi gerektiğini görselleştirmesine yardımcı olur.
Bu yapıyı kullanarak, özellikle Backend Agent’ım için bir CLAUDE.md dosyası hazırladığımda, modelin hem daha hızlı hem de daha az hata ile istediğim API’yi oluşturduğunu gördüm. Bu, sadece bir talimat seti değil, aynı zamanda modelin içsel akıl yürütmesini yönlendiren bir rehberdir.
Etkili Context Yönetimi için Pratik Yaklaşımlar
Claude gibi LLM’lerle çalışırken context yönetimi, özellikle büyük projelerde veya uzun süreli etkileşimlerde kritik öneme sahiptir. Context window limitini aşmak, modelin önemli bilgileri unutmasına ve tutarsız çıktılar üretmesine neden olabilir. Bu nedenle, context’i akıllıca yönetmek, hem maliyetleri düşürür hem de çıktı kalitesini artırır. Kendi projelerimde uyguladığım birkaç pratik yaklaşım var.
İlk olarak, gereksiz bilgileri eleme yöntemini kullanıyorum. Her etkileşimde tüm konuşma geçmişini veya tüm proje dosyasını göndermek yerine, sadece o anki görevle alakalı en kritik bilgileri modele sağlıyorum. Örneğin, sadece User modelini geliştiren bir subagent’a tüm Order veya Product modellerini göndermenin bir anlamı yok. İlgili kısımları ayıklamak için basit bir token sayacı ve dinamik context oluşturma mekanizmaları kullanıyorum.
İkinci olarak, özetleme ve özetleri kullanma stratejisini benimsedim. Uzun konuşma geçmişlerini veya büyük kod dosyalarını doğrudan göndermek yerine, bu bilgilerin kısa ve öz özetlerini oluşturup modele iletiyorum. Bir “Summarizer Agent” tanımlayarak, önceki etkileşimlerin veya kod bloklarının ana çıkarımlarını özetleyip bunları ana context’e ekleyebiliriz. Bu, modelin ana konuyu kaybetmemesini sağlarken, context window’unu da verimli kullanmamıza yardımcı olur.
Üçüncü olarak, “Retrieval-Augmented Generation” (RAG) desenini aktif olarak kullanıyorum. Bu, modelin bilgi tabanında olmayan veya güncel olmayan bilgilere erişmesini sağlamak için harici bir bilgi deposuyla (vektör veritabanı gibi) entegrasyonu içerir. Örneğin, bir üretim ERP’si için yeni bir modül geliştirirken, mevcut modüllerin kod tabanını doğrudan Claude’a beslemek yerine, kritik fonksiyonların ve yapıların vektör temsillerini oluşturup, ilgili prompt’larda bunları modele retrieve ediyorum. Böylece, Claude sadece ilgili kod parçacıklarına odaklanarak daha doğru ve entegre çıktılar üretebiliyor. Bu yöntem, özellikle büyük ve sürekli değişen kod tabanlarında çok etkili oluyor.
# Örnek: Basit bir context yönetimi fonksiyonu
def manage_context(messages, max_tokens=4000):
current_tokens = sum(len(message["content"].split()) for message in messages)
if current_tokens <= max_tokens:
return messages
# En eski mesajları veya en az önemli kısımları ele
# Basit bir örnek: En eski mesajları çıkar
while current_tokens > max_tokens and len(messages) > 1:
removed_message = messages.pop(0) # En eski mesajı çıkar
current_tokens -= len(removed_message["content"].split())
# Daha sofistike bir yaklaşım: Önemli mesajları koru, kodları özetle vb.
# Context'in hala çok büyük olması durumunda bir uyarı veya hata
if current_tokens > max_tokens:
Callout(type="warning", title="Context Aşıldı", content="Context window hala çok büyük, önemli bilgiler kaybedilebilir.")
print("Uyarı: Context window hala çok büyük, önemli bilgiler kaybedilebilir.")
return messages
# Kullanım örneği
# conversation_history = [
# {"role": "user", "content": "İlk prompt."},
# {"role": "assistant", "content": "İlk yanıt."},
# # ... daha fazla mesaj
# ]
# optimized_history = manage_context(conversation_history)Bu basit manage_context fonksiyonu, temel bir eleme stratejisini gösterir. Gerçek uygulamalarda, bu mantık çok daha karmaşık olabilir ve içerik analizi, özetleme veya RAG tekniklerini içerebilir.
Code Generation için Prompt Engineering İpuçları
Claude’dan yüksek kaliteli kod çıktısı alabilmek için prompt engineering, adeta bir sanat haline geliyor. Sadece ne istediğimizi söylemek yetmez; nasıl istediğimizi, hangi kısıtlamalarla istediğimizi ve hatta modelin düşünce sürecini nasıl yönlendirdiğimizi de belirtmemiz gerekir. Kendi deneyimlerimde, bu alanda birkaç kritik ipucu edindim.
İlk olarak, detaylı ve spesifik talimatlar vermek çok önemli. “Bir web sitesi yap” demek yerine, “Python FastAPI kullanarak, PostgreSQL veritabanına bağlı, JWT tabanlı autentikasyon içeren, kullanıcılar ve blog yazıları için CRUD endpoint’leri olan bir REST API oluştur” demeliyiz. Ayrıca, beklenen dosya yapısını, kullanılacak kütüphaneleri (örneğin, Pydantic için model validasyonu, SQLAlchemy için ORM), hatta main.py dosyasının adını bile belirtmek, modelin daha doğru çıktılar üretmesini sağlar.
İkinci olarak, adım adım düşünme (chain-of-thought) tekniğini kullanıyorum. Claude’dan doğrudan kodu yazmasını istemek yerine, ona görevi parçalara ayırarak her adımı düşünmesini ve açıklamasını talep ediyorum. Örneğin, “Önce veritabanı şemasını düşün, sonra Pydantic modellerini yaz, ardından API endpoint’lerini tasarla ve son olarak implementasyonunu yap” gibi talimatlar veriyorum. Bu, modelin problem çözme sürecini takip etmemi ve hataları erken aşamada tespit etmemi sağlıyor.
Üçüncü olarak, pozitif ve negatif kısıtlamaları bir arada kullanmak etkili sonuçlar veriyor. “Bu özellikleri ekle” (pozitif) demek kadar, “X kütüphanesini kullanma” veya “Y güvenlik açığına dikkat et” (negatif) gibi kısıtlamalar da modelin istenmeyen davranışlardan kaçınmasına yardımcı olur. Bir musteri projesinde, belirli bir legacy sistemle entegrasyon yapmamız gerektiğinde, bazı yeni kütüphanelerin kullanılmaması gerektiğini belirtmek, Claude’un gereksiz bağımlılıklar eklemesini engelledi.
Dördüncü olarak, örnekler (few-shot prompting) sunmak, modelin beklenen çıktı formatını ve stilini anlamasına büyük katkı sağlar. Küçük bir fonksiyon veya bir Pydantic model örneği vermek, Claude’un diğer benzer yapıları üretirken bu örneği referans almasını sağlar. Özellikle belirli bir kodlama standardına veya mimari desene uygun kod istiyorsam, bunu birkaç basit örnekle göstermek çok daha etkili oluyor.
Subagent ve CLAUDE.md Kullanımının Trade-off’ları Nelerdir?
Subagent mimarisi ve CLAUDE.md kullanımı, Claude’dan kod üretiminde verimliliği ve kaliteyi artırsa da, her mühendislik yaklaşımında olduğu gibi belirli trade-off’ları da beraberinde getirir. Bu yaklaşımları uygularken, projenin büyüklüğü, karmaşıklığı ve mevcut kaynaklar göz önünde bulundurulmalıdır.
En belirgin avantajı, karmaşıklık yönetimidir. Büyük bir görevi küçük, yönetilebilir parçalara bölmek, her bir parçanın daha odaklı ve hatasız üretilmesini sağlar. Ayrıca, her subagent’ın kendi context’i ve rolü olduğu için, modelin “hallucination” yapma veya konudan sapma olasılığı azalır. Özellikle bir üretim ERP’sinde karmaşık iş akışlarını otomatik kodlamak için bu yöntemi kullandığımda, farklı modüller arasındaki bağımlılıkların daha iyi yönetildiğini gözlemledim.
Ancak, bu yaklaşımın bir dezavantajı ekstra yönetim yükü getirmesidir. Birden fazla agent’ı koordine etmek, her agent için ayrı prompt’lar ve CLAUDE.md dosyaları hazırlamak, ilk başta daha fazla çaba gerektirebilir. Ana agent’ın subagent’lar arasındaki iletişimi ve çıktıların entegrasyonunu sağlaması, kendi başına ayrı bir mühendislik görevidir. Bu durum, özellikle küçük ve basit projelerde aşırı mühendislik (over-engineering) olarak görülebilir.
Bir diğer trade-off ise latency ve maliyettir. Birden fazla API çağrısı yapmak (her subagent için ayrı bir çağrı), tek bir büyük çağrıya göre toplam işlem süresini artırabilir. Ayrıca, her çağrı için context’in yeniden hazırlanması ve gönderilmesi, toplam token tüketimini ve dolayısıyla maliyeti yükseltebilir. Bu nedenle, özellikle gerçek zamanlı veya yüksek hacimli kod üretimi gerektiren senaryolarda, bu ek maliyetleri dikkatlice değerlendirmek gerekir. Ben, kendi yan ürünümde daha optimize bir çağrı sırası ve akıllı context eleme ile bu maliyetleri kabul edilebilir seviyelerde tutmaya çalıştım.
Son olarak, entegrasyon zorlukları da göz ardı edilmemelidir. Subagent’ların ürettiği kod parçacıklarını bir araya getirmek ve bunların birbiriyle uyumlu olduğundan emin olmak, bazen beklenenden daha fazla manuel düzeltme gerektirebilir. Özellikle farklı subagent’lar farklı varsayımlarla kod ürettiğinde, bu entegrasyon katmanında çakışmalar yaşanabilir. Bu yüzden, ana agent’ın bu çıktıları birleştirme ve tutarlılık kontrolü yapma becerisi kritik hale gelir.
Sonuç: Claude ile Daha Akıllı Kod Geliştirme
Claude’u sadece bir prompt kutusundan ibaret görmek, onun kod üretim potansiyelini tam anlamıyla kullanmamızı engeller. Subagent mimarileri, CLAUDE.md standardı ve dikkatli context yönetimi gibi mühendislik yaklaşımlarını benimseyerek, Claude’dan aldığımız kod çıktısının kalitesini, tutarlılığını ve güvenilirliğini önemli ölçüde artırabiliriz. Bu teknikler, özellikle karmaşık ve çok parçalı projelerde, LLM’leri sadece bir “yardımcı” olmaktan çıkarıp, gerçek bir “takım arkadaşı” haline getirir.
Elbette, bu yaklaşımlar belirli bir öğrenme eğrisi ve başlangıç maliyeti gerektirir, ancak uzun vadede hem zaman tasarrufu sağlar hem de daha az hata içeren, daha sürdürülebilir kod tabanları oluşturmamıza yardımcı olur. Kendi projelerimde, bu yöntemleri uyguladıktan sonra, Claude’un sadece basit script’ler değil, aynı zamanda karmaşık API’ler ve hatta mikroservis mimarileri için bile güçlü ve doğru çıktılar üretebildiğini gördüm. Bir sonraki adım, bu yaklaşımları kendi projelerinizde denemek ve Claude’un kod yazma yeteneklerini bir üst seviyeye taşımak olabilir.