GanDaicheng/vibecoding-workflow

Fluxo de Trabalho Vibe Coding

Ajuda programadores iniciantes a levar projetos Web pequenos da ideia a resultados verificáveis. Discuta decisões de produto na linguagem que o usuário entende; ajuste o processo conforme o tamanho da tarefa. Este Skill é um método de trabalho, não pressupõe framework, banco de dados ou plataforma de deployment.

A primeira versão concentra-se em páginas públicas simples. Login, gerenciamento interno, upload de arquivos, pagamento e tratamento de dados sensíveis estão fora deste escopo simplificado; quando esses requisitos surgirem, primeiro aponte a necessidade de novas decisões de produto, dados, permissões e deployment, e então planeje de acordo com o escopo estendido confirmado pelo usuário, sem incorporá-los silenciosamente no roteiro original.

Entrada: Primeiro, direcione e determine o destino e o estado atual

1. A partir do que o usuário já disse, extraia objetivos, restrições e autoridade, e determine se é uma pequena alteração clara, um novo projeto ou uma funcionalidade de várias etapas em um projeto existente. Pequenas alterações seguem o caminho rápido; novos projetos e funcionalidades de várias etapas seguem o caminho completo.
2. Se o caminho completo ainda não especificou o destino de entrega, pergunte ao usuário o que ele deseja: apenas esboçar a solução, executável localmente, pronto para deployment ou lançamento oficial. Pequenas alterações só perguntam se a forma de entrega afetar a tarefa. O trabalho subsequente avança apenas até o nível que o usuário escolheu ou autorizou explicitamente.
3. Para projetos existentes, leia primeiro a descrição do repositório, AGENTS.md (se houver), código relevante, métodos de execução e verificação, documentos de planejamento existentes e o status do Git. Identifique alterações não commitadas do usuário, não as sobrescreva nem misture com seus próprios commits. Para diretórios vazios, confirme primeiro o produto a ser feito e os recursos existentes.
4. Com um breve resumo, liste os fatos conhecidos, decisões de produto ainda pendentes e recomendações atuais. Priorize fazer apenas uma pergunta por rodada que mais impacte o próximo passo; combine várias perguntas apenas quando as decisões estiverem intimamente relacionadas e o usuário desejar responder em lote. Detalhes de baixo impacto podem ser registrados como suposições claramente identificadas.

Caminho Completo: Primeiro, determine o produto; depois, escolha a forma de implementação

1. Determinar o produto da primeira versão

• Esclareça os usuários-alvo, o problema a ser resolvido, os critérios de sucesso da primeira versão e as restrições. Organize as principais histórias de usuário por papel, selecione o caminho principal P0 e registre P1/P2 e o que não será feito. Evite adicionar todos os recursos sugeridos pela IA na primeira versão.
• A partir das histórias, derive páginas, navegação, operações principais e os estados necessários (vazio, carregamento, sucesso, falha). Permita que o usuário descreva, em um cenário real, as etapas desde a entrada no site até a conclusão do objetivo.
• Converta metas vagas como "bom uso" e "completo" em comportamentos observáveis. Se as histórias ou prioridades entrarem em conflito, aponte o conflito primeiro.
• Mantenha uma correspondência breve: a página ou comportamento correspondente a cada história P0, a fatia de desenvolvimento e o método de aceitação. Antes de finalizar o planejamento, verifique se todas as histórias P0 têm uma fatia correspondente, para evitar que funcionalidades principais sejam omitidas.

2. Fornecer recomendações técnicas, de dados e de deployment

• Para projetos existentes, priorize o uso de tecnologias e convenções razoáveis já existentes. Para novos projetos, primeiro entenda o que o usuário conhece; se não houver preferência, recomende uma combinação que atenda aos requisitos da primeira versão e seja fácil de desenvolver, implantar e manter. Explique os motivos da recomendação e os principais custos; mostre alternativas apenas se o usuário solicitar uma comparação.
• Primeiro pergunte quais conteúdos precisam ser salvos, atualizados, compartilhados ou lidos em diferentes dispositivos, depois decida se um banco de dados é necessário. Se o conteúdo estático atender à primeira versão, escreva explicitamente que não há necessidade de banco de dados. Se a persistência for realmente necessária, explique as entidades de dados, relacionamentos, caminhos de leitura/escrita, impacto da perda de dados e método de migração; não adicione backend ou sistema de contas do nada.
• De acordo com o destino de entrega, considere com antecedência o ambiente de execução, localização dos dados, variáveis de ambiente, custos, domínio, método de construção e rollback. Quando envolver versões atuais, compatibilidade, recursos da plataforma ou preços, verifique fontes oficiais e anote a base e a incerteza.
• Faça o usuário confirmar decisões que alteram custos, dados, arquitetura ou manutenção futura. Não faça iniciantes adivinharem nomes de frameworks, produtos de banco de dados ou nomes de campos de tabelas.

3. Iniciar o trabalho após confirmar o roteiro

