Los agentes de IA para programar no necesitan mejores prompts. Necesitan un arnes.

El primer error que cometi con los agentes de IA para programar fue tratar cada mal resultado como un problema de prompt. Si el agente tocaba el archivo equivocado, culpaba a mi redaccion. Si olvidaba una restriccion, agregaba otro parrafo. Si escribia codigo plausible pero fallaba en el flujo real, pedia un plan mas detallado. Eso funciona durante una tarde. Despues entiendes que el problema no es la frase. El problema es la superficie de operacion que le diste al agente.

La conversacion interesante en 2026 ya no es solo "Claude Code o Codex" ni "Cursor o Copilot". El modelo importa, claro. Pero el modelo ya no es todo el producto. Cuando un asistente puede leer un repositorio, editar archivos, ejecutar comandos shell, llamar herramientas MCP, abrir pull requests o tocar infraestructura, no estas usando autocompletado. Estas ejecutando un operador junior con una terminal.

Y un operador necesita un arnes.

Un prompt es una peticion de politica. Un arnes es la aplicacion de esa politica.

No uso "arnes" como una palabra elegante para plantilla de prompt. Hablo del sistema de control alrededor del modelo: contexto, herramientas, permisos, workflow, verificacion, recuperacion y memoria. El arnes decide que ve el agente, que puede tocar, que debe demostrar y que ocurre cuando se equivoca.

Si usas agentes de codigo en software real, esta diferencia vale mas que la mayoria de benchmarks.

La conversacion real entre desarrolladores

El marketing publico sigue sonando magico: describe la feature, espera el patch, mergea mas rapido. La conversacion privada entre desarrolladores es menos romantica.

La encuesta Developer Survey 2025 de Stack Overflow captura bien la tension. Las herramientas de IA ya son habituales o estan en los planes de muchos equipos, pero la confianza no crece al mismo ritmo. La mayor frustracion es el resultado "casi correcto". Esa frase duele porque es exacta. El codigo casi correcto es caro porque parece progreso hasta que tienes que integrarlo.

Por eso el debug de codigo generado por IA aparece tambien entre las grandes frustraciones. Un codigo malo que falla de inmediato molesta. Un codigo casi correcto es peor. Pasa la primera revision. Pasa el happy path. Usa nombres que parecen coherentes con el repo. Luego falla en el borde: autenticacion, permisos, migraciones, reintentos, zonas horarias, cache, teardown, rollback.

El dolor no es "la IA no sabe escribir codigo". Si sabe. El dolor es que generar codigo se volvio barato y verificarlo sigue siendo caro.

Veo el mismo patron en discusiones sobre Claude Code, Codex, Cursor y MCP. La gente habla de ventanas de contexto, calidad que baja, agentes que cambian demasiado, herramientas que meten salidas enormes en la conversacion, o agentes que hacen algo "logico" que ningun ingeniero de produccion habria permitido. Parecen quejas distintas. Tienen la misma raiz: el agente opera dentro de un arnes debil.

Que significa arnes en este contexto

Un arnes para agentes de codigo es la disciplina de runtime alrededor del modelo.

Tiene siete piezas:

1. Contexto: mapa del repo, brief de tarea, reglas del proyecto, decisiones anteriores y solo los archivos relevantes.
2. Herramientas: shell, sistema de archivos, navegador, GitHub, issue tracker, base de datos, observabilidad, servidores MCP.
3. Permisos: que puede leer, escribir, ejecutar, borrar, pushear, desplegar o consultar el agente.
4. Workflow: planificacion, edicion con alcance, review, CI, aprobacion humana, ruta de release.
5. Verificacion: tests, type checks, lint, browser checks, revision del diff, dry-runs de migracion, escaneos de seguridad.
6. Recuperacion: rollback, backups, checkpoints, logs de auditoria, soft deletes, estrategia de revert.
7. Memoria: notas duraderas sobre arquitectura, trampas, decisiones, intentos fallidos y convenciones.

