4 de noviembre de 2026Actualizado el Fathy Shalaby14 min de lectura
Contexto de producto para agentes de código con IA: qué compartir y cómo
Los agentes de código leen tu código, pero no a tus clientes. Aquí tienes qué contexto de producto necesitan, qué herramientas lo entregan, cuánto es demasiado y un task packet para copiar.
El contexto de producto para agentes de código con IA es el conjunto pequeño y actual de datos que un agente necesita y que el código no muestra: quién tiene el problema, las pruebas, la decisión vigente y su responsable, las restricciones y cómo comprobará una persona el resultado. La mejor configuración tiene tres capas: un archivo de instrucciones corto en el repositorio, un task packet por cambio y un enlace en vivo a tu fuente de verdad del producto.
Ideas clave
Más contexto no es mejor contexto. Chroma probó 18 modelos y concluyó que el rendimiento «se vuelve cada vez menos fiable a medida que crece la longitud de la entrada», incluso en tareas sencillas (Chroma, 2025).
La propia definición de Anthropic del trabajo es encontrar el conjunto más pequeño de tokens de alta señal para la tarea y cargar el resto justo a tiempo mediante enlaces y rutas de archivos (Anthropic, 2025).
Los archivos del repositorio son para reglas duraderas. Anthropic recomienda menos de 200 líneas por CLAUDE.md y Cursor dice que las reglas deben quedarse por debajo de 500 líneas, así que las pruebas de clientes y las decisiones que cambian no pertenecen ahí.
No existe una única mejor herramienta. Usa un archivo de instrucciones corto, un task packet por cambio y una conexión MCP al lugar donde realmente viven las decisiones.
Los equipos ya pierden más del 25 % de su semana laboral buscando información (Atlassian, 2025). Un segundo wiki de producto escrito solo para agentes lo empeora.
¿Qué cuenta como contexto de producto para un agente de código con IA?
Un agente de código puede leer tu repositorio, ejecutar tus tests y buscar en tus archivos. No puede leer la llamada con el cliente que originó la petición, el compromiso al que llegó el equipo en la reunión del martes ni la razón por la que una función se dejó fuera a propósito. Eso es contexto de producto: el «quién» y el «por qué» detrás del cambio de código.
Contexto de código (el agente puede encontrarlo)
Contexto de producto (alguien tiene que aportarlo)
Frameworks, estructura de archivos, patrones existentes
Quién tiene el problema y con qué frecuencia
Comandos de test, build y lint
Pruebas: entrevistas, tickets, analítica
Firmas de funciones y tipos
La decisión vigente, su responsable y su fecha
Commits anteriores y comentarios del código
Qué queda deliberadamente fuera de alcance
Mensajes de error y logs
Restricciones de clientes, contratos o políticas
Resultados de CI
Qué comprobará un revisor antes de aceptar
Los agentes ya están lo bastante extendidos como para que esta brecha importe. En la encuesta de Stack Overflow de 2025, el 14,1 % de los desarrolladores usaba agentes de IA a diario en el trabajo, y al 86,9 % le preocupaba la exactitud de la información que ofrecen los agentes (Stack Overflow, 2025). Parte de esa imprecisión es del modelo. Otra parte viene de una petición que dejó fuera los datos de producto importantes.
¿Cuál es la mejor herramienta para dar contexto de producto a agentes de código con IA?
Ninguna herramienta lo cubre todo. Cada forma de entregar contexto es buena en una capa y débil en las demás, así que la pregunta útil es qué combinación encaja con el lugar donde tu equipo guarda sus decisiones.
El Model Context Protocol (MCP), que Anthropic publicó como estándar abierto el 25 de noviembre de 2024, es lo que hace posibles las filas «en vivo»: un protocolo en lugar de un conector a medida por cada fuente de datos (Anthropic, 2024). Linear, por ejemplo, aloja un servidor que funciona con Claude Code, Cursor, Codex y VS Code mediante OAuth 2.1 (Linear docs).
Una configuración práctica por defecto para un equipo pequeño:
Un AGENTS.md o CLAUDE.md corto con comandos, convenciones, reglas de seguridad y una línea que diga dónde viven las decisiones de producto.
Un task packet (plantilla más abajo) enlazado desde cada incidencia que recoja el agente.
Una conexión MCP de solo lectura al sistema que guarda tus decisiones y pruebas, para que el agente consulte el detalle cuando lo necesite en vez de que tú lo pegues.
Prefiere el acceso de solo lectura para los agentes de código salvo que la tarea requiera escribir. Linear ofrece un endpoint de solo lectura aparte precisamente para esto. Importa: el 81,4 % de los desarrolladores de la encuesta de Stack Overflow tenía preocupaciones de seguridad y privacidad sobre los datos al usar agentes de IA.
¿Cuánto contexto debes dar a un agente de código?
Menos de lo que crees, y bien elegido. Tres líneas de investigación apuntan en la misma dirección.
Las entradas largas degradan el rendimiento. El estudio de Chroma de 2025 hizo 194 480 llamadas con 18 modelos de Anthropic, OpenAI, Google y Alibaba. El rendimiento bajó al crecer la longitud de la entrada en todos los experimentos, y los pasajes «distractores» relacionados temáticamente redujeron aún más la precisión. En LongMemEval, un benchmark de memoria conversacional, todos los modelos puntuaron claramente más alto con un prompt centrado de unos 300 tokens que con el prompt completo de unos 113 000 tokens (Chroma, 2025).
La posición importa. En el estudio «Lost in the Middle», los modelos aprovechaban mejor la información que estaba al principio o al final de una entrada larga, y notablemente peor la que estaba en el medio (Liu et al., TACL). La única restricción que importa puede desaparecer dentro de una exportación larga.
La atención es un presupuesto. Anthropic describe el context rot como la capacidad decreciente de un modelo para recordar información a medida que se llena la ventana, porque cada token atiende a todos los demás, lo que crea n² relaciones para n tokens. Su consejo es conservar identificadores ligeros, como rutas de archivos y enlaces, y cargar el contenido cuando el agente lo necesite (Anthropic, 2025).
La documentación de las herramientas dice lo mismo con palabras más llanas. VS Code señala que las referencias explícitas cuentan para la ventana de contexto y recomienda añadir solo las fuentes que ayuden con la tarea actual (VS Code docs).
Regla de decisión: incluye una fuente si puede cambiar la implementación o la decisión de aceptación. Una nota de decisión reciente más dos ejemplos representativos de clientes vale más que una exportación completa del backlog. Enlaza todo lo demás.
¿Cómo separas el contexto de producto de las instrucciones del repositorio?
Mantén tres tipos de contexto diferenciados, cada uno con su lugar y su responsable.
1. Decisiones de producto compartidas
El problema del cliente, las pruebas de investigación, las decisiones estratégicas y las que necesitan varias personas. Guárdalas en el espacio de trabajo de producto que el equipo ya usa. Cada decisión debería tener responsable, fecha, motivo y enlaces a las pruebas. Una plantilla de registro de decisiones de producto o un grafo de decisiones para equipos pequeños de IA funcionan igual de bien.
2. Instrucciones del repositorio
Guía de ingeniería estable: cómo ejecutar la app, convenciones, límites de arquitectura, comandos de test y reglas de seguridad. Anthropic dice que Claude trata CLAUDE.md como contexto y no como configuración impuesta, y que los archivos más largos reducen el cumplimiento (Claude Code docs). Los archivos anidados ayudan en bases de código grandes: con AGENTS.md prevalece el archivo más cercano al código editado, y el repositorio principal de OpenAI tenía 88 cuando se escribió el sitio agents.md (agents.md). Nada de esto es lugar para la hoja de ruta ni para la investigación de clientes.
3. El task packet
El puente breve entre la intención de producto y una sesión de código. Apunta a las decisiones relevantes y dice qué debe hacer este cambio. Puede vivir en una incidencia, un brief o un prompt, siempre que los responsables puedan encontrarlo. Para una versión completa con comprobaciones de aceptación y reglas de parada, usa la plantilla de PRD para agentes de código con IA.
Esta separación da al agente lo suficiente para actuar, y el conocimiento de producto duradero del equipo se queda donde las personas pueden discutirlo y actualizarlo.
¿Cómo das contexto de producto a un agente de código, paso a paso?
Empieza con un problema de usuario. Indica a quién afecta y qué intenta hacer. Enlaza la entrevista, los ejemplos de soporte o la analítica que lo respaldan. Etiqueta las suposiciones como suposiciones; una explicación verosímil escrita por una IA no es una prueba de cliente. Si todavía no tienes pruebas, el flujo de customer discovery para product engineers es la forma rápida de conseguirlas.
Enlaza la decisión, no un montón de documentos. Elige las dos o tres fuentes que pueden cambiar la implementación. Si las fuentes se contradicen, di cuál es la vigente y pasa los conflictos importantes a una persona.
Indica el resultado y los límites. Describe el resultado visible para el usuario y después los límites: permisos, tratamiento de datos, flujos existentes, accesibilidad, rendimiento y qué queda fuera de alcance. Marca como abiertas las decisiones abiertas.
Haz que el packet sea fácil de verificar. Enumera lo que debe observar un revisor. Sustituye «funciona bien» por un comportamiento que alguien pueda comprobar.
Pide al agente que informe de la incertidumbre. Que señale el contexto que falta, las instrucciones contradictorias y las suposiciones antes de tomar una decisión importante. Para un cambio reversible y de bajo impacto, seguir adelante con una suposición etiquetada puede estar bien. Con control de acceso, facturación, datos privados o acciones destructivas, la ambigüedad vuelve a una persona.
Revisa y devuelve las nuevas decisiones a la fuente compartida. El resultado del agente es una propuesta. Una persona lo contrasta con la intención de producto mediante una checklist de aceptación de PM para el trabajo de agentes de IA, y cualquier decisión nueva se anota en el registro de producto, no solo en la transcripción de un chat o en un comentario del código.
Ejemplo: un context packet para filtros guardados
Este es un escenario ilustrativo, no una historia de cliente ni un hallazgo de investigación.
Un fundador técnico pide a un agente de código con IA que añada filtros guardados a un panel interno. «Añade filtros guardados» deja abiertas decisiones de producto: quién lo necesita, si las vistas son privadas o compartidas, qué pasa cuando cambian los datos y cómo encuentra un usuario una vista guardada más adelante.
El task packet dice:
Usuario y problema: un miembro del equipo reconstruye la misma vista filtrada antes de cada revisión semanal, unos 10 minutos cada vez en este caso hipotético.
Pruebas: enlace a la nota de la entrevista o al flujo observado. Si no existe, el packet dice «suposición».
Resultado deseado: un usuario puede guardar una vista con nombre, volver a abrirla y ver cuándo se actualizaron sus datos por última vez.
Restricciones: no cambiar las definiciones de los informes; mantener las vistas guardadas privadas por defecto; respetar los permisos existentes del espacio de trabajo.
Comprobaciones de aceptación: guardar y volver a abrir una vista; renombrarla y eliminarla; gestionar un resultado vacío; mostrar un estado claro tras revocar el acceso; controles utilizables con teclado.
Decisión abierta: ¿debe poder compartirse una vista guardada con el espacio de trabajo? Una persona designada decide antes de que el agente construya el compartir.
Fuera de alcance: un nuevo constructor de paneles o un modelo de informes rediseñado.
Ahora el agente tiene un resultado y unos límites, pero sigue eligiendo la implementación. La pregunta sobre compartir es visible antes de que exista el código, en lugar de adivinarse en silencio. Tras la construcción, el revisor comprueba los mismos cinco comportamientos y registra la decisión sobre compartir en la fuente compartida del equipo.
Plantilla de context packet para copiar
## Context packet: [feature]
- User and problem: [who needs what; what they do today]
- Evidence: [links to specific observations or data] (observed / inferred / assumed)
- Desired outcome: [the change a user should notice]
- Current decision: [the choice] (owner: [name], date: [YYYY-MM-DD], link: [record])
- Constraints: [security, permissions, data, accessibility, compatibility, performance]
- Acceptance checks: [observable behaviours, incl. empty, loading and error states]
- Open questions: [what is unknown] -> [who answers]
- Out of scope: [adjacent work to leave alone]
- Sources as of: [date or version]
- Review owner: [person who accepts the result and updates the record]
Mantenlo proporcionado. Un prototipo de una sola pantalla puede necesitar cuatro viñetas. Un cambio en el acceso a datos sensibles necesita todas las líneas y un revisor con nombre.
¿Cómo evitas que el contexto de los agentes se quede obsoleto?
El contexto obsoleto es peor que la falta de contexto, porque el agente lo sigue con total seguridad. Cinco hábitos lo mantienen al día:
Una copia canónica por dato. Si una regla de producto aparece en varios archivos, decide cuál es la canónica y enlázala desde los demás. La documentación de Cursor da el motivo: las copias se quedan obsoletas, así que referencia archivos (Cursor docs).
Pon fecha a cada packet. «Fuentes a 12 de noviembre» le dice al revisor si una decisión se ha movido desde entonces.
Asigna un responsable a cada archivo. Un archivo de instrucciones sin responsable crece hasta que nadie se fía de él.
Poda tras los errores, no antes. Añade una regla cuando el agente repita el mismo error; quita las reglas que ya cumple a partir del código.
Cierra el círculo tras la revisión. Las decisiones tomadas durante la implementación vuelven al registro de decisiones el mismo día.
Comprobación rápida de la calidad del contexto
Antes de entregar el trabajo, pregúntate:
¿Puede un compañero encontrar las pruebas detrás de la petición?
¿Se distingue la decisión vigente de una propuesta antigua?
¿Conoce el agente el resultado que se busca para el usuario?
¿Están explícitos las restricciones y los no objetivos?
¿Puede un revisor comprobar el resultado sin reconstruir la conversación?
¿Hay una persona designada para las decisiones de producto sin resolver?
Si dos o más respuestas son negativas, arregla el packet o resuelve la decisión antes de que el agente construya.
Errores comunes al dar contexto de producto a los agentes
Volcar el backlog. Una exportación completa entierra la única decisión que importa y cuesta contexto en cada turno.
Escribir un segundo wiki para el agente. Se aleja del real en pocas semanas y nadie se hace cargo.
Poner decisiones cambiantes en CLAUDE.md o AGENTS.md. Estos archivos se cargan en cada tarea; resérvalos para reglas duraderas.
Tratar como actual un archivo llamado «context». Estar junto al código no lo hace cierto. Comprueba la fecha.
Conceder acceso de escritura por defecto. Empieza en solo lectura y amplía solo cuando una tarea lo necesite.
Dejar las decisiones en el chat. Si el único registro de una decisión es una transcripción, el siguiente agente y el siguiente compañero no la encontrarán.
Dónde encaja Specky
Specky reúne llamadas con clientes, feedback, tickets y decisiones en un único Product Graph, de modo que las pruebas detrás de una decisión quedan enlazadas en lugar de copiadas. Su servidor MCP permite que Claude Code, Cursor, Codex y otros clientes MCP obtengan ese contexto cuando lo necesitan: get_product_context carga los principios de producto confirmados y las instrucciones del espacio de trabajo, y get_coding_brief devuelve los PRD, decisiones y pruebas relevantes para un ticket. Todo lo que el agente escribe de vuelta llega como borrador para revisión humana. La configuración está en la página de MCP para agentes de IA, y la guía para PMs técnicos cubre el flujo de trabajo completo.
Preguntas frecuentes
¿Qué es el contexto de producto para un agente de código con IA?
Es la información que un agente necesita y que el código no muestra: quién tiene el problema, las pruebas que lo respaldan, la decisión vigente y su responsable, las restricciones, los no objetivos y las comprobaciones que hará un revisor. El contexto de código, como la estructura de archivos y los comandos de test, el agente suele encontrarlo solo. El contexto de producto tiene que aportarlo alguien.
¿Cuál es la mejor herramienta para dar contexto de producto a agentes de código con IA?
Ninguna herramienta lo hace todo. Usa un archivo corto en el repositorio (CLAUDE.md, AGENTS.md o reglas de Cursor) para las reglas duraderas, un task packet o PRD por cambio y una conexión MCP al lugar donde viven tus decisiones y pruebas, como un gestor de incidencias, una herramienta de documentación o un espacio de trabajo de pruebas de producto. Elige según dónde registra de verdad tu equipo las decisiones.
¿El contexto de producto va en CLAUDE.md o AGENTS.md?
Solo un puntero a él. Esos archivos se cargan en cada tarea y funcionan mejor si son cortos: Anthropic recomienda menos de 200 líneas por CLAUDE.md. Pon ahí comandos, convenciones y reglas de seguridad, más una línea que diga dónde viven las decisiones de producto. Mantén las pruebas de clientes y las decisiones cambiantes en su lugar compartido y enlázalas desde cada tarea.
¿Cuánto contexto debo dar a un agente de código?
Lo suficiente para cambiar la implementación o la decisión de aceptación, y no más. El estudio de Chroma sobre context rot y el artículo «Lost in the Middle» muestran que los modelos se vuelven menos fiables cuando crecen las entradas y pasan por alto la información enterrada en el medio. En la práctica, una nota de decisión, dos o tres ejemplos representativos y comprobaciones de aceptación claras suelen superar a una exportación completa de documentos.
¿Puede un agente de código con IA leer Jira, Linear o Notion directamente?
Sí, mediante servidores MCP. Linear aloja uno que funciona con Claude Code, Cursor, Codex y VS Code, y el de Notion permite a un asistente buscar páginas y bases de datos. Empieza con acceso de solo lectura y recuerda que los tickets y las páginas de wiki rara vez dicen qué decisión es la vigente ni qué pruebas la respaldan. Eso sigue necesitando un task packet.
GDPR-aligned. EU workspace data is stored in Frankfurt, Germany. GDPR and EU data Built in Vienna, Austria. A product of influence solutions fm GmbH (FN 675374y). Imprint 14-day trial. Card required, and nothing is charged until day 14. 30-day refund after subscribing. See pricing