A geração anterior de assistente completava uma linha por vez e devolvia a bola pra você. Aqui o pedido é a funcionalidade inteira, e o encadeamento das ferramentas (ler arquivo, buscar, rodar bash, editar) é decisão dele. Você não escreve no prompt qual ferramenta usar e em que ordem: descreve o resultado e revisa o caminho.

Quase toda boa prática do Claude Code sai de uma limitação só: a janela de contexto enche rápido e o desempenho cai conforme ela enche. A janela guarda a conversa inteira, cada arquivo lido e cada saída de comando, e uma única sessão de depuração consome dezenas de milhares de tokens. Quando ela aperta, o agente começa a esquecer instrução antiga e a errar mais. Contexto é o recurso escasso, não a inteligência do modelo.

Tratar a sessão como chat infinito. Misturar três tarefas sem relação na mesma janela é o erro mais comum, e o custo aparece como resposta pior sem motivo aparente. Use /clear entre tarefas que não conversam entre si, e /context pra ver o que está ocupando espaço.

Ele roda no terminal, então funciona com qualquer editor e em qualquer ambiente: local, dentro de uma sessão SSH, dentro do tmux. Não existe passo de indexação nem espera pra começar a usar: ele lê os arquivos sob demanda, na hora da pergunta. O que sai da sua máquina são os prompts e as saídas do modelo, trafegando por TLS, e o limite de escrita padrão é a pasta onde você iniciou a sessão mais as subpastas dela.

A doc oficial trata isso como fluxo de integração a uma base nova, porque reduz o tempo de rampa e tira carga dos outros engenheiros do time: em vez de interromper alguém, você pergunta ao repositório. E, do ponto de vista de quem está aprendendo a ferramenta, perguntar ensina a escrever prompt sem risco nenhum, já que nada é escrito em disco.

• Como o log funciona neste projeto, e como eu crio um endpoint novo seguindo o padrão que já existe?
• Que casos de borda o fluxo de cadastro trata hoje, e quais ele ignora?
• Por que esta função tem tantos argumentos? Olhe o histórico do git e resuma como ela chegou nesse formato.
• O que eu entreguei nesta semana? Leia o log do git filtrando pelo meu usuário e resuma por tema.

Aponte a fonte em vez de descrever o problema. A doc é explícita: trocar "por que essa API é tão estranha?" por "olhe o histórico do git desta classe e resuma como a API dela surgiu" muda a qualidade da resposta, porque direciona o agente pra evidência em vez do palpite. Vale o mesmo pra @arquivo, que puxa o conteúdo pro contexto antes da resposta.

Pedir "investigue o sistema" sem escopo. Ele lê centenas de arquivos, entope a janela e a sessão fica ruim pro resto do dia. Delimite a investigação ou mande usar subagente: o subagente explora num contexto separado e devolve só o resumo, mantendo a sua conversa limpa.

Ganho de tempo de integração depende do tamanho e da bagunça da base. A doc afirma a direção (melhora a rampa, reduz a carga sobre o time) sem cravar número, e eu não vou inventar um. Meça no seu repositório antes de prometer prazo pra alguém.

Aperte Shift Tab até a barra de status mostrar o modo de plano, ou inicie a sessão já nele com claude --permission-mode plan. Nesse modo ele lê arquivos e responde sem alterar nada. Depois de gerado o plano, Ctrl G abre o plano no seu editor pra você corrigir antes de liberar. Sair do modo plano é aprovar ou apertar Shift Tab de novo.

Planejar tem custo. A doc é direta: se o escopo está claro e a mudança é pequena (corrigir um typo, adicionar uma linha de log, renomear uma variável), peça direto. A regra prática que eu uso: se você consegue descrever o diff em uma frase, pule o plano. Planejar vale quando você está inseguro sobre a abordagem, quando a mudança encosta em vários arquivos, ou quando você não conhece o código que vai mexer.

