SpyBara
Go Premium

best-practices.md 2026-10-26 22:57 UTC to 2026-10-27 22:59 UTC

This page contains 417 additions and 355 deletions.

2026
Fri 2 22:59 Sun 4 23:58 Tue 6 23:59 Tue 20 23:00 Thu 22 22:58 Fri 23 22:59 Tue 27 22:59 Fri 30 23:01

Boas práticas para Claude Code

Aproveite mais o Claude Code: diga ao Claude o que ele não consegue ver, dê a ele uma verificação para executar e imponha as regras que não podem ter exceções.

O Claude Code é construído de forma que, na maioria dos casos, seu primeiro prompt simples em uma sessão nova já faz a coisa certa, sem nenhuma configuração da sua parte.

Por exemplo:

  • Para permitir que comandos sejam executados com segurança sem que você aprove cada um, novas sessões de terminal e VS Code começam no modo auto, em que um classificador revisa qualquer coisa arriscada antes de ser executada.
  • Para manter sua conversa principal focada enquanto trabalho independente acontece em paralelo, Claude delega a subagentes e só consulta você quando precisa.
  • Para manter uma sessão longa funcionando sem que você precise gerenciá-la, sua conversa é compactada automaticamente antes que a janela de contexto se encha.

Esta página aborda o que fazer quando os padrões não são suficientes. Isso geralmente acontece quando seu projeto tem conhecimento, regras ou restrições que Claude não consegue ver apenas pelo código:

  • Um processo de deploy que existe apenas na cabeça de alguém
  • Um arquivo que nunca deve ser lido
  • Uma verificação que precisa passar antes que qualquer coisa seja considerada concluída
  • Um orçamento que você precisa respeitar

Nenhum padrão pode saber essas coisas sobre o seu projeto, então é aqui que uma pequena quantidade de configuração da sua parte compensa.

Quando uma sessão não sai como você esperava, quase sempre é por um destes motivos:

  • Claude construiu algo diferente do que você tinha em mente, ou precisa redescobrir o mesmo fato no início de cada sessão. Falta a ele informação que não consegue obter lendo o repositório. Consulte Diga ao Claude o que ele não consegue ver.
  • Claude disse que tinha terminado e não tinha exatamente, geralmente porque não tinha como verificar o próprio trabalho. Consulte Dê ao Claude uma verificação para executar.
  • Claude fez algo que nunca deve acontecer neste repositório, ou pulou uma etapa que sempre deve acontecer. Um prompt sozinho não consegue garantir nenhuma dessas coisas. Consulte Imponha as regras que não podem ter exceções.
  • Claude acertou, mas levou mais tempo, tokens ou prompts de permissão do que a tarefa valia. Consulte Altere um padrão.

Deixe Claude trabalhar sem você aplica os mesmos quatro pontos a execuções desacompanhadas, e O que você pode parar de fazer lista os conselhos que os modelos atuais tornaram desnecessários.

[!NOTE]

A configuração para uma equipe inteira está em uma página separada: Configure o Claude Code para sua organização.

Instruções determinísticas e não determinísticas

Toda instrução que você dá ao Claude Code é de um destes tipos:

  1. Não determinística: você escreve a instrução, e Claude (o modelo) a lê. Pode ser seu prompt, o CLAUDE.md ou uma skill. O modelo então decide o que fazer com essa informação. Ele geralmente segue seus comandos, e os modelos atuais são bons em entender sua intenção sem muito contexto, mas não há garantia de que ele seguirá suas instruções. Ele ainda pode decidir não fazer certas coisas, ou fazer outras.
  2. Determinística: você configura a instrução, e o Claude Code (o harness) precisa executá-la. Pode ser um hook, uma regra deny ou uma configuração gerenciada. O Claude Code aplica isso sempre, não importa o que o modelo tenha decidido fazer.

A maioria das coisas no Claude Code existe nas duas formas:

Não determinística (Claude decide) Determinística (Claude Code impõe)
O que fazer Seu prompt, CLAUDE.md, skills que Claude escolhe por conta própria Hooks, e quais skills só você pode iniciar
O que ele pode tocar O classificador do modo auto Regras deny, o sandbox em modo estrito, configurações gerenciadas
Quando está concluído Um pedido de evidências, /goal, /code-review Testes, typecheck, um hook Stop, CI
Quanto ele gasta Nível de esforço, o próprio ritmo do Claude --max-turns ou --max-budget-usd com -p, um limite de gastos que você definiu
Quem tem a palavra final O resumo do Claude sobre o que ele fez Proteção de branch, uma pessoa que aprova o merge

Na maioria das vezes, você quer que Claude decida. Quase toda diretriz tem exceções, e os modelos atuais são bons em ler o código à sua frente e julgar se uma diretriz se encaixa na situação. Com o código real à sua frente, Claude geralmente está em melhor posição para tomar essa decisão do que uma regra que você escreveu com antecedência.

O tipo determinístico é para quando você quer garantir que certas coisas sempre aconteçam (ou nunca aconteçam), não importa o que o modelo decida. Não precisa ser nada dramático. O modo auto já bloqueia as coisas dramáticas, como um deploy em produção ou um force push sobre o trabalho de alguém. Geralmente é algo específico do seu projeto, e pode ser tão específico quanto você quiser:

  • Nunca edite o cliente gerado em src/gen/
  • Sempre execute o script de cabeçalho de licença depois de criar um arquivo

Você poderia ter escrito qualquer uma dessas como uma linha no CLAUDE.md ou no seu prompt, e Claude a seguiria quase sempre. Mas não importa com que força você a formule, se Claude segue essa linha em um determinado turno ainda é decisão do Claude.

[!TIP]

Se você continua adicionando ênfase a uma linha do CLAUDE.md e Claude ainda a ignora, isso é sinal de que a linha pertence a um hook. O inverso também vale: se você tem hooks para coisas que são apenas preferências, exclua-os e deixe Claude decidir.

