Transforma uma spec ou PRD de feature em plano técnico versionável com decisões, modelo de dados, contratos e quickstart.
Antes → Depois · resultado real
O mesmo pedido, com e sem a skill.
SaaS de gestão para escolas de idiomas: o PM entregou uma spec de 2 páginas — 'cobrança recorrente por Pix e boleto para os responsáveis dos alunos'. O tech lead sabe como isso termina: se começar a codar agora, metade das decisões será tomada no meio do PR, e fluxo de dinheiro não perdoa improviso.
Quem manda · Tech lead que já viu feature de cobrança virar dois sprints de retrabalho por decisão não escrita.
Antes · pedido improvisado
“implementa a cobrança recorrente aí, depois a gente vê os detalhes”
O que a IA devolve
Beleza! Já criei o endpoint /api/charge, escolhi o Stripe (é o melhor), salvei o cartão do responsável no nosso banco pra facilitar a recorrência e mandei o código direto pro branch main. Qualquer coisa a gente ajusta depois! 🚀
Por que é fraco · Coda antes de planejar, escolhe PSP por achismo (sem avaliar Pix/boleto nacional), armazena dado de cartão no próprio banco — risco grave — e empurra pra main sem revisão. Cada 'a gente ajusta depois' em fluxo de dinheiro é um incidente agendado.
Depois · com a skill
O comando
Use Plano Técnico a partir de Especificação.
Repo na raiz, com .specify/. Spec: spec.md — cobrança recorrente por Pix e boleto para responsáveis de alunos (escolas de idiomas).
Stack atual: Node + Postgres, auth própria, sem PSP contratado.
Quero plan.md, research.md, data-model.md, contracts/ e quickstart.md — decisões com racional e alternativas, dúvidas marcadas, riscos LGPD/financeiro. SEM implementar código.
O que a IA devolve
Toca nos 4 pins
Pré-checagem: raiz do repo OK, spec.md encontrada, `.specify/memory/constitution.md` lido. Scripts do Spec Kit revisados antes de qualquer execução — nada roda às cegas.
Contexto técnico: Node + Postgres, auth própria. PSP não contratado — toda decisão de integração fica condicionada a essa escolha.
Constitution check: o padrão do projeto exige teste de integração em fluxo de dinheiro e proíbe segredo em código — o plano herda os dois gates.
NEEDS CLARIFICATION (bloqueiam as fases seguintes):
Regra de multa/juros por atraso: vem da escola ou é fixa do produto?
Responsável inadimplente: bloqueia o acesso do aluno ou só notifica?
Retenção de dados de pagamento após cancelamento do contrato da escola?
research.md (decisões com racional e alternativas):
Recorrência via cobrança gerada mês a mês (Pix/boleto), não tokenização de cartão: a spec não pede cartão e .
Alternativa descartada: polling de status — mais simples, mas atrasa a baixa do pagamento e quebra a conciliação da escola.
data-model.md (entidades, estados, validações):
`Responsavel`: dados mínimos (nome, CPF validado e mascarado na exibição, e-mail de cobrança).
`Cobranca`: estados `pendente → paga | vencida | cancelada` — transição só por webhook verificado ou ação administrativa auditada.
`WebhookPagamento`: `event_id` único (idempotência), payload bruto com retenção curta a definir.
contracts/: `POST /cobrancas` (criar) · `GET /cobrancas/:id` (status) · `POST /webhooks/pagamento` (confirmação — autenticado por assinatura do PSP, resposta idempotente). Erros mapeados: cobrança duplicada, CPF inválido, assinatura de webhook inválida.
quickstart.md (cenários de QA): cadastro válido; CPF inválido; webhook duplicado (mesmo `event_id` 2x → uma baixa só); boleto vencido; Pix expirado; cancelamento com cobrança em aberto.
Riscos e escalonamento: ; multa, juros e conciliação → financeiro/contábil; assinatura de webhook e gestão de segredos → revisão de segurança.
Fechamento: 5 artefatos planejados, 4 dúvidas bloqueantes nomeadas, zero linha de código de produção. Próximo passo: PM responde as clarificações 1-3 antes de a fase de design fechar.
Por que ganha · Pára exatamente onde a skill manda parar — no plano. As 4 dúvidas que iam virar retrabalho ganham nome de NEEDS CLARIFICATION, o webhook nasce idempotente, cartão fica fora do banco por decisão escrita e dado de menor de idade sobe pro DPO antes do primeiro commit.
O 'implementa aí que depois a gente vê' virou plano com 4 dúvidas bloqueantes nomeadas, webhook idempotente e zero cartão no banco — antes da primeira linha de código.
antes ~2 sprints de retrabalho por decisão não escrita → depois ~40min revisando o plano com o PM
Um conjunto de artefatos de planejamento técnico: plan.md, research.md, data-model.md, contracts/ quando aplicável e quickstart.md.
Do PRD ao plano técnico executável, com menos ambiguidade entre produto e engenharia.
Problema: Times têm specs, tickets ou PRDs, mas decisões técnicas ficam espalhadas em Slack, Jira e reuniões, causando retrabalho, escopo mal entendido e riscos não mapeados antes da sprint.
Fluxo: Planejar
Exemplo de pedido pronto (prévia)
Usando uma spec de cadastro de cliente PJ para um SaaS B2B em um repositório com Spec Kit, gere o plano técnico e liste os artefatos esperados sem implementar código.
