Objetivo del tema
Aprender a preparar cualquier proyecto para trabajar con OpenCode: generar el archivo AGENTS.md con el comando /init, entender qué información conviene incluir, diferenciar reglas globales de las propias del proyecto y aprovechar las opciones avanzadas de instrucciones.
Cuando abres OpenCode sobre un repositorio nuevo, el agente no sabe nada de él: cómo compilar, dónde viven los tests, qué convenciones sigue el equipo. El archivo AGENTS.md resuelve esto: es un documento Markdown ubicado en la raíz del proyecto cuyas instrucciones se incluyen automáticamente en el contexto del modelo en cada sesión.
Piensa en él como el "manual de incorporación" que le entregarías a un desarrollador nuevo en su primer día:
AGENTS.md, así que la inversión sirve para todo tu ecosistema.La forma recomendada de crear este archivo es dejar que el propio agente lo redacte. Desde la TUI, dentro del proyecto:
cd /ruta/a/tu/proyecto
opencode
/initAl ejecutar /init, OpenCode escanea los archivos importantes del repositorio, puede hacerte algunas preguntas puntuales cuando el código no responde a algo, y luego crea (o mejora) el AGENTS.md con guía concisa y específica del proyecto. Se centra en lo que las sesiones futuras más necesitan:
Build, lint y tests: cómo ejecutarlos y en qué orden cuando el orden importa.
Estructura del repositorio y relaciones entre módulos que no son obvias por los nombres de archivo.
Reglas del proyecto, particularidades de configuración y errores comunes que evitar.
Referencia a reglas previas de Cursor o Copilot si ya existen en el repo.
Si ya existe un AGENTS.md, /init lo mejora en lugar de reemplazarlo a ciegas.
Consejo clave: agrega el AGENTS.md al control de versiones y comitealo junto con tu proyecto. Así todo el equipo comparte las mismas instrucciones y el historial de cambios queda documentado.
También puedes escribirlo a mano. Este ejemplo ilustra el nivel de detalle útil para un monorepo TypeScript:
# Proyecto: API de pedidos (monorepo)
Monorepo en TypeScript con bun workspaces.
## Estructura
- packages/core - lógica de negocio compartida
- packages/functions - funciones serverless
- infra/ - definición de infraestructura por servicio
## Estándares de código
- TypeScript en modo estricto
- Código compartido va en packages/core con exports configurados
- Infraestructura dividida en archivos lógicos dentro de infra/
## Comandos
- Instalar dependencias: bun install
- Tests: bun test
- Verificación completa antes de entregar: bun run check
## Convenciones
- Importar módulos compartidos por nombre de workspace: @api/core/...Observa que no es una biografía del proyecto: son instrucciones accionables que cambian el comportamiento del agente.
OpenCode lee instrucciones desde varias ubicaciones, cada una con un propósito distinto:
| Ubicación | Alcance | Uso recomendado |
|---|---|---|
AGENTS.md en la raíz (o subcarpetas) del proyecto |
Sólo ese proyecto | Convenciones del equipo, comandos de build/test, arquitectura. |
~/.config/opencode/AGENTS.md |
Todas tus sesiones, en cualquier proyecto | Preferencias personales: idioma de respuesta, estilo de commits. |
Las reglas globales no se comparten por Git, así que reserva ese archivo para gustos personales; lo compartido por el equipo pertenece al repositorio.
Si migras desde Claude Code, OpenCode entiende sus convenciones como alternativa de respaldo:
CLAUDE.md en el proyecto se usa sólo si no existe AGENTS.md.~/.claude/CLAUDE.md se aplica si no existe ~/.config/opencode/AGENTS.md.~/.claude/skills/ también se reconocen.Puedes desactivar esta compatibilidad exportando OPENCODE_DISABLE_CLAUDE_CODE=1 (existen variantes para deshabilitar sólo las reglas o sólo las skills).
Cuando OpenCode arranca, busca los archivos de reglas en este orden y gana la primera coincidencia de cada categoría:
AGENTS.md, luego CLAUDE.md).~/.config/opencode/AGENTS.md.~/.claude/CLAUDE.md (si no está deshabilitado).Por ejemplo, si conviven AGENTS.md y CLAUDE.md en el mismo directorio, sólo se usa el primero.
Para reutilizar documentación existente sin duplicarla, el campo instructions admite archivos locales, patrones glob e incluso URLs remotas:
{
"$schema": "https://opencode.ai/config.json",
"instructions": [
"CONTRIBUTING.md",
"docs/guidelines.md",
"packages/*/AGENTS.md",
"https://raw.githubusercontent.com/mi-org/reglas/main/style.md"
]
}Estos archivos se combinan con tus AGENTS.md. Las URLs remotas se descargan con un tiempo máximo de 5 segundos; para monorepos, los patrones glob suelen ser la opción más mantenible.
Otra técnica avanzada es enseñarle al agente a cargar documentos bajo demanda desde el propio AGENTS.md:
@docs/api-standards.md.Así mantienes un AGENTS.md corto mientras la guía detallada vive en archivos modulares reutilizables entre proyectos.
Buenas prácticas para tu AGENTS.md: mantenlo conciso (el contexto del modelo es valioso), actualízalo cuando cambien los comandos o la estructura, evita instrucciones contradictorias y revísalo en code review como cualquier archivo fuente.
Conclusión: invertir quince minutos en un buen AGENTS.md mejora todas las sesiones futuras: el agente compila, testa y respeta las convenciones sin que tengas que explicárselo cada vez. Con el proyecto inicializado, estamos listos para explorar a fondo la interfaz TUI en el próximo tema.