Diga ao Claude o que ele não consegue ver

[!TIP]

Escreva apenas o que Claude não consegue encontrar lendo o repositório, ou o que ele gastaria tempo redescobrindo a cada sessão.

Claude começa toda tarefa lendo seu código, e os modelos atuais são muito bons nisso. Eles encontram a estrutura de arquivos, suas convenções, seu framework de testes e como os componentes existentes são construídos, geralmente mais rápido do que você conseguiria explicar. Isso significa que Claude já sabe a maior parte do que você poderia ficar tentado a escrever para ele.

O que ele não consegue encontrar é a informação que nunca esteve no repositório:

  • Uma decisão que sua equipe tomou em uma reunião
  • Um processo de deploy que existe na cabeça de uma pessoa
  • A variável de ambiente de que seus testes de integração precisam

Também há informação que está no repositório, mas exige alguns minutos de investigação para ser encontrada, e Claude precisa refazer essa investigação no início de cada sessão.

Um bom teste antes de escrever qualquer coisa para Claude:

  1. Ele conseguiria encontrar isso lendo o código?
  2. Ele de fato iria procurar?

Se ambas as respostas forem sim, deixe de fora.

Escreva um prompt específico

Um prompt específico ajuda pelo mesmo motivo, porque dá ao Claude informação que ele ainda não tem. Se você nomear o arquivo, descrever o sintoma e disser logo de início como é o "corrigido", geralmente você se poupa de uma rodada de correções depois.

O mesmo vale para uma preferência entre duas abordagens razoáveis: Claude não consegue ler isso no código, então, se você se importa com qual ele escolhe, diga logo de início.

Em vez de Tente
"corrija o bug de login" "usuários relatam que o login falha depois que a sessão expira. veja a atualização de token em src/auth/, escreva um teste que falha reproduzindo o problema, depois corrija"
"adicione um widget de calendário" "siga o padrão em HotDogWidget.php e construa um widget de calendário que permita escolher um mês e paginar entre anos. sem novas bibliotecas"

Se você já tem o que Claude precisa, entregue em vez de descrever:

  • Um arquivo: digite @ e o caminho para incluir o conteúdo do arquivo na sua mensagem.
  • Uma imagem: cole a captura de tela do design ou do erro no prompt.
  • Saída de comando: canalize a partir do seu shell com cat error.log | claude -p "what's going on here".

Frases como think step by step ou be thorough são texto comum de prompt, e não palavras-chave. O principal controle de quão intensamente Claude pensa é o nível de esforço, abordado em Altere o modelo e o esforço. Formulações assim ainda podem dar um empurrão em Claude dentro da configuração de esforço, mas não o levam além dela.

Uma frase que ainda ajuda é be ambitious. Claude tende a interpretar um pedido de forma conservadora e construir a menor coisa que o satisfaça, já que não consegue ver o quanto você esperava. Quando você quiser a versão mais completa, com os casos extremos tratados e os desdobramentos naturais incluídos, diga isso:

build the settings page from the mockup. be ambitious: empty and error states, the save flow wired up, keyboard navigation, not just the layout

Isso informa Claude sobre o escopo, que só você conhece, e não sobre o quanto pensar.

E quando você está explorando em vez de corrigir algo específico, um prompt vago como what would you improve in this file? é perfeitamente aceitável. Você vai corrigir um pouco mais ao longo do caminho, e essa é a troca.

Faça um brainstorming com Claude primeiro

Quando você ainda não sabe exatamente o que quer, não precisa resolver tudo antes de escrever o prompt. Em vez disso, peça ao Claude para entrevistar você:

I want to add rate limiting to the public API but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md.

Claude volta com perguntas de múltipla escolha sobre as partes que você ainda não definiu: limites por usuário versus por chave, o que acontece com requisições acima do limite, o que está fora do escopo. Ele continua perguntando até que as respostas formem uma especificação.

Depois que o SPEC.md existir, inicie uma sessão nova para construir a partir dele, para que a construção comece com um contexto limpo e uma definição escrita de concluído. Ele também é o arquivo para o qual você vai apontar o revisor mais tarde, em Dê ao Claude uma verificação para executar.

Mantenha o CLAUDE.md curto

O Claude Code carrega o CLAUDE.md em toda sessão, o que significa que cada linha nele ocupa um pouco da atenção do Claude em toda tarefa, seja relevante ou não. Por isso o arquivo funciona melhor quando contém apenas o que Claude não conseguiria deduzir a partir do próprio código:

  • Como confirmar o trabalho neste repositório: os comandos exatos de teste, typecheck e lint, e como executar um único arquivo de teste
  • Lugares onde o código engana: um padrão antigo que está em todo lugar, mas que código novo não deve copiar, ou um diretório que parece não usado, mas é
  • Decisões que não estão no repositório: qual helper de erro a equipe escolheu, como os deploys funcionam, o que precisa de revisão de migração
  • Qualquer coisa que você já precisou corrigir duas vezes

Um CLAUDE.md que passa nesse teste continua curto:

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

Em uma sessão, execute /context para confirmar que Claude carregou o arquivo.

Observe que a linha de typecheck é apenas o comando. Claude precisa conhecer o comando para poder verificar o próprio trabalho à medida que avança. Se você também quiser que o Claude Code imponha um typecheck aprovado antes que Claude termine, isso é tarefa para um hook Stop. Uma linha como Always typecheck before you finish neste arquivo funciona na maioria das vezes, não em todas.

Você não precisa escrever o arquivo do zero:

  • /init gera uma versão inicial a partir da sua base de código. A partir daí, o trabalho é principalmente remover linhas. O guia de memória recomenda ficar abaixo de 200.
  • /doctor sugere cortes para qualquer coisa que Claude já consegue deduzir a partir do código.
  • /doctor prompt-audit sinaliza instruções que foram escritas para modelos mais antigos, que apontam para arquivos que não existem mais ou que se contradizem.

