Cómo Escalar Agentes de Codificación AI en un Equipo de Desarrollo

Un desarrollador con un agente de codificación es una historia de productividad. Es fácil de contar, se presenta bien y es genuinamente cierto.

Cinco desarrolladores con veinte agentes es algo completamente diferente. Es un problema de coordinación, y los problemas de coordinación no se resuelven con la herramienta que los creó. Esta es la parte de la que nadie escribe, porque solo aparece después de la fase de entusiasmo: las ganancias individuales son reales, llegan de inmediato, y luego, en algún momento alrededor del tercer o cuarto desarrollador, el equipo comienza a gastar su nueva velocidad en limpiarse a sí mismo.

Lo que sigue es el orden de fallos. No una lista de mejores prácticas en abstracto, sino la secuencia en la que las cosas realmente se rompen, porque arreglarlas en el orden incorrecto desperdicia un cuarto.

Lo que se rompe primero: contexto compartido

Cada desarrollador que ejecuta un agente está enseñándole silenciosamente su propia versión de la base de código.

Una persona le dice a su agente que el proyecto utiliza acciones del servidor y nunca rutas API. Otra nunca lo menciona, así que su agente escribe rutas API. Un tercero lo menciona una vez, en una sesión que terminó hace tres días. Nadie está equivocado, nadie está mintiendo, y el repositorio ahora contiene tres interpretaciones de la misma convención. Notarás esto en la cola de revisión, que es el lugar equivocado para notarlo: para entonces, el código ya existe.

La solución es aburrida y es la cosa de mayor apalancamiento en esta página. Pon las convenciones en un archivo, compromete el archivo.

CLAUDE.md para Claude Code, AGENTS.md para Codex y la mayoría de otros agentes CLI, y en la práctica muchos equipos mantienen un archivo de contexto portátil en lugar de mantener dos que se separan. El mecanismo importa más que el nombre del archivo: las instrucciones viven en el repositorio, así que llegan con un git pull en lugar de llegar a través de quienquiera que estuviera en la sala.

Lo que debe incluir:

• Las convenciones que un agente no puede inferir al leer el código, especialmente las que la base de código actualmente viola en algunos lugares.
• Los comandos: cómo ejecutar las pruebas, la construcción, el linter, y cuáles de ellos están permitidos para ejecutarse automáticamente.
• Las partes del repositorio que son peligrosas de tocar, y por qué.
• Lo que el equipo no quiere: la refactorización que nadie pidió, la dependencia que no debe añadirse, el patrón del que se está migrando.

Lo que no debe incluir, y aquí es donde los equipos se queman: cualquier cosa específica de una máquina. Rutas absolutas, tokens API personales, puertos locales, el editor preferido de alguien. En el momento en que un valor específico de máquina aterriza en un archivo de contexto comprometido, cada otro desarrollador hereda una configuración que es incorrecta para ellos, y los agentes son extremadamente buenos siguiendo instrucciones que ya no se aplican.

Una prueba útil antes de agregar una línea: si un compañero de equipo lo extrae, ¿les ayuda o les perjudica?

Lo que se rompe segundo: dos agentes, un archivo

Los agentes no negocian. No verifican si alguien más está editando. Dos agentes apuntando al mismo módulo se sobrescribirán entre sí, y ninguno lo mencionará, porque desde el punto de vista de cada uno, el trabajo se completó con éxito.

En solitario, esto es invisible. Ejecutas un agente a la vez, o ejecutas varios y tocan cosas diferentes. En un equipo se convierte en estructural, y produce la peor clase de error: trabajo que desaparece silenciosamente entre dos ejecuciones de prueba exitosas.

Dos mecanismos lo solucionan, y quieres ambos.

Aislamiento. Git worktrees le da a cada tarea su propia copia del repositorio, así que los agentes paralelos físicamente no pueden chocar. Esta es la mitad barata de la solución y no hay razón para no hacerlo.

Propiedad. El aislamiento detiene la sobrescritura; no detiene a dos personas de resolver el mismo problema dos veces, en dos ramas, de dos maneras incompatibles. Esa se resuelve en el momento de la asignación, delimitando cada tarea a un conjunto de archivos y diciendo así en la propia tarea. No "mejorar el flujo de checkout" sino "cambiar el paso de pago, en estos tres archivos, no tocar el carrito".

La segunda mitad es la que los equipos omiten, y es la que determina si la fusión es una formalidad o una tarde.

Lo que se rompe tercero: revisión

Todo sobre la revisión a escala de equipo sigue de un número: cuántas diferencias llegan por hora.