Em funcionalidade grande, inverta: em vez de você explicar tudo, mande ele te entrevistar. Um prompt curto pedindo entrevista detalhada faz ele perguntar sobre implementação, interface, casos de borda e trade-offs que você ainda não pensou, e no fim gravar a especificação num arquivo. Aí você abre uma sessão nova, limpa, só pra executar a especificação. Tempo gasto deixando a spec precisa rende mais que tempo assistindo a implementação.

Corrigir a mesma coisa três vezes na mesma sessão. Depois de duas correções falhas, o contexto está poluído de tentativa errada e cada nova tentativa piora. O caminho é /clear e um prompt novo, melhor, que já incorpore o que você aprendeu.

Qualquer coisa que devolva um sinal legível dentro da conversa: uma suíte de testes, o código de saída de um build, um linter, um script que compara a saída com um arquivo de referência, ou um screenshot do navegador comparado com o design. O critério não é sofisticação, é ter resposta binária.

• No próprio prompt: mandar rodar a checagem e iterar na mesma mensagem. Funciona hoje, em qualquer tarefa, sem configurar nada.
• Na sessão inteira: registrar a checagem como condição de /goal. Um avaliador separado reconfere a cada turno e o agente segue trabalhando até a condição valer.
• Como portão determinístico: um hook Stop roda sua checagem como script e impede o turno de encerrar enquanto não passar. Existe um teto: depois de oito bloqueios seguidos, a ferramenta encerra o turno mesmo assim.
• Como segunda opinião: um subagente revisor, ou um fluxo que reconfere as próprias conclusões, faz um modelo novo tentar derrubar o resultado, pra que quem executou não seja quem dá a nota.

Mande mostrar evidência em vez de afirmar sucesso: a saída do teste, o comando exato que rodou e o que ele devolveu, ou o screenshot do resultado. Revisar evidência é mais rápido que refazer a verificação, e é a única forma de auditar sessão que você não assistiu.

Confiar na implementação plausível. Ela compila, parece certa e não trata o caso de borda. E, no outro extremo, um revisor instruído a achar falha quase sempre acha alguma, mesmo quando o trabalho está bom, porque foi isso que você pediu. Instrua o revisor a apontar só o que afeta correção ou requisito declarado, e trate o resto como opcional.

A doc chama a linha de comando de jeito mais econômico em contexto de falar com serviço externo. Se você usa GitHub, instale o gh: ele já sabe abrir issue, criar pull request e ler comentário. Sem o gh, sobra chamar a API sem autenticação e bater no limite de requisição. E ele aprende CLI que não conhece: mande use a CLI tal com --help pra aprender a usar, e depois resolva A, B e C. Ferramenta que você usa direto, registre no CLAUDE.md pra não reexplicar toda sessão.

MCP é o protocolo aberto que conecta o agente a ferramenta, banco e API externa. O que decide se aquilo é seu ou do time é o escopo do registro: local vale só pra você naquele projeto, user vale pra você em todos os projetos, e project grava num arquivo .mcp.json na raiz, que é justamente o que você versiona pra todo mundo receber o mesmo conjunto.

# so pra voce, neste projeto
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

# pro time inteiro: grava .mcp.json na raiz do repositorio
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# pra voce, em todos os projetos
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

# conferir o que esta ligado
claude mcp list

Servidor de escopo de projeto não conecta sozinho: por segurança, a ferramenta pede aprovação em sessão interativa antes de usar servidor vindo do .mcp.json. Enquanto ninguém aprovar, ele aparece como pendente na listagem. E um repositório clonado não consegue se autoaprovar: a aprovação só passa a valer depois que você roda a sessão naquela pasta e aceita o diálogo de confiança. Pra zerar as escolhas de aprovação, existe claude mcp reset-project-choices.

Ligar servidor MCP demais. Cada servidor conectado carrega descrição de ferramenta pra dentro do contexto, e contexto é o recurso escasso. Ligue o que o projeto usa de verdade, e prefira CLI quando ela resolve, porque CLI custa menos contexto que servidor.

