1. O QUE É SDD

Spec-Driven Development (SDD) é escrever especificações estruturadas antes do código, usando-as como fonte de verdade para agentes de IA. Surgiu em 2025 como resposta ao vibe coding — onde devs descrevem o que querem e a IA gera código sem planejamento.

O que é uma “Spec”?

A palavra spec vem de specification (especificação). Uma spec no SDD é:

• Estruturada — formato consistente (user stories, critérios de aceite, decisões de design), não texto livre
• Orientada a comportamento — descreve o que o software deve fazer, não como (similar ao GIVEN/WHEN/THEN do BDD)
• Em linguagem natural — não UML nem DSL, é markdown legível
• Guia para agentes — clara o suficiente para a IA implementar sem “adivinhar”
• Versionável — vive no repositório em arquivos como requirements.md, design.md, tasks.md

A diferença que importa: um prompt vive no chat e morre ali. Uma spec vive no repositório e é a fonte de verdade.

O termo já está sofrendo difusão semântica — tem gente usando “spec” como sinônimo de “prompt detalhado”. Não é a mesma coisa.

Os 3 Níveis de SDD

SDD não é uma coisa só. Existem 3 níveis, e cada um muda a relação entre spec e código:

Nível 1 — Spec-First

É o nível mais simples e o mais prático pra começar. A ideia é: antes de sair codando, você escreve uma spec com requirements, design e tasks. O agente usa essa spec pra implementar. Depois que a feature está pronta e mergeada, a spec pode ser descartada ou arquivada.

Na próxima feature, você cria uma spec nova do zero. Cada spec tem o ciclo de vida da tarefa, não da feature.

Quando funciona bem: para features pontuais, refators, e qualquer tarefa onde o planejamento prévio evita retrabalho. É onde a maioria dos times começa e já traz ganho real.

Limitação: se daqui a 3 meses alguém precisar entender a feature e a spec foi descartada, volta a depender de ler código. A documentação não sobrevive.

Nível 2 — Spec-Anchored

Aqui a spec não é descartada. Ela é mantida no repositório como um documento vivo que acompanha o ciclo de vida da feature. Quando alguém precisa evoluir ou dar manutenção naquela feature, consulta e atualiza a spec.

O fluxo muda: em vez de criar spec nova pra cada tarefa, você edita a spec existente da feature e adiciona o que mudou. A spec vira um histórico de decisões — por que fizemos assim, quais trade-offs foram escolhidos, o que mudou desde a versão original.

Quando funciona bem: para features que vão evoluir ao longo de meses. Para times onde rotatividade é alta e conhecimento precisa sobreviver à saída de quem implementou. Para projetos onde “por que foi feito assim?” é uma pergunta frequente.

Limitação: exige disciplina do time pra manter a spec atualizada. Se ninguém atualiza, vira documentação morta — e documentação morta é pior do que não ter documentação, porque engana.

Nível 3 — Spec-as-Source

É o nível mais radical. A spec vira o único arquivo que humanos editam. O código é gerado automaticamente a partir da spec e pode até ter um comentário no topo tipo // GENERATED FROM SPEC - DO NOT EDIT. Quando precisa mudar algo, você muda na spec e regenera o código.

Pense como SQL: você descreve o resultado que quer, o sistema se vira pra executar. Ou como um Terraform: você declara o estado desejado, a ferramenta aplica.

Onde isso está hoje: só a Tessl está explorando esse nível, e ainda em beta. É o futuro, mas tem desafios sérios — o principal é o não-determinismo dos LLMs. A mesma spec pode gerar código diferente em execuções distintas. Além disso, escrever specs suficientemente precisas pra gerar código consistente é muito difícil.

Pra nós hoje: não é prático. Mas é bom saber que existe pra entender pra onde o mercado está indo.

Resumo dos 3 níveis

O caminho natural: começar com Spec-First (já traz ganho), evoluir pra Spec-Anchored nas features mais importantes (specs que vale a pena manter), e acompanhar o Spec-as-Source conforme as ferramentas amadurecem.

O que vai dentro: System Design

A spec inclui a parte de arquitetura e decisões técnicas: componentes, data model, fluxo de dados, contratos de API, restrições e trade-offs.

Exemplo:

# Design — NCM Attributes Response System

## Componentes
- NcmAttribute (Model) → belongs_to :ncm
- AttributeResponse (Model) → belongs_to :ncm_attribute, belongs_to :product
- Product (Model) → belongs_to :project, has_many :attribute_responses
- Project (Model) → has_many :project_ncms; has_many :ncms, through: :project_ncms

## Data Model
ncm_attributes:
  - id, ncm_id (FK), name, field_type (enum), required, options (jsonb), position

