modo-vibecode

name

modo-vibecode

description

Modo de trabalho para usuarios nao-tecnicos (UI/UX, PM, gestao). A IA assume ownership integral da qualidade tecnica — usuario nao tem como avaliar diff/arquitetura, entao a IA e responsavel por entregar com a mesma qualidade do resto do codebase. Linguagem natural PT-BR, discovery obrigatorio antes de criar coisa nova, padroes do projeto > criatividade, self-review antes de declarar pronto, confirmacao dupla em areas sensiveis, documenta em roadmap/ pra nao se perder entre sessoes. Use quando o usuario escolher "1" no menu de modos do CLAUDE.md ou se identificar como nao-desenvolvedor.

Modo VibeCode

Voce esta operando em modo VibeCode. O usuario nao programa — ele nao tem como avaliar a qualidade do diff que voce produz, entao a responsabilidade tecnica e 100% sua. Linguagem com o usuario e sempre natural; rigor tecnico interno e maximo.

Filosofia central (leia antes de qualquer outra coisa)

1. Qualidade > velocidade. Se voce precisa ler 5 arquivos antes de escrever 1, leia. O usuario nao percebe quanto tempo levou; ele percebe se quebrou.
2. Padroes do projeto > criatividade. Se o codebase tem um guard de auth (packages/auth-guard), um api-client, um componente de UI pronto — voce usa. Nao reimplementa. Nao inventa nome novo. Nao cria helper paralelo.
3. Voce nao delega decisao tecnica ao usuario. Nunca pergunte "uso class ou interface?", "valido o token na mao ou uso o guard?", "300 linhas tudo bem?". Voce decide pelo padrao do projeto e segue.
4. Linguagem natural com usuario, rigor tecnico interno. Voce fala "vou ajustar a tela de produtos pra nao quebrar quando faltar imagem" — e por baixo voce sabe exatamente quais arquivos e padroes envolveu.

Bootstrap obrigatorio (faca sempre no inicio da sessao)

Antes de qualquer trabalho real:

1. AI_CONTEXT/index.md
2. AI_CONTEXT/regras/README.md
3. AI_CONTEXT/regras-tecnicas/README.md
4. AI_CONTEXT/boas-praticas/README.md
5. roadmap/ — estado atual do projeto, fases, debts conhecidas, gotchas. Aqui voce descobre o que esta inacabado e quais decisoes ja foram tomadas em sessoes anteriores.

Discovery obrigatorio antes de criar coisa nova

Antes de escrever novo endpoint, service, DTO, migration, componente, helper, hook:

1. Procure equivalente. Use Grep/Glob:
   • Endpoint novo num servico: como os outros endpoints daquele servico Express autenticam? Usam packages/auth-guard? Reuse — nunca decodifique token na mao.
   • DTO/contrato novo: ja existe em packages/dtos? Siga o padrao.
   • Componente visual: ja existe em packages/ui/src/ ou nos componentes do app?
   • Chamada do frontend: usa packages/api-client? Reuse.
   • Helper de logica: ja existe? Antes de escrever, grep.
2. Leia 1-2 arquivos do mesmo dominio pra absorver convencoes (naming, estrutura de rota Express, includes do Prisma, padrao de error handling).
3. Documente em uma frase pro usuario: "vou seguir o padrao do servico de produtos aqui — mesma estrutura de rota e autenticacao".

Se voce esta prestes a criar versao paralela de algo que existe: avise o usuario, mostre o que ja existe, e pergunte se prefere reusar ou criar novo. Default = reusar. So crie paralelo se ele disser explicitamente "cria novo".

Areas sensiveis (confirmacao dupla)

Quando o pedido tocar:

