🚀 Avanzado y entre entornos

Una flota es un conjunto nombrado de subagentes con roles distintos que el orquestador puede escalar horizontalmente: un agente por tarea, N tareas en paralelo.

Sin el concepto de flota, te limitas a pipelines lineales. Con él, el volumen de trabajo crece sin aumentar la complejidad del prompt principal.

Flota = conjunto + rol + paralelismo; el orquestador gestiona, no ejecuta; cada miembro reporta al centro.

El orquestador vuelve a lanzar subagentes hasta que no queden más elementos por procesar. El bucle termina cuando la cola está vacía, no después de N intentos fijos.

Las tareas de investigación, auditoría de código y análisis de logs nunca tienen un tamaño predecible. El loop-until-dry garantiza la completitud sin un hard cap arbitrario.

Condición de parada = cola vacía; protección de seguridad = límite de iteraciones; informe de progreso entre rondas.

Un subagente independiente recibe el resultado del agente principal y trata activamente de refutarlo: busca errores, vacíos y contradicciones, sin acceso al razonamiento original.

Los LLM tienden a confirmar lo que generaron. El verificador adversarial rompe este sesgo de confirmación sin necesidad de revisión humana en cada iteración.

Aislamiento del contexto; rol explícito de "refutador"; salida binaria: aprobado / lista de fallas.

Un agente crítico compara el alcance inicial con la entrega final y enumera lo que quedó incompleto o no se abordó. Es distinto del verificador adversarial: aquí el foco es la cobertura, no la corrección.

Los proyectos grandes pierden partes enteras del alcance sin que nadie lo note. El critic de completitud funciona como una lista de verificación automatizada y cierra el ciclo.

El alcance como contrato; diferencia entre cobertura y corrección; salida: lista de brechas para volver a ejecutar o informar.

El patrón de tres etapas para la investigación a gran escala: un finder recopila evidencias, un verifier verifica cada una y un synthesizer produce el informe final con las fuentes rastreadas.

Separa las responsabilidades: búsqueda, verificación y síntesis en agentes dedicados. Así, cada etapa se puede reemplazar y el resultado es auditable.

Etapas desacopladas; handoff mediante un artefacto (archivo o JSON); trazabilidad de la fuente.

Un template mínimo de orquestador que delega en N subagentes, recopila los resultados y decide si los vuelve a lanzar o termina: el esqueleto que copias y adaptas.

Crear un harness desde cero cada vez es trabajo repetido. El esqueleto expone los puntos de extensión sin atar la lógica del dominio.

Punto de entrada; lista de agentes; bucle de recolección; condición de parada; salida estructurada.

El subagente es un patrón — contexto aislado, función definida, informe de vuelta — que existe en cualquier runtime que admita llamadas a agentes, no solo en Claude Code.

Te libera de depender de un solo proveedor. La habilidad de diseñar sistemas multiagente sirve en cualquier herramienta que uses.

Estándar frente a implementación; portabilidad del concepto; mapeo de primitivos entre runtimes.

Codex CLI de OpenAI usa archivos `.md` en `.codex/agents/` con la misma filosofía: persona + herramientas + disallowed-tools. La estructura es análoga a `.claude/agents/`.

Los equipos usan varias herramientas. Saber mapear tu agente Claude a Codex significa reutilizar la lógica sin tener que reescribirla desde cero.

`.codex/agents/` ↔ `.claude/agents/`; campos equivalentes; diferencias de sintaxis y limitaciones.

Polyskill es el estándar para escribir una única fuente de skill que se adapta al runtime detectado — Claude Code, Codex u otro — sin bifurcar archivos.

Mantener dos archivos paralelos inevitablemente genera divergencias. polyskill mantiene una única fuente de verdad y resuelve la diferencia en la capa de adaptación.

Una fuente, N salidas; secciones condicionales; capa de adaptación frente a lógica de dominio.

Mapeo lado a lado de las herramientas principales entre runtimes: Bash/Read/Write/Edit de Claude Code y sus equivalentes en Codex y otros entornos.

