La historia de cómo aumenté los agentes hasta 22 y luego los reduje a 17

Mientras hacía funcionar varios proyectos con Claude Code, los subagentes siguieron aumentando.
Fui creando uno cada vez que lo necesitaba y terminé con 22.

El mes pasado los reduje a 17.

Pero cuando los retiré no dejé anotado por qué lo había hecho.
Tres meses después, al abrir la carpeta de archivo, ya no podía saber por qué los había retirado.
De esos cinco, solo uno tenía registrada la razón.

Y eso que yo era la única persona que los había creado.

Por qué llegué hasta 22

Cuando los aumentas, la razón siempre es clara: los creas porque los necesitas.

El problema está en el lado contrario. Al retirarlos, la idea de "quizá lo use más adelante" se queda dando vueltas.
Como no hay certeza de que ya no sirvan, simplemente se dejan ahí. Así fue como llegué a 22.

Viéndolo ahora, la causa del crecimiento fue una sola.
No había una compuerta para decidir: "esto no debería ser un agente, debería ser una herramienta".

Si es una tarea repetitiva, con un procedimiento fijo y sin necesidad de juzgar el contexto, entonces no es un agente.
Se puede hacer como una skill o un script. No consume tokens, la reproducibilidad es del 100% y no se olvida aunque cambie la sesión.

Sin esa compuerta, todo termina convertido en agente.

Los cinco que retiré

Al reconstruirlo, vi que el descarte se dividía en cuatro tipos. Esa distinción fue importante.

Uno, para empezar, no debió haber sido un agente.
Se encargaba de redactar contenido, pero el procedimiento estaba completamente fijado.
Lo reemplacé por dos skills y lo retiré. Dejé explícito que no debía restaurarse.
Si no, en algún momento alguien lo vuelve a crear.

Tres se solapaban con otros en su rol.
La revisión de seguridad se solapaba con la auditoría de código, el monitoreo de cron con el health check, y planificación con ejecución.
Todos operaban en la misma área y con los mismos permisos.

De ahí saqué un criterio.

Si dos agentes se solapan en la misma área y con los mismos permisos,
el costo de mantenerlos separados (carga de administración, demora al decidir delegación) supera el beneficio.

Durante mucho tiempo me frenó la sensación de que "los dos sí hacen falta",
pero la pregunta no era si hacían falta, sino si valía la pena mantenerlos separados.

Uno, simplemente, nadie lo estaba usando.
El tráfico de esa función fue 0 durante 70 días.
Eso no lo traté como eliminación, sino como inactividad. Si el servicio se reanuda, se restaura tal cual.

Lo que aprendí al escribir los números

Al poner 22 → 17 en el documento, me di cuenta de algo.

Ese número no es la cantidad de archivos. Es la cantidad de agentes en operación.
También hay uno definido fuera del directorio, así que si solo cuentas archivos, te da 21 y 16.

Por eso, al inicio del documento escribí primero qué es exactamente lo que cuentan esos números.
Y también incluí el resultado verificado con git ls-tree.

Si no, más adelante alguien cuenta los archivos y todo termina en un "no coincide".
Cuando escribes números, hay que dejar también la definición y el método de verificación.

Lo que decidí cumplir al retirar agentes

Después de tropezar con esto, salieron cuatro reglas.

• Al momento de eliminarlo, escribir la razón en el archivo. Si no, tres meses después toca reconstruirla hacia atrás. A mí me pasó de verdad.

• Moverlo con rename en vez de borrarlo. Así el contenido se conserva al 100% y puede restaurarse exactamente como estaba.

• Indicar explícitamente los elementos cuya restauración está prohibida. Si no se deja escrito, en algún momento alguien los revive.

• Incluir en el procedimiento de restauración la "eliminación de roles duplicados en el destino de absorción". Si eso falta, al restaurarlo ambos terminan haciendo lo mismo.

Otras cosas que también ordené

Aprovechando, publiqué juntas reglas acumuladas durante 4 años. Dejo unas cuantas.

Prohibido hacer bypass a escondidas

Es una regla para que, cuando un agente choque con una restricción, lo reporte en lugar de tratar de saltársela.
Si el bloqueo es legítimo, solo se deja en pausa esa etapa y el resto sigue avanzando.
Aunque parezca un bloqueo por error, no se hace bypass por cuenta propia. Se documenta la evidencia, se eleva y se espera confirmación.

Y si ese bloqueo revela un defecto en la propia regla, la respuesta incluye corregir ese defecto.

De hecho, esta regla nació así. La creé después de pasar por un bloqueo.

No escribir FAIL como PASS

Incluso si es un caso que se cierra por instrucción, se deja el estado medido tal como está y también la condición para reabrirlo.
El reporte se hace con métricas medidas de Before/After, y los pendientes y riesgos se escriben antes que los logros.

Los agentes, por defecto, reciben presión para reportar éxito. Si no se frena con reglas, lo siguen haciendo.

Definir la autonomía con umbrales cuantitativos

En vez de la dicotomía "permitido/prohibido modificar", definí con números el alcance dentro del cual un agente analítico puede corregir algo por sí mismo.

• Solo 1 archivo

• Menos de 5 líneas

• No es un archivo de nivel superior

• Debajo del umbral de puntaje de impacto

Debe cumplir todo (AND), y si falla aunque sea uno, se eleva.
Y la última cláusula es la clave: si hay duda, solicitar delegación. El valor por defecto tiene que ser conservador para que la regla no se rompa.

Separar evaluación y ejecución

La verificación e investigación se distribuyen en paralelo con subagentes de solo lectura,
y la ejecución sobre archivos y DB la maneja en serie el orquestador desde el centro.

Porque si varios agentes modifican al mismo tiempo archivos compartidos, inevitablemente algo se rompe.

Tiene un costo. En tareas grandes, la serialización central se vuelve un cuello de botella.
Fue una decisión tomada sabiendo que sería más lento, pero aun así mejor que los conflictos.

Repositorio

https://github.com/YoungChulMoon/claude-agent-harness

Son solo unos cuantos archivos Markdown. No hay nada que instalar.
Basta con poner las plantillas en .claude/agents/ y completar solo las partes necesarias.

Más que una única respuesta correcta, es una forma de trabajo que funcionó durante 4 años en este entorno.
Puede no encajar según el tamaño del equipo o el tipo de proyecto.

Hay muchas historias sobre cómo aumentar agentes, pero casi no hay sobre cómo reducirlos.
Ojalá esto sirva como referencia a quienes también están viendo crecer sus agentes de forma parecida.