¿Por qué la IA no construye lo que le pido?

Casi siempre es por falta de contexto, no por falta de capacidad. Cuando le mandas un prompt corto, la IA tiene que adivinar tu stack, tus convenciones, qué consideras 'terminado' y qué casos borde importan. Con una especificación clara le quitas todo lo que tendría que adivinar, y por eso construye lo que de verdad pediste.

¿Qué es una especificación (spec) en el contexto de desarrollo con IA?

Es un documento corto en markdown que define qué quieres construir, qué NO entra, cómo se comporta y cómo sabrás que está terminado. La spec se vuelve la fuente de verdad del proyecto: la IA construye contra ella en vez de contra el prompt del momento.

¿Dónde guardo las especificaciones en mi proyecto?

En una carpeta /specs en la raíz del repo, versionada con Git junto al código. Una carpeta o archivo por feature, numerados (0001-login, 0002-checkout). Así cualquiera que clone el proyecto —humano o IA— las encuentra de inmediato. El versionado lo da Git, nunca archivos tipo spec-v2.md.

¿Qué stack se usa en este ejemplo?

React en el frontend, NestJS con PostgreSQL y Prisma en el backend, Docker para correr la base de datos local y Git para versionar. Es un stack moderno y muy común para apps full-stack, y la IA lo conoce bien, lo que facilita que respete las convenciones.

¿Cómo hago que Claude Code lea mis specs de forma confiable?

Agrega un archivo AGENTS.md (o CLAUDE.md) en la raíz que le diga explícitamente que las specs viven en /specs y en qué orden leerlas. Herramientas como Claude Code y Cursor leen ese archivo automáticamente, así que se vuelve el contrato entre tú y la IA.

Los wireframes son la otra mitad: las especificaciones definen el QUÉ y el cómo, los wireframes definen cómo se ve y se siente. En este post me enfoco solo en las especificaciones; los wireframes los cubro en un video y post aparte.

Especificaciones claras: el secreto para que la IA construya lo que de verdad pediste

Grabé un video corto sobre algo que veo fallar todo el tiempo: la gente le pide cosas a la IA, no recibe lo que esperaba, y concluye que "la IA no sirve para programar". El problema casi nunca es la IA. El problema es que le estamos dando instrucciones ambiguas.

Para que un agente como Claude Code construya correctamente lo que le pides, necesita dos cosas: especificaciones claras y wireframes. En el video no me dio tiempo de cubrir los dos, así que este post va solo de especificaciones (los wireframes los dejo para el siguiente).

Y como prometí, al final te dejo un prompt listo para iniciar un proyecto con el stack que uso, configurado para que tú y la IA empiecen a definir las specs desde el día uno.

Si quieres la versión metodológica más a fondo, ya escribí sobre esto en Spec-Driven Development con Claude Code. Este post es el complemento práctico, enfocado en el stack y en cómo guardar los archivos.

Por qué la IA "no te hace caso"

Cuando le mandas algo como "hazme el login", la IA tiene que adivinar:

¿Con qué tecnología? ¿JWT, sesiones, OAuth?
¿Cómo se ve la base de datos?
¿Qué pasa cuando el usuario se equivoca 5 veces?
¿Qué consideras "terminado"?

Cada cosa que tiene que adivinar es una oportunidad para equivocarse. Una especificación es, literalmente, quitarle todo lo que tendría que adivinar. No es burocracia: son 30 líneas que te ahorran 3 horas de prompts de corrección.

El stack del que hablo en el video

Para que los ejemplos sean concretos, este es el stack que uso y el que asumo en el prompt:

React — frontend
NestJS — backend (estructurado, ideal para que la IA respete convenciones)
PostgreSQL + Prisma — base de datos y ORM con tipado
Docker — para correr la base de datos local sin instalar nada en tu máquina
Git — para versionar el código y las specs

La razón de elegir un stack "con opiniones" como NestJS + Prisma es justo esa: mientras más convenciones claras tenga el stack, menos tiene que inventar la IA.

