Framework de desenvolvimento AI-assisted

Como usar o RF-Dev
em projetos reais

Um guia direto: você não precisa entender a arquitetura interna pra usar. Escolha o seu caso abaixo e siga o passo a passo.

Qual é o seu caso?

Quatro pontos de partida. Cada um leva ao mesmo motor (Plan → Execute → Verify), por um caminho diferente.

Tenho um projeto que já existe

Brownfield: o RF-Dev mapeia o código existente e cria a memória do projeto antes de você mexer em qualquer coisa.

Vou iniciar um projeto novo

Greenfield: parte da ideia, não do código. O framework te leva da ideia ao primeiro plano de desenvolvimento.

Quero discutir e criar o PRD

Uma entrevista guiada transforma a discussão em requirements + roadmap, e daí em desenvolvimento.

Já tenho um PRD pronto

O framework ingere seu documento, valida as lacunas e deriva o plano de execução direto dele.

Conceitos em 2 minutos

O mínimo pra entender o que está acontecendo enquanto você usa.

O ciclo central

Todo trabalho no RF-Dev segue três fases. Você não chama elas manualmente uma a uma — os comandos orquestram, e as skills embutidas garantem o rigor de cada fase.

📋 Plan→ ⚙️ Execute→ ✅ Verify

As 4 camadas (o que faz o framework "inteligente")

Camada	O que faz por você
Code Intelligence (GitNexus)	Um grafo do seu código. O agente sabe quem chama o quê e o que quebra se você mudar X — em vez de adivinhar lendo arquivos.
Wiki	A memória de longo prazo do projeto (em `.rf-dev/wiki/`). Conventions, conceitos, decisões. O agente lê isso em toda tarefa.
SDD Workflow	O motor Plan → Execute → Verify, com planos tipados e skills especializadas (TDD, simplificação, debugging…).
CLI / Visual	Os comandos que você dispara dentro do seu runtime (Claude Code, Cursor, etc.).

Regra de ouro: o CLI rf-dev (npm) instala e atualiza o framework no projeto. Tudo que é decisão de produto/código acontece dentro do runtime, via comandos nativos (/init, /plan, /prd…).

Comandos

Cada comando abre com os detalhes: quando usar, parâmetros e exemplos. Clique para expandir.

Próximos passos. Ao final de cada comando, o RF-Dev sugere os próximos comandos do fluxo (um bloco ─── Próximos passos ───) conforme o resultado — é só uma sugestão, ele nunca executa o próximo comando sozinho.

Convenção: "texto" = descrição livre · <valor> = valor que você fornece · --flag = opção · (nenhum) = comportamento padrão. plan_id = PLAN-NNN; T<id> = id de task.

Principais

/init Entrada universal — inventaria o projeto e cria a wiki

Quando usar: sempre o primeiro comando num projeto. Em projeto existente, ele mapeia stack/convenções e cria a memória (wiki). Em projeto novo, detecta greenfield e delega pro PRD.

Parâmetros

Argumento	O que faz
(nenhum)	Init completo: detector → agentes paralelos → secret scan → GitNexus → bootstrap da wiki → conventions → config seed.
`--sequential`	Roda os agentes em série em vez de paralelo. Use em runtimes sem fan-out (Cursor, Windsurf, OpenCode).
`--reference <path>`	Inclui um projeto antigo como fonte secundária (páginas marcadas `source: reference/...`).
`--skip-design-system`	Pula o 5º agente (análise de design system) mesmo em projeto com frontend.
`--non-interactive`	Modo CI/installer: lê pré-aprovações de `.rf-dev/init.json`. Aborta se algo não estiver coberto.

Exemplos

/init                          # inventaria + cria a wiki
/init --reference ../old-app   # usa projeto antigo como referência
/init --sequential             # agentes em série (Cursor, Windsurf)

/prd Transforma ideia ou documento em requirements + roadmap

Quando usar: antes de planejar, quando você precisa definir o quê. Conduz uma entrevista que vira requirements + roadmap na wiki.

Parâmetros

Argumento	O que faz
`"descrição"`	PRD novo do zero: entrevista agressiva → módulos → requirements → roadmap.
`--from @arq1 @arq2`	Ingere documentos existentes + entrevista de validação (preenche lacunas). Aceita múltiplos arquivos.
`--continue`	Retoma um PRD em andamento a partir de `prd-draft.json`.
(nenhum)	Mostra a ajuda e para.

