Ingeniería de contexto para agentes de programación

La ingeniería de contexto es el trabajo de decidir qué ve un agente de programación antes de que actúe. Es la mejor herramienta de las que dispones para influir sobre la calidad de los resultados, porque un modelo competente no sirve de nada si lo que le pones delante no vale.

En Jira, el contexto que necesita un agente ya forma parte de la actividad. La actividad contiene la meta y los criterios de aceptación, y el Teamwork Graph la vincula con el código, las decisiones y la documentación relacionada para que un agente actúe con un propósito real, no a partir de un prompt en blanco. Ese contexto permanece compartido con todo tu equipo, no atrapado en archivos locales de una sola máquina.

Esta guía explica qué es la ingeniería de contexto, por qué la ventana de contexto es la verdadera limitación de los agentes de programación y cómo puedes preparar el contexto en Jira para que los agentes obtengan lo que necesitan sin tener que indicárselo manualmente en cada prompt. En la práctica, esto se reduce a llevar a cabo una serie de acciones en la actividad que ya gestionas:

• Dale al agente la meta, no un mero prompt. Escribe la actividad de Jira como la especificación, con los criterios de aceptación con los que se evalúa al agente.

• Deja que el gráfico proporcione el contexto circundante. Al usar la actividad como punto de partida para el prompt, el Teamwork Graph lo amplía a los documentos, las decisiones y el contexto relacionado con la tarea.

• Mantén los estándares compartidos y actualizados. Las convenciones están en Confluence, extraídas de la misma fuente por cada agente y miembro del equipo.

• Proporciona a cualquier agente la misma capa de contexto. Todos los agentes de programación (como Claude Code, Cursor, Codex, GitHub Copilot y el agente de programación de Jira, entre otros) reciben el mismo contexto de la organización.

¿Qué es la ingeniería de contexto?

La ingeniería de contexto es la práctica de decidir deliberadamente qué información ve un modelo en cada paso, de forma que un agente de programación tenga lo que necesita para desempeñar su trabajo como es debido. Esa información va más allá del prompt: es el código base, tus estándares, dependencias, historial de Git, definiciones de herramientas, metas y criterios de aceptación. El nuevo trabajo consiste en seleccionar todo eso para cada tarea.

La ingeniería de prompts conlleva seleccionar la información e introducirla en una sola instrucción por tu cuenta. La ingeniería de contexto significa que el sistema proporciona lo que el agente necesita a lo largo de una tarea de varios pasos: lo que entra, lo que se recupera, lo que se resume y lo que se descarta, para que el agente pueda encontrar el resto bajo demanda.

Es importante tener en cuenta que dar más contexto no necesariamente lo mejora:

• El contexto de señal alta es la información que realmente ayuda con la tarea en cuestión.

• El contexto de señal baja es el contenido obsoleto, sin relación con el tema o duplicado que el modelo tiene que leer igualmente.

A medida que una ventana de contexto se va llenando de tokens de señal baja, las respuestas se ralentizan y pierden precisión aunque el modelo no haya cambiado. A esta degradación se la llama deterioro del contexto: el declive gradual de los resultados a medida que la ventana de contexto se va llenando de tokens obsoletos, de señal baja o contradictorios. Una buena ingeniería de contexto consiste tanto en eliminar el contexto obsoleto como en añadir el adecuado.

¿Por qué la ventana de contexto es la limitación para los agentes de programación?

Un modelo de programación solo puede razonar sobre lo que cabe dentro de la ventana de contexto, cuyo tamaño es reducido si lo comparamos con tu código base, tu documentación y el historial de tu equipo. Aunque el agente sea competente, seguirá lanzando código incorrecto o poco seguro si la ventana no llegó a contener nunca tus convenciones, tu arquitectura o la decisión detrás de una tarea.

Cuando se deja que el agente recopile el contexto por su cuenta, falla recurrentemente de las siguientes maneras:

• El agente se desvía en una tarea larga porque la decisión que tomó al principio queda fuera de la ventana de contexto a medida que se van acumulando tokens más recientes y de señal más baja.

• Recupera demasiado contexto, por lo que introduce en la ventana más cosas de las que de verdad utiliza y malgasta el presupuesto para tokens en ruido.

• Un agente no verá nunca un estándar si no se lo pones delante de las narices, por lo que lanzará código que romperá alguno de los patrones que sigue el resto del equipo.

• Funciona bien en solitario, pero no tiene ni idea de lo que el resto del equipo (u otro agente) está haciendo en el mismo ámbito.

En cambio, al dejarle el contexto adecuado al alcance de la mano, el agente puede descubrir lo que necesita por su cuenta y sobre la marcha para que tus prompts puedan mantenerse a un alto nivel, en vez de tener que detallarle cada convención y decisión manualmente.

¿Cómo se diseña el contexto para los agentes de programación de Jira?

