AI-SDD CLI — Spec-Driven Development no seu Terminal

Pré-requisitos

Node.js (versão LTS mais recente)
Agente de IA para código instalado: Claude Code, Antigravity CLI (agy), Cursor, Codex CLI, GitHub Copilot, Qwen Code, Windsurf

Instalação

# Abra seu terminal e vá para o diretório do projeto, ou crie um novo
mkdir meu-novo-projeto
cd meu-novo-projeto
npx ai-sdd --lang pt  # Selecione seu agente de IA da lista

# Inicie seu Assistente de IA
claude  # ou agy, etc.

# Pronto! Agora é só conversar com seu agente:
# Inicie uma especificação para um aplicativo web de Calculadora de Aposentadoria

Dois Caminhos

# Inicie o agente de IA e comece o desenvolvimento spec-driven imediatamente
/sdd:spec-init "Construir uma Calculadora de Aposentadoria" # A spec é iniciada
/sdd:spec-requirements calculadora-aposentadoria              # Requisitos são gerados
/sdd:spec-design calculadora-aposentadoria                    # Design é criado
/sdd:spec-tasks calculadora-aposentadoria                     # Divide em tarefas
/sdd:spec-impl calculadora-aposentadoria                      # Executa com TDD

# Primeiro estabeleça o contexto do projeto, depois prossiga com o desenvolvimento
/sdd:steering                                  # A IA aprende o contexto do projeto existente

/sdd:spec-init "Adicionar Checkout como Convidado ao e-commerce existente"
/sdd:spec-requirements checkout-convidado
/sdd:validate-gap checkout-convidado               # Opcional: Analisar existente vs requisitos
/sdd:spec-design checkout-convidado
/sdd:validate-design checkout-convidado            # Opcional: Validar integração do design
/sdd:spec-tasks checkout-convidado                 # Divide em tarefas de implementação
/sdd:spec-impl checkout-convidado                  # Executa com TDD

Artefatos Gerados

Gerado em aproximadamente 10 minutos:

requirements.md

Requisitos no formato EARS

design.md

Arquitetura com diagramas Mermaid

tasks.md

Tarefas de implementação com dependências

Casos de Uso

Em vez de executar comandos, converse com seu agente de IA. Aprove cada fase antes de prosseguir para a próxima.

Você "Inicie uma spec para uma Calculadora de Aposentadoria"

AI Gera requirements.md e revisa com você

Você "Os requisitos estão bons — aprove"

AI ✅ Requisitos aprovados. Gerando design.md...

Você "Design está sólido — aprove"

AI ✅ Design aprovado. Dividindo em tasks.md...

Você "Tarefas estão corretas — aprove"

AI ✅ Tarefas aprovadas. Implementando com TDD...

O que commitar (e o que não commitar)

npx ai-sdd monta a camada de ferramentas do agente — .claude/, CLAUDE.md, .sdd/settings/. As specs e os arquivos de steering são criados separadamente, conforme você executa os comandos de spec e steering. Esses sim são a linguagem compartilhada do projeto. Commite os artefatos, não as ferramentas.

Adicione estas linhas ao seu .gitignore:

# Arquivos de agente AI-SDD (Claude Code — regenere com `npx ai-sdd`)
CLAUDE.md
.claude/
.sdd/settings/

Cada desenvolvedor executa npx ai-sdd para montar os arquivos do agente localmente.

Mantenha .sdd/specs/ e .sdd/steering/ no controle de versão.

Alguns times preferem versionar CLAUDE.md e .claude/commands/ para compartilhar instruções e comandos customizados. Escolha o que funciona para o seu time — os arquivos de spec e steering foram projetados para serem commitados como sua trilha de auditoria spec-as-code.

Steering Customizado

O /sdd:steering-custom estende os arquivos de .sdd/steering/ que seu agente lê como memória do projeto. A maioria dos templates captura padrões de uma única análise do código. Dois deles funcionam de forma diferente — e merecem atenção.

Nada disso é obrigatório. O fluxo padrão — requisitos → design → tarefas → implementação — funciona sem nenhum arquivo customizado. Eles existem para quando os padrões deixarem de ser suficientes.

Templates padrão, gerados uma vez a partir do seu código:

api-standards testing security database error-handling authentication deployment cross-repo jira azure-devops

Documentação viva

Research Notes

As respostas que o código não dá.

Todos os outros templates são gerados uma única vez, a partir de uma análise do código. Este começa quase vazio e cresce a cada conversa — o que um campo realmente significa, qual sistema grava o quê, respostas de stakeholders, peculiaridades não documentadas. Fatos que exigiram esforço real para descobrir, capturados uma vez para que seu agente nunca mais reaprenda do jeito difícil.

research-notes.mdcresce a cada conversa

## tabela orders — coluna statussessão 3

Somente o webhook de pagamento grava em orders.status; a API apenas lê.

## sync noturno — comportamento de retrysessão 11

Tenta 3× com intervalo fixo de 5s e depois descarta o lote em silêncio — uma queda de ~15s pode perder dados.

## staging vs produçãosessão 19

Staging usa cache de 60s e produção, 10s — diferença conhecida, não é bug de configuração.

Pergunte ao seu agente "Crie o steering de research notes" → .sdd/steering/research-notes.md

Estilo opcional

Diagram Conventions

Diagramas de design que mostram o que mudou.

Por padrão, os diagramas do design.md são Mermaid puro — estrutura, sem cor. Adicione este arquivo uma vez e todo diagrama ganha significado: componentes novos em verde, modificados em azul, intocados em cinza, sistemas externos em amarelo-claro, agrupados em raias por módulo.

Pergunte ao seu agente "Crie o steering de diagram conventions" → .sdd/steering/diagram-conventions.md

Recorra às research notes quando seu agente insistir em perguntas que alguém já respondeu. Recorra às diagram conventions quando a revisão de design precisar mostrar, de relance, o que uma mudança afeta. Até lá, os padrões são exatamente o que você precisa.

Saiba mais

ai-sdd.com npm i ai-sdd

Um framework para agentes de IA que implementa Spec-Driven Development (SDD)