Context engineering para agentes de código sin desperdicio

Context engineering para agentes de código es la práctica de controlar qué evidencias, herramientas y memorias entran en el trabajo del agente. No consiste en meter más material en el prompt. Consiste en decidir, antes de que empiece el loop, qué evidencia entra, qué ruido queda fuera y qué verificación cierra la tarea.

En 2025, Google Cloud informó en el reporte DORA que la adopción de IA entre profesionales de software llegó al 90%, con una mediana de dos horas diarias de uso (Google Cloud, "How are developers using AI? Inside our 2025 DORA report", 2025). El acceso ya no es el problema principal. La memoria útil, el costo, la confianza y la revisión sí lo son.

TL;DR: puntos clave

• DORA midió 90% de adopción de IA en software, mientras Stack Overflow midió 46% de desconfianza en la precisión. El camino práctico es menos contexto, mejor verificación y loops con reglas claras de parada.
• Los subagentes ayudan cuando devuelven síntesis, no volcados de logs.
• MCP debe exponer herramientas y recursos con alcance definido, no toda la empresa por defecto.

¿Por qué context engineering se volvió el cuello de botella?

En 2025, Stack Overflow midió que el 84% de los encuestados usa o planea usar herramientas de IA en desarrollo, pero el 46% desconfía de la precisión de esos resultados (Stack Overflow, "2025 Developer Survey: AI", 2025). Context engineering se volvió el cuello de botella porque el agente necesita suficiente evidencia para actuar, sin recibir tanto ruido que se desvíe.

El error común es tratar la ventana de contexto como almacenamiento. El agente recibe README, logs largos, conversaciones antiguas, árbol completo, issue entera, stack trace bruto y reglas duplicadas. Eso parece seguro, pero empeora la revisión. La persona que lee el diff no sabe qué premisa importó ni qué prueba cerró la tarea.

Un flujo mejor separa el contexto en capas. El contexto estable explica cómo funciona el repositorio. El contexto recuperado trae archivos y decisiones relevantes. El contexto operativo define comandos, límites y permisos. La evidencia registra lo que se probó. Cada capa necesita dueño, vigencia y forma de expirar.

Esto conecta directamente con mi artículo sobre un harness de agentes de código para pull requests confiables. El harness decide si el trabajo pasa. Context engineering decide si el agente recibió material suficientemente bueno para llegar allí sin desperdiciar iteraciones.

Según Stack Overflow, en 2025 solo el 3,1% de los encuestados dijo confiar mucho en la precisión de las herramientas de IA, mientras el 19,6% dijo desconfiar mucho (Stack Overflow, "2025 Developer Survey: AI", 2025). El punto no es abandonar agentes. Es hacer que el error aparezca temprano, con un rastro que el revisor pueda inspeccionar.

¿Qué entra en el presupuesto de contexto?

En 2025, DORA informó que el 65% de los profesionales dependía de IA en desarrollo de software en niveles moderado, alto o muy alto (Google Cloud, "How are developers using AI? Inside our 2025 DORA report", 2025). Un presupuesto de contexto convierte esa dependencia en un contrato operativo: el agente recibe objetivo, restricciones, evidencia y criterios de parada.

Empieza por el contexto que casi no cambia. Debe caber en un archivo corto, como AGENTS.md, CLAUDE.md o un documento equivalente. Incluye estructura del repositorio, comandos de build, estándares de pull request, reglas de seguridad y definición de terminado. La documentación de Codex recomienda que AGENTS.md cubra estructura, comandos, convenciones, restricciones y verificación del trabajo (OpenAI Developers, "Best practices - Codex", 2026).

Después viene el contexto recuperado. Aquí entran búsqueda léxica, búsqueda vectorial, grafo de dependencias e historial de decisiones. Para codebases grandes, RAG sobre codebase solo funciona cuando devuelve fragmentos pequeños con motivo. Una búsqueda que entrega diez archivos completos es otra forma de ensuciar el prompt.

Por último, define el contexto operativo. Responde qué herramientas se pueden usar, qué comandos son baratos, qué comandos exigen permiso y qué salida debe volver a la conversación principal. En loops largos con Claude Code o Codex, uso una regla simple: los logs brutos van a un archivo; el agente principal recibe una síntesis con rutas, fallos y próximo paso.

Un presupuesto de contexto para agentes de código limita lo que entra en la conversación principal y mueve el ruido a artefactos auditables. Esa disciplina reduce retrabajo porque el agente deja de discutir logs antiguos y empieza a operar sobre objetivo, prueba y restricción. Es la diferencia entre "lee todo" y "usa estas señales para esta decisión".

¿Cómo montar un agentic loop que se corrige?

