Cómo replicar localmente los archivos de instrucciones remotas de OpenCode antes de que un timeout los omita (Guía 2026)

OpenCode lee instrucciones personalizadas de un archivo AGENTS.md y, adicionalmente, de una lista que especificas en opencode.json o en la configuración global. Esa lista acepta rutas simples, globs y URLs, y el comportamiento documentado es que "todos los archivos de instrucciones se combinan con tus archivos AGENTS.md".

Combinados es la palabra clave. Hay un único cuerpo fusionado de instrucciones, ensamblado al inicio, y nada en la conversación marca qué entradas contribuyeron. Un archivo que llegó y un archivo que superó el tiempo de espera producen la misma sesión visible: el agente está siguiendo instrucciones, solo que no todas.

Compara eso con cómo se comportan las entradas locales. Una ruta en la lista se resuelve en el disco o no, y las búsquedas en disco no tardan cinco segundos. Un glob coincide con archivos o no coincide con nada. Esos fallos son estables: lo que está mal hoy estará mal mañana, que es el tipo de fallo que encuentras una vez y corriges una vez.

Una entrada remota falla de manera intermitente. Funciona en tu escritorio y no en el tren. Funciona para ti y no para el colega detrás de un proxy más lento. La ausencia intermitente de instrucciones es la peor versión de este problema, porque lo que hace la gente cuando un agente ignora una regla es volver a enunciar la regla, no verificar si la regla llegó. Esa es la misma trampa detrás de la mayoría de los casos de un agente que parece estar omitiendo las reglas en tu archivo de instrucciones.

Hay un segundo problema, más silencioso, en la misma lista. El propio ejemplo de OpenCode para el campo instructions incluye un glob de .cursor/rules que termina en .md. Las reglas de proyecto de Cursor usan una extensión diferente, por lo que un glob escrito de esa manera no coincide con nada en una carpeta llena de reglas de Cursor, y no coincidir con nada no es un error. Copiar un ejemplo que funciona de la documentación de una herramienta en la configuración de otra herramienta es cómo terminas con una lista que parece llena pero aporta poco.

Apuntar cada proyecto a la misma URL y llamarlo centralizado. Está centralizado. Pero ahora también es una dependencia de red en la ruta de inicio de cada sesión en la empresa.

Aumentar el timeout. No hay ninguna opción documentada para ello. Los cinco segundos se establecen como el comportamiento, no como un valor predeterminado que puedas ajustar.

Agregar una segunda URL como respaldo. Dos entradas remotas son dos oportunidades de agotar el tiempo de espera, no una tolerancia a fallos. Nada en el comportamiento documentado intenta una y luego la otra.

Asumir que un fallo de descarga es ruidoso. Nada en la documentación describe un fallo crítico o una sesión bloqueada cuando un archivo de instrucciones remotas no llega a tiempo. Planifica para el silencio.

Duplicar las reglas compartidas en el AGENTS.md de cada proyecto. Esta es la opción confiable y es la que la función remota existe para evitar. Funciona, y en un mes las copias ya no coinciden.

Asumir que la sintaxis de referencia de archivos te salvará. No lo hará, y la documentación es explícita: "opencode no analiza automáticamente las referencias a archivos en AGENTS.md". Escribir una ruta dentro del archivo de instrucciones no importa ese archivo. El campo instructions es la vía compatible.

El objetivo es mantener una versión autoritativa de las reglas compartidas sin poner una llamada de red en la ruta crítica de cada sesión. Eso significa que la copia en el repositorio es lo que OpenCode lee, y la red es lo que actualiza la copia.

Paso 1: Reemplaza la entrada remota con una ruta local confirmada

En opencode.json, cambia la entrada de la URL por una ruta dentro del repositorio. Algo como una carpeta docs que contenga la guía compartida, referenciada como una ruta simple en el array instructions. Confirma (commit) el archivo.

