Arquitetura em 3 camadas:a IA a escrever código limpo

A IA gera código confuso porque o teu projeto não tem arquitetura, não porque a IA seja má. Uma arquitetura em 3 camadas resolve isso. Dá-lhe três camadas claras — componentes para a interface, serviços para a lógica de negócio, uma camada de dados para a base de dados — e escreve prompts para uma camada de cada vez, e a mesma IA produz código limpo, testável e escalável. Foi assim que construí o FIKR Space.

Eis o padrão, porque funciona e a sequência exata de prompts.

O problema: IA sem estrutura cria caos

Pedes à IA que construa uma funcionalidade. Ela dá-te código. Colas. Uma semana depois, a tua base de código é uma confusão: chamadas à base de dados espalhadas por todo o lado, lógica de negócio misturada com a interface, código copiado e colado por todo o lado, impossível de testar, parte quando tentas escalar.

O problema não é a IA. É a tua arquitetura.

A IA gera o que lhe pedes. Mas sem uma arquitetura clara, mistura responsabilidades, cria padrões inconsistentes e não consegue manter a estrutura da tua base de código — cada prompt cria caos novo. A IA não conhece a tua arquitetura. Tens de ser tu a guiá-la.

A solução: uma arquitetura em 3 camadas

Imagina a tua app como um prédio de três andares. Os componentes em cima — só interface. Os serviços no meio — lógica de negócio. A camada de dados em baixo — base de dados e APIs. Cada andar só fala com o que está imediatamente abaixo. Quando a IA sabe em que camada está a trabalhar, gera código limpo.

• Camada 1 — Componentes (só interface). O que pertence aqui: lógica de apresentação, interações do utilizador, rotas, layout. O que não pertence: chamadas à base de dados, lógica de negócio, validação, permissões. Um mau componente vai buscar os utilizadores à base de dados dentro de si próprio, filtrando pelo estado pelo caminho. Um bom componente pede a um hook os «utilizadores ativos», mostra um esqueleto de carregamento enquanto espera e apresenta a lista. É esse o trabalho todo.
• Camada 2 — Serviços (lógica de negócio). O que pertence aqui: obtenção de dados, validação, permissões, regras de negócio, transformações de dados. O que não pertence: tudo o que é apresentado no ecrã, ou estado específico de um componente. Um UserService conhece as regras — é obrigatória uma organização, que filtros se aplicam, o que acontece em caso de falha — e é o único sítio onde essas regras vivem.
• Camada 3 — Dados (base de dados e APIs). Consultas à base de dados, chamadas a APIs, integrações externas. Acedida apenas através dos serviços, nunca diretamente a partir dos componentes.

Como escrever prompts para a IA com este padrão

A forma errada é um único prompt: «Constrói uma funcionalidade de gestão de utilizadores.» O resultado é tudo num único componente — chamadas à base de dados, validação, interface, tudo misturado. A forma certa são três prompts, de baixo para cima, uma camada cada:

1. Primeiro o serviço: «Gera um UserService com métodos para obter, criar, atualizar e apagar utilizadores. Inclui validação e tratamento de erros.»
2. Depois o hook: «Cria um hook useUsers que envolve o UserService com cache.»
3. Por fim o componente: «Constrói um componente UserList que usa o hook useUsers. Mostra os estados de carregamento e trata os erros.»

Resultado: código limpo e separado, cada camada focada na sua responsabilidade. Pedir tudo de uma vez é o erro número um — a IA gera código misturado, com todas as camadas emaranhadas. Uma camada de cada vez, construída de baixo para cima.

O livroThe Solopreneur RevolutionLuis Gonçalves sobre como construir um negócio de EUpreendedor com IA sem deixar o emprego.Quero o livro →

Funciona com qualquer stack

O mesmo padrão, ferramentas diferentes:

Já tens código confuso? A migração em 5 passos

