Rama de IA: Cambios de proyecto más seguros con Agentes de IA

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 la API. Léala 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 el Nuevo Apidog CLI	Desarrollo de la arquitectura
3	La Regla de Oro: La CLI Produce Hechos, el Modelo Actúa sobre Hechos	Filosofía central
4	`agentHints`: Enseñando a las CLIs a Hablar con los Agentes	Salida estructurada
5	SKILL: Enviando Experiencia Operacional como Código	Experiencia operacional
6	Los Números no Mienten: 30% Menos de Llamadas a Herramientas, 25% Menos de Tokens	Resultados cuantitativos
7	Del PRD al Bucle 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 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

Cuando un Agente modifica recursos del proyecto, la seguridad y la capacidad de revisión importan. La Rama de IA proporciona un entorno de edición aislado; los cambios entran en la rama de destino solo después de la confirmación humana.

El Desafío de la Seguridad

Cuando los Agentes de IA participan en el desarrollo y las pruebas de API, pueden crear, actualizar y eliminar recursos del proyecto a través de comandos CLI.

Este poder conlleva un riesgo.

Riesgo	Qué podría pasar
Resultados impredecibles	El Agente escribe contenido inesperado
Errores de campo	Aserciones incorrectas, parámetros faltantes
Expansión del alcance	El Agente modifica recursos más allá de la tarea
Sin rastro de revisión	Los cambios aparecen directamente en la rama principal
Disrupción del equipo	La rama de colaboración compartida cambia repentinamente

¿Cómo permite que los Agentes trabajen en proyectos reales sin poner en riesgo la rama principal?

Rama de IA: La Capa de Seguridad

La Rama de IA es un tipo especial de Rama de Sprint diseñada específicamente para operaciones externas de IA y CLI.

Concepto clave:

Todas las operaciones de edición iniciadas desde Apidog CLI son tratadas como iniciadas por IA / Agentes de IA por defecto.

La Rama de IA proporciona a los Agentes de IA una rama de edición aislada. Los cambios permanecen en la Rama de IA hasta que un humano los revisa y los fusiona.

El Agente realiza cambios a través de CLI
        ↓
Cambios almacenados en la Rama de IA (aislada)
        ↓
El usuario revisa las diferencias
        ↓
El usuario confirma el alcance de los recursos
        ↓
Fusión a la rama de destino (directa o solicitud de fusión)

La rama principal permanece intacta hasta que usted la apruebe.

Por qué se necesita la Rama de IA

Las ediciones iniciadas por IA pueden ser impredecibles. Apidog CLI ofrece una amplia gama de capacidades de edición: endpoints, esquemas, escenarios de prueba, suites de prueba y más.

La Rama de IA está diseñada para estas operaciones de edición iniciadas por IA de mayor riesgo.

Permite a los Agentes de IA editar recursos del proyecto dentro de un alcance controlado:

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
Sin 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 características específicas:

Características clave

Característica	Descripción
Edición aislada	Los cambios se almacenan en la Rama de IA, no afectan la rama principal o de origen
Origen claro	No se puede crear en el cliente; debe provenir de CLI/MCP; registra la rama de origen
Confirmación humana	Los cambios deben confirmarse antes de la fusión
Sin límite de cantidad	Cree tantas Ramas de IA como necesite para diferentes tareas
Archivado automático	Las ramas sin diferencias se archivan cada 24 horas

Cómo funciona

Operación	Dónde ocurre
La IA crea un endpoint	En la Rama de IA
La IA actualiza el escenario de prueba	En la Rama de IA
El equipo revisa los 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 en el cliente por parte de los usuarios sigue las reglas de permisos de miembros del proyecto y protección de ramas.

Casos de uso

La Rama de IA es adecuada cuando la IA necesita participar en el mantenimiento del proyecto, preservando al mismo tiempo el aislamiento de las ramas y la confirmación humana.

