Diferencias

Muestra las diferencias entre dos versiones de la página.

--- cursos:sdd:19-kiro [2026/11/05 22:22] – borrado - editor externo (Fecha desconocida) 127.0.0.1
+++ cursos:sdd:19-kiro [2026/11/06 00:30] (actual) – Lorenzo
@@ Línea 1: / Línea 1: @@
+====== 19. Kiro ======
+[[https://kiro.dev|Kiro]] es el agente de AWS (IDE y CLI) 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 fuera de Kiro con **cc-sdd**. No es de AWS: es un proyecto de terceros, creado por un desarrollador independiente ([[https://github.com/gotalab|gotalab]]), para poder usar las //skills// de Kiro sin depender de AWS. Se instala con npm dentro del agente que ya estés usando y reproduce las mismas fases y los mismos documentos, así que las specs son compatibles entre los dos.
+^              ^ Kiro                                                                                  ^ cc-sdd                                                                 ^
+^ Qué es       | Un agente completo de AWS: IDE (también CLI), orquestación de agentes, //skills//, //hooks// | Solo la metodología: //skills// y comandos                               |
+^ Modelos      | Los que ofrece su servicio, con cuenta de Kiro (no hace falta de AWS) y créditos       | Los de tu agente: con OpenCode, cualquier proveedor o un modelo local    |
+^ Dónde se usa | Kiro IDE o Kiro CLI                                                                    | En tu agente: OpenCode, Claude Code, Codex, Cursor...                    |
+**En este tema, «Kiro» significa cc-sdd.**
+  * Proyecto: [[https://github.com/gotalab/cc-sdd|github.com/gotalab/cc-sdd]]
+----
+===== 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/
+│   └── ..... Hay más skills
+├── .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/
+│   └── ..... Hay más skills
+├── .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]]