En 2025, OpenAI describió Codex como un agente que trabaja en tareas paralelas y normalmente tarda de 1 a 30 minutos por tarea (OpenAI, "Introducing Codex", 2025). Un loop que se corrige debe usar esa capacidad como sistema de prueba, no como permiso para aceptar cualquier diff.

El loop empieza con una tarea estrecha. Debe decir qué comportamiento cambia, dónde observar el resultado y qué no puede modificarse. Luego el agente crea un plan corto, consulta la codebase, aplica el cambio, ejecuta verificación y registra evidencia. Si falla, no debería empezar desde cero; debería reducir la hipótesis e intentar de nuevo.

Usa evals cuando la salida no cabe en una prueba unitaria. OpenAI recomienda empezar los problemas difíciles definiendo cómo se medirá el éxito, combinando chequeos deterministas y evaluación por rúbrica cuando sea necesario (OpenAI Developers, "Iterate on difficult problems", 2026). En software, eso mezcla pruebas automatizadas, análisis estático, revisión semántica e inspección del artefacto final.

tarea:
  objetivo: "corregir fallo de expiracion de sesion en el endpoint de renovacion"
  fuera_de_alcance: "no cambiar el proveedor de autenticacion"
contexto:
  archivos_obligatorios:
    - "src/auth/session.service.ts"
    - "src/auth/session.controller.ts"
  recuperar:
    - "pruebas que mencionan renovacion de sesion"
    - "decisiones de arquitectura sobre tokens"
verificacion:
  comandos:
    - "npm run test -- auth"
    - "npm run lint"
  parada: "diff pequeño, pruebas pasando y explicacion del riesgo residual"

En la práctica, este contrato funciona mejor cuando el agente debe escribir su propia hipótesis antes de editar. Si la hipótesis no menciona archivo, comportamiento y verificación, la tarea sigue siendo vaga. Eso fuerza una pausa barata antes de la parte cara: cambiar código.

En mi experiencia revisando cambios generados por agentes, la hipótesis corta reduce la discusión circular. Cuando el agente escribe "tocaré este archivo, por este comportamiento, y lo probaré con este comando", el revisor puede separar fallo de contexto, fallo de implementación y fallo de prueba.

Para loops que necesitan cruzar varias sesiones, una herramienta como RemoteCode para extender Claude Code y Codex en flujos agentic es un recurso del propio autor de este blog para mantener el contexto de trabajo más económico y permitir que los agentes avancen más sin cargar todo el historial en el prompt principal.

Un agentic loop autocorrectivo no es "autonomía" en sentido laxo. Es un proceso con memoria limitada, herramientas explícitas y salida verificable. El agente puede intentar más de una vez, pero cada intento debe producir evidencia más pequeña y mejor que la anterior.

¿Cuándo usar subagentes en vez de una conversación mayor?

En 2025, Stack Overflow señaló que el 69% de los usuarios de agentes estuvo de acuerdo en que aumentaron la productividad, pero solo el 17% dijo que mejoraron la colaboración del equipo (Stack Overflow, "2025 Developer Survey: AI", 2025). Los subagentes ayudan cuando reducen coordinación, no cuando crean una reunión paralela entre modelos.

Usa subagentes para lectura, investigación y crítica independiente. Un subagente puede buscar riesgos de seguridad. Otro puede mapear pruebas rotas. Otro puede resumir cambios en un módulo legado. El agente principal no necesita cada comando que ejecutaron. Necesita hallazgos con archivo, línea, confianza y recomendación.

La documentación de subagentes de Codex advierte que volcar notas de exploración, logs y stack traces en la conversación principal contamina y degrada el contexto. La recomendación es mantener al agente principal enfocado en requisitos, decisiones y salida final, mientras los subagentes devuelven síntesis (OpenAI Developers, "Subagents", 2026).

Esta división funciona bien con RAG sobre codebase y grafos de conocimiento. El subagente de recuperación puede explicar por qué eligió ciertos archivos. El subagente de pruebas puede explicar qué suite cubre el comportamiento. El subagente de revisión puede señalar regresiones probables. La conversación principal se vuelve el lugar de decisión.

Evita subagentes escribiendo en el mismo tramo de código al mismo tiempo. Eso aumenta conflicto y vuelve confusa la autoría de la decisión. Si necesitas paralelizar escritura, divide por fronteras reales: paquete, servicio, ruta, schema o capa de infraestructura. Aun así, consolida con un agente revisor antes de abrir el pull request.

Un fan-out útil tiene tres propiedades. La tarea de cada subagente es pequeña. La salida de cada subagente es una síntesis. El merge final exige prueba. Si falta alguna, una conversación única con contexto más limpio suele ser mejor.

¿Cómo cambia MCP la disciplina de contexto?

