Seu App Criado por IA Está Virando um Frankenstein (e Você Sabe Disso)

Seu app agora:
┌─────────────────────────────────┐
│  TUDO MISTURADO                 │
│                                 │
│  Login + Carrinho + Pagamento   │
│  + Email + Banco de Dados       │
│  + Notificações + Favoritos     │
│                                 │
│  (1 arquivo gigante)            │
└─────────────────────────────────┘

Resultado: Mexe em uma coisa, quebra três.

App bem organizado:
┌─────────┐  ┌─────────┐  ┌──────────┐  ┌─────────┐
│  Login  │  │ Carrinho│  │ Pagamento│  │  Email  │
└─────────┘  └─────────┘  └──────────┘  └─────────┘

Resultado: Mexe em uma coisa, só ela muda.

📁 meu-app/
  📄 app.js
  📄 app-v2.js
  📄 app-final.js
  📄 app-final-AGORA-VAI.js
  📄 app-que-funcionava-antes.js

Empresa Bagunçada:
┌─────────────────────────────────┐
│  1 pessoa faz TUDO              │
│  (atende, vende, entrega,       │
│   faz contabilidade)            │
└─────────────────────────────────┘
❌ Lento, confuso, quebra fácil

Empresa Organizada:
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Vendedor │ │ Entregador│ │ Contador │
└──────────┘ └──────────┘ └──────────┘
✅ Rápido, claro, escalável

Os Sintomas (que você reconhece)

Sintoma #1: Acoplamento Invisível

Você já viu isso:

// Você muda isso aqui...
function updateUser(userId, data) {
  db.users.update(userId, data);
  sendEmail(data.email); // ← WTF? Por que email aqui?
  analytics.track('user_updated'); // ← E analytics?
  cache.invalidate(`user_${userId}`); // ← E cache?
  notifyWebhook(userId); // ← E webhook?
}

// ...e quebra isso aqui (em outro arquivo)
function getUserProfile(userId) {
  // Esperava que o cache estivesse atualizado
  // Mas alguém mudou a lógica de invalidação
  return cache.get(`user_${userId}`);
}

Por que dói:

• Lógica de negócio misturada com infraestrutura
• Impossível testar isoladamente
• Mudança em um lugar quebra outro
• Ninguém sabe todas as dependências

Você tem medo de mexer. E com razão.

Sintoma #2: God Classes / God Functions

O arquivo que ninguém quer abrir:

# user_service.py (2.500 linhas)
class UserService:
    def create_user(self, data):
        # Valida dados (50 linhas)
        if not data.get('email'):
            raise ValueError('Email obrigatório')
        if '@' not in data['email']:
            raise ValueError('Email inválido')
        # ... mais 40 linhas de validação
        
        # Conecta no banco (30 linhas)
        conn = psycopg2.connect(...)
        
        # Envia email (40 linhas)
        smtp = smtplib.SMTP(...)
        
        # Atualiza cache (20 linhas)
        redis_client = redis.Redis(...)
        
        # ... você entendeu
        pass

Por que dói:

• Arquivo com 2.500 linhas que ninguém quer abrir
• Mudança simples = risco de quebrar tudo
• Testes impossíveis (ou com 500 mocks)
• Code review vira pesadelo
• Onboarding de novos devs leva semanas

Você já ouviu: "Não mexa no UserService, ele é sensível".

Sintoma #3: Dependências Circulares

O inferno dos imports:

user_service.py → order_service.py → payment_service.py → user_service.py

Por que dói:

• Import errors aleatórios
• Impossível entender o fluxo
• Refatoração = missão impossível
• "Não mexa nisso, vai quebrar tudo"

Sintoma #4: Testes que Não Testam Nada

O teatro da cobertura:

test('should create user', async () => {
  // Precisa de banco real
  await setupDatabase();
  
  // Precisa de servidor de email
  await startEmailServer();
  
  // Precisa de Redis
  await startRedis();
  
  // Leva 5 segundos para rodar
  const user = await createUser({
    email: 'test@example.com',
    password: '12345678'
  });
  
  // Isso não testa nada
  expect(user).toBeDefined();
});

