8 min leitura • Guide 758 of 877
Especificações Técnicas para Desenvolvimento
Boas especificações previnem retrabalho. O GitScrum ajuda equipes a criar e rastrear specs técnicas que guiam implementação de forma efetiva.
Quando Escrever Specs
Árvore de Decisão
VOCÊ PRECISA DE UMA SPEC TÉCNICA?
┌─────────────────────────────────────────────────────────────┐
│ │
│ Este trabalho é significativo? │
│ (> 1 semana de trabalho, múltiplos componentes, arriscado)│
│ │
│ SIM NÃO │
│ ↓ ↓ │
│ Coordenação cross-equipe É bem entendido? │
│ é necessária? │
│ SIM → Descrição de tarefa │
│ SIM → SPEC COMPLETA NÃO → Mini-spec ou RFC │
│ NÃO → É arquiteturalmente │
│ significativo? │
│ │
│ SIM → DESIGN DOC / ADR │
│ NÃO → MINI-SPEC │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ │
│ SPEC COMPLETA: Features novas, redesigns, integrações │
│ MINI-SPEC: Mudanças menores que precisam clareza │
│ ADR: Decisões de arquitetura │
│ DESC TAREFA: Trabalho pequeno e bem entendido │
│ │
│ NA DÚVIDA: │
│ Se você precisaria explicar para alguém por > 5 minutos, │
│ escreva. │
└─────────────────────────────────────────────────────────────┘
Estrutura da Spec
Template de Spec Técnica
TEMPLATE DE ESPECIFICAÇÃO TÉCNICA:
┌─────────────────────────────────────────────────────────────┐
│ SPEC: Feature de Exportação de Usuários │
├─────────────────────────────────────────────────────────────┤
│ │
│ Autor: @alex │
│ Status: Rascunho → Revisão → Aprovado │
│ Data: 2024-01-15 │
│ Tarefa Relacionada: PROJ-123 │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ │
│ 1. VISÃO GERAL │
│ ────────────── │
│ Resumo breve do que esta feature faz e por quê. │
│ │
│ 2. BACKGROUND │
│ ──────────── │
│ Contexto: Por que estamos construindo isso? │
│ Estado atual: Como funciona hoje? │
│ Fonte de requisitos: Link para requisitos de produto │
│ │
│ 3. OBJETIVOS E NÃO-OBJETIVOS │
│ ─────────────────────────── │
│ Objetivos: │
│ • O que estamos resolvendo │
│ │
│ Não-objetivos: │
│ • O que explicitamente NÃO estamos resolvendo │
│ • Considerações futuras │
│ │
│ 4. SOLUÇÃO PROPOSTA │
│ ─────────────────── │
│ Abordagem de alto nível e arquitetura │
│ │
│ 5. DESIGN DETALHADO │
│ ─────────────────── │
│ Mudanças de API, modelos de dados, interações │
│ │
│ 6. EDGE CASES │
│ ───────────── │
│ O que acontece quando...? │
│ │
│ 7. ESTRATÉGIA DE TESTES │
│ ─────────────────────── │
│ Como isso será testado? │
│ │
│ 8. PLANO DE ROLLOUT │
│ ─────────────────── │
│ Como será deployed e monitorado? │
│ │
│ 9. PERGUNTAS ABERTAS │
│ ──────────────────── │
│ Decisões ainda necessárias │
│ │
│ 10. APÊNDICE │
│ ──────────── │
│ Diagramas, exemplos de API, referências │
└─────────────────────────────────────────────────────────────┘
Seção de Design Detalhado
EXEMPLO DE DESIGN DETALHADO:
┌─────────────────────────────────────────────────────────────┐
│ 5. DESIGN DETALHADO │
│ │
│ 5.1 DESIGN DE API │
│ │
│ Novo endpoint: │
│ │
│ POST /api/v1/users/export │
│ Request: │
│ { │
│ "format": "csv" | "json", │
│ "filters": { │
│ "created_after": "2024-01-01", │
│ "status": "active" │
│ }, │
│ "fields": ["id", "name", "email", "created_at"] │
│ } │
│ │
│ Response (async): │
│ { │
│ "export_id": "exp_123", │
│ "status": "processing", │
│ "estimated_time_seconds": 60 │
│ } │
│ │
│ 5.2 MODELO DE DADOS │
│ │
│ Nova tabela: exports │
│ ├── id (uuid) │
│ ├── user_id (foreign key) │
│ ├── status (enum: pending, processing, completed, failed)│
│ ├── format (enum: csv, json) │
│ ├── file_url (string, nullable) │
│ ├── error_message (string, nullable) │
│ ├── created_at (timestamp) │
│ └── completed_at (timestamp, nullable) │
│ │
│ 5.3 FLUXO DE PROCESSAMENTO │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Request │ → │ Validate│ → │ Queue │ → │ Process │ │
│ └─────────┘ └─────────┘ │ Job │ │ Export │ │
│ └─────────┘ └────┬────┘ │
│ │ │
│ ┌─────────────────────────────────────────────┘ │
│ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Upload │ → │ Update │ → │ Notify │ │
│ │ to S3 │ │ Status │ │ User │ │
│ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────┘
Edge Cases
Documentando Edge Cases
EDGE CASES IMPORTANTES:
┌─────────────────────────────────────────────────────────────┐
│ 6. EDGE CASES │
│ │
│ 6.1 DADOS GRANDES │
│ O que acontece com exportação de 1M+ registros? │
│ → Streaming, paginação, ou limite com warning │
│ │
│ 6.2 DADOS AUSENTES │
│ O que acontece se campos solicitados não existem? │
│ → Retornar null/vazio, não falhar │
│ │
│ 6.3 REQUISIÇÕES CONCORRENTES │
│ Usuário pode iniciar múltiplas exportações? │
│ → Sim, máximo 3 simultâneas, rate limit depois │
│ │
│ 6.4 FALHA DURANTE PROCESSAMENTO │
│ Export falha no meio? │
│ → Retry 3x, depois marca como failed com mensagem │
│ │
│ 6.5 PERMISSÕES │
│ Usuário pode exportar dados de outros? │
│ → Não, apenas dados próprios (admin pode todos) │
│ │
│ 6.6 CARACTERES ESPECIAIS │
│ Como lidar com vírgulas/quebras em CSV? │
│ → Escape padrão RFC 4180 │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ REGRA: │
│ Para cada input, pergunte: "O que acontece se...?" │
│ • Valor muito grande/pequeno │
│ • Valor nulo/vazio │
│ • Valor malicioso │
│ • Operação concorrente │
│ • Falha no meio │
└─────────────────────────────────────────────────────────────┘
Qualidade de Specs
Checklist de Spec
CHECKLIST DE QUALIDADE DE SPEC:
┌─────────────────────────────────────────────────────────────┐
│ │
│ COMPLETUDE: │
│ ☐ Problema claramente definido │
│ ☐ Solução descrita em detalhe suficiente │
│ ☐ Edge cases documentados │
│ ☐ Estratégia de teste definida │
│ ☐ Plano de rollout incluído │
│ │
│ CLAREZA: │
│ ☐ Alguém de fora entende sem explicação verbal? │
│ ☐ Termos ambíguos definidos? │
│ ☐ Diagramas onde ajudam? │
│ ☐ Exemplos concretos (não só abstratos)? │
│ │
│ IMPLEMENTABILIDADE: │
│ ☐ Desenvolvedor pode começar sem perguntas? │
│ ☐ APIs especificadas com request/response? │
│ ☐ Modelos de dados definidos? │
│ ☐ Dependências identificadas? │
│ │
│ REVISÃO: │
│ ☐ Revisado por pelo menos 1 dev que vai implementar │
│ ☐ Revisado por stakeholder de produto │
│ ☐ Perguntas abertas resolvidas ou documentadas │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ NÍVEL DE DETALHE: │
│ │
│ MUITO POUCO: │
│ "Implementar exportação de usuários" │
│ → Implementador não sabe por onde começar │
│ │
│ DEMAIS: │
│ 50 páginas especificando cada linha de código │
│ → Spec desatualiza, implementador não lê │
│ │
│ IDEAL: │
│ O quê e porquê claros, como com flexibilidade │
│ → Implementador pode tomar decisões táticas │
└─────────────────────────────────────────────────────────────┘
Processo de Spec
Workflow
WORKFLOW DE SPEC:
┌─────────────────────────────────────────────────────────────┐
│ │
│ 1. RASCUNHO │
│ ──────── │
│ Autor escreve versão inicial │
│ Status: Draft │
│ │
│ 2. REVIEW │
│ ────── │
│ • Dev que vai implementar revisa │
│ • PM valida requisitos │
│ • Tech lead revisa arquitetura │
│ Status: In Review │
│ │
│ 3. ITERAÇÃO │
│ ──────── │
│ Atualizar baseado em feedback │
│ Resolver perguntas abertas │
│ │
│ 4. APROVAÇÃO │
│ ───────── │
│ Stakeholders aprovaem │
│ Status: Approved │
│ │
│ 5. IMPLEMENTAÇÃO │
│ ───────────── │
│ Desenvolver seguindo spec │
│ Atualizar spec se descobrir coisas novas │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ TEMPO TÍPICO: │
│ Spec pequena: 1-2 dias draft + 1 dia review │
│ Spec média: 3-5 dias draft + 2-3 dias review │
│ Spec grande: 1-2 semanas draft + 1 semana review │
└─────────────────────────────────────────────────────────────┘