Diferencias

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

--- cursos:sdd:11-kiro [2026/09/14 22:24] – Nueva pagina: comandos SDD de Kiro (cc-sdd) - instalacion en Claude Code y OpenCode, steering, spec-init, spec-requirements, spec-design, spec-tasks e impl claude
+++ cursos:sdd:11-kiro [2026/09/14 23:22] (actual) – Diagrama del flujo con PlantUML en lugar de mermaid claude
@@ Línea 3: / Línea 3: @@
 [[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 el conjunto de //skills// y comandos de Kiro dentro del agente que ya estés usando (Claude Code, OpenCode, Codex, Cursor...). Es un proyecto independiente de terceros, no un producto de AWS —el IDE es cerrado—, pero reproduce las mismas fases y los mismos documentos, y las especificaciones son compatibles y portables entre los dos.
+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.** Todo lo que sigue se ejecuta en la terminal.
+**En este tema, «Kiro» significa cc-sdd.**
-  * Proyecto: [[https://github.com/gotalab/cc-sdd|github.com/gotalab/cc-sdd]]
+  * Proyecto: [[https://github.com/gotalab/cc-sdd|github.com/gotalab/cc-sdd]] (v3.0.2, MIT)
-  * Paquete: [[https://www.npmjs.com/package/cc-sdd|npm: cc-sdd]] (v3.0.2, MIT)
 ----
@@ Línea 14: / Línea 13: @@
 ===== 1. Instalación =====
-Requisitos: **Node.js** (para poder usar ''npx'') y ejecutar el comando **en la raíz del proyecto**, porque instala ficheros dentro de él.
+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 ====
-Es el destino por defecto, así que basta con:
 <code bash>
 cd mi-proyecto
-npx cc-sdd@latest
+npx cc-sdd@latest --claude-skills --lang es
 </code>
-Para elegir idioma y ser explícito con el agente:
+<code>
+mi-proyecto/
-<code bash>
+├── .claude/skills/              # las skills de Kiro
-npx cc-sdd@latest --claude-skills --lang es
+│   ├── 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>
-Esto deja en el proyecto:
-  * ''.claude/skills/'' — las 17 //skills// ''kiro-*''
-  * ''.kiro/'' — plantillas, //steering// y especificaciones
-  * ''CLAUDE.md'' — configuración del proyecto para el agente
 ==== 1.2. En OpenCode ====
@@ Línea 44: / Línea 45: @@
 </code>
-Esto deja en el proyecto:
+<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>
-  * ''.opencode/skills/'' — las mismas 17 //skills//
+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.
-  * ''.kiro/'' — plantillas, //steering// y especificaciones
-  * ''AGENTS.md'' — configuración del proyecto para el agente
-<note>El soporte de OpenCode está marcado como **beta**. No significa que falten comandos —las 17 //skills// y las plantillas son idénticas en todas las plataformas—, sino que la integración concreta (lanzamiento de subagentes, carga de ''SKILL.md'') está menos rodada que en Claude Code y Codex.</note>
+----
-==== 1.3. Otros agentes y opciones ====
+===== 2. Comandos iniciales en el proyecto =====
-^ Agente ^ Opción ^ Estado ^
+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.
-| Claude Code | ''--claude-skills'' (por defecto) | Estable |
-| Codex | ''--codex-skills'' | Estable |
-| Cursor | ''--cursor-skills'' | Beta |
-| GitHub Copilot | ''--copilot-skills'' | Beta |
-| Windsurf | ''--windsurf-skills'' | Beta |
-| OpenCode | ''--opencode-skills'' | Beta |
-| Gemini CLI | ''--gemini-skills'' | Beta |
-| Antigravity | ''--antigravity'' | Beta experimental |
-Opciones útiles:
+<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>
-<code bash>
+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''.
-npx cc-sdd@latest --lang es        # idioma de los documentos (en, es, ja, zh-TW, pt, de, fr...)
-npx cc-sdd@latest --dry-run        # ver qué ficheros tocaría, sin escribir nada
-npx cc-sdd@latest --kiro-dir docs  # usar otro directorio en lugar de .kiro
-</code>
-Conviene lanzar primero ''--dry-run'' sobre un proyecto que ya tenga contenido, para ver qué se va a crear o sobrescribir.
+^ 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 |
-==== 1.4. Estructura resultante ====
+==== 2.1. La memoria del proyecto ====
-<code>
+''/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/'':
-mi-proyecto/
-├── .claude/skills/          # (o .opencode/skills/) las 17 skills kiro-*
-├── .kiro/
-│   ├── settings/templates/  # plantillas de requirements, design, tasks, steering
-│   ├── settings/rules/      # reglas y criterios de generación
-│   ├── steering/            # memoria del proyecto  <- la crea /kiro-steering
-│   └── specs/               # una carpeta por funcionalidad <- la crea /kiro-spec-init
-└── CLAUDE.md                # o AGENTS.md
-</code>
-----
+^ 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 |
-===== 2. Los dos ciclos: qué se hace una vez y qué se repite =====
+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.
-Antes de ver los comandos uno a uno conviene tener el mapa, porque cc-sdd tiene **dos ritmos distintos** y es fácil confundirlos.
+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.
-==== 2.1. Pasos iniciales: una sola vez por proyecto ====
+----
-^ # ^ Paso ^ Comando ^ Deja en el proyecto ^
-| 1 | Instalar las //skills// | ''npx cc-sdd@latest --claude-skills --lang es'' | ''.claude/skills/'', ''.kiro/settings/'', ''CLAUDE.md'' |
-| 2 | Crear la memoria del proyecto | ''/kiro-steering'' | ''.kiro/steering/product.md'', ''tech.md'', ''structure.md'' |
-| 3 | //Opcional//: conocimiento de dominio | ''/kiro-steering-custom'' | ''.kiro/steering/api-standards.md'', ''testing.md''... |
-Terminado esto, el proyecto ya «sabe de sí mismo»: cualquier comando posterior arranca leyendo ese //steering//.
+===== 3. Creación de una nueva especificación =====
-==== 2.2. Pasos por cada nueva especificación ====
+Esto es lo que se repite **una vez por cada funcionalidad** que quieras construir.
-Esto es lo que se repite **una vez por cada funcionalidad** que quieras construir:
+==== 3.1. Las cinco fases ====
-^ # ^ Fase ^ Comando ^ Documento que produce ^
+^ Fase ^ Comando ^ Documento que produce ^
-| 1 | //Opcional//: enrutar la idea | ''/kiro-discovery <idea>'' | ''brief.md'' (y ''roadmap.md'') |
+| Inicializar | ''/kiro-spec-init <descripción>'' | ''spec.json'' |
-| 2 | Inicializar | ''/kiro-spec-init <descripción>'' | ''spec.json'' + ''requirements.md'' vacío |
+| Requisitos (el QUÉ) | ''/kiro-spec-requirements <nombre>'' | ''requirements.md'' |
-| 3 | Requisitos (QUÉ) | ''/kiro-spec-requirements <nombre>'' | ''requirements.md'' en formato EARS |
+| Diseño (el CÓMO) | ''/kiro-spec-design <nombre> -y'' | ''design.md'' |
-| 4 | //Opcional//: hueco con lo existente | ''/kiro-validate-gap <nombre>'' | ''research.md'' |
+| Tareas | ''/kiro-spec-tasks <nombre> -y'' | ''tasks.md'' |
-| 5 | Diseño (CÓMO) | ''/kiro-spec-design <nombre>'' | ''design.md'' (+ ''research.md'') |
+| Implementación | ''/kiro-impl <nombre>'' | **código** y //commits// |
-| 6 | //Opcional//: revisar el diseño | ''/kiro-validate-design <nombre>'' | — |
-| 7 | Tareas | ''/kiro-spec-tasks <nombre>'' | ''tasks.md'' |
-| 8 | Implementación | ''/kiro-impl <nombre>'' | **código** + //commits// |
-| 9 | //Opcional//: validar la funcionalidad | ''/kiro-validate-impl <nombre>'' | veredicto GO / NO-GO |
-Los cuatro documentos viven juntos, uno por funcionalidad:
+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É, en EARS
+├── requirements.md    # QUÉ
-├── design.md          # CÓMO, con diagramas y plan de ficheros
+├── design.md          # CÓMO
-├── research.md        # hallazgos de la investigación (si hubo)
+└── tasks.md           # tareas
-└── tasks.md           # tareas, fronteras y dependencias
 </code>
-==== 2.3. Dónde está el humano ====
+==== 3.2. Entre fase y fase está el humano ====
-Entre fase y fase hay una **puerta de aprobación**. ''spec.json'' guarda, para cada fase, si está ''generated'' y si está ''approved''; un comando se niega a arrancar si la fase anterior no está aprobada:
+''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>
@@ Línea 136: / Línea 135: @@
 </code>
-Aprobar consiste en **leer el documento y lanzar el comando siguiente**. La opción ''-y'' aprueba la fase anterior automáticamente y se salta esa lectura: es cómoda para prototipos y peligrosa para lo demás, porque la revisión humana entre fases es justo lo que distingue este método de pedirle a la IA que «hazme el login».
+<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>
-<note>**Una especificación = una funcionalidad.** Si la idea es demasiado grande, no la metas en una sola //spec//: usa ''/kiro-discovery'' para que la descomponga, o ''/kiro-spec-batch'' para generar varias especificaciones coordinadas a partir de una //roadmap//.</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'' |
-==== 2.4. Mantenimiento ====
+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-steering'' se vuelve a lanzar** de vez en cuando (modo //sync//) para que la memoria del proyecto no se quede desfasada respecto al código que ya se ha escrito.
+==== 3.3. Una funcionalidad de principio a fin ====
-  * Las especificaciones **no se borran** al terminar: quedan como documentación de por qué el código es como es, y ''/kiro-validate-gap'' las usa para saber qué hay ya implementado.
+<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.
 ----
-===== 3. Inicializar el proyecto: /kiro-steering =====
+===== 4. Referencia de comandos =====
-El //steering// es la **memoria persistente del proyecto**: lo que todos los demás comandos leen antes de hacer nada. Es el primer comando que hay que ejecutar, sobre todo en un proyecto que ya tiene código.
+==== 4.1. /kiro-steering ====
 <code>
@@ Línea 155: / Línea 168: @@
 </code>
-No lleva argumentos. Analiza el repositorio y genera tres documentos en ''.kiro/steering/'':
+Crea o actualiza la memoria del proyecto. No lleva argumentos.
-^ Fichero ^ Qué recoge ^
+**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).
-| ''product.md'' | Contexto de negocio: 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 e imports |
-Funciona en dos modos, y decide solo cuál aplica mirando si ya existen los tres ficheros:
+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.
-  * **Bootstrap** (primera vez): lee README, ''package.json'', configuración, dependencias y árbol de directorios, y redacta los tres documentos a partir de las plantillas.
+  * **Captura patrones, no inventarios.** «Así se nombran los servicios aquí», no una lista de los 200 ficheros del proyecto.
-  * **Sync** (mantenimiento): compara el //steering// existente con el código y reporta la deriva (//code drift//), por ejemplo «''tech.md'': React 18 → 19».
+  * **Relánzalo de vez en cuando** para que no se quede desfasado respecto al código ya escrito.
-Reglas importantes:
+==== 4.2. /kiro-spec-init ====
-  * **Lo que edites a mano se respeta.** Las actualizaciones son aditivas: sync no pisa tus personalizaciones.
-  * **Captura patrones, no inventarios.** El objetivo es «así se nombran los servicios aquí», no una lista de los 200 ficheros del proyecto. Lo específico de una funcionalidad va en su especificación, no en el //steering//.
-  * **Revisa lo que genera antes de seguir.** El //steering// pasa a ser la fuente de verdad para el agente, así que un error aquí se propaga a todas las especificaciones.
-  * Conviene **re-ejecutarlo periódicamente** para que el contexto no se quede obsoleto.
-Para conocimiento de dominio más específico existe ''/kiro-steering-custom'', que es interactivo y crea documentos adicionales en la misma carpeta a partir de plantillas: ''api-standards.md'', ''testing.md'', ''security.md'', ''database.md'', ''error-handling.md'', ''authentication.md'', ''deployment.md''...
-----
-===== 4. Empezar una especificación: /kiro-spec-init =====
-Crea el esqueleto de la especificación de **una** funcionalidad.
 <code>
-/kiro-spec-init <descripción del proyecto>
+/kiro-spec-init <descripción de la funcionalidad>
 </code>
-Ejemplo:
 <code>
@@ Línea 192: / Línea 187: @@
 </code>
-Qué hace, por pasos:
+Crea el esqueleto de la especificación de **una** funcionalidad.
-  - Genera un **nombre de funcionalidad** único en ''kebab-case'' a partir de la descripción (aquí, ''user-auth-oauth''). Si la descripción es ambigua, propone 2-3 opciones y te deja elegir; si el nombre ya existe, añade un sufijo numérico (''-2'', ''-3'').
+**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 contiene los tres elementos obligatorios: **quién tiene el problema**, **cuál es la situación actual** y **qué debería cambiar**. Si falta alguno, //pregunta// en lugar de rellenarlo con suposiciones propias.
-  - Crea el directorio ''.kiro/specs/<nombre>/''.
-  - Escribe dos ficheros a partir de las plantillas: ''spec.json'' (metadatos: nombre, //timestamp//, idioma, estado de aprobación de cada fase) y ''requirements.md'' (solo el esqueleto con la descripción).
-Salida típica:
+  * 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.
-<code>
+  * Cuanto más concreta sea la descripción —stack, restricciones, requisitos clave—, mejor arranca todo lo demás.
-## Generated Feature Name
-`user-auth-oauth`
-## Created Files
-- ✓ .kiro/specs/user-auth-oauth/spec.json
-- ✓ .kiro/specs/user-auth-oauth/requirements.md
-## Next Step
-/kiro-spec-requirements user-auth-oauth
-</code>
-<note important>''/kiro-spec-init'' **no** escribe los requisitos, ni el diseño, ni las tareas: solo inicializa la estructura. Es deliberado —cada fase se genera en su propio comando, con su propia revisión— y es lo que hace que el comando sea instantáneo.</note>
-Consejos:
-  * Cuanto más **concreta** sea la descripción (stack, restricciones, requisitos clave), mejor sale el nombre y mejor arrancan los requisitos.
-  * Revisa ''spec.json'' después de crearlo, sobre todo el campo de idioma.
-  * En un proyecto existente, ejecuta antes ''/kiro-steering''.
-----
-===== 5. Generar los requisitos: /kiro-spec-requirements =====
-Es el paso siguiente a ''/kiro-spec-init'': convierte la descripción en un documento de requisitos completo y **verificable**.
-<code>
-/kiro-spec-requirements <nombre-funcionalidad>
-</code>
-El argumento es el nombre de la carpeta que creó ''/kiro-spec-init'', no la descripción:
+==== 4.3. /kiro-spec-requirements ====
 <code>
@@ Línea 237: / Línea 201: @@
 </code>
-==== 5.1. Qué hace ====
+Convierte la descripción en un documento de requisitos **verificable**. El argumento es el nombre de la carpeta, no la descripción.
-  - **Carga el contexto**: ''spec.json'' (idioma y metadatos), los tres ficheros de //steering// (''product.md'', ''tech.md'', ''structure.md''), el ''brief.md'' si existe, y la descripción que quedó en ''requirements.md''.
+**Produce** ''requirements.md'' con los criterios de aceptación en formato EARS.
-  - **Investiga en paralelo**, delegando en subagentes para no ensuciar el contexto principal: qué hay ya implementado en el repositorio (en proyectos //brownfield//), investigación de dominio con búsqueda web si hace falta, y el //steering// adicional que sea relevante.
-  - **Redacta un borrador** agrupando la funcionalidad en áreas lógicas, con todos los criterios de aceptación en formato EARS.
-  - **Pasa el borrador por una puerta de revisión** (//review gate//): cobertura, cumplimiento de EARS, ambigüedades y límites de alcance. Corrige y vuelve a revisar, con un máximo de dos pasadas. Si aparece una ambigüedad real, **se para y pregunta** en lugar de inventarse el requisito.
-  - **Escribe ''requirements.md''** solo cuando la revisión pasa, y actualiza ''spec.json'' a ''phase: requirements-generated''.
-==== 5.2. Formato EARS ====
+=== Formato EARS ===
-EARS (//Easy Approach to Requirements Syntax//) es una sintaxis acotada para escribir criterios de aceptación que no se puedan interpretar de dos maneras:
+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>
+WHEN  <disparador>   THE <sistema> SHALL <acción>
-IF    <condición>   THEN THE <sistema> SHALL <acción>
+IF    <condición>    THEN THE <sistema> SHALL <acción>
-WHERE <característica> THE <sistema> SHALL <acción>
 THE <sistema> SHALL <acción>
 </code>
-Un fragmento del ''requirements.md'' resultante:
+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 de Google
+- 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>
-La gracia de EARS es que cada línea es directamente un caso de prueba: hay un disparador, un sujeto y un resultado observable.
+Cada línea es directamente un caso de prueba: hay un disparador, un sujeto y un resultado observable.
-==== 5.3. Requisitos son el QUÉ, no el CÓMO ====
+=== Requisitos son el QUÉ, no el CÓMO ===
-Es la regla que más cuesta respetar. El comando pregunta —y escribe— solo sobre comportamiento observable:
+Es la regla que más cuesta respetar:
 ^ Sí va en requisitos ^ No: eso es diseño ^
-| Alcance funcional: qué entra y qué queda fuera | Elección de stack (base de datos, //framework//, lenguaje) |
+| 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 (monolito, microservicios, eventos) |
+| 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 |
-| Requisitos no funcionales perceptibles: tiempos de respuesta, disponibilidad, nivel de seguridad | Cómo se consiguen: estrategia de caché, escalado |
+| Tiempos de respuesta, disponibilidad, nivel de seguridad | Cómo se consiguen: caché, escalado |
-**Prueba del algodón**: si el criterio de aceptación se puede escribir sin nombrar ninguna tecnología, es un requisito. Si necesita nombrarla, es diseño.
+**Prueba del algodón**: si el criterio se puede escribir sin nombrar ninguna tecnología, es un requisito. Si necesita nombrarla, es diseño.
-==== 5.4. Consejos y problemas frecuentes ====
+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//.
-  * Es un comando **iterativo**: puedes lanzarlo varias veces para refinar, y respeta lo que hayas editado a mano en ''requirements.md''.
+==== 4.4. /kiro-spec-design ====
-  * **Revisa el documento antes de aprobarlo.** El diseño y las tareas se generan a partir de aquí, así que un requisito mal puesto se arrastra hasta el código.
-  * Si los requisitos salen **genéricos**, casi siempre es que falta //steering//: ejecuta ''/kiro-steering'' y vuelve a lanzarlo.
-  * Si da «Spec not found», el nombre no coincide: mira qué carpetas hay en ''.kiro/specs/''.
-  * Las reglas de formato están en ''.kiro/settings/rules/ears-format.md'' y la plantilla del documento en ''.kiro/settings/templates/specs/requirements.md''; ambas se pueden personalizar.
-==== 5.5. Siguiente paso ====
-Con los requisitos aprobados:
 <code>
-/kiro-validate-gap user-auth-oauth    # opcional, solo en proyectos con código existente
+/kiro-spec-design user-auth-oauth -y
-/kiro-spec-design user-auth-oauth     # diseño técnico
-/kiro-spec-design user-auth-oauth -y  # ...aprobando los requisitos automáticamente
 </code>
-La opción ''-y'' salta la confirmación humana de la fase anterior. Cómoda, pero es justo la puerta de control que da sentido al método: úsala solo cuando ya hayas leído el documento.
+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:
-===== 6. El diseño técnico: /kiro-spec-design =====
+  * **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.
-Traduce el QUÉ de los requisitos al CÓMO: arquitectura, componentes, interfaces y plan de ficheros.
+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.
-<code>
-/kiro-spec-design <nombre-funcionalidad> [-y]
-</code>
-==== 6.1. Investigación antes de diseñar ====
-Es el comando más caro de los cuatro, porque antes de escribir nada **clasifica la funcionalidad** y ajusta cuánto investiga:
-^ Tipo de funcionalidad ^ Investigación ^ Qué hace ^
-| Nueva, //greenfield// o compleja | Completa | Busca en la web patrones de arquitectura, verifica APIs y versiones de dependencias, lee documentación oficial y problemas conocidos |
-| Extensión de algo existente | Ligera | Se centra en los puntos de integración: recorre el código con //grep// buscando los patrones que ya se usan |
-| Añadido simple (CRUD, una pantalla) | Mínima | Comprobación rápida del patrón y a escribir |
-La investigación se reparte entre **subagentes en paralelo** (uno para el código existente, otro para la búsqueda web) que devuelven un resumen, no datos en bruto, para no ensuciar el contexto principal. Los hallazgos quedan escritos en ''research.md'': qué se investigó, con qué fuentes y qué implicaciones tuvo. Es el registro que permite entender meses después por qué se eligió una librería y no otra.
-==== 6.2. Qué contiene design.md ====
-  * **La frontera, primero de todo** (//boundary-first//): qué posee esta especificación, qué **no** posee, de qué dependencias puede tirar y qué cambios obligarían a revalidar a los de al lado. Es la sección que da sentido a todo lo demás.
-  * **Componentes e interfaces**, con tipado explícito. En TypeScript, prohibido ''any''; en lenguajes dinámicos, anotaciones de tipo y validación en los bordes.
-  * **Diagramas Mermaid** cuando la arquitectura lo pide.
-  * **Plan de ficheros** (//File Structure Plan//): rutas concretas, cuáles se crean y cuáles se modifican, y una responsabilidad clara por fichero. No es decoración: de aquí salen directamente las fronteras de las tareas del paso siguiente, así que un plan de ficheros vago produce una implementación vaga.
-  * **Estrategia de pruebas** derivada de los criterios de aceptación concretos, no de plantillas genéricas. Nada de «probar que el login funciona»: qué se verifica y por qué importa.
-  * **Trazabilidad**: cada componente referencia los IDs numéricos de los requisitos que cubre.
-Igual que los requisitos, el borrador pasa por una **puerta de revisión** (cobertura de requisitos, madurez de la arquitectura, ejecutabilidad) con un máximo de dos pasadas de reparación. Si la revisión destapa un hueco real en los requisitos, **se para y te manda de vuelta a la fase anterior** en lugar de tapar el agujero en el diseño.
-Al terminar: ''phase: design-generated'' y ''approvals.requirements.approved: true''.
-----
-===== 7. Descomponer en tareas: /kiro-spec-tasks =====
+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í.
-Convierte el diseño en una lista de tareas ejecutables.
+==== 4.5. /kiro-spec-tasks ====
 <code>
-/kiro-spec-tasks <nombre-funcionalidad> [-y] [--sequential]
+/kiro-spec-tasks user-auth-oauth -y
 </code>
-==== 7.1. Cómo son las tareas ====
+Convierte el diseño en una lista de tareas ejecutables. El ''-y'' aprueba el diseño de la fase anterior.
-  * **De 1 a 3 horas cada una.** Ni un «implementar la autenticación» ni un «crear el fichero».
+**Produce** ''tasks.md''. Cómo son las tareas:
-  * **Numeradas jerárquicamente**: ''1.'', ''2.'' son cabeceras de grupo; ''1.1'', ''1.2'' son las unidades que realmente se ejecutan.
-  * **Con entregable verificable**: un fichero, un //endpoint//, un componente, una configuración. Cada subtarea incluye al menos una línea que describe **cómo se ve que está hecha**, en términos observables.
-  * **Anotadas**:
-    * ''%%_Boundary: NombreComponente_%%'' — a qué parte del sistema pertenece.
-    * ''%%_Depends: 1.2_%%'' — dependencias no evidentes entre tareas.
-    * ''(P)'' — la tarea se puede ejecutar en paralelo con otras sin riesgo. Con ''--sequential'' no se marca ninguna.
-  * **Sin prerrequisitos implícitos**: si una tarea necesita que exista un //runtime//, un SDK o un fichero de configuración, montar eso es una tarea previa explícita. Nada de dar por hecho el andamiaje.
-  * **Todas conectadas al sistema**: no se permiten tareas huérfanas cuyo resultado no se integre en ninguna parte.
-==== 7.2. La doble revisión ====
+  * **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'' hay dos filtros:
+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**.
-  - **Puerta de revisión del plan**: ¿está cada requisito en alguna tarea? ¿está cada componente del diseño representado? ¿son todas ejecutables y verificables? ¿cuadran las dependencias y las fronteras?
+Es la última oportunidad de detectar un problema de diseño antes de que se convierta en código.
-  - **Revisión independiente del grafo de tareas**: un subagente nuevo, que lee ''requirements.md'' y ''design.md'' por su cuenta en lugar de fiarse del resumen del padre, busca prerrequisitos ocultos, errores de orden, solapamiento de fronteras y tareas demasiado grandes o vagas. Devuelve un veredicto: ''PASS'', ''NEEDS_FIXES'' o ''RETURN_TO_DESIGN''.
-Si sale ''RETURN_TO_DESIGN'', el comando **no escribe ''tasks.md''** y te señala el hueco exacto que hay que arreglar antes. Es la última oportunidad de detectar un problema de diseño antes de que se convierta en código.
+==== 4.6. /kiro-impl ====
-Al final muestra un resumen (cuántas tareas, cuántos requisitos cubiertos, marcas de paralelismo) y **pregunta si apruebas**. Solo entonces marca ''approvals.tasks.approved''.
-----
-===== 8. Implementar: /kiro-impl =====
-Ejecuta las tareas aprobadas. Es donde por fin se escribe código.
 <code>
-/kiro-impl <nombre-funcionalidad>                    # modo autónomo: todas las tareas pendientes
+/kiro-impl user-auth-oauth
-/kiro-impl <nombre-funcionalidad> 1.1,1.2            # modo manual: solo esas tareas
-/kiro-impl <nombre-funcionalidad> --review off       # sin revisión por tarea (no recomendado)
 </code>
-==== 8.1. Antes de empezar ====
+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''.
-  * Comprueba que las tareas están aprobadas en ''spec.json''; si no, se para.
+**Produce** código y //commits//, trabajando **una tarea por iteración**:
-  * **Descubre los comandos de validación del repositorio** mirando, por este orden, ''package.json'' / ''pyproject.toml'' / ''go.mod'' / ''Cargo.toml'', luego ''Makefile'' o ''justfile'', luego los ficheros de CI, luego el README. De ahí saca el conjunto de comandos de test, de //build// y de //smoke test//. Prefiere los que ya usa la automatización del proyecto antes que inventarse una tubería de //shell//.
-  * Anota el estado inicial con ''git status --porcelain'' para no mezclar cambios previos con los suyos.
-==== 8.2. El ciclo por tarea ====
+  - 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>''.
-**Una tarea por iteración**, nunca varias a la vez. En cada iteración vuelve a leer ''tasks.md'' desde cero en lugar de fiarse de lo que recuerda, y al terminar se queda solo con un resumen de una línea. Ese es el truco que permite que una ejecución larga no se degrade, y que ''/kiro-impl'' sea **seguro de relanzar** si se interrumpe.
+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.
-Cada tarea pasa por hasta tres papeles, cada uno en un **subagente con contexto limpio**:
-^ Papel ^ Qué hace ^
-| **Implementador** | Construye su propio //Task Brief// leyendo la especificación y programa con TDD: primero la prueba que falla (RED), luego el código que la pasa (GREEN), detrás de un //feature flag// si el cambio es de comportamiento. Devuelve ''READY_FOR_REVIEW'', ''BLOCKED'' o ''NEEDS_CONTEXT'' |
-| **Revisor** | Pasada independiente: ejecuta ''git diff'' por su cuenta —el código real es la fuente de verdad, no el informe del implementador—, busca TODOs, lanza las pruebas y comprueba que no se ha salido de su frontera. Veredicto: ''APPROVED'' o ''REJECTED'' |
-| **Depurador** | Se lanza si el implementador está bloqueado o si el revisor rechaza dos veces. Recibe **solo el error, no el historial de intentos fallidos** —eso es lo que rompe los bucles de reintento infinito—, investiga la causa raíz (con búsqueda web si hace falta) y entrega un plan de arreglo a un implementador nuevo. Máximo 2 rondas |
-Con la tarea aprobada, antes de cantar victoria aplica ''kiro-verify-completion'': una comprobación con evidencia fresca del estado actual del código. Solo entonces marca la tarea ''[x]'' y hace //commit//.
-==== 8.3. Commits y aprendizajes ====
-  * El //commit// lo hace el proceso padre y es **selectivo**: ''git add'' con las rutas exactas que ha tocado esa tarea, más ''tasks.md''. Nunca ''git add -A'' ni ''git add .''.
-  * Formato del mensaje: ''feat(<nombre-funcionalidad>): <descripción de la tarea>''.
-  * Si una tarea descubre algo transversal («esta librería necesita recompilarse para Electron»), se anota en la sección ''## Implementation Notes'' de ''tasks.md'' y se **inyecta en el //prompt// de las tareas siguientes**. Así el error no se repite quince veces.
-  * Si el depurador se rinde, la tarea queda marcada con ''%%_Blocked: <causa>_%%'' y se pasa a la siguiente, o se para el proceso pidiendo revisión humana.
 <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>
-Terminadas las tareas, ''/kiro-validate-impl <nombre>'' valida la funcionalidad **completa** —integración entre tareas, cobertura de requisitos, alineación con el diseño, evidencia de la //suite// entera— y devuelve ''GO'', ''NO-GO'' o ''MANUAL_VERIFY_REQUIRED''.
 ----
-===== 9. Resumen y comandos auxiliares =====
+===== 5. Enlaces =====
-Una funcionalidad de principio a fin, sobre un proyecto ya inicializado:
-<code>
-/kiro-discovery Álbumes de fotos con subida, etiquetado y compartición
-/kiro-spec-init photo-albums
-/kiro-spec-requirements photo-albums
-/kiro-spec-design photo-albums
-/kiro-spec-tasks photo-albums
-/kiro-impl photo-albums
-/kiro-validate-impl photo-albums
-</code>
-Si no sabes por dónde empezar, ''/kiro-discovery'' analiza la petición y te dice cuál es el siguiente comando: extender una especificación existente, implementar directamente sin //spec//, crear una, o descomponer en varias.
-Comandos de apoyo:
-^ Comando ^ Para qué ^
-| ''/kiro-discovery <idea>'' | Punto de entrada: enruta el trabajo y escribe ''brief.md'' |
-| ''/kiro-spec-batch'' | Genera varias especificaciones en paralelo a partir de una //roadmap//, con revisión cruzada para detectar contradicciones |
-| ''/kiro-validate-gap <nombre>'' | Qué falta respecto a lo ya implementado (proyectos con código existente) |
-| ''/kiro-validate-design <nombre>'' | Revisión interactiva de la calidad del diseño |
-| ''/kiro-validate-impl <nombre>'' | Validación de la funcionalidad completa: GO / NO-GO |
-| ''/kiro-spec-status <nombre>'' | En qué fase está una especificación y qué toca hacer |
-| ''/kiro-steering-custom'' | Documentos de //steering// de dominio |
-Y tres //skills// que no se invocan a mano, pero que conviene conocer porque son las que dan las garantías: ''kiro-review'' (protocolo de revisión adversaria), ''kiro-debug'' (depuración por causa raíz) y ''kiro-verify-completion'' (exigir evidencia fresca antes de dar algo por terminado).
-<note>**Guiones frente a dos puntos.** En las versiones 1.x y 2.x los comandos se llamaban ''/kiro:steering'' y ''/kiro:spec-init'', con dos puntos. Desde la 3.0 el modo recomendado es el de //skills//, con guion: ''/kiro-steering'', ''/kiro-spec-init''. Los comandos con dos puntos siguen funcionando (opciones ''--claude'', ''--opencode''...) pero están **obsoletos**.</note>
-----
-===== 10. Enlaces =====
   * [[https://github.com/gotalab/cc-sdd|Repositorio de cc-sdd]]
-  * [[https://github.com/gotalab/cc-sdd/blob/main/docs/guides/skill-reference.md|Skill Reference]] — referencia del modo //skills// (v3)
-  * [[https://github.com/gotalab/cc-sdd/blob/main/docs/guides/command-reference.md|Command Reference]] — referencia de los comandos ''/kiro:*'' antiguos
   * [[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]]