Capítulo 7 — Decomposição: desenhe a mudança antes de distribuir trabalho

Dividir trabalho não é o mesmo que decompor um sistema

Quando geração de código fica barata, parece natural aumentar o paralelismo.

Uma feature vira quatro subtarefas. Quatro subtarefas viram quatro agentes. Quatro agentes parecem significar quatro vezes mais velocidade.

O problema é que software não é uma pilha de tarefas independentes por padrão.

Uma mudança atravessa conceitos de domínio, dependências, estados, contratos e efeitos colaterais.

Se a divisão ignora essas relações, o paralelismo apenas distribui a inconsistência.

McEntire coloca a decomposição no centro da arquitetura: decidir as partes significa decidir onde ficam as fronteiras e os pontos de integração que determinarão se o conjunto consegue compor corretamente. ¹

A primeira decisão, portanto, não é quantos agentes usar.

É onde uma parte do trabalho pode realmente terminar sem obrigar a próxima parte a reconstruir tudo que veio antes.

A fronteira boa reduz informação compartilhada

Uma fronteira útil não é escolhida porque divide o número de arquivos de forma equilibrada.

Ela é útil quando separa responsabilidades com pouco conhecimento mútuo.

McEntire descreve natural information boundaries como pontos em que o acoplamento diminui e a interface pode ser especificada com poucas suposições. Uma interface estreita permite que cada lado seja implementado e testado contra um contrato sem conhecer os detalhes internos do outro. ²

Essa ideia oferece uma regra prática para trabalho agêntico:

decomponha onde o contrato entre as partes for menor que a complexidade que ele separa.

Se dois agentes precisam compartilhar:

detalhes internos de estado;
convenções implícitas;
decisões ainda não registradas;
muitos tipos mutáveis;
conhecimento de implementação um do outro;

então talvez não existam duas tarefas independentes.

Talvez exista uma única mudança artificialmente partida.

Decomposição começa no domínio

O capítulo anterior transformou intenção em Spec.

Mas uma Spec ainda pode conter trabalho grande demais para uma única execução.

É aqui que Domain e Architecture voltam a aparecer.

Antes de distribuir, precisamos perguntar:

quais capacidades do domínio são realmente separáveis?
quais invariantes atravessam a mudança?
onde os dados mudam de responsabilidade?
quais estados precisam ser compartilhados?
quais interfaces já existem?
quais interfaces seriam inventadas apenas para permitir paralelismo?

O objetivo não é maximizar o número de tarefas.

É encontrar unidades que possam ser compreendidas, verificadas e integradas sem reconstrução excessiva de contexto.

Paralelo só quando a dependência permite

Há trabalho que pode acontecer em paralelo.

Há trabalho que apenas parece paralelizável quando visto de longe.

McEntire chama atenção para a perda de informação nos handoffs: o resultado entregue por um agente é uma representação comprimida do raciocínio, das alternativas descartadas e das restrições descobertas durante a execução. ³

Por isso, quando o passo B depende do estado produzido por A, forçar A e B a acontecerem simultaneamente cria previsão onde deveria existir observação.

No método deste livro, classificamos uma decomposição inicialmente como:

Independente

Duas partes podem avançar sem conhecer decisões internas uma da outra.

Exemplo estrutural:

contrato já definido;
dados de entrada/saída definidos;
testes de interface disponíveis;
nenhum estado intermediário compartilhado.

Sequencial

A saída de uma etapa determina o contexto ou estado da próxima.

A segunda parte deve começar depois que a primeira produziu evidência suficiente.

Coordenada

As partes podem avançar em paralelo, mas compartilham uma superfície de integração que precisa de contrato, sincronização ou gate intermediário.

Essa classificação é método deste livro.

Ela não é apresentada como taxonomia universal das fontes.

Serve como instrumento operacional para evitar que “multi-agent” vire sinônimo de “paralelo por padrão”.

O custo escondido do handoff

Todo handoff tem custo.

Não apenas custo de mensagem.

Há custo de:

reconstruir contexto;
interpretar decisões anteriores;
descobrir pressupostos não documentados;
alinhar nomes e tipos;
corrigir incompatibilidades;
repetir investigação;
revisar uma integração maior.

Isso cria uma consequência importante:

a unidade ótima de trabalho não é a menor possível.

Uma tarefa pequena demais pode depender de tantas informações externas que o agente passa mais tempo reconstruindo o entorno do que executando a mudança.

Uma tarefa grande demais, por outro lado, pode exceder o que conseguimos especificar, observar e revisar com segurança.

O ponto de equilíbrio precisa ser descoberto pela arquitetura da mudança.

Não por uma meta arbitrária de quantidade de agentes.

Contratos tornam o paralelo verificável

Paralelismo seguro exige mais do que dizer “você cuida do backend” e “você cuida do frontend”.

Precisamos definir a superfície que liga os dois lados.

O contrato pode assumir formas diferentes:

schema;
API;
evento;
interface;
tipo;
fixture;
arquivo;
protocolo;
acceptance property.

A forma importa menos que a propriedade central:

cada lado deve conseguir trabalhar sem inventar o comportamento do outro.

Isso conecta decomposição diretamente à Evidence Architecture.

Se o contrato é explícito, podemos testar:

compatibilidade;
formato;
invariantes;
erros;
estados esperados;
comportamento na integração.

O artefato de handoff deve sobreviver à conversa

SASE propõe substituir prompts transitórios por artefatos estruturados, duráveis e legíveis por máquina que funcionam como contratos e memória institucional entre humanos e agentes. ⁴

Isso é particularmente relevante na decomposição.

