La imagen de portada pertenece a jonakoh_
Si como yo, has utilizado la suscripción de Opencode OpencodeGo quizás te cueste llegar a fin de mes con los tokens que se ofrecen.
Tras un año usando Opencode te puedo decir que la solución no está en los prompts, sino en la forma en que implementamos distintos patrones arquitecturales para hacer el trabajo. Podemos expresar estos patrones haciendo uso de las capacidades de definir agentes dentro de un espacio de trabajo con OpenCode. Este feature desata el verdadero potencial de la herramienta.
Hoy te enseñare el primer patrón que he descubierto haciendo utilización de los agentes mediante la creación de un tablero Kanban para demostrar su implementación.
Tipos de agentes en Opencode
En Opencode tenemos dos tipos de agentes:
Primarios: Son los agentes a los que se puede acceder desde la caja de interacción de la ventana principal de Opencode (shift+tab).build y plan son agentes primarios.
Sub-agentes: Son agentes que pueden ser invocados por los agentes primarios. El agente general y explore subagentes.
Si en nuestro proyecto creamos una carpeta llamada .opencode con una sub-carpeta llamada agents podemos definir tanto agentes primarios como secundarios en nuestro proyecto.
Layered Agent Pattern
Primero visualicemos su forma mas general antes de ir a la implementación:
En este caso vamos a hacer tenemos un esquema lineal para abrir la mente sobre la utilización de estos agentes, de a poco iremos añadiendo mas complejidad en futuras entregas.
El agente primario es el orquestador, que funciona como un bus principal donde está todo el historial de cambios del proyecto. Como es un bus principal, el objetivo es mantenerlo limpio con un contexto sumamente acotado y que pueda tener todos los mensajes de principio a fin sin necesidad de compactar ni de crear nuevas conversaciones, como se ve en la imágen:
Los subagentes tienen contextos vacíos al comienzo de cada petición, esto permite que la atención del modelo no se diluya.
Otra cosa fundamental es acotar bien las restricciones de los agentes, esto permitirá utilizar menos tokens y reducir la incertidumbre de los agentes, permitiendo que tengan menos libertad y opciones para realizar, esto permitirá que el modelo divage menos se centre en acabar la taréa
FastKanban
El proyecto a desarrollar es un proyecto de juguete diseñado para este blog, que es un Kanban que permite crear proyectos y cada proyecto tiene su propia pizarra Kanban. Puedes definir distintas columnas y también arrastrar notas de una columna a otra, es bastante simple para no saturar el blog y poder completarlo en pocos prompts.
La definición de los agentes depende del proyecto a desarrollar, no existe una formula, es parte de la ingeniería del proyecto. Para este proyecto decidí usar el siguiente Stack Tecnologico:
- Next.JS: Framework web fullstack.
- Sqlite: Base de datos en un archivo.
Estas decisiones fueron tomadas para facilitar el proceso de creación.
La carpeta de mi proyecto tiene los siguiente contenidos:
.
└── .opencode
└── agents
├── auditor.md
├── backend.md
├── database.md
├── frontend.md
├── integrador.md
├── orchestrator.md
└── qa.md
Los contenidos de cada archivo son:
auditor.md
---
description: "Audita el código buscando antipatrones y fallos de arquitectura. Solo lectura."
mode: subagent
steps: 8
permissions:
- action: "*"
resource: "*"
effect: deny
- action: read
resource: "*"
effect: allow
- action: shell
resource: "git diff*"
effect: allow
---
Eres el auditor de calidad.
OBJETIVO
Detectar código duplicado, funciones huérfanas o antipatrones mediante `git diff`.
FORMATO DE SALIDA (máximo 12 líneas)
`ruta:línea severidad hallazgo` (ordenado por alta, media, baja). Si no hay fallos: `OK`.
Como podemos observar los permisos son limitados, primero se deniegan todas las acciones, para luego definir las acciones permitidas. En este caso el auditor puede leer archivos pero no ejecutar comandos de shell libremente.
backend.md
---
description: Implementa rutas de API y lógica de servidor en Next.js.
mode: subagent
steps: 8
permissions:
- action: "*"
resource: "*"
effect: deny
- action: read
resource: "*"
effect: allow
- action: edit
resource: "*"
effect: allow
- action: glob
resource: "*"
effect: allow
---
Eres el desarrollador backend de Next.js.
OBJETIVO
Implementar los endpoints (API Routes del App Router) requeridos por el orquestador.
REGLAS
- Cambios mínimos. Limítate a la carpeta `src/app/api/`.
- Conéctate limpiamente con Prisma. No edites componentes gráficos (frontend).
FORMATO DE SALIDA (máximo 20 líneas)
- Archivos tocados (rutas).
- Endpoints implementados.
- Bloqueos o decisiones pendientes.
Aquí debemos ser mas permisivos para que el agente pueda trabajar
database.md
---
description: Crea esquemas de base de datos y migraciones con Prisma y SQLite.
mode: subagent
steps: 8
permissions:
- action: "*"
resource: "*"
effect: deny
- action: read
resource: "*"
effect: allow
- action: edit
resource: "*"
effect: allow
- action: glob
resource: "*"
effect: allow
- action: shell
resource: "*"
effect: allow
---
Eres el especialista en base de datos.
OBJETIVO
Implementar esquemas en `prisma/schema.prisma` y funciones con SQLite mediante Prisma.
REGLAS
- Cambios mínimos. No toques archivos de UI ni rutas de API.
- Motor: SQLite. ORM: Prisma.
FORMATO DE SALIDA (máximo 20 líneas)
- Archivos tocados (rutas).
- Comandos ejecutados y resultado (OK/FALLO).
- Decisiones o bloqueos.
No vuelques código completo en la respuesta.
frontend.md
---
description: Implementa componentes y páginas de la interfaz en Next.js y Tailwind CSS.
mode: subagent
steps: 8
permissions:
- action: "*"
resource: "*"
effect: deny
- action: read
resource: "*"
effect: allow
- action: edit
resource: "*"
effect: allow
- action: glob
resource: "*"
effect: allow
---
Eres el desarrollador frontend.
OBJETIVO
Implementar vistas y componentes en Next.js utilizando Tailwind CSS.
REGLAS
- Cambios mínimos. Limítate a `src/app/` (vistas y componentes visuales).
- No modifiques esquemas de base de datos ni lógica de servidor interna.
FORMATO DE SALIDA (máximo 20 líneas)
- Archivos tocados (rutas).
- Componentes creados o modificados.
- Bloqueos o decisiones pendientes.
---
description: Ejecuta pruebas, typecheck y compilación del proyecto Next.js. Solo lectura.
mode: subagent
steps: 10
permissions:
- action: "*"
resource: "*"
effect: deny
- action: read
resource: "*"
effect: allow
- action: glob
resource: "*"
effect: allow
- action: shell
resource: "npm run *"
effect: allow
- action: shell
resource: "npx tsc *"
effect: allow
- action: shell
resource: "npx vitest *"
effect: allow
---
Eres QA del proyecto.
OBJETIVO
Verificar la compilación, tipos y pruebas del código sin alterarlo (solo lectura).
FORMATO DE SALIDA (máximo 15 líneas)
- Comando ejecutado y resultado (OK/FALLO).
- Error exacto con `archivo:línea` si aplica.
- Siguiente acción recomendada.
Y por ultimo el orquestador, como veremos el orquestador esta bastante limitado y tiene todos los subagentes como recursos a su disposicion. Se enfoca en la comunicación y acotar la petición con preguntas:
---
description: Pregunta al usuario, define el alcance mínimo y delega en el equipo de Next.js y base de datos. No lee ni edita código.
mode: primary
steps: 12
permissions:
- action: "*"
resource: "*"
effect: deny
- action: question
resource: "*"
effect: allow
- action: subagent
resource: "backend"
effect: allow
- action: subagent
resource: "frontend"
effect: allow
- action: subagent
resource: "database"
effect: allow
- action: subagent
resource: "qa"
effect: allow
- action: subagent
resource: "auditor"
effect: allow
---
Eres el orquestador de un equipo que construye una aplicación Next.js con Prisma y SQLite.
TU ROL
- Hablas con el usuario y delegas. No lees archivos, no escribes código y no ejecutas comandos.
- Usa la herramienta `question` para decisiones de alcance. Si la petición es clara, delega directo.
DESCOMPOSICIÓN Y FLUJO
- Si una tarea mezcla áreas distintas (DB, API, UI, tests), divídela antes de delegar.
- Cada llamada a un subagente pide un cambio mínimo y verificable en una sola área.
- Orden recomendado: Esquema DB → API/Backend → Componentes Frontend → Tests → Auditoría e Integración.
AHORRO DE TOKENS (OBLIGATORIO)
- No repitas contexto; envía a cada trabajador solo lo que necesita.
- Limita los informes de los subagentes a un máximo de 20 líneas.
- Responde en español, breve y directo.
Habiendo mostrado las instrucciones de cada agente vamos con los prompts que se hicieron para el desarrollo del proyecto.
Desarrollo
Para desarrollar yo opto por usar un archivo llamado prompts.md que es mi fuente de verdad por si algún día necesito recrear el proyecto. también de esta manera puedo trabajar mejor el formato de cada petición.
Prompt 1: Vista de proyectos
Crea la vista inicial (#1: Dashboard de Proyectos) para la aplicación FastKanban usando Next.js (App Router, TypeScript y Tailwind CSS).
Requerimientos de la vista:
1. Estado Vacío (sin proyectos):
- Mostrar un botón principal cuadrado con bordes punteados (border-dashed) que diga "Agregar proyecto".
2. Lista de Proyectos (con datos presentes):
- Renderizar una cuadrícula (grid) de tarjetas de proyectos.
- Cada tarjeta debe mostrar el nombre del proyecto y un preview temporal que diga "Proyecto 1" (placeholder mientras se implementa la vista detallada del Kanban).
- Incluir el botón "Agregar proyecto" al final de la lista.
3. Funcionalidad mínima:
- Manejar un estado local/simulado para alternar entre el estado vacío y la lista de proyectos al hacer clic en "Agregar proyecto".
Instrucciones para los agentes:
- Limitarse estrictamente a la Vista #1.
- No implementar el tablero Kanban detallado aún.
Prompt 2: DB Proyectos
Implementa la base de datos para la vista de proyectos:
- Los proyectos tienen un nombre.
- Una fecha de creación.
- Una fecha de actualización.
- Un Blob para el preview (Por ahora un placeholder).
Prompt 3: Tablero Kanban
Crea un tablero de Kanban para los proyectos:
1. Sidebar:
- Un botón para crear colas.
- Cuando se presione el botón debe aparecer un dialog para escoger el color de la cola y el nombre.
- Para el color un color picker.
- Para el nombre un input estilizado.
2. El tablero de kanban con las colas:
- Cada cola tiene que tener el nombre y su color en la parte superior.
- Un espacio mas oscuro para delimitar la colulmna.
- Cada cola ocupa una columna con un overflow.
3. Cuando se haga click en la cola:
- Aparece un dialog para agregar la nota con soporte para markdown.
- El dialog tiene un look como de postit con el color correspondiente a la cola.
- El texto debe ser blanco o negro dependiendo del color de cada cola.
- No debe tener un campo para el titulo de la nota explicito.
- El titulo de la nota es el primer header de la nota y si no tiene se pone como (sin titulo).
- Hay un hint al principio que indica que el titulo es el primer header.
4. La nota en la cola:
- Se representa como un titulo con su contenido parcial oculto con ...
5. Cuando arrastro una nota:
- La puedo cambiar de cola lo que hara mutar so color.
- Hay una animación drag and drop con framer-motion.
6. Esquema de datos:
- La nota tiene que tener los campos:
- Titulo.
- Fecha de cracion.
- Fecha de actualización.
- Cola a la que pertenece.
- Proyecto al cual pertenece (FK)
- La cola debe tener los campos:
- Titulo
- Fecha de creación
- Color
- Proyecto al cual pertenece (FK)
Cualquier detalle omitido debera ser tomado en cuenta para la creación la compatibulidad
Prompt 4: Limpieza y detalles
1. La nota al arrastrarla debe quedar por encima de todos los elementos de la pagina.
2. Añadir soporte para quitar colas (un botón X arriba a la derecha de cada cola).
3. Añadir soporte para quitar notas (Un botón X arriba a la derecha de cada nota).
4. En la pantalla principal al crear un proyecto debe existir un dialogo que te permita definir el titulo del proyecto.
5. Soporte de edición de los titulos de proyecto y las notas: Si clickeo cualquier de una cola o un proyecto debo poder editarlo. Se indica con un lapiz y un background gris al hacer hover en el elemento.
6. Verificar que todos los elementos tengan un CRUD completo en el frontend.
7. Agregar un botón de navegación para volver a la ventana de proyectos.
Prompt 5: Ultimos detalles
Corrige los puntos.
1. Integra los snapshots y mejora los cards de proyectos.
- Un header gris con el nombre
- En el cuerpo un snapshot del kanban creado
- Si no hay un kanban reemplazar por una tarjeta en blanco
2. Modo oscuro:
- Para la vista de proyectos y vista del kanban.
Y estos son los prompts que utilice en este proyecto. Por la misma naturaleza del proyecto no se necesitaron mas recursos.
Adjunto algunas imágenes del resultado
Conclusión
En lo personal este patrón me ha ayudado a ahorrar tokens al momento de crear una gran variedad de proyecto, si bien este no es el único patrón de mi caja de herramientas es una base solida para ir mejorando. Es adaptable a cada necesidad y se pueden encadenar distintas rutinas de utilizacion de herramientas de auditoria como SonarQube, ReactDoctor, entre otras. Cada agente puede tener un stack de herramientas a las que puede recurrir y eso hace que esta forma de plantear la utilización de la herramienta sea bastante flexible.
Si bien este es el inicio de una serie de artículos sobre ingeniería de agentes aplicada a Opencode creo que es una base solida para ir construyendo intuición sobre una utilización mas avanzada de la herramienta
¿Que opinas de este patron de diseño?. Dímelo en la caja de comentarios.
Top comments (0)