🎧 Vibe Coding Toolkit

O fluxo real de desenvolvimento assistido por IA — testado em produção, não em teoria.

💡 Sobre o projeto

Programar com IA parece simples até você perceber que "colar um prompt grande e torcer" não é um fluxo de trabalho — é sorte. O Vibe Coding Toolkit é o oposto disso: é o fluxo que uso todo santo dia, em código de produção de verdade, pra fazer um agente de IA (Claude Code, principalmente, mas boa parte também vale pro Codex da OpenAI) funcionar como parte de fato do time — não como um estagiário hiperativo que precisa de babá.

Cada peça daqui existe porque resolveu um problema real: sessões que perdiam o fio da meada, agentes que construíam mais do que o pedido, warnings de lint (avisos de uma ferramenta que analisa o código atrás de padrões arriscados, sem precisar executá-lo) que ninguém nunca zerava, lições caras que se repetiam a cada sessão nova porque nada ficava registrado. Nada foi adicionado só "porque parecia legal" — se está aqui, é porque já evitou um problema de verdade pelo menos uma vez.

Um parênteses de transparência: as práticas daqui vêm de um projeto privado real de produção (fintech, sob NDA) — o código de origem não pode ser mostrado, então o que existe aqui é o método já extraído e genericizado, não um changelog público daquele projeto. Por isso o histórico deste repositório é curto — aqui é onde o método é documentado, não onde ele foi construído.

Sou o Matheus Gomes — no Instagram (@matheusgomes) falo sobre prompt e IA pra devs — e esse repositório é a versão organizada, testável e sem enrolação de tudo que venho ensinando por lá.

Pra quem é: devs de qualquer nível — se um termo técnico aparecer, ele é explicado ali mesmo, na primeira vez — que já usam ou estão testando Claude Code / Codex e querem um fluxo estruturado em vez de tentativa e erro.

⭐ Superpowers primeiro

[!IMPORTANT] Superpowers é, na humilde opinião do autor, a ferramenta mais poderosa de todo este toolkit. Não é só mais um plugin — é a disciplina que garante que um agente explore a intenção do pedido, planeje, e só então escreva código, em vez de arriscar a primeira interpretação plausível de algo em aberto. Tudo mais neste repositório apoia essa peça; ela sozinha já muda como uma sessão inteira se comporta.

Se você só for configurar uma coisa deste repositório, que seja essa: leia docs/tools/01-superpowers.md antes de qualquer outra ferramenta daqui.

Dois outros documentos merecem destaque igual, mesmo sem holofote de ferramenta de terceiro puxando atenção pra eles: orquestração de subagentes em ondas paralelas (o protocolo que elimina colisão de arquivo e disputa de commit na estrutura, não na disciplina — nada parecido apareceu em nenhuma coleção de terceiro que pesquisei pra este repositório) e quality gates de ESLint/Biome (promoção de aviso pra erro como migração rastreada, fronteira de arquitetura imposta via lint). Se Superpowers é o motor, esses dois são o chassi.

🚀 Comece por aqui

Se é sua primeira vez por aqui, não tente ler tudo em ordem — vá direto pro Playbook completo. É o guia de onboarding do zero até um projeto real com o setup inteiro funcionando, com um exemplo ponta a ponta em vez de teoria solta.

Um teaser do que te espera lá — os primeiros comandos, antes de qualquer coisa mais sofisticada. Repare que isso é "copie o arquivo certo, digite o comando certo" — não existe (ainda) um instalador que detecta sua stack sozinho e escreve tudo por você. Se é exatamente isso que você quer, pule direto pro atalho do aia-harness (/aia-harness:init) descrito em docs/01-installation.md — ele monta a base sozinho; o resto deste repositório vira material pra entender o que foi montado, não pra montar do zero:

npm install -g @anthropic-ai/claude-code
/plugin marketplace add anthropics/claude-plugins-official
/plugin install superpowers@claude-plugins-official
cp templates/CLAUDE.md.template CLAUDE.md

Isso já deixa o Claude Code instalado, a ferramenta mais importante do toolkit ativa, e o template de instruções de projeto no lugar certo. O resto — orquestração de subagentes, quality gates, memória entre sessões — o Playbook mostra em ordem, com o porquê de cada peça antes do como.

Ou: só o ESLint, numa linha