attribute_responses:
  - id, ncm_attribute_id (FK), product_id (FK), value, status (enum)
  - unique index: [ncm_attribute_id, product_id]

## Fluxo
1. Projeto criado com 1+ NCMs → 2. Produto adicionado →
3. Sistema carrega atributos → 4. Usuário preenche respostas →
5. Validação de completude

## Trade-offs
- jsonb para options de select → flexibilidade, validação no Service
- text genérico para value → simplifica schema, casting no Service
- project_ncms como tabela (não HABTM) → permite metadados futuros

2. OS BUILDING BLOCKS DO CLAUDE CODE

CLAUDE.md — Arquivo na raiz do projeto com regras que valem SEMPRE. Claude lê ele em toda sessão. Pense como a “memória” do projeto. Manter abaixo de 200 linhas.

Skills — Pastas com um SKILL.md que Claude carrega automaticamente quando a tarefa combina com a description. Diferente do CLAUDE.md (sempre ativo), Skills só entram no contexto quando necessário. São probabilísticas — Claude decide se usa.

Subagents — Instâncias separadas de Claude com contexto isolado. Ideais para delegar tarefas pesadas sem poluir o contexto principal. Cada um faz seu trabalho e retorna o resultado.

Hooks — Scripts que executam em eventos específicos (salvar arquivo, fim de sessão). São determinísticos — executam 100% das vezes, sem exceção. Use para regras invioláveis.

Slash Commands — Atalhos que você dispara manualmente (/spec-new). Bom para workflows que repete todo dia.

Plugins — Empacota Skills + Subagents + Commands + Hooks num pacote distribuível pro time.

A distinção mais importante:

Progressive Disclosure — por que Skills são eficientes

Skills carregam em 3 níveis:

1. Startup (~100 tokens): só name e description de todas as Skills
2. Match (<5k tokens): SKILL.md completo quando a tarefa combina
3. On-demand: arquivos auxiliares só quando necessário

Resultado: dezenas de Skills instaladas sem custo de contexto. Claude só carrega o que precisa.

3. O SETUP SDD

3.1 Skill SDD — O Workflow Reutilizável

Essa é a peça central. Quando alguém disser “spec”, “requirements” ou “plan before coding”, Claude ativa essa Skill automaticamente.

.claude/skills/sdd-workflow/
├── SKILL.md                        # Instruções principais (<500 linhas)
├── templates/
│   ├── requirements-template.md    # Lido só na fase 1
│   ├── design-template.md          # Lido só na fase 2
│   └── tasks-template.md           # Lido só na fase 3
└── scripts/
    └── check_spec_completeness.rb  # Executado sem consumir contexto

# .claude/skills/sdd-workflow/SKILL.md
---
name: sdd-workflow
description: >
  Spec-Driven Development workflow. Use when creating new features,
  doing large refactors, or when the user says "spec", "requirements",
  "design doc", or "plan before coding".
allowed-tools: Read, Write, Glob, Grep, Bash
---
# Spec-Driven Development Workflow

## Quando usar
- Features novas (médias a grandes)
- Refators que tocam 5+ arquivos

## Quando NÃO usar
- Bug fixes simples / alterações de 1 arquivo / protótipos

## Fases
1. Requirements → Gere docs/specs/<feature>/requirements.md. PARE.
2. Design → Gere design.md. PARE.
3. Tasks → Gere tasks.md. PARE.
4. Implementação → Cada tarefa por subagent + commit atômico.

## Regras
- NÃO escrever código antes de aprovação humana em cada fase
- Se descobrir algo novo, ATUALIZE a spec antes de continuar

3.2 Subagents Especializados para SDD

Diferente dos subagents genéricos, esses são focados nas fases do SDD:

# .claude/agents/spec-writer.md
---
name: spec-writer
description: Writes feature specs from high-level descriptions
tools: Read, Write, Glob, Grep
model: sonnet
---
Você é um analista de requisitos. Pesquise o codebase,
identifique componentes afetados, escreva user stories
com critérios testáveis. Nunca escreva código.

# .claude/agents/task-implementer.md
---
name: task-implementer
description: Implements a single task from a spec with tests
tools: Read, Write, Edit, Bash, Glob, Grep
---
Implemente UMA tarefa de cada vez seguindo a spec.
Escreva testes RSpec. Rode os testes. Faça commit.
NÃO toque em arquivos fora do escopo da tarefa.

3.3 Hooks e Commands para SDD

Hooks garantem que regras sejam seguidas sem depender do Claude “lembrar”:

// .claude/settings.json — Hook para verificar sintaxe Ruby
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write",
      "command": "ruby -c $CLAUDE_FILE_PATH 2>/dev/null || echo 'SYNTAX ERROR'"
    }]
  }
}