Suas preferências pessoais vão no CLAUDE.local.md em vez do CLAUDE.md, e você adiciona esse arquivo ao .gitignore para que ele fique fora do repositório.

[!NOTE]

Se Claude continua ignorando uma linha que está no CLAUDE.md, adicionar IMPORTANT provavelmente não vai resolver. Ou o arquivo cresceu tanto que a linha se perde, ou a linha é uma regra que não pode ter exceções e, nesse caso, pertence a um hook.

Restrinja regras a uma parte da base de código

Se uma regra importa apenas em uma parte da base de código, coloque-a em .claude/rules/ com um filtro paths: para que ela só seja carregada quando Claude estiver de fato trabalhando ali. Por exemplo, este .claude/rules/api.md é carregado para arquivos TypeScript em src/api/:

---
paths:
  - "src/api/**/*.ts"
---
- Validate request bodies with the zod schemas in src/api/schemas/, don't hand-roll checks
- Every new endpoint needs an entry in openapi.yaml, CI fails without it

Coloque os procedimentos da equipe em skills

Um modelo mais capaz sabe mais sobre engenharia, mas não sabe como a sua equipe faz um release, o que diz o seu runbook de incidentes ou como você quer que a documentação de API seja escrita. Esse tipo de conhecimento vai em uma skill: um procedimento ou um conhecimento da equipe salvo em .claude/skills/<name>/SKILL.md.

Skills também pesam menos no contexto do que o CLAUDE.md para esse tipo de coisa. Para uma skill que Claude pode iniciar por conta própria, ele vê o nome e a descrição em toda sessão, mas só lê o arquivo completo quando a tarefa exige. Um procedimento de release longo em uma skill não pesa na sua correção de bug não relacionada como pesaria no CLAUDE.md.

[!NOTE]

A regra do CLAUDE.md também se aplica às skills: escreva apenas o que Claude não consegue encontrar sozinho.

Para um fluxo de trabalho com efeitos colaterais, como de fato fazer esse release, adicione disable-model-invocation: true. Claude então não consegue iniciar a skill por conta própria, e ela só é executada quando você mesmo digita /release. Salva como .claude/skills/release/SKILL.md, ela poderia ser assim:

---
name: release
description: Cut a new release. Bumps the version, writes the changelog entry, tags it and pushes the tag so CI can publish.
disable-model-invocation: true
---
1. Make sure you're on main with a clean tree. If not, stop and ask.
2. Run `pnpm changeset version` and commit the result.
3. Summarize the PRs merged since the last tag into CHANGELOG.md, one line each, user-facing changes only.
4. Tag `v<new version>` and push the tag. CI publishes from there, never publish from your machine.

Conecte as ferramentas de que Claude precisa

Parte do que Claude não consegue ver está inteiramente em outro sistema, como seu rastreador de issues ou seu painel de erros. Se esse sistema tem uma CLI, geralmente esse é o caminho mais fácil. Com o gh instalado e autenticado, por exemplo, Claude abre pull requests e lê comentários de revisão sem nenhuma explicação sua. Para uma CLI que ele nunca viu, apontá-lo para --help é suficiente.

Para sistemas sem CLI, existe o MCP. Você adiciona um servidor a partir do seu shell:

claude mcp add --transport http notion https://mcp.notion.com/mcp

O servidor então aparece em /mcp dentro de uma sessão. Servidores conectados adicionam os nomes de suas ferramentas e instruções ao contexto mesmo quando você não os está usando, então vale a pena desativar ali os que você não precisa.

E se você trabalha em uma linguagem tipada, um plugin de inteligência de código permite que Claude vá direto a uma definição em vez de ler vários arquivos para encontrá-la.

Dê ao Claude uma verificação para executar

Claude para quando o trabalho parece pronto. Se ele não tem nada para executar que diga se o trabalho de fato está pronto, "parece pronto" é tudo o que ele tem como base. Na prática, isso faz de você o conjunto de testes, e cada erro fica ali até que você por acaso o perceba.

Se você der a ele algo que retorne sucesso ou falha, Claude pode fechar esse loop sozinho. Ele faz a alteração, executa a verificação e, se algo quebrou, lê a saída e corrige antes de executar a verificação de novo.

[!TIP]

Dê ao Claude algo que ele possa executar e que retorne sucesso ou falha. Com isso, ele consegue seguir sozinho e você não precisa ficar observando.

A verificação pode ser quase qualquer coisa, desde que Claude consiga ler o resultado:

  • Um arquivo de teste
  • O código de saída de um build
  • Um linter
  • Um script que compara a saída com um fixture
  • Uma captura de tela do navegador ao lado do mockup

Se seu repositório já tem uma dessas, a linha mais útil do seu CLAUDE.md é o comando que a executa.

O quão rigorosa você torna a verificação depende de você. As opções vão de Claude decidir por si mesmo até o Claude Code impor a verificação:

  • No prompt: run the auth tests after, and keep going until they pass. Claude decide por si mesmo quando está satisfeito. Isso funciona para qualquer tarefa, hoje, sem configuração.
  • Como meta: /goal all tests in tests/auth pass and lint is clean define uma condição que um modelo separado verifica em relação à conversa após cada turno, e Claude continua até que ela seja atendida. Raramente você precisa disso na sessão. Isso importa em execuções longas em segundo plano, nas quais Claude às vezes termina um turno com um resumo de progresso enquanto ainda há itens em aberto, e a meta o manda de volta ao trabalho.
  • Como um hook Stop: um hook Stop executa seu script sempre que Claude tenta encerrar o turno e manda Claude de volta ao trabalho se o script sair com código 2. Este é imposto pelo Claude Code (o harness), então o turno não termina até que o typecheck passe ou o limite de bloqueios seja atingido. Há um exemplo mais abaixo.
  • Por alguém que não escreveu o código: no terminal, /code-review revisa o diff em um subagente novo que nunca viu sua conversa. Ele não é influenciado pelo raciocínio que produziu o código.

