tderoussel/fleet-brief

Fleet brief

Agentes paralelos falham em terreno compartilhado — duas lanes editando um mesmo arquivo. O resumo existe para tornar essa colisão impossível antes do despacho. Derive os limites a partir do mapa de arquivos real; nunca os suponha.

Construa o resumo nesta ordem

1. Mapeie os arquivos primeiro

Antes de definir as lanes, liste os arquivos que cada mudança proposta tocaria. Leia-os. Uma lane definida sem ler seus arquivos é uma colisão à espera de acontecer.

2. Atribua propriedade exclusiva

Cada arquivo tem exatamente uma lane proprietária. Produza esta tabela:

Lane	É dona (escreve)	Apenas lê
W1 —	path/a.ts, path/b.ts	path/shared.ts

Se duas lanes precisam escrever um mesmo arquivo, você tem três opções — escolha uma explicitamente, nunca a deixe ambígua:

• Sequencie (W2 espera o merge de W1)
• Agrupe em uma única lane
• Costure: uma lane adiciona um ponto de extensão, a outra o consome

3. Nomeie o terreno compartilhado

Liste todo arquivo que mais de uma lane lê e declare quem pode escrevê-lo.

Derive esta lista da base de código à sua frente — não traga a lista de outro projeto. Os padrões recorrentes que vale a pena verificar:

• O caminho de entrada ativo. Tudo que recebe webhooks ou tráfego de usuários. Edições concorrentes aqui falham em produção, não em testes.
• Módulos de engine e dispatcher que várias funcionalidades chamam.
• Manifestos apenas de adição — configs de deploy, tabelas de rota, listas de funções. Plataformas impõem limites (contagens de funções, tamanhos de arquivo); duas lanes adicionando independentemente podem violá-los.
• Exportações amplamente importadas. Estenda de forma aditiva; uma renomeação se propaga por todos os chamadores.
• Arquivos gerados ou vindos de fornecedor que nenhuma lane deve editar manualmente.

Um arquivo que já causou colisão uma vez é terreno compartilhado permanentemente. Registre-o no resumo para que a próxima frota herde o conhecimento.

4. Derive a lista DO-NOT

Cada DO-NOT nomeia um arquivo ou comportamento e o motivo. Proibições nuas são ignoradas; as fundamentadas se mantêm.

Entradas que se generalizam na maioria das bases de código:

• Nunca git add -A durante resolução de conflitos — ele adiciona marcadores de conflito e trabalho de outras lanes.
• Workers não fazem commit em worktrees vinculados; o orquestrador faz o commit.
• Se o conjunto de testes simular o banco globalmente, um teste unitário verde não prova nada sobre o banco. Diga isso explicitamente.
• Não adicione dependências sem uma justificativa de uma linha.
• Não aplique migrações de esquema de dentro de uma lane. Adie-as para uma única etapa revisada.
• Cuidado com chamadas de CLI que falham silenciosamente — ex. gh pr create precisa de um --base explícito, e heredocs encadeados podem engolir erros.

Em seguida, adicione as específicas do projeto. Todo incidente que lhe custou uma noite pertence aqui, com seu motivo anexado.

5. Defina o portão

Declare explicitamente, por lane: o que significa 'pronto', qual evidência prova isso e quem revisa antes do merge.

O padrão que vale a pena manter é revisão-antes-da-publicação — build, depois revisão independente de linha, depois rodadas de correção obrigatória, depois merge. Nunca faça merge de uma lane apenas com a aprovação de seu próprio autor. O agente do autor é o pior revisor possível de sua própria diff.

6. Marque o que está retido

Uma seção Deliberadamente NÃO feito — precisa de um humano. Itens retidos para um aval explícito são retidos de propósito. Não deixe uma lane executar um deles só porque parece pronto.

Isolamento

Execute builds em worktrees do git, nunca no checkout principal — uma frota que compartilha um diretório de trabalho vai intercalar edições. Se lanes modificarem arquivos sobrepostos apesar do mapa, dê a cada uma seu próprio worktree.

Dimensionamento

Lanes devem ser mergeáveis independentemente. Se uma lane não puder fazer merge sem a PR de outra lane, não é uma lane — é uma fase. Sequencie fases; paralelize lanes.

Saída

Escreva o resumo onde quer que o projeto mantenha seus planos, e abra-o com um aviso de 'verifique, nunca suponha'. Linhas de status em qualquer documento fonte são pontos de verificação, não autoridade — verifique novamente o commit atual, o estado do banco de dados, as verificações da PR e as cabeças dos worktrees antes de despachar com base neles.