Bir ajan koşum takımı oluşturmanın en zor kısımlarından biri, eylem alanını inşa etmektir.
Claude, Araç Çağırma (Tool Calling) yoluyla hareket eder, ancak Claude API'sinde bash, beceriler (skills) ve yakın zamanda kod yürütme (code execution) gibi temel yapılarla araçlar oluşturmanın birçok yolu vardır (Claude API'sinde programatik araç çağırma hakkında daha fazla bilgiyi @RLanceMartin'in yeni makalesinde okuyabilirsiniz).
Tüm bu seçenekler varken, ajanınızın araçlarını nasıl tasarlarsınız? Kod yürütme veya bash gibi sadece bir araca mı ihtiyacınız var? Ya ajanınızın karşılaşabileceği her kullanım durumu için bir tane olmak üzere 50 aracınız olsaydı?
Kendimi modelin zihnine koymak için, bana zor bir matematik problemi verildiğini hayal etmeyi seviyorum. Bunu çözmek için hangi araçları isterdiniz? Bu, kendi becerilerinize bağlı olurdu!
Kağıt minimum olurdu, ancak manuel hesaplamalarla sınırlı kalırdınız. Bir hesap makinesi daha iyi olurdu, ancak daha gelişmiş seçenekleri nasıl kullanacağınızı bilmeniz gerekirdi. En hızlı ve en güçlü seçenek bir bilgisayar olurdu, ancak kod yazmak ve çalıştırmak için onu nasıl kullanacağınızı bilmeniz gerekirdi.
Bu, ajanınızı tasarlamak için kullanışlı bir çerçevedir. Ona, kendi yeteneklerine göre şekillendirilmiş araçlar vermek istersiniz. Peki bu yeteneklerin ne olduğunu nasıl bilirsiniz? Dikkat edersiniz, çıktılarını okursunuz, deney yaparsınız. Bir ajan gibi görmeyi öğrenirsiniz.
İşte Claude Code'u oluştururken Claude'a dikkat ederek öğrendiğimiz bazı dersler.
Elicitation'ı ve AskUserQuestion Aracını İyileştirme
AskUserQuestion aracını oluştururken amacımız, Claude'un soru sorma yeteneğini (genellikle elicitation olarak adlandırılır) geliştirmekti.
Claude soruları düz metin olarak sorabilse de, bu soruları yanıtlamanın gereksiz yere zaman aldığını gördük. Bu sürtünmeyi nasıl azaltabilir ve kullanıcı ile Claude arasındaki iletişim bant genişliğini nasıl artırabilirdik?
Deneme #1 - ExitPlanTool'u Düzenleme
İlk denediğimiz şey, ExitPlanTool'a planın yanında bir dizi soru içeren bir parametre eklemek oldu. Bu, uygulaması en kolay şeydi, ancak Claude'un kafasını karıştırdı çünkü aynı anda hem bir plan hem de planla ilgili bir dizi soru istiyorduk. Ya kullanıcının yanıtları planın söyledikleriyle çelişirse? Claude'un ExitPlanTool'u iki kez çağırması gerekir miydi? Başka bir yaklaşıma ihtiyacımız vardı.
(Neden bir ExitPlanTool yaptığımız hakkında daha fazla bilgiyi prompt önbelleğe alma ile ilgili yazımızda okuyabilirsiniz)
Deneme #2 - Çıktı Formatını Değiştirme
Daha sonra, Claude'un soru sormak için kullanabileceği, biraz değiştirilmiş bir işaretleme formatı sunması için çıktı talimatlarını değiştirmeyi denedik. Örneğin, parantez içinde alternatifleri olan madde işaretli sorulardan oluşan bir liste çıkarmasını isteyebilirdik. Daha sonra bu soruyu ayrıştırabilir ve kullanıcıya bir kullanıcı arayüzü olarak biçimlendirebilirdik.
Bu, yapabileceğimiz en genel değişiklik olsa da ve Claude bunu çıkarmada iyi görünse de, garanti altına alınmamıştı. Claude fazladan cümleler ekliyor, seçenekleri atlıyor veya tamamen farklı bir format kullanıyordu.
Deneme #3 - AskUserQuestion Aracı
Sonunda, Claude'un herhangi bir anda çağırabileceği, ancak özellikle plan modunda bunu yapması için yönlendirildiği bir araç oluşturmaya karar verdik. Araç tetiklendiğinde, soruları görüntülemek için bir modal gösteriyor ve kullanıcı yanıtlayana kadar ajanın döngüsünü bloke ediyorduk.
Bu araç, Claude'dan yapılandırılmış bir çıktı istememize olanak tanıdı ve Claude'un kullanıcıya birden çok seçenek sunmasını sağlamamıza yardımcı oldu. Ayrıca kullanıcılara bu işlevselliği oluşturmanın yollarını sundu; örneğin Ajan SDK'sında çağırmak veya becerilerde buna atıfta bulunmak.
En önemlisi, Claude bu aracı çağırmayı sevmiş görünüyordu ve çıktılarının iyi çalıştığını gördük. En iyi tasarlanmış araç bile, Claude onu nasıl çağıracağını anlamazsa işe yaramaz.
Bu, Claude Code'da elicitation'ın son hali mi? Emin değiliz. Bir sonraki örnekte göreceğiniz gibi, bir model için işe yarayan şey bir başkası için en iyisi olmayabilir.
Yeteneklerle Güncelleme - Görevler ve Yapılacaklar
Claude Code'u ilk kullanıma sunduğumuzda, modelin yolunda gitmesi için bir Yapılacaklar listesine ihtiyacı olduğunu fark ettik. Yapılacaklar başlangıçta yazılabilir ve model çalışma yaptıkça işaretlenebilirdi. Bunu yapmak için Claude'a TodoWrite aracını verdik; bu araç, Yapılacakları yazar veya günceller ve bunları kullanıcıya gösterirdi.
Ancak o zaman bile Claude'un ne yapması gerektiğini unuttuğunu sık sık gördük. Buna uyum sağlamak için, her 5 turda bir Claude'a hedefini hatırlatan sistem hatırlatıcıları ekledik.
Ancak modeller geliştikçe, yalnızca Yapılacaklar Listesinin hatırlatılmasına ihtiyaç duymamakla kalmadılar, aynı zamanda bunu kısıtlayıcı da bulabildiler. Yapılacaklar listesinin hatırlatıcılarının gönderilmesi, Claude'un listeyi değiştirmek yerine ona bağlı kalması gerektiğini düşünmesine neden oldu. Ayrıca Opus 4.5'in alt ajanları kullanmada çok daha iyi hale geldiğini gördük, ancak alt ajanlar paylaşılan bir Yapılacaklar Listesi üzerinde nasıl koordinasyon sağlayabilirdi?
Bunu görerek, TodoWrite'ı Görev Aracı (Task Tool) ile değiştirdik (Görevler hakkında daha fazlasını burada okuyun). Yapılacaklar modeli yolda tutmakla ilgiliyken, Görevler daha çok ajanların birbirleriyle iletişim kurmasına yardımcı olmakla ilgiliydi. Görevler bağımlılıklar içerebilir, alt ajanlar arasında güncellemeler paylaşabilir ve model bunları değiştirip silebilirdi.
Model yetenekleri arttıkça, modellerinizin bir zamanlar ihtiyaç duyduğu araçlar artık onları kısıtlıyor olabilir. Hangi araçlara ihtiyaç duyulduğuna dair önceki varsayımları sürekli olarak yeniden gözden geçirmek önemlidir. Bu aynı zamanda, oldukça benzer yetenek profillerine sahip, desteklenecek küçük bir model kümesine bağlı kalmanın neden yararlı olduğunu da açıklar.
Bir Arama Arayüzü Tasarlama
Claude için özellikle önemli bir araç seti, kendi bağlamını oluşturmak için kullanılabilecek arama araçlarıdır.
Claude Code ilk çıktığında, Claude için bağlam bulmak amacıyla bir RAG vektör veritabanı kullanıyorduk. RAG güçlü ve hızlı olsa da, indeksleme ve kurulum gerektiriyordu ve çok çeşitli ortamlarda kırılgan olabiliyordu. Daha da önemlisi, Claude bu bağlamı kendisi bulmak yerine kendisine verilen bağlamı alıyordu.
Ancak Claude web'de arama yapabiliyorsa, neden kod tabanınızda arama yapmasın? Claude'a bir Grep aracı vererek, dosyaları aramasına ve bağlamı kendisinin oluşturmasına izin verebilirdik.
Bu, Claude daha akıllı hale geldikçe, doğru araçlar verildiğinde bağlamını oluşturmada giderek daha iyi hale geldiğini gördüğümüz bir kalıptır.
Ajan Becerilerini (Agent Skills) tanıttığımızda, ajanların keşif yoluyla ilgili bağlamı aşamalı olarak keşfetmesine olanak tanıyan aşamalı açıklama (progressive disclosure) fikrini resmileştirdik.
Claude beceri dosyalarını okuyabilir ve bu dosyalar daha sonra modelin yinelemeli olarak okuyabileceği diğer dosyalara başvurabilir. Aslında, becerilerin yaygın bir kullanımı, Claude'a bir API'nin nasıl kullanılacağı veya bir veritabanının nasıl sorgulanacağı konusunda talimatlar vermek gibi daha fazla arama yeteneği eklemektir.
Bir yıl boyunca Claude, bağlamını gerçekten oluşturamamaktan, ihtiyaç duyduğu tam bağlamı bulmak için birkaç dosya katmanında iç içe arama yapabilmeye geçti.
Aşamalı açıklama, artık bir araç eklemeden yeni işlevsellik eklemek için kullandığımız yaygın bir tekniktir.
Aşamalı Açıklama - Claude Code Rehber Ajanı
Claude Code'un şu anda ~20 aracı var ve sürekli olarak hepsine ihtiyacımız olup olmadığını kendimize soruyoruz. Yeni bir araç ekleme çıtası yüksektir, çünkü bu, modele düşünmesi için bir seçenek daha verir.
Örneğin, Claude'un Claude Code'un nasıl kullanılacağı hakkında yeterince bilgi sahibi olmadığını fark ettik. Ona bir MCP'nin nasıl ekleneceğini veya bir eğik çizgi komutunun ne yaptığını sorarsanız, yanıtlayamıyordu.
Tüm bu bilgileri sistem istemine koyabilirdik, ancak kullanıcıların bunu nadiren sorması göz önüne alındığında, bu bağlam çürümesine (context rot) neden olur ve Claude Code'un ana işine, yani kod yazmaya müdahale ederdi.
Bunun yerine, bir aşamalı açıklama biçimi denedik. Claude'a, daha fazla bilgi aramak için yükleyebileceği belgelerine bir bağlantı verdik. Bu işe yaradı, ancak Claude'un doğru cevabı bulmak için bağlama çok sayıda sonuç yüklediğini gördük; oysa aslında ihtiyacınız olan tek şey cevaptı.
Bu yüzden, Claude'un kendisi hakkında soru sorduğunuzda çağırması için yönlendirildiği Claude Code Rehber alt ajanını oluşturduk; alt ajan, belgeleri iyi bir şekilde nasıl arayacağı ve neyi döndüreceği konusunda kapsamlı talimatlara sahiptir.
Bu mükemmel olmasa da (Claude, kendisini nasıl kuracağını sorduğunuzda hala kafası karışabilir), eskisinden çok daha iyi! Claude'un eylem alanına bir araç eklemeden şeyler ekleyebildik.
Bir Bilimden Çok Bir Sanat
Araçlarınızı nasıl oluşturacağınıza dair katı kurallar umuyorsanız, ne yazık ki bu kılavuz onu içermiyor. Modelleriniz için araçlar tasarlamak, bir bilim olduğu kadar bir sanattır. Kullandığınız modele, ajanın hedefine ve çalıştığı ortama büyük ölçüde bağlıdır.
Sık sık deney yapın, çıktılarınızı okuyun, yeni şeyler deneyin. Bir ajan gibi görün.
