Vibe Coding tem seu lugar, mas tem um teto
Vibe coding não é vilão. É uma etapa. Reconheça o que ele faz bem antes de entender por que não basta.
O que o vibe coding fez bem
- Reduziu a fricçãoSaímos do papel em branco em minutos. Prototipar virou esporte de baixo custo.
- Liberou energia criativaIdeias que nunca passariam do whiteboard viraram POCs jogáveis num fim de tarde.
- Ampliou quem pode codarPessoas de produto, design e dados conseguem montar coisas que funcionam — sem depender de uma fila de eng.
Onde encontra o teto
- Amnésia de contextoA cada sessão o contexto se perde. É preciso reexplicar regras do zero. Resultado: regressões silenciosas.
- Soluções no vácuoSem spec clara, a IA gera código que funciona mas resolve o problema errado. Bonito, plausível, inutilizável.
- Spaghetti Code que compõe jurosSem visão de arquitetura, cada nova feature quebra duas que funcionavam. A dívida técnica vira chumbo no pé.
Eixo horizontal: o projeto crescendo — novas features, correções, integrações. A cada passo à direita, a chance de quebrar algo que funcionava aumenta. A linha mostra o que acontece com a qualidade do output sem disciplina.
Hardening é a fundação; SDD e TDD são as disciplinas que rodam sobre ela
Três pilares load-bearing, assimétricos. Hardening dá à squad papéis, constituição, task file e roteiro — é o que torna a operação repetível e não dependente de gênio. Sobre essa fundação, SDD garante o rigor da entrada e TDD prova que a saída funciona. Sem um deles, o sistema regride: sem Hardening vira improviso; sem SDD resolve o problema errado; sem TDD o bug vai a produção.
Hardening
A fundação que torna a squad operável e repetível — não depende de gênio. É o que transforma um LLM com um prompt num time. Tem quatro faces:
- Papéis claros — Agentes especializados, cada um consumindo o output do anterior. O número e a composição da squad variam com o projeto — os 8 papéis deste repo são um exemplo frequente, não regra. Sem generalistas heróicos.
- Constituição do Projeto — CLAUDE.md + convenções: stack, regras e decisões load-bearing. Onboarding instantâneo.
- Task File Central + definições — O arquivo contínuo que acumula contexto fase a fase, com as specs de produto, técnica e teste.
- Roteiro/ciclo + checkpoints — O arco ideação→merge com gates não-negociáveis e alocação de LLM por fase.
SDD — Spec-Driven Development
A especificação, não o prompt, é o artefato principal. Spec vaga produz código vago; a qualidade do output é proporcional ao rigor do input. Documentação é mandatória antes do RFD.
TDD — Test-Driven Development
Todo critério de aceite tem um teste que o prova. "Critério de aceite sem teste objetivo é teatro." A camada de teste é escolhida por projeto; o smoke manual é uma camada, não a estratégia inteira.
A especificação é o artefato principal — não o prompt
O Pilar SDD em prática. À esquerda: um prompt solto entra direto no código. À direita: o mesmo prompt entra na esteira da squad, vira spec rigorosa, e só então código. Veja a diferença no que sai do outro lado.
Esquerda: código gerado a partir de prompts soltos. Direita: especificação caprichada com humanos especialistas dando as diretrizes em cada etapa.
AC-02. Tentativa de notificação respeita hierarquia de canais (ADR-012).
AC-03. Falha em todos os canais → registra
notification_failed no audit log e dispara alerta operacional.AC-04. Cliente em régua de cobrança ativa não recebe nova tentativa antes de 48h da última.
Métrica de sucesso: taxa de leitura WhatsApp > 70% em 30 dias.
default— lista paginada de clientes elegíveis, ordenada por dias_atraso desc.loading— skeleton de 5 linhas, mantém header e filtros visíveis.empty-no-eligibility— copy: "Sem clientes elegíveis no momento. Próxima janela: 06:00."erro-canal-indisponível— banner amarelo: "WhatsApp Business indisponível. Fallback automático para SMS." Não bloqueia operação.sucesso-com-protocolo— toast verde com número de protocolo + link "Ver no audit log".
POST /notifications/dispatchAuth: Bearer token (service account)
Body:
{ customerId: uuid, templateId: enum, idempotencyKey: uuid }Respostas:
202 Accepted— body:{ protocoloId, canal_usado, eta_segundos }409 Conflict— cliente em cooldown de 48h422 Unprocessable— cliente inelegível503 Service Unavailable— todos os canais down (raro, alerta ops)
Unit — hierarquia de canais e fallback (AC-02).
Contract — schema do POST /dispatch validado contra OpenAPI, 4xx e 5xx cobertos.
Integration — repositório de clientes + audit log, contra Postgres real (testcontainers).
E2E — jornada feliz (cliente elegível → WhatsApp validado → 202) + 2 erros canônicos (canal down, cooldown).
Coverage gate: 85% em
src/domain/, 70% global.export function checkEligibility(customer: Customer, today: Date): EligibilityResult {
if (customer.negativationStatus !== 'pending') return { eligible: false, reason: 'not_pending' };
if (daysOverdue(customer, today) < 5) return { eligible: false, reason: 'within_grace_period' };
if (customer.openBalance < 50) return { eligible: false, reason: 'below_threshold' };
return { eligible: true };
}
Code quality: ✓ sem
any injustificado · ✓ SRP respeitado · ✓ erros como tipos discriminados.Segurança: ✓ Zod nos boundaries · ✓ idempotência implementada · ✓ audit log persistido.
Performance: ✓ sem N+1 · ✓ índice composto em
(status, dias_atraso).Cobertura: ✓ 91% em domain, 76% global. Acima do gate.
Status final: ✅ APROVADO — pronto para merge.
Olhando os dois ao mesmo tempo
Oito papéis, sete comandos, memória persistente
Antes de virem usados, a squad precisa ser apresentada. Cada agente vive em .claude/agents/ versionado no repo, opera sob a regra do fluxo obrigatório (produto → UX → arquitetura → fullstack → QA → writer) e mantém memória por-projeto em .claude/agent-memory/[agente]/MEMORY.md — o que aprende em uma task fica disponível para a próxima. Sem generalistas heróicos.
Sete comandos reais orquestram a squad — /new-feature inicia uma feature num epic existente; /split-epic quebra um objetivo em tasks no TODO/; /next-task escolhe a próxima task elegível e a inicia; /architect ativa o arquiteto sobre uma task em IN_PROGRESS; /refactor gera um epic técnico com escopo e riscos; /bootstrap calibra a squad para um projeto novo; /evolve auto-evolui a squad puxando deltas do método-base. Todos vivem em .claude/commands/, versionados no repo.
O mapa macro: da ideação ao merge, com os três pilares vivos
Este é o arco inteiro — ideação → produto → UX → arquitetura → gate RFD → engenharia → QA → docs → code review → merge. Os três pilares operam o tempo todo: Hardening é a fundação (papéis, constituição, task file, roteiro); SDD garante o rigor da entrada; TDD prova a saída. Quatro tollbooths não-negociáveis seguram o arco. E o próprio método é versionado e constantemente evoluído — não é um manual congelado.
Versão do método
- METHOD-VERSION na raiz versiona o método em semver
- MAJOR quebra o contrato da squad; MINOR é aditivo; PATCH é redação
- Distinto da versão do artefato (site)
Journal de mudanças
- docs/journal/vX.Y.Z.md — um arquivo por versão
- Cada delta nomeia o arquivo-fonte e o ponto de inserção
- CHANGELOG.md indexa, mais novo primeiro
Base canônica
- Este repo é a origem; o template/ é a versão portátil
- /bootstrap calibra a squad num projeto novo
- Provenance no CLAUDE.md diz de onde a cópia puxa deltas
Auto-evolução
- /evolve lê o journal upstream entre a versão local e a atual
- Apresenta cada delta como checklist ao humano
- MAJOR exige confirmação humana por delta — nunca auto-aplica
Sete comandos versionados em .claude/commands/ disparam fluxos completos. Cada um ativa o agente certo no momento certo — do planejamento à auto-evolução da própria squad.
Regras de negócio e arquitetura vivem na raiz
Os estatutos de trabalho são parte do Hardening (a constituição do projeto): ficam onde todo mundo entra primeiro — a raiz do repo. Regras de negócio mantidas pelos donos do domínio. Decisões arquiteturais mantidas pelos arquitetos. Mesmo lugar, mesmas pessoas in the loop, mesmo histórico — onboarding instantâneo para humanos e agentes.
Regras de Negócio
- São as invariantes do projeto: stack, convenções e decisões que não se renegociam por task.
- Exemplo (case da Régua, ver Cases): 'nunca modificar o Valor Original do ERP; apenas calcular o Valor Atualizado visivelmente.'
- Exemplo (case da Régua): hierarquia de canais — WhatsApp validado → SMS fallback → Email paralelo.
- Cada projeto define as suas; agentes e humanos consultam antes de qualquer task começar.
Decisões Arquiteturais (ADRs)
- Status: proposto · aceito · substituído por ADR-XXX
- Contexto: o problema e as restrições.
- Decisão: o que foi decidido.
- Consequências: o que ganha, o que perde, o que fica caro reverter.
- Alternativas consideradas: o que foi descartado e por quê.
A unidade de trabalho é um arquivo que evolui
É a terceira face do Hardening: o trabalho se acumula num arquivo de task contínuo. Ele vive em docs/epics/epic-NNN-nome/ e fisicamente se move entre TODO → IN_PROGRESS → DONE (ou BLOCKED), acompanhando o ciclo completo. Cada agente que passa anexa uma seção — produto, UX, técnica, log, review, docs. Quando chega em DONE, o arquivo é a história completa, e o gate RFD só o libera com as três specs presentes.
Metadata: { epic: 001, size: M, priority: high, status: IN_PROGRESS }
## PM · Especificação de Produto
## UX · Especificação de UX
## Architect · Especificação Técnica
## Engineer · Log de Execução
## QA · Review
## Writer · Notas de Documentação
Caminhar o mapa: a rotina mãos-na-massa de uma task
Se O Ciclo Completo é o mapa macro, o Fluxo Diário é caminhá-lo task a task. Cinco estações na esteira; nelas vivem os quatro checkpoints humanos. As três specs (produto, técnica, teste) precisam estar no task file antes de o gate RFD abrir a engenharia — e o quarto checkpoint, o code review + merge, é humano e fecha a task. Uma entrega cuidada, testada, observável, documentada, evolutiva, sustentável.
Aprovação PM/UX
Aprovação Architect
Pronto para Dev (RFD)
Code review + merge
- Atende a demanda
- Sem débito técnico
- Cobertura de testes unitários e integrados
- Aprovado no fluxo de QA
- Documentado
- Instrumentado com observabilidade
- Sustentável no tempo
- Autodocumentado pelo processo
Agora você tem uma squad inteira ao seu dispor
Antes, uma pessoa ocupava um papel dentro da squad — uma peça de uma engrenagem maior. Agora, cada pessoa comanda uma squad inteira. O papel muda — e o que sai do outro lado muda mais ainda.
- Cada pessoa cobria uma parte do trabalho.
- Esperava o review humano em fila.
- Documentava depois (se sobrasse tempo).
- QA era etapa separada, com handoffs lentos.
- Onboarding de quem chega: semanas.
- Você orquestra PM, UX, Architect, Engenheiro, QA e Writer ao mesmo tempo.
- Code review é ciclo contínuo, em minutos, com critérios objetivos.
- Documentação sai pronta da esteira — não é afterthought.
- QA roda em paralelo, gera TODOs, fecha consenso.
- Onboarding lê o histórico dos épicos — dias, não semanas.
Spec validada antes do código elimina ida-e-volta de regra de negócio.
Quem comanda a squad entrega features inteiras — não pedaços.
O método não depende de gênio. Vira capacidade do time — cada pessoa amplia sua potência de entrega.
Testes, observabilidade e docs são parte do default, não opcional.
Input cuidadoso · Execução especializada · Human in the loop garante a intenção
A Trindade é a leitura dos três pilares pelo lado de quem opera: Input Cuidadoso é o Hardening em ação; Execução Especializada é SDD + TDD rodando; o Humano dá a intenção e revisa. Velocidade sustentável e qualidade saem da interseção das três. Faltando uma, o sistema regride.
Input Cuidadoso e Estratégico
É o Hardening: papéis claros, a constituição do projeto, o task file central e o roteiro com checkpoints. A fundação que torna a squad operável — a clareza do problema vem antes da resposta.
Execução Especializada
É SDD + TDD: a spec rigorosa define o que construir, os testes provam que foi construído. Squad de agentes modulares, agnósticos de framework, especialistas em sua função.
Human in the Loop
A intenção e o juízo final: o humano define o porquê e é o revisor nos checkpoints — o code review + merge é dele. A intenção é, e continua sendo, humana.
A intenção é sempre humana
A IA não acorda querendo algo. Não tem auto-motivação, não persegue market-share, não está preocupada com a satisfação dos clientes, não pensa em fechar o trimestre com um EBITDA melhor. Quem quer essas coisas é gente. O papel humano deixou de ser escrever o código — a IA faz isso com mais consistência, documenta, instrumenta, valida, segue as regras com paciência infinita. O papel humano passou a ser: dar a visão estratégica, definir o porquê, e acompanhar cada etapa relevante e o resultado final.