Un desarrollador leyendo cada línea funciona bien. Cinco desarrolladores ejecutando cuatro agentes cada uno generan más diferencias por día de las que el equipo puede leer, y el resultado honesto no es una revisión cuidadosa, es un teatro de aprobación. Un humano hojeando un diff de novecientas líneas a las 6 pm produce una firma sin producir conocimiento, lo cual es peor que no revisar, porque fabrica una garantía donde no la hay.

La política que sobrevive no es "revisar todo" y no es "confiar en los agentes". Es mover la revisión a los dos límites del trabajo: leer el plan antes de que el agente comience, porque un plan incorrecto ejecutado perfectamente es el modo de fallo más costoso disponible, luego leer el diff en proporción a lo que el cambio puede romper. Copia de marketing y CSS reciben un vistazo. Autenticación, pagos, permisos, datos personales y migraciones se leen línea por línea por un humano, cada vez, independientemente de lo limpio que se vea el diff.

Esto merece su propia conversación, y lo escribimos por separado: ¿deberías seguir revisando el código de tu agente AI? repasa los diez indicadores objetivos de que un cambio salió mal, y la tabla de radio de explosión que los equipos pueden adoptar tal cual.

Una adición específica del equipo. Cuando varios agentes comparten un repositorio, la revisión necesita atribución: qué agente, qué tarea, qué desarrollador. Sin ello, un diff no tiene autor y la revisión se convierte en arqueología. Esta es la cosa más útil para arreglar en tu configuración una vez que superas tres o cuatro agentes concurrentes.

Lo que se rompe cuarto: costo, y la conversación sobre el costo

El gasto de tokens deja de ser un detalle personal en el momento en que aparece en una factura del equipo.

La trampa es que la factura es mensual y agregada, así que la conversación que produce también es mensual y agregada, lo que significa que produce una política en lugar de una solución. Alguien propone un modelo más barato para todos. Alguien más propone limitar las sesiones. Ambos son conjeturas.

La distribución real casi nunca es uniforme. Es un pequeño número de sesiones de larga duración, en uno o dos proyectos, con un contexto que creció todo el día y nunca se restableció. Ese es un comportamiento solucionable, y solo puedes arreglarlo si puedes ver el gasto por sesión y por proyecto en lugar de por mes. Cubrimos la mecánica de esto en cómo verificar el uso de tokens y cómo reducirlo sin desacelerar.

Haz que el número sea visible para las personas que lo generan, antes de que se convierta en un tema de gestión. Un desarrollador que puede ver que una sesión costó más que su día anterior completo cambia sus hábitos por su cuenta, y eso no le cuesta nada políticamente al equipo.

Lo que realmente cambia en los rituales del equipo

Tres cosas, en nuestra experiencia y en lo que los equipos informan.

El standup cambia de estado a desbloqueo. Lo que cada persona hizo ayer es en gran medida visible en las ramas. Lo que vale cinco minutos es qué agentes están atascados, y en qué.

Los prompts se convierten en activos compartidos. La instrucción que obtuvo un buen resultado para un desarrollador vale más para el equipo que el código que produjo, y es exactamente el tipo de cosa que se evapora en el historial de terminal privado. Los equipos que mantienen una biblioteca de prompts compartida en el repositorio dejan de redescubrir la misma redacción cada semana.

La especialización se mueve de personas a roles. Una vez que los agentes manejan la escritura, la pregunta interesante es quién revisa qué, y los equipos naturalmente tienden a asignar roles a los agentes de la misma manera que los asignan a las personas: uno en implementación, uno en revisión, uno en pruebas. Esa es la idea detrás de Agent Teams, donde una tarea se entrega de un rol de Dev a un rol de QA con el diff, los riesgos y las pistas de prueba adjuntas, y las puertas de calidad son decididas por tu suite de pruebas en lugar de por la propia opinión de un agente sobre su trabajo.

La configuración que se mantiene

Condensado, en el orden que importa:

Los primeros cuatro no cuestan nada más que acuerdo. Los últimos dos son la razón por la que un equipo eventualmente quiere algo más allá de la terminal: no porque las terminales sean malas, sino porque una terminal muestra un agente a la vez y no te da forma de responder "quién está ejecutando qué, en qué proyecto, ahora mismo".

Ese es el problema AgentsRoom para equipos está construido alrededor: cada agente a través de cada proyecto en una vista, con su rol, su estado y su costo adjunto, y un compañero móvil para los momentos en que el equipo no está en sus escritorios. Funciona de la misma manera con Claude Code y con Codex, lo cual importa más de lo que suena: la mayoría de los equipos terminan ejecutando ambos, y una configuración que asume un proveedor se convierte silenciosamente en la siguiente cosa que se rompe.

Comienza con el archivo de contexto, sin embargo. Es gratis, toma una tarde, y elimina más fricción que cualquier herramienta que puedas instalar este trimestre.