Programando com IA: Comece pela Arquitetura, Termine pelo Código

Muita gente me pergunta como eu uso IA pra programar e que tipo de prompt eu mando pra um LLM conseguir gerar código de qualidade. Resolvi reunir aqui, com base nos meus próprios prompts e na minha experiência em projetos reais, o que tem funcionado pra mim no dia a dia.

Pra mim, usar Inteligência Artificial 🤖 para programar é, antes de qualquer coisa, começar pela arquitetura 🏗️ e terminar pelo código ⌨️.

Geralmente, nós estamos acostumados a escrever o código primeiro e, depois que ele já está funcionando, pensar na arquitetura. Com IA, a ordem certa é exatamente o oposto: você define a arquitetura, as regras e o estilo, e só então deixa o modelo escrever o código.

Quanto mais contexto 💡 você dá ao modelo antes da primeira linha de código, melhor o resultado e menor o retrabalho.

O que você precisa dizer ao modelo 📋

Para um LLM gerar código de qualidade, ele precisa receber contexto suficiente sobre o que você quer construir. Antes de pedir uma única linha de código, descreva claramente:

• 🧭 Contexto e Introdução
• 🎯 Objetivo do Projeto
• 📜 Regras de Negócio
• ⚙️ Funcionalidades e Como Implementar Cada Uma
• 👤 Fluxo do Usuário
• 🔀 Fluxo de Dados
• 🔌 Fluxo de API e Integrações
• 🔐 Fluxo de Autenticação e Sessão
• 🛠️ Ferramentas e Frameworks (com versões)
• 🧩 Como as Partes Funcionam Juntas
• 🗂️ Organização do Projeto (MVVM, MVC, etc.)
• 🧠 Gerenciamento de Estado
• 🗺️ Estrutura de Navegação
• 🎨 Direção de UI/UX
• 🌈 Cores, Assets, Branding e Identidade Visual
• 💾 Estratégia de Armazenamento
• 🌍 Estratégia de Localização
• 🚨 Estratégia de Tratamento de Erros
• 🛡️ Regras de Segurança
• ✍️ Formato do Código
• 📐 Padrões de Código
• 🚫 Restrições (não criar: fallbacks, código sujo, código legado, testes, documentação)
• ✅ Processo de Revisão e Qualidade

📌 Esses tópicos formam o "briefing arquitetural" do projeto. Sem eles, o modelo improvisa — e improviso, em código, vira dívida técnica.

💡 Um exemplo prático

A seguir, um exemplo real de prompt arquitetural que você pode usar como ponto de partida. Cada seção define com precisão o que o modelo deve e o que não deve fazer.

🧭 Contexto e Introdução

Você está construindo um aplicativo iOS moderno chamado "Avinu" utilizando SwiftUI a partir de um novo projeto no Xcode.

O app deve seguir um estilo visual limpo, minimalista, elegante e altamente profissional.

O foco é escalabilidade, manutenibilidade, arquitetura limpa, componentes reutilizáveis e excelente UX.

A aplicação deve transmitir a sensação de um app premium moderno, com navegação fluida, espaçamento suave, tipografia limpa e layouts organizados.

🎯 Objetivo do Projeto

Criar um app iOS manutenível, com telas de autenticação, home, categorias, busca e perfil, utilizando uma estrutura escalável e organizada.

O app deve estar preparado para expansão futura sem gerar dívida técnica.

📜 Regras de Negócio

• Apenas usuários autenticados podem acessar Home, Categorias, Busca e Perfil.
• A sessão deve persistir entre aberturas do app até que o usuário faça logout.
• Recuperação de senha é feita por e-mail.
• Categorias e conteúdos são carregados de uma fonte remota.
• O histórico de buscas recentes é limitado às últimas 10 entradas por usuário.

⚙️ Funcionalidades e Como Implementar Cada Uma

🔑 Autenticação

• Criar uma tela de login com:
  • Campo de e-mail
  • Campo de senha
  • Botão de login
  • Botão para navegar até o cadastro
  • Botão de "esqueci minha senha"
• Criar uma tela de cadastro com:
  • Campo de nome
  • Campo de e-mail
  • Campo de senha
  • Campo de confirmação de senha
  • Botão de cadastro
  • Botão para voltar ao login

🏠 Home