• Divida o trabalho em fatias de ponta a ponta que o usuário possa ver o resultado; cada fatia deve ter objetivo, escopo, dependências, comportamento de aceitação e método de verificação claros. A primeira fatia deve priorizar percorrer o caminho mais importante.
• Antes de começar a modificar arquivos em um novo projeto, mostre o escopo do produto, as principais decisões técnicas e a primeira fatia. Se o usuário ainda não confirmou essas decisões, obtenha a confirmação primeiro; se o usuário já confirmou e autorizou explicitamente o início, continue diretamente sem perguntar novamente. Detalhes de implementação comuns são tratados pelo Codex; alterações no escopo, arquitetura ou decisões de alto impacto exigem realinhamento.
• Se o usuário deseja apenas uma solução, pare na solução ou no documento de planejamento solicitado. Não transforme uma solicitação de planejamento automaticamente em codificação ou lançamento.

Caminho Rápido: Pequenas alterações claras

Verifique o código relevante e o estado do espaço de trabalho, descreva em uma frase o comportamento esperado e o método de aceitação, conclua a alteração de escopo limitado e verifique. Se o usuário solicitar apenas etapas ou solução, explique também como a alteração real será verificada e diferencie as verificações planejadas das já executadas. Só mude para o caminho completo quando o requisito realmente envolver vários módulos, estrutura de dados, arquitetura ou forma de deployment. Não crie novos documentos de produto ou frameworks de teste para pequenas alterações.

Ciclo de cada fatia de desenvolvimento

1. Antes de começar, releia a fatia atual, o código-fonte relevante e as convenções do projeto, confirme que não há alterações do usuário que serão sobrescritas no espaço de trabalho. Use o Git local para pontos de verificação que podem ser revertidos; se ainda não houver repositório, crie um local antes de começar a implementação. Não faça commits de alterações não relacionadas ao usuário; configure repositórios remotos conforme necessário.
2. Ao desenvolver novas funcionalidades, crie um branch de funcionalidade a partir do branch principal ou do branch de integração existente do projeto, implemente e faça commits nesse branch. Primeiro, trate as alterações não commitadas do usuário no espaço de trabalho, evitando carregá-las para o branch de funcionalidade ou resultado do merge. Pequenas correções claras podem decidir se criam branch ou não, conforme o hábito do projeto.
3. Implemente a fatia atual sem expandir o escopo. Se encontrar comportamento de produto não decidido, alterações que afetam dados ou dependências que se desviam claramente do plano original, explique o impacto e atualize o plano.
4. Execute testes existentes, builds, verificações de inicialização ou aceitação de operações de página de acordo com o risco. Para caminhos críticos, adicione testes automatizados que agreguem valor; para alterações simples, use etapas manuais claras. Se a verificação falhar, diagnostique, corrija e reexamine; não declare como aprovado o que não foi executado.
5. Compare os resultados reais com as condições de aceitação da fatia atual e das histórias P0 relacionadas; itens não atendidos devem ser marcados como pendentes. Verifique o escopo das alterações, atualize a documentação necessária do projeto e os pontos de verificação Git locais.
6. Depois que a aceitação e verificação do branch de funcionalidade forem aprovadas, confirme o estado do branch principal de destino antes de fazer o merge. Se houver conflitos ou o branch principal tiver mudado durante o desenvolvimento, resolva e reexecute as verificações relevantes no resultado do merge; se falhar, mantenha o estado pendente de merge e relate o motivo, não marque resultados não verificados como concluídos. Conclua esta fatia antes de passar para a próxima.

Registro e Recuperação do Projeto

• Deixe as decisões-chave confirmadas na pasta docs/ do projeto. Para novos projetos, normalmente use docs/PROJECT.md para registrar fatos do produto, escopo da primeira versão e escolhas importantes, e docs/ROADMAP.md para registrar fatias e progresso; se as soluções técnicas e de dados forem complexas, mantenha documentos de arquitetura separadamente. Adicione um arquivo de especificação apenas quando uma funcionalidade específica realmente precisar de especificação de aceitação independente.
• Mantenha um único local principal para cada fato. Em projetos existentes, priorize a atualização de sua estrutura de documentação existente, evitando criar novos arquivos com conteúdo duplicado. Ao retomar o trabalho, leia primeiro os registros do projeto e depois verifique com o código atual; aponte as diferenças quando a documentação e o código estiverem inconsistentes.
• Quando o usuário alterar os requisitos, explique as histórias, páginas, dados, tecnologia ou marcos afetados; atualize os registros correspondentes e as fatias não concluídas, não sobrescreva silenciosamente decisões antigas.

Lançamento e Conclusão

Finalize de acordo com o destino de entrega escolhido inicialmente pelo usuário. Se o deployment for necessário, prepare primeiro a construção, exemplos de variáveis de ambiente, migração de dados, verificação do ambiente de produção e etapas de rollback; antes de criar recursos reais, incorrer em custos ou fazer o lançamento oficial, explique as operações específicas e obtenha a confirmação correspondente. Não escreva chaves reais no código, documentação ou registros de commit.

Na entrega, use uma breve lista de verificação: o que foi concluído, como executar, quais verificações foram realmente feitas e seus resultados, limitações restantes e próximos passos. Partes que não podem ser executadas ou verificadas devem ser claramente identificadas.