En Jira, tu propio trabajo se convierte en el contexto: la intención reside en la actividad, los conocimientos circundantes se conectan a través del Teamwork Graph y los estándares y decisiones duraderos se extraen de Confluence y Loom, donde cada agente y miembro del equipo recurre a la misma fuente. Jira abarca mucho más que los archivos locales de un solo equipo y se extiende hasta las metas, las decisiones y conversaciones en curso, y el historial de todo tu trabajo. Además, mantiene toda esa información compartida, por lo que el contexto a partir del cual actúa un agente está estructurado, es actual y coherente para todo el equipo.

La ingeniería de contexto se basa en tres principios:

1. Seleccionar la información adecuada

2. Mantenerla estructurada

3. Hacer que persista

1. Selección y recuperación: escribe la actividad como la especificación

La selección consiste en elegir el menor conjunto posible de contexto de señal alta para una tarea; mientras que la recuperación consiste en extraer los datos correctos bajo demanda, en lugar de volcar todo en la ventana desde el principio. En Jira, ambos procesos empiezan con la actividad.

• Cómo funciona en Jira: Indica la meta en la descripción y recoge los criterios de aceptación en una lista de comprobación. De este modo, brindarás al agente la intención y las pautas con las que se le evaluará, en una estructura que podrá leer. Acto seguido, asigna la actividad a un agente conectado. Este tomará como punto de partida la actividad y el contexto vinculado, no todo el código base. Intercambiar ideas con el agente para pulir esa especificación forma parte del trabajo, ya que el agente lee enormes cantidades de datos rápidamente y te ayuda a detectar las carencias antes de empezar.

• Próximamente: Jira Planner convierte las ideas en planes y actividades listos para agentes con el contexto ya adjuntado. Únete a la lista de espera.

2. Contexto compartido: no pegues la actividad, enlázala

La estructura y el formato son clave: moldea el contexto para que un agente pueda orientarse en él y mantenlo conectado en lugar de copiado. El Teamwork Graph es lo que hace que el contexto circundante esté disponible sin tener que montarlo manualmente cada vez.

• Cómo funciona en Jira: Vincula la actividad con actividades relacionadas, el código y las páginas de Confluence que contienen la especificación, la solicitud de cambios o el registro de decisiones. El agente hereda el contexto que rodea a la tarea, no solo el texto del ticket. Un vídeo explicativo de Loom también cuenta: la reproducción grabada de un error o la justificación de un diseño lleva su transcripción y resumen al gráfico, por lo que una explicación dada a otro miembro del equipo se convierte en contexto legible para un agente. De este modo, los “datos recuperados adecuados” proceden de tu actividad real, no de un almacén de vectores independiente que hay que compilar y mantener.

3. Persistencia: mantén los estándares y las decisiones donde se recopilan

La persistencia, también llamada “memoria”, consiste en preservar la disponibilidad de datos duraderos de una sesión a otra para que el agente no empiece siempre de cero. Las tres categorías que hay que tener en cuenta son las siguientes: lo que el agente retiene durante una tarea, lo que debería conservar de una tarea a otra y lo que puede consultar cuando sea necesario.

• Cómo funciona en Jira: Las convenciones, las decisiones de arquitectura y los patrones preferidos residen en el espacio compartido de Confluence, donde todo el equipo y cada agente obtienen información de una misma fuente a través del gráfico, en vez de estar en una copia alojada en la máquina de alguien y que nadie más puede ver. A medida que el trabajo avanza por el sistema, el gráfico se enriquece, por lo que el siguiente agente dispone de más recursos a los que recurrir. El contexto se acumula a medida que se va sacando adelante el trabajo, sin que el equipo de desarrollo tenga que hacer ningún paso extra manualmente.

Son dos cosas las que hacen que todo esto siga funcionando para todo el equipo: la existencia de una única capa de contexto que cada agente puede usar y un control que hace que siga siendo fiable y estando autorizada.

Una sola capa de contexto para cualquier agente

El contexto que diseñas solo será válido si todas las herramientas pueden usarlo. Volver a enseñar tus estándares a cada agente es la forma más rápida de volver a abrir la puerta a que el contexto se deteriore.

• Cómo funciona en Jira: Dale a cualquier agente de programación el mismo contexto de la organización a través de dos vías. La CLI de Teamwork Graph brinda a tu agente de programación un acceso directo a ese contexto y a sus herramientas desde la terminal. Con solo configurarla una vez, tu agente podrá consultar el gráfico mientras trabaja. El servidor MCP de Atlassian Rovo hace lo mismo con los clientes MCP como Claude, Cursor, Codex y GitHub Copilot. El Teamwork Graph es lo que lo lleva todo de un lado a otro: las actividades, las decisiones, la documentación y el código permanecen conectados como una única capa consultable. Diseña el contexto una vez y úsalo con cualquier modelo que haga lo que necesitas.

Gobernanza: mantén el contexto fiable y autorizado

El contexto solo es útil si está actualizado y el agente tiene permiso para verlo. La gobernanza mantiene la capa compartida fiable a medida que más agentes recurren a ella.