Exemplos

/prd app de cobrança recorrente   # PRD novo (entrevista)
/prd --from @docs/prd.md          # ingere doc + valida
/prd --continue                   # retoma PRD em andamento

/plan Decompõe uma feature/PRD em fases e tasks verificáveis

Quando usar: o caminho padrão para qualquer feature que precise de decomposição. Gera o PLAN.json — mas não executa; você inspeciona e aprova.

Parâmetros

Argumento	O que faz
`<feature>`	Cria/atualiza o `PLAN.json` a partir de uma entrada do roadmap, decompondo em fases/tasks.
`--from-prd <path>`	Lê um PRD/RFC existente e deriva o plano direto dele.
`--update <plan_id>`	Re-decompõe um plano existente após mudança de escopo, sem perder histórico.
`--phase <nome>`	Decompõe apenas a fase nomeada (planejamento incremental).

Exemplos

/plan filtro por status nos pedidos  # de uma feature
/plan --from-prd docs/prd.md         # deriva de um PRD
/plan --update PLAN-013              # re-decompõe após mudança
/plan --phase "fase 2: API"          # só uma fase

/quick Tarefa pequena: planeja e executa num passo só

Quando usar: alteração pequena e bem delimitada que não merece um plano formal. Um guard avisa se a tarefa for grande demais e sugere /plan.

Parâmetros

Argumento	O que faz
`"descrição"`	Nova quick task: carrega contexto da wiki, roda o complexity guard, plan+execute num agente só, commit atômico.
`--validate`	Igual à quick, mas exige sua confirmação explícita dos passos antes de executar.
`--continue`	Retoma uma quick em andamento a partir de `.planning/quick/quick-NNN.json`.
(nenhum)	Mostra a ajuda e para.

Exemplos

/quick corrigir timezone no parser  # tarefa pequena num passo
/quick --validate renomear campo     # confirma antes de executar

/execute Executa um plano aprovado (por padrão, uma fase por vez)

Quando usar: depois de aprovar um plano. Roda as tasks; com --auto-continue, percorre todas as fases sozinho (mas nunca faz o ship).

Parâmetros

Argumento	O que faz
`<plan_id>`	Executa todas as tasks pendentes da fase atual e para (sem verify automático).
`<plan_id> --auto-continue`	Executa todas as fases: tasks → verify → fix-loop → INGEST → próxima fase. Nunca chama `/ship`.
`--auto-continue`	Idem, no único plano ativo (sem precisar do id).
(nenhum)	Fase atual do único plano ativo. Com 2+ planos, lista e para; com 0, orienta a rodar `/plan`.

Exemplos

/execute PLAN-013                  # executa a fase atual e para
/execute PLAN-013 --auto-continue  # todas as fases
/execute                           # fase atual do único plano ativo

/next Executa só a próxima task elegível e para

Quando usar: quando você quer avançar task a task, com controle entre cada uma — em vez de rodar a fase inteira de uma vez.

Parâmetros

Argumento	O que faz
`<plan_id>`	Próxima task pendente do plano informado.
(nenhum)	Próxima task do único plano ativo. 2+ planos: lista e para; 0: orienta.

Exemplos

/next            # próxima task do plano ativo
/next PLAN-013   # próxima task de um plano específico

/redo Refaz uma task ou fase concluída, com motivo registrado

Quando usar: quando uma task/fase já concluída não ficou boa. O motor decide a estratégia (refinar vs reverter) e confirma antes de mexer no git. Não funciona em Quick.

Parâmetros

Argumento	O que faz
`T<id> "motivo"`	Refaz uma task concluída. O motor decide REFINE / REVERT parcial / REVERT total e pede confirmação antes de qualquer operação git.
`T<id> T<id> "motivo"`	Refaz várias tasks consecutivas na mesma invocação.
`phase <n> "motivo"`	Refaz uma fase: o motor classifica re-executar (HOW) vs re-decompor (WHAT). Máx 1 redo por fase.
`<arg> "motivo" plan-<id>`	Idem, escopado a um plano explícito.

Exemplos

/redo T04 "não tratou o caso de lista vazia"
/redo phase 2 "mudou o contrato da API"
/redo T07 "lógica errada" plan-PLAN-013