En 2025, la especificación del Model Context Protocol definió tres superficies centrales para servidores: recursos, prompts y herramientas (Model Context Protocol, "Specification 2025-11-25", 2025). MCP cambia la disciplina de contexto porque convierte acceso en interfaz: el agente no necesita recibir todo cuando puede consultar lo correcto en el momento correcto.

Para agentes de código, los recursos MCP pueden exponer archivos, schemas de base de datos, documentación interna o decisiones arquitectónicas. Las herramientas MCP pueden ejecutar búsqueda, consulta SQL, inspección de colas, lectura de feature flags o ejecución controlada de pruebas. Los prompts MCP pueden estandarizar flujos como triage de bug, revisión de seguridad o análisis de migración.

El riesgo es confundir capacidad con permiso. Un servidor MCP que accede a toda la base, todos los secretos y todos los repositorios convierte un error de prompt en error operativo. La regla práctica es exponer herramientas estrechas, con argumentos tipados, alcance por workspace y salida resumida. El agente debe pedir más contexto, no recibirlo todo por defecto.

OWASP lista prompt injection, divulgación de información sensible, supply chain, denegación de servicio de modelo y exceso de agencia entre los riesgos de aplicaciones con LLMs en 2025 (OWASP, "Top 10 for Large Language Model Applications", 2025). En un entorno con MCP, esos riesgos dejan de ser teóricos porque una herramienta puede ejecutar efectos reales.

El mejor diseño de MCP para desarrollo no imita una terminal ilimitada. Se parece más a una API interna: herramientas pequeñas, nombres explícitos, logs de auditoría y respuestas que caben en una decisión. Si la herramienta devuelve una enciclopedia, está compitiendo con el presupuesto de contexto.

¿Cómo medir si el contexto mejoró?

En 2025, GitHub informó que los desarrolladores fusionaron en promedio 43,2 millones de pull requests por mes y crearon más de 230 repositorios por minuto (GitHub, "Octoverse 2025", 2025). A escala real, medir mejor contexto significa medir revisión, retrabajo y tiempo hasta la prueba, no líneas generadas.

Elige métricas que el equipo ya siente. ¿Cuántos intentos necesita el agente antes de que pase una prueba? ¿Cuántos archivos irrelevantes toca? ¿Cuántos comentarios de code review repiten el mismo fallo? ¿Cuántas veces el agente pide contexto que ya debería estar en AGENTS.md? Esas respuestas muestran dónde se fuga el presupuesto.

Para equipos TypeScript, una métrica simple es la tasa de fallo en typecheck después de cambios generados por IA. GitHub observó en 2025 que TypeScript llegó al primer lugar en crecimiento de contribuidores y conectó esa subida con sistemas tipados que ayudan a llevar código asistido por IA a producción (GitHub, "Octoverse 2025", 2025). Los tipos se vuelven parte del harness de contexto.

Usa una revisión breve después del loop. Pide al agente responder qué contexto faltó, qué sobró y qué regla debería convertirse en instrucción estable. Si la respuesta sirve, actualiza AGENTS.md o el documento equivalente. Si es vaga, el loop no produjo aprendizaje operativo.

Una buena meta no es hacer que el agente use menos tokens a cualquier costo. La meta es hacer que cada token cargue una decisión. Un archivo correcto vale más que cinco archivos casi relacionados. Una prueba que falla con mensaje claro vale más que una explicación larga. Un resumen honesto de subagente vale más que mil líneas de log.

Checklist de adopción para una base real

En 2025, Google Cloud anunció que el reporte DORA combinó más de 100 horas de datos cualitativos con respuestas de casi 5.000 profesionales de tecnología (Google Cloud, "Announcing the 2025 DORA Report", 2025). La conclusión práctica es que la IA amplifica el sistema existente; adopta context engineering como mejora de plataforma, no como truco de prompt.

Antes de automatizar pull requests, escribe un archivo de instrucciones corto y real. Debe explicar cómo ejecutar el proyecto, cómo probar, cómo revisar y qué áreas son sensibles. Después, crea un mapa de recuperación: dónde viven decisiones arquitectónicas, schemas, contratos de API, colas, jobs y runbooks. Sin ese mapa, RAG se vuelve búsqueda genérica.

Luego, estandariza herramientas. Si el agente necesita consultar una base de datos, expón una herramienta de lectura con alcance. Si necesita probar una cola, expón un comando controlado. Si necesita revisar seguridad, ofrece checklist y prueba. Conecta esto al CI para que la evidencia no dependa de la buena voluntad del modelo.

Por último, cierra el ciclo en el pull request. El diff debe venir con resumen, comandos ejecutados, evidencia, riesgos residuales y puntos que exigen revisión humana. Ese formato conversa con el artículo sobre tipos de pruebas en desarrollo de software y con prácticas de arquitectura de servicios en TypeScript, porque un buen agente aún necesita fronteras claras.