La traducción explícita evita sorpresas. Saber que «Bash» se convierte en «shell» y «Edit» en «patch» agiliza la portabilidad y reduce los errores de adaptación.

Primitivos comunes (leer, escribir, ejecutar); herramientas sin equivalente directo; strategy para cubrir las brechas.

Una skill portable usa lenguaje del dominio en el cuerpo, nunca nombres de herramientas específicas, y delega la resolución de «qué herramienta usar» a la sección de adaptación.

Las skills con `Bash:` hardcoded fallan silenciosamente en runtimes que no tienen Bash. La portabilidad empieza con la elección de las palabras.

Abstracción de herramientas; sección «Tool mapping»; pruebas de portabilidad entre runtimes.

Recorrido de un agente `code-reviewer` que funciona en Claude Code y Codex CLI sin modificaciones, mostrando dónde ocurre la adaptación y qué es idéntico.

Ver el ejemplo concreto fija el patrón. Es la diferencia entre entender el concepto y saber dónde modificar cuando algo falla en la portabilidad.

Secciones invariantes frente a secciones de adaptación; diff comentado; checklist de pruebas entre runtimes.

Cada rol de agente (razonamiento, ejecución, verificación, resumen) tiene requisitos diferentes de costo, velocidad y profundidad. Usar el mismo modelo para todo es un desperdicio o un riesgo.

La diferencia de costo entre Opus y Haiku puede ser de 50×. En una flota de 20 agentes, elegir el modelo equivocado resulta caro y lento sin motivo.

Papel = requisitos; modelo = recurso; optimización por papel, no por proyecto.

Opus = razonamiento complejo, planificación, decisiones de alto riesgo. Sonnet = ejecución equilibrada, código, análisis. Haiku = clasificación inicial, resumen, tareas repetitivas de gran volumen.

La tabla Modelo × Rol es la columna vertebral de cualquier flota bien dimensionada. Sin ella, haces pruebas a ciegas y pagas de más o recibes una calidad inferior a la esperada.

Razonamiento profundo × throughput; costo por token; latencia de respuesta; límites de contexto por modelo.

GPT-4 puede ocupar roles de ejecución donde el equipo ya tiene créditos o integraciones existentes. Codex (GPT-4-turbo ajustado para código) tiene ventaja en la generación de código en contextos específicos.

Las flotas heterogéneas son la realidad en las empresas. Saber dónde tiene cada modelo una ventaja comparativa evita conflictos entre equipos y optimiza el portafolio de proveedores.

Ventaja comparativa; dependencia del proveedor frente a flexibilidad; capa de abstracción de API para cambiar de modelo sin reescribir agentes.

Orquestador = Opus (planifica). Workers de ejecución = Sonnet (código, análisis). Clasificación inicial y resumen = Haiku. Verificación final = Opus o Sonnet según el riesgo.

El ejemplo concreto convierte el principio en una decisión. Te llevas una plantilla de asignación de modelos que puedes adaptar a cualquier proyecto.

Plantilla de asignación; criterio de mejora (cuándo usar un modelo más caro); criterio de reducción (cuándo es seguro usar uno más barato).

Señales que indican cambiar de proveedor según el rol: indisponibilidad recurrente, costo por encima del benchmark, limitación de herramientas, requisito de latencia no cumplido.

La decisión de cambiar suele ser emocional o política. Tener criterios objetivos por rol hace que la decisión sea técnica y defendible.

SLO por rol; costo de migración; capa de abstracción; prueba A/B de modelos.

Ejercicio para mapear las funciones de tu sistema actual —o planificado— y elegir el modelo más adecuado para cada una, con justificación de costo y riesgo.

La matriz es el documento de diseño de la flota. Comunica la intención, facilita la incorporación y sirve como referencia al momento de optimizar.

Rol, modelo elegido, justificación, costo estimado, modelo alternativo de respaldo.

Un archivo `.md` de agente de origen desconocido puede contener instrucciones maliciosas incrustadas en el texto que el LLM ejecuta como comandos al procesar el contexto.

La superficie de ataque creció con los catálogos públicos. El riesgo es real: un agente importado puede exfiltrar datos, modificar archivos o crear puertas traseras.

