AI Coding Agent Runbook: cómo convertir un issue en un pull request usando agentes de programación sin perder control

El salto importante: la IA ya no solo escribe código, ahora puede tomar tareas

Hasta hace poco, usar IA para programar era algo bastante directo:

le pedías una función;
copiabas el código;
lo pegabas;
probabas;
corregías.

Después llegaron los copilotos dentro del editor. La IA empezó a sugerir líneas, completar métodos, explicar errores y ayudarte a refactorizar.

Pero el cambio actual es más profundo.

Ahora los agentes de programación pueden trabajar sobre un repositorio completo, leer un issue, proponer cambios, modificar archivos, ejecutar pruebas y abrir un pull request para revisión.

Eso cambia la pregunta.

Ya no basta con saber escribir buenos prompts.

Ahora necesitas saber escribir buenos tickets de trabajo para agentes.

Porque un agente de programación no funciona como un chatbot. Funciona más como un junior muy rápido que necesita contexto, límites, pruebas y criterios de aceptación.

Si le das una tarea vaga, probablemente te dará un pull request vago.
Si le das un issue bien diseñado, puede ahorrarte horas de trabajo repetitivo.

Este tutorial te enseña a crear un flujo profesional:

issue claro
→ agente de programación
→ rama aislada
→ cambios limitados
→ pruebas
→ pull request
→ revisión humana
→ merge controlado

Ese flujo es el corazón de un AI Coding Agent Runbook.

Por qué este tema está en tendencia

GitHub ya documenta el uso de Copilot cloud agent, una función en public preview donde puedes asignar un issue a Copilot para que trabaje la tarea, cree un pull request y solicite revisión cuando termine.

Google también ofrece Jules, un agente autónomo experimental que se integra con GitHub, entiende el repositorio y puede ayudarte a corregir bugs, agregar documentación y construir nuevas funciones de forma asíncrona.

OpenAI, por su parte, viene empujando flujos agénticos con herramientas y APIs orientadas a agentes, lo que confirma una dirección clara del mercado: los modelos ya no quieren quedarse como asistentes de texto; quieren ejecutar tareas dentro de entornos reales.

La tendencia es clara:

El desarrollo asistido por IA está pasando de “sugerir código” a “entregar cambios revisables”.

El riesgo también es claro:

Si no controlas el proceso, el agente puede generar cambios grandes, inseguros o difíciles de mantener.

La regla de oro: un agente no arregla un issue mal escrito

Un issue humano puede tolerar ambigüedad porque el desarrollador pregunta, interpreta y negocia.

Un agente también puede razonar, pero no conviene obligarlo a adivinar.

Un mal issue dice:

Arreglar el login.

Un buen issue dice:

El formulario de login muestra error genérico cuando el usuario escribe una contraseña incorrecta. 
Debe mostrar “Credenciales inválidas” sin revelar si el correo existe.
No modificar el backend.
Agregar prueba para validar el mensaje.
No tocar estilos globales.

La diferencia no es estética. Es operativa.

Un agente necesita saber:

• qué problema resolver;
• qué archivos probablemente tocar;
• qué no tocar;
• cómo verificar;
• qué comportamiento se espera;
• qué se considera fuera de alcance;
• qué pruebas ejecutar;
• qué criterio define “terminado”.

El issue es el contrato de trabajo del agente.

Antes de usar un agente: prepara el repositorio

Un agente de programación será tan bueno como el entorno que le dejes.

Antes de asignarle tareas, revisa cinco cosas.

1. El proyecto debe poder instalarse

Debe existir un comando claro:

npm install

o:

pip install -r requirements.txt

o:

composer install

Si instalar el proyecto requiere conocimiento tribal, el agente fallará o improvisará.

2. Debe existir un comando de pruebas

Ejemplos:

npm test

pytest

php artisan test

dotnet test

Si no hay pruebas, el agente no puede comprobar si rompió algo.

3. Debe existir una guía de arquitectura

Puede ser un README.md, un CONTRIBUTING.md o un archivo específico para agentes.

Ejemplo:

/AGENTS.md

