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. 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. Kiro ofrece dos flujos según tu punto de partida: 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 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 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] ## 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ó 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 ## 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 ú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. Así se ve el proceso desde cero: 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. Kiro te pregunta: ¿Feature o Bug fix? Selecciona Feature, luego elige Requirements-First. 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 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 Una vez aprobado el diseño, abres tasks.md y ejecutas las tareas. Kiro implementa, y tú revisas. 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 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. 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.