Como usar o Claude Code em uma linguagem que você não domina sem aceitar código que não sabe revisar

Fala aí, beleza? O risco de pedir Go, Rust ou Elixir pro agente não é ele escrever errado

o risco é você dar merge em algo que não consegue ler

E isso é mais comum do que parece: uma pesquisa da Anthropic sobre uso real do Claude Code mediu a distribuição de linguagens nas consultas e viu JavaScript e TypeScript somando 31%, HTML e CSS somando mais 28%, e Python com 14%

Ou seja, existe uma faixa enorme de trabalho acontecendo fora dessas linguagens, com gente que não domina a stack em que está mexendo

Este post não é atalho pra confiar cego, é método de revisão: o que preparar antes, o que pedir ao agente pra conseguir auditar a saída, e quais sinais dizem "para aqui e estuda antes de aceitar"

O que preparar antes de abrir a primeira sessão na linguagem nova

Antes de pedir uma linha de código sequer, três coisas precisam existir

Sem elas, você não tem como saber se o que voltou presta

Um CLAUDE.md com as instruções do projeto:

O CLAUDE.md é um arquivo markdown com instruções persistentes, e ele é lido no início de toda sessão

Uma ressalva pra já deixar combinada: isso vale pra sua conversa principal

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

Existe uma exceção do lado dos SUBAGENTES, e ela tem nome e endereço: eu explico certinho no passo 3 lá embaixo

É ali no CLAUDE.md que moram as regras que você não quer repetir toda vez: convenções do projeto, o que não pode ser tocado, como rodar as coisas

Dá pra ter versão de projeto, de fluxo pessoal e de organização

Uma checagem que devolva pass/fail legível:

Essa é a parte que o pessoal pula, e é a mais importante quando a linguagem é nova pra você

A documentação de boas práticas é bem direta: dê ao Claude uma checagem que ele mesmo possa rodar

Qualquer coisa que devolva pass/fail legível serve: suíte de testes, exit code de build, linter ou um script seu

Sem isso, o Claude para quando o trabalho parece pronto

E aí quem vira o loop de verificação é você, justamente na linguagem que você não lê bem 😅

O modo de permissão que você vai usar:

Os modos de permissão disponíveis hoje incluem plan, auto, Manual, dontAsk e bypassPermissions

Escolha isso ANTES, não no meio da pressa

O /permissions configura as regras de aprovação da sessão, e regras Read em permissions.deny bloqueiam o Claude de abrir caminhos específicos, tipo um SDK vendorizado ou código gerado que foi commitado

Isso importa numa stack desconhecida: você não quer o agente aprendendo o "padrão do projeto" a partir de um monte de código gerado automaticamente

Se o seu problema é mais bloquear edições que você não pediu, a configuração de permissões é o lugar certo pra começar

E tem uma camada a mais: permissões e sandboxing são coisas diferentes, e a recomendação é usar as duas juntas

As permissões controlam quais ferramentas e caminhos o Claude usa

O sandboxing aplica restrição de sistema operacional ao acesso de filesystem e rede da ferramenta Bash, e continua valendo mesmo se uma prompt injection driblar a decisão do modelo

Passo a passo: o fluxo que te deixa revisar a saída do Claude Code

Bora ver na prática?

A lógica do fluxo é simples: você adia a edição o máximo possível e força o agente a te entregar racional e evidência pelo caminho

1. Entre em plan mode antes de qualquer coisa. No plan mode o Claude lê arquivos, explora e escreve um plano, mas as edições ficam bloqueadas até você aprovar

Dá pra entrar com Shift+Tab dentro da sessão, ou prefixando um prompt único com /plan

/plan mapeie como a autenticação é feita neste projeto e proponha onde a nova regra entraria

Se você já sabe que a sessão inteira é de exploração, comece por ela:

claude --permission-mode plan

O erro comum deste passo: aprovar o plano só porque ele "parece" coerente

Se você não consegue explicar a escolha do plano com suas palavras, você não leu o plano, você olhou o plano

2. Ligue o output style Explanatory. Ele insere "Insights" educativos durante a execução das tarefas, sobre escolhas de implementação e padrões do codebase

É literalmente o que você precisa numa linguagem nova: o porquê junto do código

A troca é feita pelo /config, na opção Output style, ou pela setting outputStyle

O erro comum deste passo: procurar o comando antigo

O /output-style isolado foi descontinuado na v2.1.73 e removido na v2.1.91, então ele simplesmente não está mais lá

