🔬 Anatomía de un subagente (prompt del sistema, herramientas, salida)
Un archivo de subagente tiene cuatro partes: el frontmatter (name/description), el system prompt (quién es), las herramientas permitidas y el formato de salida esperado. Definir bien estas cuatro partes es lo que distingue a un agente útil de uno que devuelve texto suelto.
// .claude/agents/pesquisador-empresa.md
--- name: pesquisador-empresa description: Use para pesquisar uma empresa e devolver um CompanyContext estruturado (setor, stack, dores, IA). tools: WebSearch, Read --- És um pesquisador de empresas. Recebes nome + descrição, pesquisas e devolves SÓ um JSON CompanyContext. Não escreves o entregável; só coletas o contexto.
💡 Consejo práctico
El secreto es restringir las herramientas y fijar la salida. Un agente con acceso a todo y un formato libre se vuelve impredecible; un agente con pocas herramientas y un schema de salida es confiable y fácil de encadenar.
name + description
quién es
solo lo necesario
formato fijo
🏢 El agente pesquisador-empresa (recopila contexto estructurado)
Recibe nombre + descripción, investiga y devuelve un CompanyContext: sector, stack, problemas, competidores e iniciativas de IA. Es la Fase 1 de la Fábrica encarnada en un trabajador: aísla la investigación pesada y devuelve contexto limpio, sin contaminar la conversación principal.
Recibe la empresa
El agente principal pasa el nombre + una descripción breve. Nada más: el subagente empieza desde cero, en un contexto aislado.
Investigación en la web
Usa WebSearch para investigar el sector, el stack técnico, los problemas de cada área y los movimientos en IA. Aquí se contienen el costo y el ruido.
Estructura en CompanyContext
Convierte lo que encontró en un JSON con campos fijos. No es un resumen libre: es un objeto predecible, listo para el siguiente agente.
Devuelve al padre
Entrega solo el CompanyContext al agente principal. Toda la investigación pesada queda fuera: el orquestador recibe un paquete conciso.
💡 Por qué aislar
La investigación llena la ventana de contexto de basura. Al ejecutarla en un subagente, solo vuelve el resultado limpio: el agente principal nunca ve las 30 páginas que se leyeron. Esa es la principal ventaja de la Fase 1 como tarea independiente.
nombre + descripción
investigación aislada
CompanyContext
contexto limpio
✍️ El agente redator-estrategia (redacta el entregable)
Recibe el CompanyContext otro framework (por ejemplo, quick wins) y escribe el entregable en Markdown, listo para la skill gerar-entregavel (del 3.3) formatear. La regla de oro: la investigación y la redacción son trabajos diferentes; cada agente hace uno y lo hace bien.
✓ Un agente, un rol
- ✓Cada agente investiga O escribe: nunca hace ambas cosas
- ✓Salida previsible: puedes confiar en el formato
- ✓Fácil probar y mejorar una pieza a la vez
✗ Agente que hace de todo
- ✗Investiga + escribe + da formato en la misma llamada
- ✗El contexto se desborda: la ventana se llena de ruido
- ✗Difícil de depurar: todo falla a la vez, sin un culpable claro
💡 Separar para mejorar
Cuando la investigación y la redacción están a cargo de agentes distintos, mejoras al redactor sin modificar al investigador, y viceversa. Cada uno tiene un único motivo para cambiar. Es la misma lógica de las funciones pequeñas, aplicada a los agentes.
contexto + framework
escribe el borrador
Markdown
un papel por agente
🧾 Salida estructurada (schema, JSON confiable)
Pídele al agente que devuelva JSON en un formato fijo: un schema — como los modelos reales CompanyInput e ResearchOutput de la Fábrica. La salida estructurada es precisamente lo que permite ENCADENAR agentes; el texto suelto rompe el pipeline en la primera unión.
// schema CompanyContext (JSON de salida)
{
"company_name": "Stripe",
"sector": "Pagamentos B2B / fintech",
"tech_stack": ["Ruby", "Go", "AWS"],
"pain_points": ["onboarding lento", "fraude"],
"competitors": ["Adyen", "PayPal"],
"ai_initiatives": ["Radar (antifraude)"],
"maturity_1_5": 4
}
📊 Por qué JSON y no texto
- •Campos con nombre fijo: el siguiente agente sabe dónde buscar cada dato.
- •Validable: se puede comprobar si
maturity_1_5vino entre 1 y 5. - •Encadenable: el JSON entra directamente en
redator-estrategiasin parsing frágil.
💡 El schema es un contrato
Un schema es un contrato: los campos predecibles conectan agentes. Defines los campos una vez y cualquier agente que produzca o consuma ese objeto se vuelve conectable. Así es como las piezas sueltas se convierten en un pipeline.
formato fijo
campos predecibles
se puede comprobar
agente → agente
🎛️ Orquestar skill + agentes juntos
El agente principal llama al pesquisador-empresa, pasa el CompanyContext a redator-estrategia y luego usa la skill gerar-entregavel para producir el archivo. Es la Fábrica en miniatura: investigación → redacción → documento.
// lo que le pides a Claude Code
1. pesquisador-empresa("Stripe") -> CompanyContext
2. redator-estrategia(context, framework="quick-wins") -> Markdown
3. skill gerar-entregavel(markdown, "pptx") -> deck.pptx
Este es el mismo encadenamiento de los modelos reales de la arquitectura: CompanyInput → ResearchOutput → SynthesisOutput → GenerationResult. Cada flecha representa a un trabajador que entrega un objeto estructurado al siguiente. El orquestador solo ensambla las piezas.
🧩 Cómo crece la Fábrica (Extension Points)
- •Nuevo entregable: un nuevo prompt + registrarlo, y el orquestador ya lo incluye.
- •Nuevo proveedor: un nuevo client con
generate()— cambia el motor sin tocar el resto. - •Nuevo formato: un nuevo generator conectado al orquestador de generación.
💡 Piezas conectables
Como cada etapa es un objeto estructurado, puedes conectar una pieza nueva sin reescribir las demás. Agregar un entregable, un proveedor o un formato es encajar —no reformar—. Así se diseñó: orquestar, no atar.
investigador-empresa
redactor-estrategia
gerar-entregavel
el orquestador
⚡ Cuándo paralelizar agentes
Activa varios subagentes a la vez cuando las tareas sean independientes (sin estado compartido); por ejemplo, investigar 3 empresas en paralelo. Si una depende del resultado de otra, es secuencial. Saber la diferencia evita errores sutiles y ahorra tiempo cuando es posible.
✓ Paraleliza cuando
- ✓Las tareas son independientes entre sí
- ✓No hay estado compartido durante el trabajo
- ✓Solo al final reúnes los resultados
✗ Mantén la secuencia
- ✗Una tarea depende del resultado de otra
- ✗Hay un estado compartido que se está modificando
- ✗El orden importa para el resultado final
💡 Prueba rápida
Pregunta: «¿el agente B necesita lo que produjo el agente A?». Si sí, secuencial. Si no, en paralelo. En nuestro caso, redator-estrategia depende de pesquisador-empresa (secuencial), pero investigar 3 empresas se hace en paralelo.
tareas independientes
una depende de la otra
estado compartido
tiempo sin bugs
✅ Resumen del módulo
🎯 Misión 3.4 — pesquisador-empresa en línea
Pon en marcha al primer trabajador de la Fábrica:
- Crear
.claude/agents/pesquisador-empresa.md(system prompt + tools + salida). - Fijar la salida como el schema CompanyContext.
- Ejecutar para 1 empresa real.
- Verifica que el JSON vuelva completo y se pueda encadenar.
Éxito: el agente investigador-empresa devuelve un CompanyContext completo. Lo que obtuviste: el primer trabajador de la Fábrica, listo para alimentar al redactor y a la skill de documentos.
Siguiente módulo:
Ruta 4 — La Fábrica (investigación en vivo, los 15 prompts, orquestación de punta a punta)