Ahí puedes explicar estructura, convenciones, comandos, reglas y restricciones.

4. Deben protegerse secretos

Nunca dejes .env, tokens o claves dentro del repo.

Antes de trabajar con agentes, usa herramientas como:

gitleaks detect

o:

trufflehog git file://.

5. La rama principal debe estar protegida

El agente debe trabajar en ramas o pull requests, no empujar directo a producción.

El archivo que casi nadie crea: AGENTS.md

Un archivo AGENTS.md es una guía breve para agentes de IA.

No reemplaza documentación completa. Le da al agente reglas de operación.

Ejemplo:

# AGENTS.md

## Objetivo del proyecto
Aplicación web para gestionar tickets internos.

## Stack
- Node.js 20
- Next.js
- PostgreSQL
- Prisma
- Vitest

## Comandos
Instalar:
npm install

Ejecutar pruebas:
npm test

Lint:
npm run lint

## Reglas
- No modificar archivos de migración existentes.
- No cambiar estilos globales salvo que el issue lo pida.
- No agregar dependencias sin justificar.
- No tocar variables de entorno.
- Mantener componentes pequeños.
- Crear pruebas para cambios de lógica.

## Estructura
- /src/app: rutas
- /src/components: componentes
- /src/lib: utilidades
- /prisma: esquema de datos

## Criterio de calidad
Todo PR debe incluir:
- descripción del problema;
- cambios realizados;
- pruebas ejecutadas;
- riesgos o limitaciones.

Este archivo puede reducir errores porque el agente no tiene que inferir todo desde cero.

El runbook: de issue a pull request

La estructura profesional es esta:

1. Crear issue claro.
2. Definir criterios de aceptación.
3. Asignar agente.
4. Revisar plan inicial.
5. Dejar que trabaje en rama.
6. Revisar diff.
7. Ejecutar pruebas.
8. Pedir correcciones.
9. Aprobar o cerrar.

No es “soltar la IA”.

Es darle una tarea cerrada y auditar el resultado.

Cómo escribir un issue perfecto para un agente

Usa esta plantilla.

## Problema

Describe qué está fallando o qué se necesita.

## Resultado esperado

Describe exactamente cómo debe comportarse el sistema al terminar.

## Alcance permitido

Archivos, módulos o áreas que el agente puede modificar.

## Fuera de alcance

Cosas que no debe tocar.

## Criterios de aceptación

- [ ] Criterio 1
- [ ] Criterio 2
- [ ] Criterio 3

## Pruebas requeridas

Comandos que deben ejecutarse.

## Contexto adicional

Errores, capturas, logs, rutas, ejemplos o enlaces.

Esta plantilla convierte una idea en una tarea ejecutable.

Ejemplo 1: issue malo versus issue bueno

Issue malo

Mejorar el formulario de contacto.

El agente podría cambiar diseño, backend, validaciones, textos y estilos sin criterio.

Issue bueno

## Problema

El formulario de contacto permite enviar mensajes con email inválido.

## Resultado esperado

Si el campo email no tiene formato válido, debe mostrarse el mensaje:
“Ingresa un correo válido”.

El formulario no debe enviarse hasta corregir el campo.

## Alcance permitido

- src/components/ContactForm.tsx
- pruebas relacionadas al formulario

## Fuera de alcance

- No cambiar estilos globales.
- No cambiar endpoint backend.
- No agregar librerías nuevas.

## Criterios de aceptación

- [ ] Valida formato de email antes de enviar.
- [ ] Muestra mensaje de error.
- [ ] Mantiene comportamiento actual para campos válidos.
- [ ] Agrega o actualiza prueba.

## Pruebas requeridas

npm test
npm run lint

Un agente puede trabajar mucho mejor con eso.

Qué tareas sí conviene dar a un agente

Los agentes son útiles para tareas cerradas.

Buen encaje:

• corregir bugs concretos;
• agregar pruebas;
• actualizar documentación;
• migrar nombres de funciones;
• refactorizar módulos pequeños;
• crear componentes simples;
• mejorar validaciones;
• actualizar dependencias menores;
• corregir errores de lint;
• agregar logs;
• escribir tests faltantes;
• crear ejemplos de uso.