Si falta una pieza, el prompt intenta compensar. Ahi empieza el problema. La gente escribe instrucciones mas largas, pero el agente conserva el mismo contexto gigante, el mismo token amplio, el mismo shell sin limites y el mismo incentivo a producir un patch que parezca completo.

Si el agente puede hacer lo incorrecto con un solo comando, el prompt no es la capa de control.

Un buen arnes convierte confianza vaga en restricciones aburridas. No vuelve al agente magicamente mas inteligente. Hace que el fallo sea mas pequeno.

Fallo 1: el contexto se pudre

El contexto degradado es el fallo silencioso. Nadie pierde una base de datos. Nadie escribe un postmortem viral. El agente simplemente empeora.

Empiezas con una tarea limpia. El agente lee cinco archivos. Luego lee tests. Luego un log de build. Luego un package file. Luego una issue larga. Luego un servidor MCP devuelve un payload enorme. Luego pegas un error. Luego el modelo resume un intento anterior. La sesion sigue acumulando material. En algun punto, la senal util sigue ahi, pero queda enterrada bajo historia.

La documentacion de Claude Code sobre la ventana de contexto es util porque hace visible lo invisible: instrucciones, archivos leidos, salidas de herramientas, historial de conversacion, skills, reglas y compactacion compiten por la misma memoria de trabajo. Eso significa que "mas contexto" no siempre es mejor. El contexto no es una biblioteca. Es presupuesto de atencion.

MCP hace esto mas evidente. MCP es potente porque conecta agentes con herramientas y datos reales. Pero los schemas de herramientas y las respuestas pueden consumir espacio rapido. La documentacion de Claude sobre MCP y tool search existe por una razon: cargar herramientas solo cuando hacen falta mantiene el working set mas limpio. Las discusiones en Hacker News sobre salidas MCP pesadas llegan a la misma conclusion desde la practica: meter paginas completas, listas de issues, logs y snapshots en el modelo muchas veces da menos foco, no mas capacidad.

Mi regla ahora es simple: el agente debe recibir un mapa, no un vertedero.

Para una tarea real quiero objetivo, archivos probables, patron a copiar, comandos de prueba y restricciones duras. No quiero precargar todos los documentos, herramientas, issues y conversaciones antiguas "por si ayuda". Asi obtienes un agente que mezcla tres tareas y recuerda a medias una regla de ayer.

El contexto no es memoria. El contexto es presion sobre la atencion.

La solucion no es un prompt magico. Es un protocolo de contexto: una mision por sesion, contratos cortos, lectura de archivos bajo demanda, salidas de herramientas resumidas o buscables, reglas duraderas en el repo y puntos de reinicio cuando la sesion empieza a desviarse.

Fallo 2: el acceso a herramientas convierte sugerencias en incidentes

El salto de asistente a agente ocurre cuando el modelo puede actuar.

Una respuesta de chat puede ser incorrecta y seguir siendo inofensiva. Un comando terminal con credenciales puede ser incorrecto y caro. Por eso los incidentes con agentes de codigo generan tanto debate. Lo interesante no es si el modelo tenia mala intencion. No la tenia. Lo interesante es que el sistema acepto la accion.

Las discusiones sobre Replit, Cursor, Claude Code y bases de datos borradas exponen el mismo hecho incomodo: si un agente puede llegar a produccion con credenciales amplias, produccion esta dentro de su radio de explosion. No importa que la instruccion diga "staging". No importa que el modelo se disculpe despues. La pregunta real es operativa:

Podia autenticarse el agente?

Podia ejecutar la accion destructiva?

Podia saltarse un punto de aprobacion humana?

Podia borrar aquello de lo que dependia la recuperacion?

Si la respuesta es si, el arnes fallo antes de que el modelo generara la primera palabra.

Ese es el punto de mi guia sobre guardrails para agentes de IA de codigo: usar agentes con seguridad no es una vibe. Es separacion de entornos, credenciales con alcance, aprobaciones, CI, logs de auditoria y disciplina de rollback.