Qualquer que seja a opção, peça ao Claude evidências: o comando que ele executou e a saída, ou a captura de tela. "Todos os testes passam", por si só, diz muito pouco, e ler a saída é mais rápido do que executar a verificação de novo você mesmo. Para uma sessão que você não estava observando, também é a única evidência que você tem.

[!TIP]

Depois que Claude disser que terminou, você também pode executar /verify na sessão, o que faz Claude compilar e executar o aplicativo e olhar o resultado. Isso detecta o tipo de problema que testes e typechecks deixam passar.

Revise em relação à sua especificação

Se você prefere que a revisão verifique o trabalho em relação ao seu plano em vez de procurar bugs em geral, escreva você mesmo o prompt de revisão:

use a subagent to review the rate limiter diff against SPEC.md, check every requirement is implemented and the listed edge cases have tests, report gaps that affect correctness and skip style

[!NOTE]

Não remova a parte skip style desse prompt. Um revisor a quem se pede para encontrar problemas sempre vai encontrar alguma coisa. Se você corrigir cada apontamento, acaba com camadas extras de abstração e testes para casos que não podem acontecer.

Imponha a verificação com um hook Stop

A versão em hook Stop da regra de typecheck são algumas linhas em .claude/settings.json. O código de saída 2 é o que bloqueia a parada. O que quer que o comando imprima no stderr volta para Claude como o motivo pelo qual ele ainda não pode terminar, e é por isso que a saída do compilador é redirecionada para lá:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
        ]
      }
    ]
  }
}

Para ver funcionando, peça ao Claude uma alteração que quebre um tipo: em vez de terminar, ele recebe de volta os erros do compilador e continua até que o tsc passe. Se o hook bloquear oito paradas seguidas sem nenhuma chamada de ferramenta entre elas, o Claude Code sobrescreve o próximo bloqueio e encerra o turno. Para aumentar o limite, defina CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

Imponha as regras que não podem ter exceções

[!TIP]

Se algo precisa acontecer sempre, transforme em um hook, uma regra deny ou uma configuração gerenciada. O CLAUDE.md é para diretrizes, e Claude pode decidir que uma diretriz não se aplica.

Pense em três regras que você talvez tenha no CLAUDE.md hoje: Never read .env, Always run the formatter after editing, Don't touch the migrations folder. Claude vai segui-las quase sempre. Para as poucas em que "quase" não é suficiente, tire-as do CLAUDE.md e coloque-as em uma configuração que o próprio Claude Code (o harness) aplica. A partir daí, o resultado não depende do que o modelo lembra ou decide.

Imponha etapas com hooks

Hooks executam algo seu em pontos fixos do loop do Claude: antes ou depois de uma chamada de ferramenta, quando Claude tenta parar, quando uma sessão começa e assim por diante. Esse algo pode ser:

  • Um comando de shell (o caso mais comum)
  • Um POST para um endpoint HTTP
  • Uma chamada de ferramenta em um dos seus servidores MCP
  • Um hook prompt ou agent, que deixa um modelo decidir

Um hook prompt ou agent pede a outro modelo que decida, então também não é determinístico. Para imposição real, use um hook command ou http e adicione onFailure: "block" se a ação também deve ser interrompida quando o próprio hook falhar ou atingir o tempo limite. Para um hook que verifica commits em busca de segredos, por exemplo, é melhor bloquear o commit do que deixá-lo passar sem verificação enquanto o scanner está fora do ar.

Aqui está a regra do formatador como um hook PostToolUse. Ele é executado após cada Edit ou Write, e se Claude se lembra da regra deixa de importar, porque não é Claude quem a executa:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }
        ]
      }
    ]
  }
}

Para verificar o hook, peça ao Claude para adicionar uma linha mal indentada a um arquivo que o Prettier formata. O arquivo salvo volta com a indentação corrigida.

A regra de migrações se torna um hook PreToolUse que sai com código 2 para qualquer caminho em migrations/. Você não precisa escrevê-lo: write a hook that blocks edits to the migrations folder funciona como prompt, e /hooks mostra o resultado. Mas não exagere: um hook é para uma regra com zero exceções, e Prefer named exports tem muitas, então essa fica no CLAUDE.md.

Limite o acesso com regras de permissão e o sandbox

Regras de permissão decidem o que Claude pode executar, ler e buscar. Regras deny valem em todos os modos de permissão, incluindo auto e bypassPermissions, e é exatamente por isso que a regra do .env pertence a esse lugar:

