el taller de Rob

← Todas las entradasTerminadoUna pieza pulida. Editada, probada, entregada.

Sudoku maya inclusivo en una tarde: construyendo con Kiro en AWS México

Rob MonteroInclusión

En resumen: Juega aquí: https://sudoku.robs.ws / Código: github.com/talacha/kiro-sudoku

El jueves 1 de octubre, AI Tinkerers Mexico City organizó "El Fantasma en la Máquina", un taller práctico con Kiro —el IDE con capacidades de agente de Amazon— en las oficinas de AWS México en Lomas de Chapultepec. El evento contó con el patrocinio de Kiro y AWS México, tuvo un cupo limitado a 40 personas y se desarrolló de 16:00 a 20:00 horas.

A las 19:54 horas se realizó la última integración (*merge*) en el repositorio de mi proyecto: un juego de Sudoku contenido en un único archivo HTML de 2.408 líneas, jugable en cinco idiomas (incluyendo maya yucateco con numeración de puntos y barras), además de la configuración de Terraform para desplegarlo desde un *bucket* privado de S3 a través de CloudFront. Este artículo describe el taller, el contenido del repositorio y los aspectos que puliría antes de dar el proyecto por terminado.

El taller

No se trató de una demostración de producto. Manuel Quijano Gaviria, arquitecto sénior de soluciones en AWS México, impartió el taller oficial de AWS Kiro, y cada participante desarrolló una aplicación en su propio entorno. La organización estuvo a cargo de Christopher Martinez, líder del capítulo de AI Tinkerers en Ciudad de México. Los asistentes recibieron créditos de Kiro para continuar desarrollando proyectos.

Lo que Kiro aporta al desarrollo

El flujo de trabajo de especificación de Kiro transforma una solicitud en tres archivos: `requirements.md` (con historias de usuario y criterios de aceptación), `design.md` (con la arquitectura y diagramas de secuencia) y `tasks.md` (con tareas de implementación específicas cuyo estado se monitorea a medida que el agente las ejecuta). Las tareas independientes pueden procesarse en paralelo. Los *hooks* del agente son archivos JSON ubicados en `.kiro/hooks` que se activan ante eventos como guardar un archivo, llamar a una herramienta o finalizar una sesión; por ejemplo, el caso estándar de la documentación ejecuta `eslint --fix` cada vez que el agente guarda un archivo TypeScript. Kiro Crew representa la vertiente persistente del producto: una pasarela (*Gateway*) que conserva sesiones, memoria, programaciones y puntos de control de tareas incluso tras reinicios; cuenta con un panel de control web y permite el acceso desde la aplicación de escritorio, la CLI y herramientas de chat como Slack. La herramienta `kiro-cli` puede conectarse a una pasarela en ejecución y retomar el trabajo desde una terminal.

El repositorio incluye un registro de dicha configuración en `kirocrew/connect.sh`, un script de incorporación de un solo comando diseñado para ejecutarse desde el servidor VS Code del taller. Este script instala el plugin SSM Session Manager, lee las salidas de una pila CloudFormation de `kirocrew-deployment`, ejecuta `kiro-cli login --use-device-flow` en el host EC2 mediante una sesión SSM (para que cada persona inicie sesión con su propia cuenta de Kiro), reinicia la pasarela y genera un token para el panel de control. El resultado final es una URL única que permite superar la barrera de acceso de CloudFront e iniciar sesión simultáneamente. Aunque la documentación de Crew aborda el uso de systemd, Docker, SSH y túneles HTTPS, este script sitúa el panel de control tras CloudFront, permitiendo así que el host distribuya enlaces de inicio de sesión a otros participantes.

El juego: un único archivo, sin dependencias.

El marcado, los estilos y la lógica residen en `sudoku.html`. No requiere pasos de compilación ni manifiestos de paquetes: basta con abrir el archivo o servir la carpeta mediante `python3 -m http.server`.

