Programar con agentes de IA sin perder el control del código

Un agente de IA no arruina tu proyecto en un solo commit. El daño llega de a poco: un PR que aprobaste sin leerlo bien, una dependencia que "resolvió" a su manera, una regla del proyecto que no conocía. Cuando te das cuenta, el código funciona, pero ya no sabes explicar por qué.

Uso agentes todos los días, también en el código de este sitio. En este post te muestro las reglas que me dejan ir rápido sin soltar el volante.

El riesgo no es código malo, es código que no leíste

El código malo aparece en el review. El problema es el código plausible: compila, pasa el lint y se parece a lo que tú escribirías. Ese es el que se cuela.

Por eso dejé de pensar en "cuánto puede hacer el agente solo" y empecé a hacerme otra pregunta: ¿cuánto puedo verificar después? Una tarea que no puedo revisar en diez minutos es demasiado grande para delegarla de una vez.

1. Contexto escrito, no contexto en tu cabeza

El agente empieza cada sesión sin memoria de tu proyecto. Si una regla existe solo en tu cabeza, la va a romper, y con toda la confianza del mundo.

En este sitio, el contexto vive en un solo archivo, el AGENTS.md, que lee cualquier herramienta (Claude Code, Copilot o la que venga después). Tiene el stack, los comandos, las convenciones y, sobre todo, las trampas que ya me costaron horas:

## Code conventions

- Pages, layouts and routes read posts only through `lib/content` — never call the content API directly.
- Tailwind only — no CSS-in-JS, no inline `style` props.
- Never hardcode user-visible strings; use `useTranslation`.

Known pitfalls (each one cost real debugging time):

- **Never `await app.listen()` at module top level** in the API. Vercel intercepts `listen()`,
  the promise never resolves, and every request hangs until it times out with no logs.

La regla que sigo: cada vez que corrijo al agente dos veces en lo mismo, la corrección se convierte en una línea de ese archivo. El archivo crece con los errores reales del proyecto, no con buenas prácticas genéricas copiadas de internet.

2. Límites técnicos, no promesas

"No toques producción" escrito en el prompt es un pedido. Un permiso denegado en la configuración es un límite. Prefiero el límite.

Este es un fragmento real del .claude/settings.json de este repositorio:

{
  "permissions": {
    "allow": ["Bash(yarn lint:check)", "Bash(yarn build)", "Bash(yarn api:test)", "Bash(git diff *)"],
    "deny": [
      "Read(./.env.local)",
      "Read(./.env.development.local)",
      "Read(./.env.production.local)"
    ]
  }
}

Lo que es lectura y verificación corre sin preguntarme. El agente ni siquiera puede abrir los archivos de secretos. Y hay una capa personal, fuera de git, que bloquea escrituras en la base de datos de producción, cambios de variables de entorno y deploys a producción. El agente prepara el comando; quien aprieta el botón soy yo.

No es desconfianza. Es el mismo principio que aplicas con un compañero nuevo en el equipo: acceso amplio de lectura, escritura en producción solo con revisión.

3. Tareas pequeñas, con una forma objetiva de verificarlas

Le pido al agente cosas que terminan en algo verificable: un test que pasa, un build que cierra, una página que responde 200. "Mejora la arquitectura del proyecto" no tiene fin ni criterio. "Corrige las alertas de Dependabot, corriendo lint, typecheck, tests y build" sí lo tiene.

Un ejemplo de hoy mismo. Le pedí que corrigiera las alertas de seguridad del sitio. El agente forzó versiones nuevas de varias dependencias, y una de ellas (OpenTelemetry 2.x) rompió el build:

TypeError: Cannot read properties of undefined (reading 'AlwaysOn')
    at async .../next-contentlayer2/dist/index-cjs.cjs:72:49
> Build failed because of webpack errors

Como el build era parte de la tarea, el error apareció antes del PR, no en producción. El agente sacó esa actualización, descartó la alerta dejando el motivo registrado y siguió con las demás.

