Cómo dividir los archivos steering de Kiro para que el IDE y la CLI obtengan los correctos (Guía 2026)

La página de steering de Kiro comienza con una tabla de capacidades, y las filas representan todo el diseño. "Workspace steering (.kiro/steering/)" está disponible en el IDE, la CLI, la Web y el Móvil. "Global steering (~/.kiro/steering/)" está disponible en el IDE y la CLI, y marcado como no disponible para Web y Móvil. "Cloud steering managed in Web settings" es solo para Web. "Generate foundation files via UI" es solo para el IDE. "Inclusion modes (always, fileMatch, manual)" está marcado como disponible en los cuatro.

Esa última fila es donde comienza la confusión, porque la nota informativa más abajo en la página la limita: los modos de inclusión no son compatibles actualmente en la CLI, donde todo lo que está en el directorio se carga automáticamente. Por lo tanto, el modelo mental correcto no es "mis reglas me siguen a todas partes". Es más bien: los archivos te siguen, pero la restricción no.

El directorio global tiene su propio límite, escrito con el mismo tono. "On Web, 'Global steering' refers to your local ~/.kiro/steering/ directory, which the cloud sandbox cannot read." La ruta documentada es Configuration Sync: "To reuse personal steering across cloud sessions, upload it through Configuration Sync; the cloud copy then applies to every cloud session."

Hay un cuarto caso que atrapa a quienes han comenzado a construir sus propios agentes. La documentación dice: "When using custom agents, steering files are not automatically included. You must explicitly add them to the agent's resources configuration to load steering context." Un glob como file://.kiro/steering/**/*.md en los resources del agente es lo que los trae de vuelta.

Y un nombre de archivo en particular se excluye por completo de las restricciones. Kiro admite el estándar AGENTS.md, con una advertencia indicada en la página: "AGENTS.md files do not support inclusion modes and are always included." Si mantienes un archivo compartido entre herramientas en la raíz del repositorio, es un archivo siempre activo por definición, sin importar lo disciplinado que hayas sido con el front matter en otros lugares.

Eliminar el front matter y empezar de nuevo. El instinto cuando un archivo condicional se comporta mal es asumir que el YAML es incorrecto. A menudo no lo es. La documentación advierte que "The inclusion configuration must be the first content in the file - no blank lines or content before it", lo cual vale la pena verificar una vez; pero si el archivo funciona en el IDE y no en la CLI, el front matter está bien y la superficie es la variable.

Mover todo a los tres archivos de base (foundation files). product.md, tech.md y structure.md son reales y útiles, y la documentación dice: "These foundation files are included in every interaction by default, forming the baseline of Kiro's project understanding." El modo de fallo es tratar eso como un permiso para consolidar: todo lo que integres se vuelve siempre activo en todas partes, que es exactamente el resultado que intentabas evitar.

Poner preferencias personales en el directorio global y asumir que se trasladan. Se trasladan al IDE y a la CLI. Está documentado que el sandbox en la nube no puede leer ese directorio, por lo que las preferencias dejan de aplicarse silenciosamente en las sesiones web, y nada lo anuncia.

Recortar el directorio hasta que la CLI se comporte bien. Esto funciona, en el sentido de que se cargan menos archivos. También despoja al IDE de la guía condicional que lo hacía bueno. Terminas optimizando una superficie degradando otra.

Asumir que este es el mismo problema que los modos de activación de reglas en otros lugares. Parece similar, pero el fallo es de diferente naturaleza. Cuando una herramienta admite modos de activación en todas partes y una regla aún no se activa, la pregunta es qué modo elegiste, que es el tema tratado en how to choose Windsurf rule trigger modes. Aquí el modo es correcto y la superficie lo ignora.

Paso 1: Dividir el directorio en un nivel siempre activo y un nivel restringido

Toma todo lo que esté en .kiro/steering/ y clasifícalo en dos montones según una pregunta: ¿sería aceptable que esto se cargara en cada tarea, en cada superficie, para siempre?

El montón del "sí" es tu nivel siempre activo: los archivos de base más cualquier cosa genuinamente universal. Las propias descripciones de Kiro son un buen filtro: product.md "Defines your product's purpose, target users, key features, and business objectives," tech.md "Documents your chosen frameworks, libraries, development tools, and technical constraints," y structure.md "Outlines file organization, naming conventions, import patterns, and architectural decisions." Mantén este nivel deliberadamente pequeño, porque en la CLI es el único nivel que existe.

