Guía de OpenCode Agents: 7 controles para Subagents y AGENTS.md

Respuesta rápida: usa AGENTS.md para reglas del repositorio y OpenCode agents cuando necesites un especialista con prompt, modelo, herramientas y límites propios.

AGENTS.md conserva las reglas duraderas del proyecto: comandos de prueba, estilo, carpetas generadas y advertencias. El agent contiene la conducta de un rol concreto, por ejemplo revisar cambios o preparar documentación.

Si mezclas ambas capas, el equipo acaba con instrucciones duplicadas y más difíciles de corregir.

Un subagent ayuda cuando separa una preocupación real: inspeccionar un directorio grande, revisar un diff delicado o investigar una API. Para una edición pequeña suele ser más simple usar la sesión principal.

Define un contrato de salida: hallazgos con archivo y línea, plan de parche o lista de riesgos.

El modelo debe seguir el riesgo. Revisión, arquitectura y migraciones merecen más razonamiento; resúmenes y notas pueden usar un modelo más rápido.

Limita herramientas y rutas. Un agente de documentación no necesita tocar secretos ni ejecutar despliegues.

La configuración compartida debe ser legible en Git, pero los secretos deben vivir en variables de entorno o flujos del proveedor.

Nombra los roles con estabilidad: reviewer, docs-editor o migration-checker son mejores que helper.

Primero pide una inspección sin escritura. Comprueba que respete el alcance y devuelva el formato esperado.

Luego permite un cambio pequeño y revisa el diff antes de usarlo en tareas mayores.

1. Nombrar el rolUsa reviewer, planner o docs-editor.
2. Definir salidaIndica qué devuelve y qué no debe hacer.
3. Elegir modeloAjusta razonamiento y coste al riesgo.
4. Limitar herramientasEmpieza con el conjunto mínimo.
5. Validar sin escrituraPrimero pide inspección o revisión.
6. Revisar un diffAmplía uso solo si el cambio es limpio.
7. Registrar la reglaDocumenta cuándo usar el agent.

Crear demasiados agents genera confusión de enrutamiento. Empieza por un rol que resuelva un problema repetido.

No repitas reglas entre AGENTS.md y el agent; decide una fuente de verdad.

MCP, hooks y skills pueden hacer que un agent sea más útil, pero también amplían su superficie de riesgo.

Añade una integración por vez: prompt, herramienta y ruta de escritura deben validarse por separado.

Antes de compartir el agent con el equipo, guarda un ejemplo de tarea exitosa: objetivo, archivos leídos, comandos ejecutados, resultado y diff revisado. Esa evidencia evita que el rol sea una promesa abstracta y permite comparar si cambios posteriores empeoran su comportamiento.

También conviene fijar una regla de salida. Si el agent no tiene suficiente contexto, debe pedir el archivo o comando concreto en vez de adivinar. Si detecta secretos, producción o permisos de escritura amplios, debe detenerse y devolver una lista de riesgos. Esta regla reduce errores costosos sin frenar tareas normales.

En equipos pequeños, empieza con dos roles como máximo: reviewer y docs-editor. El reviewer protege cambios de código; docs-editor mantiene instrucciones, README y notas de migración. Cuando ambos sean repetibles, puedes añadir un research agent o migration-checker con límites igual de claros.

Define nombres que expliquen el trabajo, no la personalidad. reviewer, docs-editor, release-checker o migration-planner son más fáciles de auditar que nombres creativos. En los registros del repositorio, esos nombres muestran por qué se invocó el agent y qué tipo de resultado debía entregar.

Mantén una ruta de escalado. Un agent de solo lectura puede revisar una carpeta completa, pero no debería cambiar archivos hasta que el equipo haya revisado su primer informe. Cuando pase a escribir, limita los directorios permitidos y exige que el resultado incluya archivos tocados, pruebas ejecutadas y riesgos pendientes.

Revisa la configuración cada vez que cambien los comandos del proyecto, el framework o el proveedor de modelos. Un agent que antes era seguro puede quedar obsoleto si el build cambia, si aparece una nueva carpeta generada o si el equipo mueve secretos a otro sistema.

{
  "agents": {
    "reviewer": {
      "model": "provider/reasoning-model",
      "description": "Review diffs and return concrete findings only",
      "tools": ["read", "grep"]
    },
    "docs-editor": {
      "model": "provider/fast-model",
      "description": "Update documentation after source changes",
      "tools": ["read", "edit"]
    }
  }
}

La configuración compartida debe ser legible en Git, pero los secretos deben vivir en variables de entorno o flujos del proveedor.