Software Architecture Skill - Antigravity Standards

Under-Engineering

• Codigo sem nenhum teste
• Funcoes de 200 linhas fazendo 10 coisas
• Nomes sem significado (d, x, temp, data, info)
• Regras de negocio espalhadas por toda a aplicacao
• Sem tratamento de erro estruturado

FASE 2 - DECISAO DE ARQUITETURA

Pergunta-guia: "Qual e o menor design que resolve o problema atual com espaco para evoluir?"

BAIXA COMPLEXIDADE (CRUD, ferramentas simples):

• Estrutura minima funcional, Smart UI e aceitavel

MEDIA COMPLEXIDADE (SaaS, APIs com logica de dominio):

• Layered Architecture: Presentation/Application/Domain/Infrastructure
• Domain objects com comportamento, Repositories, Testes de unidade

ALTA COMPLEXIDADE (sistemas ricos, multiplos subdominios):

• DDD completo: Ubiquitous Language, Bounded Contexts, Aggregates com invariantes

FASE 3 - PRINCIPIOS DE CODIGO (CLEAN CODE)

Nomes

• Variaveis, funcoes e classes revelam INTENCAO sem comentario
• Classes: substantivos (OrderRepository, PaymentService, Customer)
• Metodos: verbos (calculateTotal, sendNotification, findById)
• Booleanos: predicados (isActive, hasPermission, canCheckout)
• Evite: data, info, manager, processor, handler sem contexto

Funcoes

• Fazem UMA coisa apenas
• ~20 linhas como referencia (nao dogma)
• Zero a dois parametros; tres exige justificativa; mais de tres quase nunca
• Sem parametros booleanos
• Separacao comando-consulta: ou muda estado OU retorna valor
• Prefira excecoes a codigos de erro

A Regra do Escoteiro

Todo codigo tocado deve ser deixado mais limpo do que foi encontrado.

FASE 4 - ESTRUTURA DE PASTAS

API REST / Backend

src/
├── domain/           # Coracao - sem dependencias externas
│   ├── entities/
│   ├── value-objects/
│   ├── repositories/  # Apenas interfaces/contratos
│   └── services/
├── application/      # Casos de uso
│   ├── use-cases/
│   └── dtos/
├── infrastructure/   # Implementacoes concretas
│   ├── database/
│   ├── http/
│   └── external/
└── shared/
    └── errors/
tests/
├── unit/
├── integration/
└── e2e/

Frontend

src/
├── domain/           # Logica de negocio pura
├── application/      # Estado e casos de uso de UI
├── presentation/     # Componentes visuais
├── infrastructure/   # API clients, storage
└── shared/
tests/
├── unit/
├── component/
└── e2e/

FASE 5 - DESIGN PATTERNS: QUANDO E COMO APLICAR

REGRA DE OURO: Nunca aplique um padrao antecipando um problema.

FASE 6 - TESTES (NUNCA OPCIONAIS)

"Codigo sem testes nao esta limpo." - Dave Thomas

Piramide de Testes:

• E2E: poucos, lentos - testam fluxos criticos completos
• Integracao: medio volume - testam integracao entre modulos
• Unidade: muitos, rapidos - testam logica de dominio pura

Regras:

• Testes de unidade testam logica pura sem I/O, sem banco, sem HTTP
• Nomenclatura: deve_[resultado]quando[condicao]
• Use fakes/stubs nos repositories

FASE 7 - SEGURANCA ESTRUTURAL

• Aggregates sempre verificam invariantes antes de persistir
• Factories so produzem objetos em estado valido
• Value Objects sao imutaveis
• Hierarquia de erros: DomainError > ApplicationError > InfrastructureError
• Mensagens de erro seguras para usuario; detalhes apenas no log

FASE 8 - CHECKLIST ANTES DE ENTREGAR

• Todos os nomes revelam intencao sem precisar de comentario?
• Cada funcao faz apenas uma coisa?
• Cada classe tem apenas uma responsabilidade?
• A logica de dominio esta testada?
• A logica de negocio esta no dominio, nao no controller?
• As dependencias apontam para dentro?
• Nao ha over-engineering (abstracoes sem uso)?
• Erros sao tratados explicitamente?
• O codigo esta mais limpo do que quando voce o recebeu?

FASE 9 - MODELO DE RESPOSTA PADRAO

1. ENTENDIMENTO DO DOMINIO
2. DECISAO DE ARQUITETURA
3. ESTRUTURA DE PASTAS
4. MODELO DE DOMINIO (se aplicavel)
5. CODIGO (dominio -> application -> infraestrutura)
6. TESTES (sempre junto com o codigo)
7. PROXIMOS PASSOS

REFERENCIAS