• Política gerenciada (a organização inteira, distribuída por MDM ou similar): no macOS em /Library/Application Support/ClaudeCode/CLAUDE.md, no Linux e WSL em /etc/claude-code/CLAUDE.md, no Windows em C:\Program Files\ClaudeCode\CLAUDE.md. Este não pode ser excluído por configuração individual.
• Suas preferências, valendo em todos os seus projetos: ~/.claude/CLAUDE.md.
• O projeto, compartilhado com o time por controle de versão: ./CLAUDE.md ou ./.claude/CLAUDE.md.
• Local do projeto, só seu, entra no .gitignore: ./CLAUDE.local.md.

Ele sobe a árvore de diretórios a partir de onde você iniciou a sessão e concatena tudo que achou, da raiz do sistema de arquivos até o seu diretório de trabalho, sem um sobrescrever o outro. Ou seja, o arquivo mais próximo de onde você abriu é o último lido. Já os CLAUDE.md em subdiretórios abaixo do diretório atual não entram no início: eles são puxados quando o agente lê um arquivo daquela pasta. É isso que faz monorepo funcionar sem carregar o mundo inteiro.

Comandos de bash que ele não teria como adivinhar, regra de estilo que difere do padrão da linguagem, instrução de teste, etiqueta do repositório (nome de branch, convenção de PR), decisão de arquitetura específica do projeto e as pegadinhas do ambiente. Fora: o que ele descobre lendo o código, convenção padrão que ele já conhece, documentação longa de API (linke) e descrição arquivo por arquivo. O teste de cada linha é uma pergunta só: se eu apagar isto, ele passa a errar? Se não, apague.

Mire abaixo de 200 linhas por arquivo. Arquivo longo consome mais contexto e derruba a aderência, e o efeito é traiçoeiro: quando ele insiste em ignorar uma regra que existe, quase sempre o problema é o arquivo estar grande demais e a regra ter se perdido no meio. Rode /context pra confirmar quais arquivos de memória carregaram de verdade, e /init pra gerar um CLAUDE.md inicial a partir do próprio projeto.

Instrução que vale só pra um pedaço do código vira regra com caminho: arquivos .md dentro de .claude/rules/, com um campo paths no cabeçalho, carregam só quando o agente toca em arquivo que casa com o padrão. Procedimento de vários passos vira skill, que só carrega quando é usada. E o que precisa acontecer sempre, sem exceção, não é instrução: é hook, que roda como script em ponto fixo do ciclo, independente do que o modelo decidir.

CLAUDE.md não é configuração obrigatória, é contexto. A doc diz de forma explícita que o conteúdo chega como mensagem de usuário depois do prompt de sistema, e que não há garantia de cumprimento estrito, principalmente com instrução vaga ou contraditória. Se duas regras se contradizem, ele pode escolher qualquer uma. Revise e pode o arquivo com a mesma disciplina que você usa pra revisar código.

Os comandos personalizados foram unificados com as skills. Um arquivo em .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md criam o mesmo /deploy e funcionam igual. Os seus arquivos antigos em .claude/commands/ continuam valendo, então não há nada pra migrar às pressas. O que a skill acrescenta é uma pasta pra arquivos de apoio, cabeçalho pra controlar quem invoca e a possibilidade de o próprio agente carregar aquilo quando for relevante.

• Pessoal, em todos os seus projetos: ~/.claude/skills/<nome>/SKILL.md.
• Projeto, versionado com o time: .claude/skills/<nome>/SKILL.md.
• Se existir a mesma skill nos dois lugares, a do projeto vale sobre a pessoal.

Skill carrega sob demanda, CLAUDE.md carrega toda sessão. Então material longo de referência dentro de uma skill custa quase nada até a hora em que é usado, enquanto o mesmo texto no CLAUDE.md pesa em cada conversa. A regra de bolso: fato que vale sempre fica no CLAUDE.md, procedimento de vários passos vira skill.

