Claude Code como ferramenta de desenvolvimento

01. O setup que faz diferença

Voce ja 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. E um arquivo que fica na raiz do projeto e fala pro Claude Code: "aqui a gente trabalha assim". Tipo quando voce entra numa empresa nova e alguem te passa o "jeito da casa". So que pro agente de IA.

No meu, eu coloco convencao de nomes (componentes em PascalCase, arquivos em kebab-case), ordem de imports, como tratar erros, formato de commits. Parece burocracia, mas e o contrario. Sem isso, cada resposta sai de um jeito. Com isso, o codigo 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 nao da conta de tudo. Tem coisa que so faz sentido em contexto especifico. Pra isso existe a pasta .claude/rules/. Voce cria arquivos de regra dizendo em quais pastas ela se aplica. Regras de banco so carregam quando o Claude ta mexendo em migracao. Regras de CI/CD so aparecem na pasta de infraestrutura. Isso economiza contexto (que e limitado) e evita confusao.

E tem os MCP servers. MCP e um protocolo que conecta o Claude a ferramentas externas. Eu uso Playwright pra testar interface no navegador, Context7 pra puxar documentacao atualizada de libs, e EXA pra pesquisa web. E tipo dar ferramentas extras pro Claude. Ele deixa de depender so do que sabe de cabeca.

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

Essa e a parte que mais gente erra. Bate uma vontade enorme de jogar tudo pro Claude e ir tomar cafe. "Faz a arquitetura do sistema", "decide qual banco usar". Nao. Isso e decisao sua.

Pensa assim: a IA e tipo um mecanico muito rapido e habilidoso. Mas quem decide qual peca trocar e voce, que conhece o carro. Se voce pede pro mecanico decidir sozinho, ele ate troca. Mas pode colocar uma peca que nao aguenta a pressao.

Eu tenho uma regra no meu setup chamada "No Invention" (sem invencao). Toda feature precisa apontar pra um requisito documentado. Se nao tem requisito, nao implementa. Sabe aquela historia? Voce pede um formulario de login e a IA volta com login, cadastro, recuperacao de senha, autenticacao por biometria e integracao com 3 redes sociais. Ninguem pediu isso.

Delego tranquilo: implementacao quando a spec ta clara, testes unitarios, refatoracao 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 consequencia), e seguranca (RLS, autenticacao, autorizacao). Essas decisoes precisam de contexto de negocio que a IA simplesmente nao tem.

03. O que funciona de verdade

Story-driven.Toda tarefa comeca com um documento. Nao e um prompt jogado no chat. E um arquivo com contexto, criterios de aceite, lista de arquivos. E tipo pedir comida por delivery: se voce fala so "manda uma pizza", pode vir qualquer coisa. Se voce fala "margherita, massa fina, sem azeitona, cortada em 8", chega o que voce quer. A story e o pedido detalhado.

Agent handoff com compactacao. 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 so o essencial. Depois de duas trocas, o contexto usado e 57% menor. Sessoes mais longas, respostas mais precisas.

Quality gates automaticos. Antes de qualquer push, roda lint (verificacao de estilo), typecheck (tipos do TypeScript), testes e revisao automatica. Falhou? Nao passa. Tipo catraca de metro. Sem bilhete, sem entrada.

Boundary protection. Tenho regras que impedem o Claude de editar certos arquivos core. E tipo trancar o quadro de energia do predio. O eletricista mexe na fiacao do seu apartamento, mas no quadro geral so com autorizacao especial.

04. O que nao funciona

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

Nao revisar codigo. So porque compilou e passou nos testes nao quer dizer que ta certo. A IA adora criar abstracao desnecessaria. Faz um wrapper em cima de wrapper em cima de outro wrapper. Compila? Compila. Funciona? Funciona. Mas ninguem vai entender isso daqui 3 meses.

Sessoes longas sem compactar.O Claude Code tem uma janela de contexto limitada. Conforme a conversa cresce, as coisas do inicio ficam "borradas". E tipo sua mesa de trabalho: se voce nao organiza, uma hora nao acha mais nada. O /compact resolve. Eu uso a cada 30-40 minutos.

Pedir opiniao."O que voce acha de usar Redis aqui?" e convite pra resposta generica. "Implementa cache com Redis seguindo esse padrao" e instrucao clara. A IA funciona muito melhor como executor do que como consultor.

05. A produtividade real

Se alguem te falar que IA da ganho de 10x, desconfia. No meu caso, com setup maduro e meses de refinamento, o ganho fica entre 2x e 3x. E olha, 2x ja e absurdo. E entregar em uma semana o que antes levava duas.

Mas esse 2-3x nao vem de graca. Vem do CLAUDE.md bem escrito. Das regras organizadas. Das stories detalhadas. Dos quality gates. De voce saber o que delegar e o que decidir sozinho.

Pensa numa furadeira boa. Ferramenta potente, faz furo perfeito em qualquer material. Mas se voce nao sabe escolher a broca certa, nao marca o ponto antes, o resultado e um buraco torto feito muito rapido.

Claude Code e a furadeira. Voce e quem segura. O CLAUDE.md e o manual. As stories sao as marcacoes na parede. Os quality gates sao o nivel de bolha. Tira qualquer peca dessa e o resultado cai.

A ferramenta e poderosa. Mas ferramenta poderosa na mao de quem nao se preparou e so uma forma mais rapida de fazer besteira. O segredo nao e o prompt. E tudo que vem antes dele.