🏄♂️ SpecKit Vibe Coder
A Constituição do Projeto — o documento que o seu time assina antes de escrever a primeira linha de código.
📺 Aula Gratuita
Aprenda a utilizar este repositório e domine o framework SpecKit através da nossa aula completa e gratuita.
👉 ASSISTIR AULA AGORA - COMUNIDADE PROMOVAWEB
O conteúdo é gratuito. Basta se cadastrar para acessar.
🤔 Qual o problema que isso resolve?
Todo projeto começa cheio de energia e termina cheio de medo.
Medo de mudar o código. Medo de adicionar uma feature nova. Medo de que aquela função misteriosa que "sempre funcionou" pare de funcionar se alguém encostar nela.
Isso acontece porque as decisões técnicas foram tomadas no meio do caminho — individualmente, sem alinhamento e geralmente às pressas para resolver o problema do dia.
O SpecKit Vibe Coder existe para mudar isso. É um guia de perguntas técnicas que o time responde antes de começar a codar. Não é documentação de código. É um contrato de convivência técnica: onde cada coisa fica, como os problemas são resolvidos, o que é aceitável e o que não é.
Uma sessão de 1 hora agora economiza semanas de refatoração no futuro.
📋 O que está coberto
O documento percorre 15 seções, cada uma com perguntas diretas, contexto educativo e as duas opções mais comuns de resposta com suas vantagens e desvantagens:
| # | Seção | O que você decide aqui |
|---|
| 1 | 🏗️ A Planta da Casa | Arquitetura, organização de pastas, padrões de código, integrações |
| 2 | 💾 O Baú do Tesouro | Banco de dados, normalização, índices, ORM, transações |
| 3 | ⚡ A Velocidade da Luz | Cache, filas, performance, busca, otimização |
| 4 | 🔒 Os Seguranças da Balada | Autenticação, autorização, 2FA, senhas, CSRF, recuperação de conta |
| 5 | 🎨 A Cara do App | Front-end, plataforma, SPA vs SSR, REST vs GraphQL, estado global |
| 6 | 🚨 Quando a Casa Cai | Logs, alertas, monitoramento, tratamento de erros |
| 7 | 🤝 Trabalho em Equipe | Git, CI/CD, deploy, ambientes, backup, Definition of Done |
| 8 | 🧪 Testes e Garantia da Vibe | Testes automatizados, code review, linting, feature flags |
| 9 | ☁️ Nuvem, Arquivos e Infra | Storage, Docker, monolito vs microsserviços, dependências |
| 10 | ⏱️ Tempo Real e Rotinas | WebSockets, webhooks, cron jobs |
| 11 | 📊 Dados, Métricas e Conhecimento | Analytics, scraping, refatoração, documentação, LGPD |
| 12 | 🌍 Internacionalização | i18n, fuso horário, formatos de data e moeda |
| 13 | 📣 Comunicação com o Usuário | E-mail transacional, push, SMS, separação marketing vs operacional |
| 14 | 💳 Pagamentos e Recorrência | Gateway, assinatura, dunning, reembolso, chargeback, sandbox |
| 15 | 🤖 Inteligência Artificial e LLMs | Modelo, provedor, prompts, custos de tokens, privacidade, resiliência |
🛠️ Como usar
1. Copie o arquivo para o seu projeto
Baixe o TECH_STACK.md e coloque na raiz do repositório.
curl -o TECH_STACK.md https://raw.githubusercontent.com/promovaweb/vibe-tech-stack-checklist/main/TECH_STACK.md
2. Responda as perguntas — com o time ou com o agente
Opção A — Com o time (recomendado):
Marque uma call de 1 hora ou peçam uma pizza. Para cada pergunta, debatam qual opção faz mais sentido para o momento atual do projeto, apaguem a opção descartada e deixem apenas a escolhida.
A resposta certa não é a mais sofisticada. É a que o time consegue sustentar agora.
Opção B — Com o agente da sua IDE (rápido):
Abra o TECH_STACK.md no seu editor, ative o modo agente e envie uma mensagem descrevendo o projeto. O agente vai ler cada pergunta, escolher a opção mais adequada, remover a outra e justificar cada decisão com > 💡 Motivo:.
Como ativar o modo agente:
- GitHub Copilot (VS Code): painel Copilot Chat → modo Agent
- Cursor: painel Composer no modo Agent
- Windsurf: painel Cascade
- Claude (VS Code): instale a extensão Claude da Anthropic → painel Claude → abra o
TECH_STACK.md e inicie a conversa no modo agente
- Codex CLI: no terminal, execute
codex na raiz do projeto — o Codex lê automaticamente os arquivos do diretório; descreva o projeto e peça para preencher o TECH_STACK.md
- OpenCode: no terminal, execute
opencode na raiz do projeto → o arquivo TECH_STACK.md ficará disponível como contexto; descreva o projeto e solicite o preenchimento
- Claude / ChatGPT: anexe o arquivo
TECH_STACK.md na conversa
Exemplos de prompt:
Estou desenvolvendo um SaaS de gestão financeira para pequenas empresas, time de 2 devs, MVP com planos Free e Pro. Analise o TECH_STACK.md e me ajude a responder cada questão.
ou
Estou desenvolvendo um e-commerce de moda com foco em SEO, para uma marca só, precisa emitir NF-e. Analise o TECH_STACK.md e me ajude a responder cada questão.
⛑️ Não sabe responder alguma pergunta? Use este prompt na sua IA favorita:
Sou leigo em programação e você é meu Tech Lead. Me ajude a responder a pergunta abaixo considerando que meu projeto é [DESCREVA SEU PROJETO EM 1 FRASE]: [COLE A PERGUNTA AQUI]
3. Commitem e sigam a lei
O TECH_STACK.md vai para o repositório. A partir daí, ele guia o Code Review e as discussões do dia a dia.
4. Ative o contexto na sua IA
Você deve adicionar o arquivo TECH_STACK.md à constituição do projeto, envie ao agente da sua IDE:
speckit.constitution Adicione o arquivo TECH_STACK.md como guia técnico de arquitetura e padrões para a aplicação.
A IA vai adotar o documento como constituição técnica em todas as sessões. Toda sugestão de código e decisão de arquitetura passa a respeitar as escolhas documentadas pelo time — sem precisar repetir o contexto toda vez.
5. Suba no NotebookLM como Mentor Técnico
Com o TECH_STACK.md preenchido, faça o upload no Google NotebookLM e crie um NotebookLM dedicado ao projeto.
O NotebookLM transforma o arquivo em um mentor técnico interativo — qualquer pessoa do time pode fazer perguntas em linguagem natural e receber respostas fundamentadas exclusivamente no que foi documentado:
"Por que escolhemos SSR em vez de SPA?"
"Qual é a nossa política de backup do banco de dados?"
"Podemos usar JSON no banco para guardar configurações do usuário?"
Como manter o Mentor atualizado:
O TECH_STACK.md é um documento vivo. Toda vez que uma decisão técnica mudar:
- Atualize o
TECH_STACK.md no repositório
- Faça o commit com mensagem descritiva (ex:
docs: migra autenticação para OAuth)
- Faça o upload da nova versão no NotebookLM para substituir a anterior
Dica: Adicione ADRs, README técnico e diagramas de arquitetura ao mesmo notebook para criar uma base de conhecimento completa e consultável por todo o time.
💡 Filosofia do projeto
Este guia é intencionalmente opinativo e didático. Não tenta cobrir todas as possibilidades do universo — tenta cobrir as decisões que mais doem quando deixadas para depois.
- Pragmatismo acima de tudo: a opção mais simples é apresentada sem vergonha. "Monolito Majestoso" não é xingamento — é a escolha certa para 99% dos projetos no início.
- Vibe Coding em mente: quanto mais claras as decisões técnicas, melhor a IA consegue ajudar — e menos o time precisa "ensinar" as regras do projeto toda vez que abre uma nova conversa.
- Sem bala de prata: nenhuma opção é universalmente correta. O contexto (tamanho do time, prazo, risco) é soberano.
🤝 Contribuindo
Encontrou uma decisão técnica importante que não está coberta? Tem uma forma melhor de explicar algum conceito?
- Abra uma Issue descrevendo a sugestão
- Ou envie um Pull Request diretamente com a alteração no
TECH_STACK.md
Siga o padrão do documento: título direto, contexto em 1–2 frases e duas opções com _Vibe:_ descrevendo o que cada uma representa na prática.
📄 Licença
MIT — use, adapte e distribua à vontade. Se ajudar o seu time, já valeu.