Se você não quer instalar nada do toolkit e só quer as regras de lint deste repositório valendo no seu projeto — inclusive o teto de 350 linhas por arquivo — cole isto no seu agente (Claude Code, Codex, Cursor, qualquer um que leia uma URL):

Leia https://raw.githubusercontent.com/soumatheusgomes/vibe-coding-toolkit/main/docs/prompts/08-eslint-quality-gates-install.md
e execute o prompt que está nesse arquivo neste projeto. Use MAX_LINES=350.

Ele baixa as três regras já escritas e testadas, adapta a configuração pra estrutura real do seu projeto, e te devolve a lista de arquivos que passaram do teto. Não conserta nada — medir e consertar são trabalhos separados.

Quando quiser que ele conserte, cole a mesma linha trocando 08- por 09-file-size-refactor.md: aí ele quebra os arquivos grandes em módulos menores, cortando por responsabilidade (lógica de negócio, componente de UI, acesso a dados) e não por contagem de linha, um arquivo por commit, com teste e checagem de tipos rodando entre cada um.

Os dois documentos por extenso: 08 — instalar e medir e 09 — quebrar os arquivos grandes.

🧭 Índice

• 💡 Sobre o projeto
• ⭐ Superpowers primeiro
• 🚀 Comece por aqui
• 🗺️ O fluxo completo
• 🧑‍💻 Como usar este repositório
• 📚 Documentação completa
• 🙏 Créditos
• ⚖️ Licença
• 👋 Vamos juntos

🗺️ O fluxo completo

Da instalação ao primeiro commit revisado — essa é a jornada completa, e onde cada ferramenta do toolkit entra nela. Uma peça central aparece cedo: subagentes (instâncias separadas do agente principal, cada uma especialista num papel — revisor, banco de dados, testes) fazem o trabalho pesado enquanto a sessão principal só planeja e decide.

Nas caixas abaixo, o caminho principal é a linha do tempo da esquerda pra direita; os círculos são as ferramentas de suporte, que não são etapas — ficam ativas o tempo inteiro, moldando como as etapas acontecem por baixo dos panos. Quality gates é uma dessas — protege todo commit, não é um passo único que se cumpre uma vez e some.

flowchart LR
    Install["📦 Instalar<br/>Claude Code + plugins"]
    Setup["⚙️ Configurar projeto<br/>CLAUDE.md + hooks"]
    Brain["💡 Brainstorm"]
    Plan["📝 Plano"]
    Waves["🌊 Orquestração de subagentes<br/>ondas paralelas"]
    Review["🔍 Revisão multi-agente"]
    Ship["🚀 Commit / Ship"]

    Install --> Setup --> Brain --> Plan --> Waves --> Review --> Ship

    subgraph SP["⭐ Superpowers"]
        Brain
        Plan
    end

    Graphify(("🕸️ Graphify<br/>+ Context7"))
    RTK(("🪙 RTK"))
    Persona(("🦥 Ponytail + 🗣️ Caveman"))
    Memory(("🧠 Memória<br/>Claude + Obsidian"))
    Gate(("🚦 Quality gates"))

    Graphify -. orienta antes de codar .-> Brain
    RTK -. barateia a sessão inteira .-> Waves
    Persona -. governa o quê e o como .-> Waves
    Memory -. contexto ao começar .-> Setup
    Gate -. protege todo commit .-> Ship
    Ship -. registra aprendizados .-> Memory

Repare que RTK, Ponytail, Caveman, o grafo do Graphify (com o Context7 ao lado, orientando antes de codar) e os Quality gates não são paradas do caminho — são camadas ativas o tempo todo. Uma ressalva sobre o RTK especificamente: ele está aqui porque é parte real do fluxo diário do autor, mas é documentado como padrão pra replicar, não como binário público pra instalar — os outros nós deste diagrama, sim. Já a memória (sistema do Claude + Obsidian) entra dos dois lados: carrega contexto no início da sessão e grava o que valeu a pena aprender no final.

🧑‍💻 Como usar este repositório

Não existe um único jeito "certo" de percorrer este repositório — depende do que você já sabe e do que está procurando agora.

• Quer o setup completo, do zero? Vá direto pro Playbook — é o caminho guiado, passo a passo, terminando com um projeto real rodando o fluxo inteiro.
• Já conhece o fluxo e só quer consultar uma ferramenta específica? docs/tools/ é a referência — cada arquivo é autocontido, sem depender de voc