Especificar

Especificar (Spec-Driven Development)

Visão geral

Escreva uma especificação estruturada antes de escrever qualquer código. A spec é a fonte de verdade compartilhada entre você e o engenheiro humano — define o que estamos construindo, por quê, e como saberemos que está pronto. Código sem spec é chute.

Quando usar

• Início de projeto ou feature nova
• Requisitos ambíguos ou incompletos
• A mudança toca vários arquivos ou módulos
• Você está prestes a tomar uma decisão arquitetural
• A tarefa levaria mais de 30 minutos para implementar

Quando NÃO usar: correções de uma linha, typos, ou mudanças cujos requisitos são inequívocos e autocontidos.

O fluxo (com portões)

Quatro fases. Não avance para a próxima antes de a atual ser validada pelo humano.

ESPECIFICAR ──→ PLANEJAR ──→ TAREFAS ──→ IMPLEMENTAR
     │              │            │             │
     ▼              ▼            ▼             ▼
  Humano         Humano       Humano        Humano
  revisa         revisa       revisa        revisa

Fase 1: Especificar

Se existir docs/prd.md, leia-o primeiro — a spec é a derivação técnica dele. O PRD (skill prd) define o quê e por quê na linguagem do produto; esta spec traduz aquilo em decisões de engenharia. Cada requisito da spec deve ser rastreável a uma seção do PRD, e nenhum escopo novo pode entrar aqui escondido: se algo faltar no PRD, volte e corrija-o antes. Em caso de contradição entre os dois, é a spec que está errada.

Comece pela visão de alto nível e faça perguntas de esclarecimento até os requisitos ficarem concretos (se o pedido estiver muito subespecificado, rode antes a skill entrevistar; se for um produto ou funcionalidade nova de porte, rode prd antes desta).

Exponha as suposições imediatamente. Antes de escrever qualquer conteúdo da spec, liste o que você está assumindo:

SUPOSIÇÕES QUE ESTOU FAZENDO:
1. É uma aplicação web (não mobile nativo)
2. Autenticação usa cookies de sessão (não JWT)
3. O banco é PostgreSQL (com base no schema Prisma existente)
4. Alvo são navegadores modernos apenas
→ Corrija-me agora ou seguirei com essas premissas.

Nunca preencha requisitos ambíguos em silêncio. O propósito da spec é revelar mal-entendidos antes do código — e suposições são a forma mais perigosa de mal-entendido.

Escreva a spec cobrindo estas seis áreas centrais:

1. Objetivo — O que estamos construindo e por quê? Quem é o usuário? O que é sucesso?

2. Comandos — Comandos executáveis completos, com flags, não apenas nomes de ferramentas:

   Build: npm run build
   Teste: npm test -- --coverage
   Lint:  npm run lint --fix
   Dev:   npm run dev
   

3. Estrutura do projeto — Onde vive o código-fonte, onde ficam os testes, onde ficam os docs:

   src/            → código-fonte da aplicação
   src/components  → componentes React
   src/lib         → utilitários compartilhados
   tests/          → testes de unidade e integração
   e2e/            → testes ponta a ponta
   docs/           → documentação
   

4. Estilo de código — Um trecho real de código exemplificando o estilo vale mais que três parágrafos descrevendo-o. Inclua convenções de nomenclatura e regras de formatação.

5. Estratégia de testes — Qual framework, onde os testes vivem, expectativas de cobertura, qual nível de teste para qual preocupação.

6. Limites — Sistema de três camadas:

   • Sempre fazer: rodar testes antes de commits, seguir convenções de nomenclatura, validar entradas
   • Perguntar antes: mudanças de schema do banco, adição de dependências, alterações na config de CI
   • Nunca fazer: commitar segredos, editar diretórios de terceiros, remover testes que falham sem aprovação

Modelo de spec: use o modelo completo em referencias/modelo-de-spec.md — leia-o somente quando chegar nesta etapa.

Reformule instruções como critérios de sucesso. Ao receber requisitos vagos, traduza-os em condições concretas:

REQUISITO: "Deixe o dashboard mais rápido"

CRITÉRIOS DE SUCESSO REFORMULADOS:
- LCP do dashboard < 2,5 s em conexão 4G
- Carga inicial de dados em < 500 ms
- Sem deslocamento de layout durante a carga (CLS < 0,1)
→ Esses são os alvos certos?

