Protótipo

Quando Usar

Use quando este fluxo de trabalho corresponder à solicitação do usuário: Crie um protótipo descartável para detalhar um design — um aplicativo de terminal executável para questões de estado/lógica de negócios, ou várias variações de UI radicalmente diferentes que podem ser alternadas a partir de uma única rota.

Fonte: mattpocock/skills (MIT).

Um protótipo é código descartável que responde a uma pergunta. A pergunta decide a forma.

Escolha um ramo

Identifique qual pergunta está sendo respondida — a partir do prompt do usuário, do código circundante ou perguntando se o usuário está por perto:

• "Esta lógica / modelo de estado parece correto?" → LOGIC.md. Crie um pequeno aplicativo de terminal interativo que percorre a máquina de estados através de casos difíceis de raciocinar no papel.
• "Como isso deveria parecer?" → UI.md. Gere várias variações de UI radicalmente diferentes em uma única rota, alternáveis ​​via um parâmetro de pesquisa na URL e uma barra inferior flutuante.

Os dois ramos produzem artefatos muito diferentes — errar nisso desperdiça todo o protótipo. Se a pergunta for genuinamente ambígua e o usuário não estiver acessível, use o ramo que melhor corresponder ao código circundante (um módulo de backend → lógica; uma página ou componente → UI) e declare a suposição no topo do protótipo.

Regras que se aplicam a ambos

1. Descartável desde o primeiro dia, e claramente marcado como tal. Localize o código do protótipo perto de onde ele será realmente usado (ao lado do módulo ou página para o qual está prototipando) para que o contexto seja óbvio — mas nomeie-o para que um leitor casual veja que é um protótipo, não produção. Para rotas de UI descartáveis, siga a convenção de roteamento que o projeto já utiliza; não invente uma nova estrutura de nível superior.
2. Um comando para executar. O que quer que o gerenciador de tarefas existente do projeto suporte — pnpm <name>, python <path>, bun <path>, etc. O usuário deve ser capaz de iniciá-lo sem pensar.
3. Sem persistência por padrão. O estado vive na memória. A persistência é a coisa que o protótipo está verificando, não algo do qual ele deveria depender. Se a pergunta envolver explicitamente um banco de dados, use um banco de dados temporário ou um arquivo local com um nome claro "PROTÓTIPO — apague-me".
4. Pule o polimento. Sem testes, sem tratamento de erros além do que torna o protótipo executável, sem abstrações. O objetivo é aprender algo rápido e depois excluí-lo.
5. Exponha o estado. Após cada ação (lógica) ou a cada troca de variante (UI), imprima ou renderize o estado relevante completo para que o usuário possa ver o que mudou.
6. Exclua ou absorva quando terminar. Quando o protótipo tiver respondido à sua pergunta, exclua-o ou incorpore a decisão validada ao código real — não o deixe apodrecendo no repositório.

Quando terminar

A resposta é a única coisa que vale a pena manter de um protótipo. Capture-a em algum lugar durável (mensagem de commit, ADR, issue ou um NOTES.md ao lado do protótipo) junto com a pergunta que ele estava respondendo. Se o usuário estiver por perto, essa captura é uma conversa rápida; se não, deixe o espaço reservado para que ele (ou você, na próxima vez) possa preencher o veredito antes de excluir o protótipo.

Limitações

• Requer a ferramenta upstream, conta, chave de API ou configuração local quando o fluxo de trabalho nomeia um.
• Não autoriza ações destrutivas, de produção, pagas ou de mensagens externas sem aprovação explícita do usuário.
• Valide artefatos gerados ou recomendações contra as fontes reais do usuário antes de tratá-los como finais.