{
  "permissions": {
    "allow": ["Bash(pnpm tsc --noEmit)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
  }
}

Com isso salvo, perguntar ao Claude o que há no .env falha, tanto pela ferramenta Read quanto por cat .env.

Regras correspondem a chamadas de ferramenta, não a intenções, então vale a pena saber onde estão os limites:

  • A regra Read pega cat .env, porque o Claude Code reconhece os comandos comuns de leitura de arquivos.
  • Ela não pega um script que abre o arquivo.
  • Uma regra deny de WebFetch para um domínio não faz nada quanto a um curl para esse mesmo domínio, a menos que o sandbox esteja ativado.

Para um limite em nível de sistema operacional sobre acesso ao sistema de arquivos ou à rede, ative o sandbox com /sandbox em uma sessão. Ele confina os comandos de shell do Claude no macOS, Linux e WSL2 e também aplica suas regras deny de Read e regras WebFetch(domain:...), então, para qualquer coisa relacionada a segurança, você quer os dois.

Por padrão, Claude ainda pode pedir para tentar novamente um comando bloqueado fora do sandbox, e esse pedido passa pelo fluxo normal de permissão. O modo estrito do sandbox, na aba Overrides do /sandbox, desativa essa nova tentativa.

[!WARNING]

O modo auto é um modelo classificador julgando cada ação, e não uma regra rígida. Ele é bom nisso, mas, como qualquer julgamento, pode errar. Você também pode ajustar o que ele considera arriscado, e sua organização pode desativá-lo completamente, então suas regras de "nunca" pertencem a regras deny ou hooks.

Escolha a quem uma regra se aplica

O lugar onde uma regra fica decide a quem ela se aplica:

  • .claude/settings.local.json e ~/.claude/settings.json são só seus. Quando você seleciona Yes, and don't ask again para um comando, o Claude Code salva essa regra no arquivo local.
  • .claude/settings.json e os hooks nele pertencem ao repositório. Depois que você faz commit deles, eles se aplicam a todos que trabalham no repositório. As regras deny dele se aplicam imediatamente. As regras allow dele esperam até que cada pessoa aceite o diálogo de confiança daquela pasta, e a confiança do workspace também decide quando os hooks dele começam a ser executados na máquina de cada pessoa.
  • Configurações gerenciadas pertencem à organização. Elas vêm do console de administração, de MDM ou de um arquivo managed-settings.json, e nenhum arquivo de configurações pessoal pode sobrescrevê-las, o que as torna o único lugar para a política de uma equipe de segurança. Se você é a pessoa que as define, consulte Configure o Claude Code para sua organização.

Qualquer que seja o escopo, mantenha pequeno o conjunto imposto. Todo hook e toda regra deny ocasionalmente vão disparar quando não deveriam, e alguém precisa manter cada um. Se algum dia você se vir com quarenta deles, a maioria provavelmente são preferências que Claude poderia ter ponderado sozinho.

Altere um padrão

[!TIP]

Os padrões são bons o suficiente para serem deixados como estão até que uma tarefa custe mais tempo, tokens ou interrupções do que deveria. Quando isso acontecer, execute /usage na sessão para ver para onde foi.

Uma sessão nova já toma algumas decisões por você:

  • Sessões interativas de terminal e VS Code começam no modo auto.
  • Ela executa o Claude Opus 5.5 com esforço médio na maioria dos planos e provedores.
  • Ela delega trabalho a subagentes quando vê motivo para isso.
  • Ela compacta a conversa à medida que cresce.

Na maior parte do tempo você nunca pensa nisso. Quando uma tarefa custa mais do que deveria, um desses quatro geralmente é o motivo.

Altere o modo de permissão

As duas extremidades da faixa de permissões têm um custo:

  • Modo Manual: você mesmo aprova cada edição e cada comando que não seja somente leitura. É seguro, mas depois do décimo prompt você começa a aprovar sem ler, e nada avança enquanto você está longe do teclado.
  • bypassPermissions: aprova tudo o que suas regras deny e ask não cobrem, o que só faz sentido em um contêiner descartável.

O modo auto fica entre os dois, e é nele que as sessões interativas de terminal e VS Code começam. Claude trabalha sem parar para aprovações rotineiras, e um modelo classificador separado verifica as ações em uma ordem fixa antes que sejam executadas. Ele se concentra nas coisas que você gostaria que uma pessoa interrompesse:

  • curl | bash
  • Deploys e migrações em produção
  • Force pushes sobre o trabalho de outras pessoas
  • Dados sensíveis enviados a endpoints externos
  • Ações que parecem guiadas por conteúdo que Claude leu e não por você

Quando ele bloqueia algo, você recebe uma notificação e a ação aparece em Recently denied no /permissions, onde você pode tentar novamente com uma aprovação manual. Após três bloqueios seguidos (ou vinte no total), o modo auto pausa e volta a perguntar a você.

Nada disso substitui seus controles determinísticos, porque ele é executado depois deles. Regras deny e ask e hooks PreToolUse se aplicam antes que o classificador veja qualquer coisa, então uma regra deny bloqueia no modo auto exatamente como em qualquer outro lugar. O sandbox ainda confina os comandos de shell que ele envolve.

[!NOTE]

Você também pode dizer don't push until I've reviewed na conversa, e o classificador trata isso como um sinal de bloqueio. Ainda assim é um modelo lendo a transcrição, e a frase pode se perder quando a conversa é compactada, então qualquer coisa importante pertence a uma regra deny.

O problema oposto é o classificador interromper repetidamente algo que é rotineiro no seu ambiente. Em vez de aprovar manualmente toda vez, adicione isso a autoMode.allow ou descreva sua infraestrutura confiável na configuração do modo auto. Ela é escrita em inglês simples em vez de padrões, e /auto-mode-setup pode redigir a parte environment para você a partir do seu projeto e das sessões recentes:

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.com/example-org and every repo under it",
      "Trusted internal domains: *.internal.example.com"
    ],
    "allow": [
      "$defaults",
      "Deploying to the staging namespace is fine, it's isolated from production and resets nightly"
    ]
  }
}

[!WARNING]

Mantenha "$defaults" em todas as listas que você definir, porque sem ele suas entradas substituem as regras integradas daquela lista em vez de se somarem a elas. Para environment e allow, você perderia o contexto e as exceções integrados, e uma lista soft_deny sem ele descarta os bloqueios integrados de force pushes e deploys em produção.

O bloco autoMode também precisa ficar em ~/.claude/settings.json e não no projeto, porque o classificador ignora autoMode nas configurações do projeto.

Se você prefere ver cada edição e comando antes que aconteçam, Shift+Tab na sessão alterna entre os modos de permissão, incluindo o Manual, ou comece com claude --permission-mode manual a partir do seu shell. E se o Manual passar a perguntar com muita frequência, /fewer-permission-prompts examina suas transcrições recentes em busca de chamadas Bash e MCP somente leitura comuns e as adiciona a uma allowlist em .claude/settings.json.

Altere o modelo e o esforço