El montón del "no" es tu nivel restringido: convenciones específicas de frameworks, procedimientos de migración, guías de resolución de problemas, cualquier cosa larga. Estos reciben front matter, y aceptas que en la CLI se cargarán de todos modos, que es el punto de evitar que el montón crezca sin límite.

Sigue los consejos de nomenclatura mientras estás en ello. La documentación sugiere nombres que indiquen el alcance, como api-rest-conventions.md, testing-unit-patterns.md y components-form-validation.md, con "One domain per file." Los nombres importan más de lo habitual aquí, porque en las superficies donde todo se carga, el nombre del archivo es la única señal sobre para qué sirve un archivo.

Paso 2: Elegir el modo de inclusión que coincida con cómo debe llegar el archivo

Se documentan cuatro modos, y no son intercambiables.

inclusion: always es el predeterminado y no necesita front matter para comportarse de esa manera. inclusion: fileMatch toma un fileMatchPattern, que acepta un único glob como components/**/*.tsx o un array como ["**/*.ts", "**/*.tsx", "**/tsconfig.*.json"]. inclusion: manual hace que los archivos estén "disponibles bajo demanda al hacerles referencia con #steering-file-name en tus mensajes de chat", y la documentación señala que "Manual steering files also appear as slash commands - type / in chat to see and select them." inclusion: auto requiere dos campos: name ("Identifier for the steering file. Used for display and matching") y description ("When to include this file. Kiro matches this against your requests"), y el archivo se incorpora "when your request matches the description."

Vale la pena seguir los casos de uso documentados en lugar de reinventarlos. Manual es "Best for: Specialized workflows, troubleshooting guides, migration procedures, or context-heavy documentation that's only needed occasionally." Auto es "Best for: Context-heavy guidance that should only load when relevant - like specialized domain knowledge, complex workflows, or detailed reference material that would overwhelm always-on steering."

Un mecanismo más pertenece aquí. En lugar de pegar una especificación en un archivo steering, haz referencia al archivo en vivo con #[[file:<relative_file_name>]]; la documentación ofrece #[[file:api/openapi.yaml]], #[[file:components/ui/button.tsx]] y #[[file:.env.example]] como ejemplos. Un puntero se mantiene actualizado; un pegado comienza a desactualizarse el día que lo escribes. El mismo razonamiento se aplica a delimitar las instrucciones por ruta en lugar de por prosa, como en how to scope Amp instructions to files.

Paso 3: Colocar cada archivo por superficie, luego verificar en la superficie que realmente usas

Ahora decide dónde reside físicamente cada archivo, utilizando la tabla de capacidades en lugar del hábito.

Los estándares del repositorio van en .kiro/steering/ y se confirman (commit). Las preferencias personales van en ~/.kiro/steering/, y la regla de conflicto está documentada: "In case of conflicting instructions between global and workspace steering, Kiro will prioritize the workspace steering instructions." Para las sesiones en la nube, carga el steering personal desde Settings y Sync en Kiro Web, luego crea o edita la copia en la nube en Settings y Steering.

Los equipos también tienen una ruta documentada: "The global steering feature can be used to define centralized steering files that apply to entire teams. Team steering files can be pushed to user's PCs via MDM solutions or Group Policies, or downloaded by users to their PCs from a central repository, and placed into the ~/.kiro/steering folder."

Luego verifica donde importa. Abre la superficie en la que pasas la mayor parte del día y ejecuta una tarea que no debería activar un archivo restringido, y una que sí debería. En la CLI, espera que llegue todo lo que está en el directorio del espacio de trabajo; esa expectativa es la verificación. Si usas agentes personalizados, confirma que el glob de resources esté presente, porque sin él, el contexto de steering no se cargará en absoluto para ese agente.

Los archivos steering son el resumen permanente: convenciones, stack, estructura. No se adaptan bien a la otra mitad del conocimiento del proyecto: qué decidiste, cuándo y por qué rechazaste la alternativa. Esa mitad debe poder recuperarse bajo demanda en lugar de cargarse en cada tarea, y no debería cambiar de forma dependiendo de si abriste el IDE o la terminal. Un almacén en el que escribes entradas de MemoryLake a propósito mantiene ese registro en un solo lugar. Tú mismo escribes las entradas, con tus propias palabras. No se lee, escribe ni elimina nada de tus directorios de Kiro.

