Pular para o conteúdo
UseIA
0
Skill

Spec-Driven Development

Crédito: FredAntB no GitHub (FredAntB/Spec-Driven-Development) · 0 cópias

Indicada na UseIA por Cristiano Rochenbach Abreu em 5 de out. de 2026

152 estrelas no GitHubVer no GitHub
Salvar

Tradução feita por IA. Em caso de dúvida, vale o texto original (aba “Original”).

---
name: spec-driven-development
version: 1.0.0
description: >
  Use esta skill para montar a estrutura do Spec Driven Development: requirements.md, design.md, tasks.md e arquivos de configuração de IA compatíveis entre ferramentas (CLAUDE.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md). Gatilhos: 'requirements', 'spec', 'design doc', 'tasks', 'CLAUDE.md', 'cursorrules', 'SDD', 'spec driven', 'AI configuration', 'cross-AI', 'multi-agent', 'agent setup'. Acione também para: 'set up my AI tools', 'keep agents consistent', 'stop AI going off-script', 'plan before coding', 'structure project for AI'. Gatilhos de adaptação de projeto existente: 'document my system', 'document my codebase', 'describe my architecture', 'write up what we built', 'add specs to existing project', 'no specs yet', 'help me document', 'I already have a codebase'. Use sempre que um usuário quiser iniciar um projeto, configurar agentes de código, criar documentos de especificação ou impedir que agentes de IA se desviem, inventem escopo ou produzam implementações inconsistentes.
---

# Skill de Spec Driven Development

Esta skill guia o usuário na criação de um ambiente completo de Spec Driven Development:
- `requirements.md` — o que o sistema deve fazer
- `design.md` — como ele será construído
- `tasks.md` — etapas de implementação atômicas e ordenadas
- Arquivos de configuração de agentes de IA para Claude Code, Cursor, Windsurf, GitHub Copilot e Aider

**Arquivos de referência** (leia quando necessário):
- `references/sdd-curriculum.md` — currículo completo de ensino, do iniciante ao avançado
- `references/capabilities-and-cross-ai.md` — capacidades e limitações do Claude Code, estratégia entre IAs
- `references/templates.md` — todos os modelos de arquivos de especificação e de configuração de IA

---

## Quando ler os arquivos de referência

| Situação | Leia |
|---|---|
| O usuário é novo em SDD e precisa de explicação | `sdd-curriculum.md` Níveis 1–3 |
| O usuário pergunta sobre detalhes de Claude Code + SDD | `capabilities-and-cross-ai.md` Parte 1 |
| O usuário quer arquivos de configuração para várias IAs | `capabilities-and-cross-ai.md` Partes 2–3 |
| Você precisa do conteúdo dos modelos para gerar arquivos | `templates.md` |

---

## Fluxo: primeira execução (projeto novo)

### Passo 1: Entreviste o usuário

**Regra de conversa (inegociável):** Faça exatamente UMA pergunta, espere a resposta e só então faça a próxima. Nunca apresente perguntas em lista numerada ou com marcadores — isso parece um formulário, não uma conversa. Um iniciante que vê três itens pode responder só o primeiro ou se sentir sobrecarregado.

**As quatro respostas obrigatórias antes de gerar qualquer arquivo:**
1. O que o projeto faz e quem o usa
2a. Stack tecnológica (linguagem, framework, banco de dados)
2b. Destino do deploy (Railway, Fly.io, AWS, Vercel etc. — ofereça sugestões se não souber)
3. Quais ferramentas de código com IA ele usa (Claude Code, Cursor, Windsurf, Copilot, Aider, outra)

Stack e deploy são respostas obrigatórias separadas, porque uma não implica a outra. "Node.js" não diz nada sobre o deploy. "Railway" não diz nada sobre a linguagem. Ambas precisam ser conhecidas de forma independente antes de a geração prosseguir.

**Se a mensagem inicial do usuário já responde algumas dessas perguntas, mas não todas**, reconheça o que você já sabe e pergunte só o que falta — ainda assim, uma pergunta por vez.

