# 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.

- Por: Djan Magno
- Publicado em: 2026-09-27
- Atualizado em: 2026-09-27
- URL: https://t25.io/blog/limites-de-diff-agentes/
- Engenharia · diff, limites de mudança, agentes de código, política, revisão de código

> **Resumo:** > - Limite de diff é uma regra do pipeline que barra uma implementação se ela alterar arquivos ou linhas acima do teto configurado.
> - O T25 também pode medir repetição de linhas em arquivos de produção. Testes ficam fora dessa métrica.
> - Ao exceder um limite, a task falha e recebe um resumo de handoff; o sistema não reduz o diff automaticamente.
> - Esses limites controlam o tamanho e um sinal de duplicação. Eles não provam que o código está correto ou seguro.

## 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](https://t25.io/blog/o-approve-do-modelo-nao-e-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:

```yaml
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](https://t25.io/blog/uma-ordem-um-worktree-isolando-agentes-de-codigo/). Os nomes e descrições das opções estão na [referência de configuração](https://t25.io/docs/).

## 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.