vibecode-pro-max-kit: especificações, memória e colaboração multi-agent para projetos de programação IA

Projetos de código escritos com IA costumam sair do controle em três pontos: o contexto é cortado, os planos ficam espalhados na conversa e as decisões não deixam rastro. A cada mudança de requisito, você precisa explicar o projeto inteiro de novo.

vibecode-pro-max-kit resolve um problema de processo: transformar o AI coding agent em um engineering team guiado por especificações. Primeiro vem a especificação, depois o plano, depois a execução, e cada passo deixa um registro auditável. Ele não é um framework de chat e não substitui CI/CD; faz uma coisa: torna rastreável o processo de decisão da programação com IA.

---

Que problema ele resolve

Perda de contexto: conversas longas são cortadas pela compaction, e decisões de design, condições de borda e raciocínios de debug desaparecem. Na próxima mudança, você explica tudo outra vez ou deixa a IA adivinhar.

Planos e decisões sem rastro: exportar o Markdown de uma conversa não vira documentação estruturada. Na review, o time não enxerga o histórico: por que aquela solução foi escolhida, que alternativas foram descartadas, quais limites estavam em jogo.

Colaboração multi-agent custa caro: um task dividido em várias etapas, cada uma com um agente diferente, depende de handoffs vagos em linguagem natural. Quem cuida de cada fase, qual é o formato de saída, onde ficam os critérios de aceite: tudo exige supervisão manual.

Essas três coisas juntas fazem a programação IA parecer “começar do zero toda vez”. vibecode-pro-max-kit coloca isso dentro de um harness: spec no início, plan no meio, execution com checkpoints e processo com memória.

---

Instalação e auditoria de segurança

Comando de instalação

O README usa instalação por shell remoto:

curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash

Depois da instalação, execute vc-setup no Claude Code; usuários do Codex seguem o README e usam /vc-setup. Ele cria o diretório process/ e inicializa a configuração.

Lista de arquivos escritos

O README atual descreve a instalação como non-destructive: ela não limpa .claude/skills/, .claude/agents/, process/ ou settings.json, apenas escreve ou atualiza arquivos pertencentes ao kit. Ainda assim, ela coloca estes diretórios e arquivos no projeto:

Caminho	Conteúdo
.claude/agents	Definições de agentes para Claude Code; o README atual indica 15
.claude/skills	Definições de skills para Claude Code; o README atual indica 33
.claude/hooks	Hooks de ciclo de vida; o README atual indica 10
.codex/agents	Agentes espelhados para uso com Codex
.agents/skills	Symlink para .claude/skills, usado pela discovery do Codex
CLAUDE.md	Orchestrator e routing rules do Claude Code
AGENTS.md	Registry cross-tool de agentes e skills
process/	Diretório de ciclo de vida de planos e memória de projeto

O README também explica que configurações existentes são salvas em .vibecode-backup/, um CLAUDE.md existente é copiado como CLAUDE.md.pre-vibecode, e um process/ existente não é migrado diretamente pelo script de instalação: vc-setup / vc-update cuidam disso de forma interativa.

Pontos de auditoria de segurança

Não rode curl | bash diretamente na repository de produção. Mesmo que o README diga que a instalação é non-destructive, um script shell remoto precisa ser auditado, porque escreve em caminhos sensíveis como .claude/, .codex/, CLAUDE.md e AGENTS.md.

Fluxo recomendado para a primeira prova:

1. faça um fork ou copie um projeto não produtivo
2. rode a instalação no fork
3. confira os arquivos escritos com git diff
4. só pense em migrar depois de confirmar que não houve mudança inesperada

Você precisa validar se o mecanismo de backup do script serve para a sua repository. Projetos que já têm skills ou agentes personalizados com prefixo vc- devem revisar as caveats do README com atenção extra.

“Não sobrescreve” também não significa “sem risco”. Isso reduz a chance de apagar diretórios existentes, mas não substitui auditoria de supply chain, isolamento de permissões e preparo de rollback. Para times, o mínimo continua sendo: ler o script, rodar em uma cópia e pedir para alguém revisar o diff.

---

Conceito principal: workflow orientado por especificações

Contexto do Spec Kit

A ideia principal do vibecode-pro-max-kit vem de workflows de spec-driven development (SDD), como o Spec Kit. O fluxo é: escrever especificação primeiro, detalhar em plano, quebrar em tarefas e só então executar.

Cada fase gera um artefato Markdown que fornece contexto estruturado para a próxima:

Fase	Entrada	Saída
Spec	Descrição do requisito	Documento de especificação: limites, restrições, critérios de aceite
Plan	Documento de especificação	Plano de implementação: passos, responsáveis, dependências
Tasks	Plano de implementação	Lista de tarefas concreta e verificável
Implement	Lista de tarefas	Mudanças de código + registro do processo

Esse fluxo não é novo, mas o vibecode-pro-max-kit o “instala no projeto”: agentes, skills e hooks são desenhados em torno dele.

Ciclo de vida do plano

O README atual enfatiza um workflow RIPER-5 plan-first e o apresenta como 7 fases com gates:

Fase	O que faz	Artefato de saída
Research	Coleta contexto e confirma limites	research artifact
Spec	Escreve user stories e limites do requisito	spec artifact
Innovate	Compara soluções e registra decisões	alternatives / decision notes
Plan	Detalha passos, responsabilidades e formas de validação	plan artifact
Validate	Valida plano e riscos antes da execução	validation notes
Execute	Executa por tarefas e registra o processo	code changes + execution notes
Update-Process	Atualiza a memória e remove registros obsoletos	atualizações em process / context