Quando você escolhe pelo menu do /config no terminal, a seleção é salva em .claude/settings.local.json, no nível local do projeto

3. Use o subagente Explore pra mapear a base antes de decidir. O Explore é um subagente embutido, read-only, otimizado pra descoberta de arquivos, busca de código e exploração do codebase

Read-only aqui significa exatamente o que você quer no começo: ele olha, não mexe

Agora, a ressalva que eu te devia lá de cima: Explore e Plan são os únicos SUBAGENTES que não recebem o CLAUDE.md nem o git status

E atenção pra não confundir: aqui o "Plan" é o nome do subagente, não é o plan mode do passo 1

O plan mode da sua sessão continua normal, com o CLAUDE.md lido no início dela como sempre

O que fica de fora é o contexto DENTRO desses dois subagentes, enquanto eles trabalham

Mas calma, a conversa principal interpreta os resultados deles já com o CLAUDE.md carregado

E se você usa a versão v2.1.198 ou superior, o Explore herda o modelo da conversa principal em vez de rodar sempre em Haiku

4. Peça o racional, não só o código. Este é o passo que separa revisar de torcer

No prompt, exija três coisas: a explicação da escolha, as alternativas que foram descartadas e por quê, e os pontos de risco da mudança

antes de implementar: explique a escolha, liste as alternativas que você descartou
e diga qual foi o motivo de cada descarte, e aponte os pontos de risco dessa mudança

Com o Explanatory ligado, os Insights sobre escolhas de implementação e padrões do codebase vêm no meio do caminho, e aí você tem material pra discordar

É o mesmo princípio de escrever prompt sem ter design: quanto mais você especifica o que quer receber de volta, menos você aceita coisa que não sabe julgar

O erro comum deste passo: pedir explicação DEPOIS do código pronto

Aí a explicação vira justificativa, não decisão

5. Exija evidência, não afirmação de sucesso. "Funcionou" não é evidência

A recomendação da documentação de boas práticas é pedir a saída do teste, o comando que foi rodado e o que ele retornou, ou um screenshot do resultado

Revisar evidência é mais rápido que refazer a verificação inteira

O erro comum deste passo: você mesmo virar o loop de verificação, rodando tudo na mão numa linguagem que você ainda está aprendendo

6. Revise o diff com os comandos de review antes do commit. O /code-review revisa o diff atual procurando bugs de correção e limpezas

Ele aceita --fix pra aplicar os achados, e aceita um número de PR:

/code-review 1234

E o /security-review faz uma passada única sobre o diff da branch procurando vulnerabilidades, com explicação dos problemas encontrados:

/security-review

Rodar isso a partir do terminal, antes do commit, é bem mais barato que descobrir depois

7. Rode o /verify depois que a checagem automática passou. O /verify só roda quando você invoca explicitamente, ele não dispara sozinho

A recomendação é usar ele DEPOIS que o check automático passou, pra confirmar a mudança contra a aplicação rodando

Teste verde e app quebrado é uma combinação clássica, e numa linguagem nova você não tem o faro pra sentir isso no código

8. Saiba desfazer antes de precisar desfazer. O checkpointing captura o estado do código automaticamente: cada prompt que inicia um turno cria um checkpoint

Pra voltar, use /rewind ou pressione Esc duas vezes

Na hora de voltar, dá pra restaurar só o código, só a conversa, ou os dois

Só que já vou avisando aqui, pra você não confiar mais do que deve: ele guarda snapshots dos 100 checkpoints mais recentes da sessão e rastreia APENAS mudanças feitas pelas ferramentas Write, Edit e NotebookEdit

Edição que você fez na mão e efeito de comando bash ficam de fora dessa rede de proteção

O erro comum deste passo: tratar isso como backup

Já volto nesse ponto lá embaixo, porque ele engana muita gente 👀

Sinais de que você deve parar e estudar antes de aceitar o código

Cada sinal aqui é um "não dá merge ainda"

Você não consegue explicar por que a alternativa descartada era pior:

Sintoma: alguém te pergunta "por que não fizeram do outro jeito?" e você não tem resposta

Causa: o plano foi aprovado sem leitura dos Insights e sem o racional das alternativas

Solução: volta pro plan mode e pede o racional de novo, com as alternativas e os riscos explícitos, antes de qualquer edição

Como prevenir: deixar o Explanatory ligado por padrão enquanto a linguagem for nova pra você