/review Ciclo de verificação por personas especializadas

Quando usar: para revisar um PR, um plano, uma branch ou o diff atual. As personas (code/test/security) são escolhidas pelo nível e pelos triggers — ou forçadas com --full-verify.

Parâmetros

Argumento	O que faz
`"escopo"`	Roda o verify sobre o escopo: nº de PR, `plan_id`, ref de branch ou o diff do working-tree.
`--full-verify`	Força as três personas (`code-reviewer` + `test-engineer` + `security-auditor`), independente do nível.
`--continue`	Retoma um review em andamento.
(nenhum)	Mostra a ajuda e para.

Exemplos

/review 142            # review do PR #142
/review PLAN-013       # review de um plano
/review --full-verify  # força code + test + security

/ship Portão final de entrega: verificação + PR

Quando usar: para fechar a feature. Roda o ship gate e, se aprovado, monta o corpo do PR. Use --dry-run antes pra saber o que ainda falta.

Parâmetros

Argumento	O que faz
`<plan_id>`	Roda o ship gate; no veredito `SHIP`, monta o corpo canônico do PR e entrega ao runtime.
`--dry-run`	Só o veredito (`SHIP` ou `BLOCK_*`), sem gerar o PR — pra saber o que falta antes do ship real.
`--continue`	Retoma um ship em andamento (carrega `accepted_risks[]` e checklist de pré-launch).
(nenhum)	Mostra a ajuda e para.

Exemplos

/ship PLAN-013            # ship gate + monta o PR
/ship PLAN-013 --dry-run  # só o veredito (o que falta)

/status Estado read-only de planos e métricas

Quando usar: a qualquer momento, pra ver onde os planos estão. Não muda nada — é só leitura.

Parâmetros

Argumento	O que faz
`<plan_id>`	Estado de um plano específico.
(nenhum)	Estado de todos os planos ativos.
`--metrics`	Agregações de métricas de todos os planos (read-only).
`<plan_id> --metrics`	Métricas filtradas por um plano.

Exemplos

/status            # todos os planos ativos
/status PLAN-013   # um plano específico
/status --metrics  # métricas agregadas

/sync Atualiza grafo + wiki quando a base mudou por fora do fluxo

Quando usar: depois de editar código manualmente (fora do /execute), pra wiki e grafo do GitNexus não ficarem defasados.

Parâmetros

Argumento	O que faz
(nenhum)	`gitnexus analyze` + INGEST do delta do git desde o último sync.
`--wiki-only`	Pula o grafo; só o INGEST do delta na wiki.
`--graph-only`	Só o `gitnexus analyze`; não toca na wiki.

--wiki-only e --graph-only são mutuamente exclusivos — usar os dois juntos é recusado.

Exemplos

/sync               # grafo (GitNexus) + wiki
/sync --wiki-only   # só a wiki
/sync --graph-only  # só o grafo

Secundários

Fluxos de apoio — você usa sob demanda, não no dia a dia.

/autonomous Roda o pipeline completo de um plano até ficar pronto pra ship

Quando usar: quando confia no plano e quer rodá-lo de ponta a ponta sem parar a cada passo. Ele para antes do ship real — a decisão de publicar continua sua.

Parâmetros

Argumento	O que faz
`<plan_id>`	Roda o plano até ship-readiness e para antes do `/ship`.
(nenhum)	Único plano ativo. 2+ planos: lista e para; 0: orienta a rodar `/plan`.

Exemplos

/autonomous PLAN-013   # roda tudo, para antes do ship
/autonomous            # único plano ativo

/codebase-review Varredura arquitetural read-only do repositório

Quando usar: pra ter um raio-X da arquitetura — camadas, hotspots, e desvios em relação às convenções registradas na wiki.

Parâmetros

Argumento	O que faz
(nenhum)	Varredura completa: estrutura, camadas, hotspots, drift vs `wiki/architecture/conventions.md`.
`--scope <path>`	Limita a varredura a uma subárvore (ex: `--scope app/Services/`).
`--findings-only`	Pula a narrativa; só a lista de achados (bom pra triagem).
`--no-gitnexus`	Modo degradado: inspeção de arquivos sem GitNexus (emite aviso).

Exemplos