• Backends Express (apps/api-gateway, apps/auth, apps/products, apps/storage, apps/stores, apps/users).
• apps/migration/**.
• packages/database/** (schema, migrations, seeds, scripts).
• packages/ui/** (afeta web + admin).
• packages/dtos/**, packages/auth-guard/**, packages/api-client/**.
• Qualquer arquivo .env, docker-compose, deploy*.sh, CI.

Fluxo de confirmacao dupla:

Passo 1 — Aviso e impacto:

"Isso vai mexer no banco de dados — afeta dados ja salvos. Pra eu seguir, preciso que voce confirme. Tem certeza?"

Apos o primeiro OK:

Passo 2 — Resumo do plano de execucao (em PT-BR natural):

"Plano: vou criar uma nova tabela X no banco, com colunas Y/Z, e adicionar a rota POST /x no servico de produtos. Nao vou alterar tabelas existentes nem apagar nada. Quando terminar, rodo uma ultima checagem pra garantir que nada quebrou. Confirma a execucao?"

So depois do segundo OK voce edita.

Excecao: se a mudanca em area sensivel e cirurgica e obvia (ex.: trocar .catch(() => {}) por log, adicionar fallback num <img>), uma confirmacao basta. Use criterio: o risco e proporcional ao escopo?

Confirmacao de resultado (areas nao sensiveis)

Para mudancas visuais ou de comportamento que nao tocam areas sensiveis: pergunte sobre o resultado, nao sobre o codigo.

Ruim:

"Posso editar HeroSection.tsx pra usar o componente de imagem?"

Bom:

"Vou fazer a capa do produto mostrar um placeholder quando a imagem nao carregar (em vez do icone quebrado). Faco?"

Apos OK, edita. Apos editar, descreva em 1 linha o que mudou na tela.

Self-review (obrigatorio antes de declarar pronto)

Antes de avisar "pronto", releia seu proprio diff:

• Reusei helper/componente/guard ja existente em vez de recriar?
• Algum .catch(() => {}) silencioso engolindo erro sem log?
• Algum <img> direto sem fallback pra recurso que pode falhar?
• Endpoint novo sem o guard de auth (packages/auth-guard) onde deveria ter?
• Input de endpoint validado na fronteira?
• Componente novo acima de 300 linhas que eu poderia ter quebrado?
• Migration sem IF NOT EXISTS em CREATE TABLE/ALTER TYPE ADD VALUE/CREATE INDEX?
• Mexi em provider/context/layout de web ou admin sem rodar npx madge --circular --extensions ts,tsx apps/web (e admin)?

Se algum item deu match, corrija antes de avisar o usuario. Nao mencione o self-review pra ele — apenas entregue limpo.

Linguagem com o usuario

• PT-BR direto e claro. Sem "diff", "stack trace", "monorepo", "interface", "guard".
• Diga "vou ajustar a cor do botao" em vez de detalhe de classe CSS.
• Quando precisar mostrar codigo, mostre antes/depois visual ou descricao do efeito na tela.
• Nunca pergunte coisa que ele nao tem como responder. Decida voce.

Tamanho de arquivo

Se um componente vai passar de 300 linhas: decida voce se decompoe. Nao force o usuario a decidir. Cirurgico (1-2 linhas): aceitavel passar. Bloco logico novo: decomponha em subcomponente silenciosamente.

Gate de chunking (apps Next)

Quando o turno tocou em provider, context, layout root, barrel de package ou next.config de apps/web ou apps/admin, antes de declarar pronto rode npx madge --circular --extensions ts,tsx apps/web (e apps/admin). Se aparecer ciclo de valor envolvendo *Provider.tsx, aplique o padrao P1 de AI_CONTEXT/regras-tecnicas/tdz-patterns.md sem perguntar (extrair Context+hooks para *Context.ts separado).

Razao: TDZ ('Cannot access X before initialization') e erro de runtime em standalone (Docker/prod). Build local pode compilar feliz e subir imagem quebrada. O hook pre-push-validate.js bloqueia push/deploy nesse caso.

Commits

Voce sempre cria o commit (depois de perguntar ao usuario). Mensagem segue padroes do repo (git log --oneline -10 pra ver estilo).

Areas nao sensiveis: mensagem curta tipo fix(area): descricao.

Areas sensiveis: corpo obrigatorio explicando o que mudou, por que, impacto cross-stack e o que NAO foi alterado (pra deixar o escopo claro). Trailer: Co-Authored-By: Claude Opus 4.8 (1M context) <[e-mail]>.

Documentacao em roadmap/

O roadmap/ e memoria externa entre sessoes. Crie/atualize entrada para: mudancas em areas sensiveis, features medias/grandes, decisoes arquiteturais, debt deixada conscientemente. Nao precisa para ajuste visual local ou bugfix de 1-2 linhas.

Template de entrada nova:

# <Titulo curto> — YYYY-MM-DD

## Contexto
Por que isso foi feito, qual problema resolve.

## O que foi feito
- Arquivo X: o que mudou
- Arquivo Y: o que mudou

## Decisoes
- Decisao + por que

## Gotchas / pontos abertos
- O que ficou pra depois

## Como verificar
1-3 passos pra confirmar manualmente.

Atualize o indice do roadmap/ apontando pro novo arquivo.

Comunicacao de entrega

1. Em uma frase: o que ficou diferente na tela/comportamento.
2. Em uma frase: o que NAO foi mexido (pra tranquilizar).
3. Se criou/atualizou doc em roadmap/, mencione.
4. Pergunte: "quer que eu faca o commit dessa mudanca?".

O que voce NAO faz neste modo

• Nao faz refactor amplo "de quebra" (mas pode oferecer como passo separado).
• Nao apaga codigo "morto" sem perguntar.
• Nao roda migrations sem confirmacao dupla.
• Nao roda comandos destrutivos (reset, force push, drop, rm).
• Nao mergeia nem pushe sem o usuario pedir explicitamente.
• Nao pergunta coisa tecnica que o usuario nao tem como responder.