Context engineering para agentes de código es la práctica de decidir qué entra, qué queda fuera y qué se busca solo cuando un loop agentic lo necesita. La respuesta corta: no le entregues todo el repositorio al agente. Dale una spec clara, pistas trazables, comandos de verificación y herramientas para buscar el resto.
En 2025, el Stack Overflow Developer Survey informó que 84% de las personas encuestadas usa o planea usar IA en desarrollo, frente a 76% el año anterior (Stack Overflow, Developer Survey 2025 AI, acceso 2026-07-01). Esa adopción convierte el control de contexto en práctica de ingeniería.
Este artículo continúa el harness para agentes de código antes del PR. El harness decide cuándo el agente puede entregar. El context engineering decide qué debe saber antes de empezar, durante la investigación y antes de abrir el pull request.
Versiones de este artículo: portugués e inglés. Para contexto de autoría, consulta la página sobre. Para contacto editorial, usa contato.
TL;DR práctico
- Con 84% de uso o intención de uso de IA, el contexto ya es un cuello de botella.
- El agente debe empezar con spec, archivos probables, contratos y comandos, no con dump del repo.
- Subagentes, MCP y RAG ayudan cuando retrasan la lectura hasta que importa.
¿Qué es context engineering para agentes de código?
En 2025, 51% de desarrolladores profesionales dijo usar herramientas de IA todos los días (Stack Overflow, Developer Survey 2025 AI, acceso 2026-07-01). Context engineering es la respuesta operativa a esa frecuencia: preparar una ventana de trabajo que ayude al agente a decidir, editar y verificar sin llenar la conversación.
El error común es tratar contexto como volumen. Más archivos no significan más comprensión. Un agente puede leer muchos fragmentos y aun así perder el contrato que importaba: la ruta que no puede romperse, la cola que exige idempotencia, la migración que necesita rollback o la prueba que representa el comportamiento real.
El buen contexto tiene función. Reduce incertidumbre antes de la primera edición, muestra dónde buscar cuando aparece una duda y preserva evidencia para revisión. Si un fragmento no cambia ninguna de esas decisiones, probablemente no debe entrar al comienzo del loop.
En síntesis, context engineering para agentes de código convierte un repositorio grande en un camino navegable. Stack Overflow registró 51% de uso diario de IA entre desarrolladores profesionales en 2025 (Stack Overflow, acceso 2026-07-01), así que la ventaja no está solo en el modelo. Está en lo que el agente recibe, lo que puede buscar y lo que debe probar antes de entregar.
¿Por qué demasiado contexto empeora el agentic coding?
Anthropic describe un cambio hacia estrategias de contexto "just in time", donde los agentes mantienen identificadores ligeros, como rutas de archivo y consultas guardadas, y cargan datos en tiempo de ejecución con herramientas (Anthropic, Effective context engineering for AI agents, acceso 2026-07-01). El punto es directo: el contexto útil puede buscarse cuando se vuelve necesario.
Cuando apilas archivos demasiado pronto en el prompt, el agente gasta atención en material que quizá nunca use. La conversación queda más difícil de auditar. La siguiente iteración arrastra decisiones antiguas, logs e hipótesis que debieron descartarse.
La mejor pregunta no es "¿cuánto cabe en la ventana?". Es "¿qué información cambia la próxima decisión?". Para una corrección de API, eso suele incluir contrato, handler, prueba cercana, middleware y comando de validación. No suele incluir documentación vieja, logs completos, changelog entero o archivos generados.
En loops largos, el ahorro real viene de avanzar más sin releer el mismo contexto. Cuando el agente necesita investigar codebases grandes o sostener loops agentic, una herramienta del propio autor como RemoteCode para hacer que Claude Code y Codex avancen más con menos desperdicio de contexto puede ayudar, siempre que la decisión final siga en el harness y en CI.
¿Cómo montar el contexto inicial antes de la primera edición?
En 2025, 47,1% de todos los respondentes de Stack Overflow dijo usar IA diariamente, y 17,7% dijo usarla semanalmente (Stack Overflow, Developer Survey 2025 AI, acceso 2026-07-01). Con ese ritmo, el contexto inicial debe ser una rutina corta, no una ceremonia pesada.
Empieza por la spec. Debe decir el comportamiento esperado, lo que está fuera de alcance y el criterio de aceptación. Después enumera archivos probables y por qué importan. Luego registra contratos externos: endpoint, schema, evento de cola, feature flag, permiso o variable de entorno.
Incluye los comandos que prueban el cambio. Para backend, pueden ser prueba unitaria, prueba de integración, typecheck, lint y comando local que sube dependencias. Para DevOps, puede ser plan de IaC, validación de policy, prueba de workflow y simulación del job más cercana al entorno real.
| Entrada de contexto | Por qué entra | Señal de descarte |
|---|---|---|
| Spec corta | Define el contrato del trabajo | Si vira discusión de producto, vuelve a refinamiento. |
| Archivos probables | Da punto de partida para navegar | Si el agente no justifica la lectura, sale del inicio. |
| Pruebas cercanas | Muestra comportamiento esperado | Si no cubren el cambio, se ajustan antes del patch. |
| Comandos de verificación | Evitan entrega por apariencia | Si no corren, el PR debe explicar el bloqueo. |
| Contratos externos | Evitan romper consumidores | Si la fuente no existe, la afirmación sale del PR. |
En síntesis, el contexto inicial debe caber en una revisión humana rápida. El uso diario de IA por 47,1% de respondentes en 2025 (Stack Overflow, acceso 2026-07-01) vuelve este preparo lo bastante repetitivo como para estandarizarlo. Si el agente no puede nombrar contrato, prueba y archivo detrás de la primera edición, todavía está explorando.
¿Cuándo usar subagentes para preservar contexto?
La documentación de Claude Code afirma que cada subagente corre en su propia ventana de contexto, con prompt, acceso a herramientas y permisos independientes, y luego devuelve resultados a la conversación principal (Anthropic, Create custom subagents, acceso 2026-07-01). Úsalos cuando la exploración lateral generaría ruido.
Un subagente no es invitación a delegar todo. Funciona bien para tareas estrechas: ubicar archivos relevantes, resumir logs, revisar un diff, comparar contratos o investigar una prueba fallida. La respuesta debe ser corta, con evidencia y próximos pasos. Si devuelve un bloque enorme, el problema de contexto solo cambió de lugar.
Usa fan-out cuando las preguntas son independientes. Un subagente lee logs de producción, otro revisa migración y otro busca pruebas relacionadas. El agente principal decide con las síntesis. No dejes varios subagentes editando los mismos módulos sin una spec común.
En síntesis, los subagentes preservan contexto cuando aíslan exploración y devuelven decisión. La propia documentación advierte que muchos subagentes devolviendo resultados detallados pueden consumir contexto significativo (Anthropic, Create custom subagents, acceso 2026-07-01). El formato de respuesta importa tanto como la delegación.
¿Dónde entran MCP y RAG sobre codebase?
El Model Context Protocol define MCP como un estándar abierto para conectar aplicaciones de IA a sistemas externos, incluidas fuentes de datos, herramientas y workflows (Model Context Protocol, What is MCP?, acceso 2026-07-01). En trabajo de código, eso debe ser puerta de acceso, no basurero de información.
MCP ayuda cuando el agente necesita consultar issue, base de prueba, Sentry, documentación interna, Figma, GitHub u otro sistema fuera del repositorio. El contexto inicial debe decir cuándo usar la herramienta y qué evidencia debe volver. No debe pegar toda la issue, todo el log y todo el schema antes de que la decisión lo exija.
La documentación de Claude Code recomienda conectar MCP cuando te ves copiando datos de otra herramienta al chat, como un issue tracker o un dashboard de monitoreo (Anthropic, Connect Claude Code to tools via MCP, acceso 2026-07-01). Esa es una regla práctica: si lo pegas siempre, quizá merece herramienta.
RAG sobre codebase sigue la misma lógica. Ayuda a encontrar fragmentos candidatos, pero no reemplaza lectura dirigida. El agente aún debe explicar por qué ese archivo importa, qué contrato encontró y qué prueba protege el cambio.
¿Cómo leen Codex y Claude Code las instrucciones del proyecto?
La documentación de Codex informa que los archivos AGENTS.md se concatenan desde el directorio raíz hasta el directorio actual, y que el límite predeterminado para instrucciones de proyecto es 32 KiB (OpenAI, Custom instructions with AGENTS.md, acceso 2026-07-01). Las instrucciones también consumen presupuesto de contexto.
No conviertas AGENTS.md en enciclopedia. Pon allí reglas estables: comandos de prueba, estándar de PR, límites de permiso, archivos protegidos, estilo de migración y criterio de revisión. El contexto específico de la tarea debe quedar en la spec, porque cambia en cada loop.
Claude Code usa otra superficie de configuración, pero la idea de capas sigue siendo útil. Las instrucciones durables quedan en el proyecto. El contexto efímero queda en la tarea. Los datos externos entran por herramienta. El resultado de investigación se convierte en síntesis corta.
¿Cómo verificar si el contexto funcionó antes del PR?
En 2025, 58,7% de los respondentes de Stack Overflow dijo que no planea usar IA para commit y revisión de código, mientras 44,1% dijo que no planea usar IA para pruebas (Stack Overflow, Developer Survey 2025 AI, acceso 2026-07-01). Ese escepticismo es útil: el contexto solo importa cuando mejora la verificación.
Pide al agente un informe final corto. Debe listar archivos leídos, fuentes externas consultadas, comandos ejecutados, pruebas que fallaron antes, pruebas que pasaron después y riesgos que quedaron. Si algo no fue verificado, debe aparecer como limitación, no como confianza.
Codex Code Review puede revisar pull requests en GitHub, seguir orientación del repositorio y enfocarse en problemas serios; la documentación dice que marca hallazgos P0 y P1 para mantener los comentarios centrados en riesgos prioritarios (OpenAI, Codex code review in GitHub, acceso 2026-07-01). Una revisión útil corta ruido.
La prueba final es simple: el contexto funcionó si el diff quedó menor, la justificación se volvió más auditable y CI pudo confirmar comportamiento. Si el agente cambió demasiado, no leyó el contrato o no sabe explicar una decisión, vuelve al mapa de contexto antes de pedir otro patch.
FAQ sobre context engineering para agentes de código
¿Qué es context engineering para agentes de código?
Es la práctica de elegir y organizar el contexto que guía a un agente de código. En vez de cargar todo en el prompt, das spec, archivos probables, contratos y comandos, mientras dejas búsquedas mayores para herramientas, subagentes o MCP.
¿Cómo ahorrar tokens sin dejar ciego al agente?
Usa contexto inicial pequeño y navegación bajo demanda. Anthropic describe estrategias "just in time" donde los agentes mantienen referencias ligeras y cargan datos en runtime (Anthropic, acceso 2026-07-01). Eso reduce ruido sin impedir investigación.
¿Cuándo ayudan los subagentes con el contexto?
Ayudan cuando una tarea lateral llenaría la conversación principal con logs, búsquedas o archivos largos. La documentación de Claude Code dice que subagentes corren en ventanas propias y devuelven resultados (Anthropic, acceso 2026-07-01). El resultado debe ser síntesis.
¿MCP debe entrar en el contexto inicial?
Normalmente no. MCP debe estar disponible como herramienta cuando el agente necesita sistemas externos. El protocolo define MCP como estándar abierto para conectar IA a datos, herramientas y workflows (Model Context Protocol, acceso 2026-07-01).
Fuentes consultadas
- Stack Overflow, Developer Survey 2025 AI, acceso 2026-07-01, https://survey.stackoverflow.co/2025/ai
- Anthropic, Effective context engineering for AI agents, acceso 2026-07-01, https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
- Anthropic, Create custom subagents, acceso 2026-07-01, https://code.claude.com/docs/en/sub-agents
- Anthropic, Connect Claude Code to tools via MCP, acceso 2026-07-01, https://code.claude.com/docs/en/mcp
- Model Context Protocol, What is MCP?, acceso 2026-07-01, https://modelcontextprotocol.io/docs/getting-started/intro
- OpenAI, Custom instructions with AGENTS.md, acceso 2026-07-01, https://developers.openai.com/codex/guides/agents-md
- OpenAI, Codex code review in GitHub, acceso 2026-07-01, https://developers.openai.com/codex/integrations/github
Créditos de imágenes: infografías raster generadas localmente en SVG y convertidas a WebP para este post. Los créditos quedan en /files/posts/context-engineering-agentes-codigo-sem-estourar-tokens/image-credits.txt.