O esforço é o principal controle de quanto tempo Claude pensa, e substitui a maior parte do que as pessoas costumavam fazer com a formulação do prompt. Claude Opus 5.5, Sonnet 5.5 e Haiku 5.5 usam medium por padrão, o que é bastante para trabalho cotidiano de funcionalidades com escopo claro. As situações em que você o mudaria, com /effort na sessão:

  • Aumente com /effort high ou /effort xhigh quando acertar depende de casos fáceis de passar despercebidos. Pense em um bug em código que você não escreveu, um teste instável ou uma mudança de esquema em que Claude precisa encontrar todos os leitores do formato antigo. Claude então verifica mais casos extremos e valida mais do próprio trabalho antes de responder, e é aí que vão o tempo e os tokens extras.
  • Diminua com /effort low quando você estiver indo e voltando rapidamente e revisando cada resultado de qualquer forma: brainstorming, um primeiro esboço, uma renomeação em alguns arquivos. Claude entrega um ponto de partida mais cedo e, como você está guiando cada passo, a deliberação extra não mudaria muito além da espera.
  • Reserve max para um problema difícil que você quer que Claude resolva sem você, como caçar uma vulnerabilidade de segurança. Em tarefas comuns ele tende a pensar demais, então você paga mais por uma resposta que pode não ser melhor do que high teria dado.
  • Quando só a próxima mensagem precisa disso, como uma pergunta complicada no meio de um trabalho de resto rotineiro, coloque ultrathink nesse prompt em vez de alterar a configuração.

Quanto ao modelo em si, o Opus 5.5 padrão lida bem com a maior parte da programação e o Sonnet custa menos em trabalho rotineiro. O Claude Fable 5.1 está disponível quando você o seleciona explicitamente com /model fable, e o Haiku é uma boa opção para subagentes que fazem tarefas simples. Configuração de modelo tem a lista completa por plano e provedor.

Saiba quanto custam os subagentes

Claude delega a subagentes por conta própria:

  • Buscas amplas na base de código vão para o agente Explore integrado.
  • Tarefas paralelas são bifurcadas enquanto o modo fork está ativado (o padrão).
  • Os subagentes que ele inicia são executados em segundo plano por padrão, então sua conversa principal continua avançando.

Raramente você precisa pedir qualquer coisa disso, mas ajuda saber o que você está recebendo e quanto custa.

Subagentes compensam nestas situações:

  • Executar partes independentes do trabalho ao mesmo tempo, para que a tarefa inteira termine mais cedo
  • Manter saídas longas, como uma execução completa de testes ou uma busca ampla, fora da sua conversa principal, onde de outra forma seriam carregadas pelo resto da sessão
  • Obter um revisor que não viu como o código foi escrito
  • Dar a uma tarefa menos ferramentas do que a sessão principal tem, como um revisor que pode ler, mas não editar

O que eles custam é principalmente tokens, já que cada subagente envia as próprias requisições e elas contam no mesmo uso da sua conversa principal. Às vezes também custa tempo: um subagente novo primeiro precisa reunir contexto que sua conversa já tinha, então pode acabar sendo mais lento do que fazer a tarefa onde você está.

E, por padrão, é o mesmo modelo (ou um menor) na mesma tarefa. Você ganha paralelismo ou um novo par de olhos, mas não uma resposta mais inteligente.

Para gastar menos com eles:

  • Defina model: haiku na definição de um subagente se o trabalho dele for simples, como coletar os arquivos que importam um módulo ou verificar links na documentação. Esse tipo de tarefa não precisa do modelo maior, e o Haiku custa muito menos por requisição.
  • Peça resumos curtos de volta, para que vinte resultados não encham seu contexto de qualquer forma.
  • Verifique /usage para ver qual parcela do seu uso cada tipo de subagente consome, para saber quais estão valendo o custo.
  • Dê a um subagente personalizado em .claude/agents/ apenas tools: Read, Grep, Glob. Agora ele é um revisor que não consegue editar nada, e esse limite é imposto pelo Claude Code em vez de solicitado em um prompt.

Esse revisor é um arquivo curto, .claude/agents/reviewer.md:

---
name: reviewer
description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
tools: Read, Grep, Glob
---
You're reviewing code you didn't write. Compare the changed files against the spec you're given,
check that every requirement is implemented and the listed edge cases have tests,
and report only the gaps that affect correctness. Skip style.

Peça ao Claude para have the reviewer compare the rate limiter against SPEC.md e as lacunas voltam para sua sessão, onde Claude pode corrigi-las.

Reduza custo e contexto

Com uma janela de 1M de tokens na maioria dos modelos atuais e a compactação perto do topo dela, raramente você vai ficar sem contexto. Ainda assim, você pode pagar por contexto de que não precisa. Cada requisição envia a conversa inteira, então uma sessão que acumulou três tarefas não relacionadas relê as três em cada turno da quarta. Isso tem desconto enquanto o cache está quente e preço cheio depois que ele expira.

/usage é o primeiro lugar para olhar. No Pro, Max, Team e Enterprise, ele detalha seu uso por skill, subagente, plugin e servidor MCP. Ele também sinaliza padrões como contexto longo ou falhas frequentes de cache quando um deles passa de 10% do seu uso. A partir daí, as correções habituais:

  • /clear entre tarefas não relacionadas. Não custa nada e significa que a próxima tarefa não continua pagando pelo histórico da anterior. /clear oauth-migration dá nome à sessão que você está deixando, para que você possa voltar a ela depois.
  • /compact com um foco, como /compact keep the API changes and the test commands. Em uma sessão longa, o /compact é ele próprio uma requisição grande, já que lê a conversa inteira para resumi-la, e ainda mais depois que o cache expirou.
  • Fique de olho no trabalho em segundo plano: um /loop, a verificação de uma meta após cada turno e os próprios subagentes do Claude continuam enviando requisições enquanto você não está digitando.

[!NOTE]

O cache de prompt dura cerca de uma hora em uma assinatura e cinco minutos com uma chave de API, provedor de nuvem ou créditos de uso. Subagentes ficam com cinco minutos, a menos que você altere isso.

