forge-sdd — Organize seu fluxo de desenvolvimento com IA

Por que forge-sdd?

Desenvolvimento com IA
que realmente escala

4 pilares que resolvem os maiores problemas de consistência e velocidade ao usar IA no dia a dia.

🤖

Papéis Claros para a IA

Defina se a IA está planejando (Orquestrador), programando (Builder) ou testando (Revisor). Cada um faz uma coisa por vez para evitar erros.

🧠

Memória Contínua do Projeto

A IA lê o histórico e as regras locais antes de começar. Ela sempre sabe onde parou, sem você precisar reexplicar o projeto toda hora.

🔄

Evolução Passo a Passo

Cada funcionalidade é construída e encaixada com segurança. A IA não quebra o que já está funcionando.

🎓

Qualidade de Desenvolvedor Sênior

Antes de programar, o fluxo exige planejar a ideia e criar regras de sucesso claras. No final, tudo é revisado de forma automática.

🗺️ Mapa de Fluxo

Cada arquivo, um propósito no fluxo

Como a estrutura gerada pelo init se conecta a cada etapa do ciclo de desenvolvimento com IA.

Instalação

Scaffold do projeto

Rode o comando init para preparar a pasta sdd/ com toda a memória, tarefas e regras que sua IA vai precisar.

terminal

$ npx @nathanramorim/forge-sdd@latest init \ --yes \ --name "Meu Projeto" \ --stack "go" \ --db "postgres" \ --agent "gemini,claude,copilot"

Node.js ≥ 18 · binário Go baixado e cacheado em ~/.cache/forge-sdd/

Etapa 01

Início da sessão

A IA lê o progresso atual e descobre o que já foi feito, sem você precisar colar instruções gigantes de contexto a cada conversa.

/status

Etapa 02

Discovery & Arquitetura

Ajuda a detalhar o que você quer construir, alinhando o que faz sentido para o usuário com a melhor forma técnica de fazer.

/discovery /constitution /c4-architecture

Etapa 03

Gestão de Features

Cria e divide o desenvolvimento em pequenas funcionalidades fáceis de programar, definindo as regras para considerar a tarefa concluída.

/nova-feature /split-features

Etapa 04

Implementação

A IA assume o papel de programadora (Builder) e escreve o código com base nas especificações técnicas criadas nas etapas anteriores.

/proxima-feature

Etapa 05

Revisão & PR

A IA atua como revisora (Revisor), testando o código e garantindo que tudo siga as regras de qualidade do projeto antes de integrar.

/revisar /archive

Utilitários

Diagnóstico & Upgrade

Verifica a saúde das pastas da IA e atualiza a ferramenta para novas versões com facilidade.

/doctor /upgrade-sdd

sdd/ — estrutura gerada pelo init

📁 sdd/

📂 memory/ etapa 01

📄 progress.md

📄 constitution.md etapa 02

📂 spec/ etapa 02

📄 overview.md

📄 stack.md

📄 modules.md

📄 flows.md

📄 decisions.md

📂 features/ etapa 03

📄 index.md

📄 feat-00-foundation.md etapa 04

📄 feat-NN-*.md

📂 discovery/ etapa 02

📄 *.md

📂 .claude/ / .gemini/ / .github/ agente

🤖 skills/ & prompts/

📄 CLAUDE.md / GEMINI.md etapa 05

🎯 Orquestrador (O Gestor)

Entende o estado do projeto, planeja os próximos passos da IA e mantém o contexto atualizado a cada conversa.

🔨 Builder (O Programador)

Escreve e edita os arquivos de código reais para construir a funcionalidade solicitada de forma focada.

🔍 Revisor (O Inspetor)

Testa a qualidade do código produzido e confere se atende às regras de sucesso definidas antes da tarefa começar.

Início / Memória

Discovery / Arquitetura

Features / Backlog

Implementação

Revisão / PR

Utilitários / Upgrade

📸 Na prática

Como é usar o forge-sdd

Screenshots reais do fluxo, do primeiro comando ao acompanhamento do progresso.

Terminal executando forge-sdd init e criando a estrutura de pastas sdd/

Passo 1

Comece com um comando

forge-sdd init gera toda a estrutura sdd/ e os comandos do agente.

Terminal executando o comando /discovery e gerando os artefatos de discovery e criteria

Passo 2

Descreva a ideia em português