Si la base tiene CI frágil, empieza pequeño. Elige un módulo, una suite, un tipo de tarea y un agente. Mide el retrabajo. Solo después agrega subagentes, MCP y automatizaciones. El context engineering real es incremental: cada regla nace de un fallo observado, no de una lista genérica de buenas prácticas.

Preguntas frecuentes (FAQ)

En 2025, Stack Overflow midió 84% de uso o intención de uso de IA entre desarrolladores, pero también registró 46% de desconfianza en la precisión (Stack Overflow, "2025 Developer Survey: AI", 2025). Las dudas importantes no tratan sobre adoptar IA, sino sobre limitar el riesgo operativo.

¿Context engineering es solo prompt engineering con otro nombre?

No. En 2025, DORA midió 90% de adopción de IA en desarrollo de software, lo que muestra que el problema ya está en todo el flujo, no solo en el prompt (Google Cloud, "How are developers using AI? Inside our 2025 DORA report", 2025). Context engineering incluye recuperación, herramientas, memoria, permisos, evals y prueba.

¿Cuándo vale la pena usar subagentes?

Vale usar subagentes cuando la tarea puede dividirse en investigación independiente. En 2025, Stack Overflow vio que el 69% de los usuarios de agentes percibió ganancia de productividad, pero solo el 17% vio mejora de colaboración (Stack Overflow, "2025 Developer Survey: AI", 2025). Eso favorece subagentes de análisis, no edición concurrente sin coordinación.

¿MCP hace más seguro al agente?

MCP mejora la interfaz, pero no garantiza seguridad por sí solo. En 2025, la especificación oficial separó recursos, prompts y herramientas como primitivas del protocolo (Model Context Protocol, "Specification 2025-11-25", 2025). La seguridad viene de alcance, autenticación, auditoría, revisión humana y herramientas estrechas.

¿Cuál es el primer artefacto que conviene crear?

El primer artefacto debe ser un archivo de instrucciones del repositorio. En 2026, la documentación de Codex recomienda AGENTS.md con layout del repo, comandos, convenciones, restricciones y definición de terminado (OpenAI Developers, "Best practices - Codex", 2026). Sin eso, cada sesión reaprende lo básico.

Cierre

En 2025, DORA observó que equipos con más confianza en IA tenían mayor ganancia de productividad, pero también advirtió que confianza sin fundamentos puede crear dependencia acrítica (Google Cloud, "How are developers using AI? Inside our 2025 DORA report", 2025). Context engineering para agentes de código es una práctica de arquitectura: define qué sabe el agente, cómo descubre lo que falta, qué herramientas puede invocar y qué prueba debe entregar.

El siguiente paso es simple: elige un tipo de tarea repetitiva, escribe el contrato de contexto, conecta la verificación y ejecuta un loop corto. Si el agente falla, no agrandes el prompt primero. Descubre qué evidencia faltó, qué ruido sobró y qué gate debería haber bloqueado el diff.

Fuentes consultadas

• Google Cloud, "How are developers using AI? Inside our 2025 DORA report", recuperado en 2026-06-30, https://blog.google/innovation-and-ai/technology/developers-tools/dora-report-2025/
• Google Cloud, "Announcing the 2025 DORA Report: State of AI-Assisted Software Development", recuperado en 2026-06-30, https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report
• Stack Overflow, "2025 Developer Survey: AI", recuperado en 2026-06-30, https://survey.stackoverflow.co/2025/ai
• GitHub, "Octoverse: A new developer joins GitHub every second as AI leads TypeScript to #1", recuperado en 2026-06-30, https://github.blog/news-insights/octoverse/octoverse-a-new-developer-joins-github-every-second-as-ai-leads-typescript-to-1/
• OpenAI, "Introducing Codex", recuperado en 2026-06-30, https://openai.com/index/introducing-codex/
• OpenAI Developers, "Best practices - Codex", recuperado en 2026-06-30, https://developers.openai.com/codex/learn/best-practices
• OpenAI Developers, "Subagents", recuperado en 2026-06-30, https://developers.openai.com/codex/concepts/subagents
• OpenAI Developers, "Iterate on difficult problems", recuperado en 2026-06-30, https://developers.openai.com/codex/use-cases/iterate-on-difficult-problems
• Model Context Protocol, "Specification 2025-11-25", recuperado en 2026-06-30, https://modelcontextprotocol.io/specification/2025-11-25
• OWASP, "Top 10 for Large Language Model Applications", recuperado en 2026-06-30, https://owasp.org/www-project-top-10-for-large-language-model-applications/