**Perguntas complementares opcionais** (faça apenas quando a resposta do usuário gerar ambiguidade real):
- "Existem restrições de desempenho, segurança ou acessibilidade?"
- "O que está explicitamente fora do escopo desta primeira versão?"

Exemplo de ritmo correto:
> Usuário: "Quero começar um projeto novo"
> Claude: "Com prazer, vamos especificar. O que o projeto faz — quem são os usuários e qual é a tarefa principal que ele executa?"
> Usuário: "É um gerenciador de tarefas para pequenas equipes de desenvolvimento"
> Claude: "Entendi. Qual é a sua stack — linguagem, framework, banco de dados?"
> Usuário: "Node.js, Express, PostgreSQL"
> Claude: "E onde você pretende fazer o deploy? (Railway, Fly.io, AWS — ou posso sugerir um)"
> Usuário: "Railway"
> Claude: "Última coisa — quais ferramentas de código com IA você usa? (Claude Code, Cursor, Copilot, Windsurf, outra?)"

Exemplo de tratamento de resposta parcial:
> Usuário: "Estou construindo uma API de gerenciamento de tarefas em Node.js"
> Claude: "Bom começo — Node.js anotado. Qual banco de dados você pretende usar?"
> Usuário: "PostgreSQL"
> Claude: "E onde você fará o deploy? (Railway, Fly.io, AWS — ou posso sugerir um)"
> Usuário: "Railway"
> Claude: "Última coisa — quais ferramentas de código com IA você usa?"
> *(stack informada parcialmente — peça cada parte que falta, uma por vez, nunca as junte)*

### Portão de geração (aplicado entre o Passo 1 e o Passo 2)

**REGRA RÍGIDA: Nenhum arquivo de nenhum tipo pode ser gerado até que as quatro respostas da entrevista estejam em mãos.**

Este portão vale para todos os caminhos de saída — `requirements.md`, `design.md`, `tasks.md`, `.cursorrules`, `CLAUDE.md` e todos os outros arquivos de configuração. Não há exceções, inclusive quando:
- O usuário diz "crie os requisitos para X" (X é uma categoria de produto, não uma descrição completa)
- O usuário diz "faça um arquivo cursorrules" (o nome de um entregável concreto não é permissão para pular a entrevista)
- O usuário diz "configure o Cursor e o Claude Code" (nomear ferramentas não é o mesmo que fornecer o contexto do projeto)
- O usuário dá uma resposta parcial de stack, como "Node.js" (stack ≠ deploy — ambos são obrigatórios separadamente)
- O usuário fornece algumas, mas não todas, das quatro respostas obrigatórias (peça o restante, uma por vez)

Se faltar qualquer resposta, peça-a de forma conversacional antes de prosseguir. Não gere arquivos de rascunho com tokens `{{UNFILLED}}`. Não gere requisitos falsos de aparência plausível a partir de uma categoria de produto apenas.

**Checagem do portão antes de gerar qualquer arquivo:**
```
□ Sei o que o projeto faz e quem o usa?                → se não, pergunte primeiro
□ Sei a stack (linguagem/framework/banco)?             → se não, pergunte primeiro
□ Sei o destino do deploy?                             → se não, pergunte primeiro
□ Sei quais ferramentas de IA o usuário usa?           → se não, pergunte primeiro
Somente com os quatro ✓ → siga para o Passo 2
```

---

### Passo 2: Gere o `requirements.md`

Leia `references/templates.md` para obter o modelo. Preencha todos os `{{PLACEHOLDERS}}`.

**Regras de qualidade do requirements.md:**
- Todo requisito funcional usa a linguagem "shall" (REQ-xxx: Ator shall verbo objeto)
- Todo requisito tem um critério de aceitação concreto
- Os requisitos não funcionais (NFRs) têm uma métrica mensurável (não "rápido" — use "< 200 ms no p95")
- A seção "fora do escopo" não pode estar vazia (se o usuário não informou, deduza as suposições prováveis)
- Os IDs dos requisitos são sequenciais, começando em REQ-001

**Saída:** Crie `requirements.md` na raiz do projeto (ou pergunte o caminho se houver ambiguidade).

---

### Passo 3: Gere o `design.md`

Leia `references/templates.md` para obter o modelo.

