REV-OS — Escreva o Plano Antes de o Time Construir
Como escrever um PRD que define o quê será feito antes de qualquer linha de código — o método que o squad de dev usou para construir o REV-OS.
O que é
REV-OS — Escreva o Plano Antes de o Time Construir
Você vai escrever um PRD (documento de requisitos do produto): o plano completo que descreve o que precisa ser construído, como vai funcionar e em que ordem. O exemplo concreto é transformar a página /open-source de um site em um CMS dinâmico, com banco de dados Supabase, painel administrativo autenticado e migração dos dados existentes sem perder nenhuma URL.
O maior custo de um projeto de software não é escrever código — é refazer. Decisões de estrutura de banco de dados são caríssimas de reverter depois que já tem dado em produção. Escrever o plano antes força essas decisões no momento barato: antes de qualquer linha ser escrita. A regra do REV-OS é clara: primeiro o quê, depois o como.
Os conceitos centrais deste tutorial são: PRD (objetivo, escopo, estrutura de dados, arquitetura, fluxo de auth e sequência de implementação), modo cowork do Claude (lê o código real do projeto antes de responder), plano em ondas (execução organizada em fases com agentes em paralelo) e ações manuais do humano (passos de segurança que só você executa, não os agentes).
Antes de começar, você precisa do projeto acessível para o Claude ler o código via modo cowork, de uma ideia clara do problema a resolver, do squad de dev disponível no Claude Code via /team-os, e da stack Next.js + Supabase + Vercel configurada no projeto de exemplo.
Como funciona
Principais recursos
PRD antes do código
Escreva o plano completo — objetivo, tabela, arquitetura, auth e sequência — antes de qualquer linha ser executada. Isso evita retrabalho caro.
Modo cowork no Claude
Linke o projeto no Claude app para ele ler o código real. Você passa só o objetivo; o Claude descobre a estrutura existente por conta própria.
Execução em ondas
O squad de dev executa em 3 ondas sequenciais — banco, migração e componentes em paralelo, depois QA — com máximo paralelismo dentro de cada onda.
Orquestração com team-os
O /team-os lê o PRD e propõe o plano de orquestração para você aprovar antes de executar. Se o plano vier fraco, rejeite e peça mais agentes.
Ações manuais de segurança
RLS no banco, criação do usuário admin e migração de dados são feitos por você, não pelos agentes — garantindo controle total sobre os passos críticos.
URLs preservadas na migração
O PRD garante que o script de migração preserve cada URL exatamente como está, protegendo links indexados no Google e divulgados externamente.
Nível: intermediário · Tempo estimado: 25 min
Pré-requisitos
- •O projeto acessível para o Claude ler o código real — use o Claude app em modo cowork (projeto linkado)
- •Uma ideia clara do problema a resolver (exemplo: recursos da página /open-source fixos no código, mudar qualquer coisa exige abrir código)
- •O squad de dev disponível no Claude Code via comando /team-os (github.com/joaoguirunas/team-os)
- •Stack do projeto de exemplo: Next.js + Supabase (banco + Auth) + Vercel
Conceitos-chave
PRD
O documento de plano. Contém: objetivo, escopo, estrutura de dados (campos e tipos da tabela), arquitetura, fluxo de autenticação do painel admin e sequência de implementação passo a passo.
Modo cowork
O Claude lê o código real do projeto linkado, então você passa só o objetivo — ele descobre a estrutura existente sozinho, sem precisar descrever cada arquivo.
Plano em ondas
A execução é organizada em fases (ondas), com agentes trabalhando em paralelo dentro de cada onda. Onda 1 = banco; Onda 2 = migração + componentes + auth; Onda 3 = ajustes e QA.
Ações manuais do humano
Alguns passos críticos — ativar RLS, criar o usuário admin, rodar a migração — são feitos por você, não pelos agentes, por questão de segurança e controle.
Passo a passo
Como escrever e executar o PRD com o squad de dev
Passo 1 — Linke o projeto no Claude app (modo cowork)
Abra o projeto no Claude app e linke a pasta como contexto. Isso é o que permite passar só o objetivo: o Claude vai ler o código e descobrir a estrutura atual — no exemplo, os recursos hardcoded da página /open-source — por conta própria. Sem esse link, você teria que descrever toda a estrutura manualmente.
Passo 2 — Gere o PRD com o prompt canônico
Cole o prompt canônico (disponível na seção Prompts prontos abaixo) no Claude app com o projeto linkado. Ele pede um PRD completo, listando o que precisa ser construído e o que o documento deve conter. O Claude vai ler os arquivos e gerar um plano baseado na estrutura real do projeto.
Passo 3 — Revise o PRD antes de salvar
Confira se o documento tem todos os itens obrigatórios: objetivo e escopo, estrutura completa da tabela de recursos (campos, tipos, regras), arquitetura, fluxo de autenticação do painel admin, e uma sequência de implementação passo a passo — não genérica. Se faltar qualquer item, peça para completar antes de avançar.
Passo 4 — Salve o PRD no projeto
Guarde o documento como um arquivo dentro do projeto, na pasta de docs. Esse arquivo passa a ser a referência de toda a execução — o squad de dev vai lê-lo antes de propor qualquer plano.
docs/PRD-cms-open-source.md
Passo 5 — Abra o squad de dev e passe o PRD
No Claude Code, rode o /team-os, selecionando a pasta do projeto. Passe o PRD (arraste o arquivo para o terminal) junto com o prompt de objetivo. O sistema lê tudo antes de propor qualquer coisa — não pule esse passo.
Passo 6 — Peça o PLANO antes de executar
Este é o passo mais importante: não mande executar direto. Peça primeiro um planejamento completo para aprovar. Se o plano vier fraco (poucos agentes), rejeite e peça uma orquestração mais agressiva. O plano bom chega em 3 ondas — Onda 1: base do banco (estrutura das tabelas criada primeiro); Onda 2: migração dos dados + componentes + autenticação, em paralelo; Onda 3: ajustes finais + QA. Só depois de aprovar o plano você libera a execução.
Passo 7 — Faça as 3 ações manuais (só o humano)
Por segurança, três coisas são feitas por você, não pelos agentes: (1) Ativar o RLS — a regra que bloqueia acesso não autorizado ao banco — via Supabase → SQL Editor; (2) Criar o usuário admin via Supabase → Authentication → Users → Add user (e-mail e senha); (3) Pedir a migração dos dados com o prompt de migração (disponível na seção Prompts prontos).
Passo 8 — Teste o sistema
Rode o ambiente local e abra o painel admin. Acesse /admin/login, entre com o usuário criado e confira: o dashboard lista os recursos migrados, é possível adicionar/editar/ativar/desativar, e a página /open-source lê do banco em tempo real.
npm run dev
Gerar o PRD (cole no Claude app com o projeto linkado)
Com base nos arquivos do projeto, gere um PRD completo para transformar a página /open-source em um CMS dinâmico com Supabase. O que precisa ser construído: - Banco de dados com tabela de recursos substituindo os itens fixos no código — preservando todas as URLs existentes - Painel admin autenticado em /admin para adicionar, editar, ativar/desativar e remover recursos sem abrir código - Login com e-mail e senha via Supabase Auth - Regras de acesso: visitantes veem os recursos, só admin autenticado edita - A página /open-source lendo do banco em tempo real - Script para migrar os dados existentes sem perder nenhuma URL No PRD inclua: objetivo e escopo, estrutura completa da tabela de recursos, arquitetura, fluxo de autenticação do painel admin, e sequência de implementação passo a passo.
Pedir o plano no /team-os (antes de executar)
Leia o docs/PRD-cms-open-source.md e o prompt acima. Antes de executar qualquer coisa, me apresente um plano de orquestração completo para eu aprovar. Quero o plano em ondas, usando somente a squad de dev, com o máximo de paralelismo possível. Para cada onda, liste quais agentes atuam, o que cada um entrega e o que precisa estar pronto antes da onda começar.
Refazer o plano quando veio fraco
Esse plano está enxuto demais. Refaça a orquestração usando somente a squad de dev, com mais agentes em paralelo por onda. Quero ver, onda a onda: o agente responsável, o arquivo/entrega e a dependência de cada tarefa. Não comece a executar — só me apresente o plano revisado para eu aprovar.
Rodar a migração de dados
Rode o script de migração de dados.
Erros comuns
- •Executar sem plano: depois que a execução começa com permissões liberadas, ela segue sem parar. Sempre aprove o plano antes de liberar.
- •Aceitar o primeiro plano fraco: se vier com poucos agentes, rejeite e peça orquestração mais agressiva.
- •Perder URLs na migração: as URLs já estão indexadas no Google e linkadas em outros lugares. Garanta que o PRD especifique a preservação de cada URL exatamente como está.
- •Login negado no admin: confira se o RLS foi ativado e o usuário criado. Se persistir, peça ao Claude para adicionar a flag de admin.
- Projeto linkado no Claude app (modo cowork)
- PRD gerado com o prompt canônico
- PRD revisado (escopo, tabela, arquitetura, auth, sequência)
- PRD salvo em docs/PRD-cms-open-source.md
- /team-os aberto, PRD e prompt passados
- Plano em 3 ondas aprovado (rejeitado se fraco)
- RLS ativado no Supabase (SQL Editor)
- Usuário admin criado (Authentication → Users)
- Migração rodada, nenhuma URL perdida
- Testado com npm run dev em /admin/login
- •team-os — squad de dev e orquestração em ondas (https://github.com/joaoguirunas/team-os)
- •Supabase — banco de dados e autenticação (https://supabase.com)
- •Vercel — publicação do projeto (https://vercel.com)
Vá além do tutorial
Quer dominar isso na prática?
Na Formação Gestor de IA você vai do zero ao site no ar comandando equipes de agentes, sem escrever uma linha de código.