Fluxo de revisão com demo
Testes e code review comprovam o mecanismo. Eles não conseguem dizer que o menu está no lugar errado, que o fechar pisca ou que o ícone está 2 px abaixo — só o usuário consegue. Por isso, uma alteração de aparência ou operação é projetada como um demo funcional que o usuário aprova por funcionalidade antes de qualquer código de produto, e é fechada apenas quando o usuário a aceita no aplicativo real. Um painel de revisão (uma página Artifact com um banco de dados compartilhado) rastreia cada funcionalidade através de seis estados.
Configuração do projeto: .claude/demo-board.md (URL do painel, aplicativos de referência por área, larguras a verificar, aplicativo ao vivo + se contém dados reais, portas de cópia do workspace, comandos de gate, arquivo de especificação). Ausente → crie o painel primeiro: references/board-setup.md.
Qual caminho
- Altera a aparência, a posição ou a operação → este fluxo. Sem exceção por tamanho ou prazo.
- Restaura comportamento já definido pela especificação ou por um demo aprovado (crash, dados errados, overflow, regressão) → corrija diretamente com TDD, sem demo. Informe ao usuário qual caminho você julgou.
- Um bug relatado em um item já enviado do painel → volte para
porting, corrija, verifique ao vivo,shipped. Uma correção que altere a aparência → nova rodada de demo.
O fluxo
- Referência primeiro. Para a área, consulte os aplicativos que os usuários já conhecem (a configuração os lista). Registre onde o controle está posicionado, cada tecla, o movimento, incluindo saídas. Desvie apenas com um motivo declarado. Uma pesquisa com usuários simulados escolhe entre opções; ela nunca substitui a referência.
- Meça a IU real. Capture a tela das telas enviadas que a alteração afeta nas larguras do usuário, somente leitura, e meça gutters, tamanhos, alinhamento. Projete sobre esse layout.
- Construa o demo como uma entrada
feat()que realmente funciona: cliques, teclas, movimento incluindo saídas, claro + escuro, largura estreita. →references/add-feature.md - Registre-o: uma linha
changesefeatures/<id>→review. - Entregue e pare. Link + o que observar. Nenhum código de produto para este item até que esteja
approved. "Prossiga a menos que você se oponha" não é aprovação. Se a aprovação não puder vir antes de um prazo, ofereça ao usuário o que já está sendo enviado para ele — nunca construa adiantado. - Pegue as decisões no início de cada sessão de IU e sempre que o usuário disser que revisou: leia
features.approved→ 7.changes→ anoteé a solicitação → 3. Usuário diz que aprovou mas o banco discorda → o clique não foi salvo: informe isso, configure para ele. - Porte imediatamente — o usuário não revisa planos; o padrão dele é o passo 9. Defina
porting; brief porreferences/port-brief.md. Um agente de portabilidade por área de arquivo. Migrações executadas em uma cópia do workspace; em dados ao vivo apenas com aprovação explícita e um backup. - Envie apenas com evidências ao vivo (medições, movimento quadro a quadro, ambos os temas, as larguras do usuário):
shipped+ uma linhachanges+ o que verificar. - Verificado é decisão do usuário — o clique Accept dele, ou ele dizer no chat que este item foi aceito (então você define). Um "parece bem" vago → pergunte quais itens. Nunca por seu próprio julgamento.
Estados, quem os define, o esquema do banco, escritas → references/lifecycle.md. Entregas com brainstorming, escrita de planos, desenvolvimento orientado por subagentes, verificação e finalização de branch → references/superpowers-integration.md.
Segurança na verificação ao vivo
Em um aplicativo ao vivo com dados reais: navegue somente leitura, clique apenas em rótulos exatos, nunca delete/remova/edite lá — qualquer verificação que altere dados deve ser executada em uma cópia do workspace.
Racionalizações
| Pensamento | Realidade |
|---|---|
| "É pequeno / fácil de desfazer" | Tamanho não é o teste; aparência ou operação é. Pequenas mudanças de IU são onde o posicionamento dá errado. |
| "Prazo amanhã" | Uma rodada de demo leva minutos; um posicionamento errado enviado para o demo custa mais. Mantenha a ordem, informe o cronograma. |
| "Vou mostrar capturas de tela e prosseguir a menos que eles se oponham" | Silêncio não é aprovação, e uma captura de tela de uma compilação finalizada não é um demo que eles possam operar. |
| "O lugar certo é óbvio a partir de primeiros princípios" | Nomeie o aplicativo de referência. "Onde os usuários olham" é como o botão não encontrável foi enviado. |
| "Testes, revisão e compilação estão verdes, então está pronto" | Isso é porting concluído. shipped precisa de evidências ao vivo; verified precisa do usuário. |
| "'Parece bem, acho' significa aceito" | Aceitação é por item. Pergunte qual. |
| "Eles vão aprovar de qualquer forma; vou construir adiantado para o prazo" | Código não aprovado é o tipo desperdiçado. Aponte-os para o que está sendo enviado hoje; porte no minuto em que eles aprovarem. |
| "Vou inventar um status mais claro" | Apenas seis estados; a página e o usuário leem esses. |
| "Porte e demo juntos para economizar tempo" | Apenas itens approved recebem código de produto. |
Bandeiras vermelhas — pare
- Abrir um componente de produto antes de o demo mostrar o design.
- Um design sem aplicativo de referência nomeado, ou sem medição da IU real.
shippedsem evidências ao vivo;verifiedsem a palavra do usuário sobre aquele item.- Clicar em Excluir/Remover/Salvar em um aplicativo que contém dados reais.
- Dois agentes de portabilidade nos mesmos arquivos; executar uma migração em dados ao vivo.