====== Kiro: comandos SDD ======

[[https://kiro.dev|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: [[https://github.com/gotalab/cc-sdd|github.com/gotalab/cc-sdd]] (v3.0.2, MIT)

----

===== 1. Instalación =====

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

==== 1.1. En Claude Code ====

<code bash>
cd mi-proyecto
npx cc-sdd@latest --claude-skills --lang es
</code>

<code>
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
</code>

==== 1.2. En OpenCode ====

<code bash>
cd mi-proyecto
npx cc-sdd@latest --opencode-skills --lang es
</code>

<code>
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
</code>

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.

----

===== 2. Comandos iniciales en el proyecto =====

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.

<uml>
start
:npx cc-sdd;
:kiro-steering;
repeat
:kiro-spec-init;
:kiro-spec-requirements;
:kiro-spec-design -y;
:kiro-spec-tasks -y;
:kiro-impl;
repeat while (otra funcionalidad?)
stop
</uml>

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''.

^ Paso ^ Comando ^ Resultado ^
| Instalar | ''npx cc-sdd@latest --claude-skills --lang es'' | ''.claude/skills/'', ''.kiro/'' |
| Crear la memoria del proyecto | ''/kiro-steering'' | ''.kiro/steering/'' con tres documentos |

==== 2.1. La memoria del proyecto ====

''/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/'':

^ Fichero ^ Qué recoge ^
| ''product.md'' | Para qué sirve el producto, qué valor aporta, capacidades principales |
| ''tech.md'' | Stack tecnológico, frameworks, decisiones técnicas y restricciones |
| ''structure.md'' | Organización de directorios, patrones de arquitectura, convenciones de nombres |

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.

----

===== 3. Creación de una nueva especificación =====

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

==== 3.1. Las cinco fases ====

^ Fase ^ Comando ^ Documento que produce ^
| Inicializar | ''/kiro-spec-init <descripción>'' | ''spec.json'' |
| Requisitos (el QUÉ) | ''/kiro-spec-requirements <nombre>'' | ''requirements.md'' |
| Diseño (el CÓMO) | ''/kiro-spec-design <nombre> -y'' | ''design.md'' |
| Tareas | ''/kiro-spec-tasks <nombre> -y'' | ''tasks.md'' |
| Implementación | ''/kiro-impl <nombre>'' | **código** y //commits// |

Los documentos viven juntos, uno por funcionalidad:

<code>
.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
</code>

==== 3.2. Entre fase y fase está el humano ====

''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á:

<code>
Requirements not yet approved. Approval required before design generation.
</code>

<note important>**Hay que pasar ''-y'' en dos de los cinco comandos.** ''/kiro-spec-requirements'' y ''/kiro-spec-design'' generan su documento pero **no** preguntan si lo apruebas, así que la aprobación la registra el comando siguiente con ''-y''. ''/kiro-spec-tasks'' sí pregunta al terminar, y por eso ''/kiro-impl'' no necesita nada.</note>

^ Comando ^ ¿Necesita ''-y''? ^ Qué aprueba ese ''-y'' ^
| ''/kiro-spec-init'' | No | — |
| ''/kiro-spec-requirements'' | No | — |
| ''/kiro-spec-design'' | **Sí** | los **requisitos** de la fase anterior |
| ''/kiro-spec-tasks'' | **Sí** | el **diseño** de la fase anterior |
| ''/kiro-impl'' | No | las tareas ya quedaron aprobadas al final de ''/kiro-spec-tasks'' |

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.

==== 3.3. Una funcionalidad de principio a fin ====

<code>
/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
</code>

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

----

===== 4. Referencia de comandos =====

==== 4.1. /kiro-steering ====

<code>
/kiro-steering
</code>

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.

==== 4.2. /kiro-spec-init ====

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

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

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.

==== 4.3. /kiro-spec-requirements ====

<code>
/kiro-spec-requirements user-auth-oauth
</code>

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.

=== Formato EARS ===

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

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

Un fragmento del documento resultante:

<code>
### 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
</code>

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

=== Requisitos son el QUÉ, no el CÓMO ===

Es la regla que más cuesta respetar:

^ Sí va en requisitos ^ No: eso es diseño ^
| Alcance: qué entra y qué queda fuera | Elección de stack (base de datos, //framework//, lenguaje) |
| Comportamiento visible: «cuando pasa X, qué ve el usuario» | Patrones de arquitectura |
| Reglas de negocio y casos límite | Diseño de la API, modelos de datos, componentes internos |
| Tiempos de respuesta, disponibilidad, nivel de seguridad | Cómo se consiguen: caché, escalado |

**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//.

==== 4.4. /kiro-spec-design ====

<code>
/kiro-spec-design user-auth-oauth -y
</code>

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í.

==== 4.5. /kiro-spec-tasks ====

<code>
/kiro-spec-tasks user-auth-oauth -y
</code>

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.

==== 4.6. /kiro-impl ====

<code>
/kiro-impl user-auth-oauth
</code>

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**:

  - Programa con TDD: primero la prueba que falla, luego el código que la pasa.
  - 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.
  - 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.

<note important>''/kiro-impl'' escribe código y hace //commits// sin preguntar tarea a tarea. Lánzalo en una rama propia y con el árbol de trabajo limpio.</note>

----

===== 5. Enlaces =====

  * [[https://github.com/gotalab/cc-sdd|Repositorio de cc-sdd]]
  * [[https://github.com/gotalab/cc-sdd/blob/main/docs/guides/spec-driven.md|Spec-Driven Guide]] — la metodología completa
  * [[https://kiro.dev|Kiro IDE]]