Desarrollo impulsado por el contexto: cómo la IA solucionó la representación de imágenes en la integración de Jira

Como desarrolladores, a menudo nos encontramos en la misma situación: trabajas en una funcionalidad, una IA te ayuda a implementarla, pero luego tu compañero no entiende qué sucedió ni por qué se tomaron ciertas decisiones. El historial de interacción con la IA se pierde, el contexto desaparece y el equipo debe reconstruir el razonamiento. En uno de mis experimentos semanales con imdone esto se volvió evidente y además descubrí un problema técnico concreto: las imágenes embebidas en elementos de lista en markdown no se renderizaban correctamente al sincronizar con Jira.

El problema técnico era simple de describir y complicado de detectar en la práctica. Cuando un elemento de lista contenía una imagen en la misma línea, por ejemplo un bullet point con una imagen, Jira no la mostraba porque no acepta imágenes colocadas directamente en el mismo renglón de un item de lista. La solución consistió en forzar que la imagen quedara en una línea separada antes de enviar el contenido a Jira.

Para evitar que ese contexto se perdiera de nuevo desarrollé un formato estructurado en markdown para la colaboración con IA que preserva y comparte contexto con todo el equipo. Cada tarea sigue este esquema claro y repetible: archivos, objetivo, restricciones y acción esperada. Esto permite que tanto la IA como otros desarrolladores comprendan el alcance y las decisiones sin necesidad de reconstruir la historia detrás del cambio.

Formato de contexto estructurado usado

files: lista explícita de ficheros relevantes, por ejemplo cli-package/src/parsers/markdown-parser.js y cli-package/src/adapters/jira-generator.js

goal: explicación en lenguaje natural de lo que se pretende lograr

constraints: límites y requisitos como mantener compatibilidad hacia atrás y escribir pruebas que cubran el caso

action: entregable esperado, por ejemplo aplicar parche y mostrar diffs

Aplicación real: solución para la representación de imágenes

Con ese formato abordé la corrección. La tarea quedó definida así: files: markdown parser y JIRA generator, goal: si una imagen aparece en la misma línea que un elemento de lista moverla a una nueva línea para que JIRA la renderice correctamente, constraints: escribir buenas pruebas unitarias y no romper otras formas de renderizado, action: aplicar parche y mostrar diffs.

El flujo de colaboración con la IA fue directo. Con el contexto estructurado pedí a GitHub Copilot que completara la tarea en la línea X. La IA entendió el alcance leyendo los archivos indicados, se aplicó TDD creando primero tests que fallaban, implementó la lógica que extrae imágenes situadas en el mismo renglón de un item y las coloca en una nueva línea, y respetó las restricciones para mantener compatibilidad. El resultado fue una solución que cualquier compañero pudo revisar y comprender rápidamente gracias al contexto que quedó documentado junto al código.

Resultado en imdone 0.26.0

La corrección se incluyó en imdone 0.26.0. Ahora, al sincronizar markdown con imágenes en elementos de lista, el proceso mueve automáticamente la imagen a una línea separada para que Jira la renderice correctamente. Antes, un bullet con imagen podía fallar en Jira si la imagen estaba en la misma línea, después, la imagen aparece en su propia línea y se visualiza como se espera.

Por qué funciona este enfoque

files: clarifica el alcance y evita búsquedas innecesarias en el repositorio; goal: comunica el propósito final en lenguaje humano; constraints: establece límites técnicos y de calidad desde el inicio; action: indica el entregable concreto para que la IA y los revisores sepan cuándo la tarea está completa. Ese pequeño esquema mejora la predictibilidad y la trazabilidad de las intervenciones asistidas por IA.

Lecciones clave

1 Estructura para colaborar mejor con la IA: definir archivos, objetivos, restricciones y acciones permite a asistentes de código generar resultados más útiles y previsibles.

2 Preservar el contexto es crítico para los equipos: cuando las interacciones con IA quedan documentadas en el repositorio, los compañeros entienden no solo qué cambió sino por qué y cómo se tomó la decisión.

3 Tratar cada feature como experimento impulsa mejoras reales: incluso interacciones que fallan en algún paso pueden producir soluciones valiosas y aprendizajes aplicables.

4 Mantener el contexto cerca del código: guardar estas tareas estructuradas en el mismo repositorio, por ejemplo en una carpeta git-ignored backlog, mantiene acceso y orden sin ensuciar la rama principal.

Sobre Q2BSTUDIO y cómo podemos ayudarte

En Q2BSTUDIO somos una empresa de desarrollo de software y aplicaciones a medida con un enfoque práctico en inteligencia artificial y ciberseguridad. Diseñamos soluciones de software a medida y aplicaciones a medida que integran agentes IA, automatizaciones y pipelines seguros en infraestructuras cloud. Si tu proyecto requiere arquitecturas en la nube confiables podemos desplegar en servicios cloud aws y azure con prácticas de seguridad y escalado en mente. También ofrecemos servicios de inteligencia de negocio y power bi para convertir datos en decisiones estratégicas, y tenemos experiencia en pentesting y protección avanzada para mantener tus activos seguros.

Si buscas adaptar IA a procesos empresariales o crear agentes IA que aumenten la productividad de tus equipos consulta nuestras iniciativas de inteligencia artificial para empresas o descubre cómo diseñamos soluciones y aplicaciones a medida que encajan con tus objetivos. Podemos ayudarte a integrar pipelines de datos, servicios de Business Intelligence y dashboards Power BI para obtener insights accionables, o asegurar tus aplicaciones con auditorías y pruebas de ciberseguridad.

Conclusión

El experimento de desarrollo impulsado por el contexto demostró que una estructura simple y consistente puede mejorar radicalmente la colaboración entre humanos y asistentes de IA, además de generar correcciones técnicas concretas como la incluida en imdone 0.26.0. En Q2BSTUDIO creemos que la IA debe potenciar la colaboración humana, no reemplazarla. Si quieres implementar prácticas similares en tu equipo o necesitas soluciones de software a medida con IA integrada, ciberseguridad y despliegue en la nube, estamos listos para ayudarte.