Ambiente de trabalho com agente e navegador Trechos do capítulo. A explicação em português está na página. alexandrecaramaschi.com/educacao/frontends-com-vibecoding ### O que faz: instala o agente de linha de comando e abre a sessão no projeto ### Onde entra: terminal, na pasta do projeto que você quer editar ### Cuidado: a instalação é global; a sessão precisa ser aberta dentro do repositório npm install -g @anthropic-ai/claude-code claude ### O que faz: mantém o aplicativo no ar enquanto o agente grava arquivos ### Onde entra: um segundo terminal, aberto em paralelo com o do agente ### Cuidado: sem ele o navegador não recarrega sozinho e você perde o retorno imediato npm run dev ### O que faz: grava o ponto de retorno a cada tela que funciona ### Onde entra: terminal, depois de você revisar e aprovar a tela ### Cuidado: commit pequeno é o que torna a experimentação segura; commit grande esconde o que quebrou git commit -m "tela X funcionando" ### O que faz: escreve na memória do projeto a política de consultar a fonte oficial da biblioteca antes de gerar código ### Onde entra: arquivo CLAUDE.md, na raiz do repositório ### Cuidado: a segunda política existe porque nome de pacote plausível não é nome verificado ## Política de contexto de biblioteca Antes de gerar código de qualquer biblioteca de API extensa (componentes, gráficos, mapas, tabelas de dados, animação), verifique se há MCP ou skill oficial configurado no projeto. - Se HOUVER: consulte-o antes de escrever o código. Não improvise a API a partir da memória de treino. - Se NÃO houver: avise e proponha configurá-lo antes de prosseguir. ## Política de dependência nova - Não instale pacote cujo nome você não leu na documentação oficial ou no registro público. Nome plausível não é nome verificado. - Toda dependência nova entra em pedido separado, com a origem declarada. A documentação oficial do fornecedor é a fonte. A memória do modelo é o último recurso. ### O que faz: mede, em uma tarde, quanto retrabalho o contexto oficial da biblioteca poupa ### Onde entra: conversa com o agente, rodado duas vezes: uma com o contexto carregado e outra sem ### Cuidado: o pedido só vale rodado duas vezes; uma execução isolada não produz comparação nenhuma Rode o MESMO pedido duas vezes, uma com o contexto oficial da biblioteca carregado e outra sem ele, e conte quantos critérios de aceite cada versão cumpre de primeira, sem retrabalho. O número que sai daí é o mais convincente deste apêndice, porque mede exatamente quanto retrabalho o contexto poupa. Gere um painel de uma página com a biblioteca de gráficos já usada neste projeto, lendo este JSON de receita por canal e mês [cole seus dados aqui]: um gráfico de barras empilhadas (receita por canal ao longo dos meses) e um mapa de calor de coorte (retenção por mês de entrada). Critérios de aceite (verifique cada um antes de me devolver): 1. Use a API ATUAL da biblioteca, conferida no contexto oficial carregado. Não use sintaxe de versão anterior nem invente nome de método. 2. Eixos com título e unidade; sem sobreposição de rótulos. 3. Paleta categórica com contraste AA que NÃO dependa só de cor (rótulo direto na série ou padrão distinguível). 4. Dica de valor navegável por teclado e uma tabela alternativa com os mesmos dados. 5. Responsivo; o gráfico não pode inicializar em contêiner de largura zero. 6. Zero valor de cor escrito à mão: consuma os tokens do projeto via var(--...). Ao terminar, liste quais dos 6 critérios você cumpriu de primeira e cite, para cada método usado, onde ele aparece no contexto oficial que você consultou. Resultado esperado: duas contagens comparáveis, do tipo "4 de 6 sem contexto, 6 de 6 com contexto", e a lista dos métodos que a versão sem contexto inventou. ### O que faz: serve de molde para a memória do projeto, com regras conferíveis em vez de frases genéricas ### Onde entra: arquivo CLAUDE.md, na raiz do repositório ### Cuidado: troque cada linha pela realidade do seu projeto e mantenha o arquivo entre 40 e 60 linhas, porque cada linha é cobrada como contexto # CLAUDE.md ## Stack - Next.js 16 (App Router) + React 19 + TypeScript estrito - Tailwind v4; tokens em src/styles/tokens.css (cores em OKLCH) - Sem bibliotecas de UI externas; primitivas headless via Radix quando precisar de a11y não trivial ## Regras de frontend (PISO, não negociável) - Contraste WCAG AA mínimo: 4.5:1 texto normal, 3:1 texto grande - Cor SEMPRE via token var(--color-*); nunca hex espalhado no JSX - Todo componente interativo tem foco visível (focus-visible:ring-2) - Toda lista trata o estado vazio; todo fetch trata loading e erro - Texto secundário: text-slate-600 (NUNCA slate-400 sobre branco) ## Comandos - Dev: npm run dev (porta 3000) - Qualidade: npm run verify (tsc + lint + test) antes de cada commit - Build de produção: npx next build ## Convenções - Componentes em src/components, um arquivo por componente, export nomeado - Mensagens de commit em inglês, no imperativo ### O que faz: manda o agente ler o projeto e escrever o retrato dele, marcando três regras para você revisar ### Onde entra: conversa com o agente, numa sessão aberta na raiz do repositório ### Cuidado: as três regras marcadas para revisão são a parte útil, porque revelam o que o código já fazia sem ninguém ter decidido Leia a estrutura deste projeto (package.json, tsconfig, a pasta src e os arquivos de estilo) e crie um CLAUDE.md na raiz com: 1. A stack real que você detectou (framework, versões, sistema de estilo). 2. Os comandos de dev, lint, teste e build que existem no package.json. 3. As convenções que você conseguir inferir do código já escrito (estrutura de pastas, padrão de export, sistema de tokens de cor). 4. Uma seção "Regras de frontend" com o piso de acessibilidade: contraste WCAG AA, foco visível, estado vazio em listas, loading e erro em todo fetch. Não invente convenções que o código não mostra. Para cada regra, deixe-a concreta e verificável, não genérica. Ao terminar, liste as 3 regras que você acha que eu deveria revisar ou ajustar. Resultado esperado: um arquivo de 40 a 60 linhas e três regras marcadas para revisão. São essas três que revelam o que o código já fazia sem ninguém ter decidido. ### O que faz: transforma a auditoria de uma tela em atalho de fluxo, acionado por nome curto com a rota como argumento ### Onde entra: arquivo .claude/commands/auditar-tela.md, dentro do repositório ### Cuidado: o endereço local e a porta são os do exemplo; ajuste para os do seu projeto antes do primeiro uso --- description: Audita a tela aberta no browser MCP (contraste, console, teclado) e corrige --- Abra http://localhost:3000$ARGUMENTS no browser via MCP e: 1. Leia o console; aponte erros e warnings. 2. Meça o contraste de cada texto contra o fundo; cite valores abaixo de WCAG AA. 3. Teste navegação por teclado; confirme foco visível. 4. Corrija no código o que reprovar, reabra a tela e confirme que passou. Não altere o layout; ajuste só cores e o necessário para acessibilidade. ### O que faz: coloca um auxiliar escrevendo e outro auditando ao mesmo tempo, com as saídas separadas ### Onde entra: conversa com o agente, num projeto que já tem memória de projeto escrita ### Cuidado: cada auxiliar cobra o próprio contexto; dois é útil, meia dúzia é conta alta sem ganho proporcional Faça estas duas coisas EM PARALELO, cada uma num subagente próprio: Subagente 1 (escrever): crie o componente em React + Tailwind, com props { titulo, preco, destaque }, seguindo os tokens e regras do CLAUDE.md. Subagente 2 (auditar): abra a tela /precos no browser via MCP e audite contraste WCAG AA, foco por teclado e erros de console em TODOS os cards já existentes; liste cada reprovação com o valor medido e o seletor. Quando ambos terminarem, consolide: me mostre o novo componente e a lista de reprovações da auditoria, separadamente. Resultado esperado: duas saídas independentes na mesma janela de tempo, e nenhuma delas contaminada pelo caminho que a outra percorreu. ### O que faz: obriga o agente a investigar e propor o plano antes de tocar em qualquer arquivo ### Onde entra: conversa com o agente, antes de uma migração que atravessa muitos arquivos ### Cuidado: a lista dos casos sem equivalente é a que exige decisão sua; sem ela o agente escolhe por você e você descobre depois Entre em plan mode. Quero migrar todas as cores hardcoded (hex no JSX) para tokens var(--color-*). NÃO edite nada ainda. Primeiro: varra src/, liste cada arquivo com cor hardcoded e o token equivalente que você usaria, sinalize os hex que NÃO têm token (preciso decidir) e proponha a ordem de migração com os pontos de risco. Só depois que eu aprovar o plano você começa a editar. Resultado esperado: uma lista de arquivos com contagem, uma lista separada dos hex sem token equivalente e uma ordem de migração em que o projeto continua funcionando entre uma etapa e a seguinte.