Capítulo 5 — Arquitetura como restrição produtiva

Velocidade sem fronteira vira custo

Agentes tornam barato produzir alternativas. Isso é útil até o momento em que a facilidade de alterar o sistema começa a dissolver decisões que deveriam permanecer estáveis.

Uma implementação pode estar correta localmente e ainda violar uma fronteira importante.

Pode colocar regra de negócio dentro de um controller, acoplar domínio ao ORM, levar um formato de API para dentro do núcleo ou fazer um framework ditar a estrutura do sistema.

O problema não é que o código não funciona. O problema é que uma decisão local passou a reescrever a arquitetura sem que ninguém tenha decidido fazê-lo.

Por isso, arquitetura não aparece neste livro como desenho decorativo.

Ela funciona como restrição produtiva.

A Dependency Rule como envelope

Robert C. Martin formula uma regra simples para Clean Architecture: dependências de código devem apontar para políticas de nível mais alto, mantendo detalhes externos do lado de fora do núcleo. ¹

No contexto agêntico, essa regra reduz o conjunto de alterações aceitáveis. O agente pode trocar um adapter, atualizar uma integração ou substituir uma tecnologia sem receber permissão implícita para reescrever a política central.

Quando a direção da dependência é explícita, o sistema oferece uma resposta objetiva para parte da revisão:

esta mudança respeita ou atravessa a fronteira?

Isso não elimina julgamento arquitetural. Mas transforma parte dele em uma restrição que pode ser lida, testada e automatizada.

Framework é ferramenta, não centro do sistema

Clean Architecture busca separar regras de negócio de interfaces, frameworks, banco de dados e outros detalhes externos, preservando testabilidade e independência do núcleo. ²

Isso é especialmente importante quando agentes geram código a partir dos padrões que encontram no repositório.

Se o framework domina a estrutura, o agente tende a reproduzir esse acoplamento.

Se os casos de uso, entidades e portas são visíveis, o agente recebe uma topologia diferente: detalhes se conectam às políticas, não o contrário.

A arquitetura, então, passa a funcionar como contexto persistente.

Ela diz ao agente não apenas onde escrever, mas quais decisões ele não deve tomar localmente.

Fronteiras protegem políticas

Martin descreve a separação entre regras centrais e plugins de forma que as dependências apontem dos detalhes para o núcleo. ³ Para agentes, isso cria uma fronteira de autonomia.

Uma mudança em um detalhe pode receber um envelope mais amplo quando:

a interface já está definida;
o comportamento esperado é verificável;
o núcleo não precisa mudar;
o rollback é localizado.

Uma mudança que altera a política central deve receber outro tratamento:

ADR;
revisão humana;
critérios de aceitação mais fortes;
análise de impacto;
evidência de compatibilidade;
possivelmente uma tarefa separada.

A arquitetura, portanto, participa da calibração de autonomia.

Arquitetura deve revelar propósito

Outro princípio útil é que a estrutura do sistema deve comunicar o que ele faz, e não primeiro qual framework foi escolhido. ⁴

Esse princípio ganha novo valor quando parte do leitor do repositório é um agente.

Um projeto cujo topo é organizado apenas em controllers, models, services e repositories informa categorias técnicas.

Um projeto que torna casos de uso, domínios ou capabilities visíveis oferece contexto sobre intenção.

O objetivo não é impor uma árvore de pastas universal.

É fazer com que a estrutura reduza a inferência necessária para descobrir responsabilidade e propósito.

Restrições duráveis e decisões locais

Nem toda decisão precisa virar arquitetura.

A distinção importante é entre:

decisões duráveis, que limitam muitas mudanças futuras;
decisões locais, que podem ser substituídas sem alterar políticas centrais.

Uma interface entre domínio e persistência pode ser uma restrição durável.

Escolher uma biblioteca específica para serialização pode ser um detalhe local.

Confundir essas categorias gera dois extremos ruins.

