sdd

name

sdd

description

Workflow profissional de desenvolvimento de software em 4 etapas: Spec (descrever produto), Break (quebrar em tasks pequenas), Plan (planejar cada task com research), Execute (implementar cada task). Baseado no workflow da Deborah Folloni para criar aplicações profissionais com Claude Code — o oposto do vibe coding. Use quando Bruno pedir para planejar desenvolvimento, criar spec, quebrar em tasks, planejar implementação, iniciar projeto de código, ou disser "sdd", "spec", "break", "plan", "execute", "planeja esse dev", "quebra em tasks", "planeja antes de codar", "workflow deborah", "anti vibe coding". NAO use para planejamento de conteúdo, marketing, ou tarefas não relacionadas a código.

SDD — Spec-Driven Development

Workflow de desenvolvimento profissional em 4 etapas. Cada etapa preserva a janela de contexto dando tasks pequenas e bem definidas para a IA, ao invés de jogar um projeto inteiro de uma vez.

/spec → /break → /plan (por task) → /execute (por task)

Por que esse processo existe

Sem método, IA gera código com 5 problemas:

1. Engasga em tasks grandes — janela de contexto lota, qualidade despenca
2. Código bagunçado — complica o simples, reinventa a roda, ignora libs existentes
3. Duplica código — esquece que já criou um componente e cria outro igual
4. Não obedece — se você não diz QUAL arquivo mexer, ela adivinha (e erra)
5. Cobertor de pobre — arruma uma coisa, quebra outra (falta modularização)

Cada etapa do SDD é um antídoto para esses problemas.

Detecção de Entrada

A skill opera em 4 comandos. Detectar qual rodar baseado no input:

Input	Comando	Condição
Descrição de produto/app/feature	/spec	Não existe spec.md no projeto
"quebra em tasks" ou spec.md existe	/break	spec.md existe, pasta issues/ não
"planeja" + nome de issue	/plan	Pasta issues/ existe com issue files
"executa" ou "implementa" + nome de issue	/execute	Issue file tem seção de planejamento
/sdd sem contexto	Mostrar status	Verificar quais artefatos existem e sugerir próximo passo

Etapa 1 — /spec (descrever o produto)

Problema que resolve: dar clareza sobre o que construir antes de escrever código.

Input: descrição do que o usuario quer construir. Output: spec.md na raiz do projeto.

Workflow

1. Perguntar (se não informado): "Descreve o que quer construir. Quais são as páginas e o que o usuário faz em cada uma?"
2. Gerar spec.md no seguinte formato:

Formato do spec.md

# Spec — [Nome do Projeto]

[Parágrafo explicando o que é o projeto — visão geral]

## Páginas

### 1. [Nome da Página]

**Componentes:**
- [componente 1] — [o que é]
- [componente 2] — [o que é]
- [componente 3] — [o que é]

**Comportamentos (o que o usuário faz):**
- [behavior 1] — [descrição curta]
- [behavior 2] — [descrição curta]
- [behavior 3] — [descrição curta]

### 2. [Nome da Página]
...

3. Apresentar: "Spec pronta. Revise as páginas, componentes e comportamentos."
4. Aguardar aprovação. Ajustar se necessário.
5. Salvar spec.md na raiz do projeto.

A spec é um documento de PRODUTO, não técnico. Lista o que o usuário vê e faz. Não menciona arquivos, banco de dados, ou implementação.

Etapa 2 — /break (quebrar em tasks)

Problema que resolve: evitar dar tasks grandes demais pra IA, que lotam a janela de contexto.

Input: spec.md Output: pasta issues/ com um arquivo por task.

Workflow

1. Ler spec.md.
2. SE não existe: "Não encontrei spec.md. Quer rodar /spec primeiro?"
3. Criar pasta issues/ na raiz do projeto.
4. Gerar issue files seguindo estas regras:

Regras de quebra:

• Cada página vira uma issue de protótipo (só frontend, não funcional)
• Cada comportamento vira uma issue funcional
• Protótipos vêm ANTES das issues funcionais na numeração
• Issues são numeradas sequencialmente: 001-, 002-, etc.

Formato dos issue files:

# [Título da task]

[2-3 linhas descrevendo o que essa task faz]

Exemplo de estrutura gerada:

issues/
├── 001-prototype-page-login.md
├── 002-prototype-page-chat.md
├── 003-prototype-page-settings.md
├── 004-behavior-login-with-email.md
├── 005-behavior-recover-password.md
├── 006-behavior-send-message.md
├── 007-behavior-stream-ai-response.md
├── 008-behavior-stop-streaming.md
└── ...

5. SE não existe architecture.md na raiz do projeto, gerar junto:

Formato do architecture.md

# Architecture — [Nome do Projeto]

## Organização por Comportamento

Cada página tem uma pasta. Dentro dela, cada comportamento fica isolado:

src/app/ ├── [page-name]/ │ ├── components/ ← componentes visuais da página │ ├── behaviors/ │ │ ├── [behavior-1]/ ← pasta isolada por comportamento │ │ │ ├── action.ts ← server action (lógica no backend) │ │ │ └── schema.ts ← validação de input │ │ └── [behavior-2]/ │ └── page.tsx ← página principal

**Por que:** isolamento garante que mexer em um comportamento não quebra outro.

## Regras de Segurança

### Thin Client, Fat Server
- Frontend APENAS captura intenções do usuário (cliques, inputs) e renderiza respostas
- TODA lógica de negócio fica no backend (server actions, API routes)
- NUNCA colocar chaves, tokens ou secrets no frontend
- NUNCA colocar regras de acesso/permissão no frontend

**Por que:** tudo no frontend é acessível com 2 cliques no navegador.

## Convenções
- Nomes de pasta: kebab-case
- Componentes: PascalCase
- Funções/variáveis: camelCase
- Validação: Zod schemas
- Banco: [preencher após primeiro /plan que envolva banco]

6. Apresentar lista das issues geradas: "Quebrei a spec em [N] tasks. [X] protótipos + [Y] comportamentos. Gerei architecture.md com regras de organização e segurança."
7. Aguardar aprovação. Ajustar ordem, granularidade ou architecture se necessário.

Issue files começam simples — só título e descrição curta. O detalhamento vem na etapa de planning.

Etapa 3 — /plan (planejar cada task)

Problemas que resolve:

• Código duplicado → pesquisa codebase pra reutilizar o que já existe
• Reinventa a roda → pesquisa docs externas pra padrões comprovados
• IA não obedece → lista EXATAMENTE quais arquivos criar/modificar

Input: path de 1 issue file (ex: issues/004-behavior-login-with-email.md) Output: issue file expandido com planejamento completo.

Workflow

1. Ler o issue file indicado.

2. Rodar research em DUAS direções:

   Research interno (subagent Explore no codebase):

   Buscar no codebase em [path]:
   - Componentes, funções ou módulos que podem ser IMPORTADOS e reutilizados
     para implementar "[título da task]"
   - Padrões de implementação que o projeto já usa para problemas similares
   Listar: arquivo, o que faz, como reutilizar.
   NAO sugerir melhorias. Apenas listar o que existe e pode ser reaproveitado.
   

   Research externo (WebFetch/WebSearch) — APENAS se a task envolve lib/API que o Claude pode não conhecer bem:

   Buscar documentação oficial e padrões de implementação comprovados
   para [tecnologia]. Condensar em máximo 15 linhas.
   

3. Com base no research, expandir o issue file com planejamento:

Formato do issue file planejado

# [Título da task]

## Descrição
[O que esse comportamento/página faz]

## Cenários
**Happy path:** [o que acontece quando tudo dá certo]
**Edge cases:** [cenários improváveis mas possíveis]
**Erros:** [o que acontece quando algo falha]

## Banco de Dados
[SE necessário — tabelas a criar/modificar, colunas, tipos]
[SE não precisa de banco: omitir seção]

## Arquivos

### Criar:
| Arquivo | O que fazer |
|---------|-------------|
| `path/to/new-file.ts` | [descrição específica do que criar] |

### Modificar:
| Arquivo | O que fazer |
|---------|-------------|
| `path/to/existing.ts` | [descrição específica do que modificar] |

## Código Reutilizável
[Componentes/funções que JÁ EXISTEM no projeto e devem ser IMPORTADOS, não recriados]
| Arquivo existente | O que importar | Por que |
|-------------------|----------------|---------|
| `path/to/button.tsx` | `<Button>` | Já tem o estilo correto |

