Ini adalah seri 10 bagian yang menceritakan bagaimana Apidog mengembangkan Apidog CLI, sebuah alat baris perintah untuk pengujian API dan manajemen siklus hidup API. Bacalah secara berurutan atau lompat ke postingan mana pun yang menarik minat Anda:
| Judul | Fokus | |
|---|---|---|
| 1 | Kami Membangun 126 Alat MCP. Tapi Itu Bukan Solusi Terbaik untuk Agen | Penemuan masalah |
| 2 | Mengapa Kami Mengembangkan Apidog CLI yang Benar-benar Baru | Pengembangan arsitektur |
| 3 | Aturan Emas: CLI Menghasilkan Fakta, Model Bertindak Berdasarkan Fakta | Filosofi inti |
| 4 | agentHints: Mengajarkan CLI untuk Berkomunikasi dengan Agen |
Output terstruktur |
| 5 | SKILL: Mengirimkan Pengalaman Operasional sebagai Kode | Pengalaman operasional |
| 6 | Angka Tidak Bohong: 30% Lebih Sedikit Panggilan Alat, 25% Lebih Sedikit Token | Hasil kuantitatif |
| 7 | Dari PRD ke Lingkaran Pengujian: Alur Kerja Agen Lengkap dengan Apidog CLI | Tutorial praktis |
| 8 | Mengapa Kompatibilitas CI/CD Tidak Dapat Ditawar untuk Alat Agen | Perspektif DevOps |
| 9 | Cabang AI: Perubahan Proyek yang Lebih Aman dengan Agen AI | Lapisan keamanan |
| 10 | Spec-First Adalah Kemarin. Selamat Datang di Skill-First. | Visi & masa depan |
Kami membandingkan MCP vs. CLI + SKILL di berbagai tugas pengguna umum. Hasilnya: panggilan alat yang lebih sedikit, pemborosan token yang lebih kecil, pemulihan kesalahan yang lebih baik—dan data menjelaskan alasannya.
Pertanyaan yang Penting
Semua filosofi dan prinsip desain yang telah kami bagikan—apakah mereka benar-benar berfungsi?
Kami secara internal membandingkan banyak tugas pengguna umum di kedua pendekatan:
| Jenis Tugas | Deskripsi |
|---|---|
| Menambahkan kasus uji + verifikasi | Buat kasus uji untuk endpoint, jalankan pengujian |
| Memelihara skenario pengujian | Perbarui skenario multi-langkah yang kompleks |
| Mengimpor/memverifikasi aset proyek | Impor data, konfirmasi struktur, jalankan pengujian |
Hasilnya bukan hanya peningkatan subjektif. Mereka adalah pengurangan terukur.
Tugas 1: Tambahkan Kasus Uji Berdasarkan Endpoint
Permintaan pengguna:
"Tambahkan pengujian untuk endpoint ini dan jalankan verifikasi"
Rute MCP
| Tahap | Apa yang Terjadi |
|---|---|
| Penemuan alat | Agen mencari melalui daftar alat |
| Pemilihan alat | Beberapa putaran pemilihan alat yang benar |
| Penemuan kolom | Agen membaca skema alat |
| Penebakan kolom | Agen menebak kolom yang diperlukan |
| Upaya penulisan | Agen memanggil alat buat |
| Respons kesalahan | Server menolak (kolom salah/persyaratan hilang) |
| Coba lagi | Agen menyesuaikan, mencoba lagi |
| Lebih banyak percobaan | Ulangi sampai berhasil |
| Jalankan pengujian | Agen menemukan alat jalankan, mengeksekusi |
Pola umum:
Cari alat → Pilih alat → Baca skema → Tebak kolom → Tulis → Error → Coba lagi → Tulis → Error → Coba lagi → Berhasil → Temukan alat jalankan → JalankanRute CLI + SKILL
| Tahap | Apa yang Terjadi |
|---|---|
| Panduan SKILL | SKILL mengidentifikasi jenis tugas, menyediakan alur kerja |
| Baca endpoint | CLI membaca fakta endpoint |
| Hasilkan kasus uji | Agen menghasilkan berdasarkan data endpoint aktual |
| Validasi secara lokal | cli-schema memvalidasi sebelum menulis |
| Tulis | CLI membuat kasus uji |
| Baca kembali | CLI mengembalikan struktur yang dibuat + agentHints |
| Jalankan pengujian | agentHints menyarankan menjalankan, Agen mengikuti |
Pola umum:
SKILL memandu → Baca endpoint → Hasilkan → Validasi → Tulis → Baca kembali → JalankanHasil
| Metrik | Rute MCP | CLI + SKILL | Peningkatan |
|---|---|---|---|
| Langkah panggilan alat | ~15-20 | ~10-12 | ↓ ~30% |
| Token dari deskripsi | ~50.000 dimuat | ~2.000 dimuat | ↓ ~96% |
| Token dari percobaan ulang | ~5.000+ terbuang | ~500 terbuang | ↓ ~90% |
| Total pemborosan token | ~55.000 | ~2.500 | ↓ ~25% |
Langkah panggilan alat berkurang sekitar 30%. Konsumsi token dari deskripsi alat yang tidak valid dan percobaan ulang kesalahan berkurang sekitar 25%.
Tugas 2: Penulisan Terstruktur (Pemroses, Penegasan, Ekstraktor)
Permintaan pengguna:
"Tambahkan penegasan pasca-operasi dan ekstraksi variabel ke kasus uji ini"
Rute MCP
| Tahap | Apa yang Terjadi |
|---|---|
| Tebak nama kolom | Agen tidak tahu nama persisnya |
| Tebak nilai enum | Agen menebak pembanding, tipe |
| Upaya penulisan | Server menolak nilai yang salah |
| Coba lagi jaringan | Bolak-balik untuk setiap kesalahan |
| Beberapa upaya | 3-5 percobaan ulang umum |
Kesalahan umum:
| Tebakan Salah | Nilai Benar | Jumlah Percobaan |
|---|---|---|
comparator: "contains" |
comparator: "include" |
1-2 |
type: "global" |
type: "globals" |
1-2 |
subject: "responseBody" |
subject: "responseJson" |
1-2 |
Setiap kesalahan = 1 bolak-balik jaringan + respons + pemrosesan Agen.
Rute CLI + SKILL
| Tahap | Apa yang Terjadi |
|---|---|
| Baca kasus uji | CLI mendapatkan struktur aktual |
| Hasilkan penambahan | Agen menghasilkan berdasarkan format sebenarnya |
| Validasi secara lokal | cli-schema menangkap kesalahan sebelum jaringan |
| Perbaiki secara lokal | Agen menyesuaikan berdasarkan output validasi |
| Validasi ulang | Konfirmasi perbaikan |
| Tulis | Hanya penulisan yang valid yang dikirim ke server |
Semua kesalahan ditangkap secara lokal. Tidak ada percobaan ulang jaringan untuk kesalahan kolom.
Hasil
| Metrik | Rute MCP | CLI + SKILL | Peningkatan |
|---|---|---|---|
| Percobaan ulang jaringan dari kesalahan struktural | 3-5 | 0 | ↓ ~100% |
| Token dari respons kesalahan | ~2.000 | ~0 | ↓ ~100% |
| Total panggilan berulang | ~5 | ~1 | ↓ ~40% |
Panggilan berulang dari kesalahan struktural berkurang sekitar 40%.
Tugas 3: Operasi Berkelanjutan Setelah Pembuatan
Permintaan pengguna:
"Buat skenario pengujian dengan endpoint ini"
Rute MCP
| Tahap | Apa yang Terjadi |
|---|---|
| Buat skenario | Agen memanggil alat buat |
| Respons berhasil | Agen melihat "dibuat" |
| Lanjutkan menulis | Agen segera memperbarui/menambahkan lebih banyak |
| Lewati baca-balik | Agen tidak membaca struktur aktual |
| Tulis berdasarkan asumsi | Agen menulis dengan ID/struktur yang ditebak |
| Kesalahan atau tidak lengkap | Hasil tidak sesuai harapan |
Masalah: Inersia eksekusi.
Model cenderung langsung melanjutkan setelah berhasil, melewatkan langkah baca-balik.
Rute CLI + SKILL
| Tahap | Apa yang Terjadi |
|---|---|
| Buat skenario | CLI membuat skenario |
| Berhasil + agentHints | CLI mengembalikan berhasil + saran langkah selanjutnya |
agentHints: "Baca kembali dulu" |
Agen melihat saran |
| Ikuti saran | Agen membaca kembali |
| Bekerja dengan struktur nyata | Agen melanjutkan dengan data yang akurat |
agentHints secara eksplisit menyarankan baca-balik. Agen mengikuti.
Hasil
| Metrik | Rute MCP | CLI + SKILL | Peningkatan |
|---|---|---|---|
| Proporsi yang membaca kembali sebelum melanjutkan | ~20% | ~85% | ↑ ~425% |
| Percobaan ulang kesalahan dari lompatan langsung | ~3-5 | ~0-1 | ↓ ~21% |
Proporsi Agen yang secara proaktif membaca kembali, memvalidasi, dan menjalankan verifikasi meningkat secara signifikan. Percobaan ulang kesalahan dari langsung melompat ke langkah berikutnya berkurang sekitar 21%.
Ringkasan: Dari Mana Penghematan Berasal
| Sumber Penghematan | Penjelasan |
|---|---|
| Penemuan alat | Perintah CLI memiliki nama yang jelas; SKILL memandu pemilihan |
| Validasi skema | Validasi lokal menangkap kesalahan sebelum panggilan jaringan |
| Pemulihan kesalahan | agentHints memberikan saran yang dapat ditindaklanasi, bukan hanya "gagal" |
| Panduan baca-balik | Mencegah penulisan berdasarkan asumsi |
| Urutan alur kerja | SKILL mengurangi titik keputusan |
Analisis Biaya Nyata
Wawasan utama:
Pengaktifan agen produk bukan tentang semakin banyak alat, semakin baik.
Apa yang sebenarnya dikonsumsi model:
| Jenis Biaya | Beban MCP | Beban CLI + SKILL |
|---|---|---|
| Konteks | Deskripsi alat, skema | SKILL yang berfokus pada tugas saja |
| Perhatian | Memilih di antara banyak alat | Mengikuti alur kerja yang dipandu |
| Pemilihan jalur | Menebak urutan | Urutan yang ditentukan SKILL |
| Biaya token pengguna | Percobaan ulang, panggilan gagal | Penulisan yang divalidasi, panggilan yang lebih sedikit |
Setelah jumlah alat meningkat, apa yang sebenarnya dikonsumsi model bukanlah kemampuan panggilan API, melainkan pertukaran antara konteks, perhatian, pemilihan jalur, dan biaya token pengguna.
Prinsip Rekayasa
Tujuan:
Memindahkan biaya-biaya ini keluar dari konteks model dan kembali ke posisi yang dapat ditanggung oleh sistem rekayasa.
| Biaya | Lokasi MCP | Lokasi CLI + SKILL |
|---|---|---|
| Penemuan alat | Model harus mencari | SKILL menyediakan |
| Validasi kolom | Model harus tahu | cli-schema memvalidasi |
| Panduan langkah berikutnya | Model harus memutuskan | agentHints menyarankan |
| Semantik produk | Model harus memahami | CLI menangani |
Sistem rekayasa menyerap kompleksitas. Model berfokus pada pembuatan dan penilaian.
Apa Arti Angka-angka Ini
Angka-angka ini menjelaskan masalah yang lebih spesifik:
| Wawasan | Implikasi |
|---|---|
| 30% lebih sedikit panggilan alat | Kompleksitas dipindahkan dari penemuan ke panduan |
| 25% lebih sedikit token yang terbuang | Kesalahan ditangkap sebelum jaringan |
| 40% lebih sedikit percobaan ulang struktural | Gerbang validasi berfungsi |
| 21% lebih sedikit kesalahan lompatan | agentHints mencegah kelanjutan buta |
CLI + SKILL bukan hanya keanggunan arsitektur. Ini adalah efisiensi yang terukur.
Apa Selanjutnya
Sekarang setelah kami memvalidasi pendekatan dengan angka, mari kita lihat aksinya.
Di Bagian 7, Dari PRD ke Lingkaran Pengujian: Alur Kerja Agen Lengkap, kami akan membahas contoh nyata—sebuah tim memiliki PRD "Pengembalian Dana Pesanan", dan Agen menggunakan CLI + SKILL untuk menghasilkan OpenAPI, membuat pengujian, memvalidasi, dan memverifikasi.
Poin-Poin Penting
- Langkah panggilan alat berkurang sekitar 30%
- Pemborosan token dari deskripsi dan percobaan ulang berkurang sekitar 25%
- Percobaan ulang kesalahan struktural berkurang sekitar 40%
- Kesalahan lompatan dari melewati baca-balik berkurang sekitar 21%
- Penghematan berasal dari: penemuan terpandu, validasi lokal, petunjuk yang dapat ditindaklanasi
- Kompleksitas dipindahkan dari konteks ke sistem rekayasa
Unduh Apidog untuk mendesain, membuat mock, menguji, dan mendokumentasikan API dalam satu ruang kerja. Pelajari lebih lanjut tentang Apidog CLI untuk pengujian API baris perintah, otomatisasi CI, dan alur kerja Agen AI.