/discovery transforma uma frase em discovery de produto e técnico, com diagramas C4/Mermaid.

Conteúdo real do arquivo criteria gerado, incluindo diagrama C4/Mermaid

Passo 3

O artefato fica no seu repo

O critério técnico gerado é um markdown real, versionável e revisável junto com o código.

Terminal executando o comando /nova-feature e criando o arquivo de especificação da feature

Passo 4

Vira trabalho executável

/nova-feature quebra o discovery em uma feature com escopo e critérios de aceite.

Terminal executando o comando /status e exibindo o progress.md atualizado do projeto

Passo 5

Sempre saiba onde parou

/status mostra o progresso real do projeto a qualquer momento.

🛠️ Referência

Todos os comandos disponíveis

Cada comando tem um propósito claro. Use o certo no momento certo.

Comando	Quando usar	O que faz
/status	Início de sessão	Lê progress.md e reporta fases e bloqueios
/discovery	Ideia vaga	Sessão estruturada com personas PM + Engenheiro Sênior
/nova-feature	Ideia clara	Cria branch + spec + atualiza índice de features
/novo-fix	Bug encontrado	Cria branch fix/ + spec do bug
/split-features	Feature grande (>7 tasks)	Quebra em sub-features desacopladas por domínio
/proxima-feature	Iniciar implementação	Retoma a próxima feature todo do backlog
/revisar	Antes do PR	Valida critério de conclusão, lint e memória
/constitution	Início ou mudança de arch.	Alinha constitution.md com o codebase real
/c4-architecture	Documentar arquitetura	Gera diagramas C4 em Mermaid
/doctor	Diagnóstico	Verifica integridade, MCPs e budgets
/archive	progress.md > 1KB	Move histórico antigo para o log
/upgrade-sdd	Nova versão SDD	Migra a estrutura para a versão mais recente
/tutorial	Primeira vez no método	Ciclo de exemplo guiado, sem tocar dados reais

🤖 Agentes suportados

Funciona onde você trabalha

Configure um ou múltiplos agentes simultaneamente com a flag --agent.

GitHub Copilot

--agent copilot

Use / no chat do VS Code para acionar os comandos diretamente. Ex: /status

Claude

--agent claude

Mencione o comando no chat do Claude para executar. Ex: /revisar

Antigravity

--agent gemini

Peça pelo nome no chat do Antigravity para acionar. Ex: "rodar o status"

🚀 Trilhas de Início Rápido

Em minutos você já está rodando

Projeto do zero ou adoção em projeto existente — o forge-sdd se adapta.

        # Instalação interativa (menu para escolher
          agentes)

        npx @nathanramorim/forge-sdd@latest init

        # Ou direto com flags

        npx @nathanramorim/forge-sdd@latest init . --agent copilot,gemini,claude --name meu-projeto

🆕 Projeto do Zero

Comece com estrutura completa desde o início

Execute o init e escolha seus agentes via --agent

Use /constitution para definir arquitetura e regras base

Use /discovery "sua ideia" para explorar produto e engenharia

Crie features com /nova-feature e inicie com /proxima-feature

🏗️ Projeto Existente

Adote sem alterar sua estrutura atual

Execute npx forge-sdd init . --yes no seu projeto existente

Use /constitution — o agente escaneia seu codebase e aprende suas regras

Sincronize o estado com /status

Mapeie a próxima evolução com /nova-feature

Requisitos: Node.js ≥ 18 · O binário Go é baixado automaticamente e cacheado em ~/.cache/forge-sdd/

Pare de perder
contexto com IA.

Desenvolvimento com IA
que realmente escala

Cada arquivo, um propósito no fluxo

Como é usar o forge-sdd

Todos os comandos disponíveis

Funciona onde você trabalha

GitHub Copilot

Claude

Antigravity

Em minutos você já está rodando

🆕 Projeto do Zero

🏗️ Projeto Existente

Novidades

Pronto para organizar
seu fluxo com IA?

Desenvolvimento com IAque realmente escala

Cada arquivo, um propósito no fluxo

Como é usar o forge-sdd

Todos os comandos disponíveis

Funciona onde você trabalha

GitHub Copilot

Claude

Antigravity

Em minutos você já está rodando

🆕 Projeto do Zero

🏗️ Projeto Existente

Novidades

Pronto para organizarseu fluxo com IA?

Desenvolvimento com IA
que realmente escala

Pronto para organizar
seu fluxo com IA?