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 vivem ali dentro.

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 e o Pattern Registry (bloco YAML listando cada pattern com suas tags e módulos).
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.
Você edita?
Em sua maior parte auto-gerado. Você pode editar notas à mão fora dos marcadores <!-- vibeflow:patterns:start/end -->, e essas sobrevivem aos analyze incrementais. O que está dentro dos marcadores é 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ê.

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