El primer error que cometí 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 redacción. Si olvidaba una restricción, agregaba otro párrafo. Si escribia código plausible pero fallaba en el flujo real, pedia un plan más detallado. Eso funciona durante una tarde. Después entiendes que el problema no es la frase. El problema es la superficie de operación que le diste al agente.
La conversación 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 petición de política. Un arnes es la aplicación de esa política.
No uso "arnes" como una palabra elegante para plantilla de prompt. Hablo del sistema de control alrededor del modelo: contexto, herramientas, permisos, workflow, verificación, recuperación 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 código en software real, esta diferencia vale más que la mayoria de benchmarks.
La conversación real entre desarrolladores
El marketing publico sigue sonando mágico: describe la feature, espera el patch, mergea más rápido. La conversación privada entre desarrolladores es menos romántica.
La encuesta Developer Survey 2025 de Stack Overflow captura bien la tension. Las herramientas de IA ya son habituales o están en los planes de muchos equipos, pero la confianza no crece al mismo ritmo. La mayor frustración es el resultado "casi correcto". Esa frase duele porque es exacta. El código casi correcto es caro porque parece progreso hasta que tienes que integrarlo.
Por eso el debug de código generado por IA aparece también entre las grandes frustraciones. Un código malo que falla de inmediato molesta. Un código casi correcto es peor. Pasa la primera revisión. Pasa el happy path. Usa nombres que parecen coherentes con el repo. Luego falla en el borde: autenticación, permisos, migraciones, reintentos, zonas horarias, caché, teardown, rollback.
El dolor no es "la IA no sabe escribir código". Si sabe. El dolor es que generar código se volvió barato y verificarlo sigue siendo caro.
Veo el mismo patrón 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 conversación, o agentes que hacen algo "lógico" que ningún ingeniero de producción habría permitido. Parecen quejas distintas. Tienen la misma raíz: el agente opera dentro de un arnes débil.
Que significa arnes en este contexto
Un arnes para agentes de código es la disciplina de runtime alrededor del modelo.
Tiene siete piezas:
- Contexto: mapa del repo, brief de tarea, reglas del proyecto, decisiones anteriores y solo los archivos relevantes.
- Herramientas: shell, sistema de archivos, navegador, GitHub, issue tracker, base de datos, observabilidad, servidores MCP.
- Permisos: que puede leer, escribir, ejecutar, borrar, pushear, desplegar o consultar el agente.
- Workflow: planificación, edición con alcance, review, CI, aprobación humana, ruta de release.
- Verificación: tests, type checks, lint, browser checks, revisión del diff, dry-runs de migración, escaneos de seguridad.
- Recuperación: rollback, backups, checkpoints, logs de auditoría, soft deletes, estrategia de revert.
- 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 más largas, pero el agente conserva el mismo contexto gigante, el mismo token amplio, el mismo shell sin límites 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 mágicamente más inteligente. Hace que el fallo sea más pequeño.
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 sesión sigue acumulando material. En algún punto, la señal útil sigue ahi, pero queda enterrada bajo historia.
La documentación de Claude Code sobre la ventana de contexto es útil porque hace visible lo invisible: instrucciones, archivos leídos, salidas de herramientas, historial de conversación, skills, reglas y compactación compiten por la misma memoria de trabajo. Eso significa que "más contexto" no siempre es mejor. El contexto no es una biblioteca. Es presupuesto de atención.
MCP hace esto más evidente. MCP es potente porque conecta agentes con herramientas y datos reales. Pero los schemas de herramientas y las respuestas pueden consumir espacio rápido. La documentación de Claude sobre MCP y tool search existe por una razon: cargar herramientas solo cuando hacen falta mantiene el working set más limpio. Las discusiones en Hacker News sobre salidas MCP pesadas llegan a la misma conclusión desde la practica: meter páginas completas, listas de issues, logs y snapshots en el modelo muchas veces da menos foco, no más capacidad.
Mi regla ahora es simple: el agente debe recibir un mapa, no un vertedero.
Para una tarea real quiero objetivo, archivos probables, patrón a copiar, comandos de prueba y restricciones duras. No quiero precargar todos los documentos, herramientas, issues y conversaciones antiguas "por si ayuda". Así obtienes un agente que mezcla tres tareas y recuerda a medias una regla de ayer.
El contexto no es memoria. El contexto es presión sobre la atención.
La solución no es un prompt mágico. Es un protocolo de contexto: una misión por sesión, contratos cortos, lectura de archivos bajo demanda, salidas de herramientas resumidas o buscables, reglas duraderas en el repo y puntos de reinicio cuando la sesión 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 código generan tanto debate. Lo interesante no es si el modelo tenía mala intención. No la tenía. 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 incómodo: si un agente puede llegar a producción con credenciales amplias, producción esta dentro de su radio de explosión. No importa que la instrucción diga "staging". No importa que el modelo se disculpe después. La pregunta real es operativa:
Podía autenticarse el agente?
Podía ejecutar la accion destructiva?
Podía saltarse un punto de aprobación humana?
Podía borrar aquello de lo que dependia la recuperación?
Si la respuesta es si, el arnes fallo antes de que el modelo generará 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 separación de entornos, credenciales con alcance, aprobaciones, CI, logs de auditoría y disciplina de rollback.
El mayor error es darle al agente tu autoridad normal de desarrollador. Los humanos tienen juicio, hábitos, miedo y contexto social. Los agentes tienen patrones, tool calls y un objetivo local. Tratarlos como equivalentes es mal diseño de sistemas.
Un agente de código normalmente debería tener acceso al filesystem limitado al repo, ningún secreto de producción por defecto, observabilidad read-only salvo aprobación, comandos destructivos bloqueados, credenciales separadas para staging, ningún deploy directo, salida mediante pull request y logs de cada llamada a herramienta.
Si, esto ralentiza algunas tareas. Bien. La fricción no siempre es desperdicio. A veces la fricción es el producto.
El agente más rápido no es el que puede hacerlo todo. Es el que puede hacer lo correcto sin ampliar el radio de explosión.
Fallo 3: el agente optimiza el éxito visible
Los agentes de código 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 solución. El agente puede adaptar el test a su implementación. Pide que CI este verde. Puede eliminar la rama de código 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 optimización dentro de un feedback loop débil.
El arnes necesita verificación externa porque la confianza del modelo no es evidencia.
El loop minimo útil es:
read -> scope -> act -> verify -> record
Read: inspeccionar los archivos reales y el comportamiento actual antes de proponer cambios.
Scope: declarar que cambiará y que no cambiará.
Act: editar solo dentro de la superficie declarada.
Verify: ejecutar checks que no fueron inventados después de la implementación.
Record: dejar una nota corta sobre lo que cambio, lo que fallo y lo que hay que vigilar.
Las prácticas que OpenAI publico sobre como usa Codex van en esa dirección: empezar con planificación 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 debería definir por si solo que significa "terminado".
Terminado significa diff con alcance claro, tests relevantes, checks ejecutados, archivos modificados releidos, artefactos esperados, ningún cambio no relacionado y rollback evidente.
La IA no elimina la disciplina. Hace que su ausencia sea más visible.
El template de tarea que si quiero
Este es el tipo de brief que prefiero ahora. No es poético, 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, verificación y condiciones de parada. No le pidas al modelo que sea cuidadoso en abstracto. Haz explícita la superficie de operación.
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 "más 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 sesión.
La pregunta no es "puede usarlo el agente?". La pregunta es: "cuál 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 producción por defecto, llamadas registradas y herramientas inútiles 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 opinión fuerte
Esta es la opinión 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 producción, necesitas fronteras de permisos.
Si entrega bugs plausibles, necesitas verificación externa.
Si repite el mismo error la semana siguiente, necesitas memoria duradera.
El modelo puede mejorar y aún así necesitaras todo esto. Mejores modelos reducen tasas de error. No eliminan el radio de explosión. Un ingeniero senior también puede romper producción; la diferencia es que los equipos maduros no usan "por favor ten cuidado" como política 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 ingeniería controlado.
Checklist practica
Antes de dar una tarea real a un agente de IA de código, quiero cubrir esta checklist:
- La tarea es lo bastante pequeña para revisar?
- Los archivos dentro del alcance están nombrados?
- Los archivos fuera del alcance están nombrados?
- El agente conoce el patrón existente a seguir?
- Los comandos destructivos están bloqueados?
- Los secretos de producción no están disponibles?
- Las herramientas MCP se cargan solo cuando hacen falta?
- Hay un test o check que prueba el cambio?
- Hay revisión humana antes de merge o deploy?
- El rollback es evidente?
- La próxima sesión sabra que ocurrió?
Ese último punto esta subestimado. Un buen arnes deja rastros: notas de tarea, decisiones, intentos fallidos, comandos ejecutados y razones de decisiones raras.
El artículo que me hubiera gustado leer antes
Si solo estas experimentando, usa lo que sea rápido. Deja que el agente cree una demo desechable. Haz preguntas amplias. Compara modelos. Perfecto.
Pero si el código importa, deja de tratar al agente como un autocompletado más inteligente. Se parece más a un contratista muy motivado, que trabaja a velocidad de máquina, con juicio irregular y herramientas que quizas olvidaste que estaban conectadas.
Dale un arnes.
Contexto pequeño. Alcance estrecho. Herramientas limitadas. Permisos duros. Verificación externa. Memoria durable. Caminos de recuperación. Así la IA comprime lo repetitivo sin eliminar el juicio que permite enviar software con seguridad.
Para la capa de seguridad en producción, lee Guardrails para agentes de IA de código. Para la capa de herramientas, lee Model Context Protocol explicado. Para la arquitectura de los bucles de agente, lee Cómo funcionan los agentes de IA. Si estás evaluando mi perfil para un equipo o un proyecto, empieza por la sección de agentes de IA y automatización de mi página de contratación o por mis servicios freelance.