Escenario	Cómo ayuda la Rama de IA
Generar borradores de API a partir del código	La IA crea endpoints en la Rama de IA; los usuarios confirman antes de fusionar
Organizar recursos de API en masa	La IA ajusta carpetas, descripciones, modelos sin afectar la rama de colaboración
Generar borradores de pruebas automatizadas	La IA crea escenarios/casos de prueba en la Rama de IA para revisión del probador
Rellenar vacíos en la documentación de la API	La IA complementa campos faltantes basándose en informes de errores o implementación
Escritura por lotes en CI/CD	Los flujos de trabajo automatizados escriben en la Rama de IA, esperan la fusión del usuario

Flujo de Trabajo Básico

Un flujo de trabajo típico de Rama de IA:

┌─────────────────────────────────────────────────────────────────┐
│                     FLUJO DE TRABAJO DE RAMA DE IA               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Paso 1: Crear Rama de IA                                        │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog branch create --type ai             │                  │
│  │ --name "ai/20260312-from-main-feature"     │                  │
│  │ --from main                                │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Paso 2: Importar o Crear Recursos                               │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog branch pick-to (importar existentes) │                  │
│  │ O                                          │                  │
│  │ apidog endpoint create (crear nuevos)      │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Paso 3: La IA Modifica Recursos                                 │
│  ┌───────────────────────────────────────────┐                  │
│  │ El Agente usa CLI para actualizar endpoints,│                  │
│  │ esquemas, escenarios de prueba, etc.       │                  │
│  │ (el parámetro --branch especifica la Rama de IA)│                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Paso 4: El usuario revisa las diferencias                      │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog merge-request preview              │                  │
│  │ O                                          │                  │
│  │ Ver en el cliente Apidog                  │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Paso 5: Fusionar a la Rama de Destino                           │
│  ┌───────────────────────────────────────────┐                  │
│  │ Fusión directa (rama no protegida)         │                  │
│  │ O                                          │                  │
│  │ Solicitud de fusión (rama protegida)      │                  │
│  └───────────────────────────────────────────┘                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Crear una Rama de IA

Use branch create --type ai:

apidog branch create \
  --project 123456 \
  --type ai \
  --name "ai/20260312-from-main-userRegister" \
  --from main

Recomendación de nombres: ai/AAAA-MM-DD-desde-RamaOrigen-caracteristicaOModulo

Comando	Propósito
`branch create --type ai`	Crear Rama de IA
`branch list --type ai`	Ver Ramas de IA en el proyecto
`branch list --type all`	Ver todos los tipos de ramas
`branch get --type ai`	Ver detalles de la Rama de IA

Editar recursos en una Rama de IA

Cuando CLI escribe recursos del proyecto, use el parámetro --branch para escribir en la Rama de IA:

Recurso	Ejemplo de comando
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 de trabajo recomendado:

# 1. Obtener esquema
apidog cli-schema get endpoint-create

# 2. Validar antes de escribir
apidog cli-schema validate endpoint-create --file ./endpoint.json

# 3. Escribir en la Rama de IA (no en la principal)
apidog endpoint create \
  --project 123456 \
  --branch "ai/20260312-from-main-userRegister" \
  --file ./endpoint.json

Importar recursos existentes

Para modificar recursos existentes, impórtelos primero desde la rama de origen:

apidog branch pick-to \
  --project 123456 \
  --from main \
  --to "ai/20260312-from-main-userRegister" \
  --endpoint-ids 1001,1002

Esto asegura que la IA trabaje con la versión base correcta.

Revisar cambios antes de la fusión

Antes de fusionar, previsualice las diferencias:

apidog merge-request preview \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main

O vea la diferencia completa en el cliente Apidog.

Comando	Propósito
`merge-request preview`	Escanear cambios candidatos
`branch get --type ai`	Ver información de la Rama de IA

Fusionar una Rama de IA

Después de la revisión, fusione los cambios:

Fusión directa (rama no protegida)

apidog branch merge \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --endpoint-ids 1001,1002

Solicitud de fusión (rama protegida)

apidog merge-request create \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --reviewer-ids 20001,20002 \
  --endpoint-ids 1001,1002

Comando	Propósito
`branch merge`	Fusión directa a rama no protegida
`merge-request create`	Crear solicitud de fusión para revisión
`merge-request approve`	Aprobar solicitud de fusión
`merge-request reject`	Rechazar solicitud de fusión

