Mi primer subagente real — y por qué no es una skill

Llevo tres semanas construyendo agentdeck en público. Hasta esta semana, el "equipo de agentes Claude Code" del que hablo en cada email era una hipótesis. Cero agentes activos. Lo decía en los repos sin maquillarlo: el primero llega en la semana 3.

Es la semana 3. Aquí está.

Pero antes de enseñártelo, la decisión que me costó más que escribirlo.

Desde la semana 1 agentdeck tiene una skill llamada arch-guard. Define las reglas de arquitectura y tipado del proyecto, y Claude Code la carga automáticamente cada vez que se toca un archivo .ts.

Cuando llegó el momento de crear el primer agente, mi primera reacción fue: "pues otra skill, como arch-guard, pero para construir pantallas".

Estuve a punto. Y habría estado mal.

La diferencia, en una frase: una skill es contexto que se mete en quien ya está trabajando. Un subagente es alguien distinto a quien le delegas un trabajo.

arch-guard no "hace" nada. Es un conjunto de reglas que se inyectan en la conversación cuando aplican, para que quien escribe el código no se salte la arquitectura. Es un guardia, no un trabajador.

Lo que yo necesitaba para construir pantallas es un trabajador: alguien que coja "constrúyeme el detalle de un agente" y lo haga entero, mirando el design system, sin que yo le tenga que repetir cada vez cómo se hace una página en este proyecto. Eso es un subagente.

La regla que me llevo: si lo que quieres es defender una norma en todo el código, es una skill. Si lo que quieres es delegar una tarea completa a un especialista, es un subagente. No compiten. En agentdeck conviven: el View Builder construye la pantalla, arch-guard vigila que no se salte el tipado mientras lo hace. Planos distintos.

Cuatro decisiones, todas en la misma dirección: un especialista estrecho es más útil que un generalista.

Uno — foco quirúrgico. El View Builder construye páginas, layouts y componentes presentacionales. No diseña la base de datos, no escribe la lógica de negocio, no toca las APIs. Si una pantalla necesita un dato que no existe todavía, se detiene y lo pide en lugar de inventarse la query. Esto suena a limitación. Es lo contrario: un agente que sabe dónde está su frontera no mete la pata fuera de ella.

Dos — herramientas acotadas. Tiene Read, Write, Edit, Grep, Glob y Bash (este último solo para correr el linter). No tiene acceso a internet ni puede invocar a otros agentes. Cuantas menos herramientas, menos formas de que un agente "se pase de listo".

Tres — Sonnet, no Opus. Construir UI siguiendo un design system ya establecido no necesita el modelo más caro. Reservo Opus para donde de verdad aporta. Un equipo de agentes que usa siempre el modelo top es un equipo caro y lento sin motivo.

Cuatro — checklist antes de cerrar. Igual que arch-guard, el agente repasa una lista antes de dar por terminado un cambio: ¿está en el grupo de rutas correcto? ¿es server component por defecto? ¿el empty state explica algo o solo dice "no data"? ¿pasa el linter? Un agente sin checklist es un agente que te entrega cosas a medias con buena cara.

No vale decir "tengo un agente" y enseñar el archivo .md. Eso es una hipótesis otra vez.

Le pedí que construyera la pantalla de detalle de un agente individual: cuando escaneas un repo, ahora puedes hacer click en cualquiera de sus agentes y ver su contenido completo, su frontmatter, sus herramientas. La construyó a la primera, respetando el diseño del resto de la app sin que yo le pasara ni una referencia visual.

Funciona. Es un hecho verificado, no una promesa de newsletter.

Esto es lo que más me gusta de construir de verdad en lugar de hablar de construir.

Al navegar a esa pantalla nueva en un repo con 184 agentes (un repo público ajeno que uso como banco de pruebas), la página tardaba 3-4 segundos en cargar. Lento de manera molesta.

El instinto de mucha gente aquí es: "hay demasiados elementos en la lista, hay que paginar". Me paré a medir antes de añadir paginación. Y el problema no era la cantidad de elementos. Era la cantidad de bytes por elemento.

La lista estaba pidiendo, por cada uno de los 184 agentes, su contenido completo: el markdown entero, el frontmatter parseado, todo. Multiplica eso por 184 y son varios megas de HTML viajando al navegador para una vista que ni siquiera mostraba ese contenido (las tarjetas son solo enlaces; el contenido vive en la pantalla de detalle).

La solución no fue paginación. Fue separar dos cosas que tenía mezcladas: la consulta para la lista (solo lo que se ve en cada tarjeta) y la consulta para el detalle (todo). Cambié la lista a una consulta ligera. La página pasó a cargar al instante. Sin paginación, sin carga perezosa, sin componentes nuevos.

La regla que me llevo: antes de paginar, mide si el problema es cuántos elementos tienes o cuántos bytes pesa cada uno. Casi siempre es lo segundo, y lo segundo se arregla mucho más barato.

Repo público: github.com/devsdm99/agentdeck

El equipo de seis agentes sigue siendo en parte hipótesis. Pero ya tiene a su primer miembro de pleno derecho, con su trabajo, sus límites y su modelo. La semana 4 va a por el segundo.

Semana 4 — hooks: cómo evito que dos agentes editen el mismo archivo a la vez. El problema clásico cuando el equipo deja de tener un solo miembro.

Si te interesa cómo se orquesta un equipo de agentes sin que se pisen entre ellos, nos leemos el martes que viene.

— Sergio