Por que dói:

• Testes lentos (ninguém roda)
• Testes frágeis (quebram sem motivo)
• Cobertura alta, confiança zero
• "Vamos pular os testes dessa vez..."

O Custo Real (números que doem)

Vamos falar de dinheiro. Porque no final, é disso que se trata.

Tempo perdido:

• Onboarding: 4-6 semanas (deveria ser 1)
• Bug simples: 4 horas (deveria ser 30 min)
• Feature nova: 2 semanas (deveria ser 3 dias)
• Deploy: 2 horas + reza (deveria ser 5 min)

Custo financeiro:

• Dev sênior: R$ 15k/mês
• 50% do tempo debugando código ruim = R$ 7.5k/mês jogados fora
• Time de 5 devs = R$ 37.5k/mês de desperdício
• R$ 450k/ano queimados em código mal arquitetado

Custo emocional:

• Burnout
• Rotatividade alta (40% ao ano)
• "Vou procurar outro emprego"
• Produto que não evolui
• Stakeholders nervosos

Você já perdeu um dev bom porque ele não aguentava mais o código?

A Solução: Clean Architecture (sem blá-blá-blá)

Clean Architecture não é teoria acadêmica. É sobrevivência.

Clean Architecture é separar o que seu sistema faz (domínio) de como ele faz (infraestrutura). Simples assim.

As 4 Camadas

┌─────────────────────────────────────┐
│  INTERFACE (Controllers, APIs)     │  ← O mundo externo
├─────────────────────────────────────┤
│  APPLICATION (Use Cases)            │  ← O que o sistema faz
├─────────────────────────────────────┤
│  DOMAIN (Entities, Business Rules)  │  ← As regras de negócio
├─────────────────────────────────────┤
│  INFRASTRUCTURE (DB, Email, Cache)  │  ← Como o sistema faz
└─────────────────────────────────────┘

Regra de ouro:

• Dependências apontam SEMPRE para dentro
• Domínio não conhece infraestrutura
• Use Cases não conhecem controllers
• Infraestrutura conhece tudo (mas é substituível)

Antes vs Depois (código real)

ANTES - Código Frankenstein

// user-controller.ts (tudo misturado)
export async function createUser(req: Request, res: Response) {
  try {
    // Validação inline
    if (!req.body.email || !req.body.email.includes('@')) {
      return res.status(400).json({ error: 'Email inválido' });
    }
    
    // Lógica de negócio inline
    if (req.body.age < 18) {
      return res.status(400).json({ error: 'Menor de idade' });
    }
    
    // Acesso direto ao banco
    const user = await db.users.create({
      email: req.body.email,
      name: req.body.name,
      age: req.body.age
    });
    
    // Email inline
    await sendgrid.send({
      to: user.email,
      subject: 'Bem-vindo!'
    });
    
    res.json(user);
  } catch (error) {
    res.status(500).json({ error: 'Erro interno' });
  }
}

Problemas:

• ❌ Impossível testar sem banco, email, cache, analytics
• ❌ Lógica de negócio espalhada
• ❌ Mudança no banco quebra o controller
• ❌ Não dá pra reusar em CLI, worker, GraphQL
• ❌ Validação duplicada em vários lugares

DEPOIS - Clean Architecture

1. DOMAIN - Regras de negócio puras

// domain/entities/User.ts
export class User {
  private constructor(
    public readonly id: string,
    public readonly email: Email,
    public readonly name: string,
    public readonly age: Age
  ) {}
  
  static create(data: CreateUserData): Result<User> {
    const emailResult = Email.create(data.email);
    if (emailResult.isFailure) {
      return Result.fail(emailResult.error);
    }
    
    const ageResult = Age.create(data.age);
    if (ageResult.isFailure) {
      return Result.fail(ageResult.error);
    }
    
    return Result.ok(new User(
      generateId(),
      emailResult.value,
      data.name,
      ageResult.value
    ));
  }
}

Vantagens:

• ✅ Validação centralizada
• ✅ Impossível criar entidade inválida
• ✅ Zero dependências externas
• ✅ Testável em milissegundos