**Regras de qualidade do design.md:**
- Todo REQ-xxx deve corresponder a pelo menos um campo do modelo de dados, endpoint ou componente
- Os campos do modelo de dados têm tipos e restrições explícitos (não apenas "string" — use VARCHAR(255) ou TEXT, com justificativa)
- Os endpoints de API referenciam o REQ que atendem
- A seção de estrutura de arquivos mostra, no mínimo, os dois primeiros níveis da árvore do projeto
- A seção de Questões em Aberto registra tudo o que o usuário ainda não decidiu — não adivinhe, pergunte

**Saída:** Crie `design.md` na raiz do projeto.

---

### Passo 4: Gere o `tasks.md`

Leia `references/templates.md` para obter o modelo.

**Regras de qualidade do tasks.md:**
- As tarefas seguem a ordem: infraestrutura → camada de dados → lógica de negócio → camada de API → testes → validação
- Toda tarefa referencia pelo menos um REQ ou NFR **inline, na linha da caixa de seleção**, usando o formato `**TASK-{{id}}** [REQ-xxx, NFR-xxx]` — não apenas em uma linha separada `_Refs_:`. Isso torna as referências verificáveis por máquina, por ferramentas estáticas e scripts de CI.
- Toda tarefa tem uma etapa de verificação explícita (um comando de teste, uma checagem manual, uma medição de métrica)
- As tarefas são atômicas — uma tarefa não deve produzir mais de ~200 linhas de código novo
- Os objetivos das fases são descritos em linguagem simples

**Saída:** Crie `tasks.md` na raiz do projeto.

---

### Passo 5: Gere os arquivos de configuração dos agentes de IA

Pergunte ao usuário quais agentes ele usa (se isso ainda não foi respondido na entrevista).

Para cada agente selecionado, gere o arquivo de configuração adequado. Leia `references/capabilities-and-cross-ai.md` Parte 2 para os modelos por agente.

**Sempre gere:**
- `CLAUDE.md` (para o Claude Code) — mesmo que o usuário não peça, esta é a base

**Gere conforme as ferramentas do usuário:**
| Ferramenta | Arquivo | Local |
|---|---|---|
| Cursor | `.cursorrules` | Raiz do projeto |
| Windsurf | `.windsurfrules` | Raiz do projeto |
| GitHub Copilot | `.github/copilot-instructions.md` | Diretório `.github/` |
| Aider | `.aider.conf.yml` | Raiz do projeto |

**Regras de qualidade dos arquivos de configuração de IA:**
- O Bloco Universal de Instruções é IDÊNTICO em conteúdo em todos os arquivos (mesmas restrições, mesmo protocolo) — só as adições específicas de cada agente diferem
- O bloco referencia os nomes reais dos arquivos de especificação (`requirements.md`, `design.md`, `tasks.md`)
- As adições específicas de cada agente são mínimas — no máximo 5 linhas de regras específicas do agente
- Os arquivos de configuração incluem o nome do projeto e a versão da especificação no cabeçalho

**Saída:** Crie todos os arquivos de configuração solicitados nos locais corretos.

---

## Fluxo: projeto existente (adaptação)

Acionado por: "já tenho uma base de código, ainda sem especificações", "documente o que meu sistema faz", "descreva minha arquitetura", "me ajude a documentar", "escreva o que construímos", "adicione especificações ao meu projeto" ou qualquer frase parecida que indique um sistema existente sem especificações escritas.

### Entrevista de adaptação (faça uma pergunta por vez, de forma conversacional)

A entrevista de adaptação é diferente da de um projeto novo — você está descobrindo a verdade a partir do código existente, não projetando do zero. Faça estas perguntas em ordem:

1. "O que o sistema faz hoje — descreva como se estivesse explicando para um novo colega de equipe?"
2. "Qual é a stack? (linguagem, framework, banco de dados, deploy)"
3. "Quais ferramentas de IA você usa neste projeto?"
4. "Há partes da base de código que você gostaria de compartilhar para que eu leia a estrutura real? (arquivos principais, árvore de pastas ou um README)"
5. "Qual é a próxima funcionalidade ou fa

[…] Conteúdo completo no GitHub.