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 pedido
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
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.
⦿ A receita inteira · aberta
sem cadastro · sem pagar
Esta é uma das skills que a gente deixa aberta pra leitura. O arquivo abaixo é exatamente o que quem tem o catálogo completo recebe — entrada, passos, revisão e formato de saída. Use no seu assistente e adapte ao seu contexto.
---
name: "plano-tecnico-de-especificacao"
description: "Transforma uma especificação de feature em plano técnico versionável, com decisões, modelo de dados, contratos, quickstart e guardrails brasileiros."
---
# Plano Técnico a partir de Especificação
Use esta skill para converter uma spec, PRD ou ticket de feature em um plano técnico claro antes de implementar. Ela preserva a intenção do Spec Kit: gerar artefatos como `plan.md`, `research.md`, `data-model.md`, `contracts/` e `quickstart.md`, idealmente dentro de um repositório com `.specify/`. Se o time não usa Spec Kit, aplique o mesmo fluxo manualmente em arquivos Markdown.
## Quando Usar
- Depois que produto escreveu uma spec/PRD e antes de engenharia começar a codar.
- Para alinhar PM, tech lead, arquitetura, QA e engenharia sobre escopo técnico.
- Para registrar decisões, alternativas descartadas, riscos, dúvidas e dependências.
- Para features de SaaS B2B, marketplaces, sistemas internos, APIs, integrações, cobrança, permissões, dashboards e cadastros.
- Não use para implementar código, aprovar compliance ou substituir revisão técnica/jurídica.
## Resultado Esperado
Um plano técnico versionável contendo:
- contexto técnico, stack, restrições e assumptions;
- checagem da constituição/regras do projeto;
- dúvidas marcadas como `NEEDS CLARIFICATION` ou resolvidas em pesquisa;
- decisões técnicas com racional e alternativas;
- modelo de dados com entidades, estados, validações e relacionamentos;
- contratos de API, eventos, webhooks ou integrações quando aplicável;
- quickstart para desenvolvimento/QA;
- riscos, pendências e pontos de escalonamento humano.
## Entradas Necessarias
- Spec/PRD da feature: objetivo, usuários, fluxos, requisitos funcionais e não funcionais, critérios de aceite.
- Contexto do produto: stack, arquitetura atual, padrões, banco, autenticação, serviços existentes.
- Repositório Git, de preferência na raiz do projeto.
- Se usar Spec Kit: `.specify/scripts/...`, `.specify/memory/constitution.md` e template de plano.
- Restrições brasileiras relevantes: CPF/CNPJ, Pix, boleto, NF-e/NFS-e, dados pessoais, regras fiscais, antifraude, integrações bancárias.
- Lista de dúvidas conhecidas e decisões já tomadas.
## Processo
1. **Pré-checagem**: confirme se está na raiz do repo, se a spec existe e se os scripts `.specify` são esperados pelo projeto. Nunca rode script local sem revisar conteúdo, origem e permissões.
2. **Ler a spec**: extraia objetivo, usuários, fluxos principais, requisitos, exceções, integrações, dados tratados e critérios de aceite.
3. **Identificar lacunas**: marque como `NEEDS CLARIFICATION` quando faltar stack, regras de negócio, volume, permissões, dados obrigatórios, SLA ou integração crítica.
4. **Constitution Check**: compare a proposta com padrões do projeto: segurança, testes, observabilidade, arquitetura, acessibilidade, privacidade e qualidade.
5. **Fase 0 - Pesquisa**: registre decisões em `research.md`: opções avaliadas, escolha, motivo, trade-offs e riscos.
6. **Fase 1 - Design**: crie/atualize `plan.md`, `data-model.md`, `contracts/` e `quickstart.md`. Gere contratos apenas se houver API, evento, webhook, fila ou integração.
7. **Localização BR**: quando houver CPF/CNPJ, Pix, boleto, cartão, nota fiscal, logs ou dados de clientes, inclua minimização, retenção, acesso, auditoria e revisão humana.
8. **Fechamento**: reporte arquivos gerados/alterados, decisões principais, bloqueios, riscos e próximos passos. Não implemente código.
## Ferramentas E Artefatos
- Ferramentas comuns: GitHub, GitLab, Bitbucket, VS Code, Cursor, Claude Code, Jira, Linear, Notion, Confluence, Azure DevOps.
- Plataformas/formatos: Spec Kit, PowerShell, OpenAPI/Swagger, Postman, Markdown.
- Artefatos: `plan.md`, `research.md`, `data-model.md`, `contracts/`, `quickstart.md`, spec/PRD, API spec, checklist de riscos.
- Scripts típicos do Spec Kit: `setup-plan.ps1` e `update-agent-context.ps1`. Revise antes de executar.
## Exemplo Brasileiro
Spec: SaaS B2B quer cadastrar cliente PJ e ativar cobrança por Pix e boleto.
Plano deve incluir:
- entidades como `ClientePJ`, `EnderecoCobranca`, `Cobranca`, `MetodoPagamento`, `WebhookPagamento`;
- validação de CNPJ, e-mail de cobrança, status da cobrança e idempotência de webhooks;
- contratos de API para criar cliente, emitir cobrança e receber confirmação do provedor de pagamento;
- riscos: tratamento de dados pessoais de representantes, logs com identificadores, dependência do PSP, conciliação, falhas de boleto/Pix;
- revisão humana: jurídico/DPO para dados pessoais e financeiro/contábil para cobrança e obrigações fiscais;
- quickstart com cenários de QA: cadastro válido, CNPJ inválido, webhook duplicado, boleto vencido, Pix expirado.
## Criterios De Qualidade
- O plano está conectado à spec; não é genérico.
- Não inventa stack, endpoints, credenciais, regras fiscais ou integrações críticas.
- Dúvidas relevantes aparecem como `NEEDS CLARIFICATION` ou são tratadas em `research.md`.
- Decisões têm racional, alternativas e impacto.
- Modelo de dados inclui validações, estados, relacionamentos e campos sensíveis.
- Contratos aparecem só quando necessários e têm payloads, erros, autenticação e versionamento.
- Inclui riscos de LGPD, segurança, pagamentos/fiscal e escalonamento humano quando aplicável.
- Para no planejamento; não escreve código de produção.
## Cuidados, LGPD E Escalacao Humana
- Não declare conformidade legal, fiscal, bancária ou de segurança como certa. Use linguagem de triagem, checklist e revisão.
- Para dados pessoais: registre finalidade, minimização, base legal a validar, retenção, controle de acesso, criptografia quando aplicável, logs e auditoria.
- Escale para DPO/jurídico se houver dados sensíveis, profiling, compartilhamento externo, incidente ou retenção extensa.
- Escale para segurança se alterar autenticação, autorização, criptografia, RBAC, APIs públicas, webhooks ou segredos.
- Escale para financeiro/jurídico/contábil em Pix, boleto, cartão, split, antifraude, NF-e, NFS-e ou obrigações regulatórias.
- Recuse pedidos para ignorar gates, expor dados de clientes, armazenar cartão indevidamente ou rodar scripts desconhecidos sem revisão.
## Smoke Test
Prompt: “Usando uma spec de cadastro de cliente PJ em um repositório com Spec Kit, gere o plano técnico e liste os artefatos esperados sem implementar código.”
Passa se a saída trouxer: `plan.md`, `research.md`, `data-model.md`, `contracts/` quando houver API, `quickstart.md`, caminhos/assumptions, dúvidas `NEEDS CLARIFICATION`, riscos LGPD/segurança e indicação de revisão humana. Falha se implementar código, alucinar arquivos inexistentes, ignorar dados pessoais ou recomendar execução cega de scripts.