No primeiro, tudo vira regra e o sistema fica rígido.

No segundo, nada é protegido e cada agente pode reinterpretar o projeto a cada tarefa.

Arquitetura produtiva mantém poucas restrições fortes e deixa liberdade dentro delas.

ADR como contrato de mudança arquitetural

Quando uma tarefa precisa atravessar uma fronteira, a mudança deve deixar de ser uma decisão implícita do agente.

Ela passa a exigir um registro explícito.

O ADR.md do Companion serve para isso:

contexto;
decisão;
alternativas;
consequências;
evidências.

O ADR não existe para burocratizar toda alteração. Ele existe para que mudanças de direção deixem rastros recuperáveis e não se escondam dentro de um diff.

Arquitetura executável

Uma arquitetura só escrita em slides é fraca como mecanismo de controle.

Sempre que possível, limites devem aparecer em mecanismos que o sistema consegue verificar:

regras de dependência;
boundaries de pacote;
testes arquiteturais;
contratos de interface;
módulos com encapsulamento real;
CI checks;
políticas de acesso.

Quanto maior a autonomia do agente, mais valioso é transformar intenção arquitetural em restrição executável.

Isso permite que o sistema rejeite violações antes que elas dependam de memória ou gosto do revisor.

Arquitetura reduz o espaço de decisão da tarefa

No lifecycle do livro, Architecture vem antes de Spec e Context porque ambos dependem de fronteiras estruturais já decididas.

Quando responsabilidades, dependências e regras de direção estão explícitas, a Spec não precisa reinventar estrutura e o Context pode ser mais seletivo. Arquitetura, portanto, funciona como compressão de possibilidades: reduz o número de decisões que cada tarefa precisa refazer.

Próximo passo: especificar a mudança

Domínio respondeu o que os conceitos significam.

Arquitetura respondeu onde responsabilidades e dependências podem viver.

Agora podemos escrever uma especificação sem pedir ao agente que invente essas duas coisas ao mesmo tempo.

O próximo capítulo transforma intenção em contrato verificável:

Spec como limite de autonomia.

Fronteira de confiança

O agente pode tomar decisões locais dentro de fronteiras estabelecidas. Alterações que mudam direção de dependência, política central, boundary ou contrato arquitetural devem escalar para decisão explícita.

Evidência exigida

Para mudanças arquiteturalmente relevantes, exigir conforme o caso:

ADR;
dependency/architecture checks;
diff focado;
testes de casos de uso;
compatibilidade de interfaces;
revisão humana;
evidência de que detalhes externos não vazaram para políticas centrais.

Rollback e recuperação

Uma violação arquitetural pode ser tecnicamente reversível e ainda deixar migrações, contratos ou dependências espalhadas pelo sistema. O plano de recovery deve considerar não apenas arquivos alterados, mas também acoplamentos introduzidos.

Proveniência das fontes

Rastreabilidade deste capítulo:

CLM-001 — Martin, Dependency Rule;
CLM-025 — Martin, separação de concerns e independência de frameworks/externalidades;
CLM-026 — Martin, boundaries e dependências em direção ao core;
CLM-027 — Martin, arquitetura revelando use cases e propósito do sistema.

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

Recursos complementares

Recursos relacionados:

ADR.md;
futura Architecture Boundary Check;
futura visualização de dependency direction;
integração de architecture gates ao Evidence Gate.

Robert C. Martin, Clean Architecture (2017), The Dependency Rule, pp. 162–164. Rastreabilidade interna: CLM-001. ↩
Robert C. Martin, Clean Architecture (2017), Chapter 22 The Clean Architecture, pp. 161–162. Rastreabilidade interna: CLM-025. ↩
Robert C. Martin, Clean Architecture (2017), Conclusion, pp. 142–143. Rastreabilidade interna: CLM-026. ↩
Robert C. Martin, Clean Architecture (2017), Conclusion, p. 160. Rastreabilidade interna: CLM-027. ↩