Esto invierte la dependencia. OpenCode ahora lee un archivo en el disco, que existe o no, y el modo de fallo se vuelve estable en lugar de intermitente. Cualquiera que clone el repositorio obtiene las reglas, pueda o no comunicarse con el servidor interno.

Mientras editas la lista, verifica cada glob en ella. Confirma que la extensión coincida con lo que la herramienta de destino realmente escribe (ahí es donde falla el ejemplo de las reglas de Cursor) y confirma que cada glob coincida con al menos un archivo hoy. Un glob que no coincide con nada es indistinguible de una entrada que funciona, que es exactamente la propiedad que estás intentando eliminar.

Paso 2: Haz que la actualización sea un paso visible, no un efecto secundario del inicio

Ahora decide cómo se actualiza la copia local. La respuesta correcta es lo que tu equipo ya revise: una tarea programada que abra un pull request cuando cambie la guía de origen, o un paso en tu rutina de actualización de dependencias.

Lo que importa es que la actualización sea algo que una persona vea. Cuando la guía compartida cambia, alguien revisa el diff en el contexto de este proyecto, porque una regla que tiene sentido en un repositorio central a veces no tiene sentido en un servicio en particular. Una descarga al iniciar te da el nuevo texto sin revisión; un pull request te da el nuevo texto y una decisión.

También te da historial. Seis meses después, la pregunta "¿cuándo comenzó a aplicarse esta regla para nosotros?" tiene una respuesta en el registro del repositorio, que es algo que un archivo descargado directamente nunca puede proporcionar.

Paso 3: Verifica que el conjunto de instrucciones combinado sea el que esperas

Inicia una sesión y confirma que las reglas estén vigentes, no preguntándole al agente si las tiene, sino dándole una pequeña tarea que las reglas gobiernen y verificando que el resultado las siga.

Elige algo inequívoco y rápido. Si la guía compartida requiere una estructura particular de manejo de errores, pide una función pequeña que deba devolver un error y observa la estructura. Si requiere una convención de comentarios, pide un archivo nuevo y lee el encabezado.

Haz esto una vez después del cambio, y nuevamente cada vez que se actualice la copia local. Una prueba que ejercite una regla es la única verificación confiable, porque el conjunto de instrucciones se fusiona en un solo cuerpo sin informes por entrada, la misma razón por la cual limitar el alcance de las instrucciones a archivos específicos vale la pena hacerlo deliberadamente en lugar de por suposición.

La guía compartida es la configuración para una herramienta. El razonamiento detrás de sus reglas (por qué esta estructura de error, por qué este límite) es lo que realmente quieres que esté disponible en cada herramienta y en cada sesión. MemoryLake es un lugar para guardar ese razonamiento para que no dependa de que se complete una descarga.

Tú mismo escribes las entradas, con tus propias palabras. No se lee, escribe ni elimina nada de un archivo de instrucciones remotas, una configuración de OpenCode o el almacenamiento de ningún proveedor.

Paso 1: Crea una clave de API

Inicia sesión y genera una clave desde el panel de control. La clave permite que un agente lea las entradas directamente, sin un archivo intermedio que descargar y sin un timeout que perder.

Paso 2: Sube tus primeras memorias

Agrega las decisiones que codifica la guía compartida, una por entrada, cada una con su razón. "Los errores devuelven un resultado tipado porque quienes los llaman necesitan bifurcar según el tipo" es portátil. "Sigue la guía de manejo de errores" es un puntero que deja de funcionar en el momento en que el puntero se rompe.

Paso 3: Conecta tu IA y agentes

Apunta tus agentes al espacio de trabajo. El razonamiento estará presente en cada herramienta que use tu equipo, y el archivo de instrucciones específico de la herramienta podrá mantenerse tan ligero como la herramienta lo requiera.

El primer cambio es que una mala red deja de ser una interrupción silenciosa de las reglas. Leer desde el disco significa que las reglas están allí o conspicuamente no están, y "conspicuamente no están" es algo que una persona nota en la primera ejecución en lugar de en una revisión de código tres semanas después.