• Cómo funciona en Jira: los agentes heredan los mismos permisos que tu equipo ya usa como línea base, por lo que un agente ve lo que el usuario puede ver, y nada más, y su alcance se puede limitar aún más con reglas específicas del agente. Para saber cómo se integran el acceso, la aprobación y la auditoría, consulta Controles y seguridad de la ingeniería de agentes en Jira.

¿Cómo encaja Jira con el resto de tu pila de contexto?

La mayor parte del contexto de un agente de codificación hoy en día reside en una sola máquina: el repositorio que tiene abierto, algunos archivos locales y lo que el desarrollador haya escrito en el prompt. Eso funciona de forma individual, pero la información está dispersa por varios sitios, está aislada (no se comparte) y el contexto no es persistente. Jira y Teamwork Graph incorporan el contexto relevante en una capa compartida, actual y gobernable de la que se nutren todo el equipo y sus agentes.

Nada de esto sustituye a tu agente de codificación, tu IDE o tu configuración local. Esos siguen encargándose de los detalles específicos de cada repositorio y del código real. Jira es la capa compartida en la parte superior, por lo que el contexto en el que basan su actividad está estructurado, actualizado y es el mismo en todo tu equipo.

Cómo proporcionarle contexto real a tu primer agente en Jira

La ingeniería de contexto consiste, en última instancia, en dotar a un agente de las herramientas y la información necesarias para que encuentre por su cuenta lo que necesita. Jira y Teamwork Graph son la capa de contexto compartido a la que el agente accede a través de MCP o CLI, por lo que la actividad consiste en hacer que esa capa siga siendo precisa y se mantenga conectada.

Empieza con una actividad bien estructurada para ver la diferencia entre un agente que adivina y un agente que trabaja con intención.

1. Dale al agente un estándar con el que se le evaluará. Elige una tarea delimitada y de bajo riesgo que sea fácil de deshacer, como una refactorización independiente o la corrección de un pequeño error, y escribe el objetivo en la descripción con los criterios de aceptación en una lista de comprobación.

2. Deja que el agente herede el contexto en lugar de pegarlo. Conecta la actividad con su código haciendo referencia a la clave de la actividad en tu rama, confirmación o solicitud de extracción, y vincula el documento o la decisión que lo respalda. El agente recopila el contexto vinculado en torno a la tarea, no solo el texto del ticket.

3. Apunta a un estándar compartido. Vincula la convención que debería seguir a una página de Confluence para que el siguiente agente y compañero de equipo usen la misma fuente.

4. Asígnasela a un agente. El agente parte de la actividad y su contexto vinculado, un punto de partida más enfocado que toda la base de código o un prompt en blanco.

5. Revisa según los criterios que la originaron. Revisa la solicitud de extracción frente a los criterios de aceptación que escribiste en la actividad, para que el resultado se evalúe según el estándar original que le diste al agente.

6. Haz que el agente cierre el ciclo. Pídele que actualice la actividad al final con un resumen de la sesión, las decisiones sobre ventajas y desventajas, y la solicitud de extracción vinculada, para que el siguiente compañero de equipo o agente pueda retomar el trabajo donde se dejó a través de Teamwork Graph.

Ejecuta algunas actividades de esta manera y el gráfico se completará a medida que avances: cada agente deja un resumen, sus decisiones clave y la solicitud de extracción vinculada en la actividad, para que la siguiente comience con un panorama más completo que la anterior. Eso es ingeniería de contexto que se acumula en lugar de reiniciarse en cada ejecución.

Preguntas frecuentes sobre ingeniería de contexto

¿Cuál es la diferencia entre la ingeniería de prompts y la ingeniería de contexto?

La ingeniería de prompts es la disciplina que consiste en seleccionar manualmente información relevante para un solo prompt. La ingeniería de contexto es la disciplina que se ocupa de implementar un sistema que proporciona información a un agente a lo largo de una tarea de varios pasos, lo que incluye la recuperación, la estructura, la memoria y el propio objetivo, de modo que muestre los detalles bajo demanda según sea necesario.

¿Cómo obtienen contexto de Jira los agentes de codificación de IA?

Los agentes obtienen contexto de la actividad, su descripción y criterios de aceptación, y de Teamwork Graph, que conecta la actividad, los documentos y el código relacionados, para que el agente actúe con una intención real, no con un prompt en blanco.

¿Por qué los agentes de codificación producen código incorrecto incluso con un buen prompt?

Un prompt rara vez incluye tus convenciones, arquitectura o la decisión detrás de una tarea. La mayoría de los fallos del agente son de contexto, no del modelo, y un mejor contexto soluciona más que una mejor redacción.

¿Sigo necesitando ingeniería de contexto si mi agente ya lee mi repositorio?

Sí. Un repositorio le dice a un agente qué es el código, pero no por qué se creó de esa manera, qué estándares seguir ni qué más está pasando en todo el equipo. La ingeniería de contexto proporciona el resto.

¿Qué es el deterioro del contexto?

El deterioro del contexto es la degradación gradual del resultado de un agente a medida que su ventana de contexto se llena de tokens obsoletos, de baja señal o contradictorios. Las respuestas se vuelven más lentas y menos precisas aunque el modelo no ha cambiado.