Como funciona Comandos Anatomia Edições GitHub Star no GitHub
Por dentro da pasta .vibeflow/

Anatomia da pasta
.vibeflow/

O que é cada arquivo, por que ele existe, e como o agente usa. Pra você saber o que pode mexer, e o que é melhor deixar quieto.

Quando você roda /analyze, o Vibeflow cria uma pasta .vibeflow/ na raiz do projeto. É a base de conhecimento que o agente lê antes de cada spec, implementação e audit. Quatro artefatos formam essa base; os outros comandos põem as próprias pastas ao lado deles (PRDs, specs, audits e, com o implement --loop, os arquivos do loop).

index.md O mapa.
O que é
Um único arquivo com a visão geral do projeto: stack, estrutura, arquivos-chave, dependências, budget sugerido, dívida técnica conhecida, o Pattern Registry (bloco YAML listando cada pattern com suas tags e módulos) e um bloco de testes e pitfalls: o comando da suíte inteira, o comando mais estreito dos testes afetados com o tempo medido ou unmeasured, e os pitfalls que já custaram tempo ao projeto, cada um com a fonte.
Por que existe
Toda skill precisa se orientar antes de fazer qualquer coisa. Sem um mapa, o agente redescobre o projeto a cada comando, o que é lento, inconsistente e fácil de derivar. O Registry também permite que skills carreguem só os patterns relevantes em vez de todos.
Como o agente usa
Lido por toda skill no começo: analyze escreve; discover / gen-spec / implement / audit leem pra saber o stack, achar arquivos-alvo e resolver patterns via Registry. O analyze registra os comandos de teste sem rodá-los; só o analyze --measure roda cada um uma vez e grava o tempo e a data.
Você edita?
Em sua maior parte auto-gerado. Você pode editar notas à mão fora dos marcadores <!-- vibeflow:patterns:start/end --> e dos marcadores vibeflow:auto do bloco de testes e pitfalls, e essas sobrevivem aos analyze incrementais. O que está dentro de um ou de outro é regenerado.
patterns/ As soluções estruturais recorrentes.
O que é
Uma pasta com um arquivo markdown por pattern. Cada arquivo documenta um formato de solução que se repete no projeto: o que é, onde vive, as regras e exemplos reais de código tirados do próprio codebase.
Por que existe
Patterns carregam nuance: o quê, o porquê e o como. São como o agente escreve código que se parece com o seu, e não código genérico. Sem eles, cada implementação reinventa a estrutura.
Como o agente usa
gen-spec escolhe os patterns relevantes via Registry e lista no spec. implement lê só esses e replica a estrutura. audit verifica se a implementação seguiu. teach pode adicionar novos, inclusive importando de repos externos via --from.
Você edita?
Sim, mas com cuidado. O conteúdo dentro de <!-- vibeflow:auto:start/end --> é auto-gerado; edite fora dos marcadores pra adicionar notas que sobrevivam ao re-analyze. Use /teach pra adicionar um pattern novo em vez de soltar arquivo na mão.
conventions.md As regras.
O que é
Um único arquivo com as regras pequenas e atômicas do projeto: nomenclatura, layout de arquivos, linguagem/runtime, tratamento de erro, delimitadores, documentação. Bullets curtos, sem narrativa.
Por que existe
Regras sem nuance ("faça assim") pertencem a uma lista flat única, não espalhadas por docs de pattern. Esse arquivo é o que o agente aplica em cada linha de código que escreve, independente do pattern em jogo.
Como o agente usa
Carregado por gen-spec, implement e audit a cada execução. Implement aplica linha a linha; audit trata violações como falha de qualidade (o craftsmanship gate).
Você edita?
Sim. Use /teach pra adicionar ou corrigir uma convenção em linguagem natural ("a gente sempre usa named exports"). Edições diretas fora de <!-- vibeflow:auto:start/end --> são preservadas.
decisions.md A memória arquitetural.
O que é
Um log cronologicamente reverso de decisões arquiteturais: contexto, opções consideradas, o que foi escolhido e por quê. Mais novo primeiro. Escrito pelo architect durante specs e audits, nunca auto-gerado.
Por que existe
Seis meses depois, ninguém lembra por que você escolheu opção B em vez da A. Esse arquivo é o rastro. Também evita que o agente re-discuta questões já resolvidas a cada novo spec.
Como o agente usa
Lido por gen-spec e audit quando uma decisão é relevante pro escopo atual. O architect adiciona entradas quando um trade-off não-trivial é resolvido.
Você edita?
Sim. Esse é o mais "humano". Adicione entradas quando tomar uma decisão arquitetural que vale lembrar. /teach pode formatar pra você.
As pastas que o loop cria

Com o implement --loop, a .vibeflow/ ganha também quatro pastas de trabalho:

  • loop/ o ledger de cada feature (estado, a tabela de rodadas que o stats lê, decisões, follow-ups, passagem) e o config.md.
  • briefings/ um briefing por rodada do loop.
  • progress/ o progresso do executor e de cada rodada de conserto.
  • reviews/ os pacotes de revisão e o corpo do PR.

Commite a .vibeflow/ no git, menos reviews/, que guarda material de trabalho: os pacotes de revisão, refeitos a cada auditoria, e o corpo do PR. Acrescente .vibeflow/reviews/ ao .gitignore. (Nas instalações do Cursor e do Copilot, o instalador já põe a .vibeflow/ inteira no .gitignore.)

Patterns vs conventions: qual a diferença?

Ambos ensinam o agente sobre o projeto, mas em níveis diferentes. Conventions são regras atômicas ("nomes de arquivo em kebab-case"). Patterns são soluções estruturais recorrentes ("como a gente monta componentes com i18n").

conventions.md

  • Regras atômicas, uma linha cada
  • Raramente explicam o porquê
  • Aplicadas em cada linha de código
  • Pense: regras de ortografia

patterns/*.md

  • Soluções inteiras, um arquivo cada
  • Sempre explicam o porquê + exemplos
  • Aplicadas quando você enfrenta aquele problema específico
  • Pense: estrutura de redação

Convention é como escrever a palavra. Pattern é como montar o parágrafo.

Quer o quadro completo?

O MANUAL cobre cada comando, flag e workflow em profundidade.

Ler o MANUAL