## Dependências Externas
[SE necessário — libs a instalar + trecho relevante da doc]
[SE não precisa: omitir seção]

## Checklist
- [ ] [tarefa 1]
- [ ] [tarefa 2]
- [ ] [tarefa 3]
...

4. Apresentar: "Task planejada. [N] arquivos a criar, [M] a modificar, [K] componentes a reutilizar."
5. Aguardar aprovação.

O planejamento garante que a IA só vai mexer nos arquivos que você mandou. Se não tá na lista, ela não mexe.

Etapa 4 — /execute (implementar cada task)

Problema que resolve: execução limpa, seguindo o plano, sem inventar.

Input: path de 1 issue file já planejado. Output: código implementado conforme o plano.

Workflow

1. Ler o issue file planejado.
2. SE não tem seção "Arquivos": "Essa issue não foi planejada ainda. Quer rodar /plan primeiro?"
3. Apresentar resumo: "Vou implementar: [N] arquivos a criar, [M] a modificar. Confirma?"
4. Aguardar confirmação.
5. Implementar seguindo EXATAMENTE o plano:
   • Criar arquivos listados em "Criar"
   • Modificar arquivos listados em "Modificar"
   • IMPORTAR componentes listados em "Código Reutilizável" — NAO recriar
   • Seguir architecture.md se existir no projeto (organização, regras de segurança)
   • Seguir docs em references/ se existirem (design system, patterns)
6. Marcar checkboxes no issue file conforme vai concluindo.
7. SE algo do plano não bate com a realidade (arquivo não existe, API mudou):
   • PARAR
   • Reportar: "Divergência: plano diz [X], mas encontrei [Y]. Como prosseguir?"
8. Após concluir, apresentar: "Task implementada. [N/N] itens do checklist concluídos."

Regras de implementação

• Thin client, fat server: lógica de negócio SEMPRE no backend. Frontend só captura intenções do usuário e renderiza respostas. NUNCA colocar chaves, regras de acesso ou lógica no frontend.
• Isolamento por comportamento: cada comportamento fica na sua pasta/módulo. Mexer em um não pode quebrar outro.
• Importar, não recriar: se o componente já existe, importar. Não criar botão 2 quando botão 1 já existe.
• Só mexer no que foi planejado: se o arquivo não está na lista do plano, não tocar.

Docs de Apoio

Arquivo	Gerado em	Função
architecture.md	/break (automático)	Organização por comportamento, regras de segurança, thin client/fat server, convenções
references/design-system.md	Manual (opcional)	Componentes visuais, cores, tipografia, espaçamento
references/	Manual (opcional)	Qualquer doc de apoio do projeto

O architecture.md é gerado automaticamente no /break se não existir. Ele é lido no /execute para garantir que o código siga a organização e regras do projeto. Se o usuario já tem um architecture.md, respeitar o existente — não sobrescrever.

Status — /sdd sem argumentos

Quando o usuario rodar /sdd sem contexto, verificar o estado do projeto:

SE não existe spec.md → "Nenhuma spec encontrada. Quer rodar /spec?"
SE spec.md existe mas não issues/ → "Spec existe. Quer rodar /break?"
SE issues/ existe → Listar issues e status:
   - Sem planejamento (só descrição curta)
   - Planejada (tem seção Arquivos)
   - Implementada (todos checkboxes marcados)
   Sugerir próxima ação: "/plan [próxima não planejada]" ou "/execute [próxima planejada]"

Edge Cases

• Se o projeto é muito simples (1 página, 2 behaviors): ainda seguir o processo — vale o hábito
• Se o usuario quiser pular etapas ("só implementa"): avisar "Sem plano, a IA vai adivinhar quais arquivos mexer. Risco de bagunça. Quer continuar?"
• Se um behavior depende de outro (ex: "stream response" depende de "send message"): manter na ordem correta de implementação
• Se o codebase já tem código: o /plan vai mapear o que reutilizar — não começar do zero
• Se o usuario quiser replanejar uma issue: sobrescrever o planejamento existente
• Se durante /execute a janela de contexto ficar pesada: salvar progresso nos checkboxes e sugerir continuar em nova sessão

Examples

Exemplo 1 — /spec para app de chat IA

Input: "Quero criar um chat de IA onde o usuário pode conversar com vários modelos"

Output (spec.md):

