Por que o Claude Code responde melhor em um projeto do que em outro?

Fala aí, beleza? Você abre o Claude Code no seu projeto e ele acerta de primeira

Abre no projeto do colega, mesma assinatura, mesmo modelo, e ele começa a chutar arquivo que não existe, repetir decisão errada e entregar aquele código que "quase" funciona

A conclusão fácil seria culpar o modelo

Só que raramente é isso: o agente devolve o que ele consegue LER, e um repositório opaco entrega leitura ruim na entrada

Como o Claude Code enxerga um projeto (e por que isso muda tudo)

O Claude Code navega o repositório como um desenvolvedor faria: percorre o sistema de arquivos, lê arquivos, usa grep pra achar o que precisa e segue as referências pelo código

Sem índice prévio, se liga nisso

Ele roda localmente na tua máquina e não exige que um índice do código seja construído, mantido ou enviado pra um servidor

Isso é bem diferente de ferramentas baseadas em RAG, que embedam a base inteira e podem refletir um estado ANTIGO do código

Aqui a leitura é ao vivo, do arquivo que está lá agora

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

E aí vem a ponte que interessa: se ele descobre teu projeto lendo, tudo que atrapalha a leitura vira informação errada na entrada

Nome de função que mente sobre o que ela faz, ausência de tipo pra ancorar a assinatura, README que descreve um projeto que não existe mais

A Anthropic é direta nesse ponto: a qualidade da navegação do Claude é moldada por como a base de código está preparada, com contexto em camadas via arquivos CLAUDE.md e skills

Ou seja, o Claude Code contexto do projeto não é uma configuração escondida em algum menu, é o teu próprio repositório

Sinais de que o problema é o repositório, não o modelo

Antes de trocar de ferramenta, olha se algum desses sintomas é o teu caso

Sintoma 1: ele "quase acerta" e VOCÊ vira o revisor de cada erro

A causa costuma ser simples: não existe nenhuma checagem que ele mesmo possa rodar

Sem um check executável, o único sinal disponível é o resultado PARECER pronto, e a pessoa vira o loop de verificação

Como prevenir: dá pra ele uma verificação que rode sozinha (testes, build, linter, script que compara a saída com uma fixture, screenshot comparado com o design)

Com um sinal de passa ou falha, ele roda, lê o resultado e itera até passar

Se teu projeto não tem suíte nenhuma, começar é mais barato do que parece: dá até pra pedir os testes automatizados pro próprio Claude Code e usar isso como o sinal que faltava

Sintoma 2: as respostas pioram conforme o projeto cresce

Esse é traiçoeiro porque no começo tudo funcionava bem

A causa: conforme a base cresce, padrões calibrados pra projetos pequenos podem encher a janela de contexto com instruções e leituras de arquivo sem relação nenhuma com a tarefa

Isso gasta token e degrada o desempenho do Claude

Como prevenir: contexto em camadas em vez de um monte de instrução global, e exploração de base grande delegada a um subagente, pra só os ACHADOS voltarem ao contexto principal

Sintoma 3: ele repete decisão que você já corrigiu ontem

Causa: nada persiste entre as sessões

São dois os mecanismos que levam conhecimento de uma conversa pra outra: os arquivos CLAUDE.md escritos por você e a auto memory, que são notas que o próprio Claude escreve a partir das tuas correções e preferências

Os dois são carregados no início de cada conversa

Como prevenir: escrever a correção no CLAUDE.md na hora que ela acontece, em vez de repetir a mesma bronca toda sessão 😀

Projeto preparado x projeto opaco: o que muda na prática

Repara que nenhuma linha dessa tabela fala do modelo

É tudo estrutura, e tudo está na tua mão

O que arrumar no seu projeto para colher respostas melhores

Bora ver na prática? A ordem abaixo é do mais barato pro mais elaborado

1. Gere o primeiro CLAUDE.md com o /init

O comando analisa o projeto e gera um arquivo inicial

/init

O erro comum deste passo: aceitar o que saiu e nunca mais olhar

O /init gera, o /memory refina

/memory

2. Coloque o arquivo no lugar que o Claude Code procura

O CLAUDE.md de projeto pode ficar em ./CLAUDE.md ou em ./.claude/CLAUDE.md

O erro comum: inventar um caminho "organizadinho" fora desses dois e depois achar que o agente ignorou a instrução

3. Confirme que ele carregou mesmo

Não adianta supor, roda na sessão e confere a lista em Memory files

/context

O erro comum: debugar comportamento por meia hora sem antes checar se o arquivo entrou

4. Escreva ali o que o código não conta sozinho

A documentação recomenda incluir comandos de bash, estilo de código e regras de fluxo de trabalho

É contexto persistente que ele não consegue inferir só olhando os arquivos

O erro comum: transformar o arquivo num README duplicado, repetindo o que qualquer leitura já revelaria

5. Dê uma checagem que ele possa rodar sozinho

Testes, build, linter, script que compara a saída com uma fixture, screenshot comparado com o design

Qualquer coisa que devolva passa ou falha serve

O erro comum: ter o comando e não dizer qual é

Se o npm test do teu projeto exige uma flag específica, isso mora no CLAUDE.md

6. Instale um LSP pra ele navegar por significado, não por texto

Existem plugins oficiais de code intelligence no marketplace da Anthropic que habilitam a ferramenta LSP do Claude Code, com ida para definição, busca de referências e erros de tipo logo depois das edições

