Vibe Coding Toolkit
Da ideia ao projeto preparado. Do código existente a uma base que evolui.
Um toolkit de documentação, prompts e templates para desenvolver com agentes de IA: preparar a máquina, iniciar uma aplicação, melhorar um projeto existente e manter contexto e qualidade durante o trabalho.
Você descreve o objetivo. O agente inspeciona o ambiente, organiza as decisões, configura as peças aplicáveis e verifica o resultado. O código fica no seu projeto; este repositório guarda a receita.
INICIAR UM PROJETO → · PREPARAR A MÁQUINA · CONFIGURAR PROJETO EXISTENTE · EXPLORAR O TOOLKIT
MIT
·
Star History
·
Evidências e limites
Claude Code + Codex / instruções portáveis / skills locais
Next.js para projetos novos / sua stack preservada em projetos existentes
00 / Escolha onde começar
| Seu momento | Caminho | O que você recebe |
|---|---|---|
| Tenho uma ideia | Iniciar um projeto Next.js · Prompt 11 | Produto definido, base oficial, documentação, skills e checks |
| Já tenho um projeto | Configurar ou atualizar a base | Diagnóstico, brainstorming, harness, ferramentas e melhorias verificadas |
| Preciso preparar a máquina | Setup do ambiente · Prompt 10 | Runtime, agentes, integrações globais, backups e manifesto |
| Quero resolver uma necessidade | Instalação modular · Prompts | Lint, refatoração, revisão, contexto ou uma ferramenta específica |
Durante a leitura: Preparação · Agentes · Conhecimento · Qualidade · Prompts · Documentação · Comunidade.
O agente precisa conseguir ler arquivos, editar e executar comandos. Os guias tratam Claude Code e Codex separadamente; outros clientes podem seguir os acordos com capacidades equivalentes. Conversa sem acesso ao ambiente explica o processo, mas não comprova instalações ou testes.
01 / Prepare uma base que combina com o projeto
O setup começa pelo que existe: produto, arquivos, runtime, gerenciador, instruções e ferramentas disponíveis. Projetos novos recebem uma base coerente; projetos existentes recebem uma adoção compatível com seus contratos.
Comece um projeto com duas linhas
Abra o agente no diretório de destino e cole. Troque a segunda linha pela descrição do seu produto:
Leia https://raw.githubusercontent.com/soumatheusgomes/vibe-coding-toolkit/main/docs/prompts/11-next-project-bootstrap.md e execute o setup neste diretório.
Projeto: [nome, problema, público, fluxos principais e restrições].
Exemplo: “CRM para pequenas imobiliárias. Corretores registram contatos, negócios e tarefas; gestores acompanham o funil por equipe. Interface em português, MVP focado em cadastro e acompanhamento de oportunidades.”
| Parte da entrega | Conteúdo |
|---|---|
| Produto | PRODUCT.md: problema, público, MVP, restrições, hipóteses e critérios de aceitação |
| Aplicação | Base oficial Next.js, App Router, TypeScript, Tailwind e ESLint |
| Servidor e dados | Drizzle/PostgreSQL para persistência nova, Zod, Pino e fronteiras de servidor |
| Testes e qualidade | Vitest, regras locais, scripts canônicos e validação da base |
| Agentes | Instruções compartilhadas, integração por cliente e skills Vercel locais |
| Documentação | Quatro arquivos na raiz e cinco documentos em docs/, com fontes e evidências |
O bootstrap termina com a base configurada e a próxima tarefa do MVP identificada. Autenticação, serviços e funcionalidades entram conforme o produto. Uma aplicação sem persistência pode omitir banco com justificativa. Os defaults são revistos com fontes atuais na execução.
Configure ou atualize um projeto existente
Abra o agente na raiz da aplicação e cole:
Leia https://raw.githubusercontent.com/soumatheusgomes/vibe-coding-toolkit/main/docs/prompts/12-existing-project-setup.md e execute integralmente o bloco da seção “Prompt” neste projeto, começando pelo brainstorming.
O prompt atende uma base sem toolkit, uma adoção parcial ou uma configuração antiga. O trabalho segue este percurso:
- Conhecer: inspecionar produto, stack, instruções, dependências, integrações e checks atuais.
- Decidir: fazer brainstorming e apresentar melhorias, riscos, dependências e critérios de conclusão.
- Configurar: instalar, atualizar, integrar ou reaproveitar cada peça aplicável do catálogo.
- Melhorar: conciliar documentação e regras; organizar código com mudanças incrementais verificáveis.
- Comprovar: comparar antes/depois, testar integrações disponíveis e registrar limites e pendências.
Repetir o prompt é parte da manutenção. Ele confere a revisão do toolkit e a documentação atual, preserva personalizações e evita duplicar instruções, skills, hooks ou servidores MCP. Stack, banco e contratos existentes são preservados; migrações incompatíveis recebem uma decisão própria.
Prepare a máquina
Leia https://raw.githubusercontent.com/soumatheusgomes/vibe-coding-toolkit/main/docs/prompts/10-development-environment-setup.md e execute integralmente o bloco da seção “Prompt” neste computador.
O setup global cuida de ferramentas de sistema, Node.js, Docker, agentes, plugins e integrações. Registra versões, escopos, backups, validações e intervenções necessárias. O setup de projeto reutiliza esse ambiente.
Cole os textos na conversa de um agente com terminal. Os atalhos remotos usam a versão publicada em
main; em uma cópia ainda não publicada, use o arquivo local. Nenhum setup publica automaticamente sua aplicação.
02 / Dê direção ao trabalho dos agentes
Entender → desenhar → planejar quando necessário → implementar → verificar → revisar. Cada etapa existe para tornar o resultado mais previsível. O processo acompanha o tamanho do pedido e a autorização vigente.
| Função | Ferramentas e acordos | Quando entram |
|---|---|---|
| Entender e decidir | Superpowers | Brainstorming, desenho proporcional, planejamento, diagnóstico e verificação |
| Construir com escopo | Ponytail full | Reutilizar o que existe e entregar a menor mudança completa |
| Conversar com clareza | Caveman | Respostas concisas; código, documentação e commits com redação normal |
| Delegar com responsabilidade | Subagentes e ondas | Contexto isolável, especialização útil e tarefas independentes |
| Reduzir saída repetitiva | RTK | Comandos suportados, preservando acesso à saída original |
| Configurar cada cliente | Codex · Playbook Claude | Instruções, descoberta de skills, MCPs e hooks no formato correto |
Capacidade escolhida por tarefa
Com seleção de modelos autorizada, a LLM escolhe entre os modelos e esforços realmente disponíveis. Busca, inventário e mudanças mecânicas favorecem capacidade leve; decisões ambíguas, segurança, dados e revisão crítica recebem capacidade suficiente para o risco.
O prompt de projeto existente autoriza essa seleção dentro do cliente e autenticação vigentes, respeitando restrições explícitas. Sem essa política, preserve o modelo da sessão. Disponibilidade de ferramenta não autoriza trocar provedor, ativar proxy ou criar cobrança por API.
Paralelo quando o trabalho permite
- Cada tarefa tem objetivo, contexto mínimo, arquivos permitidos, dependências, aceite e checks.
- Um escritor por arquivo; lockfiles e configurações compartilhadas têm responsável único.
- Revisores paralelos trabalham em leitura. O coordenador confere o diff e a integração.
- Falhas pedem diagnóstico e possível escalonamento, com limites de tempo e tentativas.
- A retomada verifica arquivos, checkout e processos reais. Um resumo anterior não prova o estado atual.
Mudanças pequenas podem ficar no agente principal. O protocolo de orquestração detalha critérios, recuperação e concorrência.
03 / Faça o conhecimento sobreviver à sessão
Harness engineering organiza o ambiente no qual o agente trabalha: instruções localizáveis, contexto confiável, ferramentas acessíveis, comandos reproduzíveis e feedback verificável. O projeto guarda o que o próximo agente precisa para continuar.
| Necessidade | Peça do toolkit | Resultado esperado |
|---|---|---|
| Saber por onde começar | AGENTS compartilhado e ponte Claude | Comandos e restrições curtos, apontando para os detalhes |
| Consultar APIs atuais | Context7 | Documentação da biblioteca e versão relevantes, sem enviar segredos |
| Entender relações no código | Graphify | Grafo consultável com cobertura, atualidade e limites registrados |
| Guardar decisões úteis | Memória do cliente · Obsidian opcional | Índice enxuto e conhecimento detalhado sob demanda |
| Usar especialização existente | Skills Vercel · Skills de artefatos | Instruções pertinentes à tarefa e ao cliente, descobertas e verificadas |
Cada documento tem uma função
O manifesto de documentos liga os templates aos nove destinos do bootstrap:
seu-projeto/
├── README.md Como entrar e executar
├── PRODUCT.md Problema, escopo e aceite
├── AGENTS.md Comandos e acordos compartilhados
├── CLAUDE.md Ponte para as instruções compartilhadas
└── docs/
├── architecture.md Estrutura, fronteiras e decisões
├── design.md Direção visual e acessibilidade
├── onboarding.md Preparação local e primeiro fluxo
├── quality.md Checks, revisão e limites
└── setup.md Fontes, versões, evidências e pendências
Em projeto existente, preserve documentos equivalentes já canônicos e registre o mapeamento. Mudar comportamento, comando, schema ou configuração também atualiza o documento responsável. Detalhes ficam na fonte correta, sem transformar AGENTS.md em uma enciclopédia.
Skills disponíveis, ações sob demanda
Para Next/React, o catálogo Vercel cobre boas práticas, composição, UI, escrita, transições, otimização e operações Vercel, além de find-skills. React Native/Expo entra conforme a plataforma. Os nomes vêm do SKILL.md e são conferidos no upstream durante o setup.
Instalar uma skill de deploy não publica. Instalar uma skill de transições não exige animações. Skills, MCPs e memória externa entram no fluxo quando existe tarefa pertinente e autorização.
04 / Troque “parece pronto” por evidência
O toolkit separa arquivo presente, configuração concluída e integração testada. Cada check prova uma parte do resultado; pendências e falhas preexistentes continuam visíveis.
| Frente | Como verificar | Referência |
|---|---|---|
| Estrutura e fronteiras | Presets do framework, regras locais, teto de 350 linhas e imports ajustados à base | ESLint e quality gates |
| Comportamento | Tipos, testes relevantes, regressões, tratamento de erros e build | Padrões do projeto |
| Interface em uso | Navegação local, teclado, foco, estados, console, rede e desempenho quando pertinente | agent-browser · Chrome DevTools MCP |
| Integrações do agente | Descoberta real de skills, consulta ao Context7, RTK sem duplicação e grafo pertinente | Setup de projeto existente |
| O próprio toolkit | Links, âncoras, manifesto, JSON e base Next em projeto temporário | Validação reproduzível |
Regras novas em código legado recebem medição e adoção progressiva. Proteções existentes não são enfraquecidas para obter um relatório verde. O perfil de lint acompanha a stack; instalar regras não justifica trocar ORM ou introduzir dependências sem uso.
Revisão depois de implementar ou corrigir
As instruções compartilhadas recomendam 3 a 8 ciclos posteriores de code review. A LLM escolhe quantidade e focos pelo tamanho, risco e incerteza da mudança e entrega um prompt de continuação.
Os ciclos podem cobrir comportamento, regressões, segurança, dados, acessibilidade e integração. Cada um inspeciona o estado atual, registra achados e verifica correções autorizadas. A contagem não reinicia a cada correção interna. Essa faixa é uma convenção do toolkit; não garante ausência de bugs nem inicia novas rodadas automaticamente.
Evidências e limites
A base possui validação documentada em macOS, Linux e Windows, com checks automatizados também em Ubuntu e Windows. O relatório distingue testes de fronteiras, SQL, build, HTTP e integrações reais, além de registrar advisories e limites conhecidos. Instalação em outro ambiente precisa de verificação própria.
Checks são explícitos. O toolkit não instala bloqueios de push em main, não exige branch/worktree e não acrescenta hooks de commit/push. Hooks do cliente usam integrações suportadas e verificadas, sem duplicação.
05 / Uma biblioteca de prompts por objetivo
Escolha a tarefa, abra o prompt e copie o bloco indicado. O catálogo completo reúne instruções de uso e adaptação.
| Objetivo | Prompts | Quando usar |
|---|---|---|
| Preparar tudo | 10 · Máquina · 11 · Projeto novo · 12 · Projeto existente | Instalação inicial, adoção completa ou atualização |
| Entender e planejar | 04 · Brainstorm até plano | Transformar pedido ambíguo em trabalho com aceite |
| Organizar a base | 01 · Sanitização · 09 · Arquivos grandes | Medir problemas e refatorar por responsabilidade |
| Evoluir o lint | 07 · ESLint completo · 08 · Quality gates · 02 · Warnings | Instalar regras, medir legado e reduzir violações |
| Revisar e coordenar | 03 · Code review · 05 · Ondas paralelas | Revisão especializada e execução independente |
| Manter contexto | 06 · Memória | Guardar conhecimento útil sem inflar a sessão |
Adote uma peça por vez
Para instalar somente os quality gates:
Leia https://raw.githubusercontent.com/soumatheusgomes/vibe-coding-toolkit/main/docs/prompts/08-eslint-quality-gates-install.md e execute o prompt neste projeto. Use MAX_LINES=350.
Depois da medição, o prompt 09 orienta refatoração de arquivos grandes. Para apenas skills Vercel, use o catálogo e a instalação local. A adoção modular continua disponível sem executar o setup inteiro.
06 / Entenda o que pertence a cada lugar
Global e local
| Máquina e cliente | Projeto |
|---|---|
| Runtime, Git e gerenciador de pacotes | Dependências da aplicação e lockfile |
| Agente, autenticação e plugins existentes | Produto, instruções e documentação específica |
| RTK e integração funcional | Skills locais e skills-lock.json |
| Ponytail, Caveman e Superpowers já disponíveis | Regras de qualidade e comandos canônicos |
| CLI Graphify e conexão Context7 existente | Exclusões do grafo e configuração local quando necessária |
Claude Code e Codex têm descoberta e configurações próprias. Uma integração global funcional é reutilizada; conteúdo pessoal e credenciais não são copiados para templates. Instalação e atualização usam o menor escopo suportado, com limites de autorização explícitos.
Stack de partida e compatibilidade
| Contexto | Como o toolkit se adapta |
|---|---|
| Projeto web novo | Next.js estável, App Router, TypeScript, Tailwind, ESLint, Vitest e núcleo servidor conforme o produto |
| Projeto existente | Preserva framework, gerenciador, banco, ORM, testes e equivalentes funcionais; mede antes de mudar |
| Monorepo | Identifica workspaces, fronteiras e configurações compartilhadas antes de escolher alvos |
| Outro cliente ou stack | Usa capacidades e formatos compatíveis; registra componentes inaplicáveis e bloqueios |
| Sem credenciais ou serviços | Executa checks seguros e independentes; distingue configuração de integração real |
O toolkit não é um gerador próprio nem uma aplicação pronta. O scaffold novo vem de create-next-app; os templates complementam a base. Versões e APIs são conferidas durante o setup. Publicação, serviços pagos e migrações incompatíveis dependem da autorização pertinente.
07 / Explore a documentação
vibe-coding-toolkit/
├── README.md Você está aqui
├── docs/ Guias, padrões e evidências
│ ├── tools/ Ferramentas por função
│ └── prompts/ Receitas copiáveis
├── templates/ Arquivos para adaptar no destino
└── scripts/ Validação do próprio toolkit
Guias
| Documento | Para quê |
|---|---|
| Visão geral | Princípios e caminhos de adoção |
| Instalação | Comandos, distribuição e escopos |
| Playbook Claude | Fluxo narrado de trabalho dentro do projeto |
| Setup da máquina | Preparação, retomada e reprodução do ambiente |
| Bootstrap Next | Produto até base configurada |
| Projeto existente | Adoção completa, atualização e harness |
| Validação do toolkit | O que foi comprovado e quais limites permanecem |
| Padrões do projeto | Stack, documentação e critérios de adaptação |
Ferramentas
As 16 referências estão distribuídas pelos blocos funcionais desta página. O catálogo de ferramentas mantém o índice completo e os links de instalação.
Templates
O catálogo de templates reúne documentação, núcleo Next, perfis ESLint, configurações Context7 por cliente, exclusões Graphify e exemplos de hooks. Copie e adapte apenas os arquivos usados; valide no destino. O manifesto é a referência para os documentos gerados.
Verifique esta cópia
node scripts/validate-docs.mjs node scripts/validate-next.mjs
O primeiro comando confere links, âncoras, destinos e JSON. O segundo exige Node.js 24, npm e rede; cria um projeto temporário, executa os checks da base e remove os recursos criados. Dependências do produto não entram na raiz deste repositório. Veja escopo e evidências antes de interpretar os resultados.
08 / Acompanhe a evolução
Se o toolkit ajudou a preparar um projeto ou melhorar seu fluxo, uma estrela facilita encontrá-lo novamente e dá visibilidade ao trabalho.
Abrir o histórico de estrelas · Reportar um problema · Propor uma melhoria
O gráfico é fornecido pelo Star History e depende da disponibilidade desse serviço. Para contribuir, descreva o problema, preserve caminhos públicos e inclua validação pertinente. Prompts e templates precisam continuar portáveis, sem segredos ou configurações pessoais.
Créditos e licença
Construído a partir de Superpowers, RTK, Ponytail, Caveman, Graphify, Context7, agent-browser, Vercel Agent Skills e Skills CLI. Cada projeto mantém sua licença e distribuição.
Toolkit sob MIT. Por Matheus Gomes.
BUILD WITH INTENT. SHIP WITH FLOW.
Voltar ao topo ↑