Del issue de GitHub al pull request con un agente

Un buen issue es básicamente un prompt — con contexto y criterios de aceptación se convierte en un pull request limpio y verificable.

El flujo básico

Un flujo de trabajo típico con agentes funciona así: un issue de GitHub describe una tarea, un agente (p. ej. mediante @claude en un comentario o un pipeline de CI) lee el issue, trabaja en su propia rama, genera cambios de código y al final abre un pull request — para revisión humana, no para fusión automática.

Un buen issue es un buen prompt

Las mismas reglas que valen para un buen prompt valen para un buen issue: contexto claro (qué archivo, qué comportamiento, por qué), criterios de aceptación concretos y, cuando sea posible, un ejemplo del comportamiento esperado. Un issue vago lleva a un PR vago, a menudo inutilizable — independientemente de si lo implementa una persona o un agente.

Por qué es importante una rama propia

El agente nunca trabaja directamente sobre la rama principal, sino en una rama de funcionalidad propia. Esto mantiene los cambios aislados, verificables y — si algo sale mal — reversibles sin consecuencias, sin tocar la rama principal.

La revisión humana sigue siendo la puerta

El pull request es el punto de control decisivo: una persona revisa el diff, la descripción y los resultados de CI antes de fusionar. Las comprobaciones de CI (tests, linting, build) se ejecutan automáticamente como red de seguridad adicional, pero no sustituyen el juicio humano sobre si el cambio tiene sentido.

EJEMPLO

Issue: "Bug: /api/users devuelve 500 en vez de una lista vacía cuando el campo de búsqueda está vacío. Contexto: routes/users.js, línea 42. Criterio de aceptación: GET /api/users?q= devuelve [] con estado 200, el test existente tests/users.test.js sigue en verde." Comentario en el issue: @claude por favor implementa esto → El agente trabaja en la rama fix/empty-search, abre el PR "Fix: empty search returns [] instead of 500 (Closes #123)"

🛠️ EJERCICIO — PRUÉBALO TÚ

Escribe un issue de GitHub completo, apto para agentes, para un pequeño arreglo de bug y hazlo implementar.

Elige un bug pequeño y claramente delimitado, o un detalle menor, en un repositorio propio.
Escribe un issue con el archivo/función afectados, el comportamiento erróneo actual, el comportamiento objetivo y al menos un criterio de aceptación concreto.
Deja que un agente (p. ej. Claude Code o la integración de GitHub) proponga la implementación en una rama propia y abra un pull request.
Revisa el PR como lo haría un revisor: título, descripción, diff, relación con el issue.

✅ AUTOEVALUACIÓN

☐ ¿Tu issue contenía los cuatro elementos (contexto, comportamiento erróneo, comportamiento objetivo, criterio de aceptación)?
☐ ¿Pudo el agente implementar la tarea sin preguntas adicionales, o faltó información?

QUIZ RÁPIDO

¿Qué convierte a un issue de GitHub en un «buen prompt» para un agente de programación?