/codebase-review                       # varredura completa
/codebase-review --scope app/Services/  # só um subdiretório
/codebase-review --findings-only        # só os achados

/debug Investigação guiada de um bug

Quando usar: quando algo está quebrado e você quer uma triagem estruturada — rastrear o erro, levantar hipóteses, propor a correção.

Parâmetros

Argumento	O que faz
`"sintoma"`	Pré-popula o sintoma a partir da descrição e dispara a triagem de debugging.
`--from-error`	Usa o erro/stack trace mais recente que apareceu na conversa.
`--continue`	Retoma um debug em andamento.
(nenhum)	Mostra a ajuda e para.

Exemplos

/debug erro 500 ao salvar nota fiscal
/debug --from-error   # usa o último stack trace da conversa

/glossary Linguagem ubíqua do projeto (termos do domínio)

Quando usar: pra manter os termos do domínio consistentes entre código, docs e equipe. Renomear um termo aqui pode propor refactors no código.

Parâmetros

Argumento	O que faz
(nenhum)	Mostra o glossário atual (de `wiki/concepts/`).
`--add <termo>`	Adiciona um termo interativamente (definição, aliases, escopo, referências).
`--rename <antigo> <novo>`	Renomeia o termo em toda a wiki e propõe refactors de código via `rf plan`.
`--lint`	Checa consistência: duplicatas, definições conflitantes, termos usados mas não definidos.
`--diff <commit>`	Mostra como o glossário evoluiu desde um commit.

Exemplos

/glossary                       # mostra o glossário
/glossary --add "Competência"    # adiciona um termo
/glossary --lint                 # checa consistência

/wiki Operações sobre a memória de longo prazo

Quando usar: pra consultar, reconstruir ou verificar a saúde da wiki. O query é uma busca progressiva (do índice até a página completa).

Parâmetros

Argumento	O que faz
`ingest` / `ingest-external`	Ingere fontes externas de `.rf-dev/raw/` na wiki.
`ingest-phase`	Extrai conhecimento de artefatos pós-fase (`PLAN.json`, git diff, findings do verify).
`query <pergunta>`	Consulta progressiva (índice → resumos → seções → páginas completas).
`lint`	Lint completo da wiki (7 verificações).
`status`	Status da wiki (manifest, staging, frescor).
`rebuild`	Reconstrói a wiki a partir de `.rf-dev/raw/` + digests de fase.
`rollback <página>`	Restaura uma página ao estado anterior ao último INGEST.

Exemplos

/wiki query como funciona a emissão?
/wiki lint
/wiki rebuild

/settings Lê e edita a config do projeto

Quando usar: pra inspecionar ou ajustar o .planning/config.json — principalmente os triggers de segurança do verify.

Parâmetros

Argumento	O que faz
(nenhum)	Imprime o `.planning/config.json` atual.
`--get <jsonpath>`	Imprime um campo específico (ex: `--get verify.level_2_security_triggers`).
`--add-trigger <pattern>`	Adiciona um regex de trigger de segurança (confirmação por item).
`--remove-trigger <pattern>`	Remove um trigger. Os 14 canônicos (ADR-007) são protegidos — pedem confirmação explícita.
`--reset-triggers`	Restaura os 14 triggers canônicos do ADR-007.

Exemplos

/settings                                   # mostra a config
/settings --get verify.level_2_security_triggers
/settings --reset-triggers                    # volta aos 14 canônicos

/health Check read-only da instalação do RF-Dev

Quando usar: quando algo parece estranho (locks presos, GitNexus indisponível, wiki defasada). Diagnostica sem alterar nada.

Parâmetros

Argumento	O que faz
(nenhum)	Check completo: locks, GitNexus, `state.json`, integridade da wiki, presença dos schemas.
`--quick`	Smoke test: só locks + state + manifest da wiki.
`--locks`	Lista os `*.lock` em `.planning/active/` com PID + idade.
`--gitnexus`	`which gitnexus` + status + timestamp do último índice.
`--wiki`	Verifica se o manifest da wiki bate com o `HEAD` do git.

Exemplos

/health            # check completo
/health --locks    # lista locks presos
/health --gitnexus # disponibilidade do GitNexus

Não existe /verify separado. A verificação está embutida nas skills (Process → Verification → Red Flags) e no /review / /ship. O ciclo Plan→Execute→Verify acontece por construção.