2. APPLICATION - Use Cases

// application/use-cases/CreateUser.ts
export class CreateUserUseCase {
  constructor(
    private userRepo: IUserRepository,
    private emailService: IEmailService
  ) {}
  
  async execute(data: CreateUserDTO): Promise<Result<UserDTO>> {
    // 1. Criar entidade (validação automática)
    const userResult = User.create(data);
    if (userResult.isFailure) {
      return Result.fail(userResult.error);
    }
    
    const user = userResult.value;
    
    // 2. Verificar se email já existe
    const exists = await this.userRepo.existsByEmail(user.email);
    if (exists) {
      return Result.fail('Email já cadastrado');
    }
    
    // 3. Persistir
    await this.userRepo.save(user);
    
    // 4. Enviar email
    await this.emailService.sendWelcome(user.email);
    
    return Result.ok(UserMapper.toDTO(user));
  }
}

Vantagens:

• ✅ Lógica de negócio clara e isolada
• ✅ Reutilizável (HTTP, CLI, GraphQL, Worker)
• ✅ Testável com mocks simples

O Processo: Como Aplicar

❌ Erro Comum: Refatorar Tudo de Uma Vez

Você pensa: "Vou parar tudo e refatorar o projeto inteiro para Clean Arch!"

Resultado:

• 3 meses de refatoração
• Zero features novas
• Time frustrado
• Produto parado
• Projeto cancelado

Não faça isso.

✅ Abordagem Certa: Strangler Fig Pattern

A figueira estranguladora cresce ao redor de uma árvore hospedeira, substituindo-a aos poucos. Faça o mesmo com seu código.

1. Novas features = Clean Arch

• Toda feature nova já nasce com arquitetura
• Código novo não contamina código velho
• Time aprende aos poucos

2. Refatore sob demanda

• Vai mexer em um módulo? Refatore ele
• Bug em código legado? Aproveita e refatore

3. Isole o legado

src/
├── legacy/          ← Código velho (vai diminuindo)
│   ├── user.js
│   └── order.js
├── domain/          ← Código novo (vai crescendo)
│   ├── user/
│   └── order/
├── application/
├── infrastructure/
└── interface/

Resultados Reais

Projeto real que refatoramos:

ANTES

• 📁 50 mil linhas de código espaguete
• ⏱️ Onboarding: 6 semanas
• 🐛 Bug simples: 4 horas
• 🚀 Deploy: 2 horas + medo
• 🧪 Testes: 30% cobertura (fake)
• 💸 Custo: R$ 450k/ano em desperdício

DEPOIS (6 meses de refatoração gradual)

• 📁 60 mil linhas (mais código, mas organizado)
• ⏱️ Onboarding: 1 semana
• 🐛 Bug simples: 30 minutos
• 🚀 Deploy: 5 minutos (automatizado)
• 🧪 Testes: 85% cobertura (real)
• 💰 Economia: R$ 300k/ano

ROI

• Velocidade: 3x mais features entregues
• Qualidade: 70% menos bugs em produção
• Moral: Time feliz, produto evoluindo
• Negócio: Produto escalou de 10k para 100k usuários

Conclusão

Se você se identificou com os problemas:

• ✅ Código acoplado
• ✅ God classes
• ✅ Testes impossíveis
• ✅ Medo de mexer em qualquer coisa
• ✅ Onboarding que leva semanas
• ✅ Deploy que dá medo

A solução é Clean Architecture.

E você não precisa refatorar tudo de uma vez.

Comece Hoje

1. Escolha um módulo simples (notificações, autenticação)
2. Refatore em 1-2 dias (use o padrão que mostrei)
3. Documente o padrão (ADR + README)
4. Repita (um módulo por sprint)

Em 6 meses, você terá:

• ✅ Código que outros entendem
• ✅ Testes que rodam rápido
• ✅ Deploy sem medo
• ✅ Time feliz
• ✅ Produto que escala

Próximo artigo: "Testes que não testam nada: como escrever testes que realmente importam"

Escrito por TechMindDev — Specs antes de código. Arquitetura antes de features. Tolerância zero ao Código Frankenstein.