La generación del rompecabezas comienza rellenando las tres cajas diagonales de 3×3 con dígitos aleatorios (al no compartir fila, columna ni caja, cualquier disposición es válida); a continuación, se completa la cuadrícula utilizando un algoritmo de *backtracking* aleatorizado y se eliminan celdas en orden aleatorio. Una eliminación solo se mantiene si el contador de soluciones —que se detiene en cuanto encuentra una segunda solución— sigue detectando exactamente una única solución. El nivel de dificultad se determina según el número de pistas iniciales: de 36 a 40 para el nivel fácil, de 30 a 35 para el medio y de 25 a 29 para el difícil. Una verificación posterior al desarrollo permitió extraer el generador y ejecutar 300 rompecabezas por nivel de dificultad en Node 22. Los 900 tenían exactamente una solución; cada solución era una cuadrícula válida coherente con sus valores iniciales, y el número de valores iniciales de cada uno se ajustaba al rango establecido. El tiempo medio de generación fue de 1,8 ms para el nivel fácil, 7,4 ms para el medio y 80 ms para el difícil.

Las funciones de juego abarcan lo que espera un jugador habitual de Sudoku: notas (marcas de lápiz) que se eliminan automáticamente de las celdas correspondientes al colocar un dígito, resaltado de conflictos en tiempo real (filas, columnas y cajas), 20 niveles de deshacer, un temporizador que se pausa al ocultar la pestaña, contador de errores y porcentaje de completado, recuento de dígitos en el teclado numérico (deshabilitando el dígito al llegar a 9/9) y guardado automático en `localStorage` para reanudar la partida tras recargar la página.

Hay varios detalles que no figuran en el archivo README. El sonido se sintetiza mediante la Web Audio API, sin utilizar archivos de audio: tonos cortos de oscilador para colocar, borrar y anotar; un tono doble para indicar conflictos; un arpegio pentatónico al completar una fila, columna o caja (con el tono más agudo por cada grupo adicional completado en el mismo movimiento); y un acorde de Do mayor al ganar, todo ello con una limitación de ejecución de 25 ms y una opción de silencio persistente. Al completar un grupo, se activa una animación de onda escalonada mediante la Web Animations API. Los colores se definen como tokens OKLCH, adaptándose a los temas del sistema, claro y oscuro.

La accesibilidad se tuvo en cuenta desde el primer *commit*: una cuadrícula ARIA con etiquetas por celda, una región activa discreta (*polite live region*) para anuncios, control total mediante teclado (flechas, teclas 1–9, N para notas, Ctrl/Cmd+Z, Esc para pausar), áreas táctiles de 44×44 px y compatibilidad con las preferencias `prefers-color-scheme` y `prefers-reduced-motion`.

Cinco idiomas y numerales mayas

La implementación de la localización añadió inglés, español, quechua sureño (runa simi), náhuatl central y maya yucateco. Las cadenas de texto residen en un registro de internacionalización (I18N) único, organizado mediante códigos BCP-47. Añadir un idioma requiere una sola entrada; si faltan claves, el sistema recurre al inglés, y tanto el selector como el atributo `lang` de HTML, las etiquetas ARIA, los anuncios y los cuadros de diálogo se actualizan en consecuencia. El idioma inicial se determina según la configuración del navegador, y la elección del usuario se mantiene persistente.

Una decisión más interesante es la relativa a los números. El estado del rompecabezas utiliza siempre números enteros del 1 al 9; solo la representación visual y la locución varían según el idioma. El maya posee su propio sistema de numeración escrita; por ello, en maya yucateco, cada dígito se representa mediante una notación de puntos y barras construida con elementos `span` del DOM y CSS, sin depender de fuentes tipográficas específicas:

const bars = Math.floor(n / 5); // cada barra = 5; const dots = n % 5; // de 1 a 4 puntos, dibujados sobre las barras