# Spec — AI Chat

Aplicação de chat que permite ao usuário conversar com múltiplos modelos
de IA de diferentes providers (OpenAI, Anthropic, etc.).

## Páginas

### 1. Chat

**Componentes:**
- Thread de mensagens — lista de mensagens do usuário e da IA
- Input de mensagem — campo de texto com botão enviar
- Seletor de modelo — dropdown para escolher o modelo
- Botão stop — para interromper o streaming

**Comportamentos:**
- Enviar mensagem — usuário digita e envia texto para o modelo
- Stream de resposta — resposta da IA aparece em tempo real
- Parar streaming — usuário interrompe a resposta no meio
- Trocar modelo — usuário seleciona outro modelo no dropdown
- Novo chat — usuário inicia uma conversa nova

### 2. Login

**Componentes:**
- Form de login — campos email e senha
- Link de recuperação — link para recuperar senha
- Botão de signup — redireciona para cadastro

**Comportamentos:**
- Login com email — usuário faz login com email e senha
- Recuperar senha — usuário solicita reset de senha

Exemplo 2 — /break gera issues

Output:

Quebrei a spec em 9 tasks:

Protótipos (UI):
  001-prototype-page-chat.md
  002-prototype-page-login.md

Comportamentos:
  003-behavior-send-message.md
  004-behavior-stream-ai-response.md
  005-behavior-stop-streaming.md
  006-behavior-switch-model.md
  007-behavior-new-chat.md
  008-behavior-login-with-email.md
  009-behavior-recover-password.md

2 protótipos + 7 comportamentos. Aprovar?

Exemplo 3 — /plan de uma task

Input: /plan issues/003-behavior-send-message.md

Output (issue file expandido):

# Enviar mensagem

## Descrição
Usuário digita mensagem no input e envia para o modelo de IA selecionado.

## Cenários
**Happy path:** Usuário digita, clica enviar, mensagem aparece no thread,
resposta da IA começa a streamar.
**Edge cases:** Mensagem vazia (bloquear envio), conexão lenta (loading state).
**Erros:** API retorna erro 429 (rate limit) → mostrar mensagem amigável.

## Banco de Dados
| Tabela | Coluna | Tipo | Descrição |
|--------|--------|------|-----------|
| messages | id | uuid | PK |
| messages | chat_id | uuid | FK para chats |
| messages | role | enum | 'user' ou 'assistant' |
| messages | content | text | Conteúdo da mensagem |
| messages | model | varchar | Modelo usado |
| messages | created_at | timestamp | Data de criação |

## Arquivos

### Criar:
| Arquivo | O que fazer |
|---------|-------------|
| `src/app/chat/behaviors/send-message/action.ts` | Server action que recebe mensagem e chama API do modelo |
| `src/app/chat/behaviors/send-message/schema.ts` | Validação do input com Zod |

### Modificar:
| Arquivo | O que fazer |
|---------|-------------|
| `src/app/chat/components/message-input.tsx` | Adicionar onSubmit que chama a server action |
| `src/app/chat/components/thread.tsx` | Renderizar nova mensagem na lista |

## Código Reutilizável
| Arquivo existente | O que importar | Por que |
|-------------------|----------------|---------|
| `src/components/ui/button.tsx` | `<Button>` | Botão de enviar — já estilizado |
| `src/lib/db.ts` | `db` | Conexão com banco já configurada |

## Dependências Externas
- `ai` (Vercel AI SDK) — já instalada, usar `streamText()` para streaming

## Checklist
- [ ] Criar schema de validação
- [ ] Criar server action
- [ ] Modificar message-input com onSubmit
- [ ] Modificar thread para renderizar mensagem nova
- [ ] Importar Button existente (não recriar)
- [ ] Testar happy path
- [ ] Testar edge case (mensagem vazia)
- [ ] Testar erro (rate limit)

Exemplo 4 — /sdd mostrando status

Output:

Status do projeto:

spec.md ✓
issues/ (9 tasks):
  ✅ 001-prototype-page-chat — implementada
  ✅ 002-prototype-page-login — implementada
  📋 003-behavior-send-message — planejada
  📄 004-behavior-stream-ai-response — sem planejamento
  📄 005-behavior-stop-streaming — sem planejamento
  ...

Próximo passo: /execute issues/003-behavior-send-message.md