O marketplace oficial (claude-plugins-official) é adicionado automaticamente pelo Claude Code na primeira vez que ele é iniciado em modo interativo

/plugin install typescript-lsp@claude-plugins-official

O plugin de TypeScript cobre .ts, .tsx, .js, .jsx, .mts, .cts, .mjs e .cjs, e ativa automaticamente quando você trabalha com esses arquivos

O erro comum deste passo, e esse pega MUITA gente: o plugin configura a conexão com um language server, mas não inclui o servidor

O binário do language server precisa ser instalado separadamente

7. Automatize o que você não quer pedir toda vez

Um hook PostToolUse pode rodar o formatador automaticamente a cada alteração de arquivo, já que ele dispara em toda chamada de ferramenta dentro do loop do agente

E o hook Stop pode bloquear o encerramento do turno, exigindo por exemplo que a suíte de testes passe antes de continuar

Pra isso ele devolve um JSON assim:

{"decision": "block", "reason": "a suíte de testes precisa passar antes de encerrar"}

O erro comum: começar pelos hooks

Hook é o último degrau, não o primeiro

Monorepo, base grande e onde você abre o terminal

Tem um detalhe que quase ninguém trata como decisão técnica: o lugar onde você executa o comando claude

Ele determina quais arquivos o Claude pode ler e editar sem permissão extra, quais CLAUDE.md entram no contexto na inicialização e quais configurações de projeto valem

Em monorepo isso fica bem visível

Ao iniciar a partir de packages/api/, ele carrega o packages/api/CLAUDE.md e o CLAUDE.md da raiz, sem trazer as instruções de packages/web/ pro contexto

O carregamento é aditivo: arquivos CLAUDE.md e CLAUDE.local.md na hierarquia ACIMA do diretório de trabalho entram por inteiro na inicialização, e os que estão em subpastas carregam sob demanda, quando o Claude lê arquivos daquelas pastas

E o que é comum a todo mundo vai pra raiz: skills compartilhadas por vários diretórios (convenções de PR, checklist de deploy, essas coisas) podem ficar em .claude/skills/ na raiz do repositório, pra carregarem a partir de qualquer diretório de origem

Esse mesmo raciocínio de escopo vale quando você precisa alternar entre dois projetos sem misturar contexto, beleza?

Em base grande, soma isso com a dica da doc de delegar a exploração a um subagente

Assim a janela principal recebe o achado, não o passeio inteiro pelo repositório

O que apareceu quando o projeto chegou pronto para o agente

No vídeo abaixo eu levo essa mesma ideia pra um caso extremo: um projeto que nem existia ainda

Antes de abrir o Claude Code, eu montei o contexto do produto no NotebookLM, alimentando com fontes: artigos, docs, concorrentes que eu já conhecia, pesquisa própria salva em arquivo de texto, sites, vídeos e PDFs

E aqui vale a parte chata: a busca devolve fonte boa e fonte ruim, e o meu papel foi abrir cada uma e descartar as ruins, porque fonte ruim piora a resposta

Mesma lógica do repositório, né? Entrada ruim, saída ruim

Depois eu conversei com o notebook pedindo pra ele pensar como product manager e dizer o que não podia faltar na V1, focando na dor principal e no que diferencia do que já existe

Salvei as respostas boas em observações, porque o histórico da conversa se perde

Quando o primeiro prompt saiu raso, eu pedi de novo e veio um bem maior

Aí eu troquei a ideia de prompt gigante por um PRD: prompt muito grande pode fazer o Claude Code atrapalhar alguma coisa, e o PRD tem a vantagem de virar ARQUIVO e ser referenciado

Pedi um PRD do MVP com páginas, funcionalidades essenciais, jornada do usuário, stack, design system e o resto que ajudasse o Claude Code a entender o projeto

O PRD já sai formatado em Markdown, então foi copiar, tirar a primeira linha de introdução da resposta e salvar como prd.md dentro do projeto

Só então eu abri o Claude Code numa pasta EM BRANCO e pedi o MVP referenciando o prd.md junto do prompt inicial

A diferença que eu sinto é essa: pedir direto pra IA tende a gerar projetos muito parecidos entre si

O contexto construído antes é o que dá diferencial real ao produto

E não acabou no MVP: eu trato a V1 como coisa pra colocar no mercado e volto ao notebook pra novas perguntas e novos prompts a cada iteração

Assiste ali principalmente a parte da curadoria das fontes e o momento em que o PRD vira arquivo no projeto: é onde o "contexto" deixa de ser papo e vira algo que o agente consegue ler

Por onde começar hoje

A tese é essa e ela é meio incômoda: o agente devolve o que ele consegue ler

Se o teu repositório não conta nada sobre si mesmo, o Claude Code vai preencher as lacunas com suposição, e suposição errada custa o teu tempo de revisão

Não precisa refatorar o mundo hoje

Roda o /init, confere no /context se o arquivo entrou de verdade e adiciona UMA checagem que o Claude possa rodar sozinho

Esse último passo é o que a Anthropic aponta como o de maior peso: dar ao Claude uma forma de verificar o próprio trabalho melhora de forma marcante a qualidade do resultado final

Depois disso a gente conversa sobre LSP, hooks e monorepo…

até o próximo post! 😀