Importante: Los comandos de fusión procesan solo la lista de recursos explícitamente proporcionada. Confirme las dependencias (directorios, modelos, componentes de respuesta, pruebas) antes de fusionar.

Archivar y Eliminar

Después de que los cambios se fusionan o ya no son necesarios:

# Archivar
apidog branch archive "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

# Eliminar (después de archivar)
apidog branch delete "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

Permisos de edición de IA externa

Por defecto, CLI escribe en la Rama de IA. Esto mantiene los cambios generados por IA aislados hasta la confirmación del usuario.

Para habilitar la edición directa de la rama principal:

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 la principal (evita la Rama de IA)
Edición directa de rama de sprint estándar	CLI escribe directamente en las ramas de sprint
Edición directa de rama general	CLI escribe directamente en las ramas generales
Edición directa de la Rama de IA	CLI escribe en las Ramas de IA (normalmente se mantiene habilitado)

Recomendación: Mantenga habilitado el aislamiento de la Rama de IA. Habilite la edición directa solo cuando los flujos de trabajo de automatización lo necesiten claramente.

Mejores Prácticas

Práctica	Por qué
Una Rama de IA por tarea	Alcance claro: API de registro de usuario, documentos del módulo de pedidos, pruebas de pago
Importar antes de editar	Use `pick-to` para recursos existentes; evite la confusión de origen
Validar antes de escribir	Use `cli-schema validate` para detectar errores antes de la Rama de IA
Previsualizar antes de fusionar	Use `merge-request preview` o la vista de diferencias del cliente
Alcance de fusión explícito	Confirme endpoints, modelos, directorios, pruebas juntos
Mantener revisión humana	Las definiciones de API, los scripts de prueba deben revisarse antes de la fusión
Archivar rápidamente	Mantenga la lista de ramas clara después de la fusión o el abandono

Rama de IA en el flujo de trabajo de CLI + HABILIDAD

La Rama de IA se integra naturalmente con CLI + HABILIDAD:

Etapa	CLI + HABILIDAD + Rama de IA
Leer	`endpoint get` de cualquier rama
Generar	El Agente crea JSON
Validar	`cli-schema validate` localmente
Escribir	`endpoint create --branch <nombreRamaIA>` en la Rama de IA
Revisar	`merge-request preview`
Fusionar	El usuario confirma, luego `branch merge`
Verificar	`apidog run` en los recursos fusionados

Cada escritura pasa por la Rama de IA → revisión humana → fusión.

Resumen de Seguridad

Capa	Protección
`cli-schema validate`	Detecta errores estructurales antes de escribir
`agentHints`	Guía al Agente a los siguientes pasos seguros
Rama de IA	Aísla los cambios de la rama principal
Revisión humana	Confirma el contenido antes de la fusión
Alcance de fusión	El usuario selecciona qué recursos fusionar

Juntas, estas capas crean un bucle más seguro para los cambios de proyecto impulsados por Agentes.

Qué sigue

Con la Rama de IA proporcionando la capa de seguridad, todas las piezas están en su lugar:

MCP para la conexión de herramientas (Parte 1)
CLI + HABILIDAD para la ejecución del flujo de trabajo (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 la seguridad (Parte 9)

Ahora es el momento de la visión.

En la Parte 10, Spec-First fue ayer. Bienvenido a Skill-First., explicaremos cómo evoluciona el desarrollo de API con los Agentes de IA, y qué deben hacer los equipos a continuación.

Puntos clave

La Rama de IA proporciona edición aislada para operaciones de IA/CLI
Los cambios no afectan la rama principal hasta la confirmación humana
Cree con branch create --type ai, escriba con el parámetro --branch
Importe recursos existentes con branch pick-to antes de editar
Previsualice con merge-request preview, luego fusione o cree una solicitud de fusión
Los permisos de edición directa pueden omitir la Rama de IA; úselos con cuidado
Mejor práctica: una Rama de IA por tarea, validar antes de escribir, 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.

botón