Desenvolvimento Orientado por Especificação (SDD) — modo guiado

O usuário nunca deve precisar conhecer o fluxo SDD. Você o dirige: a cada turno, você descobre onde o projeto está, faz tudo o que puder sozinho, pergunta apenas o que não consegue inferir e termina informando exatamente o que acontece em seguida.

Cada funcionalidade passa por spec.md → design.md → tasks.md → implementação → review.md. Os templates estão em ${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates/. Inicie todo comando shell que copie templates com T="${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates"; (os trechos abaixo usam $T).

O loop (execute toda vez que a skill for usada)

Detecte o estado (veja Detecção de estado). Faça isso silenciosamente — leia arquivos, não pergunte ao usuário onde ele está.
Absorva a entrada. O que quer que o usuário tenha enviado — um caminho de task.md, um documento colado, uma frase, "continue", "ok" — mapeie para a etapa atual (veja Tratamento de entrada).
Faça o trabalho da etapa você mesmo. Redija o documento com base no que você sabe: a entrada, docs/PRODUCT.md, docs/PRINCIPLES.md, docs/ARCHITECTURE.md, docs/GLOSSARY.md e o próprio código. Inspecione a base de código em vez de perguntar coisas que o código responde (stack, comandos, caminhos de arquivo, padrões existentes). Escreva cada documento de acordo com Estilo de escrita e execute sua auto-verificação antes de mostrar o documento.
Pergunte apenas as lacunas (veja Fazendo perguntas). Nunca pergunte por algo que você já redigiu com confiança razoável — mostre e deixe o usuário corrigir.
Finalize com o bloco-guia (veja Bloco-guia). Toda resposta termina com ele, sem exceção.

Fale com o usuário no idioma em que ele escreve. Escreva os documentos no idioma que os documentos existentes do projeto usam (inglês se não houver nenhum ainda, a menos que o usuário peça o contrário).

Detecção de estado

Verifique nesta ordem e pare na primeira correspondência:

#	Condição	Etapa atual
1	Nenhum `docs/PRODUCT.md` ou `docs/PRINCIPLES.md`	Setup — documentos do projeto
2	`PRODUCT.md`/`PRINCIPLES.md` ainda contém texto `[placeholder]`	Setup — termine de preenchê-los
3	Usuário enviou novo trabalho (arquivo, texto, ideia) que não é a funcionalidade ativa	Triagem do novo trabalho
4	Funcionalidade ativa tem `spec.md` com `status: draft`	Spec
5	`spec.md` aprovado, `design.md` ausente ou `status: draft`	Design
6	`design.md` aprovado, `tasks.md` ainda tem placeholders do template	Tasks (planejamento)
7	`tasks.md` tem algum `T` não `done`	Implementar — próximo `T`
8	Todos `T` concluídos, `review.md` `status: pending`	Review
9	`review.md` aprovado / aprovado-com-observações	Fechar — memória + estado, então ofereça a próxima funcionalidade

Funcionalidade ativa = aquela nomeada em docs/MEMORY.md → Estado Atual → Em andamento; se estiver vazio, a de maior número em docs/specs/NNN-*/ cujo review.md não está aprovado. Se várias estiverem abertas e o usuário não nomeou uma, pergunte qual (uma pergunta, liste-as).

Uma maneira rápida de ler o estado:

ls docs/ docs/specs/ 2>/dev/null
grep -H '^status:' docs/specs/*/*.md 2>/dev/null
grep -H -- '- \*\*Status:\*\*' docs/specs/*/tasks.md 2>/dev/null

Tratamento de entrada

Um caminho para um task.md (ou qualquer .md/.txt) — leia-o completamente. Trate como requisitos brutos, não como um tasks.md finalizado: extraia problema, comportamentos, exemplos, casos de borda, restrições, dicas de arquivos. Depois faça a triagem.
Texto colado ou ideia de uma linha — igual ao acima.
"continue" / "próximo" / "ok" / "aprovado" / "pode seguir" — se o documento atual está aguardando aprovação, isto é aprovação: defina seu status e vá para a próxima etapa na mesma resposta. Caso contrário, apenas execute a etapa atual.
Uma correção ou resposta — aplique ao documento atual, atualize qualquer Q que ela resolva, re-verifique lacunas, continue.
Uma pergunta sobre o fluxo — responda brevemente, depois retome com o bloco-guia.

Triagem (novo trabalho)

Decida o tamanho e diga o que decidiu em uma linha:

Pequeno — óbvio, reversível, ~1–3 arquivos, nenhuma decisão de design (erro de digitação, pequeno bug, mudança de configuração). Crie apenas tasks.md (em docs/specs/NNN-name/), preencha-o e vá direto para Implementar. Pule spec/design/review a menos que o usuário os queira.
Funcionalidade — qualquer coisa com comportamento a definir ou uma escolha de design. Execute o fluxo completo.
Precisa de pesquisa — uma escolha chave é genuinamente desconhecida (biblioteca, abordagem, fornecedor). Fluxo completo mais research.md antes do design.

Em caso de dúvida entre pequeno e funcionalidade, escolha funcionalidade e diga que o usuário pode pedir para atalhar.

Em seguida, crie a pasta:

Próximo número = maior NNN- em docs/specs/ + 1 (comece em 001). Nome = kebab-case curto a partir da entrada; não pergunte por ele.
Copie os templates:

D=docs/specs/NNN-nome-da-funcionalidade; mkdir -p "$D"
cp $T/specs/spec.md $T/specs/design.md $T/specs/tasks.md $T/specs/review.md "$D"/
# apenas se pesquisa for necessária:
cp $T/specs/research.md "$D"/

Coloque tudo o que foi extraído da entrada nos documentos certos imediatamente: problema/ACs/restrições/fora-de-escopo → spec.md; dicas de implementação e caminhos de arquivo → mantenha como notas para design.md/tasks.md (não as perca; adicione-as sob a seção relevante quando chegar lá).
Atualize docs/MEMORY.md → Estado Atual → Em andamento com o ID da funcionalidade e etapa.
Continue diretamente para a etapa Spec na mesma resposta.

Etapas

Setup

mkdir -p docs/decisions docs/specs
for f in PRODUCT PRINCIPLES ARCHITECTURE GLOSSARY MEMORY; do [ -f docs/$f.md ] || cp $T/$f.md docs/$f.md; done
[ -f docs/decisions/0000-template.md ] || cp $T/decisions/0000-template.md docs/decisions/
[ -f CLAUDE.md ] || cp $T/CLAUDE.md CLAUDE.md

Nunca sobrescreva arquivos existentes. Em seguida, pré-preencha a partir do repositório antes de perguntar qualquer coisa: leia package.json / pyproject.toml / go.mod / Cargo.toml / Makefile / arquivos CI / README para preencher Stack, Comandos, Mapa de Diretórios e Componentes. Pergunte ao usuário apenas o que o código não pode dizer: o que é o produto e para quem, objetivos, não-objetivos, regras de negócio, regras da equipe. Se o usuário veio com uma funcionalidade, mantenha o setup curto (essenciais de PRODUCT + PRINCIPLES) e vá para a funcionalidade; ARCHITECTURE e GLOSSARY podem ser preenchidos incrementalmente depois.

Spec

Preencha spec.md a partir da entrada. Cada AC deve ser Dado/Quando/Então e testável por si só — reescreva requisitos vagos em ACs você mesmo e mostre-os. Cada desconhecido que bloqueia o design se torna um Q [blocking]; desconhecidos menores se tornam Q [non-blocking] com sua resposta sugerida. Apresente um breve resumo (Problema, ACs, Fora de Escopo, Qs abertos) e peça aprovação. Portão: o design só começa quando nenhum Q blocking estiver aberto e o usuário aprovou (ou disse para prosseguir sem perguntar) → defina status: approved.

Design

Leia docs/PRINCIPLES.md e docs/ARCHITECTURE.md, e inspecione os caminhos de código envolvidos. Redija o design.md completo você mesmo; cubra cada AC (diga qual parte cobre qual). Tome as decisões locais você mesmo como entradas D com uma razão; leve ao usuário apenas decisões que são caras de reverter ou questão de preferência, cada uma com sua recomendação. Uma decisão que afeta todo o projeto → proponha um ADR em docs/decisions/. Mostre um breve resumo e peça aprovação. Portão: igual ao spec.

Tasks

Preencha tasks.md a partir de spec + design: pequenos Ts em ordem de dependência, cada um com Cobre (Covers), Arquivos (Files) e um comando Verificar (Verify) real de PRINCIPLES.md → Comandos. Todo AC é coberto por pelo menos um T; todo caso de borda E tem um teste. Nenhum portão de aprovação a menos que o usuário tenha pedido um — mostre a lista de tarefas e vá para Implementar.

Implementar

Um T de cada vez: defina in-progress, implemente, execute seu Verificar, defina done (ou blocked com o motivo). Após cada T, relate em 2–3 linhas e continue para o próximo a menos que algo falhe, um T conflite com PRINCIPLES.md, ou finalizar precise de algo em Fora de Escopo — então pare e pergunte. Mantenha docs/MEMORY.md → Em andamento apontando para o T atual.

Review

Preencha review.md: Relatório de Implementação, cada AC com resultado e evidência, execute os comandos completos de teste/lint/build, aplique a checklist de revisão de PRINCIPLES, liste os achados. Verifique os documentos da funcionalidade contra Estilo de escrita. Registre cada violação como um achado minor. Apresente o veredito. Corrija achados blocker/major se o usuário concordar, então re-revise.

Fechar

Mova lições duradouras para docs/MEMORY.md, atualize Estado Atual (Concluído += esta funcionalidade, Em andamento limpo), adicione a capacidade a PRODUCT.md → Capacidades, crie qualquer ADR de Acompanhamentos. Em seguida, ofereça o próximo item (de Próximo (Next), de Acompanhamentos da revisão, ou "envie-me a próxima tarefa").

Fazendo perguntas

Faça no máximo 3–5 perguntas por turno, mais importantes primeiro. Numeradas, curtas.
Toda pergunta carrega sua resposta sugerida, para que o usuário possa responder "ok" / "1 ok, 2 não" em vez de escrever: 1. Links expirados devem mostrar uma página de erro? → sugestão: sim, com um botão "enviar novamente".
Quando a ferramenta AskUserQuestion estiver disponível e a resposta for uma escolha entre poucas opções, use-a, com a opção recomendada primeiro.
Nunca pergunte o que o código, os documentos ou a entrada já respondem. Nunca pergunte ao usuário qual etapa SDD fazer a seguir — esse é seu trabalho.
Se o usuário disser "decide você" / "tanto faz" / "pode seguir", aceite suas sugestões, registre-as (como Q → answer ou D) e continue.

Bloco-guia

Termine toda resposta com este bloco (no idioma do usuário), para que o usuário nunca precise pensar no que fazer:

---
📍 Funcionalidade: NNN-nome-da-funcionalidade · Etapa: Spec (2/6)   [Setup · Spec · Design · Tasks · Implement · Review]
✅ Feito agora: <uma linha>
❓ Preciso de você: <perguntas numeradas, ou "nada">
➡️ Próximo: <exatamente o que acontece após o usuário responder — ex. "responda 'ok' para aprovar a spec e eu escreverei o design">

Se nada for necessário do usuário, diga isso e diga o que fará a seguir com "continue".

O bloco-guia e as mensagens de chat não precisam da auto-verificação completa de Estilo de escrita. Mantenha-os curtos e diretos.

Regras dos documentos

Substitua todo [placeholder], NNN e YYYY-MM-DD. Uma seção vazia se torna Nenhum. — nunca remova o cabeçalho.
Use IDs (AC, Q, D, T, E, F) para referência cruzada entre documentos em vez de copiar texto.
Leia docs/PRINCIPLES.md antes de design.md e antes de implementar qualquer tarefa.
Se um requisito não estiver claro, adicione um Q e pergunte em vez de adivinhar. Se uma tarefa conflitar com PRINCIPLES.md, pare e pergunte.
Cada fato vive em um documento; outros apontam para ele.

Estilo de escrita (todo documento)

O próximo modelo lê estes documentos e age sobre eles. Escreva de modo que cada frase tenha apenas um significado. Estas regras se aplicam em qualquer idioma. Equivalentes em português estão entre parênteses.

Clareza e Precisão (inspirado em ASD-STE100)

Uma ideia por frase. Use no máximo 20 palavras em uma instrução. Use no máximo 25 palavras em uma descrição.
Uma instrução por frase. Use o imperativo para ações. Escreva "Retorne 404." Não escreva "O sistema provavelmente deve retornar 404."
Voz ativa, presente. Nomeie o ator: o usuário, o sistema, ou um componente pelo seu nome.
Um termo = um significado. Use o termo exato de docs/GLOSSARY.md. Não use sinônimos para o mesmo conceito. Quando usar um novo termo de domínio, adicione-o a GLOSSARY.md.
Palavras-chave de requisito: use apenas deve / não deve / pode (must / must not / may). Não use "deveria", "idealmente", "tentar", "se possível" (should, ideally, try to, if possible).
Quantifique. Substitua cada palavra vaga por um número, uma unidade ou um resultado observável. Não use estas palavras sem um número: rápido, lento, muitos, poucos, grande, robusto, fácil, adequado, alguns, "etc." (fast, slow, many, few, large, robust, easy, proper, some, "etc.").
- Errado: "A página carrega rápido." Correto: "A página carrega em menos de 2 s (p95)."
Sem expressões idiomáticas, metáforas, piadas, palavras de preenchimento ou tom de marketing.
Sem pronomes ambíguos. Se "ele", "isso" ou "este" (it, this, that) puderem se referir a dois substantivos, repita o substantivo.
Estrutura sobre prosa. Prefira listas e tabelas. Um parágrafo tem no máximo 3 frases.
Nomes exatos em código. Escreva identificadores, caminhos, comandos, campos e valores entre crases. Não os parafraseie.

Primeiros Princípios

Parta dos fatos. Hábito e analogia não são razões. "Outros projetos fazem X" não é uma razão.
Rotule cada afirmação que importa:
- Fato — verificado. Dê a fonte: caminho de arquivo, saída de comando, dado ou documento.
- Suposição — não verificado. Escreva como verificá-lo.
- Decisão — uma escolha. Dê a razão, derivada de fatos ou restrições.
Rastreie cada decisão a um problema, um AC ou uma restrição. Se uma decisão não tiver rastro, remova-a.
Necessidade antes da solução. Escreva nesta ordem: problema → restrições → a solução mais simples que as satisfaça.
Opção mais simples primeiro. Escolha a opção mais simples que satisfaça todos os ACs. Cada componente, dependência ou etapa adicionada precisa de uma razão declarada.

Auto-verificação (execute antes de mostrar um documento)

Nenhum [placeholder], NNN ou YYYY-MM-DD permanece.
Nenhuma palavra proibida das regras 5 e 6 permanece.
Cada frase está dentro do limite de palavras da regra 1.
Cada termo de domínio está em docs/GLOSSARY.md.
Cada D e cada Decisão tem uma razão.
Cada afirmação não verificada está rotulada como Suposição e tem um método de verificação.

Referência

Templates em $T = ${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates/:

PRODUCT.md, PRINCIPLES.md, ARCHITECTURE.md, GLOSSARY.md, MEMORY.md, CLAUDE.md — nível de projeto, criados uma vez.
decisions/0000-template.md — um ADR por decisão de todo o projeto.
specs/spec.md, design.md, tasks.md, review.md, research.md — um conjunto por funcionalidade.

slate-sdd

O que é slate-sdd?

Perguntar na sua IA favorita

Documentação