8. Modos Plan y Build

Objetivo del tema

Comprender los dos agentes primarios que trae OpenCode de fábrica —Plan y Build—, aprender a alternar entre ellos con la tecla Tab y adoptar el flujo profesional de planificar antes de construir.

8.1 Agentes primarios: el interruptor de Tab

Dentro de la TUI siempre hay un agente primario activo manejando tu conversación. OpenCode incluye dos:

  • Build: el agente predeterminado, con todas las herramientas habilitadas. Es el modo de trabajo para desarrollo real.
  • Plan: un agente restringido pensado para analizar, sugerir y planificar sin tocar tu código.

Pulsando Tab ciclas entre ellos en cualquier momento de la sesión; el modo activo se muestra en la esquina inferior derecha de la TUI.

Idea clave: la diferencia no está en el modelo sino en los permisos. En Plan, las ediciones de archivos (edit) y los comandos bash (bash) están configurados como ask: el agente puede proponer, pero nada cambia sin aprobación explícita.

8.2 Modo Build: manos a la obra

Build es donde ocurre el trabajo: puede leer, escribir y parchar archivos, ejecutar comandos, lanzar tests y encadenar tareas autónomamente hasta completar tu pedido. Usalo cuando:

  • El plan ya está acordado y quieres aplicarlo.
  • La tarea es directa y bien definida ("agrega este campo al formulario", "corrige este test roto").
  • Necesitas que ejecute comandos reales: instalar dependencias, correr migraciones, validar builds.

Aun en Build, OpenCode respeta el sistema de permisos del proyecto: si configuraste que git push pida confirmación o que ciertos comandos estén prohibidos, el agente consultará antes de actuar.

8.3 Modo Plan: pensar antes de escribir

Plan convierte a OpenCode en un asesor de solo lectura: explora el repositorio, evalúa alternativas y te devuelve un plan concreto, pero no modifica nada por su cuenta. Es ideal para:

  • Tareas grandes: nuevas funcionalidades, refactors de alcance medio o migraciones.
  • Código desconocido: entender cómo está resuelta una parte antes de proponer cambios.
  • Revisiones: analizar propuestas y riesgos sin riesgo de efectos secundarios.

8.4 El flujo recomendado: planificar, iterar, construir

Para funcionalidades que van más allá de un arreglo puntual, el flujo con mejores resultados tiene tres etapas:

1. Planificar (Tab → Plan)

Describe la funcionalidad con detalle y deja que el agente proponga cómo implementarla. Ejemplo: "cuando un usuario borra una nota, marcarla como eliminada en la base y crear una pantalla de eliminadas con opción de restaurar o borrar definitivo".

2. Iterar el plan

Responde con correcciones y contexto extra: referencias con @, capturas arrastradas a la terminal, restricciones de diseño. Cada vuelta afina la propuesta.

3. Construir (Tab → Build)

Con el plan aprobado, cambia a Build: "sounds good, adelante con los cambios". El agente ejecuta, corre los tests y reporta resultados.

Habla con él como a un compañero junior del equipo: cuanto más contexto (ejemplos, imágenes, archivos de referencia), menos idas y vueltas.

8.5 ¿Cuál uso en cada situación?

Elección de modo según la tarea
Situación Modo sugerido Motivo
Agregar una feature compleja Plan → Build Primero alinear diseño, después ejecutar sin sorpresas.
Corregir un bug puntual Build Cambio acotado; el diff final sirve de revisión.
Entender un módulo ajeno Plan Análisis seguro sobre código que no quieres tocar todavía.
Refactor de gran alcance Plan → Build El plan por fases permite revisar antes de cada paso.
Escribir tests o documentación Build Tareas aditivas de bajo riesgo.

8.6 Los subagents: General, Explore y Scout

Además de los dos agentes primarios, OpenCode trae tres subagents: asistentes especializados que el agente principal invoca automáticamente cuando la tarea lo requiere, o que tú puedes llamar mencionándolos con @:

  • @general: propósito general para investigaciones complejas y tareas multipaso; puede editar archivos si hace falta y ejecutar varias unidades de trabajo en paralelo.
  • @explore: búsquedas veloces de solo lectura: encontrar archivos por patrón, localizar palabras clave, responder preguntas sobre el código.
  • @scout: investigación externa: clona dependencias en una caché administrada para inspeccionar su código fuente sin ensuciar tu workspace.

Cuando un subagent crea sesiones hijas, puedes navegar entre ellas y volver a la conversación principal con las flechas (Líder+Abajo para entrar, Izquierda/Derecha para ciclar, Arriba para volver).

@explore encuentra todos los endpoints que no validen permisos
@general compara las dos implementaciones de caché y recomienda una

También existen agentes de sistema ocultos (compaction, title y summary) que resumen contextos largos y titulan sesiones; corren solos y no aparecen en la interfaz.

Mirando adelante: tanto los agentes integrados como tus propios agentes se configuran en opencode.json o en archivos Markdown dentro de .opencode/agents/, con prompt, modelo, temperatura y permisos propios (incluso existe opencode agent create para generarlos guiados). Lo veremos a fondo en el tema 14.

Conclusión: Plan y Build formalizan una disciplina que ya aplicaban los buenos equipos: pensar antes de escribir. Alternar con Tab cuesta un segundo y evita horas de re-trabajo: explora y acuerda el camino en Plan, y ejecuta con todas las herramientas en Build. En el próximo tema recorreremos los comandos esenciales tanto de la TUI como del modo CLI.

Retornar