Swe Solution Design

Solution Design — Python SWE Agent

Antes de Qualquer Design: As Perguntas Certas

Antes de propor qualquer solução, responda:

1. Qual PROBLEMA estamos resolvendo? (não: "o que vamos construir")
2. Quais são as constraints? (prazo, equipe, performance, custo)
3. Quais são os requisitos de qualidade? (SLA, latência, disponibilidade)
4. Quais são as alternativas? (pelo menos 3, mesmo que óbvias)
5. Como saberemos que funcionou? (critérios de sucesso mensuráveis)

Template de Architecture Decision Record (ADR)

Use para qualquer decisão com impacto >2 semanas de trabalho ou difícil de reverter.

# ADR-{NNN}: {Título descritivo e específico}

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-{NNN}
**Data:** YYYY-MM-DD
**Autores:** @nome
**Contexto:** #{issue ou ticket}

## Contexto

{Descreva o problema ou necessidade que gerou esta decisão.
Inclua constraints relevantes: técnicos, organizacionais, temporais.
Seja específico — evite generalidades.}

## Decisão

{Descreva a solução escolhida de forma direta e afirmativa.
"Vamos usar X para Y porque Z."}

## Alternativas Consideradas

### Opção A: {Nome} ← ESCOLHIDA
- **Prós:** ...
- **Contras:** ...
- **Custo de reversão:** Baixo / Médio / Alto

### Opção B: {Nome}
- **Prós:** ...
- **Contras:** ...
- **Por que não:** {razão específica}

### Opção C: {Nome}
- **Prós:** ...
- **Contras:** ...
- **Por que não:** {razão específica}

## Consequências

### Positivas
- ...

### Negativas / Trade-offs aceitos
- ...

### Riscos e Mitigações
| Risco | Probabilidade | Impacto | Mitigação |
|-------|--------------|---------|-----------|
| ... | Baixa/Média/Alta | Baixo/Médio/Alto | ... |

## Plano de Implementação

- [ ] Fase 1: ...
- [ ] Fase 2: ...
- [ ] Critérios de rollback: ...

## Referências
- [Link para doc/issue/RFC]

Template de Especificação Técnica (Tech Spec)

Para features que envolvem múltiplos componentes ou >1 semana de desenvolvimento.

# Tech Spec: {Nome da Feature}

**Status:** Draft | Review | Approved | Done
**Equipe:** @nome1, @nome2
**Timeline:** {data início} → {data entrega}
**Ticket:** #{número}

## Objetivo

{Uma frase: o que isso faz e por que importa para o negócio.}

## Não-Objetivos (Fora de Escopo)

{O que explicitamente NÃO será feito nesta iteração.}

## Solução Técnica

### Visão Geral
{Diagrama ou descrição de alto nível do fluxo.}

### Modelo de Dados
{Novas tabelas/campos, mudanças no schema existente.}

### APIs
{Novos endpoints ou mudanças em existentes.}

### Fluxo Principal
{Passo a passo do caminho feliz.}

### Tratamento de Erros
{Como cada falha possível é tratada.}

## Impactos

### Performance
{Estimativa de load, queries adicionais, caches necessários.}

### Segurança
{Novos vetores de ataque? Mudanças de permissão?}

### Observabilidade
{Novos logs, métricas, alertas necessários.}

### Migrations
{Backwards compatible? Downtime necessário?}

## Plano de Testes

| Tipo | Cenário | Critério de Aceite |
|------|---------|-------------------|
| Unit | ... | ... |
| Integration | ... | ... |
| E2E | ... | ... |
| Load | ... | ... |

## Rollout

- [ ] Feature flag: `{nome_da_flag}`
- [ ] Rollout gradual: 1% → 10% → 100%
- [ ] Critério de rollback: {métrica + threshold}

Frameworks de Decisão

Escolha de Banco de Dados

Precisa de ACID + relações complexas?       → PostgreSQL
Documentos sem schema fixo?                 → MongoDB
Cache/sessões/filas simples?                → Redis
Analytics / OLAP?                           → ClickHouse / BigQuery
Time series (métricas, IoT)?               → TimescaleDB / InfluxDB

Escolha de Comunicação entre Serviços

Request/Response síncrono?                  → REST (HTTP) ou gRPC
Eventos assíncronos / desacoplamento?       → Kafka / RabbitMQ / SQS
Tarefas em background / jobs?              → Celery + Redis/RabbitMQ
Real-time / bidirectional?                 → WebSocket / SSE

Quando Criar um Microsserviço

✅ Crie microsserviço se:
   - Time dedicado e independente para operar
   - SLA/escalabilidade muito diferente do monolito
   - Domínio genuinamente separado (bounded context claro)
   - Linguagem/runtime diferente justificado

❌ NÃO crie microsserviço se:
   - "Vai ficar mais organizado" (use módulos)
   - "Vai escalar melhor" (prove com dados)
   - Time <10 engenheiros sem SRE dedicado
   - Bounded context ainda não está claro

Estimativa de Complexidade

XS — 1-2 dias:   mudança isolada, sem novo modelo de dados
S  — 3-5 dias:   1 use case novo, 1 endpoint, testes inclusos
M  — 1-2 sem:    feature completa, migrations, integração externa
L  — 2-4 sem:    redesign de componente, múltiplos serviços
XL — 1+ mês:     mudança arquitetural, migração de dados em larga escala

Regra: Se a estimativa for L ou XL, exija Tech Spec aprovada antes de iniciar.

Diagrama de Arquitetura — Convenção (Mermaid)

graph TB
    Client[Cliente Web/Mobile]
    API[FastAPI — API Gateway]
    UC[Use Cases]
    Domain[Domínio]
    Repo[Repositories]
    DB[(PostgreSQL)]
    Cache[(Redis)]
    Queue[Celery Queue]
    Worker[Background Worker]

    Client -->|HTTPS| API
    API --> UC
    UC --> Domain
    UC --> Repo
    Repo --> DB
    UC --> Cache
    UC --> Queue
    Queue --> Worker
    Worker --> Repo

Checklist — Antes de Apresentar um Design

• O problema está claramente definido (não só a solução)
• Pelo menos 3 alternativas foram consideradas
• Trade-offs estão documentados explicitamente
• Impacto em sistemas existentes está mapeado
• Plano de rollback existe se a decisão for reversível
• Critérios de sucesso são mensuráveis
• Segurança foi considerada
• Observabilidade foi planejada
• Estimativa de esforço está presente