Bu yazı, Apidog'un API testi ve API yaşam döngüsü yönetimi için komut satırı aracı olan Apidog CLI'ı nasıl geliştirdiğini anlatan 10 bölümlük serinin son bölümüdür. Sırayla okuyabilir veya ilginizi çeken bölüme atlayabilirsiniz:
| Başlık | Odak Noktası | |
|---|---|---|
| 1 | 126 MCP Aracı İnşa Ettik. Ama Ajan İçin En İyi Çözüm Bu Değil | Problem keşfi |
| 2 | Neden Yepyeni Apidog CLI Geliştirdik | Mimari geliştirme |
| 3 | Altın Kural: CLI Gerçekleri Üretir, Model Gerçeklere Göre Hareket Eder | Temel felsefe |
| 4 | agentHints: CLI'lara Ajanlarla Konuşmayı Öğretmek |
Yapılandırılmış çıktı |
| 5 | BECERİ: Operasyonel Deneyimi Kod Olarak Göndermek | Operasyonel deneyim |
| 6 | Sayılar Yalan Söylemez: %30 Daha Az Araç Çağrısı, %25 Daha Az Token | Nicel sonuçlar |
| 7 | PRD'den Test Döngüsüne: Apidog CLI ile Eksiksiz Bir Ajan İş Akışı | Pratik eğitim |
| 8 | CI/CD Uyumluluğunun Ajan Araçları İçin Neden Tartışılmaz Olduğu | DevOps perspektifi |
| 9 | Yapay Zeka Dalı: Yapay Zeka Ajanları ile Daha Güvenli Proje Değişiklikleri | Güvenlik katmanı |
| 10 | Önce Şartname Dündü. Önce Beceri'ye Hoş Geldiniz. | Vizyon & gelecek |
API geliştirme, Yapay Zeka Ajanları ile değişiyor. Beceri Odaklı yaklaşım; şartnameleri, testleri ve senaryoları yürütülebilir, doğrulanabilir becerilere dönüştürerek Ajan çağı için mevcut yaklaşımları tamamlıyor.
Şartname Odaklı Dönem
Yıllarca birçok geliştirme ekibi API süreçlerini Şartname Odaklı yürüttü.
Pratikte bu yaklaşım şu sırayı izler:
| Prensip | Uygulama |
|---|---|
| Önce API'leri tasarla | Uygulamadan önce API sözleşmesini tanımla |
| Dokümantasyon etrafında işbirliği yap | Frontend, backend, QA ve ürün ekipleri aynı şartnameyi referans alır |
| Erken mock oluştur | Frontend, gerçek backend hazır olmadan geliştirmeye başlayabilir |
| Birlikte hata ayıkla | Sorunlar paylaşılan formatta görünür hale gelir |
| Şartnameye karşı test et | Uygulamanın tasarımla eşleştiğini doğrula |
| Hazır olunca yayınla | Belgelenmiş ve test edilmiş API'leri kullanıma aç |
Neden işe yaradı?
| Fayda | Neden Önemli |
|---|---|
| Açık sözleşmeler | Frontend ve backend ekipleri ne bekleyeceğini bilir |
| Paralel geliştirme | Ekipler bağımsız ilerleyebilir |
| Daha az sürtünme | Yanlış iletişim erken yakalanır |
| Stabil test | Testler belgelenmiş davranışla eşleşir |
| Canlı dokümantasyon | Şartname ürünle birlikte gelişir |
Şartname Odaklı yaklaşım, insan odaklı API geliştirme için doğru yaklaşımdı.
Yeni Tüketici: Yapay Zeka Ajanları
Yapay Zeka Kodlama araçları yaygınlaştıkça API varlıklarının tüketicileri de değişti.
Artık yalnızca insanlar değil, Ajanlar da API dokümantasyonunu, testleri ve raporları tüketiyor.
Ajanların API varlıklarından beklediği şeyler
| Ajan Aktivitesi | Gerekli Varlık |
|---|---|
| Uç noktaları okumak | API dokümantasyonu |
| Test eklemek | Uç nokta tanımları, şemalar |
| Otomasyon çalıştırmak | Test senaryoları, ortamlar |
| Raporlara göre kodu düzeltmek | Hata detayları, yanıt verileri |
| Değişikliğin kullanılabilir olup olmadığını değerlendirmek | Test sonuçları, kapsama |
Bu bağlamda Apidog'daki API dokümantasyonu, test senaryoları ve test durumları yalnızca insanlar için işbirliği materyali değildir.
Bunlar, Ajanlar tarafından deterministik olarak çağrılabilir varlıklardır.
Varlık Dönüşümü
Ajan destekli geliştirmede API varlıklarının rolü değişir:
| Varlık | Şartname Odaklı İnsan Görünümü | Beceri Odaklı Ajan Görünümü |
|---|---|---|
| API dokümantasyonu | İşbirliği materyali | Çağrılabilir veri kaynağı |
| Test durumları | Kalite artefaktı | Yürütülebilir doğrulama |
| Test senaryoları | Test iş akışı | Otomasyon hedefi |
| Ortamlar | Yapılandırma | Çalışma zamanı bağlamı |
| Raporlar | İnceleme çıktısı | Geri bildirim sinyali |
Varlıklar "okunabilir" olmaktan "çağrılabilir" olmaya dönüşür.
Beceri Odaklı Yaklaşım Nedir?
Beceri Odaklı yaklaşım, Şartname Odaklı yaklaşımı ortadan kaldırmaz. Onun üzerine bir Ajan yürütme katmanı ekler.
Değişmeden kalanlar
| Neler Kalıyor | Neden |
|---|---|
| Uç nokta spesifikasyonları | Net sözleşmelere hâlâ ihtiyaç var |
| Test durumları | Kalite artefaktlarına hâlâ ihtiyaç var |
| İş senaryoları | İş akışı kapsamına hâlâ ihtiyaç var |
| Dokümantasyon | İnsan referansına hâlâ ihtiyaç var |
Eklenenler
| Eklenen Ne | Amaç |
|---|---|
| Yürütülebilir beceriler | Ajanlar iş akışlarını çağırabilir |
| Doğrulanabilir adımlar | Her aşamada kalite kontrolü yapılır |
| İzlenebilir zincirler | Ajan eylemleri denetlenebilir hale gelir |
Kısa formül:
Beceri Odaklı = Şartname Odaklı + Ajan yürütme katmanı
Sistem Mimarisi
Beceri Odaklı iş akışında her katmanın ayrı bir sorumluluğu vardır:
| Katman | Sorumluluk | Örnek |
|---|---|---|
| Apidog | API ve test varlıklarını yönetir | Uç noktalar, şemalar, test durumları, senaryolar |
| CLI | Deterministik yürütme sağlar | Komutlar, doğrulama, çıktı |
| BECERİ | Görev yargısı ve izlenecek yolları sağlar | İş akışı rehberliği, sıralama kuralları |
| Ajanlar | Hedefleri anlar, yürütür ve ayarlar | Claude Code, Cursor, Trae, Codex |
Birlikte nasıl çalışırlar?
Örnek istek:
Kullanıcı: "Geri ödeme API'si için testler oluştur ve doğrulama çalıştır"
Olası akış:
Kullanıcı hedefi belirtir
↓
Ajan görev türünü anlar
↓
BECERİ iş akışı yolunu belirlemesine yardım eder
↓
Ajan uç noktaları okumak için CLI'ı çağırır
↓
CLI deterministik çıktı döndürür
↓
Ajan test durumları oluşturur
↓
CLI yapıyı doğrular
↓
Ajan test durumlarını yazar
↓
CLI agentHints döndürür
↓
Ajan ipuçlarına göre geri okur ve ayarlar
↓
Ajan testleri çalıştırır
↓
CLI rapor döndürür
↓
Ajan sonucu kullanıcıya özetler
Bu ayrım önemlidir:
- Ajan hedefi anlar ve değişiklik üretir.
- CLI yürütür ve doğrular.
- BECERİ iş akışı bilgisini sağlar.
- İnsan hedefi belirler ve sonucu inceler.
İş Akışı Dönüşümü
Şartname Odaklı İş Akışı: İnsan Odaklı
İnsan şartnameyi tasarlar
↓
İnsan belgeler
↓
İnsan mock oluşturur
↓
İnsan hata ayıklaması yapar
↓
İnsan testler yazar
↓
İnsan yayınlar
| Yön | Açıklama |
|---|---|
| Sürücü | İnsan |
| Odak | İşbirliği |
| Geri Bildirim | Manuel inceleme |
| Hız | İnsan hızı |
| Hatalar | İnsan yakalar |
Beceri Odaklı İş Akışı: Ajan Destekli
İnsan hedefi belirtir
↓
Ajan mevcut varlıkları okur
↓
Ajan değişiklikler oluşturur
↓
CLI doğrular
↓
Ajan yazar
↓
CLI sonraki adımlara rehberlik eder
↓
Ajan doğrular
↓
İnsan sonucu inceler
| Yön | Açıklama |
|---|---|
| Sürücü | Ajan, insan hedefi tarafından yönlendirilir |
| Odak | Yürütme |
| Geri Bildirim | Otomatik doğrulama |
| Hız | Ajan hızı |
| Hatalar | CLI yakalar |
Ekipler Ne Yapmalı?
Beceri Odaklı yaklaşıma geçmek için büyük bir yeniden tasarım gerekmeyebilir. Küçük ve doğrulanabilir görevlerle başlayın.
1. Apidog CLI'ı yükleyin
npm install -g apidog-cli@latest
2. BECERİ'yi yükleyin
apidog skill install
3. Sürümü kontrol edin
apidog -v
Not: Serideki akışlar için 2.2.5+ sürümü gerekir.
4. Kimlik doğrulayın
apidog auth login
5. Projeleri listeleyin
apidog project list
6. Düşük riskli bir görevle başlayın
İlk görev, üretim açısından kritik olmayan küçük bir uç nokta veya test oluşturma işi olmalı.
İlk Ajan Görevi Örneği
Ajanınıza şu şekilde net, sınırlı ve doğrulanabilir bir görev verebilirsiniz:
Apidog CLI'yı kullanarak Apidog'da ilk API uç noktamı oluşturmama yardım et.
Önce Apidog CLI kurulumumu kontrol et ve erişebileceğim projeleri listele.
Hangi projeyi kullanacağımı bana sor.
Onayladıktan sonra, 200 yanıt örneği ile Sağlık Kontrolü adlı basit bir
GET /health uç noktası oluştur.
Yazmadan önce yapılandırılmış tüm girdiyi doğrula.
Ardından uç noktayı geri oku ve ne oluşturulduğunu özetle.
Bu görev birkaç iyi pratiği aynı anda uygular:
| Fayda | Açıklama |
|---|---|
| Kurulum kontrolü | Ajan önce ortamı doğrular |
| Proje seçimi | Ajan yazmadan önce kullanıcıdan seçim ister |
| Küçük oluşturma | İlk görev düşük risklidir |
| Doğrulama | Yazmadan önce yapı kontrol edilir |
| Geri okuma | Oluşturulan varlık tekrar kontrol edilir |
| Özet | İnsan net bir sonuç alır |
Başlangıç Komutları
Aşağıdaki komutları başlangıç kontrol listesi olarak kullanabilirsiniz:
# Apidog CLI'ı yükle
npm install -g apidog-cli@latest
# Eşlik eden BECERİ'yi yükle
apidog skill install
# Sürümü kontrol et
apidog -v
# Kimlik doğrula
apidog auth login
# Projeleri listele
apidog project list
Uygulama İçin Basit Kontrol Listesi
Ajan destekli API iş akışına geçerken şu sırayı izleyin:
1. CLI kurulumu var mı?
2. Kimlik doğrulama tamam mı?
3. Ajan erişebileceği projeleri listeleyebiliyor mu?
4. Yazmadan önce kullanıcıdan seçim istiyor mu?
5. Üreteceği veriyi doğruluyor mu?
6. Yazdıktan sonra geri okuyup kontrol ediyor mu?
7. Sonucu insanın anlayacağı şekilde özetliyor mu?
Bu kontrol listesi, Ajan'ın doğrudan yazma işlemi yapmadan önce bağlamı doğrulamasını sağlar.
Gelecek
API geliştirme iş akışlarında yön şu tarafa gidiyor:
| Trend | Yön |
|---|---|
| Ajan katılımı | Daha fazla API geliştirme görevi Ajanlar tarafından yürütülecek |
| CLI + BECERİ desenleri | Daha olgun ve standartlaştırılmış iş akışları oluşacak |
| Daha fazla Beceri | Farklı bağlamlar için alana özgü Beceri'ler ortaya çıkacak |
| Daha iyi yakınsama | Kritik düğümler için daha iyi mühendislik yapılacak |
| İnsan-Ajan işbirliği | İnsan ve Ajan arasında daha kesintisiz aktarım sağlanacak |
Gelecek, Ajan destekli API geliştirmesidir.
Serinin Tam Özeti
Bu seride şu yolculuğu ele aldık:
| Bölüm | Konu | Temel İçgörü |
|---|---|---|
| 1 | Problem | 126 MCP aracı → rastgele araçlardan oluşan duvar |
| 2 | Dönüm Noktası | Karmaşıklık bağlamdan mühendisliğe kaydı |
| 3 | Felsefe | CLI doğrular, Ajan oluşturur |
| 4 | Tasarım |
agentHints sonraki adımlara rehberlik eder |
| 5 | Deneyim | BECERİ iş akışı bilgisini paketler |
| 6 | Doğrulama | %30 daha az çağrı, %25 daha az token |
| 7 | Uygulama | PRD → OpenAPI → Testler → Doğrulama |
| 8 | Temel | CI/CD temel olmaya devam ediyor |
| 9 | Dürüstlük | Dört zorluk devam ediyor |
| 10 | Vizyon | Şartname Odaklı → Beceri Odaklı |
Son Prensip
Şartname Odaklı, insan işbirliği içindi. Beceri Odaklı, Ajan yürütmesi içindir.
| Dönem | Yaklaşım | Tüketici |
|---|---|---|
| Geleneksel | Şartname Odaklı | İnsanlar |
| Ajan Çağı | Beceri Odaklı | İnsanlar + Ajanlar |
Varlıklar çağrılabilir hale gelir. İş akışları yürütülebilir hale gelir. Kalite doğrulanabilir hale gelir.
Beceri Odaklı'ya hoş geldiniz.
Temel Çıkarımlar
- Şartname Odaklı yaklaşım, insan odaklı geliştirme için doğruydu.
- Ajanlar artık API varlıklarının tüketicileridir.
- API varlıkları okunabilir olmaktan çağrılabilir olmaya dönüşür.
- Beceri Odaklı yaklaşım, Şartname Odaklı yaklaşımın üzerine Ajan yürütme katmanı ekler.
- Sistem modeli: Apidog varlıkları yönetir, CLI yürütür, BECERİ yargılama sağlar, Ajan eyleme geçer.
- İnsan hedefi belirler, Ajan yürütür, CLI doğrular.
- Küçük başlayın, desenleri öğrenin, kapsamı kademeli olarak genişletin.
Tek bir çalışma alanında API'leri tasarlamak, mock'lamak, test etmek ve belgelemek için Apidog'u kullanabilirsiniz. Komut satırı API testi, CI otomasyonu ve Yapay Zeka Ajan iş akışları için Apidog CLI hakkında daha fazla bilgi edinin.
Top comments (0)