Guia Completo

Do zero ao primeiro deploy. Entenda como cada peça do AI Workbench se conecta e como usar na prática.

Fluxo Completo

Fase 1: Configuracao do Projeto

Clone o Repositório

git clone https://github.com/jdonini/ai-workbench.git
cd ai-workbench

Execute o Wizard de Setup

cd /seu/projeto/existente
claude /caminho/para/ai-workbench/templates/setup-wizard.md

O wizard faz 12 perguntas sobre seu projeto e detecta automaticamente a stack. Ao final, gera toda a estrutura de configuração.

Instale o Superpowers para Sua Ferramenta

Na Fase 0, o wizard instala o superpowers, mas o método de instalação depende da ferramenta:

Claude Code (marketplace oficial)
/plugin install superpowers@claude-plugins-official

Claude Code (marketplace obra)
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Codex
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

OpenCode
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

Instale o Codex Plugin

O codex-plugin-cc permite usar o Codex dentro do Claude Code para reviews e delegação de tarefas:

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins

Após instalar, rode /codex:setup para verificar se o Codex está pronto. Se não estiver logado, rode !codex login.

Fase 2: Ferramentas

Claude Code — Orquestrador

Ferramenta principal que orquestra o workflow. Usa o CLAUDE.md como entrypoint e gerencia subagents.

/start-feature

Inicia uma nova feature com brainstorm + planning

/debug-issue

Debug sistemático com hipóteses

Codex CLI — Revisao

Usado como reviewer automatizado. Roda subagents para verificar qualidade do código antes do commit.

/review-code

Delega review para o Codex

OpenCode — Executor

Executor open-source alternativo. Suporta OpenRouter como provider, permitindo uso de modelos de baixo custo.

opencode run

Executa tarefas com modelo configurado

Zed / VS Code — Editores

Editores alternativos que leem a mesma configuração gerada pelo wizard. Compatíveis com .claude/ e .opencode/.

Fase 3: Workflow SDD na Prática

Brainstorming

Antes de codar, descreva a feature. O skill brainstorming deve ativar automaticamente:

Quero implementar autenticação JWT
com refresh tokens.

O brainstorming deve explorar:
- Requisitos funcionais e não-funcionais
- Abordagens alternativas
- Riscos e dependências

Branch Isolada + Plano

Depois que o design é aprovado, o Superpowers deve seguir para worktree e planejamento estruturado:

Fluxo esperado após aprovação:
- using-git-worktrees
- writing-plans

Arquivos gerados:
- docs/spec/...-design.md
- docs/plan/...md

Execução + TDD

A implementação deve acontecer tarefa por tarefa pelo workflow de execução, com TDD aplicado em cada etapa:

Execução recomendada:
/subagent-driven-development

Alternativa:
executing-plans

Dentro de cada tarefa:
1. RED: escrever teste que falha
2. GREEN: código mínimo para passar
3. REFACTOR: melhorar sem quebrar testes

Revisao + Finalizacao

Entre tarefas, o Superpowers deve rodar revisão. No final, feche a branch com o workflow de encerramento:

Skill de review:
requesting-code-review

Comando de encerramento:
/finishing-a-development-branch

Isso verifica:
- Qualidade do código
- Cobertura de testes
- Aderência ao plano
- Prontidão para merge / PR

Encerramento

Commits limpos, PR pronto para revisao humana:

git add -A
git commit -m "feat: descrição da feature"
git push origin feature/nome-da-feature

Manutenção

↻

Wizard Update

Para atualizar a configuração do projeto, re-execute o wizard. Ele detecta o estado atual e atualiza apenas o necessário:

claude /caminho/para/ai-workbench/templates/setup-wizard.md

Próximo Passo

Agora que você entende o fluxo completo, explore cada ferramenta em detalhe.

Ver Ferramentas Ver Fluxo