Dónde guardar las especificaciones

Esta es la parte que más dudas genera, así que le pedí la recomendación a mi sistema de organización. La regla es simple: las specs viven en el repo, no en tu app de notas. Son artefactos de ingeniería y deben versionarse junto al código.

La estructura recomendada es una carpeta /specs en la raíz:

code

mi-proyecto/
├── AGENTS.md                  ← contrato para la IA (apunta a /specs)
├── CLAUDE.md                  ← copia o symlink de AGENTS.md
├── specs/
│   ├── README.md              ← índice de todas las specs
│   ├── _template.md           ← plantilla base para copiar
│   ├── 0001-auth-login/
│   │   ├── spec.md            ← el QUÉ y el PORQUÉ
│   │   ├── plan.md            ← el CÓMO (diseño técnico)
│   │   └── tasks.md           ← checklist de implementación
│   └── 0002-checkout/
│       └── spec.md            ← features chicas: un solo archivo basta
├── prisma/
│   └── schema.prisma
└── src/

Reglas que vale la pena memorizar:

Feature grande → carpeta con spec.md + plan.md + tasks.md.
Feature chica → solo spec.md. No sobre-estructures.
Numeración de 4 dígitos (0001-, 0002-): da orden cronológico y un ID estable para referenciar ("implementa la spec 0003").
El versionado lo da Git, nunca el nombre del archivo. Nada de spec-v2.md. Si una spec queda obsoleta, cambias su estado en el frontmatter y apuntas a la que la reemplaza.

Qué lleva una spec

Esta es la plantilla de spec.md — el QUÉ y el porqué. Cópiala tal cual:

markdown

---
feature: auth-login
estado: borrador        # borrador | aprobada | implementada | obsoleta
autor: Lalo García
fecha: 2026-06-04
---

# Spec 0001 — Login de usuario

## Objetivo
Una o dos frases. Qué problema resuelve y para quién.

## Contexto
Por qué se necesita ahora. Qué existe ya.

## Requisitos funcionales
- [ ] RF-1: El usuario inicia sesión con email + contraseña.
- [ ] RF-2: Tokens JWT con expiración de 15 min + refresh token.
- [ ] RF-3: Bloqueo tras 5 intentos fallidos.

## Requisitos NO funcionales
- Contraseñas hasheadas con bcrypt (cost 12).
- Respuesta del endpoint < 300 ms en p95.

## Fuera de alcance
- Login social (Google/GitHub) — spec futura.
- Recuperación de contraseña — spec 0004.

## Criterios de aceptación
- Dado un email válido y contraseña correcta, cuando hago POST /auth/login,
  entonces recibo 200 con accessToken y refreshToken.
- Dado 5 intentos fallidos, el siguiente intento devuelve 429.

## Datos y modelo
Tabla `User` ya existe. Agregar campos `failedAttempts`, `lockedUntil`.

## Preguntas abiertas
- [ ] ¿Refresh token en cookie httpOnly o en body?

La sección que más errores previene es "Fuera de alcance". La IA tiende a sobre-construir; decirle explícitamente qué NO hacer la mantiene a raya.

Para features grandes, el spec.md se acompaña de un plan.md (el CÓMO: schema de Prisma, endpoints de NestJS, archivos a crear) y un tasks.md (checklist accionable). Tres archivos, tres preguntas: qué quiero, cómo se construye, qué pasos sigo.

Haz que la IA lea tus specs de forma confiable

De nada sirve tener specs perfectas si la IA no sabe que existen. El truco es un archivo AGENTS.md (o CLAUDE.md) en la raíz. Claude Code y Cursor lo leen automáticamente:

markdown

# AGENTS.md

## Specs
Las especificaciones viven en `/specs`. Antes de implementar una feature:
1. Lee `specs/README.md` (índice).
2. Lee el `spec.md` de la feature para entender el QUÉ.
3. Lee el `plan.md` para el CÓMO. Respeta las decisiones técnicas.
4. Trabaja contra el checklist de `tasks.md` y marca los `- [x]` que completes.

