Cómo evitar problemas al pedir código a la IA sin especificaciones

Poca gente dice esto en las charlas con café gratis: pedir código antes de dar contexto es como contratar a un pintor y no decirle qué pared. Va a pintar rápido. Va a quedar espectacular al principio. Y al primer olor a humo descubrirás que pintó sobre el sistema eléctrico.

Resumen rápido (lectores con prisa)

La IA genera código probables según datos y prompts. Sin una spec que defina objetivos, stack, contratos y criterios de aceptación, las soluciones serán rápidas pero frágiles. Escribe SPEC.md, publica contratos, exige plan y tests; audita con red teaming. Conserva disciplina para convertir velocidad en sostenibilidad.

Poca gente habla de esto: la IA no entiende tu negocio

Los modelos de lenguaje son máquinas de probabilidades. No entienden SLAs, ni GDPR, ni las peleas internas por usar Next.js o Svelte. Responden con lo más probable según su entrenamiento y tu prompt. Si no les das reglas, toman decisiones por ti. Decisiones elegantes, pero improvisadas. Y la improvisación no escala.

Lo que pasa cuando pides código demasiado pronto

No es teoría. Es patrón repetido en equipos que adoptan IA rápido y disciplina lenta:

Demo brillante en 48 horas. Integración rota, tokens expuestos, tests que fallan en producción. Dos semanas de refactor para rescatar el proyecto.

Síntomas concretos

• Componentes gigantes que hacen todo: UI, llamadas HTTP, validaciones y cambios en la base de datos. Un archivo de 500 líneas que asusta.
• Mezcla de librerías por impulso: Fetch aquí, Axios allá, una dependencia vieja que “funcionaba” en un tutorial.
• Flujos automatizados (n8n, Zapier) que fallan ante el primer timeout porque nadie pensó en idempotencia.
• Tests que existen pero no validan casos reales. O peor: pruebas que pasan porque la spec nunca fue clara.

Alucinación arquitectónica: la versión elegante del desastre

No es solo que la IA invente funciones. Inventará abstracciones. Te propondrá un patrón porque en sus datos aparece muchas veces. Puede recomendarte Event Sourcing para una app de encuestas. Te entregará un PR perfecto. Y tú, encantado, lo mergeas.

Hasta que llega la primera incidencia. Hasta que un miembro nuevo del equipo abre ese PR y no entiende nada. La IA actúa con convicción. Por eso hace falta liderazgo humano que coloque límites.

La spec: no es burocracia. Es supervivencia

Quien sigue llamando a la spec “ese PDF que nadie lee” está mirando el problema con los ojos cerrados. En la era de la IA la spec es la única forma de que la creatividad de la herramienta aterrice donde debe.

Piensa en la spec como el System Prompt del repositorio. No es un texto largo que nadie abre; es la brújula del proyecto. Contiene: objetivos, stack, reglas innegociables, modelos de datos, respuestas ante fallos, y criterios de aceptación.

Si la IA fuera un barco y tu equipo fuera la tripulación, la spec es la brújula. Sin ella, el barco navega rápido y choca.

Cómo evitar pedir código demasiado pronto (pasos concretos)

No es magia. Es disciplina con sentido. Haz esto antes del primer commit generado por IA.

1) Escribe el objetivo en una frase

¿Qué problema resuelve este módulo? ¿Qué NO debe hacer? Si no puedes decirlo en una frase, no lo pidas. La IA no lo adivina.

2) Define el stack y las reglas innegociables

Next.js 14 OK. No usar SSR en X páginas. No introducir nueva dependencia sin CVE-check. ¿Postgres o Mongo? ¿Monolito o microservicios? Quítale opciones a la IA para que deje de improvisar.

3) Publica contratos antes que código

Interfaces TypeScript, esquemas Prisma, OpenAPI. Si la IA tiene contratos, genera lógica que encaje. Si no los tiene, generará sutilezas que rompen todo.

4) Exige plan antes de ejecución

Pide un plan en pasos. Repite: plan. No “hazlo tú ahora”. Pide la lista de entregables, aprobala y luego ejecuta cada paso con prompts acotados.

5) Red Teaming desde el minuto cero

Pídele a la IA que sea adversaria: “Rompe este diseño.” “¿Qué falla con 10k req/s?” “¿Qué pasa si el proveedor OAuth cae 30s?” Esto saca a la luz cuellos de botella y casos límite.

6) Testes y ejemplos junto al contrato

Cada endpoint debe venir con payloads válidos e inválidos y tests de aceptación. Si la IA genera código sin tests que validen la spec, recházalo.

7) Guarda la spec en el repo (no en Google Docs)

SPEC.md, .cursorrules, spec.json. Ponlo en la raíz. Que sea lo primero que lea el agente cuando genere código.

Plantilla mínima de SPEC.md (pégala ya)

No la copies sin adaptar, pero ten algo así en la raíz del repo:

• Título en una frase: Objetivo del módulo.
• Stack aprobado: Next.js 14, Node 20, Postgres 15.
• Reglas innegociables:
• No exponer secretos en frontend.
• Mutaciones por Server Actions.
• Máximo 2 dependencias nuevas sin revisión de seguridad.
• Contratos principales:
• /api/users POST -> CreateUserRequest, CreateUserResponse (interfaces TypeScript)
• DB: users (id uuid, email text unique, password_hash text)
• Criterios de aceptación:
• Test de integración que crea usuario y valida hash.
• Tiempo máximo respuesta: 500ms en endpoint crítico.
• Política de secretos: usar Vault, nunca env vars en texto plano.
• Responsables: Tech Lead: @ana, Owner: @carlos.