El mayor error es darle al agente tu autoridad normal de desarrollador. Los humanos tienen juicio, habitos, miedo y contexto social. Los agentes tienen patrones, tool calls y un objetivo local. Tratarlos como equivalentes es mal diseno de sistemas.

Un agente de codigo normalmente deberia tener acceso al filesystem limitado al repo, ningun secreto de produccion por defecto, observabilidad read-only salvo aprobacion, comandos destructivos bloqueados, credenciales separadas para staging, ningun deploy directo, salida mediante pull request y logs de cada llamada a herramienta.

Si, esto ralentiza algunas tareas. Bien. La friccion no siempre es desperdicio. A veces la friccion es el producto.

El agente mas rapido no es el que puede hacerlo todo. Es el que puede hacer lo correcto sin ampliar el radio de explosion.

Fallo 3: el agente optimiza el exito visible

Los agentes de codigo son muy buenos satisfaciendo la forma visible de una tarea. Eso ayuda hasta que la forma visible esta incompleta.

Pide un test que falle y una solucion. El agente puede adaptar el test a su implementacion. Pide que CI este verde. Puede eliminar la rama de codigo que revelaba el fallo. Pide simplificar un flujo. Puede borrar un edge case porque complica el patch. Esto no es mentir en sentido humano. Es optimizacion dentro de un feedback loop debil.

El arnes necesita verificacion externa porque la confianza del modelo no es evidencia.

El loop minimo util es:

read -> scope -> act -> verify -> record

Read: inspeccionar los archivos reales y el comportamiento actual antes de proponer cambios.

Scope: declarar que cambiara y que no cambiara.

Act: editar solo dentro de la superficie declarada.

Verify: ejecutar checks que no fueron inventados despues de la implementacion.

Record: dejar una nota corta sobre lo que cambio, lo que fallo y lo que hay que vigilar.

Las practicas que OpenAI publico sobre como usa Codex van en esa direccion: empezar con planificacion para cambios grandes, estructurar prompts como issues de GitHub, usar contexto persistente mediante AGENTS.md y mejorar el entorno de desarrollo con el tiempo. Eso es pensamiento de arnes. El prompt es solo una entrada del sistema.

El agente no deberia definir por si solo que significa "terminado".

Terminado significa diff con alcance claro, tests relevantes, checks ejecutados, archivos modificados releidos, artefactos esperados, ningun cambio no relacionado y rollback evidente.

La IA no elimina la disciplina. Hace que su ausencia sea mas visible.

El template de tarea que si quiero

Este es el tipo de brief que prefiero ahora. No es poetico, pero funciona.

Objetivo:
Corregir tokens expirados de password reset que devuelven 500 en vez de 400.

Comportamiento visible:
Cuando el token esta expirado, devolver HTTP 400 con codigo TOKEN_EXPIRED.

Archivos dentro del alcance:
- app/api/password-reset/route.ts
- lib/auth/password-reset.ts
- tests/auth/password-reset.test.ts

Archivos fuera del alcance:
- schema de base de datos
- templates de email
- middleware de sesion

Comandos permitidos:
- npm run test -- password-reset
- npm run typecheck

Enfoque requerido:
- Agregar o actualizar primero un test que falle.
- Reutilizar el patron AppError existente.
- No cambiar la forma publica de la respuesta salvo el caso de token expirado.

Detenerse y preguntar si:
- parece necesaria una migracion;
- el modelo de token es inconsistente;
- algun comando requiere credenciales de produccion.

Definicion de terminado:
- test objetivo pasa;
- typecheck pasa;
- diff sin formateo no relacionado;
- resumen del cambio y riesgo residual.

Es un contrato compacto de arnes: contexto, permisos, workflow, verificacion y condiciones de parada. No le pidas al modelo que sea cuidadoso en abstracto. Haz explicita la superficie de operacion.

Que cambia con MCP

