Conozco la sensación. Descargaste Kiro porque escuchaste que era el siguiente nivel de los IDE con IA. Lo abriste, viste algo parecido a VS Code, y pensaste "esto lo domino". Dos minutos después estás leyendo sobre specs, steering files, hooks, vibe mode, EARS notation, powers... y ya no sabes si estás usando un IDE o configurando un satélite.
La documentación oficial es completa, pero no siempre te dice por dónde empezar. Te da el qué, pero no siempre el cómo ni el cuándo. Y si eres como yo, necesitas alguien que te diga: "tranquilo, empieza por aquí, ignora eso por ahora, y esto otro lo vas a necesitar mañana".
Eso es exactamente lo que vamos a hacer. Al terminar este artículo vas a entender los tres conceptos fundamentales de Kiro, vas a tener tu primer proyecto configurado, y vas a saber cuándo usar cada modo de trabajo. Sin rodeos.
Todo el código y los templates de este artículo están en el Kiro Starter Kit — un repo con templates, hooks, guías de decisión y ejemplos completos listos para copiar a tu proyecto.
Kiro en 2 minutos
Kiro es un IDE creado por AWS que integra un agente de IA directamente en tu flujo de desarrollo. Hasta ahí suena como cualquier otro copiloto de código. La diferencia está en cómo trabaja.
Un copiloto tradicional te autocompleta líneas. Kiro entiende tu proyecto completo: sabe qué stack usas, cómo está organizado tu código, cuáles son tus convenciones y qué estás intentando construir. No adivina: tiene contexto.
¿Cómo lo logra? Con tres mecanismos:
- Specs le dicen qué construir (requisitos, diseño, plan de tareas).
- Steering files le dicen cómo construir (tu stack, tu arquitectura, tus reglas).
- Hooks automatizan lo que no quieres hacer manualmente (tests, docs, seguridad).
Piensa en Kiro no como un autocompletador inteligente, sino como un developer junior que se leyó toda la documentación de tu proyecto antes de escribir su primera línea de código. Tu trabajo es darle esa documentación.
Los 3 conceptos que necesitas entender
1. Steering files: el manual del empleado nuevo
Imagina que llega un developer nuevo a tu equipo. ¿Qué le darías para que empiece a ser productivo? Probablemente un documento con el stack tecnológico, la estructura del proyecto, las convenciones de código y el contexto del producto. Eso son los steering files.
Son archivos Markdown que viven en .kiro/steering/ y le dan al agente contexto persistente sobre tu proyecto. Los tres fundamentales son:
- product.md — Qué es tu producto, para quién es, qué problema resuelve. Es el "por qué existimos".
- tech.md — Tu stack: lenguajes, frameworks, bases de datos, herramientas. Es el "con qué trabajamos".
- structure.md — Cómo está organizado el código: directorios, convenciones de nombres, patrones de importación. Es el "dónde va cada cosa".
Estos tres archivos se configuran con inclusion: always, lo que significa que el agente los lee en cada interacción. Cada vez que le pides algo, ya sabe que usas TypeScript con Express, que tus tests van en __tests__/, y que tu API sigue REST con versionado en la URL.
También puedes crear steering files especializados (estándares de API, políticas de seguridad, convenciones de testing) con inclusion: fileMatch, para que se carguen solo cuando el agente trabaja con archivos relevantes. Así no desperdicias contexto.
La analogía: si el agente de Kiro fuera un chef, los steering files serían la receta base, la lista de ingredientes disponibles y las reglas de la cocina. Sin eso, cocina a ciegas.
2. Specs: el plano antes de construir
¿Alguna vez empezaste a codear un feature sin pensar en el diseño y terminaste reescribiéndolo tres veces? Los specs son la solución a eso.
Un spec es un conjunto de tres documentos que Kiro genera a partir de un prompt tuyo:
- requirements.md — User stories con acceptance criteria formales. Kiro usa EARS notation (Easy Approach to Requirements Syntax), que estructura los requisitos como: "WHEN un usuario hace X, THE SYSTEM SHALL hacer Y". Suena formal, pero es útil para que no quede nada ambiguo.
- design.md — La arquitectura técnica: componentes, flujo de datos, diagramas de secuencia, esquema de base de datos. Es el plano del edificio antes de poner el primer ladrillo.
- tasks.md — El plan de implementación dividido en tareas numeradas. Cada tarea especifica qué archivos crear o modificar y los criterios de aceptación.
Lo valioso del sistema es el flujo: Requirements → Design → Tasks → Implementation. En cada fase puedes refinar antes de avanzar. No te gusta un requirement? Lo ajustas antes de que genere el design. ¿El design no usa la tecnología correcta? Lo refinas antes de que genere las tasks.
La analogía: los specs son como el proceso de un arquitecto. No empieza a construir la casa pidiendo ladrillos. Primero entiende qué necesita el cliente (requirements), dibuja los planos (design) y hace la lista de trabajo (tasks).
3. Vibe mode vs spec mode: la intuición y el método
Kiro ofrece dos formas de trabajar:
Vibe mode es conversación libre. Abres el chat, le preguntas, le pides cambios, debuggeas. No genera documentación formal. Es rápido, directo, informal. Como pedirle ayuda a un colega en el escritorio de al lado.
Spec mode es trabajo estructurado. Generas requirements, design y tasks antes de tocar código. Es más lento al inicio, pero produce resultados más consistentes y documentados. Como una reunión de planificación antes de un sprint.
La pregunta no es cuál es mejor, sino cuándo usar cada uno:
- Vibe mode: bugs simples, preguntas, cambios en 1-3 archivos, cosas de menos de una hora.
- Spec mode: features nuevos, trabajo que toca 3+ archivos, cualquier cosa que necesite documentación o que involucre a más personas.
Tu primer proyecto con Kiro
Basta de teoría. Vamos a configurar un proyecto real paso a paso.
Paso 1: Crear la estructura .kiro (5 minutos)
Abre tu proyecto en Kiro y crea la estructura de directorios:
mkdir -p .kiro/{steering,hooks,settings,specs}
O si quieres ir más rápido, el Kiro Starter Kit incluye un script que inicializa todo con templates listos:
git clone https://github.com/jcarriolaa/kiro-starter-kit.git
cd kiro-starter-kit
./scripts/setup-kiro-project.sh fullstack # o: data | aws | minimal
El script crea la estructura .kiro/, copia los templates de steering files, hooks, y configura MCP según el tipo de proyecto. Si prefieres hacerlo manual, sigue con los pasos de abajo.
Paso 2: Crear tus steering files (10 minutos)
Crea tres archivos en .kiro/steering/. No necesitas llenarlos perfectamente desde el inicio. Lo importante es que existan y tengan lo básico.
.kiro/steering/product.md — Define tu producto:
---
inclusion: always
---
# Producto
## Propósito
API REST para gestión de usuarios con autenticación JWT.
## Usuarios objetivo
- Frontend web app (SPA en React)
- Aplicaciones móviles
## Features principales
- Registro y login de usuarios
- CRUD de perfiles
- Control de acceso basado en roles
.kiro/steering/tech.md — Define tu stack:
---
inclusion: always
---
# Stack Tecnológico
## Lenguaje
- TypeScript 5.x (strict mode)
## Backend
- Node.js 20 LTS
- Express.js 4.x
## Base de datos
- PostgreSQL 16
## Testing
- Vitest
## Validación
- Zod
.kiro/steering/structure.md — Define tu arquitectura:
---
inclusion: always
---
# Estructura del Proyecto
## Layout
- src/controllers/ — Route handlers
- src/services/ — Business logic
- src/repositories/ — Data access layer
- src/middleware/ — Express middleware
- src/schemas/ — Zod validation schemas
- tests/ — Test files (mirror src/ structure)
## Convenciones
- Archivos: kebab-case (user-service.ts)
- Clases: PascalCase
- Funciones: camelCase
- Un archivo por responsabilidad
## Module Boundaries
api → core → infrastructure
api → shared
core → shared
❌ infrastructure → core (use dependency injection)
❌ shared → anything except stdlib
Este último bloque de Module Boundaries es clave — le dice al agente qué capas pueden importar de qué otras. Sin esto, Kiro podría generar imports circulares o violar tu arquitectura de capas. El template del Starter Kit incluye además file templates con código de ejemplo para que el agente siga el patrón exacto cuando cree archivos nuevos.
Eso es todo. Tres archivos, información concreta, sin florituras. Reinicia Kiro después de crearlos para que los detecte.
Si quieres templates más completos, el Kiro Starter Kit incluye 7 steering files listos para personalizar. Por ejemplo, el template de tech.md incluye secciones para infraestructura, CI/CD, política de dependencias y ambientes:
## Infrastructure
### Cloud Provider
- **Provider**: [AWS/GCP/Azure]
- **Region**: [us-east-1/etc.]
### Compute
- **Primary**: [ECS Fargate/Lambda/EC2/EKS]
- **Background Jobs**: [Lambda/Step Functions/etc.]
## CI/CD
### Environments
| Environment | Purpose | Deploy Trigger |
|-------------|---------|----------------|
| `dev` | Development testing | Push to `develop` |
| `staging` | QA/UAT | Push to `staging` |
| `prod` | Production | Tag release / Manual |
También hay templates especializados con inclusion: fileMatch para API standards, testing standards y security policies.
Paso 3: Tu primer spec (10 minutos)
Ahora viene lo interesante. Abre Kiro en spec mode y escribe un prompt como este:
Create a spec for a new API endpoint:
**Endpoint**: POST /api/auth/register
**Purpose**: Register a new user with email and password
**Input**:
- email: string - valid email, required
- password: string - min 8 chars, 1 uppercase, 1 number, required
- name: string - required
**Business Rules**:
- Email must be unique
- Password hashed with bcrypt (salt 12)
- Return user profile without password
**Constraints**:
- Rate limit: 10 requests per minute per IP
- Validate all inputs with Zod
Kiro va a generar tres archivos en .kiro/specs/user-registration/. Para que veas qué esperar, el Kiro Starter Kit incluye un ejemplo completo de este spec. Acá un resumen de lo que genera:
requirements.md — User stories con EARS notation:
### Requirement 1: Registro de usuarios
**User Story:**
Como visitante del sistema, quiero registrarme con mi email y contraseña,
para poder obtener una cuenta y acceder a las funcionalidades protegidas.
**Acceptance Criteria:**
1. WHEN un visitante envía un request POST a `/api/auth/register` con email
y contraseña válidos THE SYSTEM SHALL crear un nuevo usuario en la base
de datos AND SHALL retornar HTTP 201 con el perfil del usuario creado
(sin incluir la contraseña)
2. WHEN un visitante intenta registrarse con un email que ya existe
THE SYSTEM SHALL retornar HTTP 409 (Conflict)
3. THE SYSTEM SHALL almacenar las contraseñas usando bcrypt con salt round
mínimo de 12
design.md — Arquitectura, esquema de datos y diagramas:
-- Kiro genera el schema SQL basado en tus requirements
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email VARCHAR(255) UNIQUE NOT NULL,
password VARCHAR(255) NOT NULL,
name VARCHAR(100) NOT NULL,
role VARCHAR(20) NOT NULL DEFAULT 'user'
CHECK (role IN ('user', 'admin')),
is_active BOOLEAN NOT NULL DEFAULT TRUE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
// Y las interfaces TypeScript coherentes con tu stack
interface UserResponse {
id: string;
email: string;
name: string;
role: string;
isActive: boolean;
createdAt: string;
}
También incluye tabla de endpoints, decisiones técnicas con justificación, diagrama de secuencia del flujo completo y estrategia de manejo de errores. Ver design.md completo en el Starter Kit.
tasks.md — Plan de implementación numerado:
## Task 1: Configuración del proyecto y dependencias (30 min)
- Ejecutar `npm init`, configurar `tsconfig.json` con strict mode
- Instalar: express, pg, bcrypt, jsonwebtoken, zod, express-rate-limit
- Crear estructura: src/controllers/, src/services/, src/repositories/
## Task 3: Esquemas de validación con Zod (1 hora)
- Schema de registro: email (RFC 5322, lowercase), password (min 8,
mayúscula, minúscula, número), name
- Helper de sanitización que remueva tags HTML
## Task 5: Auth Service (1 hora)
- register: verificar email único, hash con bcrypt (salt 12), retornar DTO
- login: buscar por email, comparar password, generar JWT {sub, email, role}
## Task 9: Tests unitarios de services (2 horas)
- AuthService.register: caso exitoso, email duplicado, validación de hash
- AuthService.login: credenciales válidas, password incorrecto, usuario inactivo
El ejemplo completo tiene 11 tasks con dependencias, archivos a crear y tiempo estimado por tarea. Cada task tiene steps detallados que Kiro ejecuta uno a uno.
Antes de implementar nada, revisa cada documento. Si algo no te convence, usa "Refine" para ajustarlo. Este es el momento de corregir, no después de que el código ya esté escrito.
Paso 4: Ejecutar tasks (5 minutos)
Cuando estés conforme con los tres documentos, ve al panel de specs y haz click en "Start task" para ejecutar una tarea a la vez, o "Run all tasks" si confías en el plan completo.
Kiro va a generar código que respeta tu arquitectura (controller → service → repository), usa las tecnologías que definiste (Express, Zod, bcrypt) y sigue las convenciones que documentaste (kebab-case, un archivo por responsabilidad).
Revisa el código generado. Si necesitas ajustes menores, cámbiate a vibe mode: "el error message de email duplicado debería incluir un código de error". Commitea cuando estés satisfecho.
¿Cuándo uso vibe mode y cuándo spec mode?
Esta es la pregunta del millón, y la respuesta cabe en una tarjeta:
VIBE si: SPEC si:
- Menos de 1 hora - Más de 1 hora
- 1-3 archivos - 3+ archivos
- Solo yo - Trabajo en equipo
- No necesito docs - Necesito documentación
- Bug fix / pregunta - Feature nuevo
- Exploración / POC - Código para producción
Regla de oro: si tienes dudas, empieza con vibe mode. Si la tarea crece y llevas más de una hora o has tocado más de 5 archivos, cambia a spec mode. Puedes pedirle a Kiro que genere un spec a partir de la conversación que ya tuviste:
This is getting complex. Generate spec from this conversation.
Algunos ejemplos prácticos:
| Tarea | Modo | Por qué |
|---|---|---|
| Arreglar un typo en una validación | Vibe | Trivial, 1 archivo |
| Agregar un endpoint GET simple | Vibe | Cambio localizado |
| Implementar autenticación completa | Spec | Múltiples componentes, necesita diseño |
| "No entiendo este middleware" | Vibe | Solo es una pregunta |
| Integrar pagos con Stripe | Spec | Sistema externo, complejo |
| Refactorizar una función | Vibe | Localizado |
| Migrar de REST a GraphQL | Spec | Cambio arquitectural masivo |
Lo peor que puedes hacer es usar vibe mode para un feature de dos semanas. Terminas con código fragmentado, sin documentación y sin trazabilidad. Lo segundo peor es usar spec mode para cambiar un string. Respeta el peso de cada herramienta.
Hooks: tu copiloto silencioso
Los hooks son automatizaciones que se disparan ante eventos del IDE. Se definen como archivos .kiro.hook (JSON) en .kiro/hooks/ y ejecutan prompts cuando se cumplen ciertas condiciones.
Piensa en ellos como reglas de "si pasa esto, haz aquello" que trabajan en segundo plano. Tres ejemplos que vale la pena tener desde el día uno:
1. Test Synchronizer
Se activa cuando editas un archivo de código fuente (no de tests). Le pide al agente que revise si los tests correspondientes necesitan actualizarse.
{
"name": "Test Synchronizer",
"description": "Suggests test updates when source code changes.",
"enabled": true,
"version": "1",
"when": {
"type": "fileEdited",
"patterns": [
"src/**/*.py", "src/**/*.ts",
"!src/**/*_test.py", "!src/**/*.test.ts", "!src/**/*.spec.ts"
]
},
"then": {
"type": "askAgent",
"prompt": "A source file has been modified. Please:\n1. Check if a corresponding test file exists\n2. If tests exist, analyze if they need updates based on the changes:\n - New functions/methods added → suggest new test cases\n - Function signatures changed → update existing tests\n - Logic changes → verify test coverage\n3. If no tests exist, suggest creating a test file with basic test cases"
}
}
Este hook y 4 más vienen pre-configurados en el Kiro Starter Kit.
Resultado: nunca más olvidas actualizar los tests cuando cambias la lógica.
2. Security Scanner
Se activa manualmente (antes de hacer commit). Escanea los archivos staged buscando secretos hardcodeados, vulnerabilidades de inyección, datos sensibles expuestos y problemas de autenticación.
{
"name": "Security Scanner",
"description": "Scans staged files for common security vulnerabilities before commit.",
"enabled": true,
"version": "1",
"when": { "type": "userTriggered" },
"then": {
"type": "askAgent",
"prompt": "Perform a security scan on staged files (git diff --staged):\n\nCheck for:\n1. Hardcoded Secrets - API keys, tokens, passwords, connection strings\n2. Injection Vulnerabilities - SQL injection, command injection, XSS\n3. Sensitive Data Exposure - PII in logs, credentials in config\n4. Auth Issues - Missing auth checks, hardcoded user IDs\n\nFor each finding report: Severity (CRITICAL/HIGH/MEDIUM/LOW), File:line, Issue, Remediation."
}
}
Resultado: una capa extra de seguridad antes de cada commit, sin instalar herramientas externas.
3. Documentation Sync
Se activa cuando editas archivos de API. Revisa si la documentación necesita actualizarse.
{
"name": "Documentation Sync",
"enabled": true,
"version": "1",
"when": {
"type": "fileEdited",
"patterns": ["src/api/**/*.ts"]
},
"then": {
"type": "askAgent",
"prompt": "An API file was modified. Check if documentation needs updates: docstrings, OpenAPI schemas, README examples."
}
}
Resultado: documentación que se mantiene sincronizada con el código automáticamente.
Los hooks no reemplazan tu CI/CD ni tus linters. Son una capa adicional de asistencia que trabaja mientras tú te enfocas en la lógica de negocio.
Tips de alguien que ya pasó por esto
Después de usar Kiro extensamente, estas son las cosas que desearía haber sabido el primer día:
1. Los steering files no tienen que ser perfectos al inicio. Empieza con lo mínimo (producto, stack, estructura) y ve refinando. Cada vez que Kiro genere algo que no respeta tus convenciones, es señal de que falta información en los steering files. Agrégala y no volverá a pasar.
2. Revisa siempre los requirements antes del design. Es tentador darle "siguiente" a todo y que genere el código de una vez. No lo hagas. Los errores en requirements se multiplican en el design y se convierten en bugs en la implementación. Cinco minutos revisando requirements te ahorra una hora de debugging.
3. Los context providers son tu mejor amigo en vibe mode. Usa #terminal cuando tienes un error, #current cuando trabajas en un archivo, #git diff para code review. Le dan al agente el contexto exacto que necesita sin copiar y pegar nada.
4. No uses spec mode para todo. Es la trampa clásica del developer que descubre specs: querer especificar hasta el cambio de un color. Specs son para features que necesitan diseño previo. Para lo demás, vibe mode es más eficiente.
5. Los hooks se acumulan rápido. Empieza con 2-3 (test sync, security scan, docs sync) y agrega más según los necesites. Demasiados hooks activos generan ruido y consumen créditos innecesariamente.
6. Estructura tus prompts de spec con contexto. No le digas solo "create a user registration endpoint". Usa esta estructura:
Create a spec for a new API endpoint:
**Endpoint**: [METHOD] /api/v1/[resource]
**Purpose**: [Qué hace]
**Input**:
- [campo]: [tipo] - [descripción]
**Business Rules**:
- [Regla 1]
**Constraints**:
- [Auth? Rate limits? etc.]
El Kiro Starter Kit incluye una biblioteca completa de prompts: templates para crear specs de APIs, CRUDs, integraciones, jobs; prompts para refinar requirements y design; y prompts efectivos para sesiones en vibe mode (debugging, code review, refactoring).
7. El patrón híbrido Vibe → Spec es poderoso. Cuando no tienes claro el approach, explora en vibe mode. Haz preguntas, prueba ideas, haz un POC rápido. Cuando tengas claridad, genera un spec desde esa conversación: "This is getting complex. Generate spec from this conversation." Lo mejor de ambos mundos.
Lo que viene: Kiro está evolucionando rápido
Este artículo cubre los fundamentos — lo que necesitas para ser productivo desde el día uno. Pero Kiro ha estado lanzando features a ritmo acelerado en 2026:
- Autonomous Agent — un agente que trabaja en background, crea PRs, y aprende de tus code reviews
- Custom subagents — agentes especializados con roles y herramientas específicas
- Agent Skills — paquetes de instrucciones compartibles entre proyectos
- Nuevos workflows de specs — Design-First (empezar por arquitectura) y Bugfix (análisis de root cause estructurado)
Eso lo cubriremos en el siguiente artículo de esta serie. Primero domina los fundamentos — el resto se construye sobre ellos.
Kiro Starter Kit: el repo companion de este artículo
Armé el Kiro Starter Kit como recurso práctico para que no tengas que crear todo desde cero. Incluye:
Templates listos para copiar:
- 7 steering files — product, tech, structure, API standards, testing, security, code conventions
- 5 hooks pre-configurados — test sync, security scan, docs sync, commit messages, SQL optimizer
- 4 configuraciones MCP — fullstack, AWS, data engineering, minimal
- 4 agentes custom — code reviewer, data engineer, AWS architect, backend developer
Ejemplos completos de specs:
- REST API con EARS notation — requirements, design y tasks completos
- ETL Pipeline — spec para pipeline de datos
Guías de decisión:
- ¿Vibe o Spec? — Árbol de decisión completo
- Estrategia de steering — Qué archivos crear según tu proyecto
- Patrones de hooks — Cuáles usar según tu stack
Setup rápido:
./scripts/setup-kiro-project.sh fullstack --with-agents
Otros recursos:
Top comments (0)