# Not fixed (dismissed as tolerable risk)
- @opentelemetry/core and @opentelemetry/propagator-jaeger: the fix is 2.x only, and forcing it breaks the contentlayer build (Cannot read properties of undefined (reading 'AlwaysOn')). Build-time tracing inside contentlayer2, which has no newer release.
- braces, http-cache-semantics, sprintf-js: no patched version published; dev/build-time chains (chokidar, node-gyp, argparse).

# Verification
- yarn lint:check, site and API typechecks, yarn api:test (54 passed)
- yarn build against the production content API: contentlayer generated 9 documents, build OK
- next start: /pt, /en, /pt/curriculum, /pt/about and an English post return 200

4. Revisa el diff como si fuera de un compañero

Sigo con el mismo caso: después del merge, GitHub reabrió doce alertas que estaban marcadas como corregidas, pero nunca lo estuvieron. El agente había confiado en el estado de GitHub, y yo también. Solo lo detectamos porque pedí revisar las alertas después del deploy, en lugar de dar el trabajo por terminado en el merge.

La lección se volvió regla: el agente verifica el resultado en la fuente, no en el resumen. La versión en el lockfile, no el estado de la alerta. Los logs de producción, no "el deploy pasó".

En la revisión, leo tres cosas antes que nada:

Lo que cambió fuera del alcance. Un archivo que no esperaba en el diff es la primera señal de problema.
Lo que se eliminó. Un agente borra un test "que estaba fallando" con una facilidad que asusta.
Lo que se decidió por mí. Una versión mayor de una dependencia, un cambio de API pública, una migración de base de datos: todo eso tiene que estar en la descripción del PR, no escondido en el diff.

Errores comunes

// ❌ Mal: "refactoriza el módulo de pagos y ajusta lo que creas necesario"
// ✅ Bien: "extrae el cálculo de intereses a una función pura, con tests para los 3 casos actuales"

// ❌ Mal: aprobar porque el CI pasó
// ✅ Bien: aprobar porque leíste el diff y sabes explicar cada archivo

// ❌ Mal: corregir al agente en el chat y olvidarlo
// ✅ Bien: dos correcciones = una línea nueva en el AGENTS.md

// ❌ Mal: dejar que la IA genere el texto que llega al usuario final sin revisión
// ✅ Bien: la IA hace la parte creativa, el código dibuja lo que tiene que ser exacto

Esa última la aprendí con las portadas de este blog. Dejaba que una IA dibujara la portada entera, título incluido, y los títulos salían con errores de tipeo. Hoy la ilustración viene de la IA y el título lo dibuja un canvas a partir del texto del post. Cada uno hace lo que hace bien.

Cuándo delegar y cuándo no

Delega	Hazlo tú (o síguelo de cerca)
Actualización de dependencias con tests y build	Decisiones de arquitectura que mantendrás por años
Boilerplate que sigue un patrón ya existente	Código de autenticación y autorización
Investigar logs y plantear hipótesis	Cualquier escritura en producción
Primer borrador de tests para código legado	Reglas de negocio que solo tú conoces
Traducción y revisión de textos	Lo que llega al usuario sin pasar por revisión

La columna de la derecha no es "IA prohibida". Es donde el costo de un error plausible es demasiado alto para revisarlo solo al final.

Por dónde empezar

Si hoy usas agentes sin ninguna de estas reglas, empieza por algo pequeño:

Crea un AGENTS.md con cinco líneas: el stack, los comandos de verificación y las tres reglas que más repites en el code review.
Configura los permisos de tu herramienta: libera lint, tests y build; bloquea la lectura de .env y cualquier comando de producción.
En la próxima tarea, define cómo vas a verificarla antes de pedirla. Si no sabes decir cómo vas a comprobar el resultado, la tarea todavía no está lista para delegar.

El agente acelera muchísimo. Pero la responsabilidad por el código que llega a producción sigue llevando tu nombre en el commit. Y tú, ¿ya pillaste al agente "resolviendo" algo a su manera? Cuéntame qué regla entró en tu AGENTS.md por eso.