Kiro Specs: Deja de Improvisar y Empieza a Planificar Features con IA

Antonia Navarrete — Tue, 28 Apr 2026 21:15:37 +0000

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.

DEV Community: Antonia Navarrete

[Boost]