Kiro: comandos SDD

Kiro es el IDE de AWS que popularizó un flujo de spec-driven development por fases: primero requisitos, luego diseño, luego tareas y solo al final código, con una aprobación humana en cada salto.

Ese mismo flujo se puede usar desde la terminal, sin el IDE, con cc-sdd: un paquete npm que instala las skills de Kiro dentro del agente que ya estés usando. Es un proyecto independiente de terceros, no un producto de AWS, pero reproduce las mismas fases y los mismos documentos.

En este tema, «Kiro» significa cc-sdd.

• Proyecto: github.com/gotalab/cc-sdd (v3.0.2, MIT)

Hace falta Node.js y ejecutar el comando en la raíz del proyecto, porque instala ficheros dentro de él.

cd mi-proyecto
npx cc-sdd@latest --claude-skills --lang es

mi-proyecto/
├── .claude/skills/              # las skills de Kiro
│   ├── kiro-steering/
│   ├── kiro-spec-init/
│   ├── kiro-spec-requirements/
│   ├── kiro-spec-design/
│   ├── kiro-spec-tasks/
│   └── kiro-impl/
├── .kiro/
│   ├── settings/                # plantillas y reglas, personalizables
│   ├── steering/                # memoria del proyecto  <- la crea /kiro-steering
│   └── specs/                   # una carpeta por funcionalidad <- la crea /kiro-spec-init
└── CLAUDE.md

cd mi-proyecto
npx cc-sdd@latest --opencode-skills --lang es

mi-proyecto/
├── .opencode/skills/            # las skills de Kiro
│   ├── kiro-steering/
│   ├── kiro-spec-init/
│   ├── kiro-spec-requirements/
│   ├── kiro-spec-design/
│   ├── kiro-spec-tasks/
│   └── kiro-impl/
├── .kiro/
│   ├── settings/                # plantillas y reglas, personalizables
│   ├── steering/                # memoria del proyecto  <- la crea /kiro-steering
│   └── specs/                   # una carpeta por funcionalidad <- la crea /kiro-spec-init
└── AGENTS.md

Cambia la carpeta de las skills y el fichero de configuración del agente; el contenido de .kiro/ y los comandos son idénticos a los de Claude Code.

Estos son los pasos que se dan una sola vez, al empezar con el proyecto. A partir de ahí, lo único que se repite es el ciclo de la sección siguiente.

Los dos primeros pasos se dan una sola vez. El resto se repite por cada funcionalidad nueva, y de ahí la flecha de vuelta de kiro-impl a kiro-spec-init.

/kiro-steering crea lo que en cc-sdd se llama steering: la memoria del proyecto, lo que todos los demás comandos leen antes de hacer nada. Son tres documentos en .kiro/steering/:

Sin steering, cada especificación arranca a ciegas y el agente reinventa las convenciones del proyecto en cada funcionalidad. Con él, todas parten del mismo contexto.

Es lo primero que hay que ejecutar, y conviene revisar los tres documentos antes de seguir: pasan a ser la fuente de verdad del agente, así que un error aquí se propaga a todas las especificaciones.

Esto es lo que se repite una vez por cada funcionalidad que quieras construir.

Los documentos viven juntos, uno por funcionalidad:

.kiro/specs/user-auth-oauth/
├── spec.json          # metadatos y estado de aprobación de cada fase
├── requirements.md    # QUÉ
├── design.md          # CÓMO
└── tasks.md           # tareas

spec.json guarda si cada fase está generada y si está aprobada. Un comando se niega a arrancar si la fase anterior no lo está:

Requirements not yet approved. Approval required before design generation.

Sin -y el comando se para con el mensaje de arriba. -y no es un atajo para ir más deprisa: es la forma de decir «ya he leído el documento anterior y me vale». Léelo de verdad antes de escribirlo.

/kiro-spec-init Álbumes de fotos con subida, etiquetado y compartición
/kiro-spec-requirements photo-albums
/kiro-spec-design photo-albums -y
/kiro-spec-tasks photo-albums -y
/kiro-impl photo-albums

Leyendo y aprobando el documento de cada fase antes de lanzar la siguiente.

/kiro-steering

Crea o actualiza la memoria del proyecto. No lleva argumentos.

Produce tres documentos en .kiro/steering/: product.md (para qué sirve el producto), tech.md (stack y decisiones técnicas) y structure.md (organización y convenciones).

La primera vez los escribe desde cero leyendo README, dependencias y árbol de directorios. Las siguientes veces compara con el código y reporta lo que se ha desviado, respetando lo que hayas editado a mano.

• Captura patrones, no inventarios. «Así se nombran los servicios aquí», no una lista de los 200 ficheros del proyecto.
• Relánzalo de vez en cuando para que no se quede desfasado respecto al código ya escrito.

/kiro-spec-init <descripción de la funcionalidad>

/kiro-spec-init Autenticación de usuarios con OAuth 2.0 y tokens JWT para una aplicación Next.js

Crea el esqueleto de la especificación de una funcionalidad.

