Cinco níveis de imersão em um sistema complexo

Quando todos os níveis de contexto se misturam

O que impede você de ver a visão geral quando todos os detalhes estão disponíveis de uma só vez?

Um repositório comum não separa a informação por escala: apresenta de uma só vez áreas de negócios, operações, modelos de dados, ordem de chamada, infraestrutura e linhas de código individuais. A memória de trabalho precisa reter fatos de níveis diferentes e reconstruir sozinha as relações entre eles. A atenção fica alternando entre a estrutura do sistema e os detalhes locais, de modo que a compreensão se desfaz rapidamente depois de uma pausa.

Primeiro, um mapa de responsabilidades

Onde mora a responsabilidade?

O primeiro pilar é um mapa de responsabilidades. Ele reúne controllers, serviços, modelos de dados, adaptadores de infraestrutura e cadeias de chamadas em torno das grandes áreas do sistema — uma moldura à qual operações, dados e código podem então ser ligados.

Os domínios dividem o sistema por áreas estáveis de responsabilidade, não por camadas técnicas: pedidos, pagamentos, comunicação e analytics. No lugar de centenas de arquivos aparentemente equivalentes surge uma primeira topologia compreensível.

O mapa se torna um catálogo de capacidades

O que o sistema pode fazer?

O mapa de domínios mostra onde reside a responsabilidade, mas ainda não diz o que o sistema pode fazer. Para responder a isso, cada domínio se abre em um catálogo de Actions – recursos nomeados que ele fornece ao restante do sistema.

Um Action é uma capacidade pública e nomeada de um domínio. O catálogo não mostra funções internas, e sim as operações que um domínio fornece ao restante do sistema, junto com as relações direcionadas entre elas. Cada Action se torna um único ponto de invocação: quem chama escolhe a capacidade de que precisa pelo significado, em vez de montar a operação a partir de métodos separados.

Fixamos a fronteira da operação

O que a operação exige e promete?

A capacidade já tem um nome e um lugar no sistema. Para usá-lo como caixa preta, precisamos saber exatamente quais dados ele aceita e qual resultado promete retornar.

Um Contract torna o limite Action digitado e inequívoco. Params descreve tudo o que a operação aceita; Result descreve tudo que deve retornar. A chamada do código depende dessa promessa, não do formato interno do Action. A implementação pode mudar desde que a entrada, a saída e o comportamento observável permaneçam compatíveis.

Desdobramos a operação em um cenário

Como o cenário se desenrola?

O contrato fixa o início e o fim de uma operação, mas não mostra como um se transforma no outro. Para perceber isso, desdobramos o fluxo interno do cenário de negócios.

Um Pipeline torna linear e visível o cenário principal do negócio: validar o insumo, reservar estoque, cobrar o pagamento e montar o resultado. Isso não significa que não existam erros, desvios e compensações; eles recebem um lugar explícito em relação à linha principal. Cada etapa também possui um contrato local: ele declara o que lê de Params, State e Context e o que adiciona a State para etapas posteriores.

Só agora, o comportamento concreto

Onde mora o comportamento concreto?

O Pipeline localiza o comportamento necessário com precisão e restringe drasticamente a área de pesquisa. Agora podemos abrir não o repositório inteiro ou mesmo o Action inteiro, mas uma etapa cujo propósito, entrada e saída já são conhecidos.

Code é o quinto nível, não porque os detalhes não sejam importantes, mas porque agora estão rodeados de significado. Sabemos qual domínio possui o comportamento, qual capacidade o Action implementa, o que o Contract promete e onde reserve_inventory fica no Pipeline. A implementação é interpretada como uma resposta local a uma tarefa concreta, em vez de uma entrada para uma investigação interminável do repositório.

@regular_aspect("Reserve inventory")@result_string("reservation_id", required=True)@context_requires("user.tenant_id", "env.inventory_region")async def reserve_inventory_aspect(    self, params, state, box, connections, ctx):    inventory = box.resolve(InventoryResource)    reservation_id = await inventory.reserve(        tenant_id=ctx.get("user.tenant_id"),        region=ctx.get("env.inventory_region"),        items=state["validated_items"],    )    return {"reservation_id": reservation_id}

Os cinco níveis não escondem o código nem reduzem o sistema a um diagrama. Eles preservam o caminho do modelo geral até um detalhe concreto. Quem está chegando constrói o contexto progressivamente; o arquiteto gerencia a gramática e as fronteiras em vez de cada arquivo; e o agente de IA executa trabalho local dentro de regras declaradas: as pessoas projetam a linguagem do sistema e a máquina atua nessa linguagem.