Kiro: buenas prácticas para configurar Steering y Specs en tus proyectos
Aprende a configurar Steering en Kiro utilizando los modos always, fileMatch y manual para definir estándares de desarrollo, optimizar el contexto y mantener consistencia en tus proyectos. Descubre cómo combinar estas reglas con Specs para planificar implementaciones basadas en requisitos.
Kiro: buenas prácticas para configurar Steering y Specs en tus proyectos
Introducción
El uso de inteligencia artificial en el desarrollo de software está cambiando la manera en que diseñamos, implementamos y mantenemos nuestras aplicaciones.
Hoy podemos solicitar a un agente de IA que genere código, automatice tareas o proponga soluciones técnicas. Sin embargo, hay un problema que aparece con frecuencia: la IA no siempre conoce los estándares, convenciones y decisiones arquitectónicas de nuestro proyecto.
Por ejemplo, podemos pedirle que desarrolle un nuevo endpoint para una API, pero ¿cómo sabe qué estructura de carpetas utilizar, qué librerías están permitidas, cómo manejar errores o qué convenciones de seguridad debe respetar?
Podemos repetir estas instrucciones en cada conversación, pero esto resulta poco práctico conforme nuestros proyectos crecen.
Aquí es donde Kiro y sus Steering Files se vuelven especialmente interesantes.
En este artículo veremos cómo organizar el contexto de nuestros proyectos con Steering, cuándo utilizar los modos
always, fileMatch y manual, y cómo combinar estas configuraciones con Specs para desarrollar funcionalidades de manera más estructurada.1. ¿Qué es Kiro?
Kiro es un entorno de desarrollo asistido por agentes de inteligencia artificial que permite trabajar con código, requisitos, diseños técnicos y tareas de implementación.
Una de sus características es el enfoque de desarrollo basado en especificaciones, conocido como Spec-Driven Development.
En lugar de comenzar directamente escribiendo código, podemos estructurar el trabajo en etapas como:
- Requirements: definir qué necesita resolver nuestra funcionalidad.
- Design: establecer cómo vamos a implementar la solución.
- Tasks: dividir el desarrollo en actividades concretas.
Esto permite revisar las decisiones antes de ejecutarlas y mantener documentación relacionada con la implementación.
Sin embargo, para obtener resultados consistentes necesitamos otro componente: Steering.
2. ¿Qué es Steering en Kiro?
Steering es un mecanismo que permite proporcionar contexto e instrucciones persistentes a Kiro mediante archivos Markdown.
Estos archivos pueden definir:
- Estándares de programación.
- Convenciones de nombres.
- Tecnologías y librerías utilizadas.
- Principios de arquitectura.
- Reglas de seguridad.
- Estrategias de pruebas.
- Procedimientos de despliegue.
Los archivos de Steering de un proyecto se almacenan normalmente en:
.kiro/steering/Por ejemplo:
1
2
3
4
5
6
7
8
9
10
11
12
mi-proyecto/
├── .kiro/
│ ├── steering/
│ │ ├── project-context.md
│ │ ├── security-standards.md
│ │ ├── python-standards.md
│ │ ├── terraform-standards.md
│ │ └── deployment-guide.md
│ └── specs/
├── src/
├── infrastructure/
└── README.mdLa ventaja es que no necesitamos repetir todas nuestras reglas en cada solicitud.
Pero existe una consideración importante: no todas las instrucciones necesitan cargarse en todas las interacciones.
Para resolver esto, Kiro ofrece diferentes modos de inclusión.
3. Modos de inclusión de Steering
Los archivos de Steering pueden incluir un encabezado YAML, conocido como front matter, para definir cuándo deben cargarse.
Los tres modos que analizaremos son:
| Modo | Funcionamiento | Cuándo utilizarlo |
|---|---|---|
| always | Se carga automáticamente en todas las interacciones | Reglas generales del proyecto |
| fileMatch | Se carga al trabajar con archivos que coinciden con un patrón | Reglas específicas por tecnología |
| manual | Se incluye cuando el usuario lo solicita explícitamente | Procedimientos especializados |
Una buena organización consiste en proporcionar a Kiro el contexto adecuado para cada tarea, sin sobrecargar todas las conversaciones con instrucciones que no siempre son necesarias.
4. Always: reglas que deben estar presentes
El modo
always permite definir instrucciones que Kiro debe considerar en todas las interacciones del proyecto.Su configuración es:
1
2
3
inclusion: always
Imaginemos que estamos trabajando en un proyecto que utiliza Python, FastAPI y PostgreSQL.
Podemos crear el archivo:
.kiro/steering/project-context.mdCon el siguiente contenido:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
inclusion: always
# Contexto del proyecto
## Stack tecnológico
- Backend: Python con FastAPI.
- Base de datos: PostgreSQL.
- Infraestructura: AWS.
- Infraestructura como código: Terraform.
## Reglas generales
- Respetar la arquitectura existente.
- No introducir dependencias sin justificar su uso.
- No almacenar credenciales en el código.
- Mantener separación entre lógica de negocio y acceso a datos.
- Agregar pruebas para nuevas funcionalidades.
- No modificar archivos fuera del alcance solicitado sin justificación.De esta manera, Kiro dispone de información fundamental sobre el proyecto, independientemente de la funcionalidad en la que estemos trabajando.
Buenas prácticas para Always
Recomiendo reservar este modo para instrucciones verdaderamente globales.
Evitemos incluir documentación demasiado extensa, procedimientos especializados o reglas que solamente aplican a ciertos archivos.
La idea no es proporcionar la mayor cantidad de contexto posible, sino el contexto fundamental que siempre resulta relevante.
5. fileMatch: instrucciones según el archivo
Ahora imaginemos que nuestro proyecto contiene código Python, Terraform y archivos de configuración.
No tendría mucho sentido cargar instrucciones de Terraform cuando estamos desarrollando un endpoint en Python.
Para estos escenarios podemos utilizar
fileMatch.Este modo permite cargar instrucciones cuando los archivos de trabajo coinciden con uno o varios patrones.
Por ejemplo, creamos:
.kiro/steering/terraform-standards.md1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
inclusion: fileMatch
fileMatchPattern: "**/*.tf"
# Estándares de Terraform
- Mantener una estructura modular.
- Utilizar variables para parámetros configurables.
- Aplicar convenciones de nombres y etiquetas.
- Evitar valores sensibles dentro del código.
- Declarar restricciones de versiones de proveedores.
- Revisar el impacto de cambios sobre recursos existentes.
- Ejecutar terraform fmt y terraform validate.
- Revisar terraform plan antes de aplicar cambios.
- No ejecutar terraform apply sin autorización explícita.Cuando Kiro trabaja con archivos Terraform que coinciden con el patrón definido, puede incorporar estas instrucciones específicas.
Podemos hacer lo mismo con Python:
.kiro/steering/python-standards.md1
2
3
4
5
6
7
8
9
10
11
12
13
14
inclusion: fileMatch
fileMatchPattern: "**/*.py"
# Estándares de Python
- Seguir convenciones PEP 8.
- Utilizar type hints cuando corresponda.
- Separar responsabilidades en módulos.
- Manejar excepciones de manera explícita.
- No exponer datos sensibles en logs.
- Escribir pruebas unitarias con pytest.
- Mantener funciones pequeñas y comprensibles.También es posible declarar varios patrones:
1
2
3
4
5
6
inclusion: fileMatch
fileMatchPattern:
- "**/*.tf"
- "**/*.tfvars"
Buenas prácticas para fileMatch
- Crear archivos independientes por tecnología o dominio.
- Utilizar patrones que correspondan a la estructura real del repositorio.
- Evitar reglas contradictorias entre diferentes archivos.
- Comprobar que el contexto se activa con los archivos esperados.
- No asumir que un patrón se activará únicamente porque mencionamos una tecnología en el chat.
Este modo resulta especialmente útil en repositorios con múltiples tecnologías.
6. Manual: instrucciones bajo demanda
En algunos proyectos tenemos procedimientos que únicamente necesitamos ejecutar en situaciones específicas.
Por ejemplo:
- Realizar una migración de base de datos.
- Investigar un incidente de producción.
- Revisar una arquitectura antes de desplegar.
- Ejecutar un procedimiento de recuperación.
- Preparar una revisión de seguridad.
Para estos casos podemos utilizar
manual.Creamos el archivo:
.kiro/steering/production-review.md1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
inclusion: manual
# Revisión previa a producción
Antes de proponer un despliegue:
1. Identificar los recursos afectados.
2. Revisar dependencias entre servicios.
3. Evaluar posibles cambios disruptivos.
4. Confirmar compatibilidad con versiones actuales.
5. Revisar permisos IAM involucrados.
6. Verificar pruebas y mecanismos de rollback.
7. Presentar riesgos y medidas de mitigación.
No ejecutar despliegues ni modificar recursos de producción
sin aprobación explícita.Este archivo no necesita cargarse continuamente.
Podemos incluirlo cuando lo requiramos mediante una referencia en el chat:
1
2
3
4
5
6
7
#production-review
Revisa los cambios de infraestructura que estamos
preparando para producción.
Identifica riesgos, dependencias y posibles impactos.
No ejecutes ninguna modificación.Kiro utiliza el contenido del archivo cuando lo referenciamos explícitamente.
¿Por qué resulta útil?
Porque podemos crear procedimientos reutilizables sin convertirlos en instrucciones globales.
Manual permite mantener contexto especializado disponible, pero utilizarlo solamente cuando realmente aporta valor.
7. Cómo organizar Steering en un proyecto real
Una estructura sencilla podría ser:
1
2
3
4
5
6
7
8
9
.kiro/
├── steering/
│ ├── project-context.md # always
│ ├── security-baseline.md # always
│ ├── python-standards.md # fileMatch
│ ├── terraform-standards.md # fileMatch
│ ├── production-review.md # manual
│ └── incident-response.md # manual
└── specs/Para decidir el modo de cada archivo, podemos hacernos tres preguntas:
¿Esta instrucción aplica a todas las tareas del proyecto?
Utilizamos
always.¿Esta instrucción aplica únicamente a determinados archivos o tecnologías?
Utilizamos
fileMatch.¿Esta instrucción corresponde a un procedimiento ocasional?
Utilizamos
manual.Esta separación permite mejorar la relevancia del contexto y mantener las reglas más fáciles de administrar.
Nota: Kiro también documenta el modo
auto, que permite seleccionar contexto mediante descripciones. En este artículo nos concentramos en los tres modos anteriores por su claridad y control explícito. La compatibilidad exacta de las funcionalidades puede variar entre versiones del IDE y CLI.8. Combinando Steering con Specs
Hasta aquí hemos definido cómo proporcionar contexto al agente.
Pero existe otra pregunta:
¿Cómo conseguimos que Kiro utilice nuestras reglas al desarrollar una funcionalidad completa?
Aquí entran los Specs.
Mientras Steering define estándares y convenciones relativamente persistentes, un Spec describe una funcionalidad concreta que queremos construir.
Por ejemplo, podemos solicitar:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Necesito desarrollar una API REST en Python
para administrar solicitudes de despliegue.
La API debe permitir:
- Crear solicitudes.
- Consultar su estado.
- Validar los parámetros recibidos.
- Registrar eventos de auditoría.
Utiliza los estándares existentes del proyecto.
Primero define los requisitos y criterios de aceptación.
Después presenta el diseño técnico.
Finalmente genera las tareas de implementación.En un flujo estándar de Feature Specs, Kiro puede generar documentos como:
1
2
3
4
5
6
7
8
9
10
.kiro/
├── specs/
│ └── deployment-api/
│ ├── requirements.md
│ ├── design.md
│ └── tasks.md
└── steering/
├── project-context.md
├── python-standards.md
└── security-baseline.mdCada documento cumple una función:
requirements.md: describe los requisitos funcionales y criterios de aceptación.
design.md: documenta el diseño técnico y las decisiones de implementación.
tasks.md: organiza el trabajo en tareas que pueden revisarse y ejecutarse.
Steering proporciona las convenciones del proyecto, mientras que Specs organiza el trabajo de una funcionalidad.
Es importante revisar las especificaciones generadas y validar que incorporen los estándares correspondientes antes de autorizar la implementación.
9. Buenas prácticas que recomiendo
Mantener archivos pequeños y especializados
Es preferible tener instrucciones claras por responsabilidad que un documento enorme con reglas mezcladas.
Evitar instrucciones ambiguas
En lugar de indicar:
"Utiliza buenas prácticas de seguridad".
Podemos especificar:
"No almacenar credenciales en el repositorio. Utilizar mecanismos de administración de secretos y evitar registrar tokens en logs".
Tratar Steering como parte del código
Los archivos deberían versionarse, revisarse mediante pull requests y mantenerse alineados con la evolución del proyecto.
No incluir información sensible
No almacenar contraseñas, tokens, llaves privadas ni información confidencial dentro de Steering.
Validar los resultados
Steering ayuda a orientar al agente, pero no reemplaza las pruebas automatizadas, revisiones de código o controles de seguridad.
Mantener el control sobre las operaciones
Para tareas de infraestructura, recomiendo establecer claramente cuáles son las acciones permitidas y cuáles requieren autorización.
Especialmente cuando trabajamos con recursos de producción, bases de datos o infraestructura crítica.
10. Reflexión desde DevOps y SRE
Como profesionales de DevOps y SRE, estamos acostumbrados a definir estándares para construir y operar infraestructura.
Utilizamos módulos Terraform, pipelines de CI/CD, políticas de seguridad, controles de calidad y procedimientos operativos.
Cuando incorporamos agentes de IA al desarrollo, aparece una necesidad similar: establecer reglas claras para que las soluciones generadas sean consistentes con nuestra arquitectura.
Steering permite documentar parte de esas reglas y ponerlas a disposición del agente.
Por su parte, Specs ayuda a estructurar los cambios antes de comenzar la implementación.
La combinación de ambos mecanismos permite adoptar una forma de trabajo más organizada, donde la IA colabora con el equipo dentro de un contexto técnico definido.
Conclusión
Trabajar con agentes de IA no consiste solamente en escribir mejores prompts.
También implica preparar el contexto, establecer estándares y definir cómo queremos desarrollar nuestras soluciones.
Con Kiro podemos organizar ese contexto utilizando Steering y sus diferentes modos de inclusión:
always: reglas generales.fileMatch: instrucciones por tipo de archivo.manual: procedimientos bajo demanda.
Al combinar estas configuraciones con Specs, podemos planificar funcionalidades de forma estructurada y mantener una mejor alineación entre requisitos, diseño e implementación.
La clave no está en agregar más instrucciones, sino en proporcionar el contexto correcto en el momento adecuado.
¿Ya utilizas Steering en tus proyectos con Kiro? ¿Cómo organizas las instrucciones que compartes con tus agentes de IA?
Me gustaría conocer tu experiencia.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article