Produce .kiro/specs/<nombre>/ con spec.json y un requirements.md vacío. El nombre lo genera él en kebab-case a partir de la descripción: aquí, user-auth-oauth.

• Comprueba que la descripción dice quién tiene el problema, cuál es la situación actual y qué debería cambiar. Si falta algo, pregunta en lugar de suponerlo.
• No escribe requisitos, ni diseño, ni tareas: solo la estructura. Por eso es instantáneo.
• Cuanto más concreta sea la descripción —stack, restricciones, requisitos clave—, mejor arranca todo lo demás.

/kiro-spec-requirements user-auth-oauth

Convierte la descripción en un documento de requisitos verificable. El argumento es el nombre de la carpeta, no la descripción.

Produce requirements.md con los criterios de aceptación en formato EARS.

EARS (Easy Approach to Requirements Syntax) es una sintaxis acotada para escribir criterios que no admitan dos lecturas:

WHEN  <disparador>   THE <sistema> SHALL <acción>
IF    <condición>    THEN THE <sistema> SHALL <acción>
THE <sistema> SHALL <acción>

Un fragmento del documento resultante:

### 1.1 Autenticación de usuarios
**FR-1.1.1**: Login con OAuth
- WHEN el usuario pulsa "Entrar con Google" THE sistema SHALL redirigir a la pantalla de consentimiento
- WHEN se recibe el callback de OAuth THE sistema SHALL validar el código de autorización
- IF la validación es correcta THEN THE sistema SHALL crear una sesión con token JWT

Cada línea es directamente un caso de prueba: hay un disparador, un sujeto y un resultado observable.

Es la regla que más cuesta respetar:

Prueba del algodón: si el criterio se puede escribir sin nombrar ninguna tecnología, es un requisito. Si necesita nombrarla, es diseño.

Es un comando iterativo: puedes lanzarlo varias veces para refinar, y respeta lo que edites a mano. Si los requisitos salen genéricos, casi siempre falta steering.

/kiro-spec-design user-auth-oauth -y

Traduce el QUÉ al CÓMO. El -y aprueba los requisitos de la fase anterior; sin él, el comando se para.

Produce design.md con:

• La frontera, primero de todo: qué posee esta especificación, qué no posee y de qué dependencias puede tirar.
• Componentes e interfaces con tipado explícito.
• Diagramas cuando la arquitectura lo pide.
• Plan de ficheros: rutas concretas, cuáles se crean y cuáles se modifican, una responsabilidad por fichero. De aquí salen las fronteras de las tareas del paso siguiente, así que un plan vago produce una implementación vaga.
• Estrategia de pruebas derivada de los criterios de aceptación concretos. Nada de «probar que el login funciona»: qué se verifica y por qué importa.

Antes de escribir nada investiga: en funcionalidades nuevas busca patrones de arquitectura y verifica versiones de dependencias; en extensiones recorre el código existente buscando los patrones que ya se usan.

Si al revisar el diseño aparece un hueco real en los requisitos, se para y te manda de vuelta en lugar de taparlo aquí.

/kiro-spec-tasks user-auth-oauth -y

Convierte el diseño en una lista de tareas ejecutables. El -y aprueba el diseño de la fase anterior.

Produce tasks.md. Cómo son las tareas:

• De 1 a 3 horas cada una. Ni «implementar la autenticación» ni «crear el fichero».
• Numeradas: 1., 2. son cabeceras de grupo; 1.1, 1.2 son lo que realmente se ejecuta.
• Con entregable verificable: un fichero, un endpoint, un componente. Cada tarea dice cómo se ve que está hecha, en términos observables.
• Anotadas con la parte del sistema a la que pertenecen y con sus dependencias.
• Sin prerrequisitos implícitos: si una tarea necesita un runtime o un fichero de configuración, montar eso es una tarea previa explícita.

Antes de escribir tasks.md comprueba que cada requisito está en alguna tarea y que cada componente del diseño está representado. Al terminar muestra un resumen y pregunta si apruebas.

Es la última oportunidad de detectar un problema de diseño antes de que se convierta en código.

/kiro-impl user-auth-oauth

Ejecuta las tareas aprobadas. Es donde por fin se escribe código. No necesita -y: las tareas se aprobaron al final de /kiro-spec-tasks.

Produce código y commits, trabajando una tarea por iteración:

1. Programa con TDD: primero la prueba que falla, luego el código que la pasa.
2. Revisa el resultado de forma independiente: ejecuta git diff, lanza las pruebas y comprueba que no se ha salido de la frontera de la tarea.
3. Marca la tarea como hecha en tasks.md y hace commit solo de los ficheros de esa tarea —nunca git add -A— con el mensaje feat(<funcionalidad>): <tarea>.

Que sea una tarea por iteración es lo que hace que /kiro-impl sea seguro de relanzar si se interrumpe: al reanudar relee tasks.md y sigue por donde iba.

• Repositorio de cc-sdd
• Spec-Driven Guide — la metodología completa
• Kiro IDE