Teto de diff: como parar um agente que reescreve o repositório
Limites de arquivos, linhas e duplicação ajudam a manter a implementação perto do escopo pedido.
Read in English Versão em Markdown
O que um teto de diff faz
Um teto de diff é um limite configurável para o tamanho de uma implementação. No T25, max_files_changed limita quantos arquivos a task pode alterar e max_diff_lines limita as linhas de diff. max_duplicate_line_ratio acrescenta uma verificação contra repetição excessiva em arquivos de produção.
Essas regras não entendem a intenção do código. Servem para chamar atenção quando uma mudança cresce além do que o projeto está disposto a revisar em uma única tarefa. A revisão de findings e o gate humano continuam necessários; veja por que o APPROVE do modelo não é o merge.
Os limites padrão
No momento, os valores padrão documentados são:
| Chave | Padrão | O que conta |
|---|---|---|
max_files_changed |
40 | Arquivos alterados pela task |
max_diff_lines |
2000 | Linhas alteradas no diff |
max_duplicate_line_ratio |
0.5 | Maior razão de linhas duplicadas entre arquivos de produção |
A razão de duplicação é calculada por arquivo e a maior razão é comparada ao teto. Arquivos de teste em test/, tests/, ou com nomes .test. e .spec. não entram nessa conta. Em modo bootstrap, o T25 pula somente essa métrica; os limites de arquivos e linhas continuam valendo.
Ajuste os limites ao tamanho do seu projeto
O bloco limits no t25.yaml permite ajustar esses valores:
limits:
max_files_changed: 40
max_diff_lines: 2000
max_duplicate_line_ratio: 0.5
Esses números são os padrões documentados, não uma receita para todo repositório. Se o seu time revisa tarefas menores, reduza os tetos. Se uma tarefa legítima precisa passar deles, prefira dividir o trabalho em entregas revisáveis antes de abrir a exceção. Um teto mais alto aceita diffs maiores; um teto muito baixo pode rejeitar trabalho válido.
O que acontece quando o limite é ultrapassado
Depois da implementação, o T25 coleta as estatísticas do workspace e compara cada métrica configurada com seu limite. Se alguma regra falhar, grava um artefato handoff.md com o motivo e os números observados e marca a task como falha. O agente não segue silenciosamente para QA como se o diff estivesse dentro da política.
O handoff explica o bloqueio para que a equipe decida o próximo passo. Pode reduzir o escopo, dividir a tarefa ou revisar o limite do projeto. A fábrica não corta arquivos do diff nem altera os limites por conta própria.
O T25 registra a falha e o handoff para a equipe decidir o próximo passo. Consulte o estado da tarefa e os artefatos disponíveis no seu ambiente antes de retomar o trabalho.
O que essa barreira não verifica
Um diff pequeno ainda pode conter um bug sério, uma regressão ou uma falha de segurança. E uma mudança grande pode ser necessária para uma migração ou uma tarefa de bootstrap. Por isso, teto de diff complementa spec, testes, QA, review e controles de risco; não substitui nenhum deles.
Para separar cada tarefa em uma branch e worktree próprios, veja uma ordem, um worktree. Os nomes e descrições das opções estão na referência de configuração.
Perguntas frequentes
O T25 apaga ou reverte o diff quando o teto é excedido?
Não. A task falha e recebe um resumo de handoff. A equipe decide se reduz o escopo, divide o trabalho ou ajusta a política.
As linhas dos arquivos de teste contam?
Elas contam para max_diff_lines. Ficam excluídas apenas do cálculo de max_duplicate_line_ratio.
O modo bootstrap ignora todos os limites?
Não. Ele pula a verificação de duplicação; limites de arquivos e de linhas continuam ativos.
Um diff dentro do teto está pronto para merge?
Não. O teto mede tamanho e, opcionalmente, repetição. QA, revisão e o gate humano ainda precisam fazer seu trabalho.
Devo aumentar o teto para uma tarefa grande?
Considere primeiro dividir a tarefa. Se o escopo maior for legítimo, ajuste a política do projeto deliberadamente e mantenha a revisão humana do resultado.