El numeral gráfico permanece oculto para los lectores de pantalla, los cuales reproducen en su lugar la palabra correspondiente en maya (*jun*, *ka'*, *óox*, etc.). El quechua y el náhuatl conservan los dígitos occidentales en la cuadrícula, pero utilizan sus respectivos nombres numéricos para las etiquetas ARIA (*huk*, *iskay*, *kimsa*; *cē*, *ōme*, *ēyi*). Los comentarios del código explican la razón: ni los *quipus* incas ni los pictogramas de base 20 del náhuatl cuentan con un equivalente compacto para los glifos del 1 al 9.

Infraestructura: S3 privado tras CloudFront

La configuración de Terraform despliega el archivo único en un *bucket* que bloquea todas las formas de acceso público, impone la propiedad del objeto por parte del propietario del *bucket* (deshabilitando las ACL), activa el versionado y cifra los datos mediante SSE-S3 utilizando una clave del *bucket*. El nombre del *bucket* incluye un sufijo aleatorio para garantizar su unicidad global sin necesidad de coordinación previa; además, el ETag del objeto corresponde al hash MD5 del archivo, de modo que cualquier modificación en `sudoku.html` provoca una nueva subida al ejecutar la siguiente operación de despliegue (*apply*). CloudFront accede al bucket mediante *Origin Access Control* (Control de acceso al origen), que firma cada solicitud al origen con SigV4 y sustituye a la antigua *Origin Access Identity* (Identidad de acceso al origen). La política del bucket concede el permiso `s3:GetObject` a la entidad principal del servicio CloudFront solo cuando `AWS:SourceArn` coincide con esta distribución:

`condition { test = "StringEquals" variable = "AWS:SourceArn" values ​​= [aws_cloudfront_distribution.site.arn]}`

La distribución redirige HTTP a HTTPS, utiliza la política gestionada *CachingOptimized* con compresión, sirve contenido mediante IPv6, limita la cobertura de borde a `PriceClass_100` y asigna las respuestas 403 y 404 a la aplicación. Las variables de entrada se validan (una expresión regular para `project_name`, una lista de valores permitidos para `price_class`) y las etiquetas predeterminadas (`default_tags`) marcan cada recurso con `Project` y `ManagedBy`.

El *commit* también incluye dos diagramas Mermaid de la arquitectura desplegada: una versión de arquitectura con iconos de servicios de AWS y un diagrama de flujo alternativo para visualizadores que no admiten paquetes de iconos. Ambos tienen fondo transparente e incluyen instrucciones para importarlos en draw.io. El diagrama de flujo etiqueta el ID de la distribución activa.

Aspectos que ajustaría

Confirmar (*commit*) los artefactos de Kiro. El repositorio carece de directorio `.kiro`, por lo que las especificaciones, la configuración de control (*steering*) y los *hooks* que sustentan la compilación no están bajo control de versiones. En un flujo de trabajo basado en especificaciones, la especificación es lo primero que lee un revisor.

Añadir las pruebas enseñadas en el taller. Los invariantes del generador (exactamente una solución, pistas iniciales dentro del rango de dificultad, pistas coherentes con la solución) se corresponden directamente con pruebas basadas en propiedades (*property-based tests*), y la comprobación de los 900 rompecabezas mencionada anteriormente debería integrarse en la CI utilizando una biblioteca como `fast-check`.

Clasificar la dificultad según la técnica utilizada. El número de pistas es un indicador poco fiable: un rompecabezas con 28 pistas iniciales puede resolverse simplemente mediante técnicas de "únicos desnudos" (*naked singles*) y "únicos ocultos" (*hidden singles*). Clasificarlo según la técnica más compleja requerida por un solucionador lógico haría que la categoría "Difícil" realmente implicara dificultad.

Corregir la desactualización del archivo README. No menciona la localización, el sonido, los temas ni Terraform, y su árbol de proyecto es anterior a la creación de la carpeta de Terraform.

Reforzar la seguridad en el borde (*edge*). Añade una política de cabeceras de respuesta para CSP y HSTS, un dominio personalizado con certificado ACM, registros de acceso, un backend de estado remoto y un paso de despliegue que ejecute la invalidación de CloudFront en lugar de dejarla como un comando manual.

Solicita una revisión por parte de hablantes nativos de las cadenas de texto en quechua, náhuatl y maya antes de lanzar estos idiomas más allá de la fase de demostración.

Conclusiones

Dos horas de tiempo de construcción dieron como resultado una aplicación accesible y multilingüe, alojada bajo el principio de privilegios mínimos. La restricción de archivo único facilitó gran parte de este trabajo: al no haber paso de compilación, cada cambio realizado por el agente podía desplegarse inmediatamente, y el repositorio incluye capturas de pantalla de verificación para seis tamaños de pantalla en ambos temas.

Las carencias siguen un patrón. Lo que se generó más rápido es aquello que resulta fácil de verificar a simple vista. Lo que falta (pruebas, el registro de especificaciones, documentación precisa) es lo que un segundo ingeniero necesitaría antes de confiar en el código. Esos son los aspectos del flujo de trabajo de Kiro en los que se centró el taller, y los próximos elementos que se añadirán a este repositorio.

Enlaces

talacha/kiro-sudoku en GitHub

El Fantasma en la Máquina, AI Tinkerers Mexico City

Kiro specs, agent hooks, y documentación de Kiro Crew