O diff cresceu além do que você consegue ler:

Sintoma: você abre o diff, bate o olho e já sabe que não vai revisar aquilo linha a linha

Causa: tarefa grande demais pra uma sessão só, contexto entupido

Solução: rode o /context pra ver o que está ocupando a janela de contexto e fatie a tarefa em pedaços que caibam na sua revisão

Como prevenir: definir o tamanho do passo no plan mode, antes de liberar a edição

A mudança "parece" pronta mas não existe checagem pass/fail:

Sintoma: ninguém consegue dizer se está certo, só que está bonito

Causa: o projeto não tem suíte de testes, exit code de build, linter ou script que devolva pass/fail legível

Solução: parar a feature e criar a checagem primeiro, porque sem ela o Claude para quando o trabalho parece pronto

Como prevenir: tratar a checagem como pré-requisito da sessão, junto com o CLAUDE.md

Você está confiando no /rewind como se fosse backup:

Sintoma: "relaxa que dá pra voltar"

Causa: o checkpointing tem cobertura parcial e limite de retenção, igual eu falei no passo 8

Solução: usar git de verdade pro que importa, e o /rewind só pra desfazer passo recente

Como prevenir: lembrar de dois limites: ele guarda snapshots dos 100 checkpoints mais recentes da sessão, e rastreia APENAS mudanças feitas pelas ferramentas Write, Edit e NotebookEdit

Edição que você fez na mão e efeito de comando bash não entram nessa conta

Tome cuidado! Isso é exatamente o tipo de coisa que só dói quando já era

Comandos de leitura passando sem prompt te deram falsa sensação de controle:

Sintoma: "ele nem me pediu permissão, então não fez nada demais"

Causa: o Claude Code reconhece um conjunto embutido de comandos Bash como somente leitura e roda eles sem pedir permissão em todos os modos

A lista embutida inclui ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd e formas somente leitura do git

Solução: entender que silêncio ali significa leitura, não significa que nada mudou no projeto

Como prevenir: ler a documentação de permission modes e combinar permissões com sandboxing, em vez de inferir segurança pela ausência de prompt

Como ajustar o método conforme o tipo de tarefa

O fluxo completo nem sempre se paga

Se liga em como calibrar por cenário

Cenário 1: ler e entender uma base existente na linguagem nova

Aqui você não quer editar nada ainda

Abre a sessão com claude --permission-mode plan, joga o subagente Explore pra mapear arquivos e busca de código, e deixa o Explanatory ligado pra colher os Insights sobre os padrões do codebase

É leitura guiada, não implementação

Cenário 2: alterar código de produção que você vai manter

Aqui a checagem pass/fail deixa de ser recomendação e vira obrigação

E dá pra automatizar o feedback: um hook PostToolUse no .claude/settings.json com o matcher Edit|Write roda o linter depois de cada edição

O matcher usa a sintaxe de regra de permissão, então Edit(*.ts) limita o hook a arquivos TypeScript

Detalhe massa pra quem está em stack nova: o linter da linguagem vira seu segundo par de olhos enquanto o seu ainda está treinando 🙂

Cenário 3: revisar antes de abrir o PR

Passa /code-review (com o número do PR quando já existir) e /security-review sobre o diff da branch

E só então o /verify, contra a aplicação em execução

E quando o Explanatory vira ruído?

Quando você já domina aquele trecho, o texto educativo atrapalha mais do que ajuda

A troca continua sendo pelo /config ou pela setting outputStyle, beleza?

O próximo passo

A linguagem nova não é o obstáculo

O obstáculo é a ausência de um loop de verificação: sem checagem pass/fail e sem racional, qualquer código é um chute que você aceitou

Então o próximo passo é bem concreto: escolhe um projeto pequeno na stack que você não domina, escreve o CLAUDE.md, define a checagem que devolve pass/fail legível e abre a sessão assim:

claude --permission-mode plan

Dois detalhes pra fechar

A restauração do plan mode ao retomar uma conversa que terminou nele exige a v2.1.246 ou superior, então se isso não acontecer aí, olha a sua versão

E o que você quiser valendo pra TODOS os projetos vive na configuração de usuário: ~/.claude/settings.json, ~/.claude/agents/ e ~/.claude/output-styles/

Revisar bem é uma habilidade que você leva pra qualquer linguagem, e ela se constrói lendo racional, não aceitando diff

até o próximo post!