Aquele processo de release que só três pessoas do time sabem fazer na ordem certa: escreva os passos num SKILL.md, commite, e a partir dali qualquer pessoa digita a barra e o agente executa a sequência inteira. É o efeito de rede que faz o investimento render: uma pessoa escreve, o time inteiro usa.

• Modo automático: um classificador à parte revisa os comandos e bloqueia só o que parece arriscado (escalada de escopo, infraestrutura desconhecida, ação induzida por conteúdo hostil). Serve quando você confia na direção da tarefa e não quer clicar em cada passo.
• Lista de permissão: você libera nominalmente o que sabe que é seguro, tipo rodar o lint ou fazer commit.
• Sandbox: isolamento no nível do sistema operacional, restringindo sistema de arquivos e rede, pra ele trabalhar com mais liberdade dentro de uma fronteira definida.

Bloqueio ganha de liberação, em qualquer nível. Se um nível nega, nenhum outro consegue permitir, e política gerenciada é o topo: nem argumento de linha de comando derruba uma negativa gerenciada. Também vale ao contrário do que muita gente espera: um bloqueio amplo como Bash(aws *) anula até uma liberação mais específica que casaria com a mesma chamada, ou seja, regra de bloqueio não carrega exceção.

Se existe um endereço que ninguém deveria acessar, a regra é WebFetch(domain:exemplo.com) no bloqueio. Subdomínio em qualquer profundidade se escreve WebFetch(domain:*.exemplo.com), e ele não cobre o domínio raiz. Só que bloquear a ferramenta de busca não basta: quem quiser burlar chama curl. O caminho completo é negar também os comandos de rede no bash e liberar por domínio na ferramenta própria.

Quando você escolhe "sim, não pergunte de novo" pra um comando de bash, a regra é gravada em .claude/settings.local.json na raiz do repositório, e passa a valer nas próximas sessões daquele repositório inteiro, inclusive nas iniciadas em subpasta. Aprovação de edição de arquivo é diferente: ela não é gravada, vale até o fim da sessão.

Achar que regra em CLAUDE.md protege alguma coisa. Não protege: instrução é contexto, permissão é regra do cliente. Se algo não pode acontecer, escreva como bloqueio de permissão ou como hook, nunca como pedido educado no arquivo de instruções. E cuidado com o outro extremo, o de desligar tudo por conveniência em máquina que tem acesso a produção.

• Shift Tab · alterna o modo de permissão, circulando entre manual, aceitar edições e modo de plano, mais os modos que você tiver habilitado.
• Esc · interrompe no meio da ação. O trabalho feito até ali é preservado, então você redireciona sem perder contexto. Com um diálogo aberto, ele fecha o diálogo em vez de interromper.
• Esc Esc · com texto digitado, limpa o rascunho e guarda no histórico. Com o campo vazio, abre o menu de retorno, pra restaurar código e conversa de um ponto anterior.
• Exclamação no começo · modo shell. Roda o comando direto, joga a saída pra dentro da sessão e o agente responde a partir dela.
• Arroba · menciona caminho de arquivo, com autocompletar, e puxa o conteúdo pro contexto.
• Ctrl R · busca reversa no histórico de comandos.

Ele sugeriu uma edição de vinte linhas e dezenove estão perfeitas. Em vez de aceitar e mandar corrigir depois, aperte escape, diga exatamente qual linha está errada e mande refazer. Ciclo curto de correção rende mais que ciclo longo de conserto, e a doc afirma isso de forma direta: corrigir cedo em geral produz solução melhor e mais rápido do que esperar o fim.

A conversa fica salva localmente. claude --continue retoma a mais recente daquele diretório e claude --resume abre a lista pra escolher, ou aceita o identificador direto. Batize as sessões com nome descritivo e trate cada uma como uma branch de trabalho: cada frente com o próprio contexto persistente.