El segundo es que la guía compartida gana un paso de revisión. Los repositorios centrales de reglas acumulan reglas, y un proyecto que las descarga al iniciar adopta cada adición automáticamente, incluidas las que no se aplican a él. Una actualización que llega como un diff se lee.

El tercero es que tu lista de instrucciones se vuelve auditable. Cada entrada es una ruta o un glob que puedes verificar, y verificar un glob toma segundos. Una vez que no hay ninguna URL en la lista, "qué hay en mi conjunto de instrucciones" es una pregunta con una respuesta definitiva, que es la propiedad que hace que valga la pena mantener un archivo de instrucciones, y la razón por la cual el orden de los archivos y la precedencia valen la pena definirse explícitamente.

Hay un costo, y es honesto nombrarlo: la copia local puede quedar desactualizada. Un archivo descargado siempre está al día, y uno confirmado está al día hasta la última actualización. Vale la pena hacer ese intercambio porque una regla desactualizada es visible en el archivo y una regla faltante no lo es, pero solo se sostiene si la actualización realmente ocurre. Si tu equipo no va a ejecutar la actualización, habrás elegido la desactualización en lugar de sorprenderte por ella.

El mismo compromiso aparece cada vez que una herramienta ofrece extraer instrucciones de otro lugar, ya sea un agente que genera una regla para ti a pedido o una migración que reescribe tu configuración en el formato de una nueva herramienta, como reconocerá cualquiera que haya trasladado un proyecto a OpenCode desde Cursor.

Mantén local la ruta de inicio. Todo lo que OpenCode deba leer antes del primer turno debe estar en el disco. Las llamadas de red pertenecen a las tareas de actualización, no al inicio de la sesión.

Verifica cada glob contra la extensión real de la herramienta de destino. Esta es una verificación de dos minutos que detecta la entrada silenciosa vacía más común. No confíes en un ejemplo, incluso en uno oficial.

Una copia autoritativa por repositorio, confirmada (committed). No un enlace simbólico a una copia compartida, no una ruta fuera del proyecto. Alguien que clone de cero debería obtener las reglas.

Prueba una regla, no preguntes sobre ella. Que un agente informe que tiene tus instrucciones no es evidencia. Una pequeña tarea gobernada por una regla sí lo es.

Mantén el motivo fuera del archivo de reglas y en un lugar duradero. Los archivos de reglas se reescriben cuando las herramientas cambian. El motivo por el cual existe una regla es lo que permite a la siguiente persona decidir si conservarla.

Pon fecha a la copia local. Una nota de una línea en la parte superior que indique cuándo se actualizó por última vez convierte el "¿está esto al día?" de una investigación a un simple vistazo.

Vigila lo que crece. Cada entrada en la lista de instrucciones se combina en la solicitud. Una lista que acumula entradas es un prefijo que crece en cada turno, lo cual es el mismo problema de contabilidad que los costos de tokens que provienen de lo que envías cada vez.

Los archivos de instrucciones remotas resuelven un problema real e introducen uno específico. OpenCode los descarga con un timeout de cinco segundos, combina lo que llegue con tus archivos AGENTS.md y no te ofrece ningún informe por entrada, por lo que un archivo de instrucciones que no llegó se ve exactamente igual que uno que sí lo hizo.

Apunta la lista a una copia local confirmada, haz de la actualización un paso revisado en lugar de un efecto secundario del inicio, y demuestra que las reglas están activas dándole al agente una tarea que estas gobiernen. Pierdes la actualización automática y ganas un modo de fallo que puedes ver.

Luego, mantén el razonamiento detrás de las reglas en algún lugar que no resida en el archivo de configuración de ninguna herramienta, porque esa es la parte que seguirás necesitando después de la próxima migración, la misma conclusión a la que llegan los equipos cuando mueven instrucciones entre agentes y descubren que el archivo era la parte fácil.