Paso 1: Crear una clave API

Inicia sesión y genera una clave API desde la configuración de tu espacio de trabajo. Esta es la credencial que usan tus agentes e integraciones, así que créala antes de comenzar a mover cualquier cosa.

Paso 2: Subir tus primeros recuerdos

Comienza con las decisiones que tus archivos steering implican pero nunca declaran: por qué el stack es el que es, qué enfoque rechazaste y por qué motivos, qué restricción existe por una razón que nadie recuerda. Escribe cada una como una nota breve e independiente para que pueda recuperarse por sí sola.

Paso 3: Conectar tu IA y agentes

Conecta los asistentes y agentes que utilizas. El registro te seguirá a través de superficies y herramientas, en lugar de depender de qué directorio puede leer una sesión determinada.

Tu nivel siempre activo se convierte en un presupuesto en lugar de una carpeta. Una vez que aceptas que una superficie lo carga todo, el tamaño de ese directorio es una decisión que tomas a propósito en lugar de algo que se acumula. Ese presupuesto interactúa directamente con cuánto espacio queda más adelante en una sesión larga, que es el mismo compromiso analizado en what survives Kiro compaction.

Las revisiones obtienen un segundo canal. En Kiro Web, los comentarios en las solicitudes de extracción (pull requests) se convierten en steering: comenta con pautas como "always use our standard error handling" y "the agent learns and applies those patterns to future work across all your repositories." Hay un límite importante establecido junto a esto: "Only your feedback (the user who created the task) influences the agent's learnings. Other reviewers' comments don't affect what the agent learns." El comentario de un revisor senior en la tarea de otra persona no le está enseñando nada al agente.

Los archivos compartidos entre herramientas dejan de ser una victoria gratuita. Un AGENTS.md en la raíz es conveniente y siempre se incluye, lo que significa que pertenece a tu presupuesto siempre activo en lugar de estar fuera de él. Si mantienes un archivo en varios agentes, el contrato de carga de cada herramienta difiere, y el archivo compartido es tan útil como el lector menos restringido del mismo.

Moverse entre herramientas se vuelve más fácil de planificar. Cuando la restricción reside en el front matter en lugar de en una interfaz de usuario específica de la herramienta, puedes ver de un vistazo qué necesitaría expresarse de otra manera en otro lugar, que es la parte práctica de how to migrate from Kiro to Claude Code.

Escribe la suposición de la superficie dentro del archivo. Una línea en la parte superior de un archivo restringido que diga "expected to load only for src/components" no cuesta nada y le dice a la siguiente persona qué verificar cuando aparezca en otro lugar.

Mantén el nivel siempre activo bajo revisión programada. Es el nivel que cuesta algo en cada tarea en cada superficie, y es el que crece por accidente.

Prefiere las referencias de archivos al contenido pegado. Un puntero #[[file:...]] a una especificación en vivo no puede quedar obsoleto de la forma en que lo hace un extracto copiado.

Asigna a los archivos de inclusión automática descripciones que parezcan activadores, no resúmenes. El trabajo documentado del campo es "When to include this file", por lo que una descripción redactada como una condición ("Use when creating or modifying API endpoints") hace más trabajo que una etiqueta de tema. Los archivos de contexto compartido se comportan de la misma manera en otras herramientas, como en how Cursor Projects share context files.

Audita lo que realmente está disponible en lugar de lo que recuerdas haber escrito. Una lista de directorios no es lo mismo que una lista de carga, y la brecha entre ambas es el mismo problema descrito en how to find Zed skills missing from your catalog.

Kiro te ofrece cuatro modos de inclusión, dos directorios y un agente en cinco superficies, y documenta claramente dónde se aplican las restricciones y dónde no. La CLI carga todo en el directorio del espacio de trabajo. El sandbox en la nube no puede leer tu directorio global. Los agentes personalizados no cargan ningún steering a menos que lo indiques en resources. Un AGENTS.md en la raíz siempre se incluye.

Clasifica tus archivos en un nivel siempre activo que aceptarías en todas partes y un nivel restringido que mantengas deliberadamente pequeño, coloca las preferencias personales donde la superficie que usas realmente pueda leerlas y verifica en esa superficie en lugar de en aquella donde funcionó primero. Luego, mantén las decisiones detrás de esas convenciones en algún lugar recuperable, para que el razonamiento sobreviva la próxima vez que cambie la estructura de archivos.