Pedir bien, dar contexto y revisar: el contrato que impide que tu agente improvise

Resumen ejecutivo

1. La ilusión de la velocidad

Pinochet define el vibe coding sin condescendencia y sin entusiasmo: es programar delegando decisiones de diseño y de dependencias al agente sin un contrato verificable. Su seducción es real —resultados en pantalla en minutos, una sensación tangible de avance— y su riesgo también: el código funciona en el camino feliz e ignora permisos, límites de infraestructura y seguridad.

La pregunta que deja caer en clase incomoda a cualquier equipo: ¿qué código está en producción hoy que nadie del equipo escribió ni auditó a fondo?

El objetivo del curso no es eliminar la IA del flujo. Es hacer visible y reversible su poder.

2. El problema: las decisiones invisibles del agente

Un agente que trabaja sin contrato no se queda quieto: toma decisiones que nadie le pidió y que nadie ve. La clase las agrupa en tres familias.

• Dependencias fantasma — librerías añadidas sin revisión de licencias ni de vulnerabilidades conocidas.
• Esquemas alterados — cambios en la estructura de la base de datos que nadie solicitó explícitamente.
• Permisos excesivos — roles globales o privilegios innecesarios asignados solo para «hacer que funcione rápido».

A eso se suman dos fallos más graves porque no se ven en la revisión superficial. El primero es la alucinación de paquetes: el modelo sugiere una librería que no existe, y ese nombre inventado es exactamente la superficie que explota el typosquatting —alguien registra el paquete inventado y espera. Pinochet lo describe con crudeza en la grabación: el modelo puede declararte una función o una librería asegurando que funciona, y a lo mejor nunca existió.

El segundo es el desvío arquitectónico: romper el patrón MVC o el límite de un microservicio para resolver rápido un bug puntual. La IA resuelve el problema inmediato e ignora el contexto sistémico. El resultado se acumula como deuda técnica acelerada, y la deuda técnica acelerada se manifiesta, tarde o temprano, como incidente de seguridad.

3. Cinco fases para recuperar el control

La propuesta central de la clase es que gobernar agentes exige un circuito de control estructurado, no una secuencia de ocurrencias. Cinco fases obligatorias, donde cada una reduce la ambigüedad de la siguiente y deja una evidencia auditable.

3.1 DDD: fronteras para que el agente no se pierda

Domain-Driven Design aporta algo que los agentes necesitan más que los humanos: límites explícitos. Sin ellos, un agente diseñado para el módulo de pagos termina modificando la tabla global de usuarios para resolver un malentendido. La analogía de la clase es buena: el carpintero no rediseña las tuberías de gas.

En la práctica son dos movimientos. Separar dominios —aislar Facturación de Inventario— con reglas de acceso explícitas: el agente de facturación puede leer inventario, nunca escribir. Y construir un lenguaje ubicuo: si el término es «Order», es «Order» en todos los prompts, nunca «Purchase». Esas fronteras no se explican en el chat: se inyectan en el system prompt o en el archivo de reglas del repositorio.

3.2 SDD: la spec como única fuente de verdad

Aquí está el corazón de la clase. La especificación reemplaza dos cosas igualmente frágiles: la memoria del desarrollador y la suposición del agente. Y funciona como un contrato en sentido estricto:

• Si el código no hace lo que dice la spec, el código está mal —no la spec—.
• Para cambiar el comportamiento se actualiza primero la spec y después el código. Nunca al revés.
• Elimina el sesgo del «asumí que querías esto».

La spec vive versionada junto al código, como un artefacto más del repositorio. El ecosistema ya se está moviendo en esa dirección: formatos como Spec Kit u OpenSpec para contratos legibles por máquinas y por modelos, herramientas emergentes que validan especificaciones contra la implementación real, y modos «spec» en los IDE donde el agente exige la especificación antes de escribir una línea.

3.3 TDD y la trampa que casi todos caen

Este es el hallazgo más práctico de la clase y merece leerse dos veces:

La corrección es de reparto de roles, no de herramienta: el desarrollador define los casos de prueba; el agente escribe el código que los pasa. Y el ciclo se supervisa: en RED se escribe la prueba que falla y demuestra que el comportamiento aún no existe; en GREEN se implementa lo mínimo para pasarla, sin sobreingeniería; en REFACTOR se mejora el diseño sin romperla. La barandilla es una sola y es innegociable: el agente no puede modificar la prueba durante GREEN ni durante REFACTOR.

3.4 FDD: cambios pequeños o revisión imposible

«Créame todo el backend» y «cree el endpoint POST /login» no son la misma petición con distinta ambición: son dos regímenes de riesgo distintos. El primero satura el contexto, mezcla dominios, genera demasiado código de una vez, multiplica las regresiones y —sobre todo— hace imposible la revisión humana. Feature-Driven Development divide el problema en piezas que una persona puede leer de verdad. Detectar una alucinación en cincuenta líneas es realista; en quinientas, no.

3.5 Auditoría: lo que el prompt no puede garantizar

La última fase es la que no depende de cómo pediste las cosas. SAST para inyecciones y vulnerabilidades conocidas en el código generado; SCA para verificar que las dependencias sugeridas por la IA sean seguras y existan; y el pipeline como red que atrapa las alucinaciones de paquetes antes del merge. La seguridad, insiste Pinochet, no vive en el prompt: vive en el pipeline.

4. Anatomía de una spec segura

¿Por qué fallan las especificaciones tradicionales con modelos de lenguaje? Por dos razones. La ambigüedad —«como usuario quiero…» deja abiertas demasiadas decisiones técnicas— y, sobre todo, el vacío de seguridad: las historias de usuario asumen que un humano aplicará OWASP por sentido común. El modelo no tiene sentido común. Si la seguridad no está especificada, el modelo toma el camino más fácil, que casi siempre es el inseguro.

Una spec segura tiene cinco componentes: contexto (dominio, actores y límites de confianza), objetivo medible, comportamiento (flujo principal y reglas de negocio), casos límite (nulos, timeouts, concurrencia, payloads gigantes, caídas de infraestructura) y restricciones de seguridad y arquitectura no negociables.

Ese último bloque es el que se olvida y el que evita los incidentes: nunca confiar en el cliente y validar identidad y permisos en el backend; lista blanca para toda entrada, rechazando lo no esperado; nada de secretos en duro y hashing con algoritmos estándar como Argon2; prohibición explícita de registrar datos personales, tokens o contraseñas en texto plano.

Criterios de aceptación que el agente no pueda falsear

Si el criterio es «el login debe ser seguro», el agente responderá que todo está en orden y no habrá forma de contradecirlo. La clase propone una regla de oro que ordena el resto:

La diferencia entre un prompt informal y una spec se ve mejor en paralelo. «Hazme un login con base de datos» deja el hashing, las sesiones y el límite de intentos a la imaginación del modelo, y el resultado habitual es una consulta concatenada. «POST /login con esquema estricto, validación de entradas, Argon2 para el hash y JWT en cookie HTTP-only» obliga al agente a cumplir restricciones comprobables desde el diseño.

5. Ingeniería de contexto: menos es más

La ilusión más extendida es creer que pasarle todo el repositorio al modelo mejorará sus respuestas. La ventana de contexto no es una base de datos infinita: tiene límites de atención y de razonamiento, y cada línea irrelevante degrada la capacidad del modelo para seguir reglas complejas de seguridad. A mayor contexto, mayor probabilidad de que el agente ignore una restricción crítica.

La analogía de Pinochet es difícil de olvidar: no le entregas a un cirujano los planos del hospital para operar; le entregas el historial del paciente. El contexto se diseña como se diseña una API —enviando solo lo estrictamente necesario—.

De ahí una separación de responsabilidades en tres archivos, cada uno con su propio ritmo de cambio:

Y tres antipatrones que arruinan el razonamiento del agente aunque las reglas estén bien escritas. Envenenamiento de contexto: incluir código legado lleno de malas prácticas que el modelo imitará como ejemplo. Instrucciones contradictorias: un AGENT.md que dice «usa fetch» y un prompt que dice «usa axios». Sobrecarga de reglas: un archivo de mil líneas que el modelo terminará ignorando por completo.

El complemento es el aislamiento: agentes o sesiones distintas por tarea, espacios de trabajo limitados a la carpeta del microservicio actual, instrucciones secuenciales en vez de un mega-prompt. Todo apunta a controlar el radio de impacto: si el agente se equivoca, que solo afecte al módulo aislado.

6. Leer código que no escribiste

La última pieza es de lectura, no de escritura. El código de IA engaña porque es sintácticamente impecable: no hay errores de compilación, se ve limpio, genera una falsa sensación de confianza. La postura que recomienda la clase es tratarlo como un prototipo funcional pero potencialmente hostil.

El catálogo de señales de alarma es corto y directo. En inyecciones y secretos: claves o tokens de prueba dejados en el código, concatenación de strings para formar consultas, imports que apuntan a librerías que conviene verificar que existan. En autorización y fugas: el bypass clásico —verificar autenticación y olvidar los permisos sobre el recurso concreto, es decir IDOR—, algoritmos obsoletos como MD5 o SHA1 para contraseñas, y bloques catch que devuelven el stack trace completo al cliente.

Para auditar con el propio modelo hay técnicas que funcionan mejor que «revisa la seguridad»: prompting adversarial —pedirle que actúe como atacante contra el código que acaba de escribir—, juego de roles explícito, especificidad quirúrgica sobre qué revisar, y usar un agente distinto con contexto limpio para auditar al agente creador. Un buen prompt de auditoría pide evidencia, no opinión: severidad, vector de ataque y parche para cada hallazgo.

Con un límite que la clase no disimula: el modelo audita solo lo que tiene delante, y la falta de contexto implica omisiones. Sirve para encontrar el ochenta por ciento de los errores obvios; el veinte por ciento crítico sigue necesitando análisis determinista y revisión humana experta.

7. Conclusiones

Tres ideas para llevarse. Primera: la spec es el contrato, y el contrato manda. Sin un artefacto verificable, cualquier discusión sobre si el agente «lo hizo bien» es una discusión de opiniones. Segunda: quien escribe la prueba define la verdad —si el agente escribe el código y su test en el mismo movimiento, no verificaste nada—. Tercera: el contexto es un recurso escaso que se diseña; más información no es más precisión, y un contexto contaminado destruye la capacidad de razonamiento aunque las reglas de seguridad estén perfectamente redactadas.

Referencias

• Pinochet Maturana, R. (2026). Spec-Driven Development Seguro: pedir bien, dar contexto y revisar [presentación]. Curso FVCS-101, Comunidad IA LATAM × 8.8 Academy.
• OWASP Foundation. OWASP Top 10 — referencia de las restricciones de seguridad citadas en la spec.
• Evans, E. (2003). Domain-Driven Design: Tackling Complexity in the Heart of Software — origen de los Bounded Contexts y el lenguaje ubicuo.
• Beck, K. (2002). Test-Driven Development: By Example — el ciclo rojo-verde-refactor citado en la Fase 3.
• Herramientas y formatos mencionados en clase: Spec Kit, OpenSpec, Kiro, BMAD y los modos «spec» de OpenCode y KiloCode.

Autoría

Sr. Rudy Pinochet Maturana — Presidente de ISACA Santiago · Director de Alianzas de Comunidad IA LATAM. Profesional y docente con más de 15 años liderando arquitectura de plataformas, ciberseguridad, auditoría y gestión de riesgos en banca, seguros, retail, telecomunicaciones y energía. Presidente de ISACA Santiago, consultor senior y académico en programas de postgrado en Chile y Latinoamérica. CISM, CDPSE, CEH, CHFI.

Artículo elaborado por Comunidad IA LATAM a partir de la presentación y la grabación de la clase. Las cinco clases del curso están abiertas en Academy IA LATAM.