Mal encaje:

• rediseñar arquitectura completa;
• tomar decisiones de negocio;
• tocar seguridad crítica sin revisión;
• modificar pagos;
• cambiar autenticación;
• reescribir base de datos;
• optimizar rendimiento sin métricas;
• hacer cambios grandes sin pruebas.

Regla práctica:

Si no puedes explicar la tarea en un issue claro, no se la des al agente todavía.

Cómo usar GitHub Copilot cloud agent

GitHub documenta que puedes pedir a Copilot que trabaje en un issue asignándoselo. Copilot empieza a trabajar la tarea, crea un pull request y solicita revisión cuando termina.

Flujo conceptual:

1. Abre el repositorio en GitHub.
2. Crea un issue usando una plantilla clara.
3. Asigna el issue a Copilot.
4. Espera que cree una rama y un pull request.
5. Revisa el PR como si fuera de un desarrollador humano.
6. Pide cambios si es necesario.
7. Ejecuta pruebas y revisa seguridad.
8. Haz merge solo si cumple criterios.

Lo importante: no trates el PR como “código aprobado por IA”. Trátalo como “código propuesto por IA”.

Cómo usar Google Jules

Jules se presenta como un agente autónomo que se integra con GitHub, entiende tu código base y trabaja tareas como bugs, documentación y nuevas funciones.

Flujo conceptual:

1. Entra a Jules.
2. Conecta tu cuenta de GitHub.
3. Selecciona repositorio y rama.
4. Describe la tarea con precisión.
5. Revisa el plan o resultado.
6. Permite que cree cambios.
7. Revisa el pull request.
8. Ejecuta pruebas antes de fusionar.

Jules es especialmente útil para tareas asíncronas: puedes dejarle una tarea bien definida y revisar luego el resultado.

La revisión humana: dónde debes mirar primero

Cuando llegue el pull request, no empieces leyendo todo línea por línea.

Primero mira estructura.

1. Tamaño del cambio

Si el issue era pequeño y el PR toca 30 archivos, algo está mal.

2. Archivos modificados

Pregunta:

¿tocó solo lo permitido?

3. Dependencias nuevas

Si agregó una librería, debe justificarla.

4. Seguridad

Busca:

• manejo inseguro de input;
• exposición de secretos;
• logs con datos sensibles;
• cambios en autenticación;
• permisos excesivos;
• validaciones débiles.

5. Pruebas

Un cambio de lógica sin prueba es sospechoso.

6. Compatibilidad

No debe romper comportamiento existente.

7. Estilo

Debe respetar arquitectura del proyecto.

Checklist de revisión de PR generado por IA

El patrón de seguridad: solo lectura primero

Si estás empezando, no le des al agente tareas de escritura compleja.

Empieza con:

leer código;
explicar estructura;
generar documentación;
proponer tests;
detectar áreas de riesgo;
crear PR pequeño;

Luego avanza a:

corregir bug puntual;
agregar validación;
actualizar test;
refactorizar función pequeña;

Deja para después:

autenticación;
pagos;
permisos;
migraciones;
infraestructura;
despliegue;
seguridad crítica.

La confianza se gana por historial.

Cómo dividir tareas grandes

Un error común es darle al agente una tarea gigante.

Mal:

Implementa el módulo de facturación.

Mejor:

Issue 1: crear modelo de datos.
Issue 2: crear formulario.
Issue 3: validar campos.
Issue 4: crear pruebas.
Issue 5: integrar endpoint.
Issue 6: documentar uso.

Los agentes funcionan mejor con unidades pequeñas y verificables.

Ejemplo de tarea ideal para un primer agente

## Problema

El componente LoginForm no muestra mensaje claro cuando el campo email está vacío.

## Resultado esperado

Al presionar “Ingresar” con email vacío, debe mostrarse:
“El correo es obligatorio”.

## Alcance permitido

- src/components/LoginForm.tsx
- src/components/LoginForm.test.tsx

## Fuera de alcance

