Esta es una serie de 10 partes sobre 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 API. Puede leerla en orden o ir directamente a la parte que necesite.
| Título | Enfoque | |
|---|---|---|
| 1 | Creamos 126 herramientas MCP. Pero no es la mejor solución para el Agente | Descubrimiento de problemas |
| 2 | Por qué desarrollamos el nuevo Apidog CLI | Desarrollo de arquitectura |
| 3 | La regla de oro: CLI produce hechos, el modelo actúa sobre hechos | Filosofía central |
| 4 | agentHints: Enseñando a los CLIs a hablar con los Agentes |
Salida estructurada |
| 5 | HABILIDAD: Entregando la experiencia operativa como código | Experiencia operativa |
| 6 | Los números no mienten: 30% menos de llamadas a herramientas, 25% menos de tokens | Resultados cuantitativos |
| 7 | Del PRD al ciclo de pruebas: Un flujo de trabajo completo del Agente con Apidog CLI | Tutorial práctico |
| 8 | Por qué la compatibilidad con CI/CD no es negociable para las herramientas del 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 |
Cuando un Agente modifica recursos del proyecto, necesita aislamiento, revisión y control de alcance. La Rama de IA proporciona una rama de edición separada; los cambios solo llegan a la rama de destino después de una confirmación humana.
El desafío de seguridad
Cuando un Agente de IA participa en el desarrollo o las pruebas de API, puede crear, actualizar y eliminar recursos mediante comandos CLI.
Ese poder introduce riesgos operativos:
| Riesgo | Qué puede pasar |
|---|---|
| Resultados impredecibles | El Agente escribe contenido inesperado |
| Errores de campo | Aserciones incorrectas, parámetros faltantes |
| Expansión del alcance | El Agente modifica recursos fuera de la tarea |
| Sin rastro de revisión | Los cambios aparecen directamente en la rama principal |
| Disrupción del equipo | La rama compartida cambia sin aviso |
La pregunta práctica es:
¿Cómo permitir que los Agentes trabajen sobre proyectos reales sin exponer la rama principal?
Rama de IA: la capa de seguridad
La Rama de IA es un tipo especial de Rama de Sprint diseñada para operaciones externas de IA y CLI.
Concepto clave:
Todas las operaciones de edición iniciadas desde Apidog CLI se tratan como iniciadas por IA / Agentes de IA por defecto.
En lugar de escribir directamente en main, el Agente escribe en una rama aislada:
El Agente realiza cambios mediante CLI
↓
Los cambios se guardan en la Rama de IA
↓
El usuario revisa las diferencias
↓
El usuario confirma el alcance de los recursos
↓
Los cambios se fusionan en la rama de destino
La rama principal permanece intacta hasta que usted apruebe la fusión.
Cuándo usar una Rama de IA
Use una Rama de IA cuando el Agente vaya a modificar recursos del proyecto, por ejemplo:
- Endpoints
- Esquemas/modelos de datos
- Escenarios de prueba
- Suites de prueba
- Documentación de API
- Estructura de carpetas o recursos relacionados
Comparación práctica:
| Sin Rama de IA | Con Rama de IA |
|---|---|
| El Agente escribe directamente en la principal | El Agente escribe en una rama aislada |
| Los cambios aparecen inmediatamente | Los cambios esperan revisión |
| No hay red de seguridad | Se requiere confirmación humana |
| Riesgo de modificaciones no intencionadas | Alcance limitado a recursos específicos |
Qué es la Rama de IA
La Rama de IA es una rama de sprint especial con reglas orientadas a seguridad.
| Característica | Descripción |
|---|---|
| Edición aislada | Los cambios se almacenan en la Rama de IA y no afectan la rama principal o de origen |
| Origen claro | No se crea desde el cliente; debe provenir de CLI/MCP y registra la rama de origen |
| Confirmación humana | Los cambios deben revisarse y confirmarse antes de fusionar |
| Sin límite de cantidad | Puede crear tantas Ramas de IA como necesite |
| Archivado automático | Las ramas sin diferencias se archivan cada 24 horas |
Flujo de responsabilidad:
| Operación | Dónde ocurre |
|---|---|
| La IA crea un endpoint | En la Rama de IA |
| La IA actualiza un escenario de prueba | En la Rama de IA |
| El equipo revisa cambios | En el cliente o en la vista previa de CLI |
| El usuario aprueba la fusión | Acción del usuario, no de la IA |
| Los cambios entran en la rama de destino | Después de la confirmación |
La edición normal desde el cliente sigue usando las reglas de permisos del proyecto y la protección de ramas.
Casos de uso
La Rama de IA es útil cuando la IA debe contribuir al mantenimiento del proyecto sin perder control humano.
| Escenario | Cómo ayuda la Rama de IA |
|---|---|
| Generar borradores de API desde código | La IA crea endpoints en la Rama de IA; el usuario revisa antes de fusionar |
| Organizar recursos de API en masa | La IA ajusta carpetas, descripciones y modelos sin afectar la rama compartida |
| Generar pruebas automatizadas | La IA crea escenarios o casos de prueba para revisión |
| Completar documentación de API | La IA rellena campos faltantes basándose en implementación o reportes |
| Escritura por lotes en CI/CD | Los flujos automatizados escriben en una Rama de IA y esperan fusión manual |
Flujo de trabajo básico
Un flujo típico con Rama de IA tiene cinco pasos:
1. Crear Rama de IA
apidog branch create --type ai
2. Importar o crear recursos
apidog branch pick-to
o
apidog endpoint create
3. Modificar recursos con IA
Usar --branch <nombreRamaIA>
4. Revisar diferencias
apidog merge-request preview
o revisar en el cliente Apidog
5. Fusionar en la rama de destino
branch merge
o
merge-request create
1. Crear una Rama de IA
Use branch create --type ai:
apidog branch create \
--project 123456 \
--type ai \
--name "ai/2026-03-12-from-main-userRegister" \
--from main
Convención recomendada:
ai/AAAA-MM-DD-from-ramaOrigen-moduloOTarea
Comandos útiles:
| Comando | Propósito |
|---|---|
branch create --type ai |
Crear una Rama de IA |
branch list --type ai |
Ver Ramas de IA del proyecto |
branch list --type all |
Ver todos los tipos de ramas |
branch get --type ai |
Ver detalles de una Rama de IA |
2. Editar recursos en una Rama de IA
Cuando CLI escriba recursos del proyecto, especifique la rama con --branch.
| Recurso | Ejemplo |
|---|---|
| Endpoint HTTP | apidog endpoint create --project <id> --branch <nombreRamaIA> --file ./endpoint.json |
| Modelo de datos | apidog schema update <schemaId> --project <id> --branch <nombreRamaIA> --file ./schema.json |
| Escenario de prueba | apidog test-scenario update <scenarioId> --project <id> --branch <nombreRamaIA> --file ./scenario.json |
| Suite de pruebas | apidog test-suite create --project <id> --branch <nombreRamaIA> --file ./suite.json |
Flujo recomendado antes de escribir:
# 1. Obtener el esquema esperado por el comando
apidog cli-schema get endpoint-create
# 2. Validar el archivo local antes de escribir
apidog cli-schema validate endpoint-create --file ./endpoint.json
# 3. Escribir en la Rama de IA, no en main
apidog endpoint create \
--project 123456 \
--branch "ai/2026-03-12-from-main-userRegister" \
--file ./endpoint.json
3. Importar recursos existentes antes de editarlos
Si el Agente debe modificar recursos existentes, impórtelos primero desde la rama de origen:
apidog branch pick-to \
--project 123456 \
--from main \
--to "ai/2026-03-12-from-main-userRegister" \
--endpoint-ids 1001,1002
Esto ayuda a que la IA trabaje sobre la versión base correcta y reduce conflictos de contexto.
4. Revisar cambios antes de fusionar
Antes de fusionar, previsualice las diferencias:
apidog merge-request preview \
--project 123456 \
--from "ai/2026-03-12-from-main-userRegister" \
--to main
También puede revisar la diferencia completa desde el cliente Apidog.
| Comando | Propósito |
|---|---|
merge-request preview |
Escanear cambios candidatos |
branch get --type ai |
Ver información de la Rama de IA |
Checklist mínimo de revisión:
- ¿El Agente modificó solo los recursos esperados?
- ¿Los endpoints tienen métodos, rutas y parámetros correctos?
- ¿Los esquemas referenciados existen?
- ¿Las pruebas contienen aserciones válidas?
- ¿Faltan dependencias como carpetas, modelos o componentes de respuesta?
5. Fusionar una Rama de IA
Después de revisar, hay dos rutas: fusión directa o solicitud de fusión.
Fusión directa para ramas no protegidas
apidog branch merge \
--project 123456 \
--from "ai/2026-03-12-from-main-userRegister" \
--to main \
--endpoint-ids 1001,1002
Solicitud de fusión para ramas protegidas
apidog merge-request create \
--project 123456 \
--from "ai/2026-03-12-from-main-userRegister" \
--to main \
--reviewer-ids 20001,20002 \
--endpoint-ids 1001,1002
Comandos relacionados:
| Comando | Propósito |
|---|---|
branch merge |
Fusionar directamente en una rama no protegida |
merge-request create |
Crear una solicitud de fusión |
merge-request approve |
Aprobar una solicitud de fusión |
merge-request reject |
Rechazar una solicitud de fusión |
Importante: los comandos de fusión procesan solo la lista de recursos explícitamente proporcionada. Confirme dependencias como directorios, modelos, componentes de respuesta y pruebas antes de fusionar.
Archivar y eliminar Ramas de IA
Cuando los cambios ya se fusionaron o la rama dejó de ser útil:
# Archivar
apidog branch archive "ai/2026-03-12-from-main-userRegister" \
--project 123456 \
--type ai
# Eliminar después de archivar
apidog branch delete "ai/2026-03-12-from-main-userRegister" \
--project 123456 \
--type ai
Mantener limpias las ramas reduce ruido para revisores y Agentes.
Permisos de edición de IA externa
Por defecto, CLI escribe en la Rama de IA para mantener aislados los cambios generados por IA.
Para habilitar edición directa de otras ramas:
Configuración del Proyecto
→ Configuración de Características
→ Configuración de Características de IA
→ Permisos de Edición de IA Externa
| Permiso | Lo que permite |
|---|---|
| Edición directa de la rama principal | CLI escribe directamente en main y omite la Rama de IA |
| Edición directa de rama de sprint estándar | CLI escribe directamente en ramas de sprint |
| Edición directa de rama general | CLI escribe directamente en ramas generales |
| Edición directa de la Rama de IA | CLI escribe en Ramas de IA |
Recomendación: mantenga habilitado el aislamiento de la Rama de IA. Use edición directa solo cuando el flujo de automatización lo requiera claramente y exista una revisión equivalente.
Mejores prácticas
| Práctica | Por qué |
|---|---|
| Una Rama de IA por tarea | Mantiene el alcance claro: registro de usuario, módulo de pedidos, pruebas de pago |
| Importar antes de editar | Use pick-to para recursos existentes y evite confusión de origen |
| Validar antes de escribir | Use cli-schema validate para detectar errores estructurales |
| Previsualizar antes de fusionar | Use merge-request preview o la vista de diferencias del cliente |
| Definir alcance explícito de fusión | Fusione endpoints, modelos, directorios y pruebas relacionados juntos |
| Mantener revisión humana | Las definiciones de API y scripts de prueba deben revisarse antes de fusionar |
| Archivar rápido | Mantiene la lista de ramas limpia después de fusionar o descartar cambios |
Rama de IA en un flujo CLI + HABILIDAD
La Rama de IA encaja naturalmente en un flujo CLI + HABILIDAD:
| Etapa | Acción |
|---|---|
| Leer |
endpoint get desde cualquier rama |
| Generar | El Agente crea JSON |
| Validar |
cli-schema validate localmente |
| Escribir | endpoint create --branch <nombreRamaIA> |
| Revisar | merge-request preview |
| Fusionar | El usuario confirma y ejecuta branch merge
|
| Verificar |
apidog run sobre los recursos fusionados |
Patrón recomendado:
Rama de IA → revisión humana → fusión → verificación
Resumen de seguridad
La seguridad no depende de una sola capa. El flujo combina validación, aislamiento y revisión.
| Capa | Protección |
|---|---|
cli-schema validate |
Detecta errores estructurales antes de escribir |
agentHints |
Guía al Agente hacia pasos seguros |
| Rama de IA | Aísla cambios de la rama principal |
| Revisión humana | Confirma contenido antes de fusionar |
| Alcance de fusión | El usuario selecciona qué recursos fusionar |
Juntas, estas capas crean un bucle más seguro para cambios de proyecto impulsados por Agentes.
Qué sigue
Con la Rama de IA como capa de seguridad, el flujo queda completo:
- MCP para conexión de herramientas — Parte 1
- CLI + HABILIDAD para ejecución del flujo — Partes 2-5
- Resultados de validación — Parte 6
- Flujos de trabajo prácticos — Parte 7
- Fundamentos de CI/CD — Parte 8
- Rama de IA para seguridad — Parte 9
En la Parte 10, Spec-First fue ayer. Bienvenido a Skill-First., veremos cómo evoluciona el desarrollo de API con Agentes de IA y qué deberían preparar los equipos.
Puntos clave
- La Rama de IA proporciona edición aislada para operaciones de IA/CLI.
- Los cambios no afectan la rama principal hasta que una persona los confirma.
- Cree la rama con
branch create --type ai. - Escriba recursos usando
--branch <nombreRamaIA>. - Importe recursos existentes con
branch pick-toantes de editarlos. - Revise cambios con
merge-request preview. - Fusione directamente o cree una solicitud de fusión según la protección de la rama.
- Use permisos de edición directa con cuidado.
- Mejor práctica: una Rama de IA por tarea, validar antes de escribir y revisar antes de fusionar.
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.
Top comments (0)