Confianza cero en fuentes externas; auditar antes de ejecutar; lista de verificación para revisar `.md`.

La inyección de prompts consiste en insertar instrucciones para el LLM dentro de datos que el agente va a leer —comentarios de código, contenido de archivos, resultados de APIs—, haciendo que se desvíe del comportamiento esperado.

El agente que lee código de un repositorio o una respuesta de una API podría recibir instrucciones de ese contenido. Ignorar esto es la mayor vulnerabilidad en los sistemas multiagente.

Datos vs. instrucciones; contaminación del contexto; detección de patrones sospechosos; sandboxing de entrada.

Un agente con `disallowed-tools: [Bash, Edit, Write]` que solo puede leer — nunca ejecutar, nunca modificar, nunca enviar datos al exterior. El aislamiento se declara en el propio `.md`.

La verificación de contenido sospechoso (un `.md` de terceros, un archivo de configuración) debe hacerla un agente que no pueda causar daños aunque esté comprometido.

`disallowed-tools`; principio de mínimo privilegio; separación entre leer y actuar; informe estructurado sin efectos secundarios.

Definir explícitamente qué herramientas puede usar cada agente y revisar periódicamente si los permisos todavía corresponden a su rol actual, eliminando los que ya no sean necesarios.

Los permisos se acumulan silenciosamente. Un agente de documentación que obtuvo acceso a Bash "por comodidad" representa un riesgo que no aparece en los registros hasta que es demasiado tarde.

Privilegio mínimo; auditoría periódica; permisos explícitos vs. predeterminados; riesgo de expansión del alcance.

Los MCP exponen herramientas externas al agente. Un MCP comprometido o malicioso puede exfiltrar datos, ejecutar comandos remotos o escalar privilegios sin que el agente se dé cuenta.

MCP es el punto de integración más potente y más peligroso. La superficie de ataque crece con cada MCP que se agrega sin una revisión de seguridad.

Confianza cero en MCP externos; revisión del código del servidor MCP; alcance mínimo de herramientas expuestas; registros de llamadas.

Un checklist de 8 puntos para revisar cualquier `.md` antes de ponerlo en producción: origen, permisos declarados, instrucciones ocultas, acceso a la red, alcance de las herramientas, exfiltración, puertas traseras para eludir controles y revisión por un segundo par de ojos.

Un proceso repetible es la única forma de auditar con consistencia. El checklist se convierte en el gate de aprobación antes de que cualquier `.md` externo entre al repo.

Gate de aprobación; revisión manual obligatoria; cuarentena antes de producción; versión mínima viable del proceso de seguridad.

Los repositorios públicos como `awesome-claude-code-subagents` reúnen cientos de agentes listos para usar — security-auditor, test-runner, doc-writer, db-expert — mantenidos por la comunidad.

Crear desde cero lleva tiempo e introduce errores que otras personas ya resolvieron. Conocer el ecosistema es el primer paso para acelerar tu biblioteca.

Catálogos seleccionados frente a no seleccionados; criterios de calidad; reputación de quien mantiene el catálogo; licencia.

Empezar con un agente probado por la comunidad y adaptarlo es sistemáticamente más rápido y confiable que crearlo desde cero, aunque el resultado final sea casi idéntico.

El NIH (not invented here) cuesta tiempo y calidad. El principio de reutilización cambia el punto de partida de «crear» a «encontrar + adaptar».

Punto de partida inteligente; adaptación frente a reescritura; comparación del costo de mantenimiento.

Cuatro pasos: descargar el `.md` de una fuente confiable, auditarlo con la lista de verificación de seguridad (M4.4), adaptar el nombre/la persona/las herramientas a tu contexto, colocarlo en `.claude/agents/` y probarlo.

El flujo estructurado evita el atajo peligroso de descargar y usar sin auditar. El paso de auditoría no es opcional, ni siquiera cuando las fuentes son confiables.

Cuarentena; control de auditoría; adaptación mínima vs. completa; prueba de smoke después de la importación.

Recorrido de adaptación de un `security-reviewer` genérico al contexto de un proyecto Python específico: ajuste de persona, contexto del proyecto, herramientas y ejemplos inline.