Cada fase precisa de aprovação explícita para avançar. Isso é o que evita que a IA saia do trilho: uma pessoa entra nos checkpoints, confirma a direção e só então libera o próximo passo.

Agentes e skills

O README atual fala em 15 agentes, 33 skills e 10 hooks. Esse é o recorte verificado no README em 2026-06-23; como a repository pode mudar, não trate isso como número permanente.

A estrutura das skills é compatível com Codex Skills e Claude Code skills: cada skill tem um SKILL.md com instruções e, opcionalmente, scripts/, references/, assets/. Uma skill pode ser chamada explicitamente ou acionada implicitamente quando o escopo bate.

Outros dois conceitos:

• context groups: blocos de contexto organizados por tema ou função, evitando carregar o projeto inteiro sempre
• feature folders: arquivos organizados por módulo funcional, cada pasta com sua própria spec e process

---

Mecanismos de segurança em detalhe

O README lista algumas categorias de segurança e processo que valem atenção:

Mecanismo	Função	Quando aciona
privacy guardrails	Impedir que informações sensíveis entrem em process ou nos outputs	Antes de outputs de agentes e atualizações de processo
gated phases	Impedir que o agente pule direto para escrever código	Avanço de Research até Update-Process
check loops	Permitir que a execução se autochecke e volte ao plano	Durante execução e validação
deviation protocol	Registrar desvios do plano original	Quando o plano muda ou a execução se desvia
high-risk evidence pack	Exigir evidência extra em decisões de alto risco	Quando certos limiares de julgamento são acionados

Esses mecanismos dificultam decisões arriscadas sem supervisão. Mas eles dependem de hooks e configuração funcionando corretamente. Se hooks forem desativados, permissões forem amplas demais ou o time não revisar process/, o mecanismo ainda pode falhar.

---

Tabela para decidir se vale usar

Cenário	Faz sentido?	Motivo
Projeto mantido por muito tempo	Sim	A memória fica em process/, e os planos são auditáveis
Review em equipe	Sim	Decisões e desvios ficam rastreáveis
Requisitos complexos	Sim	Colaboração multi-agent e detalhamento em fases
Contexto que se perde facilmente	Sim	Conversa estruturada por spec-driven workflow
Script descartável	Não muito	O overhead do processo é alto demais
Pequenos ajustes	Não muito	O custo do harness passa do benefício
Processo de engenharia já maduro	Com cautela	Pode conflitar com CI/CD e reviews existentes
Você não quer introduzir um harness externo	Não	README, AGENTS.md, CLAUDE.md e process mudam a estrutura da repository

O critério principal é: o overhead do processo vale a pena? Em projetos longos, complexos e colaborativos, esse overhead compra auditabilidade e eficiência de coordenação. Em projetos curtos, simples e individuais, ele vira apenas custo.

---

Relação com Spec Kit, Codex Skills e Claude Code

Spec Kit: define o contexto e o framework de SDD, ou spec-driven development. É a camada conceitual, sem depender de um agente específico.

Codex Skills: estrutura de diretório das skills da OpenAI: SKILL.md + scripts/ + references/. Ela empacota instruções, recursos e scripts em workflows reutilizáveis.

Claude Code skills: estrutura parecida, com SKILL.md e arquivos de apoio. Trata skill como unidade reutilizável de processo, acionável de forma explícita ou implícita.

vibecode-pro-max-kit: coloca essas ideias dentro do projeto. Ele não substitui o Spec Kit; transforma o fluxo spec-driven em agentes + skills + hooks executáveis, compatíveis com configurações de projeto do Claude Code e do Codex.

Custo de migração: se o projeto já tem .claude/agents, .claude/skills, CLAUDE.md ou AGENTS.md, avalie o diff e confirme que suas configurações personalizadas não foram perdidas.

---

Fluxo para a primeira prova

Seguindo a recomendação do README, teste primeiro em um projeto não produtivo:

Passo 1: faça um fork ou copie um projeto não produtivo

Não opere diretamente na repository principal. Use um fork ou copie um diretório local de teste.

Passo 2: rode o comando de instalação

curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash

Passo 3: rode vc-setup

No Claude Code, execute vc-setup; no Codex, use /vc-setup conforme o README. Ele cria o diretório process/ e inicializa a configuração.

Passo 4: confira os arquivos escritos

git status
git diff .claude/ .codex/ .agents/ CLAUDE.md AGENTS.md process/

Confirme que os arquivos escritos estão dentro do esperado.

Passo 5: tente o primeiro workflow spec-driven

Dê ao agente uma demanda simples, como “adicionar uma função de logging”. Observe Research -> Spec -> Innovate -> Plan -> Validate -> Execute -> Update-Process e confirme se a aprovação é exigida em cada fase.

Passo 6: valide

Quando process/ tiver artefatos, as mudanças em CLAUDE.md / AGENTS.md forem compreensíveis e hooks e agentes não apresentarem erro, aí sim avalie migrar para um projeto real.

---

Próximos passos e leituras relacionadas

Artigos já publicados:

• Prática de roteamento multi-agent com OpenClaw
• Guia completo do workflow do Claude Code
• Como funciona a memória de AI agents

Conteúdos futuros da série:

• Checklist de troubleshooting para colaboração multi-agent
• Caso prático de projeto spec-driven