Existe um arquivo que a IA do seu time de desenvolvimento lê antes de qualquer tarefa e você provavelmente nunca ouviu falar dele

Para: QAs, PMs, POs, Designers e qualquer pessoa que trabalha com times que usam IA no desenvolvimento.

Você já esteve numa review olhando para uma entrega e pensando "como assim a IA fez isso? quem pediu isso aqui?"

Provavelmente ninguém pediu. E a causa, na maioria das vezes, é um arquivo que o time inteiro ignora — ou nem sabe que existe.

Ele se chama CLAUDE.md.

O que é isso, afinal?

Toda vez que um dev usa o Claude Code, a IA começa a sessão lendo esse arquivo antes de qualquer coisa. Ele fica na raiz do projeto e funciona basicamente como um briefing — aquele documento que você prepara quando um freelancer entra no projeto e precisa entender o contexto antes de começar.

Sem o briefing, o freelancer decide sozinho. Às vezes acerta. Às vezes entrega algo que faz sentido pra ele, mas não pra ninguém mais no time.

Com um CLAUDE.md bem escrito, a IA sabe o que o produto é, pra quem é, o que não pode ser mexido e qual é o padrão de qualidade que o time espera. Ela trabalha dentro de limites reais, não de suposições.

Pense assim: é o Definition of Done do time, só que a IA lê antes de cada tarefa — não só o dev.

"Mas isso não é coisa de dev?"

É aqui que a maioria dos times erra feio.

Boa parte do que deveria estar no CLAUDE.md não é decisão técnica. É decisão de produto, de processo, de qualidade, de como a experiência precisa funcionar. E esse conhecimento não mora na cabeça do dev — mora na sua.

Perfil	O que só você sabe
🔍 QA	O que significa "pronto", o que não pode ser quebrado, quais estados precisam de teste
🗺️ PM	Quem é o usuário, o que o produto otimiza, quais restrições não podem ser ignoradas
📋 PO	Quais critérios de aceite são inegociáveis, o que caracteriza regressão, o que nunca muda sem aprovação
🎨 Designer	Quais componentes existem, como os estados visuais funcionam, o que jamais pode ser substituído

Se nenhum de vocês colocar isso no arquivo, a IA vai inventar. E inventar, nesse contexto, tem um nome mais familiar: bug em produção.

As seções que merecem a sua atenção

Um bom CLAUDE.md pode ter até 10 seções. Algumas são mesmo técnicas — stack, arquitetura, comandos de terminal — e essas o dev resolve. Mas tem pelo menos cinco onde a sua contribuição faz diferença de verdade. São essas que a gente vai ver agora.

Visão geral do produto — PM e PO

Parece óbvio. E justamente por isso quase ninguém preenche direito.

A maioria dos projetos tem essa seção vazia ou com frases genéricas que poderiam descrever qualquer produto do mundo. A IA precisa de contexto real pra tomar boas decisões — sem ele, ela otimiza para o que ela imagina que faz sentido, que nem sempre é o que o produto precisa.

Veja a diferença:

❌ Vago — a IA vai adivinhar:

"App de gestão financeira pessoal"

✅ Útil — a IA vai se alinhar:

"App de controle de gastos para famílias de classe média. Prioridade: simplicidade na entrada de dados e visibilidade rápida do saldo disponível. Usuário principal: responsável financeiro do lar, 30–50 anos, sem formação em finanças."

A diferença de resultado entre esses dois é enorme.

💡 Escreva como se estivesse explicando o produto pra alguém que entrou no time hoje. Sem histórico da empresa, sem pitch de venda — só o que importa pra quem vai construir.

Convenções e padrões — QA e PO

Essa seção vai além do estilo de código. Ela cobre como o produto se comporta de verdade: como os erros aparecem pro usuário, como as telas são nomeadas, o que acontece quando um dado chega vazio ou inválido.

Sabe aquele critério de aceite que você escreve em toda história porque sempre vira problema se não estiver explícito? Ele provavelmente deveria estar aqui — de forma permanente, lida pela IA antes de qualquer entrega, sem precisar ser repetido toda sprint.

Alguns exemplos do que o QA e o PO podem trazer pra essa seção:

• Como mensagens de erro devem ser redigidas pro usuário final
• Nomes padronizados de telas e funcionalidades
• O que a IA deve fazer quando um dado está ausente, inválido ou em estado inesperado

💡 Se você se pega escrevendo o mesmo critério de aceite sprint após sprint, isso é um sinal claro de que ele pertence ao CLAUDE.md.

UI e design system — Designer, PM e PO

Essa é a seção que mais dói quando está em branco. E, curiosamente, é a que o designer tem mais condições de preencher.

Sem ela, a IA pode criar um botão novo porque simplesmente não sabia que já existia um. Pode usar um espaçamento que parece razoável isolado, mas quebra o ritmo do sistema inteiro. Pode entregar um formulário sem label porque achou que o placeholder era suficiente. Pequenas decisões que, somadas, fazem a interface perder consistência sem que ninguém consiga apontar exatamente onde o problema começou.

