Agentes

Qué es un agente está en Conceptos básicos; cómo se lanza un subagente y dónde se guarda, en OpenCode y Claude Code. Aquí, cómo se escribe uno propio.

En este curso los agentes aparecen de dos formas:

• El agente principal: el que habla contigo. En OpenCode, Plan y Build; en Claude Code, la propia sesión.
• Los subagentes: agentes especializados que el principal lanza para un trozo del trabajo, cada uno con su propia ventana de contexto, sus herramientas y sus instrucciones. Esa ventana propia es la razón de fondo para usarlos, más que el paralelismo: es lo que permite abarcar un problema que no cabría en una sola conversación (patrón orquestador).

El agente organiza el trabajo: quién lo hace, con qué herramientas, en qué orden y cuándo para. El conocimiento no va en el agente: va en las skills. Así que un agente no lleva ejemplos ni convenciones del proyecto; dice qué skill cargar. La tabla completa de qué va en cada uno está en Skills.

✅ Antes de revisar, carga la skill servicios.
❌ Los servicios lanzan ErrorDeNegocio, nunca IllegalStateException... (conocimiento: va en la skill)

Un agente es un solo fichero .md: arriba el frontmatter, que cambia según la herramienta (OpenCode, Claude Code), y debajo sus instrucciones, que son iguales en las dos. Las instrucciones llevan siempre las mismas secciones, en este orden:

• Rol: quién es y qué sesgo evita. Un revisor que no se fía del resumen de quien implementó.
• Entradas: lo que le llega en el prompt, con nombre.
• Proceso: pasos numerados, un verbo cada uno.
• Criterios: cuándo está bien, cuándo mal y qué hace en la duda: fallar.
• Salida: formato cerrado, con las palabras exactas (DONE / BLOCKED). El principal compara por texto: «indícalo de alguna forma» no se puede comparar.

# Verificador de tests

Comprueba que cada requisito de la spec está cubierto por un test que pasa.

## Rol
Eres un verificador. No arreglas nada: solo dices qué falta.
No te fíes del resumen de quien implementó: comprueba en el código.

## Entradas
Te llegan en el prompt:
- `spec`: ruta del fichero de requisitos.
- `modulo`: módulo Maven donde están los tests.

## Proceso
1. Saca los identificadores de la spec (`R-1`, `R-2`...).
2. Busca en `src/test` el test que cita cada uno.
3. Ejecuta `./mvnw -pl <modulo> test`.

## Criterios
- OK: todos los requisitos tienen un test que lo cita y todos pasan.
- Fallo: un requisito sin test o un test que falla.
- En la duda: fallo.

## Salida
Primera línea, exactamente `DONE` o `BLOCKED`.
Si es `BLOCKED`, una línea por problema: `R-12: sin test`.

En el frontmatter de las dos herramientas hay tres decisiones que se toman igual:

• description: igual que en una skill, qué hace y cuándo usarlo: es lo que lee el principal para decidir si lo lanza (cómo se escribe).
• Herramientas: solo las que necesita. Si no se limitan, las tiene todas: un revisor que puede editar acaba arreglando en vez de revisar.
• Modelo: si no se pone, el del principal. Lo mecánico (verificar, contar, comprobar un formato) con el más barato: el principal no lo baja solo y gasta el caro. Lo que juzga, diseña o corrige, con el del principal.

Va en .opencode/agents/<nombre>.md, y el nombre del agente es el del fichero. opencode agent create lo crea con preguntas, pero a mano es igual de rápido.

---
description: Comprueba que cada requisito de una spec tiene un test que lo cita y
  que pasa. Usar después de implementar una funcionalidad, antes del commit.
mode: subagent
model: anthropic/claude-haiku-5-5
permission:
  edit: deny
  bash:
    "*": deny
    "./mvnw *": allow
---

Antes de empezar, carga la skill requisitos.

# Verificador de tests
...

• mode: subagent para que solo lo lance otro agente; primary para que sea un agente principal como Plan y Build. Si no se pone, vale para las dos cosas: aparece entre los principales al pulsar Tab.
• model: con el proveedor delante, proveedor/modelo, igual que en /models.
• permission: cada herramienta a allow, ask o deny. En bash se puede ir orden a orden: primero "*" y después las excepciones, porque gana la última regla que encaja.
• La skill no se puede cargar desde el frontmatter: se le pide en la primera línea del cuerpo.

Como principal, se pone mode: primary y se cambia a él con Tab, como a Plan y Build.

Va en .claude/agents/<nombre>.md. /agents lo crea con preguntas, pero a mano es igual de rápido.

---
name: verificador-tests
description: Comprueba que cada requisito de una spec tiene un test que lo cita y
  que pasa. Usar después de implementar una funcionalidad, antes del commit.
tools: Read, Grep, Bash
model: haiku
skills:
  - requisitos
---

# Verificador de tests
...

• name: obligatorio, el nombre con el que se lanza.
• tools: la lista de herramientas que puede usar.
• model: haiku, sonnet, opus o inherit (el del principal).
• skills: las skills que se cargan enteras al arrancar. Así recibe el conocimiento sin llevarlo dentro.

Como principal, para que toda la sesión siga su rol y pueda coordinar a otros:

claude --agent orquestador

Un agente que reparte el trabajo entre subagentes lo dice con números y con el orden:

• En paralelo: cuántos exactamente y que se lancen en una sola respuesta. «Lanza 3 subagentes en paralelo, uno por módulo».
• En serie si alguno puede necesitar preguntarte algo: dos preguntas a la vez no se pueden contestar.
• Los que van en paralelo no preguntan: devuelven sus dudas en la respuesta y el principal te las hace.
• Vuelven con poco: el estado y un resumen corto, o la ruta del fichero que han escrito. El contenido entero llenaría la ventana del principal, que es justo lo que se quería evitar.

En Claude Code un subagente puede lanzar a su vez otros subagentes, hasta tres niveles por debajo del principal.

Un agente sin límite da vueltas hasta gastar el plan. Siempre:

• Un criterio de terminado comprobable: los tests pasan, no «cuando esté bien» (ingeniería de bucles).
• Un límite de vueltas: «máximo 3 intentos de corrección; después, para y di qué falta».
• Cuándo parar y preguntar: «si la spec no dice qué hacer con un pedido ya enviado, para y pregunta».

Un agente también ejecuta scripts para lo determinista. Como no tiene carpeta, los scripts viven en el scripts/ de una skill y el agente los ejecuta con el comando exacto. Cómo se escriben y se citan: scripts.

• Claude Code: subagents: todos los campos del frontmatter, skills y los subagentes anidados.
• OpenCode: agents: agentes principales y subagentes, mode y permission.
• MCP vs Skills vs Agents With Scripts: Which One Should You Pick?