No cache de uma hora, uma sessão com mais de cerca de 200K tokens que fica ociosa é compactada pouco antes de o cache expirar, então depois do almoço você continua a partir de um resumo. Se você não precisa do histórico, uma sessão nova ainda custa menos.

Conduza a sessão

[!TIP]

Observe o primeiro minuto, pressione Esc no momento em que Claude se desviar e, após duas correções que não funcionaram, execute /clear e escreva um prompt melhor em vez de uma terceira.

Nenhuma configuração substitui observar o primeiro minuto e intervir quando Claude segue para onde você não pretendia. Há poucos controles para isso, e vale a pena conhecê-los de cor:

  • Esc interrompe Claude no meio de uma ação e mantém tudo até aquele ponto, para que você possa redirecionar sem perder trabalho.
  • /rewind, ou Esc duas vezes em um prompt vazio, abre o menu de rewind, onde você retorna o código, a conversa ou ambos a um prompt anterior. Isso torna de baixo risco tentar primeiro a abordagem mais ousada e voltar se não der certo. O mesmo menu também pode resumir parte da conversa quando ela ficou desatualizada.
  • /clear recomeça. Se você corrigiu a mesma coisa duas vezes e ainda está errado, uma terceira correção basicamente aumenta uma conversa que já contém duas tentativas fracassadas que Claude continua relendo. /clear mais um novo prompt que incorpore o que você aprendeu funciona melhor quase sempre.

[!WARNING]

Checkpoints cobrem os arquivos que Claude editou com as próprias ferramentas de arquivo na sua conversa principal, então um arquivo tocado apenas por um comando Bash não é restaurado. Eles funcionam junto com o git, e não o substituem.

Dois controles menores: /btw responde a uma pergunta rápida sem adicionar nada ao histórico. E para trabalhos que duram vários dias, /rename oauth-migration na sessão dá nome a ela, para que claude --resume oauth-migration a partir do seu shell a retome depois, incluindo os checkpoints. claude --continue retoma a mais recente.

Deixe Claude trabalhar sem você

[!TIP]

Antes de uma execução ficar desacompanhada, certifique-se de que ela sabe como é o concluído, consegue verificar o próprio trabalho e só pode tocar no que deve. Dê a ela um limite de turnos ou de gastos, e faça uma pessoa aprovar o resultado no final.

Tudo nesta página importa um pouco mais quando você não está por perto para pegar erros. Enquanto você está observando, Claude não ter alguma parte do contexto não é grande coisa: você percebe em uma ou duas mensagens e avisa. Em uma execução que você iniciou antes de ir dormir, ninguém avisa, e você descobre na manhã seguinte que ele passou a noite inteira construindo sobre uma suposição errada.

Antes de deixar uma tarefa sendo executada sozinha, vale a pena passar por estas cinco perguntas com essa tarefa específica em mente:

  1. Ela sabe como é o concluído? Uma condição de meta, um arquivo de especificação ou um teste que falha e precisa passar.
  2. Ela consegue verificar o próprio trabalho? O conjunto de testes, um hook Stop, algum tipo de etapa de revisão.
  3. No que ela pode tocar? Regras de permissão, dontAsk, o sandbox, um worktree, o único branch para o qual ela pode fazer push.
  4. O que a interrompe? --max-turns, --max-budget-usd, um limite de gastos.
  5. Para onde vai o resultado, e quem aprova? Um PR, um comentário ou um resumo, e então uma pessoa aprovando o merge, o deploy ou qualquer outra coisa que não possa ser desfeita.

Depois que começa, Claude leva uma tarefa longa até o fim sozinho. As partes que continuam com você são iniciá-la, decidir o que "concluído" significa desta vez e aprovar o merge no final.

Execute Claude a partir de um script

claude -p "prompt" executa uma vez e sai, e é assim que o Claude Code acaba em jobs de CI, hooks do git e loops de shell.

Em um script, você quase sempre vai querer mais algumas flags:

  • --bare ignora hooks, skills, plugins, servidores MCP e arquivos CLAUDE.md, tanto os do repositório quanto os da máquina, para que a execução faça a mesma coisa onde quer que seja executada. Ela também nunca toca no seu login do claude.ai: a autenticação vem de ANTHROPIC_API_KEY, de um apiKeyHelper no arquivo que você passa com --settings ou das credenciais do seu provedor de nuvem.
  • --append-system-prompt, --mcp-config e --settings passam explicitamente o que a execução de fato precisa.
  • --allowedTools pré-aprova as ferramentas dela, e --permission-mode dontAsk recusa qualquer outra coisa que teria gerado um prompt.
  • --output-format json fornece um único objeto de resultado para analisar, e stream-json com --verbose transmite eventos à medida que acontecem.

Juntando tudo, fica assim:

for file in $(cat files.txt); do
  claude --bare -p "Migrate $file to the new logger API and commit. Reply OK or FAIL." \
    --allowedTools "Read,Edit,Bash(git add *),Bash(git commit *)" \
    --permission-mode dontAsk \
    --max-turns 20
done

Quando uma execução termina, Claude responde OK ou FAIL, e uma execução que atinge o limite de turnos sai com um erro. Teste primeiro em três arquivos, veja o que dá errado, corrija o prompt e depois execute o resto.

O modo auto também funciona com -p se você passar --permission-mode auto. Em uma execução não interativa, um bloqueio do classificador nega aquela ação específica e Claude continua, e bloqueios repetidos não pausam a execução como acontece em um terminal. Leia como os limites se aplicam nesse caso antes de depender disso.

Inicie execuções por agendamento ou por evento

Depois que uma execução começa, Claude consegue cuidar do resto sozinho. A única coisa que ele não consegue é decidir começar, então algo precisa fazer isso: você, um timer ou um evento como uma verificação de CI que falhou ou um novo PR.

Dentro de uma sessão aberta, isso é o /loop, que repete um prompt em um intervalo:

/loop 15m check CI on this branch, and if it's red pull the failing job's log, fix it and push