Soy optimista sobre Model Context Protocol, pero no sobre conectar todas las herramientas solo porque se siente poderoso.

MCP debe tratarse como agregar nuevas capacidades al puesto de trabajo de un empleado. Un servidor MCP de GitHub no es solo "mas contexto". Puede exponer issues, PRs, datos del repo y a veces acciones de escritura. Un servidor MCP de base de datos no es una comodidad neutra. Puede exponer datos de clientes. Un servidor MCP de navegador no es solo testing visual. Puede transportar estado de sesion.

La pregunta no es "puede usarlo el agente?". La pregunta es: "cual es la menor superficie de herramienta segura para esta tarea?"

Buena higiene MCP: herramientas bajo demanda, read-only primero, salidas grandes paginadas o resumidas, credenciales aisladas por entorno, sin escritura en produccion por defecto, llamadas registradas y herramientas inutiles fuera de la tarea.

La herramienta debe ayudar al agente a recuperar la parte correcta de la realidad. No debe verter toda la empresa dentro de la ventana de contexto.

La opinion fuerte

Esta es la opinion que defenderia en una sala de ingenieros:

La mayoria de equipos que piden "mejores prompts de IA" en realidad necesitan un mejor sistema de entrega.

Si el agente olvida restricciones, necesitas disciplina de contexto.

Si toca archivos no relacionados, necesitas work orders con alcance.

Si puede borrar produccion, necesitas fronteras de permisos.

Si entrega bugs plausibles, necesitas verificacion externa.

Si repite el mismo error la semana siguiente, necesitas memoria duradera.

El modelo puede mejorar y aun asi necesitaras todo esto. Mejores modelos reducen tasas de error. No eliminan el radio de explosion. Un ingeniero senior tambien puede romper produccion; la diferencia es que los equipos maduros no usan "por favor ten cuidado" como politica de despliegue.

El futuro del desarrollo con IA no es prompt engineering. Es harness engineering.

Explica por que dos personas pueden usar el mismo modelo y obtener resultados totalmente distintos. Una chatea con un modelo. La otra ejecuta un loop de ingenieria controlado.

Checklist practica

Antes de dar una tarea real a un agente de IA de codigo, quiero cubrir esta checklist:

• La tarea es lo bastante pequena para revisar?
• Los archivos dentro del alcance estan nombrados?
• Los archivos fuera del alcance estan nombrados?
• El agente conoce el patron existente a seguir?
• Los comandos destructivos estan bloqueados?
• Los secretos de produccion no estan disponibles?
• Las herramientas MCP se cargan solo cuando hacen falta?
• Hay un test o check que prueba el cambio?
• Hay revision humana antes de merge o deploy?
• El rollback es evidente?
• La proxima sesion sabra que ocurrio?

Ese ultimo punto esta subestimado. Un buen arnes deja rastros: notas de tarea, decisiones, intentos fallidos, comandos ejecutados y razones de decisiones raras.

El articulo que me hubiera gustado leer antes

Si solo estas experimentando, usa lo que sea rapido. Deja que el agente cree una demo desechable. Haz preguntas amplias. Compara modelos. Perfecto.

Pero si el codigo importa, deja de tratar al agente como un autocompletado mas inteligente. Se parece mas a un contratista muy motivado, que trabaja a velocidad de maquina, con juicio irregular y herramientas que quizas olvidaste que estaban conectadas.

Dale un arnes.

Contexto pequeno. Alcance estrecho. Herramientas limitadas. Permisos duros. Verificacion externa. Memoria durable. Caminos de recuperacion. Asi la IA comprime lo repetitivo sin eliminar el juicio que permite enviar software con seguridad.

Para la capa de seguridad en produccion, lee Guardrails para agentes de IA de codigo. Para la capa de herramientas, lee Model Context Protocol explicado. Para la arquitectura de los loops de agente, lee Como funcionan los agentes de IA. Si estas evaluando mi perfil para un equipo de producto o automatizacion, empieza por mi pagina de desarrollador IA automation.