Isso permite iterar e resolver problemas rumo a um objetivo claro, em vez de adivinhar o que "mais rápido" significa.

Fase 2: Planejar

Com a spec validada, gere o plano técnico de implementação:

1. Identifique os componentes principais e suas dependências
2. Determine a ordem de implementação (o que precisa vir primeiro)
3. Anote riscos e estratégias de mitigação
4. Separe o que pode ser paralelo do que é sequencial
5. Defina pontos de verificação entre fases

Siga a skill planejar para a mecânica de grafo de dependências e fatiamento vertical — ela é a fonte canônica. Os itens acima são um resumo; se divergirem, planejar prevalece.

Convenção de saída: salve o plano em tarefas/plano.md e a lista de tarefas em tarefas/pendencias.md (crie tarefas/ se não existir). Comandos a jusante esperam esses caminhos.

O plano deve ser revisável: o humano precisa conseguir lê-lo e dizer "sim, essa é a abordagem certa" ou "não, mude X".

Fase 3: Tarefas

Quebre o plano em tarefas discretas e implementáveis:

• Cada tarefa cabe em uma sessão focada
• Cada tarefa tem critérios de aceitação explícitos
• Cada tarefa inclui um passo de verificação (teste, build, checagem manual)
• Ordem definida por dependência, não por importância percebida
• Nenhuma tarefa deve tocar mais de ~5 arquivos

A mecânica completa de dimensionamento e ordenação está na skill planejar (fonte canônica). Modelo inline resumido:

- [ ] Tarefa: [descrição]
  - Aceitação: [o que precisa ser verdade quando concluída]
  - Verificação: [como confirmar — comando de teste, build, checagem manual]
  - Arquivos: [quais arquivos serão tocados]

Fase 4: Implementar

Execute as tarefas uma a uma seguindo as skills implementar e teste-primeiro. Use a skill contexto para carregar apenas as seções relevantes da spec e os arquivos-fonte necessários a cada passo, em vez de inundar o agente com a spec inteira.

Mantendo a spec viva

A spec é um documento vivo, não um artefato descartável:

• Atualize quando decisões mudarem — se o modelo de dados precisa mudar, atualize a spec primeiro, depois implemente.
• Atualize quando o escopo mudar — features adicionadas ou cortadas devem se refletir na spec.
• Commite a spec — ela pertence ao controle de versão, junto do código.
• Referencie a spec nos pull requests — vincule cada PR à seção da spec que ele implementa.

Racionalizações comuns

Racionalização	Realidade
"Isso é simples, não preciso de spec"	Tarefas simples não precisam de specs longas, mas ainda precisam de critérios de aceitação. Uma spec de duas linhas serve.
"Escrevo a spec depois de codar"	Isso é documentação, não especificação. O valor da spec está em forçar clareza antes do código.
"A spec vai nos atrasar"	Uma spec de 15 minutos evita horas de retrabalho.
"Os requisitos vão mudar de qualquer jeito"	Por isso a spec é viva. Uma spec desatualizada ainda é melhor que nenhuma.
"O usuário sabe o que quer"	Até pedidos claros carregam suposições implícitas. A spec as expõe.

Sinais de alerta

• Começar a escrever código sem nenhum requisito por escrito
• Perguntar "posso já começar a construir?" antes de esclarecer o que é "pronto"
• Implementar features que não constam em nenhuma spec ou lista de tarefas
• Tomar decisões arquiteturais sem documentá-las
• Pular a spec porque "é óbvio o que construir"

Portão de aprovação

Apresente: a spec completa com as seis áreas, a lista de suposições e os critérios de sucesso reformulados como condições testáveis. O humano aprova: as suposições, os limites (Sempre / Perguntar antes / Nunca) e os critérios de sucesso — e depois, em portões separados, o plano (Fase 2) e a lista de tarefas (Fase 3). Só avance após aprovação explícita em cada portão; sem aprovação da spec, nenhum plano; sem aprovação do plano, nenhuma tarefa; sem aprovação das tarefas, nenhum código.

Verificação

Antes de prosseguir para a implementação, confirme:

• A spec cobre as seis áreas centrais
• O humano revisou e aprovou a spec
• Os critérios de sucesso são específicos e testáveis
• Os limites (Sempre / Perguntar antes / Nunca) estão definidos
• A spec está salva em um arquivo no repositório