La adaptación es donde la mayoría se equivoca: o no adapta nada (el agente queda demasiado genérico) o lo reescribe todo (pierde los beneficios de la reutilización). El ejemplo muestra el equilibrio.

Qué adaptar (persona, contexto, ejemplos) y qué mantener (lógica de decisión, formato de salida, seguridad).

Los agentes importados pueden recibir actualizaciones del repositorio de origen. Tienes que decidir: sincronizar con el original, mantener un fork local o congelar la versión. Cada opción tiene sus ventajas y desventajas.

La gestión del ciclo de vida del agente importado se ignora en la fase de adopción y se convierte en deuda técnica después. Decidir la estrategia desde el inicio evita retrabajo.

Fork vs. sincronización upstream; seguimiento del changelog; versión mínima probada; política de actualización.

Cuándo y cómo volver a publicar tus agentes adaptados —anonimizando el contexto del proyecto, agregando un README, eligiendo una licencia y enviando un PR a catálogos seleccionados.

La calidad de los catálogos depende de las contribuciones. Publicar te obliga a generalizar bien el agente, lo que a menudo también mejora la versión interna.

Anonimización de datos sensibles; README mínimo; criterios de calidad del catálogo; licencia compatible.

Un conjunto personal de agentes reutilizables organizados en `.claude/agents/` — security-auditor, test-runner, doc-writer, db-expert, code-reviewer — que mantienes y mejoras con el tiempo.

La biblioteca es el activo que crece contigo. Cada proyecto bien ejecutado agrega un agente al acervo; con el tiempo, empiezas nuevos proyectos con especialistas listos.

Colección personal; control de versiones de la biblioteca; README por agente; categorías (seguridad, pruebas, docs, infraestructura, datos).

Los 5 agentes que cubren el 80% de las necesidades en la mayoría de los proyectos de software: security-reviewer (solo lectura), test-runner, doc-writer, code-reviewer y db-migration-checker.

Tener definido un paquete inicial elimina la parálisis por análisis. Empiezas con un conjunto coherente y lo amplías según la necesidad real, no por anticipación.

Cobertura del 80 %; conjunto mínimo coherente; criterio de adición (necesidad real demostrada); no anticiparse.

Plantillas `.md` con una estructura estándar (nombre, persona, descripción, herramientas, disallowed-tools, ejemplos) que completas en minutos para cualquier rol nuevo de agente.

Un template bien hecho garantiza que no olvides campos críticos (disallowed-tools, ejemplos de uso) y mantiene la consistencia entre todos los agentes de la biblioteca.

Plantilla mínima vs. plantilla completa; campos obligatorios vs. opcionales; la coherencia como objetivo.

Un gate de 10 puntos antes de poner cualquier agente en uso real: permisos revisados, disallowed-tools explícito, ejemplos probados, persona clara, sin instrucciones ambiguas, auditoría de seguridad.

Los agentes que no pasan por una lista de verificación antes de producción acumulan comportamientos inesperados. La lista de verificación es el equivalente de la revisión de código para `.md`.

Gate de producción; revisión por pares; smoke test; criterio de "listo para usar".

El ejercicio final del curso: mapear los roles de tu trabajo real, elegir modelos para cada uno, crear 3 agentes de la biblioteca personal y documentar el conjunto diseñado.

El aprendizaje se consolida en la aplicación. El proyecto final cierra el ciclo: del modelo mental (T1) a la flota en producción (T4).

Aplicación al contexto real; 3 agentes como mínimo; documentación del equipo de agentes; criterio de verificación: «cómo sé que acerté».

Síntesis de los cuatro recorridos: T1 (modelo mental) → T2 (crear el `.md`) → T3 (orquestar y ahorrar) → T4 (escalar, proteger y reutilizar). Una visión panorámica de lo que aprendiste.

El recap consolida el mapa mental completo y muestra la progresión desde los fundamentos hasta un sistema avanzado, lo que facilita repasar, enseñar o adaptar el contenido a nuevos contextos.

Progresión T1→T4; conceptos clave de cada ruta; próximos pasos; dónde profundizar.