Instalação (uma vez por projeto)

O RF-Dev é instalado dentro do projeto que você vai desenvolver. Cenários 1 e 2 começam por aqui.

# 1) configure o registry privado uma vez (GitHub Packages)
npm config set @guilherme-miranda:registry https://npm.pkg.github.com

# 2) instale o RF-Dev no projeto, escolhendo o(s) runtime(s)
npx --yes --package=@guilherme-miranda/rf-dev rf-dev install --claude
# múltiplos:  --claude --cursor --gemini    |    todos:  --all

# dica: veja o que vai acontecer sem escrever nada
npx --yes --package=@guilherme-miranda/rf-dev rf-dev install --claude --dry-run

O install cria o .rf-dev/ (skills, schemas, scripts), os comandos nativos do runtime e registra o RF-Dev no arquivo de instruções do runtime (CLAUDE.md / AGENTS.md / etc.). Depois, abra o runtime no diretório do projeto.

Convivência com o seu CLAUDE.md. O RF-Dev escreve apenas um bloco gerenciado entre os marcadores  e . Tudo que você escrever fora do bloco é preservado — dá pra instalar até num projeto que já tem um CLAUDE.md próprio. Regra: não edite dentro do bloco (ele é regerado nas atualizações); suas instruções vão fora dele.

GitNexus (recomendado). O installer tenta configurar o GitNexus (a camada de code intelligence). Sem ele o framework funciona em modo degradado. Se não quiser agora, use --no-gitnexus.

Atualizar o framework

Quando sair uma versão nova do RF-Dev, atualize o projeto sem perder nada do que é seu:

npx --yes --package=@guilherme-miranda/rf-dev rf-dev update

O update propaga skills, comandos e o bloco gerenciado do bootstrap — e nunca toca na sua wiki (.rf-dev/wiki/), nos seus planos (.planning/), no seu código, nem no que você escreveu fora do bloco gerenciado.

1 · Projeto que já existe

Quando usar: você tem uma base de código rodando e quer começar a desenvolver com o RF-Dev.

A regra aqui é não sair codando. Primeiro o framework mapeia o que já existe e constrói a memória do projeto. Isso é o que faz o agente parar de adivinhar.

Instale o RF-Dev no projetoVeja a seção de instalação. Depois abra o runtime no diretório.
Rode /initEle inventaria stack e convenções, preserva os raw sources e faz o bootstrap da wiki.
```
/init
```
Revise a wiki geradaAbra .rf-dev/wiki/ — principalmente architecture/conventions.md. Essa é a memória que o agente vai consumir em toda tarefa. Vale o tempo de leitura e correção.
Escolha uma feature pequena e planeje
```
/plan adicionar filtro por status na listagem de pedidos
```
Inspecione o plano (fases + tasks) antes de aprovar.
ExecuteRode o plano fase a fase. O agente segue as skills embutidas (TDD, simplificação, debugging…).
```
/execute   # ou /next, task a task
```
Feche com review e PR
```
/review
/ship
```

Primeira vez? Comece por uma feature realmente pequena. O objetivo da primeira rodada é você ver o ciclo inteiro funcionando, não entregar algo grande.

2 · Iniciar um projeto novo

Quando usar: você tem uma ideia/produto e ainda não há código (ou quase nada).

Aqui o ponto de partida é a ideia, não o código. O /init reconhece que é greenfield e te encaminha para o fluxo de PRD — porque planejar código que ainda não existe exige primeiro definir o quê.

Instale o RF-Dev na pasta do projeto novoVeja a instalação. Pode ser uma pasta praticamente vazia.
Rode /initAo detectar greenfield, ele delega para o fluxo de PRD (próximo passo) em vez de tentar inventariar um código inexistente.
```
/init
```
Crie o PRD a partir da ideiaUma entrevista guiada vira requirements + roadmap. Veja o caso 3 para o detalhe da discussão.
```
/prd app de emissão de NFS-e para pequenas prefeituras
```
Planeje a primeira entrega do roadmap
```
/plan <primeira entrega do roadmap>
```
Execute → review → ship
```
/execute
/review
/ship
```

Atenção: em greenfield, o /init não popula a wiki da mesma forma que em projeto existente — a memória vai sendo construída conforme o PRD e o desenvolvimento avançam.