Regla: si la spec y el código difieren, **la spec gana**. Si encuentras
ambigüedad, pregunta antes de implementar; no inventes requisitos.

## Stack
React + NestJS + PostgreSQL + Prisma. DB local vía Docker (`docker compose up db`).

Ese "si la spec y el código difieren, la spec gana" es oro: convierte la carpeta /specs en la fuente de verdad del proyecto.

El prompt para iniciar tu proyecto

Aquí está lo que prometí. Pega esto en Claude Code (o tu agente favorito) en una carpeta vacía. Inicializa el proyecto con el stack completo y, lo más importante, deja todo listo para que empieces a definir tus specs:

text

Quiero iniciar un proyecto full-stack nuevo. Antes de escribir código,
configúralo siguiendo Spec-Driven Development.

## Stack tecnológico
- Frontend: React (con Vite + TypeScript)
- Backend: NestJS (TypeScript)
- Base de datos: PostgreSQL
- ORM: Prisma
- Base de datos local: Docker (docker-compose con un servicio "db" de Postgres)
- Versionado: Git

## Lo que necesito que hagas, en este orden:

1. Inicializa Git (git init) y crea un .gitignore apropiado para Node,
   React y NestJS (node_modules, .env, dist, etc.).

2. Crea la estructura del monorepo:
   - /apps/web   -> React + Vite + TypeScript
   - /apps/api   -> NestJS + TypeScript
   - /prisma     -> schema.prisma (datasource Postgres)
   - /specs      -> aquí van las especificaciones

3. Crea un docker-compose.yml con un servicio "db" de PostgreSQL 16,
   con volumen persistente y variables de entorno desde .env.
   Incluye un .env.example documentado.

4. Configura Prisma para conectarse a esa base de datos vía DATABASE_URL.
   Crea un modelo de ejemplo (Health o User) y deja el comando de migración
   documentado en el README.

5. Crea la carpeta /specs con:
   - specs/README.md      -> índice (tabla con ID, feature, estado, link)
   - specs/_template.md   -> plantilla de spec con frontmatter
     (feature, estado, autor, fecha) y secciones: Objetivo, Contexto,
     Requisitos funcionales, Requisitos NO funcionales, Fuera de alcance,
     Criterios de aceptación (formato Dado/Cuando/Entonces), Datos y modelo,
     Preguntas abiertas.

6. Crea un AGENTS.md en la raíz (y CLAUDE.md como copia) que le indique a
   cualquier agente de IA:
   - Que las specs viven en /specs y en qué orden leerlas.
   - Que la regla es: si la spec y el código difieren, la spec gana.
   - Que ante ambigüedad debe preguntar antes de implementar.
   - El stack y cómo levantar la DB local (docker compose up db).

7. Crea un README.md con: requisitos, cómo levantar la DB con Docker,
   cómo correr migraciones de Prisma, y cómo arrancar web y api en dev.

NO implementes features de negocio todavía. Solo deja el esqueleto y las specs
listas. Al terminar, muéstrame los comandos para levantar todo y dime cuál es
el siguiente paso para escribir mi primera spec.

Cuando termine, ya tendrás un proyecto andando, con la base de datos corriendo en Docker y, sobre todo, una carpeta /specs lista para que escribas tu primera especificación. A partir de ahí, cada feature empieza con una spec, no con un prompt al aire.

Lo que sigue: wireframes

Las especificaciones definen el qué y el cómo. Pero falta la otra mitad: cómo se ve y se siente la app. Eso son los wireframes, y son igual de importantes para que la IA construya bien la interfaz. Lo cubro en el siguiente video y post.

Por ahora, quédate con esto: la próxima vez que sientas que "la IA no te hace caso", revisa qué tan claras fueron tus instrucciones. Casi siempre, la respuesta está ahí.

Si te sirvió, sígueme en mis redes para no perderte la parte de wireframes.