1. Encontra todas as chamadas à base de dados. Procura nos teus componentes chamadas diretas à base de dados e a APIs.
2. Cria serviços. Passa todo o acesso a dados para classes de serviço — a consulta que vivia dentro de um componente passa a viver num método de serviço com tratamento de erros.
3. Cria hooks. Envolve cada serviço com a camada de obtenção de dados da tua framework, para que os componentes tenham cache e estados de carregamento sem esforço.
4. Atualiza os componentes. Substitui o padrão de ir buscar dados dentro do componente por uma única chamada a um hook.
5. Deixa a IA ajudar. Prompt: «Refatora este componente para usar o padrão de hook. Passa a lógica da base de dados para um serviço.» A IA migra cada peça.

A recompensa aparece de imediato nos testes: os serviços testam-se sem qualquer interface, os hooks testam-se como camadas finas, e os componentes testam-se com o hook simulado. Camadas limpas = testes fáceis.

Porque é que isto funciona

Sem camadas, a IA gera componentes monolíticos, duplica lógica entre ficheiros e produz código difícil de testar, difícil de manter e que parte ao escalar. Com camadas, a IA gera código focado para cada camada, a lógica fica centralizada nos serviços, cada camada testa-se de forma independente — e o padrão escala para bases de código enormes.

Construí assim. Funciona. É exatamente a arquitetura por trás do FIKR Space: 5 produtos integrados, construídos com o Claude, a correr em produção. Os dois erros a evitar: saltar os serviços («uso os hooks diretamente com a base de dados» — lógica de negócio em hooks é difícil de testar e impossível de reutilizar) e componentes inchados («ponho a validação nos componentes» — não a consegues reutilizar nem testar sem a interface).

Antes de lançar, passa a checklist: nenhuma importação da base de dados nos componentes, toda a lógica de negócio nos serviços, os componentes só tratam da interface, os hooks envolvem os serviços, os serviços testam-se sem interface, tratamento de erros em todas as camadas. Este padrão é o pilar 2 dos cinco pilares do software em produção — e, assim que as camadas existem, os prompts estruturados como os do método PRP ficam muito mais fiáveis, porque cada prompt tem uma casa óbvia.

12 semanasA tua carreira corporativa nunca foi o planoCandidata-te ao Solopreneur Accelerator.Candidatar-me →

Perguntas frequentes

Preciso de perceber de código para usar a arquitetura em 3 camadas?

Precisas de perceber o mapa, não as ruas. Saber que a interface, a lógica de negócio e o acesso a dados são três andares separados — e que cada prompt visa exatamente um — chega para dirigir bem a IA. A arquitetura é uma ferramenta de comunicação entre ti e a IA, e dirigir é a tua metade do trabalho.

3 camadas não é exagero para um MVP pequeno?

Não, porque o custo é quase zero e a alternativa acumula. Três prompts em vez de um no primeiro dia são minutos de trabalho extra; desemaranhar chamadas à base de dados de cinquenta componentes ao sexto mês são semanas. O padrão funciona desde um projeto de fim de semana até uma plataforma inteira em produção — já o usei nos dois extremos.

O que vai num serviço e o que vai num hook?

As regras vão no serviço; a canalização vai no hook. Se é uma decisão de negócio — o que conta como válido, quem tem permissão, como se calcula um valor — pertence ao serviço. Se é sobre entregar dados ao ecrã — cache, indicadores de carregamento, voltar a ir buscar dados — pertence ao hook. Na dúvida, põe no serviço: os serviços são mais fáceis de testar e reutilizar.

Como faço a IA respeitar as camadas automaticamente?

Escreve a regra nas instruções permanentes do teu projeto: os componentes nunca importam o cliente da base de dados, todo o acesso a dados passa pelos serviços, os hooks envolvem os serviços. Depois faz com que cada prompt diga a sua camada («cria um método de serviço para…»). A IA segue a arquitetura que está realmente escrita — nunca a que está na tua cabeça.