# Swe Solution Design

> Design de soluções técnicas e Architecture Decision Records (ADRs) para projetos Python. Use quando o usuário pedir para projetar uma solução, criar uma especificação técnica, documentar decisões arquiteturais, comparar alternativas tecnológicas, planejar uma feature complexa, escrever um RFC, desenhar o fluxo de um sistema, ou qualquer tarefa de design e documentação de decisões de engenharia.

- Skill: `nxs-cafi/swe-solution-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nxs-cafi/swe-solution-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nxs-cafi/swe-solution-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nxs-cafi (https://skillmd.com/u/nxs-cafi)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/nxs-cafi/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.

```markdown
# 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.

```markdown
# 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)

```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