Her ADK Geliştiricisinin Bilmesi Gereken 5 Ajan Yeteneği Tasarım Deseni

Konu 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍'ye geldiğinde, geliştiriciler genellikle formata odaklanır—YAML'ı doğru ayarlamak, dizinleri yapılandırmak ve şartnameyi takip etmek. Ancak 30'dan fazla aracın (Claude Code, Gemini CLI ve Cursor gibi) aynı düzende standartlaşmasıyla birlikte, biçimlendirme sorunu neredeyse geçerliliğini yitirdi.

Asıl zorluk artık içerik tasarımı. Şartname, bir becerinin nasıl paketleneceğini açıklıyor, ancak içindeki mantığın nasıl yapılandırılacağı konusunda sıfır rehberlik sunuyor. Örneğin, FastAPI kurallarını sarmalayan bir beceri, dört aşamalı bir dokümantasyon hattından tamamen farklı çalışır, ancak 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 dosyaları dışarıdan aynı görünür.

Ekosistem genelinde—Anthropic'in depolarından Vercel ve Google'ın dahili yönergelerine kadar—becerilerin nasıl oluşturulduğunu inceleyerek, geliştiricilerin aracılar oluşturmasına yardımcı olabilecek beş yinelenen tasarım deseni ortaya çıkıyor.

