Si alguna vez arrancaste a codear una feature "porque ya sabes lo que hay que hacer" y terminaste reescribiendo todo a mitad del camino... este post es para ti.
Kiro Specs es una de las funcionalidades más poderosas del IDE Kiro, y la mayoría de los devs la ignora porque suena a burocracia. Spoiler: no lo es. Es la diferencia entre vibe coding y desarrollo estructurado con IA.
¿Qué es un Spec en Kiro?
Un Spec (especificación) es un artefacto estructurado que convierte una idea de alto nivel en un plan de implementación detallado, con trazabilidad desde el requisito hasta el código.
Cada vez que creas un Spec, Kiro genera automáticamente tres archivos:
.kiro/specs/mi-feature/
├── requirements.md → Qué debe hacer el sistema
├── design.md → Cómo lo va a hacer
└── tasks.md → Lista de tareas ejecutables
No son documentos para guardar en un cajón. Son artefactos vivos que la IA usa para generar código coherente y trazable.
Los Dos Workflows: ¿Por Dónde Empiezas?
Kiro ofrece dos flujos según tu punto de partida:
🔹 Requirements-First (Requisitos primero)
El flujo más común. Lo usas cuando sabes qué quieres construir pero el cómo es flexible.
Requisitos → Diseño → Tareas → Código
Cuándo usarlo:
- Estás construyendo una feature desde cero
- El producto manda (customer feedback, historias de usuario)
- La arquitectura puede adaptarse a los requisitos
- Proyecto greenfield
🔹 Design-First (Diseño primero)
Lo usas cuando ya tienes una arquitectura en mente o restricciones técnicas no negociables.
Diseño → Requisitos → Tareas → Código
Cuándo usarlo:
- Tienes un diagrama de arquitectura existente
- Hay requisitos no funcionales estrictos (latencia, compliance)
- Estás portando diseños desde otra herramienta
- Necesitas validar factibilidad técnica antes de comprometerte
La Notación EARS: Requisitos que la IA Entiende (y tú también)
El requirements.md usa EARS (Easy Approach to Requirements Syntax), un estándar de la industria para escribir requisitos sin ambigüedad.
El patrón es simple:
WHEN [condición o evento]
THE SYSTEM SHALL [comportamiento esperado]
Ejemplo: Sistema de autenticación
## Requisito 1: Registro de usuario
WHEN a user submits the registration form with valid email and password
THE SYSTEM SHALL create a new account and send a verification email
## Requisito 2: Validación de formulario
WHEN a user submits the registration form with an already-registered email
THE SYSTEM SHALL display an error message without creating a duplicate account
## Requisito 3: Bloqueo por intentos fallidos
WHEN a user fails to login 5 consecutive times
THE SYSTEM SHALL temporarily block the account for 15 minutes and notify the user
¿Por qué esto importa? Porque cada requisito en formato EARS es:
- Inequívoco: no hay lugar para interpretaciones
- Testeable: cada uno se convierte directamente en un caso de prueba
- Trazable: puedes rastrear cada línea de código hasta el requisito que la originó
El design.md: Arquitectura Generada Automáticamente
Una vez confirmados los requisitos, Kiro genera el design.md con:
- Arquitectura del sistema y sus componentes
- Diagramas de secuencia
- Modelos de datos e interfaces
- Stack tecnológico recomendado
- Estrategia de manejo de errores
- Enfoque de testing
Fragmento de ejemplo:
## Arquitectura del Sistema de Autenticación
### Componentes
- **AuthController**: Maneja las rutas HTTP de autenticación
- **UserService**: Lógica de negocio para gestión de usuarios
- **TokenService**: Generación y validación de JWT
- **EmailService**: Envío de correos transaccionales
### Diagrama de Secuencia: Login
User → AuthController: POST /auth/login
AuthController → UserService: validateCredentials(email, password)
UserService → DB: findUserByEmail(email)
DB → UserService: user record
UserService → UserService: comparePassword(hash)
UserService → TokenService: generateJWT(userId)
TokenService → AuthController: { accessToken, refreshToken }
AuthController → User: 200 OK + tokens
El tasks.md: Tu Roadmap de Implementación
El último archivo que genera Kiro es el más concreto: una lista de tareas ejecutables, con dependencias y estado en tiempo real.
## Tareas de Implementación
- [ ] 1. Configurar la base de datos de usuarios
- Crear migración para tabla `users`
- Definir índices para email (unique)
- Agregar campos: id, email, password_hash, created_at, is_verified
- [ ] 2. Implementar UserService
- Método `createUser(email, password)`
- Método `validateCredentials(email, password)`
- Manejo de errores: DuplicateEmailError, InvalidCredentialsError
- [ ] 3. Implementar TokenService
- Generación de JWT con expiración configurable
- Refresh token con rotación automática
- Blacklist para tokens revocados
- [ ] 4. Crear AuthController
- POST /auth/register
- POST /auth/login
- POST /auth/logout
- POST /auth/refresh
- [ ] 5. Tests de integración
- Happy path: registro → verificación → login
- Error cases: email duplicado, credenciales inválidas
- Rate limiting: 5 intentos fallidos → bloqueo
Puedes ejecutar cada tarea individualmente o todas a la vez. Kiro actualiza el estado en tiempo real mientras implementa.
Flujo Completo: Del Prompt al Código
Así se ve el proceso desde cero:
Paso 1: Crear el Spec
En el panel de Kiro, haz clic en + bajo la sección Specs, o escribe en el chat:
Spec: sistema de autenticación con registro por email,
login, logout y reset de contraseña. Debe proteger
contra fuerza bruta y validar formatos de email.
Paso 2: Elegir el workflow
Kiro te pregunta: ¿Feature o Bug fix? Selecciona Feature, luego elige Requirements-First.
Paso 3: Iterar sobre requisitos
Kiro genera el primer borrador de requirements.md. Puedes refinarlo:
Agrega un requisito para que el sistema soporte
autenticación con Google OAuth como alternativa
Paso 4: Revisar el diseño
Kiro genera design.md. Aquí validas que la arquitectura sea correcta antes de que empiece a generar código. Puedes pedir cambios:
Cambia el storage de sesiones de memoria a Redis
para soportar múltiples instancias del servidor
Paso 5: Ejecutar tareas
Una vez aprobado el diseño, abres tasks.md y ejecutas las tareas. Kiro implementa, y tú revisas.
Cuándo Usar Specs vs. Vibe Coding
No siempre necesitas un Spec. Aquí la guía rápida:
| Situación | Usa |
|---|---|
| Feature compleja con múltiples componentes | Specs |
| Bug donde las regresiones son costosas | Specs |
| Necesitas documentación para el equipo | Specs |
| Prototipo rápido sin objetivos claros | Vibe |
| Exploración técnica sin entregables | Vibe |
| Cambio menor de una sola línea | Vibe |
Tips para Sacarle el Máximo
1. Itera en los requisitos ANTES de pasar al diseño. El poder de Requirements-First está en definir bien el "qué" antes de comprometerte con el "cómo".
2. Importa requisitos existentes. Si tienes un PRD en Confluence o tickets en Jira, puedes copiar el contenido a un archivo y pedirle a Kiro que genere el Spec desde él:
#mi-prd.md Genera un spec a partir de este documento
3. Usa imágenes de arquitectura. Si tienes un diagrama en draw.io o una foto de la pizarra, puedes incluirlo en tu prompt al usar Design-First. Kiro lo interpreta.
4. Los Specs son vivos. Si cambian los requisitos, no empieces de cero: edita requirements.md y haz clic en Refine en el design.md. Kiro actualiza todo en cascada.
Conclusión
Los Specs de Kiro no son burocracia: son la forma de hacer que la IA trabaje de manera predecible y trazable en features complejas. En lugar de tener un agente que improvisa, tienes uno que sigue un plan que tú aprobaste.
La próxima vez que vayas a arrancar una feature no trivial, antes de escribir la primera línea de código, prueba crear un Spec. El tiempo que "perdés" planificando te lo devuelve duplicado en debugging evitado.
¿Te resultó útil? En el próximo post voy a cubrir **Hooks: cómo automatizar tareas repetitivas con triggers inteligentes en Kiro.