Esta es una serie de 10 partes que comparte cómo Apidog desarrolló Apidog CLI, una herramienta de línea de comandos para pruebas de API y gestión del ciclo de vida de las API. Léalo en orden o salte a cualquier publicación que le interese:
| Título | Enfoque | |
|---|---|---|
| 1 | Construimos 126 Herramientas MCP. Pero No Es la Mejor Solución para el Agente | Descubrimiento del problema |
| 2 | Por Qué Desarrollamos un Nuevo Apidog CLI | Desarrollo de arquitectura |
| 3 | La Regla de Oro: CLI Produce Hechos, el Modelo Actúa sobre los Hechos | Filosofía central |
| 4 | agentHints: Enseñando a los CLIs a Hablar con los Agentes |
Salida estructurada |
| 5 | SKILL: Empaquetando la Experiencia Operativa como Código | Experiencia operativa |
| 6 | Los Números No Mienten: 30% Menos Llamadas a Herramientas, 25% Menos Tokens | Resultados cuantitativos |
| 7 | De PRD a Bucle de Pruebas: Un Flujo de Trabajo Completo de Agente con Apidog CLI | Tutorial práctico |
| 8 | Por Qué la Compatibilidad CI/CD No Es Negociable para las Herramientas de Agente | Perspectiva DevOps |
| 9 | Rama de IA: Cambios de Proyecto Más Seguros con Agentes de IA | Capa de seguridad |
| 10 | Spec-First Fue Ayer. Bienvenido a Skill-First. | Visión y futuro |
El desarrollo de API está cambiando con los Agentes de IA. Skill-First empaqueta especificaciones, pruebas y escenarios en habilidades ejecutables y verificables, complementando los enfoques existentes para la era de los Agentes.
La Era Spec-First
Durante años, los procesos de colaboración de muchos equipos de desarrollo fueron Spec-First.
Qué Era
| Principio | Descripción |
|---|---|
| Diseñar APIs primero | Definir API antes de la implementación |
| Colaborar en torno a la documentación | Los equipos consultan la especificación compartida |
| Mockear temprano | El frontend puede desarrollarse contra el mock |
| Depurar juntos | Problemas visibles en formato compartido |
| Probar contra la especificación | Verificar que la implementación coincida con el diseño |
| Publicar cuando esté listo | Lanzar APIs documentadas y probadas |
El Valor
| Beneficio | Por Qué Importa |
|---|---|
| Contratos claros | Frontend/backend saben qué esperar |
| Desarrollo paralelo | Los equipos trabajan de forma independiente |
| Fricción reducida | La falta de comunicación se detecta temprano |
| Pruebas estables | Las pruebas coinciden con el comportamiento documentado |
| Documentación viva | La especificación evoluciona con el producto |
Spec-First fue el enfoque correcto para el desarrollo de API impulsado por humanos.
El Nuevo Consumidor: Agentes de IA
Después de la aparición de la Codificación de IA, los consumidores de los activos de API cambiaron.
Los Agentes también comenzaron a consumir estos activos.
Qué Necesitan los Agentes
| Actividad del Agente | Activo Necesario |
|---|---|
| Leer endpoints | Documentación de API |
| Añadir pruebas | Definiciones de endpoint, esquemas |
| Ejecutar automatización | Escenarios de prueba, entornos |
| Corregir código basado en informes | Detalles de fallos, datos de respuesta |
| Juzgar si el cambio es utilizable | Resultados de pruebas, cobertura |
En este contexto, la documentación de API, los casos de prueba y los escenarios de prueba en Apidog no son solo materiales de colaboración para humanos.
Son activos invocables de forma determinista para los Agentes.
Transformación de Activos
| Activo | Spec-First (Vista Humana) | Skill-First (Vista del Agente) |
|---|---|---|
| Documentación de API | Material de colaboración | Fuente de datos invocable |
| Casos de prueba | Artefacto de calidad | Verificación ejecutable |
| Escenarios de prueba | Flujo de trabajo de pruebas | Objetivo de automatización |
| Entornos | Configuración | Contexto de ejecución |
| Informes | Salida de revisión | Señal de retroalimentación |
Los activos se transforman de "legibles" a "invocables".
Definición de Skill-First
Construyendo sobre Spec-First:
| Qué Permanece | Por Qué |
|---|---|
| Especificaciones de endpoint | Aún se necesitan contratos claros |
| Casos de prueba | Aún se necesitan artefactos de calidad |
| Escenarios de negocio | Aún se necesita cobertura del flujo de trabajo |
| Documentación | Aún se necesita referencia humana |
Además:
| Qué se Añade | Propósito |
|---|---|
| Habilidades ejecutables | Los agentes pueden invocar flujos de trabajo |
| Pasos verificables | Compuertas de calidad en cada etapa |
| Cadenas rastreables | Registro de auditoría de las acciones del Agente |
Skill-First = Spec-First + Capa de ejecución de Agente.
La Arquitectura del Sistema
| Capa | Responsabilidad | Ejemplo |
|---|---|---|
| Apidog | Gestiona activos de API y pruebas | Endpoints, esquemas, casos de prueba, escenarios |
| CLI | Proporciona ejecución determinista | Comandos, validación, salida |
| SKILL | Proporciona juicio de tareas y rutas | Guía de flujo de trabajo, reglas de secuencia |
| Agentes | Comprenden objetivos, ejecutan, ajustan | Claude Code, Cursor, Trae, Codex |
Cada capa tiene un rol específico.
Cómo Trabajan Juntos
Usuario: "Generar pruebas para la API de reembolso y ejecutar verificación"
↓
Agente: Comprende el tipo de tarea (SKILL ayuda)
↓
Agente: Llama a CLI para leer endpoints (CLI ejecuta)
↓
Agente: Genera casos de prueba (Agente crea)
↓
CLI: Valida la estructura (cli-schema valida)
↓
Agente: Escribe casos de prueba (CLI ejecuta)
↓
CLI: Devuelve agentHints (CLI guía)
↓
Agente: Lee de vuelta, ajusta (Agente sigue las pistas)
↓
Agente: Ejecuta pruebas (CLI ejecuta)
↓
CLI: Devuelve informe (CLI proporciona retroalimentación)
↓
Agente: Resume al usuario (Agente completa)Transformación del Flujo de Trabajo
Flujo de Trabajo Spec-First (Impulsado por Humanos)
Humano diseña la especificación
↓
Humano documenta
↓
Humano crea mock
↓
Humano depura
↓
Humano escribe pruebas
↓
Humano publicaCaracterísticas:
| Aspecto | Descripción |
|---|---|
| Impulsor | Humano |
| Enfoque | Colaboración |
| Retroalimentación | Revisión manual |
| Velocidad | Ritmo humano |
| Errores | Humanos los detectan |
Flujo de Trabajo Skill-First (Asistido por Agente)
Humano especifica el objetivo
↓
Agente lee activos existentes
↓
Agente genera cambios
↓
CLI valida
↓
Agente escribe
↓
CLI guía los siguientes pasos
↓
Agente verifica
↓
Humano revisa el resultadoCaracterísticas:
| Aspecto | Descripción |
|---|---|
| Impulsor | Agente (guiado por el objetivo humano) |
| Enfoque | Ejecución |
| Retroalimentación | Validación automatizada |
| Velocidad | Ritmo de agente |
| Errores | CLI los detecta |
Qué Deben Hacer los Equipos
Pasos Inmediatos
| Paso | Acción |
|---|---|
| 1. Instalar | npm install -g apidog-cli@latest |
| 2. Instalar SKILL | apidog skill install |
| 3. Probar una tarea pequeña | Dar al Agente una tarea de bajo riesgo |
| 4. Aprender patrones | Observar el flujo de trabajo del Agente |
| 5. Expandir el alcance | Aumentar gradualmente la complejidad de la tarea |
Ejemplo de Primera Tarea de Agente
Usa Apidog CLI para ayudarme a crear mi primer endpoint de API en Apidog.
Primero, verifica la configuración de mi Apidog CLI y enumera los proyectos a los que puedo acceder.
Pregúntame qué proyecto usar. Después de que confirme, crea un simple endpoint GET /health
llamado Health Check con un ejemplo de respuesta 200. Valida cualquier
entrada estructurada antes de escribir, luego lee el endpoint de nuevo y resume
lo que se creó.Esto proporciona:
| Beneficio | Descripción |
|---|---|
| Verificación de configuración | El Agente verifica el entorno |
| Selección de proyecto | El Agente pregunta antes de escribir |
| Creación pequeña | Primera tarea de bajo riesgo |
| Validación | cli-schema antes de escribir |
| Relectura | Confirma lo que se creó |
| Resumen | El humano obtiene un resultado claro |
Comandos para Empezar
# Instalar Apidog CLI
npm install -g apidog-cli@latest
# Instalar SKILL acompañante
apidog skill install
# Verificar versión (necesita 2.2.5+)
apidog -v
# Autenticar
apidog auth login
# Listar proyectos
apidog project listEl Futuro
| Tendencia | Dirección |
|---|---|
| Participación de Agentes | Más tareas de desarrollo de API manejadas por Agentes |
| Patrones CLI + SKILL | Flujos de trabajo maduros y estandarizados |
| Más Skills | Skills específicas de dominio para diferentes contextos |
| Mejor convergencia | Ingeniería mejorada para nodos críticos |
| Colaboración Humano-Agente | Transferencia fluida entre humanos y Agentes |
El futuro es el desarrollo de API asistido por Agentes.
Resumen Completo de la Serie
Hemos cubierto todo el recorrido:
| Parte | Tema | Idea Clave |
|---|---|---|
| 1 | Problema | 126 herramientas MCP → muro de herramientas aleatorias |
| 2 | Pivote | La complejidad pasó del contexto a la ingeniería |
| 3 | Filosofía | CLI valida, Agente genera |
| 4 | Diseño | agentHints guía los siguientes pasos |
| 5 | Experiencia | SKILL empaqueta el conocimiento del flujo de trabajo |
| 6 | Validación | 30% menos llamadas, 25% menos tokens |
| 7 | Práctica | PRD → OpenAPI → Pruebas → Verificación |
| 8 | Fundamento | CI/CD sigue siendo la base |
| 9 | Honestidad | Quedan cuatro desafíos |
| 10 | Visión | Spec-First → Skill-First |
El Principio Final
Spec-First era para la colaboración humana. Skill-First es para la ejecución del Agente.
| Era | Enfoque | Consumidor |
|---|---|---|
| Tradicional | Spec-First | Humanos |
| Era de los Agentes | Skill-First | Humanos + Agentes |
Los activos se vuelven invocables. Los flujos de trabajo se vuelven ejecutables. La calidad se vuelve verificable.
Bienvenido a Skill-First.
Puntos Clave
- Spec-First era lo correcto para el desarrollo impulsado por humanos
- Los Agentes son ahora consumidores de activos de API
- Los activos se transforman de legibles a invocables
- Skill-First = Spec-First + ejecución de Agente
- Sistema: Apidog (activos) → CLI (ejecución) → SKILL (juicio) → Agentes (acción)
- El humano especifica el objetivo, el Agente ejecuta, el CLI valida
- Comience poco a poco, aprenda patrones, amplíe el alcance
Descargue Apidog para diseñar, simular, probar y documentar APIs en un solo espacio de trabajo. Obtenga más información sobre Apidog CLI para pruebas de API de línea de comandos, automatización CI y flujos de trabajo de Agentes de IA.