Prompts que funcionan (ejemplos directos)

Un buen prompt = contexto + restricciones + output esperado.

Malo: “Hazme un CRUD de users.”

Bueno: “Te doy la spec (inserta SPEC.md). Genera: 1) Interfaces TS 2) OpenAPI para /api/users 3) Tests de integración con ejemplos válidos/ inválidos. No uses librerías externas para hashing. Tiempo de respuesta <500ms.”

Divide el trabajo en sprints cortos y verificables

• Sprint A: Modelo de datos + contratos + tests.
• Sprint B: Endpoints críticos + seguridad.
• Sprint C: Observabilidad y despliegue.

Aprobar cada sprint antes de pasar al siguiente.

El nuevo rol del Senior: faro y guardián, no solo coder

Antes bastaba con saber la sintaxis. Hoy el valor está en definir límites, auditar reglas y decidir qué complejidad merece implementarse. El senior no codifica menos; decide mejor. Su trabajo es preguntarse: ¿esta solución respeta la spec? Si no, veto.

Historias que sirven como espejo

Junior + Copilot = demo en 48h. Producción = caos. Reescritura 3 semanas.

Mismo caso con spec: plan en 2 días + Claude para contratos + Copilot para implementación respetando interfaces = demo en 48h. Integración estable. Diferencia: disciplina.

Metáfora corta y pegadiza

La spec es el embudo; la IA es la manguera. Sin embudo, el agua corre por todos lados. Con embudo, llega donde debe.

Cuándo no necesitas spec rígida

Sí, hay espacio para improvisar. Para generar mocks, para prototipos exploratorios o pequeñas refactors locales. Pero regla práctica: si tocas contratos (APIs, DB, auth, infra), necesitas spec. Punto.

Checklist rápido antes de pedir código a la IA

• ¿Existe SPEC.md en la raíz?
• ¿Hay interfaces/contractos definidos?
• ¿Hay reglas de seguridad básicas?
• ¿El prompt pide tests y ejemplos?
• ¿Se solicitó plan paso a paso y fue aprobado?

Si respondes no a cualquiera, NO pidas código aún.

Urgencia real: deuda técnica multiplica costes

Cada PR aceptado sin spec es una apuesta. Adivina quién paga si pierde la apuesta: tu equipo. La deuda técnica no se desintegra con buenas intenciones. Se compone. Actuar ahora cuesta horas. Rehacer después cuesta semanas, o clientes.

CTA simple y directo

Haz esto en los próximos 60 minutos: crea SPEC.md en la raíz con las seis secciones mínimas que te di. Respóndeme con “Quiero la plantilla” y te la mando lista para pegar en tu repo.

Cierre que no cierra (a propósito)

Si sigues pensando que la IA es una varita mágica, es tu opción. Tienes otra: gobernarla. La spec es la forma más barata de gobernarla. No es cómoda. Es efectiva. Y esto no acaba aquí: si quieres, te doy la plantilla, un prompt maestro listo para Claude y un .cursorrules de ejemplo. Dime cuál quieres y te lo envío ahora. Tus commits —y tu equipo dentro de seis meses— lo agradecerán.

Dominicode Labs

Si trabajas con automatización, agentes o workflows y quieres ejemplos prácticos de especificaciones y .cursorrules, revisa los recursos disponibles en Dominicode Labs. Es una continuación lógica para equipos que buscan convertir experimentos rápidos en procesos repetibles y seguros.

FAQ

¿Qué es una SPEC.md y por qué es necesaria?

Una SPEC.md es un archivo en la raíz del repositorio que define objetivo, stack, reglas innegociables, contratos y criterios de aceptación. Es necesaria para alinear generación de código automática con las restricciones del negocio y evitar decisiones improvisadas que generen deuda técnica.

¿Cuándo puedo pedir código sin spec?

Para prototipos exploratorios, mocks o pequeños refactors locales. Si el cambio afecta APIs, DB, auth o infra, siempre usar spec. Esa es la regla práctica del artículo.

¿Cómo garantizo que la IA respete los contratos?

Publica interfaces TypeScript, OpenAPI o esquemas en el repo antes de pedir código. Exige tests que validen esos contratos y revisa que las implementaciones pasen los tests de integración definidos en la spec.

¿Qué contiene un criterio de aceptación sólido?

Entradas y salidas esperadas, límites de rendimiento (ej. tiempo máximo 500ms), condiciones de error y tests de integración que validen el comportamiento en casos válidos e inválidos.

¿Quién debe ser responsable de la spec?

Responsables claros: Tech Lead y Product Owner. En el ejemplo: Tech Lead: @ana, Owner: @carlos. Debe estar versionada en el repo y ser lo primero que lea cualquier agente automatizado.

¿Cómo auditar seguridad en dependencias sugeridas por IA?

No introducir nuevas dependencias sin revisión de seguridad: CVE-check, análisis de licencia y una prueba mínima en entorno aislado. La spec puede imponer un máximo de dependencias nuevas sin revisión.