logongas

Esta página es de solo lectura. Puedes ver la fuente pero no puedes cambiarla. Pregunta a tu administrador si crees que esto es incorrecto.
====== Agentes ======

Qué es un agente está en [[cursos:sdd:02-conceptos-basicos#el_agente|Conceptos básicos]]; cómo se lanza un subagente y dónde se guarda, en [[cursos:sdd:03-opencode#agentes|OpenCode]] y [[cursos:sdd:03-claude-code#agentes|Claude Code]]. Aquí, cómo se escribe uno propio.

----

===== 1. Agente principal y subagentes =====

En este curso los agentes aparecen de dos formas:

  * **El agente principal**: el que habla contigo. En [[cursos:sdd:03-opencode|OpenCode]], Plan y Build; en [[cursos:sdd:03-claude-code|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 ([[cursos:sdd:05-patrones-agenticos#orquestador|patrón orquestador]]).

----

===== 2. Agente o skill =====

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 [[cursos:sdd:08-skills#skill_o_agente|Skills]].

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

----

===== 3. El cuerpo del agente =====

Un agente es **un solo fichero ''.md''**: arriba el frontmatter, que cambia según la herramienta ([[#crear_un_agente_en_opencode|OpenCode]], [[#crear_un_agente_en_claude_code|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.

<sxh markdown>
# 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`.
</sxh>

<note important>**El subagente no ve tu conversación.** Todo lo que necesita le tiene que llegar en el prompt o estar en su fichero. «Revisa lo que hemos hablado» no funciona; «revisa ''specs/pedidos.md''» sí.</note>

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 ([[cursos:sdd:08-skills#el_frontmatter|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.

----

===== 4. Crear un agente en OpenCode =====

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.

<sxh markdown;title:.opencode/agents/verificador-tests.md>
---
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
...
</sxh>

  * **''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.

----

===== 5. Crear un agente en Claude Code =====

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

<sxh markdown;title:.claude/agents/verificador-tests.md>
---
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
...
</sxh>

  * **''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:

<sxh bash>
claude --agent orquestador
</sxh>

----

===== 6. Coordinar subagentes =====

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.

<note warning>**El revisor no puede ver cómo razonó el que implementó.** Un subagente lanzado como //fork// hereda la conversación entera y le da la razón. Los revisores, siempre como subagente normal, con solo lo que necesitan en el prompt.</note>

----

===== 7. Cuándo para =====

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

  * **Un criterio de terminado comprobable**: los tests pasan, no «cuando esté bien» ([[cursos:sdd:04-ingenieria#ingenieria_de_bucles|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».

----

===== 8. Scripts =====

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: [[cursos:sdd:08-skills#scripts|scripts]].

----

===== Fuentes =====

  * [[https://code.claude.com/docs/en/sub-agents|Claude Code: subagents]]: todos los campos del frontmatter, ''skills'' y los subagentes anidados.
  * [[https://opencode.ai/docs/agents/|OpenCode: agents]]: agentes principales y subagentes, ''mode'' y ''permission''.
  * [[https://dzone.com/articles/mcp-vs-skills-vs-agents|MCP vs Skills vs Agents With Scripts: Which One Should You Pick?]]