<!-- .claude/commands/spec-new.md -->
Crie uma nova spec para a feature descrita abaixo.
Use a skill sdd-workflow. Pare após cada fase.
Salve em docs/specs/$ARGUMENTS/

Uso: /spec-new ncm-attribute-responses

4. O WORKFLOW NA PRÁTICA

Passo 1 — Pesquisa Paralela

> Pesquise o codebase em paralelo:
  - Subagent 1: mapeie como ncms_controller funciona
  - Subagent 2: identifique associações do model Ncm
  - Subagent 3: analise como NcmProperty lida com atributos compostos e condicionados

Passo 2 — Gerar Spec

> /spec-new ncm-attribute-responses
  Produtos de um projeto respondem atributos de NCM.
  Um projeto tem 1+ NCMs, cada NCM tem atributos tipados.

Claude gera requirements.md → você revisa e aprova

Passo 3 — Design

> Aprovado. Gere o design.

Claude gera design.md com schema, componentes, trade-offs → você revisa e aprova

Passo 4 — Tasks

> Aprovado. Decomponha em tarefas.

Claude gera tarefas atômicas com dependências e marcação de paralelismo → você revisa e aprova

Passo 5 — Implementação Orquestrada

> Implemente seguindo tasks.md
  Cada tarefa por subagent. Commit atômico após cada uma.
  Você é o orquestrador — subagents são seus devs.
  Tarefas 3 e 4 podem rodar em paralelo.

Prompts que funcionam

5. AGENTES PARALELOS — POR QUE A SPEC FAZ DIFERENÇA

Imagina 3 pedreiros construindo paredes sem planta. Cada um faz do jeito dele, nas medidas que achar melhor. No final, as paredes não encaixam.

Agora imagina que você dá a mesma planta pros 3. Cada um constrói a sua parede, mas todas seguem o mesmo projeto. No final, encaixam.

Com agentes de IA é a mesma coisa:

SEM SPEC:
  Agent 1 → recebe prompt solto → decide sozinho o que fazer
  Agent 2 → recebe outro prompt → decide diferente
  Agent 3 → recebe outro prompt → faz de outro jeito
  Resultado: código inconsistente, conflitos, retrabalho

COM SPEC:
  Todos recebem a MESMA spec aprovada →
    Agent 1 → task 1: migration + model
    Agent 2 → task 3: service        [paralelo]
    Agent 3 → task 4: controller     [paralelo]
  Resultado: código consistente, sem conflito, commits limpos

A spec é a planta. Sem ela, cada agente “adivinha” o que fazer. Com ela, todos trabalham alinhados — mesmo rodando em paralelo.

6. COMO O CRIADOR DO CLAUDE CODE USA

Boris Cherny, que criou o Claude Code, compartilhou o setup dele em janeiro de 2026. O mais interessante é que é surpreendentemente simples — e bate direto com o que estamos propondo aqui:

Paralelismo pesado

Ele roda 5 Claudes em paralelo no terminal, numerados em abas 1-5. Usa notificações do sistema pra saber quando um Claude precisa de input. Além disso, roda mais 5-10 sessões no claude.ai/code ao mesmo tempo. Também inicia sessões pelo celular (app iOS) de manhã e checa depois. No total, ele pode ter mais de 10 agentes trabalhando ao mesmo tempo.

CLAUDE.md é do time, não do dev

O time inteiro compartilha um único CLAUDE.md por repositório, commitado no Git. Todo o time contribui múltiplas vezes por semana. A regra é simples: quando Claude faz algo errado, alguém adiciona a correção no CLAUDE.md na hora. Assim Claude não repete o erro. Outros times dentro da Anthropic mantêm seus próprios CLAUDE.md — cada time é responsável por manter o seu atualizado.

Plan Mode antes de tudo

A maioria das sessões dele começa em Plan Mode (Shift+Tab duas vezes). Nesse modo Claude só lê e analisa o codebase, não escreve código. Ele vai e volta com Claude refinando o plano até gostar. Só depois disso troca pra auto-accept edits e deixa Claude implementar. Na maioria das vezes Claude acerta de primeira porque o plano estava sólido. A frase dele: “Um bom plano é realmente importante!”

Isso é exatamente o princípio do SDD: planejar antes de codar.

Slash Commands pra tudo que repete

Ele cria commands para todo ciclo de trabalho que repete muitas vezes ao dia. O principal é /commit-push-pr — que ele e Claude usam dezenas de vezes por dia. O command usa bash inline pra pré-computar git status e outras informações, fazendo o comando rodar rápido sem ficar perguntando pro modelo.

Os commands ficam em .claude/commands/ e são commitados no Git, então todo o time usa os mesmos atalhos.

Subagents pra tarefas específicas

Ele usa alguns subagents regularmente:

• code-simplifier — simplifica o código depois que Claude termina uma tarefa. Foi open-sourced como plugin oficial (claude plugin install code-simplifier)
• verify-app — tem instruções detalhadas pra testar o Claude Code de ponta a ponta

Ele pensa em subagents como automação dos workflows mais comuns que faz pra cada PR.

Hook pra formatação automática

Usa um PostToolUse hook que formata o código toda vez que Claude escreve num arquivo. Claude já gera código bem formatado na maioria das vezes, e o hook cuida dos últimos 10% — evitando erros de formatação que só apareceriam no CI depois.

Permissões sem risco

Ele não usa –dangerously-skip-permissions. Em vez disso, usa /permissions pra pré-autorizar comandos bash que sabe que são seguros no ambiente dele. Essas permissões ficam em .claude/settings.json e são compartilhadas com o time via Git.

Claude usa ferramentas externas

Claude Code acessa tudo que ele precisa: posta e pesquisa no Slack (via MCP), roda queries no BigQuery (via bq CLI), busca logs de erro no Sentry. A configuração de MCP fica em .mcp.json e é compartilhada com o time.

A dica mais importante dele

“Dê a Claude uma forma de verificar seu próprio trabalho. A qualidade do resultado sobe 2-3x.”

Verificação muda de domínio pra domínio. Pode ser rodar um comando bash, rodar a suíte de testes, testar o app num browser ou simulador. O ponto é: se Claude consegue checar se o que fez está funcionando, ele itera sozinho até acertar. Se não tem como verificar, ele para no primeiro output e torce pra ter dado certo.

No caso dele, Claude testa todas as mudanças que ele faz no claude.ai/code usando o Claude Chrome Extension — abre o browser, testa a UI, e itera até o código funcionar e a experiência ficar boa.

Os números dele

• Último mês: 259 PRs, 497 commits, 40k linhas adicionadas, 38k removidas
• Cada linha foi escrita por Claude Code + Opus
• Claude Code já escreve 4% de todos os commits do GitHub

O que tirar disso pro nosso time

• Commitar CLAUDE.md no Git e todo mundo contribuir quando Claude errar
• Começar em Plan Mode antes de implementar (é o SDD na essência)
• Criar commands pros workflows que a gente repete todo dia
• Dar a Claude uma forma de verificar — no nosso caso, bundle exec rspec
• Compartilhar configs via Git — settings.json, commands, agents, skills

7. QUANDO USAR CADA ABORDAGEM

Lições

Funciona bem:

• Spec-first melhora qualidade mesmo sem ferramentas sofisticadas
• Phase gates (aprovar spec antes de codar) reduzem retrabalho
• Commits atômicos por tarefa facilitam rollback e review

Armadilhas:

• Spec elaborada demais para problema simples (Verschlimmbesserung)
• Spec obsoleta = documentação morta (atualize durante implementação)
• Confiança cega em código gerado (revise como se fosse de um júnior talentoso)
• SDD com spec de 50 páginas de uma vez = Waterfall disfarçado

8. MÉTRICAS E PRÓXIMOS PASSOS

Como saber se está funcionando (avaliar em 30 dias)

Adoção: Specs criadas por semana | Contribuições ao CLAUDE.md | Skills commitadas e usadas

Qualidade: Retrabalho pós-merge diminuiu? | Cobertura de testes acima de 80%? | PRs com menos idas e voltas?

Velocidade: Tempo total de entrega (incluindo debug) | Tempo de revisão de código | Tempo de integração de outro dev numa feature

Documentação: Features novas com spec em docs/specs/ | Specs atualizadas após implementação

Revisão mensal (30 min, primeira sexta do mês)

1. Quantas features passaram por SDD?
2. CLAUDE.md está atualizado?
3. Alguma Skill precisa de ajuste?
4. O que o agente ainda erra? (adicionar ao CLAUDE.md)
5. Alguém descobriu um prompt bom? (compartilhar)

APÊNDICE — MATERIAL DE REFERÊNCIA

A. Antes/Depois — Custo Real

B. Checklist para Boas Specs

1. Comece alto nível — escreva um resumo curto, peça para a IA detalhar. Use Plan Mode (Shift+Tab)
2. Estruture em 6 áreas — Commands, Testing, Estrutura, Code Style, Git Workflow, Limites
3. Quebre em pedaços — cada sub-spec implementável e testável isoladamente
4. Spec é documento vivo — atualize conforme decisões são tomadas, commite no Git
5. Defina limites explícitos:

✅ SEMPRE: Rodar testes antes de commit
⚠️ PERGUNTAR ANTES: Mudanças no schema, adicionar gems
🚫 NUNCA: Editar credentials, modificar CI config

C. Ferramentas da Comunidade

D. Troubleshooting de Skills

F. Glossário