O manual definitivo para implantar SDD (Specification-Driven Development) em projetos reais usando SpecifyX, Cursor, Claude Code e qualquer agente de IA.
- Por que este guia existe
- O que é SpecifyX
- O Ciclo de 6 Fases
- Conteúdo deste Repositório
- Por onde começar
- Organização de Contexto Recomendada
- Compatibilidade por IDE/Ambiente
- Sobre o Autor
- Licença
Times que trabalham com agentes de IA em produção — Cursor, Claude Code, Gemini CLI — enfrentam o mesmo problema: codificar direto gera fragmentação arquitetural, alucinação de contexto e débito técnico precoce.
A IA não tem culpa. Ela só está fazendo exatamente o que foi pedida: codar sem especificação clara. O problema não é o modelo — é o processo.
O SpecifyX resolve isso isolando o desenvolvimento em fases auditáveis, onde a IA atua restrita por uma especificação executável, não por uma instrução vaga de chat.
Este repositório documenta, de forma prática e testada em projeto real, como implantar esse fluxo do zero até produção.
SpecifyX é um kit de ferramentas open source de governança de código que inverte a lógica tradicional Code-First. Construído a partir do spec-kit original, adiciona parametrização dinâmica via templates Jinja2 e configuração unificada em TOML.
A filosofia central, em uma frase: spec vem antes de código, e toda decisão é rastreável.
| Princípio | O que significa na prática |
|---|---|
| Spec antes de código | Você escreve bem o que quer ANTES de implementar |
| Tudo é rastreável | Cada feature tem spec, plan e tasks documentados em arquivo |
| LLMs entendem contexto | Documentação estruturada = menos alucinação, mais precisão |
| Decisões são documentadas | Não é "acho que era assim" — é "aqui está o porquê, por escrito" |
[1. SPECIFY] ──> [2. CLARIFY] ──> [3. PLAN] ──> [4. TASKS] ──> [5. ANALYZE] ──> [6. IMPLEMENT]
| Fase | Comando | O que produz |
|---|---|---|
| Specify | /specify |
spec.md — escopo, requisitos, cenários de usuário, livre de decisão técnica prematura |
| Clarify | /clarify |
Perguntas críticas que eliminam ambiguidade antes de tocar em código |
| Plan | /plan |
plan.md — arquitetura técnica: stack, schema, rotas, contratos de API |
| Tasks | /tasks |
tasks.md — tarefas atômicas, ordenadas por dependência, com critério de aceite |
| Analyze | /analyze |
Auditoria reversa — valida tasks e plan contra a spec original, zero desvio de escopo |
| Implement | /implement |
Execução incremental, tarefa por tarefa, com contexto reduzido por etapa |
💡 O ganho real não é "ter um processo bonito" — é reduzir drasticamente o contexto que a IA precisa processar de uma vez, o que reduz alucinação e mantém o código alinhado à arquitetura existente.
| Arquivo | Para que serve |
|---|---|
INSTALLATION.md |
Instalação completa do uv e do SpecifyX, passo a passo |
USAGE.md |
Guia de uso detalhado — os 6 comandos, exemplos reais, organização de contexto, boas práticas |
QUICKSTART.md |
Instalação + primeiro uso em um único arquivo, para quem quer ir direto ao ponto |
README.md |
Este arquivo — visão geral e ponto de entrada |
Nunca usou SpecifyX?
→ Comece em QUICKSTART.md (instalação + primeira feature em <15 min)
Quer entender a fundo antes de instalar?
→ Leia este README até o fim, depois INSTALLATION.md
Já instalou e quer dominar o fluxo completo?
→ USAGE.md tem o ciclo completo, organização de contexto e boas práticas
SpecifyX gera a pasta specs/ automaticamente — mas a documentação manual do projeto (contexto vivo para a IA) merece sua própria estrutura:
seu-projeto/
├── .context/ ← Documentação manual de contexto vivo
│ ├── onboarding/ (AI_CONTEXT.md — visão rápida para LLMs)
│ ├── spec/ (specs técnicas de referência)
│ ├── adr/ (Architecture Decision Records)
│ └── docs/ (setup de ferramentas, infra)
├── specs/ ← Output automático do SpecifyX (não editar manualmente)
│ └── 001-nome-da-feature/
│ ├── spec.md
│ ├── plan.md
│ └── tasks.md
├── .specify/ ← Configuração interna do SpecifyX
└── CONSTITUTION.md ← Lei máxima do repositório
Detalhamento completo de cada pasta, regras de onde cada tipo de arquivo deve viver, e a diferença entre
.context/(manual) especs/(automático) está emUSAGE.md.
| Ambiente | Compatibilidade | Observação |
|---|---|---|
| Cursor (Chat integrado) | ✅ 100% | Melhor UX — spec abre automaticamente ao lado do código |
| VS Code + Claude Code CLI | ✅ 100% | Via terminal integrado, claude /specify |
| Terminal puro (Claude Code CLI) | ✅ 100% | Ideal para automação via scripts shell |
| Claude Desktop | ✅ Funciona | Menos integrado — requer carregar contexto manualmente |
| Cowork (modo colaborativo) | ✅ 100% | Melhor para pair programming estruturado e sessões longas |
| GPT Codex / OpenAI | ❌ Não nativo | Specify é do ecossistema Claude/Anthropic — spec precisa ser escrita manualmente |
|
Bruno Goulart — AI Automation Specialist & Full Stack Developer Uno a robustez de 18+ anos de código escrito na raça e forjado no braço à inteligência de LLMs, ferramentas hype de automação, DevOps e arquitetura full-stack — do MVP ao deploy em produção. Projeto e entrego soluções escaláveis, seguras e inovadoras: integro LLMs em produtos existentes e construo do zero arquiteturas orientadas a agentes autônomos. Especialista em SDD (Specification-Driven Development), AI Agents (LangChain, LangGraph, MCP), automação n8n e infraestrutura DevOps (Docker, Portainer, GitLab/GitHub CI). |
MIT — use, adapte e distribua livremente, mantendo os créditos de autoria.
Documentação viva — mantida e atualizada conforme o ecossistema SpecifyX evolui.
Última atualização: Junho 2026