O retorno com escape duplo só desfaz o que passou pelas ferramentas de edição de arquivo do agente. Alteração feita por comando de bash ou por processo externo não é capturada. Ou seja, checkpoint é conveniência, não substitui git. Commite antes de mandar ele tentar algo arriscado.

O jogo de sinal de cerquilha pra gravar memória não aparece mais na tabela de comandos rápidos da doc de modo interativo. Hoje o caminho documentado é pedir em linguagem natural ("lembre que os testes precisam do Redis local"), que salva na memória automática, ou usar /memory pra abrir e editar os arquivos direto. Da mesma forma, /terminal-setup e /theme não constam na referência de comandos atual: quebra de linha com shift e enter já é nativa em vários terminais, e a aparência ficou dentro de /config.

O que antes se chamava SDK do Claude Code hoje é o Agent SDK, disponível como CLI pra script e CI e como pacote em Python e TypeScript pra controle programático completo. Se você encontrar material antigo falando em "Claude Code SDK", é a mesma coisa com o nome anterior.

Pra migração grande, o padrão é gerar a lista de arquivos num arquivo texto e depois varrer essa lista chamando claude -p por item, restringindo o que ele pode fazer com --allowedTools. Refine o prompt nos dois ou três primeiros arquivos e só então rode no conjunto inteiro. É trabalho não assistido, então a restrição de ferramenta deixa de ser detalhe e vira o que segura o risco.

Existe a flag --bare, que pula a descoberta automática de hooks, skills, plugins, servidores MCP, memória automática e CLAUDE.md. Serve exatamente pra CI e script, onde você quer o mesmo resultado em toda máquina, sem depender do que um colega deixou no ~/.claude dele. A contrapartida honesta: em modo bare ele não usa o login de assinatura, então é preciso ter a chave de API no ambiente. A doc sinaliza que --bare deve virar o padrão do -p no futuro.

• Entrada por cano tem teto de 10 MB. Acima disso, escreva num arquivo e cite o caminho no prompt.
• O diálogo de confiança de workspace não aparece em modo não interativo. Regra de liberação que dependeria dele fica ignorada, e o comportamento pode diferir do que você viu na sessão interativa.
• O custo em dólar que vem no JSON é estimativa do cliente e pode divergir da fatura.

Enquanto a sessão está isolada, a ferramenta bloqueia edição que aponte pro checkout principal, comando cujo diretório de trabalho caia lá, e comando que redirecione o git pra lá por qualquer caminho. Ela também recusa construção de shell que não consegue rastrear estaticamente e pede pra quebrar em comandos simples. Isso vale igualmente pros subagentes que a sessão isolada abrir.

Worktree isola arquivo. Subagente e time de agentes coordenam o trabalho: dá pra pedir que os subagentes rodem cada um no próprio worktree, ou fixar isso num subagente com isolation: worktree no cabeçalho dele. Vale lembrar que rodar em paralelo não é só velocidade: contexto novo melhora revisão, porque o revisor não fica enviesado pelo código que ele mesmo acabou de escrever.

Sessão A implementa. Sessão B, que não viu nada, recebe o arquivo e a instrução de procurar caso de borda, condição de corrida e inconsistência com os padrões que já existem. A saída de B volta pra A como pauta de correção. Funciona igual com teste: uma sessão escreve os testes, outra escreve o código pra passar neles.

• Worktree é um checkout novo, então dependência não vem instalada e arquivo ignorado pelo git, tipo .env, não existe lá. Pra copiar automaticamente, crie um arquivo .worktreeinclude na raiz, com sintaxe de gitignore.
• Sessão não interativa com -p não tem o passo de saída, então não limpa o worktree sozinha. Remova com git worktree remove.
• Aprovação de permissão dada dentro de um worktree é salva no checkout principal e passa a valer no repositório inteiro. É conveniente e é exatamente por isso que merece atenção.