O que colocar aqui:

• Quais componentes existem e devem ser usados — com os nomes exatos
• Como os estados de interface funcionam: loading, erro, vazio, sucesso
• Regras de espaçamento e hierarquia visual
• Requisitos de acessibilidade que não têm exceção
• O que absolutamente não pode ser substituído ou recriado do zero

❌ O que não funciona:

"Deixe o design moderno"

✅ O que funciona:

"Use os componentes do design system existente. Não crie variações de botão fora dos tipos primary, secondary e ghost. Espaçamento segue ritmo de 8px. Todo campo de formulário deve ter label visível — nunca use só placeholder."

💡 Designer, não espere o dev perguntar o que fazer. As regras do seu Figma já existem — só precisam estar nesse arquivo também. Se você tem uma página de componentes no design system, parte dela já é o CLAUDE.md de UI esperando pra ser escrito.

Testes e critérios de qualidade — QA

Essa seção define o que "pronto" significa de fato. Sem ela, a IA define por conta própria — e o padrão dela pode não ter nada a ver com o do seu time.

Se não estiver escrito	Se estiver escrito
IA entrega o código sem testes	IA verifica tipagem, lint e testes antes de fechar a tarefa
Estado de erro fica sem tratamento	IA valida os estados: vazio, carregando e erro sempre que faz sentido
Critérios de aceite são ignorados	IA segue a lista de qualidade definida pelo QA

💡 Liste os tipos de teste que devem existir pra cada tipo de funcionalidade e inclua também as regras de negócio críticas que precisam de cobertura — não só a lógica técnica. A IA vai seguir essa lista em todas as entregas.

Regras de mudanças seguras — PO, QA, PM e Designer

Essa é provavelmente a mais importante de todas pra quem cuida do produto.

Ela diz à IA o que ela não pode tocar sem aviso — e é exatamente o tipo de coisa que ninguém lembra de escrever até que uma regressão silenciosa vai parar em produção numa sexta à tarde.

Alguns exemplos do que isso evita:

Sem a regra	Com a regra
IA altera o cálculo de desconto progressivo e o resultado muda pro usuário sem ninguém perceber	"Não modificar lógica de cálculo de preço ou desconto sem sinalização explícita ao time"
IA reorganiza o fluxo de checkout e remove uma etapa de confirmação obrigatória	"Preservar todas as etapas do fluxo de compra. Nenhuma pode ser removida sem aprovação do PO"
IA troca um componente de input e quebra as validações que já existiam	"Não substituir componentes do design system por variações customizadas sem aprovação do designer"
IA renomeia identificadores internos e quebra o rastreamento de analytics	"Não alterar nomes de eventos de analytics sem solicitação explícita"

💡 Pense nas piores regressões que já aconteceram no produto. Agora imagine alguém sem contexto tocando exatamente naquele ponto. Essa seção existe pra evitar exatamente isso.

Como contribuir sem precisar abrir o arquivo

Ninguém está pedindo pra você virar dev. Você pode alimentar o CLAUDE.md de formas que já fazem parte da sua rotina — é só saber o que sinalizar e pra quem.

Se você é PO ou QA: quando um critério de aceite aparece em várias histórias seguidas, sinalize pro tech lead que ele deveria estar no arquivo de forma permanente. Não precisa editar nada — só apontar.

Se você é QA: quando uma regressão séria aparece na retro, vale perguntar diretamente — "isso deveria estar nas regras de mudança segura?" Com o tempo essa pergunta vira hábito do time.

Se você é PM ou PO: a seção de visão geral do produto pode vir quase inteira do seu Product Brief. Compartilhe com o time de desenvolvimento e deixa eles adaptarem.

Se você é Designer: suas regras de Figma e a documentação de componentes já são o conteúdo da seção de UI. Não espere o dev interpretar o design sozinho — raramente vai sair como você imaginou.

Nas retrospectivas: quando a IA gerar algo inesperado, vale trazer pro time a pergunta: "o que faltou no CLAUDE.md pra evitar isso?" Com o tempo, o arquivo vai ficando cada vez mais preciso e o time vai gastando menos energia corrigindo o que a IA inventou.

Pra fechar

O CLAUDE.md não é um documento do time de desenvolvimento. É um documento de todo o time.

Quanto melhor for o contexto que todo mundo fornece pra IA, melhor vai ser o que ela entrega. Menos bugs, menos regressões, menos daquelas surpresas desagradáveis que aparecem no review sem que ninguém saiba explicar de onde vieram.

QAs, PMs, POs e Designers carregam um conhecimento que os devs não têm: o comportamento esperado do produto, as regras de negócio que não podem ser ignoradas, os padrões de qualidade que são inegociáveis, a identidade visual que não pode ser improvisada.

Esse conhecimento precisa estar no CLAUDE.md. E agora você sabe exatamente por quê.