3 · Discutir o projeto e criar o PRD

Quando usar: você tem uma ideia na cabeça e quer transformá-la em algo estruturado antes de planejar.

O /prd conduz uma entrevista agressiva: ele questiona, desafia, pesquisa alternativas quando você não sabe, e força decisões de escopo (v1 / v2 / fora de escopo) e prioridade. O resultado é um PRD com requirements + roadmap, compilado na wiki.

Inicie a discussão

/prd sistema de cobrança recorrente com split de pagamento

Responda à entrevistaO agente vai te fazer perguntas e propor categorizações. Você decide o escopo e a prioridade — ele propõe, você categoriza. Cada resposta é salva incrementalmente (em prd-draft.json); se a sessão cair, o progresso fica preservado.
Defina o "Fora de escopo"Obrigatório. Todo PRD precisa de uma seção explícita do que não entra — é o que evita escopo infinito.
Pause e retome quando precisar
```
/prd --continue
```
Do PRD para o desenvolvimentoCom requirements + roadmap prontos, derive o plano:
```
/plan <entrada do roadmap>
```

Use a pesquisa do agente. Quando você não souber decidir algo, peça alternativas. Ele pesquisa, apresenta trade-offs e registra a decisão — você decide com informação, sem repetir a pesquisa depois.

4 · Já tenho um PRD pronto

Quando usar: você (ou alguém) já escreveu um PRD/RFC/doc e quer partir dele para o desenvolvimento.

Você não joga o documento fora nem recomeça do zero. O framework ingere o seu PRD e roda uma entrevista de validação — porque todo documento tem lacunas — e então deriva o plano direto dele.

Ingira o documento existenteAponte um ou mais arquivos. O agente lê, valida e preenche as lacunas com você.
```
/prd --from @docs/meu-prd.md @docs/anexo-tecnico.md
```
Passe pela entrevista de validação
A entrevista é obrigatória, mesmo com --from. Documentos sempre têm gaps — o agente desafia e completa o que falta. Não pule.
Derive o plano direto do PRDEm vez de descrever a feature de novo, aponte o PRD:
```
/plan --from-prd docs/meu-prd.md
```
Execute → review → ship
```
/execute
/review
/ship
```

Atalho: se o PRD já estiver muito completo e validado, você pode ir direto para /plan --from-prd <path>. Mas vale rodar o /prd --from antes para a validação pegar gaps que o plano herdaria.

Dicas e problemas comuns

Boas práticas

Sempre revise a wiki depois do /init. Ela é a memória que guia todas as tarefas seguintes.
Inspecione o plano antes de aprovar. O /plan só gera o plano — quem manda executar é você.
Comece pequeno. Uma feature pequena na primeira rodada ensina o ciclo inteiro sem risco.
Rode /sync quando editar código por fora do fluxo, pra wiki e grafo não ficarem defasados.

Troubleshooting

Situação	O que fazer
Não quero instalar o GitNexus agora	Use `--no-gitnexus` no install. Funciona em modo degradado.
Quero ver o que vai acontecer sem escrever arquivo	Adicione `--dry-run` em qualquer subcomando do `rf-dev`.
O runtime pede um comando que não existe	Confirme o runtime instalado (`ls .claude/commands/`) ou rode `rf-dev update --<runtime>`.
Clonei um projeto e o `.rf-dev/` não veio	Rode `rf-dev restore` — reconstrói em segundos sem reconfigurar nada.

Para o guia completo de instalação, runtimes suportados e flags, veja o docs/QUICKSTART.md no repositório.

Como usar o RF-Devem projetos reais

Qual é o seu caso?

Tenho um projeto que já existe

Vou iniciar um projeto novo

Quero discutir e criar o PRD

Já tenho um PRD pronto

Conceitos em 2 minutos

O ciclo central

As 4 camadas (o que faz o framework "inteligente")

Comandos

Principais

Secundários

Instalação (uma vez por projeto)

Atualizar o framework

1 · Projeto que já existe

2 · Iniciar um projeto novo

3 · Discutir o projeto e criar o PRD

4 · Já tenho um PRD pronto

Dicas e problemas comuns

Boas práticas

Troubleshooting

Como usar o RF-Dev
em projetos reais