• Criar uma tela home limpa com:
  • Seção de boas-vindas
  • Cards de destaque
  • Prévia de categorias
  • Seção de conteúdo recente
  • Scroll vertical suave

📁 Categorias

• Criar uma tela de categorias com:
  • Campo de busca
  • Lista de categorias
  • Cards de categoria arredondados
  • Suporte a ícone/imagem

🔎 Busca

• Criar uma tela de busca com:
  • Campo de busca
  • Seção de buscas recentes
  • Lista de resultados
  • Estado vazio

🙋 Perfil

• Criar uma tela de perfil com:
  • Avatar do usuário
  • Nome do usuário
  • E-mail do usuário
  • Seção de configurações
  • Botão de logout

👤 Fluxo do Usuário

• Primeira abertura do app: tela de login.
• Login válido: usuário entra na TabView principal (Home → Categorias → Busca → Perfil).
• Novo cadastro: após sucesso, retorna para a tela de login.
• Esqueci minha senha: envia e-mail de recuperação e retorna ao login.
• Logout: limpa sessão e volta à tela de login.

🔀 Fluxo de Dados

• Views não acessam dados diretamente; elas observam ViewModels.
• ViewModels consomem Services para qualquer operação de dados.
• Services encapsulam regras de acesso, parsing e tratamento de erro.
• Models definem as estruturas trafegadas entre camadas.
• Nenhuma camada deve depender de detalhes da camada acima.

🔌 Fluxo de API e Integrações

• Toda comunicação remota passa por Services dedicados.
• Respostas são tipadas com Models, sem uso de dicionários soltos.
• Erros de rede e parsing são convertidos em erros de domínio antes de chegar à View.
• Configurações de URL base, timeout e cabeçalhos ficam centralizadas.
• Autenticação é injetada automaticamente nas requisições autenticadas.

🔐 Fluxo de Autenticação e Sessão

• Login retorna token de acesso e dados básicos do usuário.
• Token é armazenado de forma segura no Keychain.
• O estado de autenticação é observado pela raiz do app, decidindo entre fluxo de autenticação e fluxo principal.
• Renovação de token ocorre de forma transparente quando necessário.
• Logout limpa o Keychain e o estado de sessão.

🛠️ Ferramentas e Frameworks (com versões)

• iOS
• Swift
• SwiftUI
• Xcode na versão estável mais recente

Não usar UIKit, a menos que estritamente necessário.

Não adicionar bibliotecas externas, a menos que explicitamente solicitado.

🧩 Como as Partes Funcionam Juntas

• SwiftUI controla toda a interface.
• O estado do app decide se as telas de autenticação ou as telas principais ficam visíveis.
• A navegação principal usa TabView.
• Cada tela tem sua própria View e ViewModel.
• Componentes de UI compartilhados devem ser reutilizáveis.
• Estilos visuais compartilhados devem ficar centralizados.

🗂️ Organização do Projeto (MVVM, MVC, etc.)

Use exatamente esta estrutura:

• App/
• Assets/
• Components/
• Helpers/
• Models/
• Services/
• ViewModels/
• Screens/

Dentro de Screens:

• Authentication/
• Home/
• Categories/
• Search/
• Profile/

Cada pasta de tela deve conter:

• View
• ViewModel
• Components, se necessário

🧠 Gerenciamento de Estado

Use o gerenciamento de estado do SwiftUI.

• @State
• @Binding
• @StateObject
• @ObservedObject
• @EnvironmentObject

Use ViewModels para estado de tela e lógica de negócio.

Mantenha as Views focadas em apresentação.

🗺️ Estrutura de Navegação

Use TabView como navegação principal do app.

Abas:

• Home
• Categorias
• Busca
• Perfil

O fluxo de autenticação deve ficar isolado da navegação principal do app.

🎨 Direção de UI/UX

• Interface minimalista
• Espaçamento suave
• Cantos arredondados
• Tipografia limpa
• Scroll fluido
• Cards elegantes
• Sensação de iOS moderno
• Experiência amigável e profissional
• Evitar poluição visual
• Evitar sombras pesadas
• Priorizar legibilidade e espaçamento

Estilo de referência:

• Apps modernos de produtividade
• Apps modernos de finanças
• Apps modernos de IA