Um handoff que existe apenas na conversa depende da memória daquele contexto.

Um handoff versionado pode ser:

revisado;
comparado;
testado;
retomado;
auditado;
reutilizado.

No nosso método, a passagem entre partes deve preferir artefatos persistentes.

Por exemplo:

SPEC.md;
DOMAIN.md;
ADR;
schema;
contract test;
evidência pack;
issue;
commit;
Change Episode.

A conversa coordena.

O artefato preserva.

Um agente antes de vários

A existência de múltiplos agentes não obriga o uso de múltiplos agentes.

Nosso baseline deve continuar sendo:

qual é a forma mais simples de executar esta mudança mantendo contexto, verificação e reversibilidade?

Se um único agente consegue executar a mudança dentro de um contexto adequado e produzir um diff revisável, adicionar agentes pode apenas acrescentar handoffs.

Multi-agent deve resolver um problema real:

independência clara de trabalho;
especialização necessária;
isolamento;
volume paralelizável;
validação independente;
separação de trust boundaries.

Não deve ser adotado apenas porque a ferramenta oferece essa opção.

O Task Decomposition Map

O artefato operacional deste capítulo é o Task Decomposition Map.

Ele registra, para uma mudança:

objetivo da mudança;
componentes ou capacidades afetadas;
invariantes compartilhados;
dependências entre partes;
classificação inicial: independente, sequencial ou coordenada;
contrato de cada handoff;
evidência esperada em cada fronteira;
responsável/agente;
condição de integração;
condição de escalada.

Uma representação simples pode ser:

Change
├── A: schema + contract tests
│   └── gate A
├── B: producer
│   └── depends on A
└── C: consumer
    └── depends on A

A → B
A → C
B || C
B + C → integration gate

Aqui, B e C podem rodar em paralelo depois que A estabiliza o contrato.

O mapa torna a dependência visível antes de gastar tokens e produzir diffs concorrentes.

Decompor também é escolher onde revisar

Uma fronteira de tarefa é também uma fronteira de evidência.

Se a mudança foi dividida em três partes, precisamos saber:

o que prova que cada parte terminou?
o que prova que o handoff está correto?
o que prova que a composição continua correta?

Isso evita um padrão perigoso:

cada agente termina sua tarefa local, todos os checks locais passam, mas a integração falha porque nenhum gate verificava o conjunto.

O mapa de decomposição deve indicar os gates intermediários.

Não apenas o gate final.

Quando não decompor

Há três sinais claros para resistir à decomposição:

o contrato entre as partes é maior que a tarefa;
a segunda etapa depende fortemente das decisões internas da primeira;
a integração só pode ser verificada no fim.

Nesses casos, manter contexto contínuo pode ser mais barato e mais seguro.

A disciplina é aceitar menos paralelismo quando a estrutura do problema exige sequência.

Velocidade local não compensa rework global.

Da decomposição ao contexto

Decompor produz unidades de trabalho; não determina automaticamente o que cada uma precisa saber.

Uma tarefa de schema precisa de informações diferentes de uma tarefa de UI. Uma mudança de autenticação precisa de ameaças, invariantes e permissões que não pertencem a uma tarefa editorial.

O próximo passo é, portanto, seletivo: para cada unidade, qual é o menor contexto suficiente — e o que deve permanecer fora dela?

Essa é a entrada para Context Engineering.

Fronteira de confiança

Cada fronteira de decomposição deve explicitar quais decisões permanecem locais e quais exigem escalada. Se um agente precisa atravessar uma trust boundary, ampliar permissões ou alterar um contrato compartilhado, a tarefa deixa de ser independente e deve voltar para coordenação.

Evidência exigida

Uma decomposição só é operacionalmente útil quando cada parte e cada handoff possuem evidência verificável. Contratos, contract tests, schemas, fixtures e integration gates transformam fronteiras arquiteturais em pontos verificáveis.

Rollback e recuperação

Decompor muda também o desenho de recuperação. Antes de executar partes em paralelo, registre se elas podem ser revertidas independentemente, se produzem estado persistente e em qual ordem uma reversão precisa ocorrer.

Proveniência das fontes

Rastreabilidade deste capítulo:

CLM-013 — McEntire, decomposição como decisão arquitetural de fronteiras e contratos;
CLM-031 — McEntire, natural information boundaries e interfaces estreitas verificáveis;
CLM-032 — McEntire, perda de contexto em handoffs e preservação de dependências sequenciais;
CLM-033 — Hassan et al., artefatos estruturados/duráveis como contratos e memória institucional.

As classificações independente / sequencial / coordenada e o Task Decomposition Map são método deste livro nesta versão.

Fontes de acesso limitado não foram usadas como autoridade factual neste capítulo.

Recursos complementares

Recursos relacionados:

futuro Task Decomposition Map;
SPEC.md;
DOMAIN.md;
EVIDENCE.md;
Change Episode;
futura visualização de dependency graph + gates;
futura comparação single-agent vs decomposição em Change Episodes.

Jeremy McEntire, Beyond Code (2026), Chapter 7: Decomposition as Design, p. 65. Rastreabilidade interna: CLM-013. ↩
Jeremy McEntire, Beyond Code (2026), Chapter 7: Decomposition as Design, p. 66. Rastreabilidade interna: CLM-031. ↩
Jeremy McEntire, Beyond Code (2026), Chapter 7: Decomposition as Design, p. 68. Rastreabilidade interna: CLM-032. ↩
Hassan et al., Agentic Software Engineering: Foundational Pillars and a Research Roadmap, 1 Introduction, p. 3. Rastreabilidade interna: CLM-033. ↩