- No cambiar backend.
- No cambiar estilos globales.
- No modificar autenticación.

## Criterios de aceptación

- [ ] El mensaje aparece solo cuando el campo está vacío.
- [ ] No se envía el formulario si falta email.
- [ ] Se agrega prueba automatizada.
- [ ] npm test pasa correctamente.

## Pruebas requeridas

npm test
npm run lint

Es pequeño, claro y verificable.

Cómo pedir correcciones al agente

No digas:

Está mal, corrige.

Di:

El PR modifica archivos fuera del alcance definido. Revierte cambios en src/styles/global.css y conserva solo modificaciones en LoginForm.tsx y LoginForm.test.tsx. Mantén los criterios de aceptación originales.

O:

La prueba cubre email inválido, pero no email vacío. Agrega un caso específico para email vacío y no modifiques el comportamiento de contraseña.

Los agentes responden mejor a feedback concreto.

Cómo evitar PRs inflados

Agrega estas reglas al issue o a AGENTS.md:

- Mantén el cambio mínimo.
- No refactorices código no relacionado.
- No agregues dependencias sin aprobación.
- No cambies formato de archivos completos.
- No modifiques estilos globales.
- No cambies APIs públicas salvo que el issue lo pida.

Un PR pequeño se revisa. Un PR enorme se desconfía.

Qué métricas medir

Si vas a usar agentes de programación de forma recurrente, mide:

El objetivo no es “usar agentes”. Es reducir trabajo repetitivo sin aumentar riesgo.

Riesgos que debes tomar en serio

Código inseguro

La IA puede generar soluciones funcionales, pero débiles.

Cambios demasiado amplios

Puede tocar más archivos de los necesarios.

Dependencias innecesarias

Puede instalar librerías para resolver algo simple.

Tests superficiales

Puede escribir pruebas que no prueban realmente el bug.

Repetición de patrones malos

Si el repo tiene mala arquitectura, el agente puede copiarla.

Falsa confianza

Un PR generado por IA puede verse profesional aunque tenga errores.

Secretos

Nunca permitas que el agente trabaje con tokens o .env.

Buenas prácticas para equipos

1. Crear plantilla de issues para agentes.
2. Agregar AGENTS.md.
3. Proteger rama principal.
4. Empezar con tareas pequeñas.
5. Revisar PRs como código humano.
6. Exigir pruebas.
7. Bloquear cambios fuera de alcance.
8. No permitir secretos en repositorio.
9. Medir aceptación y defectos.
10. Actualizar reglas según errores reales.

Runbook rápido para copiar

1. Crear issue con problema, alcance, fuera de alcance y pruebas.
2. Verificar que el repo instala y prueba correctamente.
3. Asignar issue al agente.
4. Revisar si el PR toca solo lo permitido.
5. Ejecutar pruebas.
6. Revisar seguridad.
7. Pedir correcciones concretas.
8. Aprobar solo si cumple criterios.
9. Documentar aprendizajes en AGENTS.md.

Prompt maestro para un agente de programación

Trabaja este issue como un pull request pequeño y revisable.

Reglas:
- Respeta el alcance permitido.
- No modifiques archivos fuera de alcance.
- No agregues dependencias sin justificar.
- No cambies estilos globales.
- No toques autenticación, permisos, pagos ni variables de entorno.
- Agrega o actualiza pruebas si cambias lógica.
- Mantén el cambio mínimo.
- Explica qué pruebas ejecutaste.
- Si falta información, pregunta antes de asumir.

Entrega esperada:
1. Resumen del problema.
2. Cambios realizados.
3. Archivos modificados.
4. Pruebas ejecutadas.
5. Riesgos o limitaciones.

La idea clave

Los agentes de programación no reemplazan el criterio del desarrollador. Reemplazan parte del trabajo repetitivo cuando el problema está bien definido. La diferencia entre un agente peligroso y uno útil no está solo en el modelo: está en el runbook. Si escribes issues claros, limitas el alcance, exiges pruebas y revisas el pull request con disciplina, la IA deja de ser un autocompletador avanzado y se convierte en un colaborador controlado.