[@Saboo_Shubham_](https://x.com/@Saboo_Shubham_) ve [@lavinigam](https://x.com/@lavinigam) tarafından

Bu makale, her birini çalışan ADK koduyla ele alıyor:

• Araç Sarmalayıcı: Aracınızı herhangi bir kütüphanede anında uzman yapın
• Oluşturucu: Yeniden kullanılabilir bir şablondan yapılandırılmış belgeler üretin
• İnceleyici: Kodu bir kontrol listesine göre ciddiyet derecesine göre puanlayın
• Tersine Çevirme: Aracı, harekete geçmeden önce sizinle görüşme yapar
• Hat: Kontrol noktalarıyla katı, çok adımlı bir iş akışı uygulayın

Desen 1: Araç Sarmalayıcı

Bir Araç Sarmalayıcı, aracınıza belirli bir kütüphane için talep üzerine bağlam sağlar. API kurallarını sistem isteminize kodlamak yerine, bunları bir beceriye paketlersiniz. Aracınız bu bağlamı yalnızca o teknolojiyle gerçekten çalışırken yükler.

Uygulaması en basit desendir. 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 dosyası, kullanıcının istemindeki belirli kütüphane anahtar kelimelerini dinler, dahili dokümantasyonunuzu 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ dizininden dinamik olarak yükler ve bu kuralları mutlak doğru olarak uygular. Bu, ekibinizin dahili kodlama yönergelerini veya belirli çerçeve en iyi uygulamalarını doğrudan geliştiricilerinizin iş akışlarına dağıtmak için kullandığınız mekanizmanın aynısıdır.

İşte bir araca FastAPI kodu yazmayı öğreten bir Araç Sarmalayıcı örneği. Talimatların, araca 𝚌𝚘𝚗𝚟𝚎𝚗𝚝𝚒𝚘𝚗𝚜.𝚖𝚍 dosyasını yalnızca kodu incelemeye veya yazmaya başladığında yüklemesini açıkça söylediğine dikkat edin:

1# skills/api-expert/SKILL.md
2---
3name: api-expert
4description: FastAPI geliştirme en iyi uygulamaları ve kuralları. FastAPI uygulamaları, REST API'leri veya Pydantic modelleri oluştururken, incelerken veya hata ayıklarken kullanın.
5metadata:
6  pattern: tool-wrapper
7  domain: fastapi
8---
9
10FastAPI geliştirme konusunda uzmansınız. Bu kuralları kullanıcının koduna veya sorusuna uygulayın.
11
12## Temel Kurallar
13
14FastAPI en iyi uygulamalarının tam listesi için 'references/conventions.md' dosyasını yükleyin.
15
16## Kodu İncelerken
171. Kurallar referansını yükleyin
182. Kullanıcının kodunu her kurala göre kontrol edin
193. Her ihlal için, belirli kuralı belirtin ve düzeltmeyi önerin
20
21## Kod Yazarken
221. Kurallar referansını yükleyin
232. Her kuralı aynen izleyin
243. Tüm fonksiyon imzalarına tür ek açıklamaları ekleyin
254. Bağımlılık enjeksiyonu için Annotated stilini kullanın

Desen 2: Oluşturucu

Araç Sarmalayıcı bilgiyi uygularken, Oluşturucu tutarlı çıktıyı zorunlu kılar. Bir aracın her çalıştırmada farklı belge yapıları oluşturmasıyla mücadele ediyorsanız, Oluşturucu boşluk doldurma sürecini düzenleyerek bunu çözer.

İki isteğe bağlı dizinden yararlanır: 𝚊𝚜𝚜𝚎𝚝𝚜/ çıktı şablonunuzu tutar ve 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ stil kılavuzunuzu tutar. Talimatlar bir proje yöneticisi gibi davranır. Araca şablonu yüklemesini, stil kılavuzunu okumasını, kullanıcıya eksik değişkenleri sormasını ve belgeyi doldurmasını söyler. Bu, tahmin edilebilir API dokümantasyonu oluşturmak, commit mesajlarını standartlaştırmak veya proje mimarilerini iskeletlendirmek için pratiktir.

Bu teknik rapor oluşturucu örneğinde, beceri dosyası gerçek düzeni veya dilbilgisi kurallarını içermez. Sadece bu varlıkların alınmasını koordine eder ve aracı bunları adım adım yürütmeye zorlar:

1# skills/report-generator/SKILL.md
2---
3name: report-generator
4description: Markdown biçiminde yapılandırılmış teknik raporlar oluşturur. Kullanıcı bir rapor, özet veya analiz belgesi yazmak, oluşturmak veya taslak hazırlamak istediğinde kullanın.
5metadata:
6  pattern: generator
7  output-format: markdown
8---
9
10Bir teknik rapor oluşturucusunuz. Bu adımları aynen izleyin:
11
12Adım 1: Ton ve biçimlendirme kuralları için 'references/style-guide.md' dosyasını yükleyin.
13
14Adım 2: Gerekli çıktı yapısı için 'assets/report-template.md' dosyasını yükleyin.
15
16Adım 3: Şablonu doldurmak için gereken eksik bilgileri kullanıcıya sorun:
17- Konu veya başlık
18- Temel bulgular veya veri noktaları
19- Hedef kitle (teknik, yönetici, genel)
20
21Adım 4: Stil kılavuzu kurallarını izleyerek şablonu doldurun. Şablondaki her bölüm çıktıda bulunmalıdır.
22
23Adım 5: Tamamlanan raporu tek bir Markdown belgesi olarak döndürün.

Desen 3: İnceleyici

İnceleyici deseni, neyin kontrol edileceğini nasıl kontrol edileceğinden ayırır. Her kod kokusunu detaylandıran uzun bir sistem istemi yazmak yerine, 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/𝚛𝚎𝚟𝚒𝚎𝚠-𝚌𝚑𝚎𝚌𝚔𝚕𝚒𝚜𝚝.𝚖𝚍 dosyasının içinde modüler bir değerlendirme tablosu saklarsınız.

Bir kullanıcı kod gönderdiğinde, aracı bu kontrol listesini yükler ve gönderimi metodik olarak puanlar, bulgularını ciddiyet derecesine göre gruplandırır. Bir Python stili kontrol listesini bir OWASP güvenlik kontrol listesiyle değiştirirseniz, aynı beceri altyapısını kullanarak tamamen farklı, özel bir denetim elde edersiniz. Bu, PR incelemelerini otomatikleştirmenin veya bir insan koda bakmadan önce güvenlik açıklarını yakalamanın oldukça etkili bir yoludur.

Aşağıdaki kod inceleyici becerisi bu ayrımı göstermektedir. Talimatlar statik kalır, ancak aracı, belirli inceleme kriterlerini harici bir kontrol listesinden dinamik olarak yükler ve yapılandırılmış, ciddiyet temelli bir çıktıyı zorunlu kılar:

1# skills/code-reviewer/SKILL.md
2---
3name: code-reviewer
4description: Python kodunu kalite, stil ve yaygın hatalar açısından inceler. Kullanıcı inceleme için kod gönderdiğinde, kodu hakkında geri bildirim istediğinde veya bir kod denetimi istediğinde kullanın.
5metadata:
6  pattern: reviewer
7  severity-levels: error,warning,info
8---
9
10Bir Python kodu inceleyicisisiniz. Bu inceleme protokolünü aynen izleyin:
11
12Adım 1: Eksiksiz inceleme kriterleri için 'references/review-checklist.md' dosyasını yükleyin.
13
14Adım 2: Kullanıcının kodunu dikkatlice okuyun. Eleştirmeden önce amacını anlayın.
15
16Adım 3: Kontrol listesindeki her kuralı koda uygulayın. Bulunan her ihlal için:
17- Satır numarasını (veya yaklaşık konumu) not edin
18- Ciddiyeti sınıflandırın: error (düzeltilmeli), warning (düzeltilmeli), info (değerlendirilmeli)
19- Sadece NEyin yanlış olduğunu değil, NEDEN bir sorun olduğunu açıklayın
20- Düzeltilmiş kodla belirli bir düzeltme önerin
21
22Adım 4: Bu bölümlerle yapılandırılmış bir inceleme üretin:
23- **Özet**: Kodun ne yaptığı, genel kalite değerlendirmesi
24- **Bulgular**: Ciddiyete göre gruplandırılmış (önce hatalar, sonra uyarılar, sonra bilgiler)
25- **Puan**: Kısa gerekçeyle 1-10 arası puan verin
26- **İlk 3 Öneri**: En etkili iyileştirmeler

Desen 4: Tersine Çevirme

Aracılar doğal olarak tahmin etmek ve hemen üretmek ister. Tersine Çevirme deseni bu dinamiği tersine çevirir. Kullanıcının istemi yönlendirmesi ve aracının yürütmesi yerine, aracı bir görüşmeci gibi davranır.

Tersine Çevirme, aracıyı önce bağlamı toplamaya zorlamak için açık, pazarlıksız geçiş talimatlarına ("Tüm aşamalar tamamlanana kadar oluşturmaya BAŞLAMA" gibi) dayanır. Sırayla yapılandırılmış sorular sorar ve bir sonraki aşamaya geçmeden önce cevaplarınızı bekler. Aracı, gereksinimlerinizin ve dağıtım kısıtlamalarınızın tam bir resmine sahip olana kadar nihai bir çıktı sentezlemeyi reddeder.

Bunu çalışırken görmek için şu proje planlayıcı becerisine bakın. Buradaki kritik unsur, katı aşamalandırma ve aracının tüm kullanıcı cevapları toplanana kadar nihai planı sentezlemesini engelleyen açık geçiş istemidir:

1# skills/project-planner/SKILL.md
2---
3name: project-planner
4description: Bir plan üretmeden önce yapılandırılmış sorular aracılığıyla gereksinimleri toplayarak yeni bir yazılım projesi planlar. Kullanıcı "bir şey yapmak istiyorum", "planlamama yardım et", "bir sistem tasarla" veya "yeni bir proje başlat" dediğinde kullanın.
5metadata:
6  pattern: inversion
7  interaction: multi-turn
8---
9
10Yapılandırılmış bir gereksinim görüşmesi yürütüyorsunuz. Tüm aşamalar tamamlanana kadar oluşturmaya veya tasarlamaya BAŞLAMAYIN.
11
12## Aşama 1 — Sorun Keşfi (her seferinde bir soru sorun, her cevabı bekleyin)
13
14Bu soruları sırayla sorun. Hiçbirini atlamayın.
15
16- S1: "Bu proje kullanıcıları için hangi sorunu çözüyor?"
17- S2: "Birincil kullanıcılar kimler? Teknik seviyeleri nedir?"
18- S3: "Beklenen ölçek nedir? (günlük kullanıcı sayısı, veri hacmi, istek oranı)"
19
20## Aşama 2 — Teknik Kısıtlamalar (yalnızca Aşama 1 tamamen cevaplandıktan sonra)
21
22- S4: "Hangi dağıtım ortamını kullanacaksınız?"
23- S5: "Herhangi bir teknoloji yığını gereksiniminiz veya tercihiniz var mı?"
24- S6: "Pazarlıksız gereksinimler nelerdir? (gecikme, çalışma süresi, uyumluluk, bütçe)"
25
26## Aşama 3 — Sentez (yalnızca tüm sorular cevaplandıktan sonra)
27
281. Çıktı biçimi için 'assets/plan-template.md' dosyasını yükleyin
292. Toplanan gereksinimleri kullanarak şablonun her bölümünü doldurun
303. Tamamlanan planı kullanıcıya sunun
314. Sorun: "Bu plan gereksinimlerinizi doğru bir şekilde yansıtıyor mu? Neyi değiştirmek istersiniz?"
325. Kullanıcı onaylayana kadar geri bildirim üzerinde yineleme yapın

Desen 5: Hat

Karmaşık görevler için atlanan adımları veya göz ardı edilen talimatları göze alamazsınız. Hat deseni, sert kontrol noktalarıyla katı, sıralı bir iş akışını zorunlu kılar.

Talimatların kendisi iş akışı tanımı olarak hizmet eder. Açık elmas geçiş koşulları uygulayarak (belge dizisi oluşturmadan son montaja geçmeden önce kullanıcı onayı gerektirmek gibi), Hat, bir aracının karmaşık bir görevi atlamasını ve doğrulanmamış bir nihai sonuç sunmasını engeller.

Bu desen, tüm isteğe bağlı dizinleri kullanır, farklı referans dosyalarını ve şablonları yalnızca ihtiyaç duyuldukları belirli adımda çekerek bağlam penceresini temiz tutar.

Bu dokümantasyon hattı örneğinde, açık geçiş koşullarına dikkat edin. Aracının, kullanıcı önceki adımda oluşturulan belge dizilerini onaylayana kadar montaj aşamasına geçmesi açıkça yasaklanmıştır:

1# skills/doc-pipeline/SKILL.md
2---
3name: doc-pipeline
4description: Python kaynak kodundan çok adımlı bir hat aracılığıyla API dokümantasyonu oluşturur. Kullanıcı bir modülü belgelemek, API dokümanları oluşturmak veya koddan dokümantasyon oluşturmak istediğinde kullanın.
5metadata:
6  pattern: pipeline
7  steps: "4"
8---
9
10Bir dokümantasyon oluşturma hattı çalıştırıyorsunuz. Her adımı sırayla yürütün. Adımları atlamayın veya bir adım başarısız olursa devam etmeyin.
11
12## Adım 1 — Ayrıştırma ve Envanter
13Kullanıcının Python kodunu analiz ederek tüm genel sınıfları, fonksiyonları ve sabitleri çıkarın. Envanteri bir kontrol listesi olarak sunun. Sorun: "Bu, belgelendirilmesini istediğiniz eksiksiz genel API mi?"
14
15## Adım 2 — Belge Dizisi Oluşturma
16Belge dizisi olmayan her fonksiyon için:
17- Gerekli biçim için 'references/docstring-style.md' dosyasını yükleyin
18- Stil kılavuzunu aynen izleyerek bir belge dizisi oluşturun
19- Kullanıcı onayı için oluşturulan her belge dizisini sunun
20Kullanıcı onaylayana kadar Adım 3'e geçmeyin.
21
22## Adım 3 — Dokümantasyonu Birleştirme
23Çıktı yapısı için 'assets/api-doc-template.md' dosyasını yükleyin. Tüm sınıfları, fonksiyonları ve belge dizilerini tek bir API referans belgesinde derleyin.
24
25## Adım 4 — Kalite Kontrolü
26'references/quality-checklist.md' dosyasına göre inceleyin:
27- Her genel sembol belgelendirildi
28- Her parametrenin bir türü ve açıklaması var
29- Fonksiyon başına en az bir kullanım örneği
30Sonuçları raporlayın. Nihai belgeyi sunmadan önce sorunları düzeltin.

Doğru aracı beceri desenini seçme

Her desen farklı bir soruyu yanıtlar. Kullanım durumunuz için doğru olanı bulmak üzere bu karar ağacını kullanın:

Ve son olarak, desenler birleşir

Bu desenler birbirini dışlamaz. Birleşirler.

Bir Hat becerisi, kendi çalışmasını çift kontrol etmek için sonunda bir İnceleyici adımı içerebilir. Bir Oluşturucu, şablonunu doldurmadan önce gerekli değişkenleri toplamak için en başta Tersine Çevirmeye güvenebilir. ADK'nın 𝚂𝚔𝚒𝚕𝚕𝚃𝚘𝚘𝚕𝚜𝚎𝚝 ve aşamalı açıklama sayesinde, aracınız bağlam belirteçlerini yalnızca çalışma zamanında ihtiyaç duyduğu desenlere harcar.

Karmaşık ve kırılgan talimatları tek bir sistem istemine sıkıştırmaya çalışmayı bırakın. İş akışlarınızı parçalara ayırın, doğru yapısal deseni uygulayın ve güvenilir aracılar oluşturun.

Bugün başlayın

Aracı Becerileri şartnamesi açık kaynaklıdır ve ADK genelinde yerel olarak desteklenir. Biçimi nasıl paketleyeceğinizi zaten biliyorsunuz. Artık içeriği nasıl tasarlayacağınızı da biliyorsunuz. Google Agent Development Kit ile daha akıllı aracılar oluşturun.