Fleet brief (Informe de flota)
Los agentes paralelos fallan en terreno compartido — dos carriles editando el mismo archivo. El informe existe para hacer imposible esa colisión antes del despacho. Deriva los límites del mapa de archivos real; nunca los supongas.
Construye el informe en este orden
1. Mapea los archivos primero
Antes de definir los carriles, lista los archivos que cada cambio propuesto tocaría. Léelos. Un carril definido sin leer sus archivos es una colisión a punto de ocurrir.
2. Asigna propiedad exclusiva
Cada archivo tiene exactamente un carril propietario. Genera esta tabla:
| Carril | Propiedad (escribe) | Solo lectura |
|---|---|---|
| W1 — | path/a.ts, path/b.ts | path/shared.ts |
Si dos carriles necesitan escribir un mismo archivo, tienes tres opciones — elige una explícitamente, nunca la dejes ambigua:
- Secuencializarlos (W2 espera al merge de W1)
- Colapsarlos en un solo carril
- Unirlos con costura: un carril añade un punto de extensión, el otro lo consume
3. Nombra el terreno compartido
Lista cada archivo que más de un carril lee, e indica quién puede escribirlo.
Deriva esta lista del código base que tienes delante — no arrastres la lista de otro proyecto. Las formas recurrentes que vale la pena revisar:
- La ruta entrante en vivo. Todo lo que recibe webhooks o tráfico de usuarios. Las ediciones concurrentes aquí fallan en producción, no en pruebas.
- Módulos de motor y despachador a los que llaman varias funcionalidades.
- Manifiestos de solo adición — configuraciones de despliegue, tablas de rutas, listas de funciones. Las plataformas imponen límites (conteo de funciones, tamaños de archivo); dos carriles añadiendo independientemente pueden sobrepasarlos.
- Exportaciones ampliamente importadas. Extiende de forma aditiva; un renombrado se propaga a todos los llamadores.
- Archivos generados o empaquetados que ningún carril debería editar a mano.
Un archivo que ha causado una colisión una vez es terreno compartido permanentemente. Regístralo en el informe para que la próxima flota herede el conocimiento.
4. Deriva la lista DO-NOT
Cada DO-NOT nombra un archivo o comportamiento y la razón. Las prohibiciones sin fundamento se ignoran; las fundamentadas se mantienen.
Entradas que se generalizan en la mayoría de los códigos base:
- Nunca uses
git add -Adurante la resolución de conflictos — añade los marcadores de conflicto y el trabajo de otros carriles. - Los trabajadores no hacen commit en worktrees vinculados; el orquestador hace commit.
- Si el suite de pruebas simula la base de datos globalmente, una prueba unitaria verde no prueba nada sobre la base de datos. Dilo explícitamente.
- No añadas dependencias sin una justificación de una línea.
- No apliques migraciones de esquema desde dentro de un carril. Diferelas a un único paso revisado.
- Cuidado con las llamadas de CLI que fallan silenciosamente — por ejemplo,
gh pr createnecesita un--baseexplícito, y los heredocs encadenados pueden tragar errores.
Luego añade las específicas del proyecto. Cada incidente que te costó una noche pertenece aquí, con su razón adjunta.
5. Establece el gate
Indica explícitamente, por carril: qué significa «terminado», qué evidencia lo prueba y quién revisa antes del merge.
El valor predeterminado que vale la pena mantener es revisión antes de producción — compilar, luego revisión de línea independiente, luego rondas de correcciones obligatorias, luego merge. Nunca fusiones un carril solo por la palabra de su propio autor. El agente del autor es el peor revisor posible de su propio diff.
6. Marca lo que está retenido
Una sección Deliberadamente NO hecho — necesita un humano. Los elementos retenidos para una autorización explícita se retienen a propósito. No dejes que un carril ejecute uno porque parece listo.
Aislamiento
Ejecuta las compilaciones en git worktrees, nunca en el checkout principal — una flota que comparte un directorio de trabajo intercalará ediciones. Si los carriles mutan archivos superpuestos a pesar del mapa, dale a cada uno su propio worktree.
Tamaño
Los carriles deben poder fusionarse independientemente. Si un carril no puede fusionarse sin el PR de otro carril, no es un carril — es una fase. Secuencializa las fases; paraleliza los carriles.
Salida
Escribe el informe donde sea que el proyecto guarde sus planes, y ábrelo con una advertencia de «verificar, nunca asumir». Las líneas de estado en cualquier documento fuente son puntos de control, no autoridad — vuelve a comprobar el commit en vivo, el estado de la base de datos, las comprobaciones de PR y las cabezas de worktree antes de despachar contra ellos.