🌈 Cores, Assets, Branding e Identidade Visual

Nome do app:

• Avinu

Estilo visual:

• Moderno
• Elegante
• Minimalista
• Dark mode em primeiro lugar

Cores principais:

• Fundo primário: #0F1115
• Fundo secundário: #171A21
• Fundo de card: #1E222B
• Texto primário: #FFFFFF
• Texto secundário: #AEB4C2
• Cor de borda: #2B313D
• Cor primária: #4F7CFF
• Cor de destaque: #7B61FF
• Cor de sucesso: #35C759
• Cor de erro: #FF453A

Botões:

• Cantos arredondados
• Altura média
• Bom contraste
• Espaçamento limpo

Inputs:

• Arredondados
• Fundo escuro
• Texto claro
• Estado de foco visível

Ícones:

• Usar SF Symbols por padrão

Estrutura de assets:

• Assets.xcassets/AppLogo/
• Assets.xcassets/Icons/
• Assets.xcassets/Illustrations/
• Assets.xcassets/Placeholders/

Regras para o logo:

• O arquivo principal do logo deve ficar em Assets.xcassets/AppLogo/
• Criar imagens relacionadas ao app com base no estilo do logo.
• Manter todos os assets gerados visualmente consistentes com o logo.
• Usar a mesma paleta de cores e linguagem visual.
• Evitar estilos de ícone inconsistentes.

Tipografia:

• Usar SF Pro Display
• Manter hierarquia clara
• Evitar textos exagerados em tamanho

💾 Estratégia de Armazenamento

• Manter estado temporário do app em memória.
• Preparar a estrutura para persistência futura.
• Evitar estado local espalhado.

🌍 Estratégia de Localização

• Preparar todas as strings da UI para localização (NSLocalizedString).
• Idioma inicial: português (pt-BR).
• Não fazer hardcode de textos diretamente nas Views.
• Manter a estrutura pronta para receber novos idiomas no futuro.

🚨 Estratégia de Tratamento de Erros

• Mostrar alertas simples e amigáveis.
• Evitar mensagens técnicas para o usuário.
• Usar helpers de alerta reutilizáveis sempre que possível.
• Manter o tratamento de erros centralizado.

🛡️ Regras de Segurança

• Evitar expor detalhes internos da implementação.
• Evitar force unwraps inseguros.
• Preferir tratamento seguro de opcionais.
• Manter a lógica sensível isolada.

✍️ Formato do Código

• Manter métodos em uma única linha quando for razoável.
• Evitar quebras de linha desnecessárias.
• Evitar espaçamento vertical excessivo.
• Manter arquivos limpos e minimalistas.
• Usar convenções de nomenclatura claras.
• Manter o código visualmente organizado.

📐 Padrões de Código

• Usar MVVM.
• Manter Views focadas em apresentação.
• Manter ViewModels responsáveis por estado e ações.
• Usar Services para lógica reutilizável.
• Usar Components para UI reutilizável.
• Usar Models para dados estruturados.
• Evitar lógica duplicada.
• Evitar Views gigantes.

🚫 Restrições

• Não criar fallbacks.
• Não criar código sujo.
• Não criar código legado.
• Não criar testes.
• Não criar documentação.
• Não criar abstrações desnecessárias.
• Não usar hacks.
• Não criar arquitetura de fachada (placeholder).
• Não misturar responsabilidades não relacionadas.
• Não criar arquivos gigantes.
• Não fazer hardcode de valores visuais repetidos.

✅ Processo de Revisão e Qualidade

• Revisar todo o app visualmente.
• Revisar consistência de espaçamento.
• Revisar reuso de componentes.
• Revisar consistência de nomenclatura.
• Revisar organização de arquivos.
• Revisar lógica duplicada.
• Revisar limpeza do código.
• Fazer uma revisão final linha a linha.

🎯 Conclusão

Programar com IA não é "pedir código e ver no que dá". É desenhar a arquitetura primeiro 🏗️, definir todas as regras, restrições e padrões — e só depois deixar o modelo gerar o código dentro desse contrato.

🚀 Quanto mais cuidado você tiver no briefing arquitetural, menos retrabalho, menos dívida técnica e mais qualidade no resultado final. A IA não substitui o engenheiro: ela amplifica o engenheiro que pensa antes de codar.