Claude Code como ferramenta de desenvolvimento

01. O setup que faz diferença

Você já abriu um projeto e cada arquivo parecia que foi escrito por uma pessoa diferente? Um usa camelCase, outro snake_case, um importa de um jeito, outro de outro. Uma zona total.

O CLAUDE.md resolve isso. É um arquivo que fica na raiz do projeto e fala pro Claude Code: "aqui a gente trabalha assim". Tipo quando você entra numa empresa nova e alguém te passa o "jeito da casa". Só que pro agente de IA.

No meu, eu coloco convenção de nomes (componentes em PascalCase, arquivos em kebab-case), ordem de imports, como tratar erros, formato de commits. Parece burocracia, mas é o contrário. Sem isso, cada resposta sai de um jeito. Com isso, o código sai padronizado desde a primeira linha.

Convenções de Nomenclatura:
- Componentes: PascalCase (WorkflowList)
- Hooks: prefixo use (useWorkflowOperations)
- Arquivos: kebab-case (workflow-list.tsx)
- Constantes: SCREAMING_SNAKE_CASE (MAX_RETRIES)

Imports: sempre absolutos com @/
import { useStore } from '@/stores/feature/store'  // certo
import { useStore } from '../../../stores/store'    // errado

Mas o CLAUDE.md sozinho não dá conta de tudo. Tem coisa que só faz sentido em contexto específico. Pra isso existe a pasta .claude/rules/. Você cria arquivos de regra dizendo em quais pastas ela se aplica. Regras de banco só carregam quando o Claude tá mexendo em migração. Regras de CI/CD só aparecem na pasta de infraestrutura. Isso economiza contexto (que é limitado) e evita confusão.

E tem os MCP servers. MCP é um protocolo que conecta o Claude a ferramentas externas. Eu uso Playwright pra testar interface no navegador, Context7 pra puxar documentação atualizada de libs, e EXA pra pesquisa web. É tipo dar ferramentas extras pro Claude. Ele deixa de depender só do que sabe de cabeça.

02. O que eu deixo a IA fazer (e o que não deixo)

Essa é a parte que mais gente erra. Bate uma vontade enorme de jogar tudo pro Claude e ir tomar café. "Faz a arquitetura do sistema", "decide qual banco usar". Não. Isso é decisão sua.

Pensa assim: a IA é tipo um mecânico muito rápido e habilidoso. Mas quem decide qual peça trocar é você, que conhece o carro. Se você pede pro mecânico decidir sozinho, ele até troca. Mas pode colocar uma peça que não aguenta a pressão.

Eu tenho uma regra no meu setup chamada "No Invention" (sem invenção). Toda feature precisa apontar pra um requisito documentado. Se não tem requisito, não implementa. Sabe aquela história? Você pede um formulário de login e a IA volta com login, cadastro, recuperação de senha, autenticação por biometria e integração com 3 redes sociais. Ninguém pediu isso.

Delego tranquilo: implementação quando a spec tá clara, testes unitários, refatoração com escopo definido, e tarefas repetitivas tipo gerar boilerplate.

Nunca delego: modelagem de dados (a estrutura do banco define o destino do projeto), trade-offs de arquitetura (cada escolha tem consequência), e segurança (RLS, autenticação, autorização). Essas decisões precisam de contexto de negócio que a IA simplesmente não tem.

03. O que funciona de verdade

Story-driven.Toda tarefa começa com um documento. Não é um prompt jogado no chat. É um arquivo com contexto, critérios de aceite, lista de arquivos. É tipo pedir comida por delivery: se você fala só "manda uma pizza", pode vir qualquer coisa. Se você fala "margherita, massa fina, sem azeitona, cortada em 8", chega o que você quer. A story é o pedido detalhado.

Agent handoff com compactação. Uso agentes especializados: um pra criar, outro pra implementar, outro pra testar. Quando troco de agente, o sistema compacta o contexto anterior num resumo de ~379 tokens e passa só o essencial. Depois de duas trocas, o contexto usado é 57% menor. Sessões mais longas, respostas mais precisas.

Quality gates automáticos. Antes de qualquer push, roda lint (verificação de estilo), typecheck (tipos do TypeScript), testes e revisão automática. Falhou? Não passa. Tipo catraca de metrô. Sem bilhete, sem entrada.

Boundary protection. Tenho regras que impedem o Claude de editar certos arquivos core. É tipo trancar o quadro de energia do prédio. O eletricista mexe na fiação do seu apartamento, mas no quadro geral só com autorização especial.

04. O que não funciona

Pedir sem explicar."Faz um dashboard bonito." Bonito como? Com quais dados? Pra quem? Se o prompt é vago, o resultado é vago. Toda vez que tive retrabalho foi porque achei que "tava óbvio". Spoiler: nunca tá óbvio.

Não revisar código. Só porque compilou e passou nos testes não quer dizer que tá certo. A IA adora criar abstração desnecessária. Faz um wrapper em cima de wrapper em cima de outro wrapper. Compila? Compila. Funciona? Funciona. Mas ninguém vai entender isso daqui 3 meses.

Sessões longas sem compactar.O Claude Code tem uma janela de contexto limitada. Conforme a conversa cresce, as coisas do início ficam "borradas". É tipo sua mesa de trabalho: se você não organiza, uma hora não acha mais nada. O /compact resolve. Eu uso a cada 30-40 minutos.

Pedir opinião."O que você acha de usar Redis aqui?" é convite pra resposta genérica. "Implementa cache com Redis seguindo esse padrão" é instrução clara. A IA funciona muito melhor como executor do que como consultor.

05. A produtividade real

Se alguém te falar que IA dá ganho de 10x, desconfia. No meu caso, com setup maduro e meses de refinamento, o ganho fica entre 2x e 3x. E olha, 2x já é absurdo. É entregar em uma semana o que antes levava duas.

Mas esse 2-3x não vem de graça. Vem do CLAUDE.md bem escrito. Das regras organizadas. Das stories detalhadas. Dos quality gates. De você saber o que delegar e o que decidir sozinho.

Pensa numa furadeira boa. Ferramenta potente, faz furo perfeito em qualquer material. Mas se você não sabe escolher a broca certa, não marca o ponto antes, o resultado é um buraco torto feito muito rápido.

Claude Code é a furadeira. Você é quem segura. O CLAUDE.md é o manual. As stories são as marcações na parede. Os quality gates são o nível de bolha. Tira qualquer peça dessa e o resultado cai.

A ferramenta é poderosa. Mas ferramenta poderosa na mão de quem não se preparou é só uma forma mais rápida de fazer besteira. O segredo não é o prompt. É tudo que vem antes dele.