Cada execução é mais um turno na mesma sessão, então não deixe um rodando em uma conversa longa. Para qualquer coisa que deva acontecer enquanto seu laptop está fechado, /schedule configura uma tarefa agendada na nuvem que é executada por timer. Ela precisa de um login do claude.ai em vez de uma chave de API. Você pode adicionar um gatilho de evento do GitHub pedindo ao Claude, ou um gatilho de API em claude.ai/code/routines.

[!WARNING]

Antes de deixar uma tarefa agendada na nuvem sendo executada, proteja o main com uma regra de branch do GitHub que a tarefa não consiga contornar. E observe as primeiras execuções de qualquer coisa nova antes de confiar nela sem supervisão.

Execute sessões em paralelo

Quando você tem trabalhos separados acontecendo ao mesmo tempo, dê a cada um o próprio checkout para que as edições não colidam. claude -w feature-auth inicia uma sessão em um novo worktree, o aplicativo desktop executa várias dessas lado a lado, e as sessões na nuvem as executam na nuvem em vez de na sua máquina.

Um worktree é um checkout novo, o que significa que arquivos ignorados pelo git, como o .env, não estão lá e as dependências não estão instaladas. Para o primeiro caso, liste os arquivos ignorados pelo git de que você precisa em um .worktreeinclude na raiz do repositório (mesma sintaxe do .gitignore) e o Claude Code os copia para todo worktree que criar:

.env
.env.local
config/dev-credentials.json

Mantenha apenas arquivos pequenos: ele copia em vez de criar links, então colocar node_modules ali significaria uma cópia completa por worktree. Para diretórios grandes, há a configuração worktree.symlinkDirectories, ou mantenha o comando de instalação no CLAUDE.md para que Claude o execute sempre que começar em um novo checkout.

Raramente você precisa limpar qualquer coisa disso você mesmo:

  • Quando você sai de uma sessão de worktree sem nome, o Claude Code remove o worktree se não houver nada nele. Para uma sessão com nome, ou uma com alterações, ele pergunta o que fazer.
  • Worktrees de subagentes desaparecem quando o subagente termina sem alterações.
  • Worktrees de subagentes e de sessões em segundo plano que acabam ficando para trás são removidos quando ficam mais antigos que cleanupPeriodDays e não contêm trabalho.

[!NOTE]

Uma execução claude -p --worktree é uma que você mesmo limpa, já que ela sai sem perguntar. Remova esses worktrees com git worktree remove <path> e, se o git recusar porque o worktree está bloqueado, execute git worktree unlock <path> primeiro.

Para uma grande alteração mecânica em muitos arquivos, /batch migrate every handler to the v2 response helpers divide o trabalho em 5 a 30 unidades e mostra o plano. Depois, executa cada unidade no próprio worktree e abre um PR para ela. A partir do seu shell, claude agents (ainda em prévia de pesquisa) oferece uma única tela para tudo o que está sendo executado em segundo plano na sua máquina.

Uma segunda sessão também é o revisor independente mais fácil que você pode conseguir. Uma sessão escreve o rate limiter, outra revisa @src/middleware/rateLimiter.ts sem ter acompanhado a escrita, e você cola os apontamentos de volta na primeira. Mesma ideia do /code-review, com você levando as mensagens.

O que você pode parar de fazer

Cada um destes foi um bom conselho quando foi escrito. A maioria eram soluções alternativas para algo que o modelo ainda não conseguia fazer de forma confiável, e os modelos já alcançaram isso. Se alguns ainda são hábitos, veja por que é seguro abandoná-los.

O conselho antigo Por que não vale mais
A janela de contexto é sua principal restrição, gerencie-a agressivamente A maioria dos modelos atuais tem uma janela de 1M de tokens e a compactação acontece sozinha, então ficar sem contexto é raro. /clear entre tarefas ainda vale a pena, porque um contexto focado produz respostas melhores e custa menos.
Adicione IMPORTANT ou MAIÚSCULAS a instruções que Claude continua ignorando Modelos mais antigos às vezes precisavam da ênfase. Os atuais seguem uma linha escrita de forma simples, e acumular ênfase faz principalmente Claude aplicar a regra em excesso. Se for uma regra que não pode ser flexibilizada, transforme-a em um hook ou uma regra deny. Se a linha está se perdendo em um arquivo longo, o arquivo precisa ser mais curto.
Use subagentes para proteger sua janela de contexto Ficar sem contexto raramente é o problema hoje em dia. Subagentes continuam ótimos para trabalho paralelo, para manter saídas ruidosas fora do seu caminho e para revisão independente, mas cada um desses custa tokens extras.
Delegue a um subagente para obter uma resposta melhor Entregar a mesma tarefa a um subagente não torna a resposta melhor. Um revisor novo ajuda, porque não viu seu raciocínio, o que é diferente de delegar.
think hard, think harder, be thorough no prompt O esforço é o controle para isso. Essas frases são texto comum de prompt que dá um empurrão em Claude dentro da configuração de esforço, e não palavras-chave que a aumentam. ultrathink ainda funciona: ele pede raciocínio mais profundo naquele único turno sem mexer na sua configuração de esforço.
Diga ao Claude para continuar, repetir até terminar, não ser preguiçoso Os modelos atuais geralmente levam uma tarefa combinada até o fim sem que precisem ser mandados, e linhas assim têm mais chance de causar excesso de trabalho do que de resolver uma parada. Dar ao Claude uma verificação para passar é diferente, e ainda vale a pena. Se uma execução parar antes da hora, diga continue, e para execuções que ninguém está observando, /goal ou um hook Stop impõe isso.
Descreva sua arquitetura e estrutura de arquivos no CLAUDE.md Claude lê o repositório sozinho. Escreva apenas o que não está lá.

Se qualquer outro conselho nesta página algum dia começar a parecer trabalho inútil, isso provavelmente é sinal de que ele também pertence a esta tabela.

Recursos relacionados