Da Ideia ao Design
Transforme ideias em designs e especificações totalmente formados através de um diálogo colaborativo natural.
Comece entendendo o contexto atual do projeto, depois faça perguntas uma de cada vez para refinar a ideia. Assim que você entender o que está sendo construído, apresente o design e obtenha a aprovação do usuário.
Anti-Padrão: "Isso é Simples Demais Para Precisar de um Design"
Todo projeto passa por este processo. Uma lista de tarefas, um utilitário de função única, uma alteração de configuração — todos eles. Projetos "simples" são onde suposições não examinadas causam mais trabalho desperdiçado. O design pode ser curto (algumas frases para projetos verdadeiramente simples), mas você DEVE apresentá-lo e obter aprovação.
Lista de Verificação
Você DEVE criar uma tarefa para cada um destes itens e completá-los em ordem:
- Explorar o contexto do projeto — verificar arquivos, docs, commits recentes
- Fazer perguntas esclarecedoras — uma de cada vez, entender propósito/restrições/critérios de sucesso
- Propor 2-3 abordagens — com trade-offs e sua recomendação
- Apresentar o design — em seções escaladas para sua complexidade, obter aprovação do usuário após cada seção
- Escrever o documento de design — salvar em
docs/superpowers/specs/YYYY-MM-DD-<topic>-design.mde commitar - Auto-revisão da especificação — verificação rápida inline para placeholders, contradições, ambiguidade, escopo
- Usuário revisa a especificação escrita — pedir ao usuário para revisar o arquivo de especificação antes de prosseguir
- Transição para implementação — invocar a skill writing-plans para criar o plano de implementação
Fluxo do Processo
flowchart TD
A[Explorar contexto do projeto] --> B[Fazer perguntas esclarecedoras]
B --> C[Propor 2-3 abordagens]
C --> D[Apresentar seções do design]
D --> E{Usuário aprova o design?}
E -- não, revisar --> D
E -- sim --> F[Escrever documento de design]
F --> G[Auto-revisão da especificação<br/>corrigir inline]
G --> H{Usuário revisa a especificação?}
H -- alterações solicitadas --> F
H -- aprovado --> I[Invocar skill writing-plans]
O estado terminal é invocar a skill writing-plans. NÃO invoque nenhuma skill de implementação. A ÚNICA skill que você invoca depois disso é writing-plans.
O Processo
Entendendo a ideia:
- Verifique o estado atual do projeto primeiro (arquivos, docs, commits recentes)
- Antes de fazer perguntas detalhadas, avalie o escopo: se a solicitação descreve múltiplos subsistemas independentes (ex.: "construa uma plataforma com chat, armazenamento de arquivos, faturamento e análises"), sinalize isso imediatamente. Não gaste perguntas refinando detalhes de um projeto que precisa ser decomposto primeiro.
- Se o projeto for grande demais para uma única especificação, ajude o usuário a decompô-lo em subprojetos: quais são as peças independentes, como elas se relacionam, em que ordem devem ser construídas? Em seguida, projete o primeiro subprojeto através do fluxo normal. Cada subprojeto obtém seu próprio ciclo de especificação → plano → implementação.
- Para projetos com escopo apropriado, faça perguntas uma de cada vez para refinar a ideia
- Prefira perguntas de múltipla escolha quando possível, mas perguntas abertas também são boas
- Apenas uma pergunta por mensagem — se um tópico precisar de mais exploração, divida-o em várias perguntas
- Foco em entender: propósito, restrições, critérios de sucesso
Explorando abordagens:
- Proponha 2-3 abordagens diferentes com trade-offs
- Apresente opções de forma conversacional com sua recomendação e justificativa
- Lidere com sua opção recomendada e explique por quê
Apresentando o design:
- Assim que você acreditar que entende o que está sendo construído, apresente o design
- Escale cada seção para sua complexidade: algumas frases se for direto, até 200-300 palavras se for cheio de nuances
- Pergunte após cada seção se parece correto até o momento
- Cubra: arquitetura, componentes, fluxo de dados, tratamento de erros, testes
- Esteja pronto para voltar e esclarecer se algo não fizer sentido
Design para isolamento e clareza:
- Divida o sistema em unidades menores que cada uma tenha um propósito claro, se comuniquem através de interfaces bem definidas, e possam ser entendidas e testadas independentemente
- Para cada unidade, você deve ser capaz de responder: o que ela faz, como usá-la, e do que ela depende?
- Alguém pode entender o que uma unidade faz sem ler seus internos? Você pode alterar os internos sem quebrar consumidores? Se não, os limites precisam de trabalho.
- Unidades menores e bem delimitadas também são mais fáceis de trabalhar para você — você raciocina melhor sobre código que pode manter em contexto de uma vez, e suas edições são mais confiáveis quando os arquivos são focados. Quando um arquivo cresce muito, isso é frequentemente um sinal de que está fazendo demais.
Trabalhando em bases de código existentes:
- Explore a estrutura atual antes de propor alterações. Siga os padrões existentes.
- Onde o código existente tem problemas que afetam o trabalho (ex.: um arquivo que cresceu demais, limites pouco claros, responsabilidades emaranhadas), inclua melhorias direcionadas como parte do design — a maneira como um bom desenvolvedor melhora o código em que trabalha.
- Não proponha refatoração não relacionada. Mantenha o foco no que serve ao objetivo atual.
Após o Design
Documentação:
- Escreva o design validado (especificação) em
docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md- (Preferências do usuário para localização da especificação substituem este padrão)
- Commite o documento de design no git
Auto-Revisão da Especificação: Após escrever o documento de especificação, veja-o com olhos frescos:
- Varredura de placeholders: Algum "TBD", "TODO", seções incompletas, ou requisitos vagos? Corrija-os.
- Consistência interna: Alguma seção contradiz outra? A arquitetura corresponde às descrições de funcionalidades?
- Verificação de escopo: Isso é focado o suficiente para um único plano de implementação, ou precisa de decomposição?
- Verificação de ambiguidade: Algum requisito poderia ser interpretado de duas maneiras diferentes? Se sim, escolha uma e torne-a explícita.
Corrija quaisquer problemas inline. Sem necessidade de re-revisão — apenas corrija e siga em frente.
Portão de Revisão do Usuário: Após o loop de revisão da especificação passar, peça ao usuário para revisar a especificação escrita antes de prosseguir:
"Especificação escrita e commitada em
<caminho>. Por favor, revise-a e me avise se quiser fazer alguma alteração antes de começarmos a escrever o plano de implementação."
Aguarde a resposta do usuário. Se eles solicitarem alterações, faça-as e reexecute o loop de revisão da especificação. Prossiga apenas quando o usuário aprovar.
Implementação:
- Invoque a skill writing-plans para criar um plano de implementação detalhado
- NÃO invoque nenhuma outra skill. writing-plans é o próximo passo.
Princípios Chave
- Uma pergunta de cada vez — Não sobrecarregue com múltiplas perguntas
- Múltipla escolha preferida — Mais fácil de responder do que perguntas abertas quando possível
- YAGNI impiedosamente — Remova funcionalidades desnecessárias de todos os designs
- Explore alternativas — Sempre proponha 2-3 abordagens antes de decidir
- Validação incremental — Apresente o design, obtenha aprovação antes de prosseguir
- Seja flexível — Volte e esclareça quando algo não fizer sentido
O que foi removido da skill upstream
A skill brainstorming original (obra/superpowers) incluía um recurso "Companheiro Visual": um servidor Node.js para navegador (scripts/server.cjs, scripts/start-server.sh, scripts/stop-server.sh) para mostrar mockups em uma aba do navegador durante o brainstorming. O SkillSpector bloqueou a skill por abuso de parâmetros de ferramenta em stop-server.sh.
Esta porta remove o Companheiro Visual completamente. A metodologia principal — diálogo de design colaborativo, hard gate, auto-revisão da especificação, portão de revisão do usuário, transição para writing-plans — é pura orientação de processo sem scripts, sem shells e sem servidor externo. É segura por construção.
Se você precisar mostrar mockups ou diagramas durante uma conversa de design, use as ferramentas nativas do agente (as ferramentas MCP do navegador, geração de imagens, ou diagramas Mermaid/ASCII inline no chat) em vez de um servidor empacotado.