====== 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]]. ✅ Antes de revisar, carga la skill servicios. ❌ Los servicios lanzan ErrorDeNegocio, nunca IllegalStateException... (conocimiento: va en la skill) ---- ===== 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. # 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 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`. **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í. 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/.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. ---- ===== 5. Crear un agente en Claude Code ===== Va en ''.claude/agents/.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 ---- ===== 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. **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. ---- ===== 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?]]