Curso completo de Claude Code: do zero a agentes, skills, hooks, MCP, plugins e automação profissional

Claude Code deixa de ser apenas um chat no terminal quando memória, comandos, skills, agentes, MCP, hooks, checkpoints, permissões e plugins passam a trabalhar como um sistema. Este curso percorre cada uma dessas camadas do básico à operação profissional, com configurações, possibilidades, exemplos e diagnóstico.

O conteúdo foi reconstruído em PT-BR a partir de todo o material técnico do projeto Claude How To, com organização e exemplos próprios. Recursos recentes ou experimentais devem sempre ser confirmados na versão instalada com claude --help e na documentação oficial.

Índice completo do curso

1 Módulo — Comandos, slash commands e workflows reutilizáveis

1.1 Comandos slash, skills e fluxos reutilizáveis

Os slash commands no Claude Code são atalhos digitados na sessão interativa para acionar comportamentos específicos. Eles servem para acelerar tarefas repetitivas, padronizar fluxos de trabalho e, em alguns casos, delegar automações para arquivos reutilizáveis no projeto.

Há quatro origens principais de comandos:

• Comandos embutidos: vêm com o próprio Claude Code, como /help, /clear e /model.
• Skills: comandos definidos pelo usuário como arquivos SKILL.md, por exemplo /optimize e /pr.
• Comandos de plugin: fornecidos por plugins instalados, como /frontend-design:frontend-design.
• Prompts MCP: expostos por servidores MCP, como /mcp__github__list_prs.

Um ponto importante: comandos slash personalizados foram incorporados ao sistema de skills. Os arquivos em .claude/commands/ ainda funcionam, mas a abordagem recomendada agora é usar .claude/skills/. Ambos criam atalhos no formato /nome-do-comando.

1.1.1 Comandos embutidos: visão geral prática

O Claude Code traz dezenas de comandos nativos, usados para controlar sessão, contexto, permissões, integrações e navegação. Eles podem mudar com a versão, então é bom consultar a lista dentro da própria interface digitando /. Você também pode digitar / seguido de letras para filtrar a lista.

Alguns comandos merecem atenção especial porque têm comportamento que afeta o fluxo da sessão:

• /branch ou /fork: cria uma ramificação da conversa em uma nova sessão. O nome oficial passou a ser /branch, e /fork ficou como alias.
• /cd <path>: muda o diretório de trabalho sem perder a cache de prompt. Isso é importante porque trocar o diretório “na marra” pode tornar a próxima resposta mais lenta e mais cara; com /cd, o cache é preservado.
• /goal: registra uma condição de conclusão para a sessão, fazendo o Claude continuar até atingir o objetivo.
• /model: seleciona o modelo; nas versões recentes a escolha pode ser salva como padrão para novas sessões.
• /effort: ajusta o nível de esforço de raciocínio dentro de limites suportados pelo modelo.
• /usage, /cost e /stats: mostram consumo, custos e estatísticas da sessão, com /cost e /stats como atalhos de digitação para abas específicas.

1.1.2 Referência dos principais comandos embutidos

Os comandos abaixo têm comportamento estável ou dependem da versão indicada. Quando houver diferença recente, isso é sinalizado para evitar uso incorreto em ambientes desatualizados.

• /add-dir <path>: adiciona um diretório de trabalho.
• /agents: gerencia configurações de agentes.
• /branch [name]: abre a conversa em uma nova sessão; antes era /fork.
• /btw <question>: faz uma pergunta lateral temporária enquanto Claude trabalha na tarefa principal, sem poluir o contexto da conversa principal.
• /cd <path>: troca o diretório sem quebrar a cache do prompt. Recurso adicionado na v2.1.169.
• /chrome: configura a integração com o navegador Chrome.
• /clear: limpa a conversa. Também disponível como /reset e /new.
• /color [color|default]: define a cor da barra de prompt. Sem argumento, escolhe uma cor aleatória de sessão nas versões v2.1.128 ou mais recentes; com argumento, aceita nome de cor ou hexadecimal.
• /compact [instructions]: compacta a conversa e pode incluir instruções de foco.
• /config ou /settings: abre as configurações.
• /context: mostra o uso de contexto em uma grade colorida.
• /copy [N]: copia a resposta do assistente para a área de transferência; com w, grava em arquivo.
• /cost: abre a aba de custo dentro de uso/consumo. Válido a partir da v2.1.118.
• /desktop ou /app: continua a sessão no aplicativo Desktop.
• /diff: visualiza interativamente diferenças de arquivos ainda não commitados.
• /doctor: diagnostica a instalação, pode ser aberto enquanto o Claude responde, mostra ícones de status e permite auto-correção com a tecla f. O layout foi aprimorado na v2.1.116 e refinado para uma árvore plana com ícones mais claros na v2.1.178.
• /effort [low|medium|high|xhigh|max|auto]: ajusta o esforço por meio de um controle interativo com setas. Os níveis vão de low para medium, high, xhigh e max. O nível xhigh foi introduzido na v2.1.111. O padrão é high no Opus 4.8 e xhigh no Opus 4.7. xhigh exige Opus 4.8 ou 4.7; max funciona com Opus 4.8, 4.7, 4.6 e Sonnet 4.6. O menu também oferece ultracode, mas isso não é um nível de esforço do modelo: ele envia xhigh e faz o Claude orquestrar fluxos dinâmicos; é um comportamento apenas da sessão.
• /exit ou /quit: encerra o REPL.
• /export [filename]: exporta a conversa atual para um arquivo ou para a área de transferência.
• /usage-credits: configura uso extra para limites de taxa; o nome anterior era /extra-usage, ainda aceito como alias na v2.1.144 e posteriores.
• /fast [on|off]: alterna o modo rápido.
• /feedback ou /bug: envia feedback. Desde a v2.1.141, é possível anexar sessões recentes dos últimos 24h ou 7 dias para dar contexto a relatos espalhados por mais de uma sessão. A partir da v2.1.178, /bug exige uma descrição antes do envio.
• /focus: alterna a visualização de foco. Introduzido na v2.1.110; substitui Ctrl+O para esse toggle específico.
• /goal <statement>: registra um objetivo de sessão. Claude continua trabalhando até cumprir a meta. /goal clear remove a meta. O objetivo aparece na barra de status e também em um painel com tempo decorrido, número de turnos e uso de tokens. Adicionado na v2.1.139.
• /help: mostra ajuda.
• /hooks: exibe configurações de hooks.
• /ide: gerencia integrações com IDE.
• /init: inicializa o CLAUDE.md. Defina CLAUDE_CODE_NEW_INIT=1 para usar o fluxo interativo.
• /insights: gera relatório de análise da sessão.
• /install-github-app: configura o app de GitHub Actions.
• /install-slack-app: instala o app do Slack.
• /keybindings: abre a configuração de atalhos do teclado.
• /less-permission-prompts: analisa chamadas recentes de ferramentas Bash/MCP e propõe uma allowlist priorizada em .claude/settings.json para reduzir prompts de permissão. Recurso adicionado na v2.1.111.
• /login: troca de conta Anthropic.
• /logout: encerra a sessão da conta Anthropic.
• /mcp: gerencia servidores MCP e OAuth.
• /memory: edita CLAUDE.md e alterna memória automática.
• /mobile, /ios e /android: mostram QR code para o app móvel.
• /model [model]: escolhe modelo com navegação por setas de esforço. Desde a v2.1.153, a escolha fica salva como padrão para novas sessões, igual ao comportamento da IDE. Para aplicar apenas na sessão atual, pressione s depois de selecionar. O keybinding modelPicker:setAsDefault foi renomeado para modelPicker:thisSessionOnly, e a antiga ação d virou s.
• /passes: compartilha uma semana grátis do Claude Code.
• /permissions ou /allowed-tools: consulta e atualiza permissões.
• /plan [description]: entra no modo de planejamento.
• /plugin: gerencia plugins.
• /proactive: alias de /loop, adicionado na v2.1.105.
• /powerup: ensina recursos por meio de lições interativas com demonstrações animadas.
• /privacy-settings: configurações de privacidade, disponível apenas nos planos Pro e Max.
• /release-notes: mostra o changelog.
• /recap: exibe um resumo da sessão ao retornar para ela. Adicionado na v2.1.108.
• /reload-plugins: recarrega plugins ativos.
• /reload-skills: faz nova varredura nas pastas de skills sem reiniciar a sessão. Recurso da v2.1.152.
• /remote-control ou /rc: controle remoto a partir do claude.ai.
• /remote-env: configura o ambiente remoto padrão.
• /rename [name]: renomeia a sessão.
• /resume [session] ou /continue: retoma uma conversa existente.
• /review <pr>: revisa um pull request do GitHub. Desde a v2.1.186, usa o mesmo mecanismo de revisão de /code-review medium. Para revisar o diff local do repositório, use /code-review.
• /rewind ou /checkpoint: retrocede a conversa e/ou o código.
• /sandbox: alterna o modo sandbox.
• /schedule [description]: cria e gerencia tarefas agendadas na nuvem.
• /scroll-speed <+N|-N>: ajusta a velocidade de rolagem da roda do mouse no painel de live preview do TUI, com pré-visualização em tempo real. A configuração persiste por máquina em ~/.claude/preferences.json. Adicionado na v2.1.139.
• /security-review: analisa a branch em busca de vulnerabilidades de segurança.
• /skills: lista as skills disponíveis.
• /stats: abre a aba de estatísticas, com uso diário, sessões e streaks. É atalho de digitação para a visualização de uso, disponível a partir da v2.1.118.
• /stickers: pede stickers do Claude Code.
• /status: mostra versão, modelo e conta.
• /statusline: configura a linha de status.
• /tasks: lista e gerencia tarefas em background.
• /team-onboarding: gera um guia de ramp-up para colegas com base na configuração local do Claude Code. Recurso novo na v2.1.101.
• /terminal-setup: configura atalhos do terminal.
• /theme: abre o seletor de temas e permite gerenciar temas personalizados. Desde a v2.1.118, temas customizados podem ser definidos por JSON em ~/.claude/themes/<nome>.json.
• /tui: alterna o modo TUI em tela cheia com renderização sem flicker. Adicionado na v2.1.110.
• /ultraplan <prompt>: cria um plano em uma sessão de ultraplan para revisão no navegador.
• /ultrareview: faz revisão de código na nuvem com análise multiagente. Adicionado na v2.1.111.
• /undo: alias de /rewind.
• /upgrade: abre a página de upgrade para um plano superior.
• /usage: dashboard canônico de uso. Combina limites do plano, rate limits, custo e estatísticas diárias. /cost e /stats são atalhos de digitação que abrem abas específicas.
• /voice: alterna a ditado por voz push-to-talk.
• /workflows: exibe execuções de workflows dinâmicos, em andamento e concluídos. Recurso adicionado na v2.1.154.

1.1.3 Comandos com escopo e comportamento recente

Alguns comandos mudaram de nome, ganharam alias ou tiveram o fluxo ajustado em versões recentes. Isso é relevante porque o mesmo atalho pode ter comportamento diferente dependendo da versão instalada.

• /fork foi renomeado para /branch, mas ainda funciona como alias na v2.1.77 e posteriores.
• /output-style está depreciado desde a v2.1.73.
• /pr-comments foi removido na v2.1.91; a recomendação é pedir ao Claude diretamente para inspecionar comentários do PR.
• /vim foi removido na v2.1.92; use /config e ajuste o modo de editor.
• /review <pr> passou a usar o mesmo engine de /code-review medium na v2.1.186.
• /model agora exibe rótulos legíveis, como “Sonnet 4.6”, em vez de IDs crus.

1.1.4 /goal: condição de conclusão da sessão

Use /goal quando quiser que Claude trabalhe sob uma meta explícita durante vários turnos. Isso é útil em tarefas longas, como migração de API, correções em cascata ou refatorações que precisam chegar até um resultado final verificável.

O comportamento prático é o seguinte: ao registrar o objetivo, o sistema mantém a meta ativa entre as interações e exibe um painel com tempo decorrido, número de turnos e tokens usados. Isso ajuda a monitorar custo e progresso sem perder o foco da conversa.

Você pode limpar a meta com /goal clear. O recurso funciona no modo interativo, com claude -p e também em Remote Control.

User: /goal Migrar o serviço de pagamentos de REST para gRPC e validar todos os testes de integração.
Claude: Meta registrada. Vou continuar até o objetivo ser concluído.
[Goal panel: ⏱ 0s · turns 0 · tokens 0]

User: liste os endpoints REST existentes
Claude: [executa a tarefa e atualiza o painel]

1.1.5 /team-onboarding: guia de entrada para a equipe

O comando /team-onboarding gera um material de ramp-up com base na configuração local do projeto. Ele inspeciona o CLAUDE.md, skills instaladas, subagentes, hooks e workflows recentes, produzindo um guia para que novos desenvolvedores entendam o ambiente mais rapidamente.

Não é preciso instalar nada: ele já vem com o Claude Code. É uma ferramenta útil para equipes que querem reduzir o tempo até a primeira contribuição consistente, especialmente em repositórios com muitas convenções locais.

claude /team-onboarding

O guia gerado costuma resumir:

• o propósito do projeto e as convenções principais registradas em CLAUDE.md;
• as skills disponíveis e em que situações são acionadas automaticamente;
• os subagentes configurados e suas responsabilidades;
• os hooks que disparam em eventos comuns;
• os fluxos de trabalho que um novo membro da equipe precisa dominar.

Esse comando foi disponibilizado na versão v2.1.101, com referência de abril de 2026 no material-fonte.

1.1.6 Skills: o padrão recomendado para comandos personalizados

Os comandos personalizados migraram para o modelo de skills. Ainda existe compatibilidade com .claude/commands/, mas o padrão atual é organizar tudo em .claude/skills/. Em ambas as formas, o usuário invoca o comando com /nome.

Se o mesmo nome existir nas duas estruturas, a skill ganha prioridade. Por exemplo, se houver .claude/commands/review.md e .claude/skills/review/SKILL.md, a versão da skill é a que será usada.

1.1.7 Como migrar um comando legado para skill

A migração é estrutural: sai um arquivo solto, entra uma pasta com SKILL.md. Isso permite reunir instruções, scripts, templates e arquivos de referência no mesmo lugar.

Antes:
.claude/commands/optimize.md

Depois:
.claude/skills/optimize/SKILL.md

1.1.8 Por que usar skills em vez de comandos antigos

• Estrutura em diretórios: permite agrupar scripts, modelos e arquivos auxiliares.
• Auto-invocação: Claude pode acionar skills automaticamente quando o contexto indicar relevância.
• Controle de invocação: você define se o comando pode ser chamado pelo usuário, pelo Claude ou por ambos.
• Execução em subagente: com context: fork, a skill roda em contexto isolado.
• Disclosure progressivo: arquivos adicionais só são carregados quando realmente necessários.

1.1.9 Estrutura mínima de uma skill

Uma skill é uma pasta contendo o arquivo SKILL.md. O frontmatter define nome, descrição e comportamento. O corpo do arquivo contém as instruções que o Claude deve seguir.

---
name: my-command
description: O que este comando faz e quando usar
---

# Meu Comando

Instruções para o Claude seguir quando este comando for acionado.

1. Primeiro passo
2. Segundo passo
3. Terceiro passo

1.1.10 Campos do frontmatter e seus efeitos

Os campos abaixo controlam como a skill aparece, quem pode acioná-la, quais ferramentas ela usa e se ela roda isolada.

• name: nome do comando, que vira /name. Por padrão, usa o nome da pasta.
• description: descrição curta. Ajuda o Claude a decidir quando usar a skill. Se não existir, o sistema pode usar o primeiro parágrafo.
• argument-hint: dica de argumentos esperados, útil para autocompletar.
• allowed-tools: lista de ferramentas que podem ser usadas sem pedir permissão. Por padrão, herda as permissões do ambiente.
• model: modelo específico a ser usado, quando a skill precisa forçar um comportamento de modelo.
• disable-model-invocation: quando true, apenas o usuário pode invocar o comando; o Claude não deve acioná-lo automaticamente.
• user-invocable: quando false, oculta o comando do menu /.
• context: defina como fork para rodar em subagente isolado.
• agent: tipo de agente usado quando context: fork está ativo; o padrão é general-purpose.
• hooks: hooks específicos da skill, como PreToolUse, PostToolUse e Stop.

1.1.11 Argumentos: passando dados para a skill

As skills podem receber argumentos de duas formas. A primeira é usar o placeholder $ARGUMENTS, que captura a string completa passada após o nome do comando. A segunda é dividir por posição com $0, $1 e assim por diante.

Quando você usa $ARGUMENTS, toda a linha após o comando entra como um único texto. Isso é simples e funciona bem quando o comando precisa apenas de um bloco livre, como um número de issue, um caminho ou uma frase descritiva.

---
name: fix-issue
description: Corrige uma issue do GitHub pelo número
---

Corrija a issue #$ARGUMENTS seguindo os padrões de código do projeto.

/fix-issue 123

Nesse caso, $ARGUMENTS vira 123.

Quando o comando precisa de campos separados, use $0, $1 e outros índices. Isso é melhor para cenários em que cada posição representa um dado diferente, como número do PR e nível de prioridade.

---
name: review-pr
description: Revisa um PR com prioridade
---

Revise o PR #$0 com prioridade $1.

/review-pr 456 high

Aqui, $0 recebe 456 e $1 recebe high.

Além disso, ${CLAUDE_PROJECT_DIR} resolve para o caminho absoluto da raiz do projeto. Esse comportamento foi documentado como disponível na v2.1.196, e é muito útil para skills que precisam montar caminhos absolutos sem depender do diretório atual da sessão.

1.1.12 Contexto dinâmico com comandos de shell

Você pode executar comandos bash antes de enviar o prompt principal usando a sintaxe !`comando`. Isso injeta contexto vivo no conteúdo da skill, o que é valioso para comandos como commit, revisão ou auditoria.

O uso é prático, mas também exige cuidado: os comandos são executados de fato e seu resultado entra no prompt. Portanto, escolha comandos seguros e previsíveis, e conceda allowed-tools apenas ao necessário.

---
name: commit
description: Cria um commit git com contexto
allowed-tools: Bash(git *)
---

## Contexto

- Status atual do git: !`git status`
- Diff atual do git: !`git diff HEAD`
- Branch atual: !`git branch --show-current`
- Commits recentes: !`git log --oneline -5`

## Sua tarefa

Com base nas alterações acima, crie um único commit git.

1.1.13 Referências de arquivos com @

Outro recurso útil é referenciar conteúdo de arquivos diretamente com @. Isso faz o Claude considerar o conteúdo indicado sem que você precise colar o arquivo inteiro no prompt.

Revise a implementação em @src/utils/helpers.js
Compare @src/old-version.js com @src/new-version.js

1.1.14 Comandos de plugin

Plugins também podem fornecer comandos. O formato geral é /plugin-name:command-name. Quando não há conflito de nome com outros comandos, às vezes o atalho simples /command-name também pode funcionar.

/frontend-design:frontend-design
/commit-commands:commit

1.1.15 Prompts MCP como comandos

Servidores MCP podem expor prompts como slash commands no formato /mcp__<server-name>__<prompt-name> [arguments]. Isso padroniza a invocação de ações externas a partir da sessão interativa.

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high

Também é possível controlar o acesso aos servidores MCP nas permissões:

• mcp__github: acesso ao servidor GitHub inteiro;
• mcp__github__*: acesso curinga a todas as ferramentas;
• mcp__github__get_issue: acesso apenas a uma ferramenta específica.

1.1.16 Arquitetura e ciclo de vida dos comandos

O fluxo interno de um comando passa por etapas previsíveis. Primeiro, o Claude identifica o tipo de comando. Depois carrega a skill ou o comando legado, lê o frontmatter, substitui variáveis, executa os comandos de shell permitidos e finalmente envia o prompt processado para o modelo.

Em comandos dinâmicos, isso significa que a resposta pode depender do estado atual do repositório, do resultado de git diff, do branch ativo e até do conteúdo de arquivos referenciados.

Entrada do usuário: /command-name
↓
Identificação do tipo
↓
Carregamento de SKILL.md ou comando legado
↓
Leitura do frontmatter
↓
Substituição de variáveis e execução de shell
↓
Envio do prompt ao Claude
↓
Resposta ao usuário

1.1.17 Exemplos incluídos no pacote de comandos

Os arquivos deste bloco representam exemplos prontos para uso, que podem ser instalados como skills ou, em modo legado, como comandos.

1.1.18 /optimize: análise de otimização de código

Esse comando examina o código procurando problemas de desempenho, vazamentos de memória, oportunidades de melhoria algorítmica, caching e concorrência. Ele é útil quando você quer uma revisão orientada a performance sem perder foco em correção funcional.

Na prática, a análise deve seguir uma ordem de prioridade para evitar que micro-otimizações ocultem gargalos maiores. Primeiro vêm os gargalos mais caros, depois os problemas de memória, em seguida algoritmos, cache e, por fim, questões de concorrência.

/optimize
[cole seu código]

O retorno esperado deve informar severidade, localização, explicação e correção recomendada com exemplo de código.

• Severidade: Critical, High, Medium ou Low.
• Localização: trecho, função ou arquivo afetado.
• Explicação: por que aquilo é um problema e como impacta o sistema.
• Correção recomendada: solução prática com exemplo.

1.1.19 /pr: preparação de pull request

O comando /pr organiza a preparação de uma PR com foco em higiene do repositório. O fluxo proposto inclui formatação, testes, revisão de diff, staging e elaboração de mensagem de commit conforme conventional commits.

O comportamento é intencionalmente prescritivo: ele ajuda a evitar PRs incompletas, sem testes ou com alterações mal descritas. Esse comando é melhor quando você quer seguir um checklist consistente antes de abrir a solicitação de revisão.

/pr

O checklist inclui:

• executar formatação com prettier --write .;
• rodar testes com npm test;
• revisar o diff com git diff HEAD;
• adicionar alterações com git add .;
• criar mensagem de commit usando convenções como feat:, fix:, docs:, refactor:, test: e chore:;
• gerar um resumo da PR com o que mudou, por que mudou, testes executados e impactos potenciais.

1.1.20 /generate-api-docs: documentação de API a partir do código-fonte

Esse comando gera documentação abrangente de API com base no conteúdo do código. Ele procura assinaturas de funções, comentários JSDoc, módulos e exemplos de uso, consolidando tudo em um arquivo Markdown.

É especialmente útil em projetos com APIs internas ou públicas que precisam de documentação viva. O fluxo também deve incluir esquemas de request/response, documentação de erros, exemplos em curl e tipos TypeScript quando aplicável.

/generate-api-docs

O formato de saída esperado é um arquivo Markdown em /docs/api.md.

1.1.21 /commit: commit Git com contexto dinâmico

O comando /commit cria um commit usando contexto atual do repositório. Ele consulta o status, o diff, o branch e os commits mais recentes para escrever uma mensagem mais coerente com o histórico do projeto.

Se o usuário informar uma mensagem por argumento, ela deve ser usada diretamente. Caso contrário, o comando deve analisar as mudanças e sugerir uma mensagem em formato conventional commits.

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*)
argument-hint: [message]
description: Create a git commit with context
---

/commit "docs: atualiza guias de comandos"

Quando a mensagem não é informada, a sugestão deve seguir estes tipos:

• feat: para novos recursos;
• fix: para correções de bug;
• docs: para mudanças de documentação;
• refactor: para refatoração;
• test: para inclusão ou ajuste de testes;
• chore: para manutenção.

1.1.22 /push-all: stage, commit e push com travas de segurança

Esse é um fluxo mais agressivo e deve ser usado com cautela. Ele adiciona todas as mudanças, cria um commit e envia para o remoto, mas antes precisa verificar se tudo realmente pode ir junto. É adequado quando há confiança de que o conjunto de alterações é coeso.

O comando começa com análise paralela do estado do repositório e depois executa checagens de segurança. Essa etapa é fundamental porque o risco aqui não é só funcional: é possível vazar segredos, publicar artefatos indevidos ou empurrar arquivos grandes sem Git LFS.

As verificações devem procurar especificamente:

• segredos, como .env*, *.key, *.pem, credentials.json, secrets.yaml, id_rsa, *.p12, *.pfx e *.cer;
• chaves de API com valores reais em variáveis como *_API_KEY, *_SECRET e *_TOKEN;
• arquivos grandes, acima de 10 MB, sem Git LFS;
• artefatos de build, como node_modules/, dist/, build/, __pycache__/, *.pyc e .venv/;
• arquivos temporários, como .DS_Store, thumbs.db, *.swp e *.tmp.

Também é recomendado validar se o branch correto está ativo, se não existem conflitos de merge e se o .gitignore está coerente.

O fluxo seguro exige confirmação explícita do usuário antes de continuar. A resposta deve mostrar um resumo com quantidade de arquivos, estatísticas de inserções e deleções, além de alertas de segurança e branch de destino.

📊 Resumo das alterações:
- X arquivos modificados, Y adicionados, Z removidos
- Total: +AAA inserções, -BBB deleções

🔒 Segurança: ✅ Sem segredos | ✅ Sem arquivos grandes | ⚠️ [avisos]
🌿 Branch: [nome] → origin/[nome]

Vou executar: git add . → commit → push

Digite 'yes' para prosseguir ou 'no' para cancelar.

Se o usuário confirmar, o comando executa o staging, valida o estado e gera a mensagem de commit, normalmente com resumo em bullets. Em caso de falha no push, o comportamento esperado é tentar git pull --rebase e então repetir o push; se o branch for protegido, a orientação correta é seguir o fluxo de PR.

1.1.23 /doc-refactor: reorganização de documentação

Esse comando é voltado para estruturar documentação de projetos. Ele começa analisando o tipo do projeto — biblioteca, API, app web, CLI ou microsserviços —, a arquitetura e as personas que vão consumir a documentação.

Depois, o fluxo centraliza a documentação técnica em docs/, cria um README raiz mais enxuto como porta de entrada e distribui documentação por componente, pacote ou serviço quando necessário. Essa separação melhora navegabilidade e reduz o acoplamento entre visão geral e detalhe técnico.

A estratégia recomendada inclui categorizar docs/ por temas relevantes ao projeto, como arquitetura, referência de API, banco de dados, design, troubleshooting, deployment e contribuição. Nem todos os projetos precisam de todas as categorias; a estrutura deve se adaptar ao contexto.

O comando também incentiva a criação de guias específicos, como guia do usuário, documentação de API, guia de desenvolvimento e guia de deployment.

Para diagramas, o padrão indicado é usar Mermaid em todos os casos, mantendo consistência visual e facilitando manutenção.

1.1.24 /setup-ci-cd: pipeline de CI/CD e qualidade

Esse comando implementa gates de DevOps adaptados ao projeto. Ele começa detectando linguagens, frameworks, sistema de build e as ferramentas já presentes, para não sobrescrever decisões existentes.

Em seguida, configura hooks de pre-commit com o ecossistema adequado: formatação, lint, segurança, type-check e testes. A ideia é usar ferramentas livres e abertas, manter o fluxo rápido e respeitar configurações já consolidadas no repositório.

O pipeline de GitHub Actions deve espelhar os checks locais e, quando fizer sentido, usar matriz de versões e plataformas, além de passos de build, teste e implantação. O último passo é verificar se tudo funciona localmente e em um PR de teste.

Exemplos de ferramentas esperadas incluem Prettier, Black, gofmt, rustfmt, ESLint, Ruff, golangci-lint, Clippy, Bandit, gosec, cargo-audit, npm audit, TypeScript, mypy e flow.

1.1.25 /unit-test-expand: expansão da cobertura de testes

O comando /unit-test-expand amplia a cobertura de testes existentes. Ele parte de um relatório de coverage para localizar ramos não testados, bordas e áreas com baixa cobertura, e depois preenche as lacunas com novos testes unitários.

Esse fluxo é útil quando você já tem uma suíte funcional, mas quer elevar confiança em caminhos de erro, condições de contorno e transições de estado. O comando deve procurar especificamente manipulação de exceções, valores mínimos e máximos, entradas nulas ou vazias, efeitos colaterais e cenários de corner case.

As estruturas de teste variam conforme a linguagem e o projeto: Jest, Vitest e Mocha em JavaScript/TypeScript; pytest e unittest em Python; Go testing e testify em Go; framework de testes nativo em Rust.

A saída deve trazer apenas blocos de código dos novos testes, respeitando os padrões de nomenclatura e a estrutura já existente no projeto.

1.1.26 Instalação dos comandos como skills recomendadas

Se você quiser usar esses exemplos como skills, a instalação consiste em criar a pasta .claude/skills e copiar cada comando para uma pasta própria com SKILL.md. Esse formato é o mais moderno e é o recomendado para novos projetos.

mkdir -p .claude/skills

for cmd in optimize pr commit; do
  mkdir -p .claude/skills/$cmd
  cp 01-slash-commands/$cmd.md .claude/skills/$cmd/SKILL.md
done

Esse exemplo mostra apenas alguns comandos, mas o mesmo padrão vale para os demais arquivos deste bloco.

1.1.27 Instalação como comandos legados

Se ainda for necessário usar o modelo antigo, copie os arquivos para .claude/commands/. Essa abordagem pode ser útil em ambientes que ainda dependem da estrutura histórica, embora o uso de skills seja preferível.

Há duas opções comuns:

• Escopo do projeto: colocar em .claude/commands para toda a equipe.
• Escopo pessoal: colocar em ~/.claude/commands para uso individual.

# Projeto inteiro
mkdir -p .claude/commands
cp 01-slash-commands/*.md .claude/commands/

# Uso pessoal
mkdir -p ~/.claude/commands
cp 01-slash-commands/*.md ~/.claude/commands/

1.1.28 Boas práticas para criar comandos reutilizáveis

Comandos bons são curtos, focados e fáceis de acionar. Eles devem declarar claramente quando usar, quais ferramentas precisam e qual saída é esperada. Quanto mais objetivo o comando, mais previsível será sua execução.

• Use nomes claros e orientados à ação.
• Inclua uma descrição com condições de gatilho.
• Mantenha o comando focado em uma única tarefa.
• Evite lógica complexa demais dentro do comando.
• Não coloque informação sensível hardcoded.
• Use disable-model-invocation para ações com efeito colateral que não devem ser acionadas automaticamente.
• Use o prefixo ! para capturar contexto dinâmico.
• Organize arquivos relacionados dentro da pasta da skill.

1.1.29 Troubleshooting de comandos

Quando um comando não aparece ou não executa como esperado, o problema geralmente está na localização do arquivo, no nome declarado no frontmatter, nas permissões ou no contexto atual da sessão.

Se o comando não for encontrado, verifique se ele está em .claude/skills/<nome>/SKILL.md ou em .claude/commands/<nome>.md, confirme se o campo name bate com o atalho esperado, reinicie a sessão do Claude Code e consulte /help para ver os comandos disponíveis.

Se o comando executa mas o resultado vem errado, vale reforçar instruções, incluir exemplos no arquivo da skill, revisar allowed-tools e testar primeiro com entradas simples.

Se houver conflito entre skill e comando legado com o mesmo nome, a skill prevalece. A correção prática é remover uma das versões ou renomeá-la.

1.1.30 Conceitos relacionados

Esses comandos se conectam diretamente com outros recursos do Claude Code, como memória persistente em CLAUDE.md, skills autoacionáveis, subagentes, hooks e plugins. Em projetos maiores, essa combinação é o que transforma o Claude Code de um assistente de chat em uma camada de automação operacional.

2 Módulo — Memória, CLAUDE.md e regras persistentes

2.1 Memória no Claude Code: visão geral, escopo e persistência

No Claude Code, memória é o mecanismo que permite manter contexto entre sessões, em vez de depender apenas da janela atual de conversa. Isso é importante porque o conteúdo persistente pode registrar padrões de trabalho, normas de time, preferências pessoais, regras de um diretório específico e até documentação externa referenciada por arquivo. O sistema também convive com a memória automática do Claude, que aprende e grava anotações ao longo do uso.

Há dois grandes modelos de memória no ecossistema Claude: a síntese automática usada no Claude web/Desktop e os arquivos CLAUDE.md no Claude Code. Neste módulo, o foco é o modelo baseado em filesystem, porque ele é versionável, hierárquico e configurável por projeto, usuário, diretório e políticas organizacionais.

2.1.1 O que a memória persistente permite fazer

• Compartilhar padrões do projeto com todo o time.
• Guardar preferências pessoais de desenvolvimento.
• Aplicar regras específicas por pasta, módulo ou subárvore.
• Importar documentação já existente sem duplicar conteúdo.
• Versionar instruções como parte do repositório.

Na prática, isso transforma o Claude Code em um agente que carrega contexto útil automaticamente sempre que você abre o projeto ou acessa uma subpasta coberta por regras.

2.2 Comandos rápidos de memória

Os comandos e atalhos mais relevantes são estes:

• /init: inicializa a memória do projeto e cria um CLAUDE.md base.
• /memory: abre os arquivos de memória para edição completa no editor do sistema.
• # como prefixo de memória rápida: recurso legado, descontinuado.
• @path/to/file: importa conteúdo externo para dentro do contexto de memória.

O atalho # foi descontinuado. Se você encontrar material antigo citando esse formato, o comportamento correto hoje é usar /memory ou pedir de forma conversacional para Claude registrar a informação.

2.3 Inicializando memória com /init

O comando /init é o caminho mais rápido para começar um projeto novo com Claude Code. Ele cria um arquivo CLAUDE.md com uma estrutura inicial de documentação e convenções do projeto.

/init

Ao executar esse comando, Claude tende a:

• criar um novo CLAUDE.md no projeto, normalmente em ./CLAUDE.md ou ./.claude/CLAUDE.md;
• registrar convenções e diretrizes iniciais;
• montar uma base de contexto persistente entre sessões;
• oferecer uma estrutura para documentar padrões técnicos do repositório.

Esse fluxo é mais útil quando você ainda não tem uma memória estruturada para o projeto ou quer começar com uma configuração guiada.

2.3.1 Modo interativo aprimorado

Existe um fluxo interativo em múltiplas etapas, disponível ao definir a variável de ambiente CLAUDE_CODE_NEW_INIT=1. Esse modo é útil quando você quer que o processo de criação da memória seja mais guiado e menos automático.

CLAUDE_CODE_NEW_INIT=1 claude
/init

Nesse modo, Claude conduz a configuração passo a passo, o que facilita a criação de uma memória inicial bem organizada, principalmente em projetos mais complexos ou em times com padrões ainda não documentados.

2.3.2 Quando usar /init

• Ao iniciar um projeto novo no Claude Code.
• Quando você quer estabelecer padrões do time logo no começo.
• Quando o repositório ainda não possui uma estrutura de memória persistente.
• Quando deseja documentar arquitetura, comandos e regras fundamentais do projeto.

2.3.3 Exemplo prático de saída esperada

Um /init bem sucedido pode gerar uma estrutura semelhante a esta:

# Project Configuration

## Project Overview
- Name: Your Project
- Tech Stack: [Your technologies]
- Team Size: [Number of developers]

## Development Standards
- Code style preferences
- Testing requirements
- Git workflow conventions

2.4 Atualizações rápidas: estado atual e histórico

O método antigo de escrever uma regra inline com # não funciona mais. Se você vir instruções como “# Always use TypeScript strict mode”, trate isso apenas como referência histórica. O caminho suportado hoje é editar os arquivos de memória com /memory ou pedir explicitamente para Claude lembrar da regra.

2.4.1 Opção 1: /memory

Esse comando abre os arquivos de memória no editor padrão do sistema. Ele é a melhor escolha para mudanças amplas, reorganização de conteúdo, revisão de estrutura e edição de múltiplas seções.

/memory

O comportamento esperado é:

• abrir o editor configurado no sistema operacional;
• permitir edições extensas em um ou mais arquivos de memória;
• mostrar as opções de escopo disponíveis, como memória do projeto, memória do usuário e memória gerenciada;
• recarregar o conteúdo atualizado depois que o arquivo for salvo.

2.4.2 Opção 2: pedido conversacional

Você também pode pedir naturalmente para Claude registrar uma preferência. Isso é útil para ajustes menores, especialmente quando você quer manter o fluxo da conversa sem sair para o editor.

Remember that we always use TypeScript strict mode in this project.
Please add to memory: prefer async/await over promise chains.

Ao receber esse tipo de solicitação, Claude deve identificar o escopo apropriado e propor onde a regra será salva, normalmente entre memória do projeto e memória pessoal.

2.4.3 Quando usar /memory

• Ao revisar a memória já existente.
• Ao fazer reorganização de várias regras.
• Ao documentar padrões técnicos mais detalhados.
• Ao manter a memória sincronizada com a evolução do projeto.

2.4.4 Comparação prática entre /memory e /init

• /init: cria a base inicial da memória; indicado para começo de projeto.
• /memory: edita arquivos já existentes; indicado para manutenção contínua.

2.5 Importação de documentação com @path/to/file

Os arquivos CLAUDE.md aceitam referência a conteúdo externo por meio da sintaxe @caminho/do/arquivo. Isso evita duplicação e permite que sua memória apenas aponte para documentação já existente no repositório ou fora dele.

# Project Documentation
See @README.md for project overview
See @package.json for available npm commands
See @docs/architecture.md for system design

# Import from home directory using absolute path
@~/.claude/my-project-instructions.md

2.5.1 Como a importação funciona na prática

• Funciona com caminhos relativos e absolutos.
• Suporta imports recursivos até a profundidade máxima de 5 níveis.
• Na primeira importação de um local externo, o Claude pode exibir um diálogo de aprovação por segurança.
• Diretivas de importação não são avaliadas dentro de spans ou blocos de código Markdown, o que permite documentá-las em exemplos sem disparar a importação.
• O conteúdo importado entra automaticamente no contexto do Claude.

Na prática, esse mecanismo é ideal quando você já possui README.md, arquitetura, contrato de API ou esquemas de banco documentados em outros arquivos e quer apenas reaproveitar essas fontes.

2.6 Arquitetura da memória no Claude Code

A memória no Claude Code é hierárquica. Isso significa que diferentes escopos têm prioridades e finalidades diferentes. A ideia não é armazenar tudo no mesmo lugar, mas sim permitir camadas: políticas organizacionais, padrões do time, preferências do usuário, regras de diretório e memória automática.

A ordem completa de precedência é esta:

1. Managed Policy, no nível organizacional.
2. Managed Drop-ins, quando disponíveis.
3. Project Memory, compartilhada pelo time.
4. Project Rules, por pasta e assunto.
5. User Memory, pessoal e válida para todos os projetos.
6. User-Level Rules, regras pessoais por tema.
7. Local Project Memory, preferências pessoais daquele projeto.
8. Auto Memory, anotações automáticas do Claude.

2.6.1 Managed Policy e Managed Drop-ins

A camada de maior prioridade é a política gerenciada pela organização. Ela existe para impor padrões corporativos, exigências de segurança e diretrizes globais. Os caminhos variam por sistema operacional:

• macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
• Linux/WSL: /etc/claude-code/CLAUDE.md
• Windows: C:\Program Files\ClaudeCode\CLAUDE.md

Ao lado dessa política, versões mais recentes suportam managed-settings.d/ para arquivos modulares de política. Nessa estrutura, os arquivos são mesclados em ordem alfabética. Esse recurso é útil quando a organização quer dividir regras grandes em blocos menores e mais administráveis.

2.6.2 Project Memory

A memória do projeto é a camada ideal para padrões compartilhados pelo time. Ela costuma ficar em ./CLAUDE.md ou ./.claude/CLAUDE.md na raiz do repositório e normalmente deve ser versionada no Git.

2.6.3 Project Rules

As regras do projeto ficam em ./.claude/rules/*.md. Elas são modulares, organizadas por tema ou por caminho, e permitem que instruções específicas sejam carregadas apenas quando necessário.

2.6.4 User Memory e User-Level Rules

A memória do usuário fica em ~/.claude/CLAUDE.md e representa preferências pessoais válidas em todos os projetos. Já as regras do usuário em ~/.claude/rules/*.md funcionam como regras pessoais temáticas.

2.6.5 Local Project Memory

O arquivo ./CLAUDE.local.md é a opção para preferências pessoais específicas de um projeto que não devem ir para o versionamento. Ele é plenamente suportado e documentado, e a prática recomendada é adicioná-lo ao .gitignore.

Esse nível é particularmente útil para configurações locais, ajustes de fluxo e preferências individuais que não fazem sentido para todo o time.

2.6.6 Auto Memory

A camada final é a memória automática, localizada em ~/.claude/projects/<project>/memory/. Essa memória é escrita pelo próprio Claude durante as sessões, com registros de aprendizados, padrões e observações recorrentes.

2.7 Descoberta e carregamento de memória

Ao iniciar, o Claude procura arquivos de memória seguindo a hierarquia de precedência. Em termos práticos, isso significa que as camadas superiores podem restringir ou complementar as inferiores, e o contexto carregado depende do que estiver disponível no repositório, no diretório do usuário e nas configurações do sistema.

O comportamento de descoberta também inclui carregamento contextual de arquivos de subtree quando o Claude acessa aqueles diretórios. Isso é importante para monorepos e repositórios grandes, onde nem toda instrução deve entrar no contexto o tempo todo.

2.8 Exclusão de arquivos com claudeMdExcludes

Em monorepos grandes, nem todo CLAUDE.md é relevante para o trabalho atual. O ajuste claudeMdExcludes permite excluir arquivos específicos para que eles não sejam carregados no contexto.

{
  "claudeMdExcludes": [
    "packages/legacy-app/CLAUDE.md",
    "vendors/**/CLAUDE.md"
  ]
}

Esse filtro é aplicado a caminhos relativos à raiz do projeto. Ele é especialmente útil para:

• monorepos com vários subprojetos, quando apenas alguns importam naquele momento;
• repositórios com documentação vendorada ou de terceiros;
• reduzir ruído no contexto evitando instruções antigas, irrelevantes ou conflitantes.

2.9 Hierarquia de arquivos de settings

Além dos arquivos de memória, o Claude Code também resolve configurações por hierarquia. Isso inclui opções como autoMemoryDirectory, claudeMdExcludes e outras preferências do ambiente.

A ordem de precedência das configurações é esta:

1. Managed policy, no nível do sistema.
2. managed-settings.d/, disponível a partir da v2.1.83.
3. .claude/settings.local.json, para overrides locais e ignorados pelo Git.
4. .claude/settings.json, para configurações do projeto versionadas.
5. ~/.claude/settings.json, para preferências do usuário.

Em macOS, ainda é possível configurar por arquivos plist; no Windows, o registro também pode ser lido. Esses mecanismos nativos convivem com os arquivos JSON e seguem as mesmas regras de precedência.

2.9.1 Persistência de /config

A partir da v2.1.119, alterações feitas por /config passam a persistir em ~/.claude/settings.json. Antes, esse tipo de mudança era mais temporário; agora, ela entra na cadeia normal de precedência de política, local e projeto.

Isso significa que /config é ideal para ajustes interativos, enquanto edição direta de arquivos de configuração é melhor para automação, provisionamento e ambientes gerenciados.

2.10 Retenção e limpeza de artefatos

O ajuste cleanupPeriodDays define a janela de retenção para artefatos em disco. O padrão é 30 dias, e desde a v2.1.117 ele vale para quatro tipos de dados: checkpoints, tasks, shell-snapshots e backups.

{
  "cleanupPeriodDays": 14
}

Os arquivos mais antigos que essa janela são podados na inicialização. Esse comportamento ajuda a controlar crescimento excessivo de dados locais e reduzir acúmulo de estado obsoleto.

2.11 Attribution, voz e URL de PR

Algumas configurações controlam metadados em commits, pull requests e recursos de voz. Essas opções são importantes para colaboração e rastreabilidade.

2.11.1 attribution.commit

Quando ativado, adiciona o trailer Co-Authored-By: Claude aos commits criados pelo Claude. Esse comportamento substitui a flag legada includeCoAuthoredBy.

2.11.2 attribution.pr

Quando ativado, inclui atribuição do Claude nas descrições de pull request. Também substitui a lógica antiga de includeCoAuthoredBy, mas aplicada ao contexto de PR.

2.11.3 attribution.sessionUrl

Essa opção, disponível a partir da v2.1.183, remove o link da sessão claude.ai dos commits e PRs gerados em sessões web e de Remote Control. É útil quando você quer evitar exposição desse vínculo em registros públicos ou semipúblicos.

2.11.4 voice.enabled

Ativa ditado por voz com push-to-talk via /voice. Esse nome substitui o antigo voiceEnabled e organiza configurações relacionadas em um namespace mais claro.

2.11.5 prUrlTemplate

Adicionado na v2.1.119, esse campo permite personalizar a URL do badge de PR no rodapé. É especialmente útil para GitLab, Bitbucket ou plataformas internas de code review.

Ele suporta os placeholders {{owner}}, {{repo}} e {{number}}.

{
  "prUrlTemplate": "https://gitlab.internal/{{owner}}/{{repo}}/-/merge_requests/{{number}}"
}

2.11.6 Exemplos de chaves legadas

As chaves antigas ainda podem funcionar, mas estão depreciadas. O ideal é migrar para a forma nova.

• includeCoAuthoredBy foi dividido em attribution.commit e attribution.pr.
• voiceEnabled foi substituído por voice.enabled.

2.12 Sistema modular de regras

As regras modulares ficam em .claude/rules/ e permitem organizar instruções por tema, tipo de arquivo ou área do projeto. Isso é útil quando a memória raiz começaria a ficar grande demais e você precisa de isolamento por assunto.

A estrutura pode existir tanto no nível do projeto quanto no nível do usuário.

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       ├── security.md
│       └── api/
│           ├── conventions.md
│           └── validation.md

~/.claude/
├── CLAUDE.md
└── rules/
    ├── personal-style.md
    └── preferred-patterns.md

As regras dentro de rules/ são descobertas recursivamente. Subdiretórios são suportados, então você pode organizar por tópicos como api/, testing/ e security/. Símlinks também são suportados, o que ajuda a compartilhar regras padronizadas entre repositórios diferentes.

2.12.1 Regras específicas por caminho com frontmatter YAML

Você pode restringir uma regra a determinados arquivos usando frontmatter YAML com a chave paths. Isso é útil quando uma instrução deve valer apenas para uma parte do código.

---
paths: src/api/**/*.ts
---

# API Development Rules

- All API endpoints must include input validation
- Use Zod for schema validation
- Document all parameters and response types
- Include error handling for all operations

O campo paths aceita glob patterns. Exemplos comuns:

• **/*.ts: todos os arquivos TypeScript.
• src/**/*: todos os arquivos abaixo de src/.
• src/**/*.{ts,tsx}: múltiplas extensões.
• {src,lib}/**/*.ts, tests/**/*.test.ts: múltiplos padrões combinados.

2.13 Memória automática

A memória automática é a camada em que Claude grava aprendizados e padrões sozinho enquanto trabalha com o projeto. Diferente dos arquivos CLAUDE.md, que você mantém manualmente, essa camada é criada e atualizada pelo próprio Claude.

2.13.1 Como funciona

• Local: ~/.claude/projects/<project>/memory/.
• Arquivo principal: MEMORY.md.
• Arquivos temáticos: podem existir, por exemplo, debugging.md, api-conventions.md e testing-patterns.md.
• Carregamento: no início da sessão, são carregadas as primeiras 200 linhas de MEMORY.md ou os primeiros 25 KB, o que vier primeiro.
• Arquivos temáticos: não entram todos no startup; são carregados sob demanda.
• Leitura e escrita: Claude lê e também grava esses arquivos conforme encontra padrões relevantes.

2.13.2 Estrutura típica

~/.claude/projects/<project>/memory/
├── MEMORY.md
├── debugging.md
├── api-conventions.md
└── testing-patterns.md

2.13.3 Requisito de versão

A memória automática exige Claude Code v2.1.59 ou superior. Em versões anteriores, esse recurso não está disponível.

npm install -g @anthropic-ai/claude-code@latest

2.13.4 Diretório personalizado de auto memory

Por padrão, a auto memory fica em ~/.claude/projects/<project>/memory/. Desde a v2.1.74, você pode mudar esse local usando autoMemoryDirectory.

{
  "autoMemoryDirectory": "/path/to/custom/memory/directory"
}

Esse ajuste só pode ser definido em escopos de usuário ou local, não em política gerenciada nem em configuração de projeto. Em outras palavras, ele é permitido em ~/.claude/settings.json ou .claude/settings.local.json, mas não em arquivos versionados do projeto.

Os casos de uso mais comuns são:

• armazenar memória automática em local sincronizado ou compartilhado;
• separar os dados automáticos do diretório padrão de configuração do Claude;
• usar um caminho específico por projeto fora da hierarquia padrão.

2.13.5 Compartilhamento entre worktrees e subdiretórios

Todos os worktrees e subdiretórios de um mesmo repositório Git compartilham um único diretório de auto memory. Isso significa que alternar entre worktrees não cria memórias separadas automaticamente. O comportamento prático é importante para evitar confusão em fluxos com múltiplas cópias de trabalho do mesmo repositório.

2.13.6 Memória de subagents

Subagents criados por ferramentas como Task ou execução paralela podem ter seu próprio contexto de memória. Para isso, a definição do subagent pode incluir o campo memory no frontmatter YAML.

memory: user
memory: project
memory: local

Esses valores determinam quais escopos devem ser carregados:

• user: carrega apenas a memória de usuário.
• project: carrega apenas a memória do projeto.
• local: carrega apenas a memória local do projeto.

Isso permite que subagents trabalhem com contexto mais focado, sem herdar toda a hierarquia de memória. Também é possível que subagents mantenham sua própria auto memory, dependendo da configuração e da documentação específica de subagents.

2.13.7 Controlando a auto memory por variável de ambiente

A auto memory pode ser ligada ou desligada com a variável CLAUDE_CODE_DISABLE_AUTO_MEMORY. O nome é um pouco contraintuitivo: o valor 1 desativa, e 0 força ativação.

• 0: força auto memory ligada.
• 1: força auto memory desligada.
• não definido: comportamento padrão, com auto memory habilitada.

# Disable auto memory for a session
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

# Force auto memory on explicitly
CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 claude

2.14 Carregar memória de diretórios adicionais com --add-dir

O parâmetro --add-dir permite que o Claude Code carregue CLAUDE.md de outros diretórios além do diretório de trabalho atual. Isso é especialmente útil em monorepos e cenários com múltiplos projetos correlacionados.

Para ativar esse recurso, é necessário definir a variável de ambiente:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1

Depois, inicie o Claude Code passando o diretório adicional:

claude --add-dir /path/to/other/project

O comportamento esperado é carregar os arquivos de memória desse diretório extra junto com a memória do diretório atual.

2.15 Exemplo prático: memória do projeto

Um arquivo raiz ./CLAUDE.md pode concentrar visão geral, padrões de trabalho, comandos frequentes e links para documentação complementar.

# Project Configuration

## Project Overview
- **Name**: E-commerce Platform
- **Tech Stack**: Node.js, PostgreSQL, React 18, Docker
- **Team Size**: 5 developers
- **Deadline**: Q4 2025

## Architecture
@docs/architecture.md
@docs/api-standards.md
@docs/database-schema.md

## Development Standards

### Code Style
- Use Prettier for formatting
- Use ESLint with airbnb config
- Maximum line length: 100 characters
- Use 2-space indentation

### Naming Conventions
- **Files**: kebab-case (user-controller.js)
- **Classes**: PascalCase (UserService)
- **Functions/Variables**: camelCase (getUserById)
- **Constants**: UPPER_SNAKE_CASE (API_BASE_URL)
- **Database Tables**: snake_case (user_accounts)

### Git Workflow
- Branch names: `feature/description` or `fix/description`
- Commit messages: Follow conventional commits
- PR required before merge
- All CI/CD checks must pass
- Minimum 1 approval required

### Testing Requirements
- Minimum 80% code coverage
- All critical paths must have tests
- Use Jest for unit tests
- Use Cypress for E2E tests
- Test filenames: `*.test.ts` or `*.spec.ts`

### API Standards
- RESTful endpoints only
- JSON request/response
- Use HTTP status codes correctly
- Version API endpoints: `/api/v1/`
- Document all endpoints with examples

### Database
- Use migrations for schema changes
- Never hardcode credentials
- Use connection pooling
- Enable query logging in development
- Regular backups required

### Deployment
- Docker-based deployment
- Kubernetes orchestration
- Blue-green deployment strategy
- Automatic rollback on failure
- Database migrations run before deploy

Esse tipo de arquivo funciona bem quando você quer alinhar todo o time com as mesmas convenções e deixar claros os comandos e práticas esperadas no projeto.

2.16 Exemplo prático: regras específicas de API

Um arquivo em ./src/api/CLAUDE.md pode sobrescrever o contexto da raiz para tudo que estiver abaixo de /src/api/. Isso é útil para concentrar políticas de validação, autenticação, paginação, limites e cache.

# API Module Standards

This file overrides root CLAUDE.md for everything in /src/api/

## API-Specific Standards

### Request Validation
- Use Zod for schema validation
- Always validate input
- Return 400 with validation errors
- Include field-level error details

### Authentication
- All endpoints require JWT token
- Token in Authorization header
- Token expires after 24 hours
- Implement refresh token mechanism

### Response Format

All responses must follow this structure:

{
  "success": true,
  "data": { /* actual data */ },
  "timestamp": "2025-11-06T10:30:00Z",
  "version": "1.0"
}

Error responses:
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "User message",
    "details": { /* field errors */ }
  },
  "timestamp": "2025-11-06T10:30:00Z"
}

### Pagination
- Use cursor-based pagination (not offset)
- Include `hasMore` boolean
- Limit max page size to 100
- Default page size: 20

### Rate Limiting
- 1000 requests per hour for authenticated users
- 100 requests per hour for public endpoints
- Return 429 when exceeded
- Include retry-after header

### Caching
- Use Redis for session caching
- Cache duration: 5 minutes default
- Invalidate on write operations
- Tag cache keys with resource type

Esse exemplo combina vários cuidados importantes: validação obrigatória, JWT no cabeçalho Authorization, expiração do token em 24 horas, uso de refresh token, paginação por cursor, limites de taxa e cache com Redis. Em uma base real, isso evita decisões inconsistentes em endpoints diferentes do mesmo módulo.

2.17 Exemplo prático: memória pessoal

A memória pessoal fica em ~/.claude/CLAUDE.md e é apropriada para preferências individuais que você quer ver refletidas em todos os projetos.

# My Development Preferences

## About Me
- **Experience Level**: 8 years full-stack development
- **Preferred Languages**: TypeScript, Python
- **Communication Style**: Direct, with examples
- **Learning Style**: Visual diagrams with code

## Code Preferences

### Error Handling
I prefer explicit error handling with try-catch blocks and meaningful error messages.
Avoid generic errors. Always log errors for debugging.

### Comments
Use comments for WHY, not WHAT. Code should be self-documenting.
Comments should explain business logic or non-obvious decisions.

### Testing
I prefer TDD (test-driven development).
Write tests first, then implementation.
Focus on behavior, not implementation details.

### Architecture
I prefer modular, loosely-coupled design.
Use dependency injection for testability.
Separate concerns (Controllers, Services, Repositories).

## Debugging Preferences
- Use console.log with prefix: `[DEBUG]`
- Include context: function name, relevant variables
- Use stack traces when available
- Always include timestamps in logs

## Communication
- Explain complex concepts with diagrams
- Show concrete examples before explaining theory
- Include before/after code snippets
- Summarize key points at the end

## Project Organization
I organize my projects as:

project/
├── src/
│   ├── api/
│   ├── services/
│   ├── models/
│   └── utils/
├── tests/
├── docs/
└── docker/

## Tooling
- **IDE**: VS Code with vim keybindings
- **Terminal**: Zsh with Oh-My-Zsh
- **Format**: Prettier (100 char line length)
- **Linter**: ESLint with airbnb config
- **Test Framework**: Jest with React Testing Library

Esse tipo de memória ajuda o Claude a ajustar explicações, exemplos e sugestões ao seu estilo de trabalho. É especialmente útil quando você prefere raciocínio explícito, exemplos concretos e organização modular.

2.18 Atualização de memória durante a sessão

Você pode adicionar novas regras enquanto trabalha em uma sessão ativa. O fluxo normalmente inclui o Claude pedindo qual arquivo de memória deve receber a mudança. Isso é importante porque a mesma preferência pode pertencer ao projeto ou ser pessoal.

2.18.1 Pedido direto

User: Remember that I prefer using React hooks instead of class components
for all new components.

Claude: I'm adding that to your memory. Which memory file should this go in?
1. Project memory (./CLAUDE.md)
2. Personal memory (~/.claude/CLAUDE.md)

User: Project memory

Claude: ✅ Memory saved!

Added to ./CLAUDE.md:
---

### Component Development
- Use functional components with React Hooks
- Prefer hooks over class components
- Custom hooks for reusable logic
- Use useCallback for event handlers
- Use useMemo for expensive computations

2.18.2 Padrão explícito com # new rule into memory

Também é possível acionar a atualização com a frase explícita # new rule into memory. Isso era uma forma de deixar a intenção clara dentro da conversa e ainda é mencionada como um padrão de interação no material de referência.

User: # new rule into memory
Always validate user input with Zod schemas before processing.

Claude: I'm saving this rule to memory. Which memory file should I use?
1. Project memory (./CLAUDE.md)
2. Personal memory (~/.claude/CLAUDE.md)

User: Project memory

Claude: ✅ Memory saved!

Added to ./CLAUDE.md:
---

### Input Validation
- Always validate user input with Zod schemas before processing
- Define schemas at the top of each API handler file
- Return 400 status with validation errors

2.18.3 Boas práticas ao adicionar regras

• Seja específico e orientado a ação.
• Agrupe regras relacionadas sob um título claro.
• Atualize seções existentes em vez de criar duplicações.
• Escolha corretamente o escopo: projeto, usuário ou local.

2.19 Comparação entre Claude Web/Desktop e Claude Code

Embora ambos tratem memória, o comportamento é diferente. No Claude Web/Desktop, a memória é sintetizada automaticamente em ciclos, geralmente a cada 24 horas. No Claude Code, o enfoque principal é em arquivos persistentes, memória automática por projeto e regras versionadas.

A comparação prática inclui estes pontos:

• Síntese automática: existe nos dois contextos, mas no Claude Code ela se manifesta como auto memory.
• Escopo entre projetos: no web/Desktop a memória é compartilhada; no Code, a memória é mais ligada ao projeto.
• Acesso do time: no Claude Code, memória de projeto pode ser versionada e compartilhada por Git.
• Busca e edição: no Code, /memory e edição direta de arquivo são o caminho principal.
• Persistência: a memória do Code é durável, não apenas um resumo de curto prazo.

2.20 Boas práticas e armadilhas comuns

Memória bem feita precisa ser útil, curta o suficiente para ser mantida e clara o bastante para não gerar ambiguidade. Alguns cuidados são especialmente importantes.

2.20.1 O que incluir

• Regras específicas e acionáveis, em vez de generalidades.
• Estrutura em seções, para facilitar manutenção.
• Exemplos concretos de comandos, formatos e nomes.
• Imports de documentação já existente, em vez de cópias.
• Comandos usados com frequência.

2.20.2 O que evitar

• Segredos, chaves de API, senhas, tokens ou credenciais.
• Dados sensíveis, PII ou informações proprietárias que não devam ficar em arquivos persistentes.
• Textos vagos como “seguir boas práticas”.
• Duplicar documentação já existente quando @path resolve melhor.
• Arquivos extensos demais sem foco.
• Excesso de subdiretórios e sobreposições desnecessárias.
• Importações encadeadas além do limite de 5 níveis.
• Memória desatualizada, que pode induzir Claude a sugerir práticas antigas.

2.20.3 Critérios para escolher o nível certo de memória

• Política corporativa: use Managed Policy.
• Padrão do time: use Project Memory.
• Preferência individual: use User Memory.
• Regra de módulo ou diretório: use Project Rules.
• Preferência local e privada no projeto: use CLAUDE.local.md.

2.21 Instalação e configuração prática

Na prática, você pode estruturar a memória em três camadas principais: projeto, pessoal e diretório específico. Cada uma tem um objetivo diferente e deve ser criada no lugar certo.

2.21.1 Configurar memória do projeto

1. Acesse a pasta do projeto.
2. Execute /init para criar um ponto de partida ou crie CLAUDE.md manualmente.
3. Adicione padrões de código, comandos, arquitetura e testes.
4. Versione o arquivo no Git para beneficiar o time.

cd /path/to/your/project
/init
git add CLAUDE.md
git commit -m "Initialize project memory with /init"

2.21.2 Configuração manual

1. Crie o arquivo CLAUDE.md na raiz do projeto.
2. Escreva as regras necessárias.
3. Commit no repositório.

cd /path/to/your/project
touch CLAUDE.md
cat > CLAUDE.md << 'EOF'
# Project Configuration

## Project Overview
- **Name**: Your Project Name
- **Tech Stack**: List your technologies
- **Team Size**: Number of developers

## Development Standards
- Your coding standards
- Naming conventions
- Testing requirements
EOF
git add CLAUDE.md
git commit -m "Add project memory configuration"

2.21.3 Configurar memória pessoal

1. Crie o diretório ~/.claude se ele ainda não existir.
2. Crie ~/.claude/CLAUDE.md.
3. Adicione preferências pessoais, como estilo de comunicação, ferramentas e abordagem de teste.

mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md

2.21.4 Configurar memória por diretório

Quando um subdiretório precisa de regras próprias, crie um CLAUDE.md naquele local. Isso permite sobrescrever ou complementar a memória raiz apenas para aquela área.

mkdir -p /path/to/directory/.claude
touch /path/to/directory/CLAUDE.md

2.22 Verificação e troubleshooting

Se o comportamento da memória não estiver como esperado, verifique primeiro se os arquivos existem nos locais corretos e se a hierarquia está coerente.

• Confirme se ./CLAUDE.md existe na raiz do projeto.
• Verifique se ~/.claude/CLAUDE.md está presente para preferências pessoais.
• Inspecione se claudeMdExcludes não está excluindo arquivos importantes por engano.
• Revise se imports com @path apontam para caminhos válidos e acessíveis.
• Cheque se o conteúdo não ultrapassou os limites práticos de profundidade ou tamanho.
• Se a auto memory não aparecer, confirme a versão mínima e a variável de ambiente de controle.

Em casos de contexto inesperado, o problema costuma ser um destes: arquivo no caminho errado, precedência maior sobrescrevendo a regra, exclusão por configuração, import inválido ou memória automática desativada.

2.23 Exemplo de fluxo de lifecycle de atualização

Quando você pede algo como “lembre que usamos async/await”, o Claude pode perguntar qual memória deve receber a regra, gravar no arquivo correto e recarregar o contexto atualizado. Esse ciclo é importante porque garante persistência real, em vez de depender apenas da conversa atual.

User: "Remember: use async/await"
Claude: "Which memory file?"
User: "Project memory"
Claude: writes to ./CLAUDE.md
Claude: reloads memory and confirms save

2.24 Detalhes técnicos importantes para retenção

• Arquivos de memória são carregados automaticamente na inicialização do Claude Code.
• O Claude sobe a árvore de diretórios a partir do diretório atual em busca de CLAUDE.md.
• Arquivos de subtree podem ser carregados contextualmente quando o Claude entra naqueles diretórios.
• Imports usam @path/to/file com suporte a caminho relativo e absoluto.
• A profundidade máxima de imports recursivos é 5.
• Arquivos de memória muito longos tendem a ser menos práticos; mantenha foco e organização.

3 Módulo — Skills e capacidades carregadas sob demanda

3.1 Guia de Skills do Agent

Skills de agente são capacidades reutilizáveis, baseadas em arquivos no sistema, que ampliam o que o Claude consegue fazer. Em vez de repetir instruções a cada conversa, você empacota conhecimento de domínio, fluxos de trabalho e boas práticas em componentes descobríveis que o Claude passa a usar automaticamente quando fazem sentido.

3.1.1 Visão geral

Skills são capacidades modulares que transformam um agente genérico em um especialista. Diferentemente de prompts, que valem só para uma conversa, uma Skill é carregada sob demanda e elimina a necessidade de reenviar a mesma orientação em tarefas parecidas, em sessões diferentes.

Os principais ganhos são:

• especializar o Claude para tarefas de domínio específico;
• reduzir repetição de instruções entre conversas;
• combinar várias Skills para formar fluxos mais complexos;
• reutilizar a mesma Skill em projetos e equipes diferentes;
• incorporar padrões de qualidade diretamente no processo.

As Skills seguem o padrão aberto Agent Skills, que funciona em múltiplas ferramentas de IA. O Claude Code amplia esse padrão com recursos adicionais, como controle de invocação, execução em subagente e injeção dinâmica de contexto.

Observação importante: comandos slash personalizados foram incorporados às Skills. Arquivos em .claude/commands/ ainda funcionam e continuam aceitando os mesmos campos de frontmatter. Para desenvolvimento novo, a recomendação é usar Skills. Quando existir uma colisão no mesmo caminho, por exemplo .claude/commands/review.md e .claude/skills/review/SKILL.md, a Skill tem prioridade.

3.1.2 Como o carregamento progressivo funciona

Skills usam uma arquitetura de divulgação progressiva: o Claude carrega as informações em etapas, conforme a necessidade, em vez de consumir tudo logo no início. Isso permite controlar o contexto com eficiência e, ao mesmo tempo, escalar sem limite prático de quantidade de Skills.

Há três níveis de carregamento:

• Nível 1: metadados — sempre carregado. Consome cerca de 100 tokens por Skill e inclui name e description do frontmatter YAML.
• Nível 2: instruções — carregado quando a Skill é acionada. Fica abaixo de 5 mil tokens e contém o corpo do SKILL.md com orientações e fluxos de trabalho.
• Nível 3 e acima: recursos — carregados conforme necessário. Inclui arquivos empacotados, como scripts, templates e documentação, que podem ser executados via bash sem trazer o conteúdo inteiro para o contexto.

Na prática, isso significa que você pode instalar muitas Skills sem custo relevante de contexto. Até a ativação, o Claude só sabe que a Skill existe e quando usá-la; ele só lê as instruções completas quando há correspondência com a tarefa.

3.1.3 Processo de carregamento de uma Skill

O fluxo típico acontece assim:

1. o usuário faz um pedido, por exemplo, revisar código por questões de segurança;
2. o Claude consulta as Skills disponíveis usando os metadados já carregados;
3. o sistema disponibiliza as descrições no startup;
4. o Claude compara a solicitação com a descrição da Skill;
5. se houver correspondência, lê o arquivo SKILL.md completo;
6. se precisar de apoio extra, abre templates, checklists ou scripts;
7. executa as instruções da Skill e devolve o resultado ao usuário.

Esse comportamento é importante porque separa descoberta, instrução e execução. Você ganha escala sem carregar todo o material no contexto o tempo inteiro.

3.1.4 Tipos de Skill e onde ficam

As Skills podem existir em vários escopos, e cada um tem uma finalidade diferente:

• Enterprise: administradas por configuração da organização, disponíveis para todos os usuários da empresa. São ideais para padrões corporativos.
• Personal: ficam em ~/.claude/skills/<nome-da-skill>/SKILL.md, valem só para o usuário local e não são compartilhadas.
• Project: ficam em .claude/skills/<nome-da-skill>/SKILL.md, valem para a equipe e podem ser versionadas no git.
• Plugin: vêm de <plugin>/skills/<nome-da-skill>/SKILL.md e aparecem onde o plugin estiver habilitado.

Quando duas Skills têm o mesmo nome em níveis diferentes, a prioridade padrão é: enterprise > personal > project. Skills de plugin usam o namespace plugin-name:skill-name, então não entram em conflito com nomes locais.

Importante para versões recentes: a descoberta de Skills por subagentes mudou na versão v2.1.133+. A partir daí, subagentes passaram a enxergar Skills de projeto, usuário e plugin por meio da Skill tool do mesmo jeito que a sessão principal. Em versões anteriores, eles só viam o conjunto embutido em si mesmos, o que fazia fluxos com Skill + subagente degradarem silenciosamente.

3.1.5 Descoberta automática em diretórios aninhados e reexecução

Quando você trabalha em subdiretórios, o Claude Code também procura Skills em pastas aninhadas .claude/skills/. Por exemplo, se você estiver editando arquivos em packages/frontend/, ele também verifica packages/frontend/.claude/skills/. Isso é muito útil em monorepos, onde cada pacote pode ter capacidades próprias.

A partir da versão v2.1.178, quando o mesmo nome de Skill existe em diretórios aninhados, vence a Skill mais próxima do diretório de trabalho atual. Ou seja, uma Skill do nível do pacote sobrescreve a mesma Skill definida na raiz do repositório.

Diretórios adicionados com --add-dir também entram na descoberta automática, com detecção de alteração em tempo real. Se você editar uma Skill nesses diretórios, a mudança passa a valer imediatamente, sem reiniciar o Claude Code.

Se a Skill não aparecer após uma alteração, existe o comando /reload-skills, introduzido na v2.1.152, que revarre todos os diretórios de Skill sem reiniciar a sessão. Um hook de SessionStart pode disparar o mesmo comportamento retornando reloadSkills: true.

Há ainda um limite prático para descrições: os metadados do Nível 1 são limitados a 1% da janela de contexto, com fallback de 8.000 caracteres. Se houver muitas Skills instaladas, algumas descrições podem ser cortadas. Os nomes continuam todos incluídos; apenas as descrições podem ser reduzidas para caber. A variável de ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET permite sobrescrever esse orçamento.

3.1.6 Criando Skills personalizadas

Uma Skill nova costuma seguir uma estrutura de diretórios simples e previsível:

my-skill/
├── SKILL.md
├── template.md
├── examples/
│   └── sample.md
└── scripts/
    └── validate.sh

O arquivo principal é SKILL.md. Os arquivos complementares servem para separar material de apoio, como templates, exemplos, scripts e documentação de referência. Isso mantém o corpo principal da Skill enxuto e mais fácil de manter.

O formato básico do SKILL.md usa frontmatter YAML seguido do conteúdo da Skill:

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this Skill.

3.1.7 Campos obrigatórios do frontmatter

• name: usa apenas letras minúsculas, números e hífens. O limite é 64 caracteres. Não pode conter anthropic nem claude.
• description: deve explicar o que a Skill faz e quando usá-la. O limite é 1024 caracteres. Esse campo é crítico porque orienta a ativação automática.

3.1.8 Campos opcionais do frontmatter

Além dos campos obrigatórios, a Skill pode aceitar várias opções para controlar comportamento, acesso e execução:

---
name: my-skill
description: What this skill does and when to use it
argument-hint: "[filename] [format]"
disable-model-invocation: true
user-invocable: false
allowed-tools: Read, Grep, Glob
disallowed-tools: Write, Edit
model: opus
effort: high
context: fork
agent: Explore
shell: bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
paths: "src/api/**/*.ts"
---

• argument-hint: dica mostrada no autocomplete de /, útil para orientar a entrada esperada.
• disable-model-invocation: quando true, só o usuário pode invocar via /nome; o Claude nunca ativa automaticamente.
• user-invocable: quando false, a Skill fica oculta do menu de slash commands e só o Claude pode chamá-la de forma automática.
• allowed-tools: lista separada por vírgulas dos tools que a Skill pode usar sem pedir confirmação.
• disallowed-tools: remove ferramentas específicas enquanto a Skill está ativa. Esse campo foi adicionado na v2.1.152 e complementa allowed-tools.
• model: substitui o modelo durante a execução da Skill, por exemplo opus ou sonnet.
• effort: define o nível de esforço, com valores low, medium, high, xhigh e max. Os níveis disponíveis dependem do modelo. O padrão é high no Opus 4.8 e xhigh no Opus 4.7.
• context: usa fork para executar a Skill em um subagente isolado, com janela de contexto própria.
• agent: define o tipo de subagente quando context: fork estiver ativo, por exemplo Explore, Plan ou general-purpose.
• shell: escolhe o shell usado nas substituições de !`command` e nos scripts. Os valores aceitos são bash (padrão) ou powershell.
• hooks: permite hooks escopados ao ciclo de vida da própria Skill, no mesmo formato dos hooks globais.
• paths: padrões glob que limitam quando a Skill pode ser ativada automaticamente. Pode ser uma string separada por vírgulas ou uma lista YAML.

3.1.9 Tipos de conteúdo dentro de uma Skill

Existem dois tipos principais de conteúdo, e eles servem a finalidades diferentes.

Conteúdo de referência adiciona conhecimento que o Claude aplica ao trabalho atual, como convenções, padrões, guias de estilo e conhecimento de domínio. Ele roda inline com o contexto da conversa.

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

Conteúdo de tarefa descreve instruções passo a passo para uma ação específica e costuma ser invocado diretamente com /skill-name.

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

3.1.10 Controle de invocação

Por padrão, você e o Claude podem invocar qualquer Skill. Dois campos de frontmatter controlam os três modos de invocação:

• padrão: você pode invocar e o Claude também;
• disable-model-invocation: true: você pode invocar, o Claude não;
• user-invocable: false: você não pode invocar pelo menu, o Claude pode.

Esse controle é especialmente importante em tarefas com efeito colateral. Por exemplo, /commit, /deploy e /send-slack-message normalmente devem usar disable-model-invocation: true, para evitar que o modelo decida executar algo destrutivo só porque o código “parece pronto”.

Já user-invocable: false é útil para conhecimento de fundo que ajuda o Claude, mas não faz sentido como comando do usuário. Um exemplo é uma Skill que descreve o contexto de um sistema legado.

3.1.11 Substituições de string e contexto dinâmico

Skills suportam valores dinâmicos que são resolvidos antes de o conteúdo chegar ao Claude:

• $ARGUMENTS: todos os argumentos passados na invocação;
• $ARGUMENTS[N] ou $N: acessa um argumento específico por índice, começando em zero;
• ${CLAUDE_SESSION_ID}: ID da sessão atual;
• ${CLAUDE_SKILL_DIR}: diretório que contém o SKILL.md da Skill;
• ${CLAUDE_PROJECT_DIR}: caminho absoluto da raiz do projeto. Pode ser usado no corpo da Skill e também em allowed-tools, a partir da v2.1.196;
• ${CLAUDE_EFFORT}: nível de esforço atual, com valores low, medium, high, xhigh ou max. Útil para ramificar o comportamento da Skill, por exemplo [ "${CLAUDE_EFFORT}" = "max" ] && deep_analysis. Esse uso está disponível na v2.1.120+;
• !`command`: executa um comando de shell e injeta a saída dinamicamente no texto.

Exemplo de uso com argumentos:

---
name: fix-issue
description: Fix a GitHub issue
---

Fix GitHub issue $ARGUMENTS following our coding standards.
1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit

Ao executar /fix-issue 123, o $ARGUMENTS é substituído por 123.

Também é possível empilhar slash-skills em uma única invocação, como /code-review /fix-issue 123. A partir da v2.1.199, isso carrega todas as Skills líderes — a primeira mais até cinco adicionais — e repassa os argumentos finais (123) para cada uma. Antes disso, apenas a primeira Skill era carregada. Se a mesma Skill aparecer mais de uma vez, o conteúdo idêntico é deduplicado desde a v2.1.202, em vez de ser anexado duas vezes.

3.1.12 Injetando contexto dinâmico com comandos de shell

A sintaxe !`command` executa comandos do shell antes de o conteúdo da Skill ser enviado ao Claude. Isso permite capturar dados vivos do ambiente, do repositório ou de ferramentas externas.

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

Os comandos executam imediatamente e apenas a saída final chega ao Claude. Por padrão, eles rodam em bash; defina shell: powershell no frontmatter se quiser usar PowerShell.

3.1.13 Executando Skills em subagentes

Adicionar context: fork faz a Skill rodar em um subagente isolado, com sua própria janela de contexto. Nesse modo, o conteúdo da Skill vira a tarefa de um subagente dedicado, o que ajuda a manter a conversa principal limpa.

Existe uma correção importante na v2.1.145: uma Skill com context: fork podia, em casos raros, entrar em loop infinito de reinvocação. Se você cria ou depende de Skills que fazem fork, atualize para v2.1.145+.

O campo agent define o tipo de subagente a usar:

• Explore: ideal para pesquisa somente leitura e análise de código;
• Plan: ideal para criar planos de implementação;
• general-purpose: adequado para tarefas amplas que exigem acesso a todas as ferramentas;
• agentes customizados: tipos especializados definidos na sua configuração.

Exemplo simples de frontmatter com fork:

---
context: fork
agent: Explore
---

E um exemplo completo:

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

3.1.14 Exemplos práticos de Skills

Um uso comum é criar uma Skill de revisão de código com diretório próprio, templates e scripts auxiliares:

~/.claude/skills/code-review-specialist/
├── SKILL.md
├── templates/
│   ├── review-checklist.md
│   └── finding-template.md
└── scripts/
    ├── analyze-metrics.py
    └── compare-complexity.py

O SKILL.md dessa Skill pode conter instruções de segurança, performance, qualidade e manutenibilidade. Um bom desenho inclui análise de autenticação/autorização, risco de exposição de dados, vulnerabilidades de injeção, fraquezas criptográficas, eficiência algorítmica, otimização de memória, consultas de banco, oportunidades de cache, princípios SOLID, padrões de design, nomenclatura, cobertura de testes, legibilidade, tamanho de função, complexidade ciclomática e segurança de tipos.

Para relatórios, vale exigir uma estrutura consistente, como resumo com nota geral, número de achados e áreas prioritárias, seguido de problemas críticos com descrição, local, impacto, severidade e sugestão de correção.

Outro exemplo é uma Skill de visualização de base de código que gera um HTML interativo com árvore expansível. Nesse caso, a Skill pode usar apenas um script Python como motor principal e delegar a lógica pesada ao script, enquanto o Claude cuida da orquestração.

~/.claude/skills/codebase-visualizer/
├── SKILL.md
└── scripts/
    └── visualize.py

python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .

Esse fluxo normalmente gera um arquivo codebase-map.html e o abre no navegador padrão. A visualização pode incluir diretórios recolhíveis, tamanho dos arquivos, cores por tipo de arquivo e totais agregados por pasta.

Há também o caso de uma Skill de deploy, que deve ser invocada apenas pelo usuário porque tem efeitos colaterais. Nela, é comum bloquear a invocação automática do modelo e permitir somente um conjunto estreito de ferramentas, como Git e NPM.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *)
---

Deploy $ARGUMENTS to production:

1. Run the test suite: `npm test`
2. Build the application: `npm run build`
3. Push to the deployment target
4. Verify the deployment succeeded
5. Report deployment status

Outro padrão útil é a Skill de voz de marca, que não precisa ser invocável pelo usuário e serve como conhecimento de fundo para padronizar comunicações de marketing, mensagens a clientes e conteúdo público.

---
name: brand-voice
description: Ensure all communication matches brand voice and tone guidelines. Use when creating marketing copy, customer communications, or public-facing content.
user-invocable: false
---

## Tone of Voice
- **Friendly but professional** - approachable without being casual
- **Clear and concise** - avoid jargon
- **Confident** - we know what we're doing
- **Empathetic** - understand user needs

## Writing Guidelines
- Use "you" when addressing readers
- Use active voice
- Keep sentences under 20 words
- Start with value proposition

For templates, see [templates/](templates/).

Também é comum criar uma Skill para gerar ou atualizar CLAUDE.md. Esse tipo de Skill é útil porque LLMs não têm estado permanente: o CLAUDE.md é o arquivo que entra automaticamente em toda conversa. Boas práticas incluem manter o documento curto, com menos de 300 linhas — idealmente abaixo de 100 —, incluir apenas informação válida para todas as sessões, não usar o Claude como linter e nunca gerar esse arquivo de forma automática sem revisão cuidadosa.

As seções essenciais costumam ser nome do projeto, stack técnica, comandos de desenvolvimento, convenções críticas e problemas conhecidos. Isso ajuda no onboarding da IA sem transformar o arquivo num manual gigante.

Outro padrão é a Skill de refatoração sistemática, inspirada em Martin Fowler. Ela pode usar fases como pesquisa e análise, avaliação de cobertura de testes, identificação de code smells, criação do plano, implementação incremental e revisão com iteração. O princípio central é preservar comportamento, trabalhar em passos pequenos, apoiar-se em testes e tratar refatoração como atividade contínua.

3.1.15 Arquivos de apoio e organização

Uma Skill pode conter múltiplos arquivos além do SKILL.md. Eles ajudam a manter a Skill enxuta e a carregar apenas o que for necessário quando for necessário.

my-skill/
├── SKILL.md              # Main instructions (required, keep under 500 lines)
├── templates/
│   └── output-format.md
├── examples/
│   └── sample-output.md
├── references/
│   └── api-spec.md
└── scripts/
    └── validate.sh

Boas práticas para arquivos de apoio:

• mantenha o SKILL.md abaixo de 500 linhas;
• mova referências longas, exemplos grandes e especificações para arquivos separados;
• linke esses arquivos a partir do SKILL.md usando caminhos relativos, por exemplo [API reference](references/api-spec.md);
• lembre que esses arquivos só são carregados no Nível 3, então não consomem contexto até serem lidos.

3.1.16 Como ver, testar, atualizar e compartilhar Skills

Para listar as Skills disponíveis, você pode perguntar diretamente ao Claude: What Skills are available?. Outra forma é inspecionar o sistema de arquivos.

# List personal Skills
ls ~/.claude/skills/

# List project Skills
ls .claude/skills/

Em versões v2.1.121+, o menu interativo /skills aceita filtro por digitação, o que ajuda muito quando há muitas Skills instaladas.

Para testar uma Skill, existem dois caminhos: deixar o Claude invocá-la automaticamente com uma frase compatível com a descrição, ou chamá-la diretamente pelo nome.

/code-review-specialist src/auth/login.ts

Se você criar uma Skill local chamada code-review-specialist, ela não conflita com o comando embutido /code-review. Esse comando embutido é o antigo /simplify, que foi renomeado no Claude Code v2.1.146. Se você copiar sua Skill para ~/.claude/skills/code-review/, ela vai sombrear o comando nativo; por isso, manter o sufixo -specialist evita conflito.

Para atualizar uma Skill, edite o arquivo SKILL.md diretamente. Alterações passam a valer na próxima inicialização do Claude Code.

# Personal Skill
code ~/.claude/skills/my-skill/SKILL.md

# Project Skill
code .claude/skills/my-skill/SKILL.md

Há três formas de controlar quais Skills o Claude pode invocar:

• desabilitar todas no menu de permissões adicionando a regra Skill na seção de deny;
• permitir ou negar Skills específicas com regras como Skill(commit), Skill(review-pr *) ou Skill(deploy *);
• ocultar uma Skill individual usando disable-model-invocation: true no frontmatter.

Quando uma Skill de projeto e uma Skill de usuário têm o mesmo nome, o padrão é o projeto vencer. O ajuste skillOverrides, disponível na v2.1.129+, permite afinar isso em ~/.claude/settings.json ou em .claude/settings.json do projeto.

{
  "skillOverrides": "name-only"
}

Os valores aceitos são:

• on (padrão): uma Skill de repositório pode sobrescrever uma Skill de usuário com o mesmo nome;
• off: desativa a sobrescrita; Skills de usuário sempre vencem;
• name-only: a regra de override considera apenas o nome da Skill, ignorando descrição e origem;
• user-invocable-only: só Skills invocáveis pelo usuário podem ser sobrescritas; Skills invocadas pelo modelo sempre vêm da localização original.

Esse ajuste é útil quando a política da equipe exige que Skills pessoais tenham prioridade total ou, ao contrário, quando você quer permitir apenas sobrescritas estreitamente baseadas em nome.

3.1.17 Boas práticas de design

Descrições precisam ser específicas. Uma descrição vaga como “ajuda com documentos” é ruim; uma descrição boa aponta exatamente o que a Skill faz, como extrair texto e tabelas de PDFs, preencher formulários ou mesclar documentos, e em que cenário ela deve ser usada.

Também vale manter a Skill focada. Uma Skill deve representar uma única capacidade. “Preenchimento de formulários PDF” é um bom exemplo; “processamento de documentos” tende a ser amplo demais.

Inclua termos de acionamento que reflitam a linguagem do usuário. Se a pessoa disser “planilha”, “Excel” ou “.xlsx”, esses termos devem aparecer na descrição da Skill para aumentar a chance de ativação correta.

Não esqueça de conservar o SKILL.md curto, mover o restante para arquivos de apoio e apontar para eles com links relativos.

Recomendações práticas:

• use nomes claros e descritivos;
• inclua instruções completas e concretas;
• adicione exemplos reais;
• empacote scripts e templates relacionados;
• teste em cenários reais;
• documente dependências.

Evite estes erros:

• criar Skills para tarefas únicas;
• duplicar funcionalidade existente;
• deixar a Skill ampla demais;
• pular o campo de descrição;
• instalar Skills de fontes não confiáveis sem auditoria.

3.1.18 Troubleshooting

Se a Skill não estiver sendo usada, comece pela descrição. Muitas vezes ela está genérica demais e não contém os termos que o usuário realmente escreveria.

Problemas comuns e correções:

• Claude não usa a Skill: torne a descrição mais específica e inclua termos de acionamento.
• Arquivo da Skill não encontrado: verifique o caminho exato, por exemplo ~/.claude/skills/name/SKILL.md.
• Erros de YAML: confira os marcadores ---, a indentação e a ausência de tabulações.
• Conflito entre Skills: use termos distintos nas descrições.
• Scripts não executam: confira permissões com chmod +x scripts/*.py.
• Claude não vê todas as Skills: talvez haja muitas Skills instaladas; verifique /context em busca de avisos.

Se a Skill não dispara quando esperado, revise se a descrição contém palavras que o usuário naturalmente usaria, confirme que ela aparece quando você pergunta quais Skills estão disponíveis, tente reformular o pedido para bater com a descrição e, para teste, invoque diretamente com /skill-name.

Se a Skill dispara demais, deixe a descrição mais específica ou marque a Skill com disable-model-invocation: true para torná-la manual.

Se o Claude não enxergar todas as Skills, lembre que as descrições são carregadas no limite de 1% da janela de contexto, com fallback de 8.000 caracteres, e que cada entrada tem teto de 250 caracteres independentemente do orçamento total. Use /context para verificar se alguma Skill foi excluída e, se necessário, ajuste o orçamento com SLASH_COMMAND_TOOL_CHAR_BUDGET.

3.1.19 Segurança

Use apenas Skills de fontes confiáveis. Uma Skill pode dar instruções e até código para o Claude executar, então uma Skill maliciosa pode induzir uso indevido de ferramentas ou execução de comandos perigosos.

Pontos de atenção:

• audite todos os arquivos da pasta da Skill;
• desconfie de Skills que buscam conteúdo de URLs externas, porque elas podem ser comprometidas;
• trate habilidades como software instalado, com o mesmo nível de revisão;
• lembre que uma Skill mal-intencionada pode manipular a sequência de ferramentas usadas pelo Claude.

Em ambientes sensíveis, é possível desativar a substituição por shell da sintaxe !`command` com o ajuste disableSkillShellExecution, adicionado na v2.1.91.

{
  "disableSkillShellExecution": true
}

Quando essa flag está ativa, qualquer marcador !`command` permanece como texto literal, em vez de ser executado. Isso reduz a superfície de ataque sem desligar as Skills. É uma boa prática combinar isso com uma allowlist de ferramentas em allowedTools para defesa em profundidade.

Outro ajuste de segurança é disableBundledSkills, adicionado na v2.1.169. Ele esconde do modelo as Skills, workflows e comandos que acompanham o Claude Code por padrão, o que pode ser útil quando esses recursos nativos só acrescentam ruído ao projeto ou quando você quer reduzir a superfície de habilidades expostas ao modelo.

{
  "disableBundledSkills": true
}

Também existe a forma equivalente por variável de ambiente:

export CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1

3.1.20 Skills versus outros recursos

As Skills não substituem todo o resto. Cada recurso tem um papel próprio:

• Skills: servem para conhecimento reutilizável e fluxos de trabalho, com invocação automática ou por /nome;
• Slash commands: continuam sendo atalhos iniciados pelo usuário, mas agora foram incorporados às Skills;
• Subagentes: lidam com execução delegada e isolada;
• Memory (CLAUDE.md): mantém contexto persistente do projeto e é sempre carregado;
• MCP: fornece acesso em tempo real a dados e serviços externos;
• Hooks: automatizam efeitos colaterais e eventos.

3.1.21 Skills embarcadas no Claude Code

O Claude Code já traz Skills embutidas, disponíveis sem instalação. Elas seguem o mesmo formato de SKILL.md usado nas Skills personalizadas. Os nomes abaixo representam atalhos e habilidades prontas para uso:

• /batch <instruction>: orquestra mudanças paralelas em larga escala usando git worktrees;
• /claude-api: carrega referência da API/SDK Claude e ativa automaticamente quando detecta imports de anthropic ou @anthropic-ai/sdk;
• /dataviz: orienta design de gráficos e dashboards, com um validador executável de paleta de cores na v2.1.198;
• /debug [description]: ajuda a diagnosticar a sessão atual lendo o log de debug;
• /fewer-permission-prompts: analisa transcrições e sugere uma allowlist priorizada para ferramentas comuns de leitura;
• /loop [interval] <prompt>: executa um prompt repetidamente em intervalos definidos, como /loop 5m check the deploy;
• /run (v2.1.145+): inicia a aplicação do projeto para observar uma mudança em execução; primeiro procura uma Skill do projeto e, se não encontrar, cai para padrões embutidos por tipo de projeto;
• /run-skill-generator (v2.1.145+): ensina /run e /verify a lidar com um projeto específico por meio da geração de uma Skill por projeto;
• /code-review [effort]: revisa o diff atual em busca de bugs de correção com o nível de esforço escolhido; aceitar --comment para postar achados como comentários inline em PR. É diferente de /simplify, que foi separado novamente em v2.1.154 para focar limpeza, reutilização e simplificação;
• /simplify: faz revisão focada em limpeza, simplificação, eficiência e altitude, e aplica as correções;
• /verify (v2.1.145+): compila, executa e observa a aplicação para confirmar que a correção realmente funciona, e não apenas que os testes passam.

3.1.22 Compartilhando Skills

Skills de projeto podem ser compartilhadas com a equipe via git. Basta criar a Skill em .claude/skills/, commitá-la e deixar os demais membros fazerem pull. Assim, ela passa a estar disponível imediatamente para todos que usam o repositório.

Skills pessoais podem ser copiadas para o diretório local com um comando simples:

cp -r my-skill ~/.claude/skills/
chmod +x ~/.claude/skills/my-skill/scripts/*.py

Para distribuição mais ampla, também é possível empacotar Skills dentro da pasta skills/ de um plugin.

3.1.23 Ecossistema, coleções e gerenciadores

Quando você começa a criar Skills com frequência, dois elementos passam a fazer muita diferença: uma biblioteca de Skills prontas e uma ferramenta para gerenciá-las.

Uma coleção útil é luongnv89/skills, que reúne Skills usadas no dia a dia em vários projetos. Entre os destaques estão logo-designer, para gerar logos automaticamente, e ollama-optimizer, para ajustar desempenho de modelos locais ao seu hardware.

Outra ferramenta útil é luongnv89/asm, o Agent Skill Manager. Ele ajuda no desenvolvimento de Skills, na detecção de duplicações e nos testes. O comando asm link permite testar uma Skill em qualquer projeto sem copiar arquivos, o que se torna essencial quando você passa de algumas poucas Skills para uma biblioteca grande.

3.1.24 Recursos adicionais e contexto de versão

As Skills descritas aqui refletem o estado do Claude Code na versão 2.1.206, com compatibilidade indicada para Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8 e Claude Haiku 4.5. Algumas opções são estáveis, enquanto outras dependem de versões específicas, como /reload-skills na v2.1.152, disallowed-tools também na v2.1.152, skillOverrides na v2.1.129+, disableSkillShellExecution na v2.1.91, disableBundledSkills na v2.1.169, descoberta em subagentes na v2.1.133+, além do comportamento de empilhamento e deduplicação em v2.1.199 e v2.1.202.

Para uso prático, vale distinguir três cenários:

• estável: estrutura de Skill, name, description, carregamento progressivo, campos básicos de controle e arquivos de apoio;
• dependente de versão: overrides, reloading, subagentes com descoberta completa, disallowed-tools e limites específicos de orçamento;
• sensível a política: execução de comandos via !`command`, Skills embarcadas e permissões de tool access.

Em ambientes novos, vale começar com descrições específicas, escopo bem definido, arquivos auxiliares organizados e uma política clara sobre quem pode acionar cada Skill e em que condições.

3.2 brand-voice-consistency

Esta habilidade garante que textos públicos, mensagens para clientes e peças de marketing mantenham uma voz consistente com a identidade da marca. Use quando o pedido envolver copy publicitária, comunicação com usuários, conteúdo externo ou quando houver menção explícita a tom, estilo ou “brand voice”.

3.2.1 Identidade da marca

A missão central é ajudar equipes a automatizar fluxos de desenvolvimento com IA. Isso influencia o posicionamento, a escolha de palavras e o tipo de benefício destacado.

• Simplicidade: tornar o complexo fácil de entender.
• Confiabilidade: transmitir execução estável e segura.
• Empoderamento: apoiar a criatividade humana em vez de substituí-la.

3.2.2 Tom de voz esperado

• Amigável, mas profissional: acessível sem parecer informal demais.
• Claro e conciso: evitar jargões e explicar conceitos técnicos com simplicidade.
• Confiante: comunicar domínio do assunto sem exagero.
• Empático: reconhecer dores e necessidades do usuário.

3.2.3 Diretrizes de escrita

Essas regras ajudam a manter a consistência em e-mails, posts e conteúdos institucionais. Elas são especialmente importantes em peças de comunicação externa, onde o leitor precisa entender valor e próximo passo rapidamente.

Boas práticas recomendadas:

• Use “você” ao falar com o leitor.
• Prefira voz ativa: “Claude gera relatórios” em vez de “Relatórios são gerados por Claude”.
• Comece pela proposta de valor.
• Inclua exemplos concretos sempre que possível.
• Mantenha frases com menos de 20 palavras, quando viável.
• Use listas para dar clareza visual.
• Finalize com chamada para ação objetiva.

O que evitar:

• Jargões corporativos ou frases vazias.
• Tom paternalista ou simplificação excessiva.
• Expressões como “nós acreditamos” ou “nós pensamos”, que enfraquecem a confiança.
• CAIXA ALTA, exceto para ênfase pontual.
• Blocos longos de texto sem respiro visual.
• Pressupor conhecimento técnico sem necessidade.

3.2.4 Vocabulário preferido e termos a evitar

O vocabulário também comunica posicionamento. Esta habilidade orienta escolhas mais precisas e menos “marketing genérico”.

• Preferir “Claude” em vez de “a IA Claude”.
• Preferir “geração de código” em vez de “auto-coding”.
• Preferir “agente” em vez de “bot”.
• Preferir “simplificar” em vez de “revolucionar”.
• Preferir “integrar” em vez de “sinergizar”.

• Avoid / evitar “cutting-edge”, porque é expressão gasta.
• Avoid / evitar “game-changer”, porque é vaga.
• Avoid / evitar “leverage” em tom corporativo.
• Avoid / evitar “utilize”; use “use”.
• Avoid / evitar “paradigm shift”, porque não explica benefício real.

3.2.5 Exemplos de tom por contexto

Os exemplos abaixo mostram como a mesma identidade se adapta a situações diferentes sem perder coerência.

• Anúncio empolgante: “Economize 8 horas por semana em revisões de código. Claude revisa seus PRs automaticamente.”
• Suporte empático: “Sabemos que fazer deploy pode ser estressante. Claude cuida dos testes para você não se preocupar.”
• Funcionalidade com tom confiante: “Claude não apenas sugere código. Ele entende sua arquitetura e mantém a consistência.”
• Conteúdo educativo: “Vamos explorar como agentes melhoram fluxos de code review. Veja o que aprendemos...”

3.2.6 Template de e-mail

Este modelo serve para mensagens com proposta de valor clara e leitura rápida. Ele funciona bem quando o objetivo é apresentar benefício, explicar funcionamento e pedir uma ação específica.

Subject: [Assunto claro e orientado a benefício]

Oi [Nome],

[Abertura: qual valor isso traz para a pessoa]

[Corpo: como funciona / o que ela vai receber]

[Exemplo específico ou benefício]

[Chamada para ação: próximo passo objetivo]

Abraços,
[Nome]

3.2.7 Template de post para redes sociais

Esse formato privilegia impacto imediato. O gancho precisa aparecer na primeira linha, e o conteúdo deve ser curto, escaneável e com um convite claro para interação.

[Gancho: chame atenção na primeira linha]
[2 ou 3 linhas: valor ou fato interessante]
[Chamada para ação: link, pergunta ou convite para engajar]
[Emoji: no máximo 1 ou 2 para dar interesse visual]

3.3 claude-md

Esta habilidade orienta a criação e atualização de arquivos CLAUDE.md, que funcionam como onboarding permanente para agentes em um repositório. Como LLMs são estateless, esse arquivo é o ponto que entra automaticamente em toda conversa e precisa carregar apenas contexto realmente universal.

3.3.1 Quando usar

• create: gerar um novo CLAUDE.md do zero.
• update: melhorar um arquivo existente.
• audit: analisar a qualidade do arquivo atual sem alterá-lo.
• Também pode receber um caminho específico, como src/api/CLAUDE.md, para instruções por diretório.

3.3.2 Princípios centrais

• Menos é mais: modelos de ponta conseguem seguir algo em torno de 150 a 200 instruções; o sistema do Claude Code já consome parte disso. O arquivo precisa ser enxuto.
• Aplicabilidade universal: inclua apenas o que vale para todas as sessões, não para tarefas isoladas.
• Não usar o Claude como linter: regras de estilo e formatação ocupam contexto e degradam a utilidade. Essas responsabilidades devem ficar em ferramentas determinísticas, como linters e formatadores.
• Nunca auto-gerar sem revisão: por ser um ponto de alto impacto, o conteúdo deve ser escrito manualmente com cuidado.

3.3.3 Fluxo de execução para criação ou atualização

1. Analise o projeto atual.
2. Planeje o conteúdo com base em WHAT, WHY e HOW.
3. Se o projeto for grande, use disclosure progressiva com arquivos auxiliares.
4. Valide o conteúdo contra os critérios de qualidade.
5. Para create e update, apresente o rascunho para revisão antes de aplicar mudanças.

3.3.4 Análise do projeto

Antes de escrever, é preciso entender o contexto do repositório. Essa etapa evita instruções erradas ou redundantes.

• Verifique se já existe CLAUDE.md na raiz, em .claude/CLAUDE.md, em subdiretórios ou em ~/.claude/CLAUDE.md.
• Identifique a stack tecnológica: linguagens, frameworks, gerenciador de pacotes, build system e runner de testes.
• Leia documentação existente, como README.md, CONTRIBUTING.md e arquivos de configuração de build ou dependências.

3.3.5 Estrutura de conteúdo: WHAT, WHY e HOW

Um bom CLAUDE.md organiza informação em três camadas.

• WHAT: visão da stack, estrutura do projeto e principais diretórios.
• WHY: finalidade do projeto e decisões arquiteturais importantes.
• HOW: fluxo de trabalho, comandos de testes, build, verificação e armadilhas práticas.

3.3.6 Disclosure progressiva para projetos grandes

Quando o repositório for complexo, a recomendação é criar uma pasta agent_docs/ com documentos especializados. O CLAUDE.md principal deve apenas apontar para eles.

agent_docs/
  |- building_the_project.md
  |- running_tests.md
  |- code_conventions.md
  |- architecture_decisions.md

Nesse caso, o arquivo principal pode orientar o agente com referências do tipo:

Para instruções detalhadas de build, consulte `agent_docs/building_the_project.md`

Use referências no formato file:line sempre que possível. Isso reduz a chance de contexto desatualizado em comparação com snippets longos.

3.3.7 Restrições de qualidade

• O alvo ideal é ficar abaixo de 300 linhas; preferencialmente, abaixo de 100.
• Não inclua regras de estilo ou formatação.
• Não coloque instruções específicas de uma tarefa isolada.
• Evite snippets de código; prefira referências de arquivos.
• Não repita o que já está em README.md ou em metadados óbvios do projeto.

3.3.8 Seções essenciais

Um arquivo bem estruturado costuma conter, no mínimo, estas partes:

# Nome do projeto

Breve descrição em uma linha.

## Tech Stack
- Linguagem principal e versão
- Frameworks/bibliotecas principais
- Banco de dados/armazenamento, se houver

## Project Structure
- `apps/` - pontos de entrada de aplicações
- `packages/` - bibliotecas compartilhadas

## Development Commands
- Install: `command`
- Test: `command`
- Build: `command`

## Critical Conventions
- Convenção 1 com explicação curta
- Convenção 2 com explicação curta

## Known Issues / Gotchas
- Problema 1
- Problema 2

3.3.9 O que evitar

• Regras de estilo de código.
• Documentação de como usar o Claude.
• Explicações longas de padrões óbvios.
• Exemplos de código copiados e colados.
• Boas práticas genéricas sem contexto.
• Instruções para tarefas específicas.
• Conteúdo auto-gerado sem curadoria.
• Listas extensas de TODO.

3.3.10 Checklist de validação

• Menos de 300 linhas, idealmente menos de 100.
• Todas as linhas precisam valer para todas as sessões.
• Sem regras de estilo ou formatação.
• Sem snippets de código; usar referências a arquivos.
• Comandos testados e confirmados.
• Disclosure progressiva usada em projetos complexos.
• Gotchas importantes documentados.
• Sem redundância com README.

3.3.11 Formato de saída esperado

Para create ou fluxo padrão, o trabalho deve seguir esta ordem: analisar o projeto, redigir o arquivo, apresentar o rascunho para revisão e só então escrever no local apropriado após aprovação.

Para update, a sequência é: ler o arquivo atual, auditar contra as práticas recomendadas, listar o que remover, condensar e adicionar, apresentar as mudanças e aplicar após aprovação.

Para audit, o resultado deve ser apenas um relatório com contagem de linhas, percentual de conteúdo universal, anti-padrões encontrados e recomendações. Não altere o arquivo.

3.3.12 AGENTS.md

Se o usuário pedir criação ou atualização de AGENTS.md, o documento deve definir comportamentos especializados de agentes, papéis, restrições e fluxos multiagente. As mesmas ideias de foco, concisão e progressive disclosure se aplicam, mas o objetivo é diferente do CLAUDE.md: aqui o foco é comportamento e coordenação de agentes, não contexto de projeto.

3.3.13 Observações práticas

• Verifique sempre se os comandos funcionam antes de incluí-los.
• Se houver dúvida, omita a informação.
• Quanto mais ruído, maior a chance de o arquivo ser ignorado pelo modelo.
• Em monorepos, a estrutura WHAT/WHY/HOW costuma trazer mais valor.
• Arquivos CLAUDE.md por diretório devem ser ainda mais focados.

3.4 code-review-specialist

Esta habilidade fornece revisão de código com foco combinado em segurança, desempenho, qualidade e manutenibilidade. Ela é apropriada quando o usuário pede análise de PR, revisão de código, avaliação de vulnerabilidades ou sugestões de otimização.

3.4.1 Áreas cobertas

• Segurança: autenticação, autorização, exposição de dados, injeção, criptografia fraca e registro indevido de dados sensíveis.
• Desempenho: eficiência algorítmica, uso de memória, consultas ao banco, cache e concorrência.
• Qualidade: princípios SOLID, padrões de projeto, nomes, documentação e cobertura de testes.
• Manutenibilidade: legibilidade, tamanho de função, complexidade ciclomática, dependências e segurança de tipos.

3.4.2 Arquivos de apoio que devem ser lidos

Este skill inclui recursos complementares que ajudam a manter a revisão consistente.

• templates/review-checklist.md: checklist estruturado para não esquecer categorias importantes.
• templates/finding-template.md: modelo para registrar cada achado com severidade, localização, exemplos e impacto.
• scripts/analyze-metrics.py: script em Python para calcular métricas básicas do código analisado.
• scripts/compare-complexity.py: script para comparar complexidade antes e depois, útil em mudanças de refatoração.

3.4.3 Uso prático dos scripts

O script analyze-metrics.py analisa um arquivo e retorna métricas simples, como quantidade de funções, classes, tamanho médio de linha e uma estimativa de complexidade. Ele aceita o caminho do arquivo como argumento único.

python scripts/analyze-metrics.py caminho/do/arquivo.py

Esse script usa expressões regulares e é útil para uma leitura quantitativa rápida. Como é uma estimativa simples, ele não substitui análise semântica nem ferramentas especializadas.

O script compare-complexity.py compara duas versões de um arquivo. Ele calcula complexidade ciclomática, complexidade cognitiva, índice de manutenibilidade, número de linhas e tamanho médio da linha. É especialmente útil para avaliar se uma refatoração realmente simplificou o código.

python scripts/compare-complexity.py antes.py depois.py

Se o comando for executado com quantidade errada de argumentos, o script exibe a sintaxe esperada e encerra com erro. Essa validação já faz parte do comportamento do utilitário.

3.4.4 Como revisar

Para cada trecho analisado, a resposta final deve incluir um resumo, problemas críticos se existirem e os achados organizados por categoria.

• Resumo: nota geral de 1 a 5, quantidade de achados e prioridades recomendadas.
• Problemas críticos: descrição, localização, impacto, severidade e exemplo de correção.
• Por categoria: segurança, desempenho, qualidade e manutenibilidade.

3.4.5 Template de achado

Use uma estrutura padronizada para que cada problema fique fácil de avaliar, discutir e acompanhar.

## Issue: [TÍTULO]

### Severity
- [ ] Critical (bloqueia deploy)
- [ ] High (corrigir antes do merge)
- [ ] Medium (corrigir em breve)
- [ ] Low (nice to have)

### Category
- [ ] Security
- [ ] Performance
- [ ] Code Quality
- [ ] Maintainability
- [ ] Testing
- [ ] Design Pattern
- [ ] Documentation

### Location
**File:** `src/components/UserCard.tsx`

**Lines:** 45-52

**Function/Method:** `renderUserDetails()`

### Issue Description

**What:** Descreva o problema.

**Why it matters:** Explique o impacto.

**Current behavior:** Mostre o código ou comportamento problemático.

**Expected behavior:** Diga como deveria funcionar.

### Code Example

#### Current (Problematic)

// Mostra o problema N+1
const users = fetchUsers();
users.forEach(user => {
  const posts = fetchUserPosts(user.id); // Uma query por usuário!
  renderUserPosts(posts);
});

#### Suggested Fix

// Otimizado com JOIN
const usersWithPosts = fetchUsersWithPosts();
usersWithPosts.forEach(({ user, posts }) => {
  renderUserPosts(posts);
});

### Impact Analysis

| Aspect | Impact | Severity |
|--------|--------|----------|
| Performance | 100+ queries for 20 users | High |
| User Experience | Slow page load | High |
| Scalability | Breaks at scale | Critical |
| Maintainability | Hard to debug | Medium |

### Related Issues

- Similar issue in `AdminUserList.tsx` line 120
- Related PR: #456
- Related issue: #789

### Additional Resources

- [N+1 Query Problem](https://en.wikipedia.org/wiki/N%2B1_problem)
- [Database Join Documentation](https://docs.example.com/joins)

### Reviewer Notes

- This is a common pattern in this codebase
- Consider adding this to the code style guide
- Might be worth creating a helper function

### Author Response (for feedback)

*To be filled by the code author:*

- [ ] Fix implemented in commit: `abc123`
- [ ] Fix status: Complete / In Progress / Needs Discussion
- [ ] Questions or concerns: (describe)

---

## Finding Statistics (for Reviewer)

- **Total Issues Found:** X
- **Critical:** X
- **High:** X
- **Medium:** X
- **Low:** X

**Recommendation:** ✅ Approve / ⚠️ Request Changes / 🔄 Needs Discussion

**Overall Code Quality:** 1-5 stars

3.4.6 Checklist de revisão

O checklist deve ser usado como guia para não pular categorias relevantes. Ele cobre segurança, desempenho, qualidade e testes.

• Segurança: segredos hardcoded, validação de entrada, prevenção de SQL injection, proteção CSRF e XSS, checagens de autenticação e autorização, hashing seguro de senha, ausência de dados sensíveis em logs e uso obrigatório de HTTPS.
• Desempenho: ausência de N+1, índices adequados, cache quando útil, nada bloqueando a thread principal, uso correto de async/await, paginação em grandes volumes, pool de conexões, regex otimizadas, nenhuma criação desnecessária de objetos e prevenção de vazamentos de memória.
• Qualidade: funções com menos de 50 linhas, nomes claros, sem código duplicado, tratamento de erros, comentários explicando o “por quê”, sem console.log em produção, tipagem adequada, SOLID, padrões de projeto aplicados corretamente e código autoexplicativo.
• Testes: testes unitários, cobertura de casos-limite e cenários de erro, testes de integração, cobertura acima de 80%, sem flakes, mocks para dependências externas e nomes claros para os testes.

3.4.7 Histórico de versão

A skill foi lançada como versão inicial em 2024-12-10, com foco em análise de segurança, desempenho, qualidade e manutenibilidade.

3.5 api-documentation-generator

Esta habilidade gera documentação de API a partir do código-fonte, com foco em especificações OpenAPI/Swagger, documentação de endpoints, exemplos de SDK, guias de integração, referências de erro e instruções de autenticação. Ela é útil quando o pedido envolve docs de endpoints, specs formais ou material de uso para consumidores da API.

3.5.1 O que ela produz

• Especificações OpenAPI/Swagger.
• Documentação de endpoints.
• Exemplos de uso para SDKs.
• Guias de integração.
• Catálogos de códigos de erro.
• Guias de autenticação.

3.5.2 Estrutura recomendada por endpoint

O formato abaixo organiza descrição, parâmetros, respostas e exemplos práticos de forma consistente. Use essa estrutura para que a documentação fique previsível e fácil de consumir.

## GET /api/v1/users/:id

### Description
Brief explanation of what this endpoint does

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | User ID |

### Response

**200 Success**
{
  "id": "usr_123",
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2025-01-15T10:30:00Z"
}

**404 Not Found**
{
  "error": "USER_NOT_FOUND",
  "message": "User does not exist"
}

### Examples

**cURL**
curl -X GET "https://api.example.com/api/v1/users/usr_123" \
  -H "Authorization: Bearer YOUR_TOKEN"

**JavaScript**
const user = await fetch('/api/v1/users/usr_123', {
  headers: { 'Authorization': 'Bearer token' }
}).then(r => r.json());

**Python**
response = requests.get(
    'https://api.example.com/api/v1/users/usr_123',
    headers={'Authorization': 'Bearer token'}
)
user = response.json()

3.5.3 Gerador em Python

O arquivo generate-docs.py extrai documentação de funções Python com base em nomes e anotações. Ele procura funções cujo nome comece com get_ ou post_, lê o docstring, coleta os parâmetros posicionais e identifica o tipo de retorno.

Esse comportamento é útil em projetos Python em que endpoints ou handlers seguem convenções de nomenclatura previsíveis. Não é um gerador universal para qualquer linguagem ou arquitetura.

3.5.4 Como o script funciona

• Ele usa ast.NodeVisitor para percorrer a árvore sintática.
• Para cada FunctionDef compatível, coleta nome, docstring, lista de parâmetros e tipo de retorno.
• Se não houver anotação de retorno, usa Any.
• Na saída, gera markdown concatenando uma seção por endpoint encontrado.

Uso básico:

python generate-docs.py caminho/do/arquivo.py

3.5.5 Limitações e comportamento prático

• Somente funções Python são analisadas.
• O critério de seleção é o prefixo do nome da função; funções que não sigam essa convenção ficam de fora.
• Os parâmetros são coletados de forma simples, sem distinguir parâmetros especiais ou contexto do framework.
• O resultado depende da qualidade dos docstrings e das anotações de tipo existentes.

3.6 code-refactor

Esta habilidade conduz refatorações sistemáticas com base na metodologia de Martin Fowler. O objetivo é melhorar a estrutura interna sem alterar o comportamento externo. O processo é incremental, guiado por testes e sempre com participação do usuário em cada fase.

3.6.1 Princípios centrais

• Preservação de comportamento: a saída externa não deve mudar.
• Passos pequenos: mudanças mínimas e testáveis.
• Orientação por testes: os testes são a rede de segurança.
• Processo contínuo: refatorar não é evento único.
• Colaboração: cada fase exige aprovação do usuário.

3.6.2 Visão geral do fluxo

Phase 1: Research & Analysis
    ↓
Phase 2: Test Coverage Assessment
    ↓
Phase 3: Code Smell Identification
    ↓
Phase 4: Refactoring Plan Creation
    ↓
Phase 5: Incremental Implementation
    ↓
Phase 6: Review & Iteration

3.6.3 Fase 1: pesquisa e análise

Antes de alterar qualquer coisa, é necessário entender o código, o escopo e os objetivos de negócio. Isso evita refatorações “bonitas” que não resolvem o problema real.

Perguntas que precisam ser esclarecidas com o usuário:

• Qual é o escopo: arquivos, módulos ou funções?
• Qual é o objetivo: legibilidade, performance ou manutenção?
• Existe alguma área que não deve ser alterada?
• Há pressão de prazo ou bloqueio de trabalho?
• Os testes existem e estão passando?

Ações esperadas nessa fase:

• Ler e entender o código alvo.
• Identificar dependências e integrações.
• Documentar a arquitetura atual.
• Registrar débitos técnicos visíveis, como TODO e FIXME.

Saída esperada:

• Resumo da estrutura do código.
• Principais áreas problemáticas.
• Recomendações iniciais.
• Pedido de aprovação para avançar.

3.6.4 Fase 2: avaliação da cobertura de testes

Testes são o fator mais importante para refatorar com segurança. Sem eles, o risco de introduzir regressões cresce muito.

Primeiro, procure arquivos de teste:

find . -name "*test*" -o -name "*spec*" | head -20

Depois, execute os testes existentes de acordo com a stack:

# JavaScript/TypeScript
npm test

# Python
pytest -v

# Java
mvn test

Se houver suporte a cobertura, verifique também:

# JavaScript
npm run test:coverage

# Python
pytest --cov=.

Decisões possíveis:

• Se os testes existem e passam: avance para a identificação de smells.
• Se faltam testes ou estão incompletos: considere escrever testes primeiro, adicioná-los aos poucos durante a refatoração ou seguir sem testes apenas com reconhecimento explícito do risco.
• Se os testes falham: pare. Corrija os testes antes de continuar.

Ao escrever testes, cubra sempre:

• Caminho feliz.
• Casos-limite, como entradas vazias, nulas ou fronteiras.
• Cenários de erro, como entradas inválidas e exceções.

O ciclo recomendado é red-green-refactor: escrever teste falhando, fazer passar e só então refatorar.

3.6.5 Fase 3: identificação de code smells

Code smells são sintomas de problemas mais profundos. Não são bugs por si só, mas indicam áreas que tendem a se tornar difíceis de manter.

Catálogo de referência disponível em references/code-smells.md.

Resumo rápido dos smells mais comuns:

• Long Method: métodos com mais de 30 a 50 linhas, difíceis de entender e testar.
• Duplicated Code: lógica repetida em vários lugares, o que duplica esforço de correção.
• Large Class: classe com responsabilidades demais, quebrando responsabilidade única.
• Feature Envy: método usa mais dados de outra classe do que da própria.
• Primitive Obsession: excesso de primitivos onde objetos de domínio fariam mais sentido.
• Long Parameter List: funções com quatro ou mais parâmetros, difíceis de chamar corretamente.
• Data Clumps: mesmos dados aparecem juntos repetidamente, sugerindo abstração faltante.
• Switch Statements: cadeias longas de switch ou if/else, difíceis de estender.
• Speculative Generality: complexidade criada “para o caso de um dia precisar”.
• Dead Code: código não utilizado, que aumenta confusão e custo de manutenção.

Etapas da análise:

1. Executar análise automatizada, se houver script disponível.
2. Fazer revisão manual com atenção a localização e severidade.
3. Priorizar problemas que bloqueiam trabalho, causam bugs ou atingem caminhos importantes.

Saída esperada:

• Lista de smells encontrados com localização.
• Severidade de cada item.
• Ordem de prioridade sugerida.
• Pedido de aprovação das prioridades.

3.6.6 Fase 4: criação do plano de refatoração

Para cada smell, selecione uma técnica adequada do catálogo de refatorações. O arquivo de referência fica em references/refactoring-catalog.md.

Mapeamento principal entre problema e técnica:

• Long Method → Extract Method, Replace Temp with Query.
• Duplicated Code → Extract Method, Pull Up Method, Form Template Method.
• Large Class → Extract Class, Extract Subclass.
• Feature Envy → Move Method, Move Field.
• Primitive Obsession → Replace Primitive with Object, Replace Type Code with Class.
• Long Parameter List → Introduce Parameter Object, Preserve Whole Object.
• Data Clumps → Extract Class, Introduce Parameter Object.
• Switch Statements → Replace Conditional with Polymorphism.
• Speculative Generality → Collapse Hierarchy, Inline Class, Remove Dead Code.
• Dead Code → Remove Dead Code.

A estrutura do plano deve seguir o template em templates/refactoring-plan.md. Cada item precisa deixar claro alvo, problema, técnica, passos, riscos e rollback.

O trabalho deve ser dividido em fases:

• Phase A: Quick Wins — baixo risco e alto valor, como renomear variáveis, extrair duplicações óbvias e remover código morto.
• Phase B: Structural Improvements — risco médio, como extrair métodos, introduzir objetos de parâmetros e mover métodos para classes corretas.
• Phase C: Architectural Changes — risco maior, como substituir condicionais por polimorfismo, extrair classes e introduzir padrões de projeto.

Antes de implementar, apresente o plano completo, explique riscos e peça aprovação explícita. A pergunta de controle sugerida é: “Should I proceed with Phase A?”

3.6.7 Fase 5: implementação incremental

A regra de ouro é simples: mudar, testar, confirmar, commitar e só então seguir para o próximo passo.

Ritmo recomendado por etapa:

1. Verifique se os testes estão verdes e se o código compila.
2. Faça uma única mudança pequena.
3. Execute os testes imediatamente.
4. Se passar, faça o commit com mensagem descritiva.
5. Se falhar, pare, reverta e investigue antes de continuar.

Os commits devem ser:

• Atômicos: uma mudança lógica por vez.
• Reversíveis: fáceis de desfazer.
• Descritivos: o nome do commit precisa dizer o que mudou.

Exemplos de mensagens:

refactor: Extract calculateTotal() from processOrder()
refactor: Rename 'x' to 'customerCount' for clarity
refactor: Remove unused validateOldFormat() method

Após cada subfase, informe o que mudou, se os testes seguem passando, se surgiram problemas e peça permissão para continuar.

3.6.8 Fase 6: revisão e iteração

Depois da refatoração, confirme se o comportamento permaneceu igual e se a qualidade estrutural melhorou.

Checklist final:

• Todos os testes passando.
• Sem novos warnings ou erros.
• Compilação bem-sucedida.
• Comportamento preservado, com verificação manual quando necessário.
• Documentação atualizada, se pertinente.
• Histórico de commits limpo.

Também é recomendado comparar métricas antes e depois. O texto original cita o comando abaixo para análise de complexidade:

python scripts/analyze-complexity.py <file>

Apesar do nome do comando referenciado, o repositório de apoio desta habilidade inclui scripts de métricas e comparação de complexidade. Em geral, o objetivo é relatar variação de linhas, complexidade ciclomática e índice de manutenibilidade.

Ao final, apresente:

• Resumo das mudanças.
• Comparação antes/depois.
• Melhorias métricas.
• Débitos técnicos remanescentes.
• Pedido de confirmação do usuário.

3.6.9 Regras importantes de parada

O processo deve ser interrompido e confirmado com o usuário quando houver incerteza sobre regras de negócio, risco sobre APIs externas, cobertura insuficiente, decisão arquitetural relevante, aumento de risco ou complexidade inesperada.

3.6.10 Regras de segurança do processo

• Nunca refatore sem testes, a menos que o usuário aceite explicitamente o risco.
• Nunca faça mudanças grandes; divida em passos pequenos.
• Nunca pule a execução de testes após cada alteração.
• Nunca continue se os testes falharem; corrija ou reverta primeiro.
• Nunca presuma; quando houver dúvida, pergunte.

3.6.11 O que não fazer

• Não misture refatoração com novas funcionalidades.
• Não refatore em emergência de produção.
• Não refatore código que você ainda não entende.
• Não complicar demais; mantenha simplicidade.
• Não tentar refatorar tudo de uma vez.

3.6.12 Exemplo rápido

Em um método longo com duplicação, o fluxo sugerido é: garantir testes, extrair validação, testar, extrair cálculo, testar, extrair notificação, testar e revisar o papel final do método como orquestrador.

function processOrder(order) {
  validateOrder(order);
  const total = calculateOrderTotal(order);
  notifyCustomer(order, total);
  return { order, total };
}

3.6.13 Referências e scripts

• references/code-smells.md: catálogo completo de code smells.
• references/refactoring-catalog.md: catálogo de técnicas de refatoração.
• templates/refactoring-plan.md: modelo de planejamento.
• scripts/analyze-complexity.py: análise de métricas de complexidade.
• scripts/detect-smells.py: detecção automatizada de smells.

3.6.14 Histórico de versão

A versão inicial é 1.0.0, datada de 2025-01-15, com metodologia Fowler, abordagem em fases e pontos explícitos de consulta ao usuário.

3.7 Catálogo de code smells e utilitários de análise sob demanda

Este bloco reúne dois tipos de conteúdo que se complementam no fluxo de refatoração profissional com Claude Code:

• um catálogo de code smells para diagnóstico arquitetural e de implementação;
• dois scripts Python para análise automática de complexidade e detecção de smells em arquivos Python, JavaScript e TypeScript.

Na prática, você usa o catálogo para interpretar sinais de problema e escolher a refatoração adequada, e usa os scripts para ganhar escala, comparar versões e localizar áreas de risco antes de mexer no código.

3.8 Catálogo de code smells

Code smell não é um erro de compilação nem necessariamente um bug funcional. É um sintoma visível de um problema mais profundo de design, modularização, coesão, acoplamento ou responsabilidade. Em um projeto real, um smell costuma indicar que o código ainda “funciona”, mas ficou mais caro de entender, testar e evoluir.

Os grupos abaixo organizam smells por natureza do problema e ajudam a reconhecer onde a refatoração tende a trazer mais retorno.

3.8.1 Bloaters

São sinais de algo que cresceu demais para ser tratado de forma confortável. O código pode até continuar correto, mas o tamanho já atrapalha leitura, isolamento de testes e mudanças seguras.

3.8.2 Long Method

Um método longo normalmente passa a concentrar validação, cálculo, montagem de resultado, integração externa e regras de negócio no mesmo lugar. O sinal clássico não é só a contagem de linhas; é também a necessidade de rolar a tela para entender o fluxo inteiro, encontrar vários níveis de aninhamento e perceber comentários explicando blocos inteiros.

Quando esse smell aparece, o risco prático é alto: um ajuste em uma parte pode afetar outra sem que a intenção original fique clara. Além disso, fica difícil testar só uma parte da lógica sem montar um cenário enorme.

Refatorações típicas para esse caso incluem:

• Extract Method, para separar blocos com responsabilidade única;
• Replace Temp with Query, quando variáveis temporárias só estão encobrindo cálculos repetidos;
• Introduce Parameter Object, quando o método ficou cheio de parâmetros relacionados;
• Replace Method with Method Object, quando a lógica precisa de estado próprio temporário;
• Decompose Conditional, quando condicionais grandes escondem intenções diferentes.

O material-fonte usa como sinais práticos métodos acima de 30 a 50 linhas, múltiplos níveis de aninhamento e comentários explicativos dentro do método. No script de detecção deste bloco, o limiar padrão é 30 linhas, e acima de 50 linhas a severidade sobe.

Exemplo de antes:

function processOrder(order) {
  // Validar pedido
  if (!order.items) throw new Error('No items');
  if (order.items.length === 0) throw new Error('Empty order');
  // ... mais validações

  // Calcular totais
  let subtotal = 0;
  for (const item of order.items) {
    subtotal += item.price * item.quantity;
  }
  // ... imposto, frete, descontos

  // Enviar notificações
  // ... lógica de email
}

Exemplo de depois:

function processOrder(order) {
  validateOrder(order);
  const totals = calculateOrderTotals(order);
  sendOrderNotifications(order, totals);
  return { order, totals };
}

Observe que o valor da refatoração não é “encurtar por encurtar”; é tornar cada bloco nomeável, testável e reutilizável.

3.8.3 Large Class

Uma classe grande costuma acumular muitos campos, muitos métodos e responsabilidades diferentes. Em geral, ela vira uma “classe gerenciadora” genérica, com nomes vagos como Manager, Handler ou Processor, o que normalmente é um aviso de abstração fraca.

O problema principal é a violação do princípio da responsabilidade única. Se a classe trata autenticação, perfil, cobrança e notificação ao mesmo tempo, qualquer mudança em uma área pode exigir revalidação das outras. Isso aumenta custo de teste, de merge e de compreensão.

Os sinais destacados no material incluem:

• mais de 7 a 10 variáveis de instância;
• mais de 15 a 20 métodos;
• nomes genéricos demais;
• métodos que não usam todos os atributos da classe.

Uma regra de triagem útil apresentada no texto é:

• mais de 300 linhas;
• mais de 15 métodos;
• mais de 10 campos.

Refatorações adequadas:

• Extract Class, para dividir por responsabilidade;
• Extract Subclass, quando parte do comportamento é especializado;
• Extract Interface, quando a classe expõe um contrato que pode ser separado.

3.8.4 Primitive Obsession

Esse smell aparece quando o domínio é modelado com tipos primitivos demais, como string para email, int para dinheiro ou números mágicos para representar estados e categorias. O resultado é um sistema que depende de convenções implícitas espalhadas pelo código, sem validação forte no tipo.

Na prática, isso gera bugs fáceis de introduzir: um email pode vir inválido, uma moeda pode ser tratada como inteiro cru, um código de status pode ser passado com valor incorreto e ninguém percebe até a execução.

Refatorações recomendadas:

• Replace Primitive with Object, para criar tipos de domínio como Email e Money;
• Replace Type Code with Class, quando um código textual ou numérico representa um conceito forte;
• Replace Type Code with Subclasses, quando o comportamento muda por tipo;
• Replace Type Code with State/Strategy, quando a variação é comportamental e pode ser encapsulada.

Exemplo de antes:

const user = {
  email: 'john@example.com',
  phone: '1234567890',
  status: 'active',
  balance: 10050
};

Exemplo de depois:

const user = {
  email: new Email('john@example.com'),
  phone: new PhoneNumber('1234567890'),
  status: UserStatus.ACTIVE,
  balance: Money.cents(10050)
};

Esse tipo de modelagem é especialmente útil quando o domínio precisa de validação, formatação e regras próprias além de simples armazenamento.

3.8.5 Long Parameter List

Uma lista de parâmetros longa normalmente indica que o método está fazendo mais do que deveria ou que está faltando uma abstração para agrupar dados relacionados. O problema fica evidente quando a chamada exige lembrar ordem, tipo e significado de vários argumentos ao mesmo tempo.

O texto aponta como sinais:

• 4 ou mais parâmetros;
• parâmetros que sempre aparecem juntos;
• bandeiras booleanas que mudam o comportamento do método;
• null ou undefined passando com frequência.

Os riscos práticos são confusão na chamada, inversão de ordem, evolução difícil e excesso de responsabilidade no próprio método.

Refatorações úteis:

• Introduce Parameter Object, para agrupar dados correlacionados;
• Preserve Whole Object, quando o método já recebe um objeto e pode usar o objeto inteiro em vez de extrair campos manualmente;
• Replace Parameter with Method Call, quando um valor é derivável internamente;
• Remove Flag Argument, quando um booleano está escondendo dois comportamentos distintos.

Exemplo de antes:

function createUser(firstName, lastName, email, phone,
                    street, city, state, zip,
                    isAdmin, isActive, createdBy) {
  // ...
}

Exemplo de depois:

function createUser(personalInfo, address, options) {
  // personalInfo: { firstName, lastName, email, phone }
  // address: { street, city, state, zip }
  // options: { isAdmin, isActive, createdBy }
}

3.8.6 Data Clumps

Data clumps são grupos de dados que viajam sempre juntos em diferentes partes do código. Quando você percebe os mesmos 3 ou mais campos aparecendo repetidamente, isso geralmente sinaliza uma abstração ausente.

O impacto é parecido com o de parâmetros longos, mas o problema se espalha por várias funções e classes: o conhecimento sobre aquele conjunto de dados fica duplicado, a manutenção ganha atrito e a extensão futura fica mais difícil.

Refatorações normalmente indicadas:

• Extract Class, se os dados formam um conceito de domínio;
• Introduce Parameter Object, se o agrupamento é usado apenas para passagem de dados;
• Preserve Whole Object, quando um conjunto de dados já existe como objeto e deve ser reutilizado.

Exemplo:

// Data clump: coordenadas (x, y, z)
function movePoint(x, y, z, dx, dy, dz) { }
function scalePoint(x, y, z, factor) { }
function distanceBetween(x1, y1, z1, x2, y2, z2) { }

// Extraindo a abstração
class Point3D {
  constructor(x, y, z) { }
  move(delta) { }
  scale(factor) { }
  distanceTo(other) { }
}

3.8.7 Object-Orientation Abusers

Esse grupo reúne sinais de uso incompleto ou incorreto de orientação a objetos. Normalmente o problema não é “usar OO”, e sim usar herança, polimorfismo e encapsulamento de forma desalinhada com o domínio.

3.8.8 Switch Statements

Switches longos ou cadeias grandes de if/else repetidas costumam significar que o comportamento que varia por tipo ainda está centralizado em vez de distribuído em classes ou estratégias. Quando um novo caso exige mudar vários lugares, o código perdeu extensibilidade.

Os sinais relevantes são:

• switch/case ou if/else longos;
• o mesmo switch repetido em vários pontos;
• switch sobre códigos de tipo;
• inclusão de novos casos exigindo alterações amplas.

Isso viola o princípio aberto/fechado porque cada novo tipo força edição do código existente. Além disso, o leitor precisa acompanhar todas as ramificações para entender o comportamento.

Refatorações sugeridas:

• Replace Conditional with Polymorphism;
• Replace Type Code with Subclasses;
• Replace Type Code with State/Strategy.

Exemplo de antes:

function calculatePay(employee) {
  switch (employee.type) {
    case 'hourly':
      return employee.hours * employee.rate;
    case 'salaried':
      return employee.salary / 12;
    case 'commissioned':
      return employee.sales * employee.commission;
  }
}

Exemplo de depois:

class HourlyEmployee {
  calculatePay() {
    return this.hours * this.rate;
  }
}

class SalariedEmployee {
  calculatePay() {
    return this.salary / 12;
  }
}

3.8.9 Temporary Field

Campos temporários aparecem quando um atributo de instância só é usado em alguns métodos, ou só existe em certos cenários de inicialização. Isso cria objetos com estado parcialmente válido e torna a leitura mental mais custosa, porque você precisa lembrar em quais caminhos o campo realmente faz sentido.

O risco prático é confundir “campo existe” com “campo está pronto”. Em sistemas grandes, isso frequentemente vira null escondido, condicionais de inicialização e bugs de estado.

Refatorações sugeridas:

• Extract Class, quando o campo pertence a uma responsabilidade separada;
• Introduce Null Object, quando um valor ausente é um caso explícito de comportamento;
• Replace Temp Field with Local, quando a variável só precisa existir dentro de um método.

3.8.10 Refused Bequest

Esse smell ocorre quando uma subclasse herda algo que não usa ou não respeita. Em vez de representar um verdadeiro relacionamento “é um”, a herança foi usada apenas para reaproveitar código, e a subclasse acaba anulando métodos para fazer nada ou ignorando dados herdados.

Isso costuma violar o princípio de substituição de Liskov e criar uma hierarquia enganosa. O problema técnico é que o leitor imagina um contrato que não existe de fato.

Refatorações comuns:

• Push Down Method/Field, movendo o que é específico para baixo na hierarquia;
• Replace Subclass with Delegate, quando composição é mais apropriada;
• Replace Inheritance with Delegation, quando a relação não é realmente de especialização.

3.8.11 Alternative Classes with Different Interfaces

Esse smell aparece quando há duas ou mais classes fazendo essencialmente a mesma coisa, mas com nomes de métodos diferentes e contratos incompatíveis. Elas poderiam ser intercambiáveis em intenção, mas a interface impede isso.

O custo é duplicação de implementação e impossibilidade de troca simples entre variantes. Em arquitetura, isso costuma ser um indício de que falta uma abstração comum.

Refatorações recomendadas:

• Rename Method, para alinhar semântica;
• Move Method, para aproximar responsabilidade da abstração correta;
• Extract Superclass, quando há um núcleo comum reutilizável;
• Extract Interface, quando o foco é o contrato compartilhado.

3.8.12 Change Preventers

Esses smells tornam mudanças mais caras. Não significam necessariamente que o sistema está errado, mas indicam que alterar um ponto tende a espalhar ajustes em várias partes.

3.8.13 Divergent Change

Ocorre quando a mesma classe passa a ser modificada por vários motivos diferentes. Em geral, isso acontece porque ela reúne responsabilidades de autenticação, perfil, cobrança, notificação e outras áreas que evoluem em ritmos distintos.

O problema prático é que uma classe assim vira ponto de atrito em manutenção. Mudanças não relacionadas compartilham o mesmo arquivo e a mesma área de conflito, o que aumenta chance de regressão e conflito de merge.

Refatorações recomendadas:

• Extract Class;
• Extract Superclass;
• Extract Subclass.

Exemplo conceitual: se uma classe User muda por autenticação, perfil, cobrança e notificações, vale separar em AuthService, ProfileService, BillingService e NotificationService.

3.8.14 Shotgun Surgery

É o inverso do problema anterior: uma pequena mudança exige edição em muitos arquivos diferentes. Isso acontece quando a lógica de um conceito está espalhada e não centralizada.

O risco aqui é alto porque sempre existe a possibilidade de esquecer um ponto. Quanto maior o espalhamento, maior a probabilidade de inconsistência após a mudança.

Refatorações adequadas:

• Move Method;
• Move Field;
• Inline Class.

O material destaca uma regra prática: se adicionar um campo exige alterações em mais de 5 arquivos, há forte indício de shotgun surgery.

3.8.15 Parallel Inheritance Hierarchies

Esse smell aparece quando uma hierarquia força a criação de outra em paralelo. Por exemplo, ao criar uma subclasse em uma árvore, você se vê obrigado a criar uma subclasse correspondente em outra árvore. Isso costuma acontecer com nomes pareados, como DatabaseOrder e DatabaseProduct.

O custo é manter duas estruturas acopladas, dobrando trabalho e aumentando a chance de esquecer a contrapartida. O leitor também precisa entender duas árvores de classes ao mesmo tempo.

Refatorações sugeridas:

• Move Method;
• Move Field;
• eliminar uma das hierarquias quando ela não for realmente necessária.

3.8.16 Dispensables

São elementos desnecessários que podem ser removidos para simplificar o código. Muitas vezes o dispensável existe porque uma solução mais simples já resolveria o problema, ou porque o código antigo ficou sem uso.

3.8.17 Comments (Excessive)

Comentários são úteis quando explicam por que algo existe, mas deixam de ajudar quando apenas repetem o que o código já diz. Comentários que explicam o “o quê” com frequência indicam que a estrutura do código poderia ser melhor nomeada ou extraída.

Também entram aqui código comentado, TODO e FIXME esquecidos por tempo demais e comentários com tom de pedido de desculpas. Tudo isso envelhece mal e tende a divergir do código real.

Refatorações adequadas:

• Extract Method, para que o nome da função carregue a intenção;
• Rename, para melhorar a clareza sem comentário;
• remover código comentado;
• Introduce Assertion, quando a intenção precisa ser tornada explícita no runtime.

Comparação útil:

// RUIM: explica o que o código faz
// Loop through users and check if active
for (const user of users) {
  if (user.status === 'active') { }
}

// BOM: explica por que a filtragem existe
// Active users only - inactive are handled by cleanup job
const activeUsers = users.filter(u => u.isActive);

3.8.18 Duplicate Code

Duplicação é um dos smells mais caros porque qualquer correção precisa ser replicada em vários lugares. Mesmo quando as cópias não são idênticas, variações muito parecidas já indicam que uma abstração está faltando.

Os sinais destacados são:

• mesmo bloco em vários lugares;
• código similar com pequenas variações;
• padrões de copiar e colar.

A regra prática do material é clara: código duplicado 3 ou mais vezes deve ser extraído.

Refatorações úteis:

• Extract Method;
• Extract Class;
• Pull Up Method em hierarquias;
• Form Template Method.

3.8.19 Lazy Class

Uma classe preguiçosa não entrega valor suficiente para justificar sua existência. Ela pode ser apenas uma camada de passagem ou uma abstração superdimensionada criada antes da hora.

O problema é que toda classe adiciona custo de manutenção, navegação e entendimento. Se não há benefício concreto, a abstração vira ruído.

Refatorações adequadas:

• Inline Class;
• Collapse Hierarchy.

3.8.20 Dead Code

Código morto é qualquer trecho sem efeito real: variáveis não usadas, funções sem chamadas, classes sem uso, blocos inalcançáveis ou código atrás de condições impossíveis. Em geral, ele não quebra a execução, mas confunde a leitura e incentiva suposições erradas sobre o sistema.

Os sinais incluem código inalcançável, símbolos não referenciados e até comentários com código antigo.

Refatorações recomendadas:

• Remove Dead Code;
• Safe Delete, quando a remoção precisa ser validada com mais cuidado.

Formas comuns de detectar:

# Procurar exports não usados
# Procurar funções não referenciadas
# Conferir avisos de "unused" na IDE

3.8.21 Speculative Generality

Esse smell surge quando o código está “preparado para o futuro” de forma abstrata demais, sem demanda real. O resultado é complexidade com pouco retorno: classes abstratas com uma única subclasse, parâmetros que só existem “para depois”, métodos que só delegam e frameworks para um único caso de uso.

O princípio associado é o YAGNI: você não deve pagar agora por uma necessidade que talvez nunca aconteça.

Refatorações típicas:

• Collapse Hierarchy;
• Inline Class;
• Remove Parameter;
• Rename Method, quando a intenção real está escondida por excesso de generalidade.

3.8.22 Couplers

São smells ligados a acoplamento excessivo entre classes. Em vez de cada objeto conhecer só o necessário, a implementação começa a navegar demais pela estrutura alheia, acessar partes íntimas ou depender de cadeias frágeis.

3.8.23 Feature Envy

Feature envy ocorre quando um método usa mais dados de outra classe do que da própria classe onde está definido. Frequentemente isso aparece como uma sequência de chamadas getter a outro objeto, enquanto a lógica local fica sem uso.

O problema é de localização do comportamento: a lógica está no lugar errado. Isso quebra encapsulamento e dificulta manutenção porque o método conhece demais a estrutura interna alheia.

Refatorações úteis:

• Move Method;
• Move Field;
• Extract Method seguido de movimentação, quando for necessário isolar o cálculo antes de realocá-lo.

Exemplo de antes:

class Order {
  getDiscountedPrice(customer) {
    if (customer.loyaltyYears > 5) {
      return this.price * customer.discountRate;
    }
    return this.price;
  }
}

Exemplo de depois:

class Customer {
  getDiscountedPriceFor(price) {
    if (this.loyaltyYears > 5) {
      return price * this.discountRate;
    }
    return price;
  }
}

3.8.24 Inappropriate Intimacy

Esse smell acontece quando classes conhecem detalhes internos demais umas das outras, como partes privadas, estado mutável específico ou até referências bidirecionais que deveriam ser evitadas. Em herança, ele também aparece quando a subclasse sabe detalhes excessivos do pai.

O efeito é acoplamento alto. Qualquer mudança de estrutura tende a exigir ajustes em ambos os lados, porque a interface “real” não está bem protegida.

Refatorações recomendadas:

• Move Method;
• Move Field;
• Change Bidirectional to Unidirectional;
• Extract Class;
• Hide Delegate.

3.8.25 Message Chains

Cadeias longas de mensagens, às vezes chamadas de “train wrecks”, aparecem quando o cliente precisa navegar por vários objetos para alcançar um valor final, como a.getB().getC().getD().getValue(). O cliente passa a depender da estrutura interna da navegação, e não apenas do resultado que realmente precisa.

Isso é frágil porque qualquer alteração em um ponto da cadeia pode quebrar a chamada inteira. Também viola a Lei de Demeter, já que o objeto sabe demais sobre os intermediários.

Refatorações úteis:

• Hide Delegate;
• Extract Method;
• Move Method.

Exemplo:

// Ruim: cadeia de mensagens
const managerName = employee.getDepartment().getManager().getName();

// Melhor: esconder a delegação
const managerName = employee.getManagerName();

3.8.26 Middle Man

Um intermediário puro é uma classe que só repassa chamadas para outra, sem agregar comportamento, validação ou abstração útil. Quando boa parte dos métodos apenas delega, a classe está adicionando um nível de indirection que não entrega valor.

Esse padrão atrapalha a leitura e cria mais pontos de manutenção sem necessidade.

Refatorações recomendadas:

• Remove Middle Man;
• Inline Method.

3.9 Guia de severidade dos smells

Nem todo smell exige ação imediata. A severidade ajuda a priorizar o que deve ser corrigido primeiro, especialmente em bases grandes onde a equipe precisa equilibrar refatoração com entrega de valor.

• Critical: bloqueia desenvolvimento ou já está causando bugs; corrigir imediatamente.
• High: gera carga de manutenção significativa; corrigir no sprint atual.
• Medium: incomoda e aumenta risco, mas ainda é manejável; planejar para breve.
• Low: incômodo menor; corrigir oportunisticamente.

3.10 Checklist rápido de detecção manual

Antes de abrir a ferramenta automatizada, vale fazer uma varredura visual com perguntas simples. Isso ajuda a reconhecer padrões óbvios e decidir se a refatoração merece prioridade.

• Existe método com mais de 30 linhas?
• Existe classe com mais de 300 linhas?
• Existe método com mais de 4 parâmetros?
• Há blocos de código duplicados?
• Existe switch/case em tipo código?
• Há código não usado?
• Algum método acessa demais os dados de outra classe?
• Há cadeias longas de chamadas?
• Os comentários explicam “o quê” em vez de “por quê”?
• Há primitivas que deveriam ser objetos de domínio?

3.11 Script analyze-complexity.py

Este utilitário faz uma análise de complexidade para arquivos Python, JavaScript e TypeScript. Ele não substitui um analisador semântico completo, mas é muito útil para comparar versões, medir efeito de refatorações e localizar arquivos que merecem revisão mais profunda.

Ele calcula cinco grupos principais de métricas:

• Cyclomatic Complexity: quantos pontos de decisão o código tem;
• Cognitive Complexity: o quão difícil o código é de entender;
• Maintainability Index: índice geral de manutenibilidade de 0 a 100;
• Lines of Code: total de linhas relevantes;
• Function Count e Average Function Length: quantidade e tamanho médio das funções.

3.11.1 Uso suportado

O script aceita três modos principais:

1. analisar um arquivo único;
2. comparar dois arquivos, tipicamente antes e depois de refatorar;
3. analisar recursivamente um diretório.

python analyze-complexity.py <arquivo>
python analyze-complexity.py <arquivo_antes> <arquivo_depois>
python analyze-complexity.py --dir <diretorio>
python analyze-complexity.py -v <arquivo>

Flags disponíveis:

• --dir ou -d: analisa todos os arquivos suportados dentro de um diretório;
• --verbose ou -v: mostra detalhes por função;
• --json ou -j: emite o resultado em JSON;
• files: argumentos posicionais, usados como arquivo único ou par antes/depois.

3.11.2 Detecção de linguagem e cobertura

O analisador identifica a linguagem pela extensão do arquivo:

• .py → Python;
• .js e .jsx → JavaScript;
• .ts e .tsx → TypeScript.

Se a extensão não for reconhecida, ele assume Python por padrão. Isso é importante porque os padrões de função, classe, comentário e decisão mudam conforme a linguagem.

3.11.3 Como o script mede complexidade

A complexidade ciclomática é calculada de forma simplificada: começa em 1 e soma ocorrências de estruturas de decisão, como if, for, while, case, try, except e operadores lógicos relevantes. Na prática, isso fornece um indicador útil de ramificação, mas não é equivalente a um analisador de AST completo.

A complexidade cognitiva tenta aproximar o esforço humano de entendimento. O script incrementa a pontuação por estruturas aninhadas e por quebras de fluxo como break, continue, return e throw quando elas ocorrem em contexto mais profundo.

O índice de manutenibilidade é uma aproximação baseada em uma fórmula que combina volume Halstead simplificado, complexidade ciclomática e linhas de código. O resultado é limitado de 0 a 100 e interpretado assim:

• 85 a 100: altamente manutenível;
• 65 a 84: moderadamente manutenível;
• 50 a 64: difícil de manter;
• 0 a 49: muito difícil de manter.

Como o cálculo de volume Halstead é aproximado, use o resultado como sinal comparativo, não como verdade absoluta.

3.11.4 Estrutura de métricas internas

O script modela duas estruturas principais:

• FunctionMetrics, para métricas de uma função individual;
• FileMetrics, para consolidar a análise do arquivo inteiro.

Essas estruturas carregam o nome do arquivo, contagem de linhas, quantidade de comentários, quantidade de funções, quantidade de classes, complexidade ciclomática, complexidade cognitiva, índice de manutenibilidade, tamanho médio e máximo de funções, além da lista detalhada das funções encontradas.

3.11.5 Limitações práticas do analisador

Por ser baseado principalmente em expressões regulares e contagem de linhas, o script tem limitações importantes:

• não interpreta completamente a árvore sintática do código;
• pode errar em casos de sintaxe não convencional ou muito dinâmica;
• identifica funções e classes por padrões textuais, o que pode gerar falsos positivos ou falsos negativos;
• a contagem de parâmetros é simplificada e baseada na primeira linha da definição;
• em JavaScript e TypeScript, o rastreamento de blocos usa contagem de chaves;
• comentários multilinha são tratados por padrão simples de início e fim;
• o cálculo de complexidade cognitiva não cobre todas as sutilezas da semântica da linguagem.

Na prática profissional, isso significa que o script é excelente para triagem e comparação relativa, mas a decisão final ainda precisa de revisão humana.

3.11.6 Saída detalhada e comparação

No modo normal, o script imprime um resumo com linhas de código, linhas em branco, linhas de comentário, quantidade de funções, classes e métricas de complexidade. Também interpreta o índice de manutenibilidade com rótulos visuais.

No modo --verbose, ele lista detalhes por função, incluindo intervalo de linhas, complexidade ciclomática, complexidade cognitiva e quantidade de parâmetros. Funções com mais de 10 de complexidade ciclomática ou mais de 50 linhas recebem marcação visual de alerta.

Quando você passa dois arquivos, o script entra em modo de comparação e imprime, para cada métrica, o valor antes, o valor depois e a variação. Ele também faz uma avaliação geral observando três sinais:

• melhora ou piora na manutenibilidade;
• redução ou aumento da complexidade ciclomática;
• redução ou aumento do tamanho médio das funções.

Isso é especialmente útil em refatorações orientadas por evidência: você altera o código e confirma se o resultado ficou realmente mais simples.

3.11.7 Exemplo de uso em arquivo único

python analyze-complexity.py app.py

Esse comando analisa o arquivo app.py e exibe um panorama geral da complexidade. Se o arquivo estiver em JavaScript ou TypeScript, basta trocar a extensão para que a detecção de linguagem funcione.

3.11.8 Exemplo de comparação antes/depois

python analyze-complexity.py before.py after.py

Esse modo é ideal para verificar se uma refatoração realmente reduziu ramificações, encurtou funções ou melhorou o índice de manutenibilidade.

3.11.9 Exemplo com saída JSON

python analyze-complexity.py --json app.ts

No modo JSON, o script retorna um objeto com o nome do arquivo e as métricas principais. O formato inclui:

{
  "filename": "app.ts",
  "lines_of_code": 182,
  "cyclomatic_complexity": 24,
  "cognitive_complexity": 31,
  "maintainability_index": 67.42,
  "function_count": 9,
  "avg_function_length": 12.7
}

Esse formato é útil para automação, integração com pipelines ou pós-processamento por outras ferramentas.

3.12 Script detect-smells.py

Este segundo utilitário procura smells comuns em arquivos Python, JavaScript e TypeScript com base em padrões práticos. Ele é mais amplo que o analisador de complexidade porque além de medir, ele classifica problemas por tipo e severidade.

Os smells detectados incluem:

• Long Method;
• Long Parameter List;
• Duplicate Code;
• Large Class;
• Dead Code;
• Complex Conditional;
• Magic Number/String;
• Feature Envy;
• Excessive Comments;
• Deeply Nested Code;
• Primitive Obsession;
• Data Clumps;
• Switch Statement;
• Message Chain.

3.12.1 Uso suportado

python detect-smells.py <arquivo>
python detect-smells.py --dir <diretorio>
python detect-smells.py -v <arquivo>

Flags:

• --dir ou -d: varre um diretório inteiro;
• --verbose ou -v: imprime snippet de código junto com cada achado;
• --json ou -j: gera saída estruturada em JSON;
• argumento posicional file: arquivo a ser analisado.

3.12.2 Severidade e classificação

O detector usa uma enumeração de severidade com quatro níveis:

• Low
• Medium
• High
• Critical

Embora o catálogo conceitual acima classifique prioridade de forma geral, este script usa a própria severidade para orientar ação e relatórios. A classe SmellReport expõe contadores prontos para cada faixa, o que facilita sumarização e automação.

3.12.3 Thresholds configuráveis no detector

O detector concentra seus limiares em um dicionário chamado THRESHOLDS. Os valores atuais são:

• long_method_lines: 30;
• very_long_method_lines: 50;
• max_parameters: 4;
• large_class_lines: 300;
• large_class_methods: 10;
• max_nesting_depth: 4;
• long_chain_length: 3;
• duplicate_min_lines: 5.

Esses valores são úteis como ponto de partida, mas podem ser ajustados para o padrão do seu time. Em bases de legado, limiares um pouco maiores podem reduzir ruído; em bases novas, vale ser mais rigoroso.

3.12.4 Como o detector trabalha

Assim como o analisador de complexidade, o detector identifica linguagem pela extensão do arquivo e lê o código inteiro em memória. Em seguida, varre as linhas procurando padrões simples e monta uma lista de objetos CodeSmell, cada um com tipo, severidade, localização, intervalo de linhas, descrição, sugestão e snippet de código.

O relatório final é agregado por tipo de smell, o que ajuda a perceber concentração de problemas. Em modo detalhado, cada achado vem acompanhado do trecho de código identificado.

3.12.5 Detecção de método longo

O detector identifica definições de função ou método e conta linhas aproximadas de cada bloco. Para Python, o fim da função é inferido pela mudança de indentação; para JavaScript e TypeScript, a lógica também considera chaves.

Se o método passa de 30 linhas, ele entra como Medium; acima de 50 linhas, como High. A sugestão gerada é aplicar Extract Method.

Essa checagem funciona bem para casos óbvios, mas pode ser enganada por estruturas incomuns, funções aninhadas ou definições muito compactas distribuídas em múltiplas linhas.

3.12.6 Detecção de lista longa de parâmetros

O script identifica chamadas e definições com muitos parâmetros. Em Python, ele ignora self e cls porque esses parâmetros fazem parte da convenção da linguagem e não representam complexidade real de domínio.

Acima de 4 parâmetros, o smell é reportado. Se houver mais de 6 parâmetros, a severidade sobe para High; caso contrário, fica em Medium.

A sugestão padrão é usar Introduce Parameter Object ou Preserve Whole Object.

3.12.7 Detecção de classe grande

A análise procura classes com muitas linhas e muitas declarações de métodos. Em Python, métodos são inferidos por indentação; em JavaScript e TypeScript, o detector procura padrões de método ou atribuições em classe.

Se a classe ultrapassa 300 linhas, ela recebe peso maior e pode ser classificada como High. Se passa do limite de métodos, a severidade tende a Medium. O texto de saída explica exatamente quais critérios foram violados.

A sugestão é Extract Class, porque o problema geralmente é uma classe concentrando responsabilidades demais.

3.12.8 Detecção de condicionais complexas

Esse detector conta operadores lógicos como and, or, && e || em uma mesma linha. Quando encontra três ou mais operadores, sinaliza uma condicional complexa.

Essa heurística é útil para encontrar pontos onde Decompose Conditional ou Consolidate Conditional Expression podem tornar a intenção mais clara.

3.12.9 Detecção de números e strings mágicos

O detector ignora alguns valores comuns e aceitáveis, como 0, 1, -1, 2, 100, true, false, null, None, "" e ''. Ele também pula linhas de comentário e importação.

Em seguida, busca literais numéricos em linhas de código e reporta apenas os que parecem participar de comparação ou operação aritmética. A intenção é reduzir ruído e focar em números com cara de valor de negócio escondido.

A severidade aqui é Low, porque muitos números são legítimos. Mesmo assim, o achado é útil quando aquele valor deveria virar constante nomeada.

3.12.10 Detecção de comentários excessivos

O script procura comentários que descrevem ações triviais, como set, get, return, loop, check, increment e termos semelhantes. A ideia é identificar comentários que repetem a estrutura do código em vez de explicar o motivo da decisão.

Esses casos são classificados com severidade Low, e a sugestão é trocar o comentário por nome de método mais explícito ou simplesmente removê-lo após refatorar.

3.12.11 Detecção de aninhamento profundo

O detector considera que código muito aninhado costuma ser difícil de ler e de testar. Em Python, a profundidade é inferida por indentação em blocos de quatro espaços; em JavaScript e TypeScript, usa-se contagem de chaves.

Se a profundidade atingir 4 níveis ou mais, o smell é reportado. Acima de 5 níveis, a severidade sobe para High; caso contrário, fica em Medium.

A sugestão indicada é Replace Nested Conditional with Guard Clauses ou Extract Method.

3.12.12 Detecção de switch statement

Em Python, o detector procura cadeias de if/elif com comparação por igualdade. Em JavaScript e TypeScript, ele procura switch e conta ocorrências de case.

Se a cadeia ou o switch tiver 4 ou mais casos, o smell é reportado como oportunidade de polimorfismo. Isso se conecta diretamente ao smell conceitual de Switch Statements descrito no catálogo.

A sugestão é Replace Conditional with Polymorphism.

3.12.13 Detecção de message chains

O detector busca cadeias longas de chamadas em uma única expressão, como navegação sucessiva por vários objetos. Quando a cadeia tem 3 ou mais chamadas encadeadas, ela é classificada como Message Chain.

A recomendação é Hide Delegate, reduzindo o conhecimento do cliente sobre a estrutura interna da navegação.

3.12.14 Detecção de código duplicado

A versão deste detector é simplificada: ela normaliza linhas significativas e procura o mesmo texto aparecendo 3 ou mais vezes. Isso não detecta duplicação estrutural profunda, mas ajuda a localizar repetições textuais com boa precisão.

A sugestão padrão é Extract Method. Em alguns cenários, a extração de classe ou a criação de uma abstração comum será mais apropriada, mas a primeira sinalização vem da repetição da linha.

3.12.15 Detecção de código morto

O detector aponta padrões comuns de código possivelmente morto, como comentários com TODO ou FIXME pedindo remoção, ou blocos atrás de condições sempre falsas como if False: e if (false).

O objetivo não é provar dead code com análise estática completa, e sim alertar para trechos que merecem revisão manual.

3.12.16 Saída de relatório

O relatório impresso organiza os achados por tipo e mostra a quantidade de ocorrências por severidade. Se não houver smells, a ferramenta sinaliza que o arquivo está limpo.

No modo detalhado, cada item inclui snippet de código com uma seta marcando a linha considerada principal. Isso é útil quando se quer localizar rapidamente o trecho exato sem abrir o editor.

O fluxo de ação recomendado ao final do relatório segue a prioridade de severidade:

• corrigir Critical primeiro;
• planejar High para o sprint atual;
• agendar Medium para as próximas entregas;
• resolver Low de forma oportunista.

3.12.17 Exemplo de saída JSON do detector

{
  "filename": "service.js",
  "total_smells": 4,
  "critical": 1,
  "high": 1,
  "medium": 2,
  "low": 0,
  "smells": [
    {
      "type": "Long Method",
      "severity": "High",
      "location": "service.js:18-82",
      "line_start": 18,
      "line_end": 82,
      "description": "Method 'processOrder' is 65 lines (threshold: 30)",
      "suggestion": "Apply Extract Method to break down into smaller functions"
    }
  ]
}

3.13 Como usar os dois scripts juntos no dia a dia

Uma sequência prática para refatoração orientada por evidência é:

1. rodar detect-smells.py no arquivo ou pasta;
2. identificar os smells mais graves ou mais frequentes;
3. aplicar refatorações como Extract Method, Move Method ou Extract Class;
4. rodar analyze-complexity.py antes e depois para verificar se a complexidade realmente caiu;
5. se necessário, repetir com --verbose para inspecionar funções específicas.

Esse ciclo é particularmente útil quando o código já está funcional e o objetivo é melhorar legibilidade, testabilidade e estabilidade sem alterar o comportamento público.

3.14 Troubleshooting e comportamento prático

Ao usar esses scripts, alguns problemas são comuns e esperados. O primeiro é falso positivo: por serem baseados em padrões textuais, eles podem marcar algo que, no contexto do seu projeto, não é realmente um smell. O segundo é falso negativo: uma estrutura sofisticada pode passar despercebida, principalmente se o código estiver distribuído em várias linhas ou usar sintaxe menos convencional.

Se o relatório parecer ruidoso, ajuste os thresholds no código-fonte do detector, especialmente para tamanho de método, contagem de parâmetros e profundidade de aninhamento. Em projetos com estilo diferente do padrão do script, isso costuma melhorar bastante a relação sinal/ruído.

Se a análise ficar incoerente em arquivos muito dinâmicos, use a ferramenta como triagem inicial e complemente com revisão manual. Para bases com muitos wrappers, delegações e métodos gerados, o modo --verbose ajuda a entender por que algo foi detectado.

Se um arquivo não for reconhecido corretamente, confirme a extensão. O comportamento padrão sempre cai para Python quando a extensão não está mapeada, então esse detalhe pode mudar bastante a qualidade da análise.

Em diretórios grandes, a análise percorre recursivamente todos os arquivos suportados e segue em frente mesmo se algum arquivo gerar exceção; o erro é mostrado por arquivo, o que facilita localizar problemas de leitura ou sintaxe sem interromper a varredura inteira.

3.15 Saídas e contratos importantes para automação

Ambos os scripts aceitam saída em JSON, o que é útil para pipelines, dashboards e pós-processamento. O analisador de complexidade retorna um conjunto enxuto de métricas principais, enquanto o detector retorna um relatório com contadores e a lista de smells encontrados.

Em integração automatizada, o contrato mais útil é tratar o JSON como fonte de verdade para gate de qualidade, enquanto a saída textual fica reservada para diagnóstico humano.

3.16 Template de Plano de Refatoração

Este modelo serve para registrar, acompanhar e aprovar uma iniciativa de refatoração de forma organizada. A ideia não é apenas listar tarefas: o plano ajuda a deixar explícito o objetivo da mudança, o nível de risco, o que precisa estar pronto antes de começar, como medir o antes e o depois e como reverter se algo sair do esperado.

Em projetos profissionais, esse tipo de documento é especialmente útil quando a refatoração afeta arquivos críticos, envolve várias pessoas ou precisa de validação formal antes do merge.

3.17 Informações do Projeto

Preencha primeiro o contexto básico da refatoração. Esses campos ajudam a identificar rapidamente o escopo e o responsável.

• Project/Module: nome do projeto, serviço, pacote ou módulo sendo trabalhado.
• Target Files: lista dos arquivos que serão alterados. Pode incluir caminhos relativos completos, como src/order/order.js e src/order/pricing.js.
• Date Created: data de criação do plano.
• Author: nome de quem elaborou o plano.
• Status: estado atual do plano. Os valores sugeridos são Draft, In Review, Approved, In Progress e Completed.

O status é importante porque indica em que etapa a refatoração está. Um plano em Draft ainda está sendo montado; In Review indica análise técnica; Approved significa que houve aceite; In Progress mostra execução em andamento; e Completed marca conclusão.

3.18 Resumo Executivo

O resumo executivo deve explicar rapidamente por que a refatoração existe e qual o limite da mudança. Ele deve ser claro o suficiente para leitura por liderança técnica, produto ou revisão de PR.

3.18.1 Objetivos

Liste os objetivos principais da refatoração em formato de checklist. É comum incluir:

• melhorar legibilidade;
• reduzir duplicação;
• aumentar testabilidade;
• simplificar manutenção;
• diminuir complexidade ciclomática;
• reduzir acoplamento entre componentes.

Exemplo prático: se um método concentra validação, cálculo e persistência, o objetivo pode ser separar responsabilidades para tornar o código mais fácil de testar e evoluir.

3.18.2 Restrições

As restrições definem o que não pode mudar durante a refatoração. Isso evita decisões que quebram contratos já assumidos pelo sistema.

• não alterar a API pública;
• manter compatibilidade retroativa;
• não mexer no schema do banco;
• não mudar comportamento observável;
• não alterar integrações externas.

Essas limitações são críticas quando o código já está em produção ou quando outras equipes dependem dele. Se a refatoração exigir algo fora dessas regras, o plano precisa registrar explicitamente o impacto e pedir nova aprovação.

3.18.3 Nível de risco

Classifique o trabalho como Low, Medium ou High:

• Low: mudanças pequenas, previsíveis e bem cobertas por testes.
• Medium: alterações moderadas, com risco controlável, mas que afetam mais de um ponto do código.
• High: mudanças profundas, com chance maior de regressão e necessidade de validação cuidadosa.

Essa classificação ajuda a decidir o ritmo de execução, a necessidade de aprovação do usuário e a quantidade de checkpoints durante a implementação.

3.19 Checklist Pré-Refatoração

Antes de iniciar qualquer alteração, verifique a maturidade do código e a segurança para avançar. Esse bloco serve como barreira de entrada para evitar que a refatoração seja feita sobre uma base já instável.

3.19.1 Avaliação da cobertura de testes

O template sugere avaliar cobertura e saúde de testes em três dimensões principais:

• Unit Test Coverage: percentual atual de cobertura de testes unitários. O alvo sugerido é pelo menos 80%, embora esse número possa ser ajustado conforme o contexto do sistema.
• Integration Tests: indicar se há testes de integração. O valor esperado é Yes.
• All Tests Passing: indicar se todos os testes estão verdes antes de começar.

Na prática, não basta ter testes existentes; eles precisam estar executando com sucesso. Refatorar sobre uma base já quebrada dificulta distinguir falhas antigas de falhas introduzidas pela mudança.

3.19.2 Itens obrigatórios antes de começar

• todos os testes passando;
• código revisado e compreendido;
• backup ou versionamento disponível;
• aprovação do usuário ou stakeholder quando necessária.

O item de backup/versionamento é essencial para permitir reversão rápida. Em ambientes com Git, isso normalmente significa trabalhar em branch dedicada e manter commits pequenos e rastreáveis.

3.20 Code Smells Identificados

Essa seção registra os problemas de design ou manutenção que motivaram a refatoração. O objetivo é tornar explícito o que está ruim, onde está ruim e por que merece atenção.

3.20.1 Resumo dos smells

A tabela resume cada odor de código identificado, com sua localização, severidade e prioridade.

• Smell: nome do problema, como Long Method, Duplicate Code ou Feature Envy.
• Location: arquivo e linha, por exemplo src/order/order.js:45.
• Severity: gravidade técnica do problema.
• Priority: ordem sugerida de execução, como P1, P2 ou P3.

É importante não usar apenas o nome do smell. A combinação entre severidade e prioridade orienta o planejamento: um problema grave pode não ser prioritário se estiver em área pouco usada, enquanto um problema médio pode ser prioridade alta se estiver em fluxo crítico.

3.20.2 Análise detalhada

Para cada smell relevante, documente os seguintes itens:

• Location: arquivo e intervalo de linhas afetado.
• Description: descrição detalhada do problema.
• Impact: efeitos práticos sobre leitura, manutenção, testes, performance ou risco de regressão.
• Proposed Solution: visão resumida da correção proposta.

Exemplo de aplicação: se um método ficou longo demais, descreva se ele concentra validação, regras de negócio e formatação. O impacto pode ser baixa legibilidade, dificuldade de teste e maior chance de erro ao alterar qualquer parte. A solução pode ser separar blocos em métodos menores e nomeados por responsabilidade.

3.21 Fases de Refatoração

O template organiza o trabalho em fases para controlar risco e permitir entregas incrementais. Isso é especialmente útil quando a refatoração envolve dependências internas ou mudanças estruturais mais profundas.

3.21.1 Fase A: Quick Wins

Esta fase reúne melhorias simples, de baixo risco, com benefício imediato. É a etapa ideal para ganhar confiança, reduzir ruído e gerar um primeiro conjunto de commits seguros.

Objetivo: aplicar melhorias simples com valor visível rapidamente.

Mudanças estimadas: informe quantos arquivos e métodos serão tocados.

Aprovação do usuário: pode ser Yes ou No, dependendo da política do time. Mesmo sendo uma fase de baixo risco, algumas equipes exigem confirmação formal.

Exemplos típicos dessa fase:

• renomear variáveis para nomes mais expressivos;
• remover código morto;
• extrair validações duplicadas para um método reutilizável.

O plano também deve incluir uma estratégia de rollback, como reverter os commits específicos da fase. Isso reduz o custo de desfazer uma mudança se um problema surgir logo após a aplicação.

3.21.2 Fase B: Melhorias Estruturais

Nessa etapa, o foco é organização interna e clareza de design. O risco sobe porque o código passa por redistribuição de responsabilidades, mas ainda sem uma alteração arquitetural profunda.

Objetivo: melhorar organização e legibilidade estrutural.

Aprovação do usuário: normalmente Yes.

Dependências: a Fase A deve estar concluída antes de seguir.

Exemplos comuns:

• extrair um método longo em métodos menores;
• introduzir um objeto parâmetro para reduzir a quantidade de argumentos;
• mover um método para a classe onde os dados realmente vivem.

O rollback deve apontar para o commit posterior à Fase A, permitindo desfazer a evolução estrutural sem perder os ganhos simples já validados.

3.21.3 Fase C: Mudanças Arquiteturais

Essa fase aborda problemas mais profundos de estrutura, normalmente com maior impacto em design e maior chance de regressão se a sequência não for bem controlada.

Objetivo: resolver questões estruturais mais complexas.

Aprovação do usuário: normalmente obrigatória.

Dependências: Fases A e B devem estar concluídas antes de iniciar.

Exemplos típicos:

• substituir switch ou cadeias de condicionais por polimorfismo;
• extrair uma classe de serviço a partir de uma classe excessivamente inchada.

O plano de rollback deve voltar ao commit posterior à Fase B. Isso é importante porque alterações arquiteturais podem espalhar efeitos por vários arquivos e classes.

3.22 Passos Detalhados de Cada Refatoração

Além do planejamento por fase, cada tarefa precisa de uma seção própria com o passo a passo. Isso permite execução controlada e facilita revisão por pares.

3.22.1 Identificação da tarefa

Para cada tarefa, registre:

• Task ID: identificador curto, como A1 ou B2;
• Task Name: nome descritivo da tarefa;
• Smell Addressed: problema que está sendo tratado;
• Refactoring Technique: técnica usada, como Extract Method ou Move Method;
• Risk Level: Low, Medium ou High.

3.22.2 Contexto antes e depois

Documente o estado atual e o estado esperado com trechos de código. Isso ajuda a equipe a entender o objetivo da mudança antes da execução.

O bloco Before deve conter o código atual, exatamente como está no momento do planejamento. O bloco After deve mostrar como o código deve ficar ao final da refatoração.

// Before
function calculateTotal(items) {
  let total = 0;
  for (const item of items) {
    if (item.active) {
      total += item.price * item.quantity;
    }
  }
  return total;
}

// After
function calculateTotal(items) {
  return items
    .filter(item => item.active)
    .reduce((total, item) => total + item.price * item.quantity, 0);
}

Os exemplos acima são apenas ilustrativos. Em um plano real, o código precisa representar fielmente o trecho que será alterado.

3.22.3 Mecânica passo a passo

Liste as etapas pequenas e verificáveis que levarão do estado atual ao estado final. Cada passo deve indicar teste e resultado esperado.

1. descrição da primeira ação, como renomear, extrair ou mover uma parte do código;
2. segunda ação, geralmente já com validação intermediária;
3. terceira ação, encerrando a tarefa ou consolidando a mudança.

A recomendação de executar testes após cada passo existe para evitar introdução de regressões cumulativas. Mesmo quando a mudança parece simples, a validação incremental ajuda a localizar rapidamente o ponto de falha.

3.22.4 Verificação

Ao final da tarefa, confirme itens de qualidade básicos:

• todos os testes passando;
• comportamento preservado;
• código compilando com sucesso;
• nenhum warning novo introduzido.

Se o projeto usa linguagem interpretada, o item de compilação pode ser substituído por verificação de lint, build, type check ou outra checagem equivalente do ecossistema.

3.22.5 Mensagem de commit

Registre uma mensagem objetiva, iniciando com refactor:. Isso ajuda a manter histórico consistente e facilita busca por mudanças de refatoração.

refactor: extract price calculation from order processing

3.23 Acompanhamento de Progresso

Essa parte do template serve para acompanhar a execução em tempo real. Ela é útil tanto para trabalho individual quanto para times com múltiplos revisores.

3.23.1 Status por fase

Para cada fase, registre:

• Status: Not Started, In Progress ou Done;
• Started: data ou horário de início;
• Completed: data ou horário de conclusão;
• Tests Passing: indicação de que a bateria de testes permanece verde naquela etapa.

Esse controle evita que uma fase seja considerada concluída sem validação real.

3.23.2 Problemas encontrados

Registre qualquer obstáculo surgido durante a implementação:

• o que aconteceu;
• como foi resolvido;
• se ainda está aberto ou já foi resolvido.

Manter esse histórico é útil para aprendizado e para futuras refatorações semelhantes. Muitas vezes, um problema que parece pontual revela dependências escondidas ou fragilidades de teste.

3.24 Comparação de Métricas

O template incentiva medir o efeito da refatoração com métricas objetivas. Isso reduz a avaliação baseada apenas em percepção.

3.24.1 Antes da refatoração

Registre valores por arquivo e no total quando fizer sentido. As métricas sugeridas são:

• Lines of Code: quantidade de linhas de código;
• Cyclomatic Complexity: complexidade ciclomática;
• Maintainability Index: índice de manutenibilidade;
• Number of Methods: número de métodos;
• Avg Method Length: tamanho médio dos métodos.

Esses números ajudam a mostrar se a refatoração simplificou o código ou apenas o reorganizou visualmente.

3.24.2 Depois da refatoração

Repita as mesmas métricas e inclua uma coluna de mudança. A comparação antes/depois é importante para evidenciar se houve melhoria real.

Em alguns casos, o total de linhas pode até aumentar um pouco, mas a manutenibilidade e a clareza melhoram. O foco não deve ser apenas reduzir linhas, e sim melhorar qualidade estrutural com segurança.

3.25 Checklist Pós-Refatoração

Depois de concluir a mudança, valide novamente o que garante entrega segura:

• todos os testes passando;
• nenhum warning ou erro novo;
• compilação bem-sucedida;
• verificação manual concluída;
• documentação atualizada, se necessário;
• código revisado;
• métricas melhoradas;
• aprovação final do usuário obtida.

A verificação manual é importante para confirmar fluxos que os testes automatizados podem não cobrir, como integrações visuais, comportamento de ponta a ponta ou regras com dependências externas.

3.26 Lições Aprendidas

Essa seção transforma a refatoração em aprendizado reutilizável. Ela ajuda a equipe a melhorar o processo nas próximas intervenções.

3.26.1 O que funcionou bem

Liste práticas, decisões ou ferramentas que ajudaram no andamento da refatoração. Exemplos:

• quebrar a mudança em commits pequenos;
• rodar testes após cada etapa;
• isolar uma classe problemática antes de expandir o escopo.

3.26.2 O que poderia melhorar

Aqui entram pontos fracos do processo, como:

• cobertura de testes insuficiente;
• documentação desatualizada;
• dependências implícitas difíceis de enxergar;
• necessidade de dividir melhor a refatoração em fases menores.

3.26.3 Recomendações para o futuro

Use essa parte para registrar ações preventivas que facilitem próximas refatorações. Isso pode incluir criar testes antes de mexer em áreas críticas, padronizar nomes, ou adotar análise de complexidade como critério de priorização.

3.27 Aprovações

O bloco de aprovações formaliza quem analisou e aceitou o plano. Em organizações com governança mais rígida, isso ajuda a demonstrar rastreabilidade.

• Plan Author: autor do plano.
• Technical Lead: liderança técnica responsável pela validação técnica.
• Product Owner: responsável pelo aceite do lado do produto, quando aplicável.

Registrar nome, data e assinatura cria um histórico útil para auditoria interna e para alinhamento entre engenharia e negócio.

3.28 Apêndice

O apêndice reúne referências complementares para que o plano não fique isolado do restante da base de conhecimento do projeto.

3.28.1 Documentação relacionada

Inclua links para documentos de arquitetura, especificações funcionais, guias de estilo, RFCs ou qualquer material que explique o contexto do código em refatoração.

3.28.2 Materiais de referência

Também vale apontar para catálogos internos ou externos de:

• code smells;
• técnicas de refatoração.

Esse vínculo ajuda a justificar por que determinada técnica foi escolhida e facilita revisão por pessoas menos familiarizadas com o problema.

3.28.3 Ferramentas usadas

Liste as ferramentas envolvidas no trabalho, como:

• framework de testes;
• linters;
• ferramentas de análise de complexidade;
• build tools ou analisadores estáticos, quando aplicável.

Esse registro é valioso porque a repetição do mesmo processo no futuro depende de saber exatamente como a qualidade foi validada.

4 Módulo — Subagentes, isolamento e times de agentes

4.1 Subagentes: visão geral, isolamento e coordenação de times

Subagentes são assistentes de IA especializados que o Claude Code pode acionar para executar tarefas delegadas. Cada subagente trabalha com uma janela de contexto própria, separada da conversa principal, e pode receber ferramentas específicas, permissões restritas e um prompt de sistema customizado. Na prática, isso permite dividir trabalho complexo em partes menores, com menos poluição de contexto e mais controle operacional.

O uso típico começa de forma simples: você pede ao Claude para criar um subagente para uma finalidade específica, como revisão de segurança, ou cria diretamente um arquivo em .claude/agents/<nome>.md. A partir da versão v2.1.198, o comando /agents deixou de abrir um assistente interativo de criação; a forma recomendada passou a ser pedir ao Claude ou editar os arquivos manualmente.

4.1.1 Benefícios principais

• Preservação de contexto: o subagente opera fora da conversa principal, evitando que tarefas grandes “sujem” o raciocínio do agente principal.
• Especialização: cada subagente pode ser ajustado para um domínio, como revisão de código, testes, documentação ou investigação.
• Reuso: o mesmo subagente pode ser reaproveitado em projetos diferentes e compartilhado com o time.
• Controle de permissões: você pode reduzir ferramentas disponíveis por tipo de tarefa, por exemplo, um revisor que só lê arquivos.
• Escalabilidade: várias tarefas especializadas podem acontecer em paralelo, reduzindo tempo total de execução.

4.2 Onde os arquivos de subagente ficam

Claude Code reconhece subagentes em múltiplos níveis de escopo. Quando houver nomes repetidos, vence a definição com maior prioridade. Em monorepos com várias pastas .claude/, a regra é a da definição mais próxima do diretório atual.

• 1. Definição pela CLI: via flag --agents, em JSON. Vale apenas para a sessão atual.
• 2. Projeto: .claude/agents/. Afeta somente o projeto atual.
• 3. Usuário: ~/.claude/agents/. Disponível em todos os projetos.
• 4. Plugin: diretório agents/ do plugin. Tem a menor prioridade.

Esse comportamento é importante para evitar ambiguidades. Se um agente com o mesmo nome existir em mais de um nível, o Claude usa o primeiro encontrado pela ordem acima. Em estruturas aninhadas de .claude/agents/, a versão mais próxima do diretório de trabalho atual vence dentro do mesmo tipo de escopo.

4.3 Formato de configuração de um subagente

O arquivo do subagente usa frontmatter YAML seguido do prompt do sistema em Markdown. O frontmatter define nome, descrição, ferramentas, modelo, restrições e recursos adicionais.

---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3
disallowedTools: tool4
model: sonnet
permissionMode: default
maxTurns: 20
skills: skill1, skill2
mcpServers: server1
memory: user
background: false
effort: high
isolation: worktree
initialPrompt: "Start by analyzing the codebase"
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

Your subagent's system prompt goes here.
It can be multiple paragraphs and should clearly define the subagent's role,
capabilities, and approach to solving problems.

4.3.1 Campos do frontmatter

• name (obrigatório): identificador único, em minúsculas e com hífens.
• description (obrigatório): texto natural explicando quando o agente deve ser invocado. Incluir termos como use PROACTIVELY ajuda a incentivar invocação automática.
• tools: lista separada por vírgulas com ferramentas específicas. Se omitido, o subagente herda todas as ferramentas disponíveis. Também aceita a sintaxe Agent(agent_name) para restringir quais subagentes ele pode acionar.
• disallowedTools: lista separada por vírgulas com ferramentas explicitamente proibidas.
• model: modelo usado pelo subagente. Pode ser sonnet, opus, haiku, um ID completo de modelo, ou inherit.
• permissionMode: modo de permissão, com valores como default, acceptEdits, dontAsk, bypassPermissions e plan.
• maxTurns: limite de turns agentic que o subagente pode executar.
• skills: lista de skills pré-carregadas. O conteúdo completo das skills entra no contexto no início. A partir de v2.1.133+, subagentes também descobrem skills de projeto, usuário e plugins via ferramenta de Skills, igual à sessão principal.
• mcpServers: servidores MCP disponíveis para o subagente.
• hooks: hooks com escopo de componente, como PreToolUse, PostToolUse e Stop.
• memory: escopo do diretório persistente, podendo ser user, project ou local.
• background: em v2.1.198, subagentes já rodam em background por padrão. Definir true força execução sempre em background e impede execução inline.
• effort: nível de esforço de raciocínio, com valores low, medium, high ou max.
• isolation: defina worktree para dar ao subagente um git worktree isolado.
• initialPrompt: primeira instrução enviada automaticamente quando o subagente roda como agente principal.

4.4 Campos honrados quando o agente vira agente principal

Quando um subagente é usado como agente principal de uma sessão, por exemplo com claude --agent <nome> ou no modo --print, alguns campos do frontmatter passam a ser respeitados diretamente.

Esses comportamentos têm suporte por versão:

• mcpServers é honrado a partir de v2.1.117+ quando o agente é invocado como agente principal.
• permissionMode é honrado a partir de v2.1.119+ para agentes встро? built-in via --agent <nome>.
• tools e disallowedTools passam a ser respeitados em --print a partir de v2.1.119+, o que é útil para uso não interativo e scripts.

4.4.1 Exemplo com MCP e permissões restritas

---
name: secure-researcher
description: Research agent with scoped MCP access and restricted permissions
permissionMode: acceptEdits
mcpServers:
  notion:
    type: http
    url: https://mcp.notion.com/mcp
  github:
    type: http
    url: https://api.github.com/mcp
tools: Read, Grep, Glob
---

You are a research agent. You may query Notion and GitHub through the
configured MCP servers, and read local files, but you cannot write or
execute commands outside of accepted edits.

claude --agent secure-researcher

4.5 Configuração de ferramentas

O subagente pode herdar todas as ferramentas ou receber apenas um subconjunto. Isso é essencial para segurança e previsibilidade: agentes de leitura não deveriam ter acesso desnecessário a escrita ou execução de comandos.

4.5.1 Opção 1: herdar todas as ferramentas

Se o campo tools for omitido, o agente recebe todas as ferramentas permitidas no ambiente atual.

---
name: full-access-agent
description: Agent with all available tools
---

4.5.2 Opção 2: declarar ferramentas individualmente

Você pode enumerar quais ferramentas o agente pode usar. Esse é o padrão mais seguro quando o papel do agente é bem definido.

---
name: limited-agent
description: Agent with specific tools only
tools: Read, Grep, Glob, Bash
---

Atenção para o comportamento de Glob e Grep em v2.1.113+: em builds nativos de macOS/Linux, essas capacidades podem ser fornecidas como bfs e ugrep via ferramenta Bash, em vez de aparecerem como ferramentas separadas. Em builds Windows e npm-JS, elas continuam expostas como ferramentas independentes. Mesmo assim, você ainda pode referenciar Glob e Grep em listas de ferramentas permitidas, porque a substituição no backend acontece de forma transparente.

4.5.3 Opção 3: acesso condicional a Bash

Também é possível restringir comandos Bash por padrão de correspondência, útil quando você quer permitir apenas famílias específicas de comandos.

---
name: conditional-agent
description: Agent with filtered tool access
tools: Read, Bash(npm:*), Bash(test:*)
---

4.6 Configuração via CLI com JSON

Além dos arquivos em disco, você pode definir subagentes por sessão usando a flag --agents com JSON. Isso é prático para experimentação rápida, automação ou ajustes temporários sem alterar o projeto.

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

4.6.1 Formato JSON aceito pela flag --agents

{
  "agent-name": {
    "description": "Required: when to invoke this agent",
    "prompt": "Required: system prompt for the agent",
    "tools": ["Optional", "array", "of", "tools"],
    "model": "optional: sonnet|opus|haiku"
  }
}

Esse formato segue a mesma lógica de prioridade dos arquivos, com a diferença de que a definição em CLI vence tudo por ser válida apenas para a sessão atual.

4.7 Subagentes embutidos no Claude Code

O Claude Code traz alguns subagentes nativos sempre disponíveis. Eles cobrem casos comuns e já vêm com comportamento e ferramentas pré-definidos.

• general-purpose: tarefas complexas com múltiplas etapas, pesquisa extensa e alterações de código.
• Plan: usado automaticamente no modo de plano para pesquisar o código antes de propor um roteiro.
• Explore: exploração de base de código em modo somente leitura, com retorno rápido ou detalhado.
• Bash: execução de comandos de terminal em contexto separado.
• statusline-setup: configuração da barra de status.
• Claude Code Guide: respostas sobre recursos e uso do Claude Code.

4.7.1 General-purpose

Esse agente herda o modelo do agente pai e tem acesso a todas as ferramentas. É a escolha padrão para tarefas complexas que exigem exploração, raciocínio e modificação de código no mesmo fluxo.

Use quando a tarefa envolver várias decisões, investigação ampla e execução prática.

4.7.2 Plan

O subagente Plan herda o modelo do agente pai e usa Read, Glob, Grep e Bash. Ele participa automaticamente do modo plano para entender a base antes da apresentação do plano de ação.

É a opção apropriada quando o Claude precisa mapear o repositório antes de propor alterações.

4.7.3 Explore

O subagente Explore trabalha em modo estritamente somente leitura. Ele herda o modelo da sessão, com limite superior em Opus a partir de v2.1.198; se você quiser mantê-lo mais barato e rápido, pode definir model: haiku.

Suas ferramentas são Glob, Grep, Read e Bash, mas apenas com comandos de leitura. Use para busca e entendimento de código sem risco de alteração.

Os níveis de profundidade disponíveis são:

• quick: busca rápida com exploração mínima, boa para localizar padrões específicos.
• medium: equilíbrio entre velocidade e profundidade; é o padrão.
• very thorough: análise ampla, com múltiplos locais e convenções de nomes; pode demorar mais.

4.7.4 Bash

Esse subagente executa comandos de shell em uma janela de contexto própria. É útil quando a execução de comandos precisa ficar isolada do raciocínio principal.

4.7.5 statusline-setup

Esse agente usa Sonnet, com ferramentas Read, Write e Bash, e existe para configurar a exibição da status line do Claude Code.

4.7.6 Claude Code Guide

Esse agente usa Haiku para responder rápido e com baixa latência. Ele é somente leitura e serve para dúvidas sobre funcionalidades e uso do produto.

4.8 Gerenciando subagentes

A forma mais simples de criar ou ajustar um subagente é pedir diretamente ao Claude. Ele pode gerar o arquivo com frontmatter adequado e prompt inicial coerente com a intenção descrita.

Create a subagent that reviews code for security vulnerabilities.

O Claude cria o arquivo .claude/agents/<nome>.md com ferramentas, modelo e descrição sugeridos. Depois disso, você pode refinar o conteúdo manualmente ou pedir novos ajustes ao próprio Claude.

Em v2.1.198, o fluxo interativo do comando /agents foi removido. A orientação atual é editar os arquivos diretamente ou solicitar a criação ao Claude.

4.8.1 Criação manual por arquivo

Você também pode criar o arquivo diretamente no projeto ou no diretório do usuário. Isso é útil quando você quer controle total sobre nome, permissões e conteúdo.

# Create a project subagent
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
name: test-runner
description: Use proactively to run tests and fix failures
---

You are a test automation expert. When you see code changes, proactively
run the appropriate tests. If tests fail, analyze the failures and fix
them while preserving the original test intent.
EOF

# Create a user subagent (available in all projects)
mkdir -p ~/.claude/agents

4.9 Como os subagentes são acionados

O Claude pode delegar automaticamente tarefas com base no texto do seu pedido, na descrição do agente e no contexto disponível. Em geral, descrições bem escritas aumentam bastante a chance de uso automático.

Para incentivar a invocação proativa, inclua termos como use PROACTIVELY ou MUST BE USED no campo description.

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after writing or modifying code.
---

4.9.1 Invocação explícita

Você pode pedir diretamente que um subagente específico execute uma tarefa.

> Use the test-runner subagent to fix failing tests
> Have the code-reviewer subagent look at my recent changes
> Ask the debugger subagent to investigate this error

A partir de v2.1.140, o parâmetro subagent_type usado em chamadas da ferramenta Agent ou na flag --agent passa a ser caseless e a ignorar o estilo de separador. Isso significa que code-reviewer, Code Reviewer e code_reviewer podem resolver para o mesmo agente. Esse comportamento reduz falhas silenciosas causadas por pequenas variações de capitalização.

4.9.2 Invocação com @-mention

O prefixo @ força a escolha de um subagente específico, evitando heurísticas automáticas.

> @"code-reviewer (agent)" review the auth module

4.9.3 Agente principal da sessão

Você pode rodar a sessão inteira usando um subagente como agente principal. Isso muda o ponto de partida da conversa e faz esse agente atuar como coordenador da interação.

# Via CLI flag
claude --agent code-reviewer

# Via settings.json
{
  "agent": "code-reviewer"
}

4.9.4 Listagem dos agentes disponíveis

O comando claude agents lista todos os agentes configurados, agrupados por fonte, incluindo built-in, usuário e projeto.

claude agents

O resultado também mostra quando um agente de maior prioridade está sobrescrevendo um agente de menor prioridade com o mesmo nome.

4.10 Subagentes retomáveis

Subagentes podem continuar conversas anteriores com o contexto preservado. Isso é muito útil para pesquisas longas, exploração iterativa e fluxos que atravessam várias sessões.

# Initial invocation
> Use the code-analyzer agent to start reviewing the authentication module
# Returns agentId: "abc123"

# Resume the agent later
> Resume agent abc123 and now analyze the authorization logic as well

Esse recurso é apropriado quando você precisa de continuidade sem perder o histórico de investigação ou decisões já tomadas.

4.11 Encadeamento de subagentes

Você pode executar vários subagentes em sequência. O resultado de um serve como entrada para o próximo, permitindo fluxos de trabalho compostos.

> First use the code-analyzer subagent to find performance issues,
  then use the optimizer subagent to fix them

Esse padrão funciona bem quando a etapa de diagnóstico e a etapa de correção exigem competências diferentes.

4.12 Memória persistente para subagentes

O campo memory define um diretório persistente que sobrevive entre conversas. O subagente pode registrar achados, notas e progresso, e depois retomar esse conhecimento nas próximas execuções.

4.12.1 Escopos de memória

• user: ~/.claude/agent-memory/<name>/. Útil para preferências pessoais e conhecimento compartilhado entre projetos.
• project: .claude/agent-memory/<name>/. Adequado para conhecimento do projeto que pode ser compartilhado pelo time.
• local: .claude/agent-memory-local/<name>/. Ideal para conhecimento local que não deve ser versionado.

4.12.2 Como funciona na prática

• As primeiras 200 linhas de MEMORY.md dentro do diretório de memória são carregadas automaticamente no prompt do sistema do subagente.
• As ferramentas Read, Write e Edit ficam habilitadas automaticamente para manipular os arquivos de memória.
• O subagente pode criar outros arquivos no diretório de memória, conforme necessário.

Um exemplo de configuração é definir um agente de pesquisa que vá acumulando conhecimento ao longo do tempo.

---
name: researcher
memory: user
---

You are a research assistant. Use your memory directory to store findings,
track progress across sessions, and build up knowledge over time.

Check your MEMORY.md file at the start of each session to recall previous context.

Em termos de fluxo, uma sessão grava em MEMORY.md, e a próxima sessão lê esse conteúdo de volta. Isso cria um ciclo contínuo de aprendizado incremental.

4.13 Subagentes em background

A partir de v2.1.198, subagentes passam a rodar em background por padrão. O Claude continua trabalhando na conversa principal enquanto o subagente executa a tarefa e avisa quando termina.

Se você definir background: true, o subagente fica sempre em background, impedindo execução inline. Isso é útil para tarefas longas ou monitoramento contínuo.

4.13.1 Configuração

---
name: long-runner
background: true
description: Performs long-running analysis tasks in the background
---

4.13.2 Atalhos de teclado

• Ctrl+B: coloca a tarefa de um subagente em background.
• Ctrl+F: encerra todos os agentes em background; pressione duas vezes para confirmar.

4.13.3 Desabilitar tarefas em background

Se a sua operação não pode usar background, defina a variável de ambiente abaixo para desativar esse suporte por completo.

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

4.14 Isolamento por git worktree

Com isolation: worktree, o subagente recebe seu próprio git worktree, o que permite alterar arquivos sem interferir no working tree principal. Esse modo é útil para desenvolvimento paralelo com menor risco de conflito.

---
name: feature-builder
isolation: worktree
description: Implements features in an isolated git worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

O comportamento prático é o seguinte: o subagente trabalha em um branch separado dentro de um worktree independente. Se nenhuma alteração for feita, o worktree é limpo automaticamente. Se houver mudanças, o path do worktree e o nome do branch são devolvidos ao agente principal para revisão ou merge.

4.15 Subagentes forjados por fork de contexto

Subagentes com context: fork herdam o contexto completo da conversa do agente pai no momento do fork, em vez de começar com uma janela vazia. Isso é útil quando você quer explorar alternativas sem perder o trabalho acumulado até ali.

Esse recurso está em GA a partir de v2.1.117. Em builds externos, fora das distribuições first-party, é necessário habilitar CLAUDE_CODE_FORK_SUBAGENT=1.

4.15.1 Configuração

---
name: alternative-explorer
description: Explore an alternative implementation path while preserving parent context
context: fork
tools: Read, Edit, Bash, Grep, Glob
---

You are a forked subagent. You inherit the parent's full conversation and
may explore an alternative approach. Return your findings and the parent
will decide whether to adopt them.

4.15.2 Habilitação em builds externos

export CLAUDE_CODE_FORK_SUBAGENT=1
claude

4.15.3 Quando usar fork e quando usar contexto limpo

• Explorar implementações alternativas: use context: fork.
• Pesquisa longa aproveitando contexto existente: use context: fork.
• Tarefa especializada e independente: prefira contexto limpo, que é o padrão.
• Evitar poluição do contexto: prefira contexto limpo.

4.16 Restringindo quais subagentes podem ser acionados

Você pode limitar quais subagentes um determinado subagente tem permissão para spawnar usando a sintaxe Agent(agent_type) no campo tools. Isso cria uma allowlist explícita de delegação.

Em v2.1.63, a ferramenta Task foi renomeada para Agent. Referências antigas no formato Task(...) ainda funcionam como alias.

---
name: coordinator
description: Coordinates work between specialized agents
tools: Agent(worker, researcher), Read, Bash
---

You are a coordinator agent. You can delegate work to the "worker" and
"researcher" subagents only. Use Read and Bash for your own exploration.

Nesse exemplo, o agente coordinator só pode acionar worker e researcher, mesmo que outros agentes existam no ambiente.

4.17 Comando claude agents

O comando claude agents exibe todos os agentes configurados, agrupados por fonte. Ele também destaca quando há substituição por prioridade, como um agente de projeto sobrescrevendo um agente de usuário com o mesmo nome.

claude agents

4.18 Times de agentes: coordenação experimental

Agent Teams é um recurso experimental que coordena múltiplas instâncias do Claude Code trabalhando juntas em tarefas complexas. A diferença principal para subagentes é que, aqui, os colegas de time trabalham de forma independente, com suas próprias janelas de contexto, e podem trocar mensagens diretamente por um sistema de caixa de entrada compartilhada.

A documentação oficial desse recurso fica em https://code.claude.com/docs/en/agent-teams. O recurso está desabilitado por padrão e requer Claude Code v2.1.32+.

4.18.1 Diferença entre subagentes e times de agentes

• Modelo de delegação: subagentes recebem subtarefas do agente pai e retornam resultado; em times, um líder coordena colegas independentes.
• Contexto: subagentes usam contexto fresco por subtarefa; colegas de time preservam seu próprio contexto persistente.
• Coordenação: subagentes são gerenciados pelo pai; times usam lista compartilhada de tarefas com dependências automáticas.
• Comunicação: subagentes devolvem resultados apenas ao pai; em times, os colegas podem se comunicar entre si pela mailbox.
• Retomada: subagentes suportam retomada; teammates in-process não suportam retomada após o fim da sessão.
• Melhor uso: subagentes são ótimos para subtarefas bem definidas; times servem melhor quando há necessidade de comunicação entre agentes e paralelismo mais rico.

4.18.2 Como habilitar Agent Teams

Você pode habilitar por variável de ambiente ou em settings.json.

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

4.18.3 Como iniciar um time

Depois de habilitar o recurso, basta pedir no prompt para o Claude trabalhar com colegas de time. Ele cria o time, distribui tarefas e coordena o fluxo automaticamente.

User: Build the authentication module. Use a team — one teammate for the API endpoints,
      one for the database schema, and one for the test suite.

4.18.4 Modos de exibição dos colegas

O modo de exibição controla como a atividade dos colegas aparece no terminal.

• Auto (--teammate-mode auto): o Claude escolhe automaticamente a melhor apresentação para seu terminal.
• In-process padrão (--teammate-mode in-process): mostra a saída no terminal atual.
• Split-panes (--teammate-mode tmux): abre cada colega em um painel separado do tmux ou do iTerm2.
• iTerm2 (--teammate-mode iterm2): disponível em v2.1.186+; cria painéis dedicados no iTerm2 e exige o CLI it2. O modo automático avisa quando o CLI não é encontrado.

claude --teammate-mode tmux

{
  "teammateMode": "tmux"
}

O modo split-pane exige tmux ou iTerm2 e não está disponível no terminal do VS Code, no Windows Terminal ou no Ghostty.

4.18.5 Navegação entre colegas

Em modo split-pane, use Shift+Down para alternar entre os colegas.

4.18.6 Configuração de times

As configurações de time ficam em ~/.claude/teams/{team-name}/config.json.

4.18.7 Arquitetura de um time de agentes

O time é composto por um líder, uma lista de tarefas compartilhada, uma mailbox de mensagens e vários colegas independentes, cada um com seu próprio contexto.

Os componentes centrais são:

• Team Lead: a sessão principal do Claude Code, responsável por criar o time, distribuir tarefas e coordenar o trabalho.
• Shared Task List: lista sincronizada de tarefas com rastreamento automático de dependências.
• Mailbox: sistema de mensagens entre agentes para troca de status e coordenação.
• Teammates: instâncias independentes do Claude Code, cada uma com sua janela de contexto.

4.18.8 Atribuição de tarefas e mensagens

O líder quebra o trabalho em tarefas e distribui entre os colegas. A lista compartilhada cuida de dependências automáticas, status e sincronização.

• Gerenciamento automático de dependências: tarefas aguardam a conclusão das dependências.
• Rastreamento de status: os colegas atualizam o estado conforme avançam.
• Mensagens entre agentes: os colegas usam a mailbox para combinar etapas, por exemplo: “o esquema do banco está pronto, você já pode escrever as queries”.

4.18.9 Fluxo de aprovação do plano

Em tarefas complexas, o líder cria um plano de execução antes de os colegas começarem. O usuário revisa e aprova esse plano para garantir que a abordagem esteja alinhada antes de qualquer alteração de código.

4.18.10 Eventos de hook para times

Agent Teams introduz dois eventos adicionais de hook:

• TeammateIdle: dispara quando um colega termina sua tarefa atual e não tem mais trabalho pendente. É útil para notificações ou redistribuição de tarefas.
• TaskCompleted: dispara quando uma tarefa da lista compartilhada é marcada como concluída. Serve para validação, atualização de dashboards ou encadeamento de trabalho dependente.

4.18.11 Boas práticas para times

• Tamanho do time: mantenha de 3 a 5 colegas para coordenar melhor.
• Tamanho das tarefas: prefira tarefas de 5 a 15 minutos; elas precisam ser pequenas o bastante para paralelizar, mas grandes o suficiente para ter valor.
• Evite conflitos de arquivos: distribua arquivos ou diretórios diferentes entre os colegas.
• Comece simples: use o modo in-process na primeira experiência e migre para split-panes quando estiver confortável.
• Descrições claras: dê tarefas específicas e acionáveis para que os colegas consigam trabalhar com autonomia.

4.18.12 Limitações do recurso experimental

• Experimental: o comportamento pode mudar em versões futuras.
• Sem retomada de sessão: colegas in-process não podem ser retomados depois que a sessão acaba.
• Um time por sessão: não é possível criar times aninhados nem múltiplos times na mesma sessão.
• Liderança fixa: o papel de líder não pode ser transferido para um colega.
• Split-pane restrito: depende de tmux ou iTerm2 e não funciona no VS Code terminal, Windows Terminal ou Ghostty.
• Sem times entre sessões: os colegas existem somente dentro da sessão atual.

Como o recurso é experimental, vale começar com trabalho não crítico e monitorar a coordenação para detectar comportamentos inesperados.

4.19 Segurança de subagentes fornecidos por plugins

Subagentes distribuídos por plugins têm capacidades de frontmatter reduzidas por motivos de segurança. Isso impede que um plugin aumente privilégios ou injete comandos arbitrários por meio de hooks.

Os campos que não são permitidos em definições de subagente de plugin são:

• hooks
• mcpServers
• permissionMode

4.20 Arquitetura e ciclo de vida dos subagentes

No nível conceitual, o agente principal recebe a solicitação do usuário e delega partes do trabalho para subagentes especializados. Cada especialista executa sua tarefa num contexto limpo e devolve apenas o resultado sintetizado ao agente principal.

Esse fluxo costuma seguir este ciclo:

1. O usuário faz uma solicitação.
2. O agente principal analisa o problema.
3. Ele delega uma subtarefa para um subagente apropriado.
4. O subagente inicializa um contexto separado.
5. O subagente executa a tarefa conforme suas instruções e ferramentas.
6. O subagente retorna achados ou mudanças.
7. O agente principal incorpora a resposta e entrega a síntese ao usuário.

4.21 Gestão de contexto e comportamento prático

Subagentes recebem uma janela de contexto nova, sem histórico da conversa principal. O agente pai só envia o contexto relevante para a tarefa. Isso evita estourar o limite de tokens em projetos longos e mantém cada especialista focado na própria responsabilidade.

Há alguns comportamentos importantes a observar:

• Nesting de subagentes: desde v2.1.172, um subagente pode spawnar outros subagentes, com profundidade máxima de 5 níveis. Versões anteriores não permitiam nesting. Use a restrição Agent(agent_type) para controlar quais agentes podem ser acionados.
• Permissões em background: subagentes em background negam automaticamente permissões que não tenham sido pré-aprovadas.
• Tecla de background: Ctrl+B muda uma tarefa em execução para background.
• Transcrições: os logs de subagente ficam em ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl.
• Auto-compaction: o contexto do subagente compacta automaticamente em cerca de 95% da capacidade. Esse limiar pode ser sobrescrito pela variável CLAUDE_AUTOCOMPACT_PCT_OVERRIDE.
• Extended thinking herdado: em v2.1.198, subagentes e compactação de contexto passam a herdar a configuração de extended-thinking da sessão. Antes disso, esse comportamento ficava desabilitado. Não existe campo específico por subagente para isso.

4.21.1 Controles adicionais de runtime

• Desabilitar Explore/Plan nativos: use CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 para remover esses agentes embutidos em v2.1.198.
• Append em todos os prompts de subagente: no modo não interativo ou --print, a flag --append-subagent-system-prompt "<text>" adiciona texto ao prompt de sistema de todos os subagentes.

4.22 Quando usar subagentes

Subagentes não são sempre a melhor escolha. Eles brilham quando há complexidade, paralelismo ou necessidade de especialização. Já para tarefas pequenas, eles introduzem latência e custo de coordenação desnecessários.

• Use para features complexas com várias etapas, execução paralela, pesquisa longa e papéis especializados.
• Evite para tarefas simples de uma etapa, como uma revisão rápida ou uma alteração pequena e direta.

4.23 Princípios de design e melhores práticas

Para subagentes úteis de verdade, o desenho importa mais do que o nome. Um bom subagente tem responsabilidade única, ferramentas mínimas e um prompt bem orientado.

4.23.1 O que fazer

• Comece com agentes gerados pelo próprio Claude e depois refine o resultado.
• Crie subagentes focados, com uma única responsabilidade clara.
• Escreva prompts detalhados, com instruções, exemplos e restrições.
• Conceda só as ferramentas necessárias.
• Versione os agentes do projeto para colaboração em equipe.

4.23.2 O que evitar

• Subagentes sobrepostos com papéis muito parecidos.
• Ferramentas desnecessárias.
• Usar subagentes para tarefas triviais.
• Misturar vários assuntos no mesmo prompt.
• Esquecer de passar o contexto essencial.

4.23.3 Boas práticas para o prompt do sistema

1. Seja específico sobre o papel

You are an expert code reviewer specializing in [specific areas]

2. Defina prioridades com clareza

Review priorities (in order):
1. Security Issues
2. Performance Problems
3. Code Quality

3. Especifique o formato de saída

For each issue provide: Severity, Category, Location, Description, Fix, Impact

4. Inclua ações de início

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

4.23.4 Estratégia de acesso a ferramentas

1. Comece restritivo: libere apenas o essencial.
2. Amplie só quando necessário: adicione ferramentas conforme a demanda real.
3. Prefira somente leitura: para análise, use Read e Grep sempre que possível.
4. Execute em sandbox: limite comandos Bash a padrões específicos.

4.24 Exemplos de subagentes deste módulo

Os arquivos de exemplo deste bloco representam perfis úteis para uso profissional imediato. Mesmo que o material fonte cite outros exemplos do diretório, neste bloco temos foco em dois revisores especializados.

4.24.1 clean-code-reviewer.md

Especialista em princípios de Clean Code, com foco em legibilidade, mantenabilidade e qualidade profissional.

• Ferramentas: Read, Grep, Glob, Bash
• Uso recomendado: após escrever código, para identificar violações de design e clareza.
• Especialização: nomes intencionais, funções pequenas, ausência de duplicação, estrutura coesa, SOLID, DRY, KISS, YAGNI e tratamento adequado de erros.

4.24.2 code-reviewer.md

Especialista em revisão geral de código com foco em qualidade, segurança, desempenho e cobertura de testes.

• Ferramentas: Read, Grep, Glob, Bash
• Uso recomendado: logo após escrever ou modificar código, para garantir qualidade e manter segurança.
• Especialização: análise de vulnerabilidades, performance, legibilidade, documentação, design e lacunas de teste.

4.25 Instalação e organização no projeto

Você pode obter subagentes de três maneiras: pedir ao Claude para criar, copiar para o projeto ou copiar para o diretório do usuário.

4.25.1 Método 1: pedir ao Claude

Essa é a forma recomendada quando você quer rapidez sem abrir mão de uma base bem estruturada.

Create a project-level subagent that runs tests and fixes failures.
Give it access to Bash, Read, Edit, and Grep.

O Claude grava o arquivo em .claude/agents/<nome>.md. Depois, revise o conteúdo gerado e faça ajustes conforme necessário.

4.25.2 Método 2: copiar para o projeto

Essa abordagem é útil quando você quer levar um conjunto de agentes para um repositório específico.

# Navigate to your project
cd /path/to/your/project

# Create agents directory if it doesn't exist
mkdir -p .claude/agents

# Copy all agent files from this folder
cp /path/to/04-subagents/*.md .claude/agents/

# Remove the README (not needed in .claude/agents)
rm .claude/agents/README.md

4.25.3 Método 3: copiar para o diretório do usuário

Use quando você quiser os agentes disponíveis em todos os seus projetos.

# Create user agents directory
mkdir -p ~/.claude/agents

# Copy agents
cp /path/to/04-subagents/code-reviewer.md ~/.claude/agents/
cp /path/to/04-subagents/debugger.md ~/.claude/agents/
# ... copy others as needed

4.25.4 Verificação da instalação

Depois de instalar, verifique se os arquivos estão presentes no diretório esperado.

ls .claude/agents/

Você também pode perguntar ao Claude quais subagentes estão disponíveis na sessão atual. Ele consegue reportar os agentes embutidos e os personalizados que pode delegar.

4.26 Estrutura de arquivos esperada

project/
├── .claude/
│   └── agents/
│       ├── code-reviewer.md
│       ├── test-engineer.md
│       ├── documentation-writer.md
│       ├── secure-reviewer.md
│       ├── implementation-agent.md
│       ├── debugger.md
│       └── data-scientist.md
└── ...

4.27 Conceitos relacionados

Subagentes se conectam com outras capacidades do Claude Code e, em muitos fluxos, funcionam melhor quando combinados com elas.

• Slash Commands: atalhos disparados pelo usuário.
• Memory: contexto persistente entre sessões.
• Skills: capacidades reutilizáveis e autoaplicáveis.
• MCP Protocol: acesso a dados externos em tempo real.
• Hooks: automação orientada a eventos de shell.
• Plugins: pacotes de extensão que podem distribuir agentes junto com outros recursos.

4.27.1 Comparação prática entre recursos

• Slash Commands: invocação pelo usuário, sem persistência nem contexto isolado.
• Subagents: podem ser invocados pelo usuário ou automaticamente, com contexto isolado.
• Memory: é automática e persistente, mas não isola contexto nem oferece acesso externo por si só.
• MCP: pode ser automático e oferece acesso externo, sem contexto isolado.
• Skills: podem ser invocadas pelo usuário ou automaticamente, sem persistência própria nem isolamento.

4.27.2 Padrão de integração

Um fluxo robusto normalmente combina essas capacidades: o agente principal usa memória para manter contexto, MCP para consultar dados vivos, skills para capacidades reutilizáveis e subagentes para tarefas especializadas com contexto isolado.

4.28 Observabilidade

A partir de v2.1.139, requisições de API originadas por um subagente carregam dois headers HTTP extras, permitindo correlacionar logs e traces com a sessão que disparou a tarefa.

• x-claude-code-agent-id: UUID do subagente que fez a requisição.
• x-claude-code-parent-agent-id: UUID do agente que disparou esse subagente, seja o agente principal ou um subagente anterior em cadeia.

Os mesmos identificadores também aparecem nos spans OpenTelemetry claude_code.llm_request como os atributos claude.code.agent.id e claude.code.agent.parent_id. Isso é útil para:

• atribuir custo de API a um tipo específico de subagente, em vez de à sessão inteira;
• reconstruir uma árvore de invocações depois do fato;
• criar alertas para subagentes descontrolados, por exemplo quando um agent.id responde por mais de 50% do gasto da sessão.

Para configurar exportação completa, consulte a seção de OpenTelemetry em Advanced Features → Telemetry.

4.29 Notas de versão, limites e compatibilidade

• Subagentes embutidos: disponíveis sempre, mas Explore e Plan podem ser desabilitados via CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 em v2.1.198.
• Background como padrão: a execução em background passou a ser padrão em v2.1.198.
• Fork de subagente: GA em v2.1.117, com habilitação extra em builds externos.
• Nesting de subagentes: suportado até 5 níveis desde v2.1.172.
• Case-insensitive matching: a resolução de subagent_type ficou mais tolerante a partir de v2.1.140.
• Teams experimentais: exigem v2.1.32+ e permanecem desabilitados por padrão.

4.30 Recorte técnico dos exemplos de revisão deste bloco

Os dois arquivos incluídos neste bloco servem como referência de como escrever agentes especializados e seguros.

4.30.1 clean-code-reviewer.md

Este agente concentra a avaliação em princípios de Clean Code. O frontmatter usa model: inherit, o que faz o agente acompanhar o modelo da sessão onde for executado. Ele também pede uso proativo após a escrita do código, para que a revisão aconteça no momento mais útil.

O processo proposto é simples e efetivo: primeiro rodar git diff, depois ler os arquivos relevantes em profundidade e, por fim, reportar violações com arquivo, linha, trecho e correção.

O que ele verifica inclui nomes, funções, comentários, estrutura, princípios SOLID, DRY/KISS/YAGNI, tratamento de erros e code smells. A severidade é classificada em Critical, High, Medium e Low.

O formato de saída exige resumo, lista de violações e boas práticas observadas. O agente também orienta a ser específico, construtivo e prático, e sugere ignorar código gerado, configurações e fixtures de teste.

4.30.2 code-reviewer.md

Este agente faz revisão geral com foco em qualidade, segurança, performance, testes e design. Assim como o anterior, usa model: inherit e se baseia em git diff para analisar apenas o que mudou.

As prioridades estão bem definidas: segurança primeiro, depois performance, depois qualidade, cobertura de testes e padrões de design. O checklist cobre legibilidade, nomes, duplicação, tratamento de erros, segredos expostos, validação de entrada, cobertura e performance.

A saída deve vir organizada por prioridade e conter severidade, categoria, localização, descrição, sugestão de correção e impacto. O exemplo fornecido destaca um problema clássico de performance: N+1 query. Nesse caso, a correção sugerida é usar JOIN ou consulta em lote, porque o impacto cresce linearmente com o volume de dados.

4.31 Referência rápida de comandos e variáveis citadas

• claude --agent <name>: usa um subagente como agente principal da sessão.
• claude --agents '{...}': define agentes por sessão via JSON.
• claude agents: lista agentes configurados e suas origens.
• /agents: não abre mais wizard interativo em v2.1.198+.
• Ctrl+B: coloca tarefa de subagente em background.
• Ctrl+F: encerra todos os background agents.
• CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1: desabilita background tasks.
• CLAUDE_CODE_FORK_SUBAGENT=1: habilita fork de subagente em builds externos.
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1: habilita Agent Teams.
• CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1: remove os agentes embutidos Explore e Plan.
• CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: ajusta o ponto de auto-compaction.
• --teammate-mode auto|in-process|tmux|iterm2: controla a exibição dos colegas.
• --append-subagent-system-prompt "<text>": acrescenta texto ao prompt de todos os subagentes no modo não interativo.

4.32 Subagentes especializados: isolamento de responsabilidades e times de agentes

Este conjunto de subagentes foi desenhado para dividir trabalho técnico em papéis bem definidos. A ideia prática é simples: em vez de pedir que um único agente resolva tudo, você escolhe um especialista com permissões, ferramentas e foco adequados ao tipo de tarefa. Isso reduz retrabalho, melhora a qualidade das respostas e também ajuda a isolar riscos, como alterações indevidas em produção ou análises sem validação adequada.

4.32.1 Como interpretar o campo description, as ferramentas e o modelo

Em cada subagente, o bloco de metadados informa três coisas importantes:

• description: descreve o domínio do agente e em que situações ele deve ser acionado proativamente.
• tools: define quais capacidades o agente pode usar, o que impacta diretamente o nível de risco e o tipo de tarefa que ele consegue executar.
• model: indica se o agente usa um modelo específico, como sonnet, ou herda a configuração do ambiente.

Na prática, isso significa que um agente pode ser mais restrito para auditoria, mais amplo para implementação ou otimizado para tarefas analíticas. A escolha do modelo e das ferramentas afeta custo, velocidade e capacidade de intervenção.

4.33 Agente de ciência de dados

4.33.1 Quando usar

O agente data-scientist é o especialista para consultas SQL, operações em BigQuery e leitura de resultados orientados a negócio. Ele deve ser usado de forma proativa quando a demanda envolve análise de dados, extração de métricas, investigação de tendências ou geração de insights com base em consultas.

4.33.2 Capacidades e permissões

• Bash para executar comandos locais e chamar utilitários do BigQuery.
• Read para inspecionar dados, esquemas e contexto do projeto.
• Write para produzir consultas, scripts ou artefatos de análise.
• Modelo definido como sonnet, ou seja, não herda automaticamente o modelo padrão do restante do sistema.

4.33.3 Fluxo de trabalho esperado

1. Entender claramente a pergunta analítica: qual métrica, período, segmento ou coorte precisa ser avaliada.
2. Escrever SQL eficiente, com filtros e agregações adequados ao volume de dados.
3. Usar a linha de comando bq quando fizer sentido para consulta, inspeção de esquema ou exportação.
4. Analisar o resultado e transformar números em conclusões legíveis.
5. Apresentar achados com foco em decisão, não apenas em listagem de linhas.

4.33.4 Boas práticas centrais

• Priorize consultas otimizadas, com filtros bem colocados e sem varreduras desnecessárias.
• Escolha agregações e junções apropriadas ao problema; evite joins caros sem necessidade.
• Inclua comentários quando a lógica for complexa, especialmente em consultas longas.
• Formate resultados para leitura humana, com nomes de colunas claros e ordenação lógica.
• Finalize com recomendações orientadas por dados, como próximos testes ou cortes adicionais.

4.33.5 Otimização de consultas SQL

Ao construir consultas, a regra é reduzir custo de processamento e evitar resultados mais amplos do que o necessário. Filtrar cedo com WHERE normalmente reduz o conjunto analisado e melhora desempenho. Em ambientes com índices, o uso correto desses índices também pode ser decisivo. Em produção, evitar SELECT * é uma prática importante porque reduz tráfego, melhora estabilidade e evita dependências frágeis em colunas que podem mudar. Durante exploração inicial, limitar o conjunto retornado ajuda a validar a hipótese antes de rodar uma consulta completa.

4.33.6 Recursos específicos do BigQuery

O agente foi preparado para usar a interface de linha de comando do BigQuery em cenários úteis para análise e inspeção.

# Executar uma consulta
bq query --use_legacy_sql=false 'SELECT * FROM dataset.table LIMIT 10'

# Exportar resultados para CSV
bq query --use_legacy_sql=false --format=csv 'SELECT ...' > results.csv

# Obter o schema de uma tabela
bq show --schema dataset.table

O parâmetro --use_legacy_sql=false garante o uso do SQL moderno do BigQuery. Isso é importante porque evita ambiguidades e alinha a consulta com práticas atuais. A exportação para CSV é útil quando a análise precisa sair do terminal para uma planilha ou ferramenta externa. Já o comando de schema ajuda a validar tipos, nomes de campos e estrutura antes de escrever a consulta final.

4.33.7 Tipos de análise cobertos

O agente cobre três grandes categorias de trabalho analítico.

1. Análise exploratória: útil para entender distribuição, perfis de dados e valores ausentes antes de qualquer conclusão.
2. Análise estatística: foca em agregações, séries temporais e correlações para identificar padrões mais robustos.
3. Relatórios: extração de métricas, comparações entre períodos e resumos executivos para tomada de decisão.

4.33.8 Formato de saída recomendado

Quando o agente responder, a estrutura esperada por análise deve conter:

• Objective: qual pergunta está sendo respondida.
• Query: o SQL usado, preferencialmente com comentários.
• Results: os achados principais.
• Insights: a interpretação dos dados.
• Recommendations: as próximas ações sugeridas.

4.33.9 Exemplo de consulta analítica

-- Tendência mensal de usuários ativos
SELECT
  DATE_TRUNC(created_at, MONTH) AS month,
  COUNT(DISTINCT user_id) AS active_users,
  COUNT(*) AS total_events
FROM events
WHERE
  created_at >= DATE_SUB(CURRENT_DATE(), INTERVAL 12 MONTH)
  AND event_type = 'login'
GROUP BY 1
ORDER BY 1 DESC;

Nesse exemplo, a consulta mede a evolução mensal de usuários ativos e eventos de login no período de 12 meses. O uso de DATE_TRUNC facilita a agregação por mês, enquanto o filtro temporal reduz o volume de dados lido.

4.33.10 Checklist de análise

• Requisitos compreendidos.
• Consulta otimizada.
• Resultados validados.
• Achados documentados.
• Recomendações entregues.

4.34 Agente de depuração

4.34.1 Quando usar

O agente debugger é o especialista para erros, falhas de teste e comportamentos inesperados. Ele deve ser acionado proativamente sempre que algo quebra, quando uma execução diverge do esperado ou quando a causa do problema ainda não está clara.

4.34.2 Ferramentas e restrições

• Read para ler código, logs e mensagens de erro.
• Edit para aplicar correções mínimas quando a causa é confirmada.
• Bash para reproduzir, inspecionar e executar testes.
• Grep e Glob para localizar padrões e arquivos relacionados.
• Modelo inherit, ou seja, herda a configuração do ambiente.

4.34.3 Processo de investigação

1. Capturar a mensagem de erro completa e o stack trace.
2. Identificar os passos para reproduzir o problema com consistência.
3. Isolar o ponto exato da falha, reduzindo o escopo até uma função ou linha.
4. Aplicar a correção mínima necessária, evitando mudanças amplas sem evidência.
5. Verificar se a solução realmente resolve e não introduz regressões.

4.34.4 Etapas de análise de causa raiz

Primeiro, leia o erro inteiro e compare com os logs recentes. Muitas vezes a informação mais útil não está apenas na exceção, mas no contexto imediatamente anterior. Depois, verifique mudanças recentes no código, especialmente com git diff, porque regressões costumam surgir após pequenas alterações. Em seguida, formule hipóteses e teste uma por vez. Se necessário, adicione logs estratégicos ou inspecione valores de variáveis para confirmar a suspeita.

4.34.5 Isolamento e correção mínima

Depuração boa não significa mexer em tudo. O ideal é reduzir o problema até uma reprodução mínima e corrigir apenas o ponto que realmente causa a falha. Isso diminui risco de efeitos colaterais e facilita revisão posterior. Depois da correção, rode os testes relevantes e confirme que o comportamento esperado voltou sem quebrar outros caminhos.

4.34.6 Formato de saída esperado

• Error: mensagem original.
• Root Cause: explicação objetiva da falha.
• Evidence: evidência usada para concluir a causa.
• Fix: mudança específica aplicada.
• Testing: como a solução foi verificada.
• Prevention: recomendação para evitar recorrência.

4.34.7 Comandos comuns de investigação

# Ver mudanças recentes
git diff HEAD~3

# Buscar padrões de erro em logs
grep -r "error" --include="*.log"

# Encontrar código relacionado
grep -r "functionName" --include="*.ts"

# Executar um teste específico
npm test -- --grep "test name"

4.34.8 Checklist de depuração

• Mensagem de erro capturada.
• Stack trace analisado.
• Mudanças recentes revisadas.
• Causa raiz identificada.
• Correção implementada.
• Testes aprovados.
• Sem regressões introduzidas.

4.35 Agente de documentação

4.35.1 Quando usar

O agente documentation-writer é o especialista para documentação técnica de APIs, guias de uso, documentação de arquitetura, changelogs e melhoria de comentários no código. Ele é útil tanto para documentação nova quanto para atualização de documentação existente quando o código muda.

4.35.2 Ferramentas e foco

• Read para analisar código e comportamento real.
• Write para criar arquivos de documentação.
• Grep para localizar referências, nomes de endpoints e padrões existentes.
• Modelo inherit, ajustando-se ao ambiente atual.

4.35.3 Etapas ao documentar

1. Analisar o código, a feature ou a API a ser documentada.
2. Identificar o público-alvo, como usuário final, desenvolvedor de integração ou equipe de arquitetura.
3. Produzir documentação seguindo as convenções do projeto.
4. Validar a precisão contra o código real, evitando descrever comportamento inexistente.

4.35.4 Tipos de documentação cobertos

• Documentação de API com exemplos.
• Guias e tutoriais para usuários ou desenvolvedores.
• Documentação de arquitetura.
• Entradas de changelog.
• Melhorias em comentários de código.

4.35.5 Padrões de qualidade

1. Clareza: linguagem simples e direta.
2. Exemplos: exemplos práticos para reduzir ambiguidades.
3. Completude: cobrir parâmetros, retornos e condições relevantes.
4. Estrutura: formatação consistente para facilitar navegação.
5. Precisão: validar tudo contra a implementação atual.

4.35.6 Seções esperadas em documentação de API

• Descrição do recurso.
• Parâmetros com tipos.
• Retornos com tipos.
• Erros possíveis e exceções.
• Exemplos em curl, JavaScript e Python quando relevante.
• Endpoints relacionados.

4.35.7 Seções esperadas em documentação de funcionalidades

• Visão geral.
• Pré-requisitos.
• Passo a passo.
• Resultado esperado.
• Troubleshooting.
• Tópicos relacionados.

4.35.8 Formato de saída esperado

• Type: API / Guide / Architecture / Changelog.
• File: caminho do arquivo de documentação.
• Sections: lista das seções cobertas.
• Examples: quantidade de exemplos incluídos.

4.35.9 Exemplo de documentação de API

## GET /api/users/:id

Recupera um usuário pelo identificador único.

### Parâmetros

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | The user's unique identifier |

### Response

{
  "id": "abc123",
  "name": "John Doe",
  "email": "john@example.com"
}

### Errors

| Code | Description |
|------|-------------|
| 404 | User not found |
| 401 | Unauthorized |

### Example

curl -X GET https://api.example.com/api/users/abc123 \
  -H "Authorization: Bearer <token>"

4.36 Agente de implementação

4.36.1 Quando usar

O agente implementation-agent é o especialista para desenvolver funcionalidades de ponta a ponta a partir de especificações. Ele tem acesso amplo para ler requisitos, escrever arquivos novos, alterar código existente, executar builds e buscar padrões na base de código.

4.36.2 Ferramentas e capacidade total

• Read para entender especificações e código já existente.
• Write para criar arquivos.
• Edit para alterar implementações já presentes.
• Bash para build, scripts e validação.
• Grep e Glob para navegar no repositório e localizar arquivos por padrão.
• Modelo inherit.

4.36.3 Fluxo de implementação

1. Entender completamente os requisitos antes de escrever código.
2. Analisar os padrões já existentes no projeto para manter consistência.
3. Planejar a abordagem técnica antes de editar arquivos.
4. Implementar de forma incremental, reduzindo risco e facilitando revisão.
5. Testar conforme avança, em vez de deixar tudo para o final.
6. Limpar e refatorar ao final para manter legibilidade.

4.36.4 Diretrizes de qualidade

4.36.5 Qualidade de código

• Siga as convenções do projeto.
• Escreva código autoexplicativo sempre que possível.
• Use comentários somente quando a lógica realmente for complexa.
• Mantenha funções pequenas e com responsabilidade única.
• Escolha nomes de variáveis significativos.

4.36.6 Organização de arquivos

• Coloque novos arquivos na estrutura esperada pelo projeto.
• Agrupe funcionalidades relacionadas.
• Respeite as convenções de nomenclatura.
• Evite diretórios profundamente aninhados sem necessidade.

4.36.7 Tratamento de erros

• Trate todos os casos de erro relevantes.
• Mostre mensagens significativas para diagnóstico.
• Registre erros quando fizer sentido operacionalmente.
• Falhe de forma controlada, sem interromper o sistema de modo abrupto.

4.36.8 Testes

• Escreva testes para novas funcionalidades.
• Garanta que os testes existentes continuem passando.
• Cubra bordas e casos alternativos.
• Inclua testes de integração para APIs quando necessário.

4.36.9 Formato de saída esperado

• Files Created: lista de novos arquivos.
• Files Modified: lista de arquivos alterados.
• Tests Added: caminhos dos testes criados.
• Build Status: Pass/Fail.
• Notes: observações importantes.

4.36.10 Checklist de implementação

• Código segue as convenções do projeto.
• Todos os testes passam.
• Build bem-sucedido.
• Sem erros de lint.
• Casos de borda tratados.
• Tratamento de erro implementado.

4.37 Agente de otimização de performance

4.37.1 Quando usar

O agente performance-optimizer é o especialista para identificar gargalos e melhorar desempenho no stack completo. Ele deve ser usado proativamente após escrever ou modificar código, especialmente quando há risco de latência, baixo throughput ou consumo excessivo de memória.

4.37.2 Ferramentas e escopo

• Read para inspecionar código e configuração.
• Edit para aplicar ajustes.
• Bash para profiling, benchmark e execução de ferramentas.
• Grep e Glob para localizar pontos quentes e arquivos relevantes.
• Modelo inherit.

4.37.3 Processo de análise

1. Definir o escopo: API, banco, frontend, algoritmo ou outro subsistema.
2. Estabelecer metas de performance, como latência, throughput ou memória.
3. Concordar com os trade-offs aceitáveis, por exemplo entre legibilidade e velocidade.
4. Medir uma linha de base antes de mudar qualquer coisa.
5. Identificar gargalos e aplicar uma otimização por vez.
6. Repetir a medição para confirmar a melhoria real.

4.37.4 O que o agente avalia

• Complexidade algorítmica, como Big O.
• Problemas de I/O versus CPU.
• Pressão de alocação de memória e coleta de lixo.
• Consultas de banco e problemas N+1.
• Round-trips de rede e tamanho de payload.

4.37.5 Checklist de otimização por área

4.37.6 Algoritmos e estruturas de dados

• Trocar O(n²) por O(n log n) ou O(n) quando possível.
• Usar estruturas adequadas, como hash maps para buscas em O(1).
• Eliminar iterações redundantes e recomputações desnecessárias.
• Aplicar memoização ou cache quando chamadas caras se repetem.

4.37.7 Banco de dados

• Detectar e corrigir problemas N+1 com joins ou batch fetch.
• Adicionar índices em colunas filtradas ou ordenadas com frequência.
• Usar paginação para evitar conjuntos sem limite.
• Preferir projeções, selecionando apenas as colunas necessárias.
• Usar pooling de conexões.

4.37.8 Backend e API

• Levar trabalho pesado para filas ou jobs assíncronos.
• Cachear resultados calculados com TTL apropriado.
• Habilitar compressão HTTP, como gzip ou brotli.
• Usar streaming para respostas grandes.
• Reutilizar recursos caros, como conexões de banco e clientes HTTP.

4.37.9 Frontend

• Reduzir o tamanho do bundle com tree-shaking e code splitting.
• Carregar imagens e recursos não críticos sob demanda.
• Evitar layout thrashing agrupando leituras e escritas no DOM.
• Aplicar debounce ou throttle em eventos caros.
• Usar Web Workers para tarefas intensivas de CPU.

4.37.10 Memória

• Evitar vazamentos liberando timers e listeners.
• Preferir streaming em vez de carregar arquivos inteiros na memória.
• Reduzir alocação de objetos em caminhos quentes.

4.37.11 Comandos comuns de profiling e benchmark

# Node.js — perfil de CPU
node --prof app.js
node --prof-process isolate-*.log > profile.txt

# Python — profiling por função
python -m cProfile -s cumulative script.py

# Go — perfil de CPU com pprof
go test -cpuprofile=cpu.out ./...
go tool pprof cpu.out

# Análise de consulta no PostgreSQL
EXPLAIN ANALYZE SELECT ...;

# Encontrar endpoints lentos em logs estruturados
grep '"status":5' access.log | jq '.duration' | sort -n | tail -20

# Benchmark de função em Go
go test -bench=. -benchmem ./...

# Executar teste de carga com k6
k6 run --vus 50 --duration 30s load-test.js

4.37.12 Formato de saída esperado

• Bottleneck: o que estava lento e por quê.
• Root Cause: causa algorítmica, de I/O, memória ou rede.
• Before: métrica de base antes da mudança.
• Change: ajuste de código ou configuração aplicado.
• After: melhoria medida depois da mudança.
• Trade-offs: custos ou limitações introduzidas.

4.37.13 Checklist de investigação

• Métricas de base capturadas.
• Hotspots identificados por profiling.
• Causa raiz confirmada, não apenas suposta.
• Otimização implementada.
• Testes ainda passam.
• Melhoria medida e documentada.
• Monitoramento e alertas recomendados.

4.38 Agente de revisão segura

4.38.1 Quando usar

O agente secure-reviewer é voltado exclusivamente para análise de vulnerabilidades. Ele é especialmente útil em auditorias de segurança, revisão pré-release e investigações de risco. Seu desenho é propositalmente restrito para reduzir a chance de alterar algo por engano durante a revisão.

4.38.2 Permissões mínimas e implicações práticas

• Read para analisar arquivos.
• Grep para localizar padrões suspeitos.
• Não pode executar código.
• Não pode modificar arquivos.
• Não pode rodar testes.

Essa limitação é uma medida de segurança operacional. O reviewer observa, mas não intervém. Isso é importante em auditorias porque evita que uma análise de segurança cause efeitos colaterais no sistema avaliado.

4.38.3 Focos de revisão de segurança

1. Autenticação: políticas fracas de senha, falta de MFA e falhas de sessão.
2. Autorização: controle de acesso quebrado, escalada de privilégio e checagens de papel ausentes.
3. Exposição de dados: dados sensíveis em logs, armazenamento sem criptografia, exposição de chaves e tratamento inadequado de PII.
4. Injeção: SQL injection, command injection, XSS e LDAP injection.
5. Configuração: modo debug em produção, credenciais padrão e defaults inseguros.

4.38.4 Padrões comuns para procurar

As buscas abaixo ajudam a localizar indícios de credenciais embutidas, consultas vulneráveis e execução de comandos potencialmente perigosa. Elas não substituem revisão manual, mas aceleram a triagem.

# Segredos codificados diretamente
grep -r "password\s*=" --include="*.js" --include="*.ts"
grep -r "api_key\s*=" --include="*.py"
grep -r "SECRET" --include="*.env*"

# Riscos de SQL injection
grep -r "query.*\$" --include="*.js"
grep -r "execute.*%" --include="*.py"

# Riscos de command injection
grep -r "exec(" --include="*.js"
grep -r "os.system" --include="*.py"

4.38.5 Formato de saída esperado

• Severity: Critical, High, Medium ou Low.
• Type: categoria OWASP associada.
• Location: caminho do arquivo e número da linha.
• Description: descrição objetiva da vulnerabilidade.
• Risk: impacto potencial caso seja explorada.
• Remediation: como corrigir o problema.

4.39 Agente de testes

4.39.1 Quando usar

O agente test-engineer é o especialista para criar cobertura de testes robusta. Ele deve ser usado proativamente sempre que uma funcionalidade nova for implementada ou quando código existente for alterado, para garantir que o comportamento continue correto.

4.39.2 Ferramentas e comportamento

• Read para entender o código que precisa de testes.
• Write para criar arquivos de teste.
• Bash para executar a suíte e validar o resultado.
• Grep para localizar convenções e padrões de teste já usados no projeto.
• Modelo inherit.

4.39.3 Estratégia de testes

1. Testes unitários: validam funções ou métodos isoladamente.
2. Testes de integração: verificam interação entre componentes.
3. Testes ponta a ponta: cobrem fluxos completos de uso.
4. Casos de borda: validam limites, valores nulos e coleções vazias.
5. Cenários de erro: cobrem falhas, entradas inválidas e comportamento de recuperação.

4.39.4 Requisitos para os testes

• Usar o framework já adotado no projeto, como Jest, pytest ou equivalente.
• Incluir setup e teardown quando necessário.
• Mockar dependências externas para evitar flutuações.
• Documentar o propósito de cada teste com descrições claras.
• Incluir assertions de performance quando isso fizer sentido para a funcionalidade.

4.39.5 Requisitos de cobertura

O alvo mínimo é 80% de cobertura no código em geral. Para caminhos críticos, como autenticação, pagamentos e manipulação de dados, a meta é 100% de cobertura. Além disso, o agente deve reportar áreas sem cobertura suficiente para orientar o próximo ciclo de testes.

4.39.6 Formato de saída esperado

• File: caminho do arquivo de teste.
• Tests: número de casos de teste criados.
• Coverage: estimativa de ganho em cobertura.
• Critical Paths: caminhos críticos atendidos pelos testes.

4.39.7 Estrutura de exemplo para testes

describe('Feature: User Authentication', () => {
  beforeEach(() => {
    // Setup
  });

  afterEach(() => {
    // Cleanup
  });

  it('should authenticate valid credentials', async () => {
    // Arrange
    // Act
    // Assert
  });

  it('should reject invalid credentials', async () => {
    // Test error case
  });

  it('should handle edge case: empty password', async () => {
    // Test edge case
  });
});

4.39.8 Checklist de testes

• Code path analisado para teste.
• Caminhos críticos e bordas identificados.
• Testes escritos conforme o padrão do projeto.
• Testes executados e aprovados.

5 Módulo — MCP, ferramentas externas e dados vivos

5.1 MCP, ferramentas externas e dados vivos

MCP, sigla para Model Context Protocol, é o mecanismo padronizado que permite ao Claude Code conversar com serviços externos, consultar dados em tempo real e executar ações fora do contexto interno da conversa. A diferença central para a memória é prática: memória serve para guardar preferências, histórico e contexto persistente; MCP serve para acessar dados que mudam o tempo todo, como issues do GitHub, linhas de um banco, arquivos locais, mensagens do Slack e documentos em nuvem.

Na rotina profissional, isso significa que o Claude pode deixar de “imaginar” um estado e passar a consultar a fonte real. Quando você precisa de informação atualizada, validação em sistemas, integração com APIs ou automação entre ferramentas, MCP é o caminho certo.

5.1.1 Características principais do MCP

• Acesso em tempo real a serviços e APIs externas.
• Sincronização viva, acompanhando alterações enquanto a sessão está em andamento.
• Arquitetura extensível, permitindo adicionar novos servidores e ferramentas.
• Autenticação segura, incluindo OAuth, tokens e headers personalizados.
• Interação baseada em ferramentas, com comandos especializados para cada serviço.

5.2 Como a arquitetura funciona

O fluxo básico é sempre o mesmo: o Claude faz uma requisição para um servidor MCP, o servidor consulta ou aciona o sistema externo, e o resultado volta para a conversa. O Claude não fala direto com o GitHub, o banco ou o filesystem; ele fala com o servidor MCP, que faz a mediação.

Esse desenho é importante por segurança e por portabilidade. Você troca o backend ou ajusta credenciais sem mudar a forma como o Claude consome a ferramenta.

5.2.1 Fluxos típicos

• Consulta: Claude pede um dado, o servidor busca e retorna o resultado.
• Ação: Claude solicita uma operação, o servidor executa e devolve a confirmação.
• Atualização dinâmica: o servidor pode notificar mudanças de ferramentas sem reiniciar a sessão.

5.3 Protocolos de transporte suportados

O Claude Code suporta diferentes formas de conexão com servidores MCP. A escolha do transporte afeta onde o servidor roda, como ele é iniciado e qual o custo operacional de manutenção.

5.3.1 HTTP transporto, recomendado

É a opção preferida quando o servidor MCP já existe como serviço web ou quando você quer acesso remoto estável. É também o caminho mais moderno para integrações novas.

# Conexão HTTP básica
claude mcp add --transport http notion https://mcp.notion.com/mcp

# HTTP com cabeçalho de autenticação
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Use HTTP quando o serviço estiver exposto como endpoint e você precisar de integração remota, autenticação por cabeçalho ou conexões que não dependam do processo local do Claude Code.

5.3.2 Stdio transporto, local

Este é o formato usado para servidores que são iniciados como processo filho local. É a escolha típica para ferramentas distribuídas via npx, scripts internos, runtimes locais e integrações que precisam ler arquivos do projeto.

# Servidor local em Node.js
claude mcp add --transport stdio myserver -- npx @myorg/mcp-server

# Com variáveis de ambiente
claude mcp add --transport stdio myserver --env KEY=value -- npx server

Esse modo é útil quando o servidor precisa ter acesso ao mesmo ambiente do projeto, aos mesmos arquivos e às mesmas variáveis de processo.

5.3.3 CLAUDE_PROJECT_DIR para servidores stdio, v2.1.139+

Desde essa versão, todo servidor MCP iniciado via stdio recebe a variável CLAUDE_PROJECT_DIR apontando para o diretório absoluto da raiz do repositório. Isso segue a mesma lógica usada por hooks e facilita resolver caminhos relativos ao projeto, mesmo quando o Claude Code foi aberto de outro diretório.

Você pode usar a variável em command, args e env dentro de arquivos .mcp.json de plugin ou de projeto. A substituição acontece antes do execve(), então o processo já nasce com os caminhos resolvidos.

{
  "mcpServers": {
    "repo-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/mcp/repo-tools.js"],
      "env": {
        "REPO_ROOT": "${CLAUDE_PROJECT_DIR}"
      }
    }
  }
}

Use esse recurso quando o servidor precisar localizar arquivos do repositório sem depender do diretório atual do terminal.

Servidores stdio também recebem CLAUDE_CODE_SESSION_ID, inclusive quando a sessão é retomada com --resume. Esse detalhe é útil para rastreamento, correlação de logs e integração com automações que precisam identificar a sessão ativa.

5.3.4 SSE transporto, obsoleto

Server-Sent Events ainda funciona, mas está desaconselhado. Em projetos novos, prefira http. Use SSE apenas para manter compatibilidade com integrações legadas que ainda não migraram.

claude mcp add --transport sse legacy-server https://example.com/sse

5.3.5 Diretórios de trabalho da sessão, roots/list

Servidores MCP podem descobrir quais diretórios estão disponíveis na sessão. Isso inclui o diretório inicial de abertura do Claude Code e todos os caminhos adicionados por --add-dir ou additionalDirectories. Essa informação é entregue por meio da requisição MCP roots/list.

Quando a lista muda, o Claude Code envia a notificação notifications/roots/list_changed. Esse comportamento foi introduzido na v2.1.203 e é importante para servidores que precisam acompanhar mudanças de escopo de arquivos ao longo da sessão.

Na mesma versão, o timeout ocioso também passou a valer para servidores stdio, com padrão de 30 minutos. Além disso, cada servidor pode ter um timeout próprio atuando como piso mínimo de ociosidade.

5.3.6 Observação específica para Windows

No Windows nativo, e não no WSL, é recomendável envolver comandos npx com cmd /c. Isso evita problemas de execução do shell e garante compatibilidade com o processo filho.

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

5.4 Autenticação OAuth 2.0

O Claude Code suporta OAuth 2.0 para servidores que exigem esse fluxo. Isso reduz o trabalho manual, porque o próprio Claude gerencia o processo de autenticação, o redirecionamento e o armazenamento seguro de tokens.

# Conectar a um servidor com OAuth
claude mcp add --transport http my-service https://my-service.example.com/mcp

# Pré-configurar credenciais OAuth
claude mcp add --transport http my-service https://my-service.example.com/mcp \
  --client-id "your-client-id" \
  --client-secret "your-client-secret" \
  --callback-port 8080

Existem alguns modos de operação relevantes:

• OAuth interativo: o fluxo é iniciado com /mcp e abre o navegador para autenticação.
• Clientes OAuth pré-configurados, v2.1.30+: serviços comuns como Notion e Stripe já podem ter clientes integrados.
• Credenciais pré-definidas: --client-id, --client-secret e --callback-port permitem setups automatizados.
• Armazenamento de tokens: os tokens ficam salvos com segurança no keychain do sistema.
• Step-up auth: suporte a autenticação reforçada para operações privilegiadas.
• Cache de descoberta: metadados OAuth são cacheados para acelerar reconexões.
• Substituição de metadados: é possível apontar a descoberta OAuth para uma URL personalizada no arquivo .mcp.json.

5.4.1 Substituindo a descoberta de metadados OAuth

Alguns servidores expõem falhas no endpoint padrão /.well-known/oauth-authorization-server, mas oferecem um endpoint OIDC funcional. Nesses casos, você pode informar ao Claude Code uma URL alternativa por meio de authServerMetadataUrl dentro do objeto oauth.

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

A URL precisa usar https://. Esse recurso exige Claude Code v2.1.64 ou superior.

5.4.2 Notificação de autenticação no início e refresh dinâmico de headers, v2.1.193+

• Notificação de startup: ao iniciar, o Claude Code mostra quais servidores MCP ainda exigem autenticação. Isso evita que um servidor fique “quebrado” sem visibilidade.
• headersHelper com auto-refresh: se você usa autenticação personalizada por meio de headersHelper, o helper é chamado novamente quando o servidor responde com 401 ou 403. Assim, as credenciais podem ser renovadas sem reconectar manualmente.

Esse comportamento é especialmente útil em integrações com token expiração curta ou rotação frequente de credenciais.

5.5 Conectores MCP do Claude.ai

Servidores MCP configurados na conta do Claude.ai ficam automaticamente disponíveis no Claude Code. Isso reduz trabalho duplicado entre a interface web e o ambiente local.

Esses conectores também funcionam no modo --print, a partir da v2.1.83, o que libera uso não interativo e scripts automatizados.

Na v2.1.117, o padrão passou a ser conexão concorrente quando existem servidores locais e do Claude.ai ao mesmo tempo, o que reduz a latência de inicialização.

Se você quiser desativar os servidores MCP vindos do Claude.ai no Claude Code, defina a variável de ambiente abaixo:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Esse recurso só está disponível para usuários autenticados com contas Claude.ai.

5.6 Fluxo de configuração de MCP

O processo de ativação costuma seguir um padrão simples: listar servidores, escolher um deles, atualizar a configuração, testar a conexão e então começar a usar as ferramentas.

No comando /mcp, você consegue ver servidores conectados, iniciar fluxos OAuth e inspecionar o estado de conexão. Desde a v2.1.121, o Claude Code tenta até 3 vezes reconectar em erros transitórios na conexão inicial. Desde a v2.1.128, a tela também mostra a contagem de ferramentas por servidor e destaca servidores com 0 tools, o que ajuda a detectar configurações quebradas rapidamente.

5.7 Busca de ferramentas MCP

Quando a descrição das ferramentas de um ou mais servidores passa de 10% da janela de contexto, o Claude Code ativa a busca de ferramentas automaticamente. O objetivo é filtrar as opções relevantes sem despejar descrições demais no contexto do modelo.

5.7.1 Opções de configuração da busca

• ENABLE_TOOL_SEARCH=auto: padrão. Liga automaticamente quando o total de descrições ultrapassa 10% do contexto.
• ENABLE_TOOL_SEARCH=auto:<N>: usa um limiar personalizado em número de ferramentas.
• ENABLE_TOOL_SEARCH=true: sempre ativa, independentemente da quantidade de ferramentas.
• ENABLE_TOOL_SEARCH=false: desativa a busca; todas as descrições são enviadas por completo.

Esse recurso exige modelos Sonnet 4 ou superior, ou Opus 4 ou superior. Modelos Haiku não são compatíveis com busca de ferramentas.

5.7.2 Ignorar a busca por servidor, v2.1.121+

Se um servidor é usado em praticamente todas as interações, pode fazer sentido carregá-lo sempre. Nesse caso, marque a configuração com "alwaysLoad": true para evitar o adiamento da carga via tool search.

{
  "mcpServers": {
    "always-on-tool": {
      "command": "node",
      "args": ["./tools/always.js"],
      "alwaysLoad": true
    }
  }
}

Use com parcimônia. Ferramentas sempre carregadas consomem contexto que poderia ser reservado para a busca seletiva de ferramentas mais relevantes.

5.8 Atualizações dinâmicas de ferramentas

O Claude Code suporta notificações list_changed. Na prática, isso significa que, se um servidor adicionar, remover ou modificar ferramentas durante a sessão, o Claude atualiza a lista automaticamente sem necessidade de reiniciar ou reconectar.

5.9 MCP Apps

MCP Apps é a primeira extensão oficial do ecossistema MCP. Ela permite que uma chamada de ferramenta retorne componentes de interface interativos que são renderizados diretamente no chat.

Em vez de receber apenas texto, o Claude pode exibir dashboards, formulários, visualizações de dados e fluxos guiados com múltiplas etapas, tudo embutido na conversa.

5.10 Elicitation MCP

Servidores MCP podem solicitar entrada estruturada do usuário por meio de diálogos interativos. Esse recurso, disponível desde a v2.1.49, é útil quando o fluxo precisa de confirmação, escolha entre opções ou preenchimento de campos obrigatórios no meio da execução.

Na prática, isso transforma integrações passivas em experiências mais ricas e orientadas a processo.

5.11 Limite de descrições e instruções de ferramentas

A partir da v2.1.84, o Claude Code aplica um teto de 2 KB para a soma de descrições e instruções de cada servidor MCP. Isso evita que um único servidor consuma contexto em excesso com metadados muito verbosos.

Se suas descrições ultrapassarem esse limite, a recomendação é reduzir textos explicativos, simplificar instruções e deslocar detalhes operacionais para documentação externa ou prompts específicos.

5.12 Prompts MCP como comandos de barra

Servidores MCP podem expor prompts que aparecem como comandos slash no Claude Code. O formato segue este padrão:

/mcp__<server>__<prompt>

Por exemplo, se o servidor github expõe o prompt review, você pode invocá-lo com:

/mcp__github__review

Esse mecanismo é útil para transformar tarefas repetitivas em comandos curtos e padronizados.

5.13 Deduplicação de servidores

Quando o mesmo servidor MCP é definido em mais de um escopo — local, projeto ou usuário — a configuração local prevalece. Isso permite sobrescrever definições de nível mais amplo sem criar conflito entre camadas.

Na prática, esse comportamento ajuda a adaptar um servidor para um repositório específico sem alterar o padrão compartilhado da equipe ou do perfil de usuário.

5.14 Correções recentes de ciclo de vida, v2.1.136

Essa versão corrigiu dois problemas importantes para ambientes com múltiplos servidores MCP:

• Persistência após /clear: servidores configurados via .mcp.json, plugins ou conectores do claude.ai deixaram de desaparecer após o comando /clear em VS Code, JetBrains e Agent SDK.
• Correção de refresh concorrente de OAuth: em setups com vários servidores OAuth, os refresh tokens deixaram de ser perdidos quando vários servidores tentavam renovar ao mesmo tempo.

Se você opera muitos MCPs ao mesmo tempo, essa atualização é importante para reduzir reconexões inesperadas e autenticações repetidas.

5.15 Recursos por referência com @

Você pode citar recursos MCP diretamente na conversa usando a sintaxe de menção com @. O formato é:

@server-name:protocol://resource/path

Exemplo:

@database:postgres://mydb/users

Isso permite trazer o conteúdo do recurso para dentro do contexto da conversa, o que é útil quando você quer trabalhar com uma fonte específica sem copiar manualmente os dados.

5.16 Escopos de configuração MCP

As configurações MCP podem ser salvas em níveis diferentes, com alcance e compartilhamento distintos. Entender isso evita sobrescritas involuntárias e confusão entre arquivos locais e de equipe.

5.16.1 Local, padrão atual

Fica em ~/.claude.json sob a raiz do projeto e é privado para o usuário atual naquele projeto. Em versões antigas, esse escopo era chamado de project.

5.16.2 Projeto

Fica no arquivo .mcp.json e é versionado no repositório. É o formato ideal para compartilhar conexões comuns com a equipe.

Ao usar esse escopo, os membros da equipe recebem um prompt de aprovação na primeira utilização do MCP do projeto. Em workspace não confiável, servidores que foram autoaprovados por meio de um .claude/settings.json comprometido no repositório não são iniciados automaticamente por claude mcp list ou claude mcp get. Eles aparecem como ⏸ Pending approval até que o diálogo de confiança seja aceito, e enableAllProjectMcpServers é ignorado dentro de uma pasta não confiável na v2.1.196.

5.16.3 Usuário

Fica em ~/.claude.json e vale para todos os projetos do usuário. Em versões antigas, esse escopo era chamado de global.

5.17 Gerenciamento de configuração MCP

O Claude Code oferece comandos específicos para administrar servidores, inspecionar configurações, remover entradas e sincronizar credenciais com o fluxo do terminal.

# Adicionar servidor HTTP
claude mcp add --transport http github https://api.github.com/mcp

# Adicionar servidor local stdio
claude mcp add --transport stdio database -- npx @company/db-server

# Listar servidores
claude mcp list

# Obter detalhes de um servidor
claude mcp get github

# Remover servidor
claude mcp remove github

# Resetar escolhas de aprovação do projeto
claude mcp reset-project-choices

# Fazer login em um servidor MCP, v2.1.186+
claude mcp login github

# Fazer logout de um servidor MCP, v2.1.186+
claude mcp logout github

# Importar do Claude Desktop
claude mcp add-from-claude-desktop

Os comandos claude mcp login <nome> e claude mcp logout <nome> são equivalentes não interativos ao fluxo OAuth do menu /mcp. Eles são úteis para automação, SSH e uso sem abrir interface interativa. Em login, o parâmetro --no-browser permite concluir OAuth em sessões headless, redirecionando o fluxo por stdin.

5.18 Tabela de servidores MCP comuns

A tabela abaixo resume usos frequentes. Ela não substitui a configuração real do servidor, mas ajuda a escolher a integração adequada para cada problema.

• Filesystem: operações de arquivo, com leitura, escrita e remoção; autenticação baseada em permissões do sistema.
• GitHub: gerenciamento de repositórios, PRs e issues; autenticação via OAuth.
• Slack: comunicação de equipe; autenticação por token.
• Database: consultas SQL e mutações; autenticação por credenciais.
• Google Docs: leitura, escrita e compartilhamento de documentos; autenticação via OAuth.
• Asana: tarefas e status de projeto; autenticação por API key.
• Stripe: dados financeiros e cobrança; autenticação por API key.
• Memory: memória persistente para preferências e histórico; não é fonte de dados vivos.

5.19 Exemplo prático: configuração do GitHub MCP

O GitHub é um dos usos mais comuns de MCP porque envolve informação viva: pull requests, issues, commits e metadados do repositório. A configuração abaixo mostra um servidor baseado em npx, com token exposto por variável de ambiente.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

5.19.1 Ferramentas típicas do GitHub MCP

• list_prs: lista pull requests do repositório.
• get_pr: traz detalhes de um PR, inclusive diff.
• create_pr: cria um novo PR.
• update_pr: altera título ou descrição de um PR.
• merge_pr: faz merge para a branch principal.
• review_pr: adiciona comentários de review.
• list_issues: lista issues.
• get_issue: mostra detalhes de uma issue.
• create_issue: cria uma issue.
• close_issue: fecha uma issue.
• add_comment: comenta em uma issue.
• get_repo_info: dados gerais do repositório.
• list_files: árvore de arquivos.
• get_file_content: lê o conteúdo de um arquivo.
• search_code: pesquisa no código.
• list_commits: histórico de commits.
• get_commit: detalhes de um commit.
• create_commit: cria um commit.

Exemplo de uso em sessão:

/mcp__github__get_pr 456

Retorno esperado:
Título: Adicionar suporte ao modo escuro
Autor: @alice
Descrição: Implementa tema escuro usando variáveis CSS
Status: OPEN
Revisores: @bob, @charlie

Para instalar e testar, você pode exportar o token no ambiente ou usar o CLI para registrar o servidor:

export GITHUB_TOKEN="your_github_token"
claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github

5.20 Expansão de variáveis de ambiente na configuração

As configurações MCP aceitam expansão de variáveis em campos como command, args, env, url e headers. Isso permite criar arquivos portáveis e evitar credenciais hardcoded.

Há dois formatos principais:

• ${VAR}: usa a variável; se ela não existir, gera erro.
• ${VAR:-default}: usa a variável, mas cai no valor padrão se ela não estiver definida.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}",
        "X-Custom-Header": "${CUSTOM_HEADER:-default-value}"
      }
    },
    "local-server": {
      "command": "${MCP_BIN_PATH:-npx}",
      "args": ["${MCP_PACKAGE:-@company/mcp-server}"],
      "env": {
        "DB_URL": "${DATABASE_URL:-postgresql://localhost/dev}"
      }
    }
  }
}

5.21 Exemplo prático: Database MCP

Servidores de banco são ideais para consultas vivas, relatórios e automações operacionais. A configuração abaixo usa npx com uma URL PostgreSQL exposta por variável de ambiente.

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-database"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
      }
    }
  }
}

Exemplo de uso: pedir que o Claude encontre usuários com mais de 10 pedidos. O servidor executa a consulta e devolve o conjunto de resultados já interpretado.

User: Busque todos os usuários com mais de 10 pedidos

Claude: Vou consultar seu banco para localizar essa informação.

SELECT u.*, COUNT(o.id) as order_count
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.id
HAVING COUNT(o.id) > 10
ORDER BY order_count DESC;

Resultado:
- Alice: 15 pedidos
- Bob: 12 pedidos
- Charlie: 11 pedidos

Para configurar localmente:

export DATABASE_URL="postgresql://user:pass@localhost/mydb"
claude mcp add --transport stdio database -- npx @modelcontextprotocol/server-database

5.22 Exemplo prático: Filesystem MCP

O Filesystem MCP é útil quando o Claude precisa inspecionar, criar, editar ou remover arquivos do projeto. É uma integração muito comum em automações de desenvolvimento e manutenção de documentação.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

5.22.1 Operações mais comuns

• Listar arquivos: equivalente a ls ~/projects.
• Ler arquivo: equivalente a cat src/main.ts.
• Escrever arquivo: cria um novo documento, como create docs/api.md.
• Editar arquivo: altera conteúdo existente, como edit src/app.ts.
• Pesquisar: busca por padrões, como grep "async function".
• Excluir arquivo: remove arquivos, como rm old-file.js.

Para registrar o servidor via CLI:

claude mcp add --transport stdio filesystem -- npx @modelcontextprotocol/server-filesystem /home/user/projects

5.23 Exemplo multi-MCP: fluxo diário de relatórios

Um uso realista de MCP é combinar vários servidores em um workflow único. Por exemplo, você pode coletar métricas do GitHub, consultar vendas no banco, salvar o relatório em arquivo e publicar um resumo no Slack.

1. GitHub MCP para buscar métricas de PR.
2. Database MCP para consultar dados de vendas.
3. Filesystem MCP para salvar o arquivo do relatório.
4. Slack MCP para postar o resumo no canal.

# Fluxo de relatório diário com múltiplos MCPs

## Etapa 1: buscar dados do GitHub
/mcp__github__list_prs completed:true last:7days

Saída:
- Total de PRs: 42
- Tempo médio de merge: 2,3 horas
- Tempo de revisão: 1,1 hora

## Etapa 2: consultar banco
SELECT COUNT(*) as sales, SUM(amount) as revenue
FROM orders
WHERE created_at > NOW() - INTERVAL '1 day'

Saída:
- Vendas: 247
- Receita: $12.450

## Etapa 3: gerar relatório
Combinar os dados em um relatório HTML

## Etapa 4: salvar no filesystem
Gravar report.html em /reports/

## Etapa 5: publicar no Slack
Enviar resumo para o canal #daily-reports

Resultado final:
✅ Relatório gerado e publicado
📊 47 PRs mesclados esta semana
💰 $12.450 em vendas diárias

export GITHUB_TOKEN="your_github_token"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_TOKEN="your_slack_token"

5.24 MCP versus Memory: quando usar cada um

A decisão correta depende do tipo de dado. Se a informação precisa ser atual, consultada de uma fonte externa ou refletir o estado do momento, use MCP. Se o dado for persistente, pessoal e estável, use Memory.

• Use Memory para preferências do usuário, histórico de conversa e contexto aprendido.
• Use MCP para issues atuais, consultas ao banco e dados em tempo real.

Uma forma prática de pensar é esta:

• O dado muda com frequência? MCP.
• O dado precisa ser lembrado entre sessões sem depender de uma fonte externa? Memory.
• Você quer executar ações em um sistema real? MCP.

5.25 Servidor MCP do próprio Claude

O próprio Claude Code pode atuar como servidor MCP para outras aplicações. Esse modo é acionado com claude mcp serve e expõe a capacidade do Claude para ferramentas externas, editores e automações que falem o protocolo.

# Iniciar o Claude Code como servidor MCP via stdio
claude mcp serve

Você também pode conectar outra instância do Claude Code a esse servidor, criando uma arquitetura em que um agente orquestra outro.

claude mcp add --transport stdio claude-agent -- claude mcp serve

5.26 Configuração MCP gerenciada para empresas

Em ambientes corporativos, administradores podem impor políticas de MCP usando o arquivo managed-mcp.json. Esse arquivo tem precedência organizacional e serve para permitir ou bloquear servidores em toda a empresa.

5.26.1 Locais do arquivo

• macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
• Linux: ~/.config/ClaudeCode/managed-mcp.json
• Windows: %APPDATA%\ClaudeCode\managed-mcp.json

5.26.2 Recursos disponíveis

• allowedMcpServers: lista de servidores permitidos.
• deniedMcpServers: lista de servidores proibidos.
• allowAllClaudeAiMcps: permite conectar conectores do claude.ai em escala corporativa, disponível a partir da v2.1.149.
• Compatibilidade com filtro por nome do servidor, comando e padrões de URL.
• Aplicação antes das configurações do usuário.
• Bloqueio de conexões não autorizadas.

{
  "allowedMcpServers": [
    {
      "serverName": "github",
      "serverUrl": "https://api.github.com/mcp"
    },
    {
      "serverName": "company-internal",
      "serverCommand": "company-mcp-server"
    }
  ],
  "deniedMcpServers": [
    {
      "serverName": "untrusted-*"
    },
    {
      "serverUrl": "http://*"
    }
  ]
}

Quando uma regra de permissão e uma de negação combinam com o mesmo servidor, a regra de negação vence.

5.27 Servidores MCP fornecidos por plugins

Plugins podem embutir seus próprios servidores MCP e disponibilizá-los automaticamente ao serem instalados. Há duas formas de fazer isso:

• colocar um arquivo .mcp.json na raiz do plugin;
• definir os servidores diretamente no manifesto plugin.json.

Para referenciar caminhos relativos à instalação do plugin, use ${CLAUDE_PLUGIN_ROOT}.

{
  "mcpServers": {
    "plugin-tools": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp-server.js"],
      "env": {
        "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config.json"
      }
    }
  }
}

5.28 MCP com escopo de subagent

É possível definir servidores MCP diretamente no frontmatter de um agente, usando a chave mcpServers:. Isso limita a disponibilidade da integração ao contexto daquele subagent específico, sem expor a mesma ferramenta ao agente pai ou a agentes irmãos.

---
mcpServers:
  my-tool:
    type: http
    url: https://my-tool.example.com/mcp
---

Você é um agente com acesso ao my-tool para operações especializadas.

Esse padrão é útil quando um fluxo tem papéis diferentes e somente um dos agentes precisa de acesso a um sistema sensível ou especializado.

5.29 Limites de saída dos MCPs

O Claude Code impõe limites para evitar que saídas muito grandes tomem toda a janela de contexto.

• Aviso: a partir de 10.000 tokens, o sistema alerta que a saída é grande.
• Limite padrão: 25.000 tokens; acima disso, a resposta é truncada.
• Persistência em disco: resultados com mais de 50.000 caracteres podem ser salvos em disco.

O limite máximo pode ser ajustado pela variável MAX_MCP_OUTPUT_TOKENS.

# Aumentar o máximo para 50.000 tokens
export MAX_MCP_OUTPUT_TOKENS=50000

5.30 Configuração dos arquivos de exemplo

Os arquivos de exemplo abaixo representam configurações mínimas úteis para começar rapidamente com cada tipo de servidor. Eles seguem o mesmo contrato de mcpServers, com variações em comando, argumentos e variáveis de ambiente.

5.30.1 github-mcp.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

5.30.2 database-mcp.json

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-database"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
      }
    }
  }
}

5.30.3 filesystem-mcp.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

5.30.4 multi-mcp.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-database"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_TOKEN": "${SLACK_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

5.31 Boas práticas de segurança

Segurança em MCP não é detalhe: os servidores têm acesso real a dados e sistemas. Por isso, vale tratar cada integração como uma superfície de risco que precisa de controle.

5.31.1 Faça

• Armazene credenciais em variáveis de ambiente.
• Gire tokens e chaves com regularidade; mensalmente é uma boa referência.
• Prefira tokens somente leitura quando possível.
• Conceda apenas o escopo mínimo necessário.
• Monitore uso e registros de acesso.
• Use OAuth sempre que disponível.
• Implemente limitação de taxa para requisições.
• Teste as conexões antes de colocar em produção.
• Documente todas as conexões ativas.
• Mantenha pacotes de servidores atualizados.

5.31.2 Não faça

• Não coloque credenciais diretamente nos arquivos de configuração.
• Não comite segredos no git.
• Não compartilhe tokens em chats ou e-mails.
• Não use tokens pessoais em projetos de equipe.
• Não conceda permissões desnecessárias.
• Não ignore falhas de autenticação.
• Não exponha endpoints MCP publicamente sem proteção.
• Não execute servidores com privilégios de root ou administrador.
• Não grave dados sensíveis em logs.
• Não desative mecanismos de autenticação.

5.32 Boas práticas de configuração e performance

1. Mantenha .mcp.json versionado, mas use variáveis de ambiente para segredos.
2. Use o princípio do menor privilégio para cada servidor.
3. Rode servidores diferentes em processos separados sempre que possível.
4. Registre requisições e erros para auditoria.
5. Teste toda mudança antes de levar para produção.

• Faça cache de dados frequentes na camada da aplicação, e não no MCP.
• Use consultas específicas para transferir menos dados.
• Monitore latência e tempo de resposta das operações.
• Considere rate limiting para APIs externas.
• Agrupe operações quando fizer várias ações seguidas.

5.33 Instalação e primeiros passos

Antes de começar, você precisa do Node.js, do npm, do Claude Code CLI e dos tokens/credenciais dos serviços externos que pretende integrar.

1. Adicione o primeiro servidor MCP pela CLI, por exemplo o GitHub:

claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github

Ou crie um arquivo .mcp.json na raiz do projeto:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

2. Defina as variáveis de ambiente necessárias.

export GITHUB_TOKEN="your_github_personal_access_token"

3. Teste a conexão.

claude /mcp

4. Use as ferramentas MCP.

/mcp__github__list_prs
/mcp__github__create_issue "Title" "Description"

5.34 Instalação por serviço

Alguns pacotes MCP podem ser instalados globalmente via npm, dependendo da estratégia do seu ambiente.

npm install -g @modelcontextprotocol/server-github
npm install -g @modelcontextprotocol/server-database
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-slack

5.35 Troubleshooting

Quando algo falha, o diagnóstico costuma seguir um padrão: verificar se o servidor existe, confirmar autenticação, checar rede e observar logs.

5.35.1 Servidor MCP não encontrado

# Verifique se o pacote está instalado
npm list -g @modelcontextprotocol/server-github

# Instale se estiver ausente
npm install -g @modelcontextprotocol/server-github

5.35.2 Falha de autenticação

# Confirme a variável de ambiente
echo $GITHUB_TOKEN

# Reexporte se necessário
export GITHUB_TOKEN="your_token"

# Verifique os escopos do token
# GitHub: https://github.com/settings/tokens

5.35.3 Timeout de conexão

• Verifique a conectividade de rede com ping api.github.com.
• Confirme se o endpoint da API responde.
• Veja se há limites de requisição sendo atingidos.
• Aumente o timeout na configuração, se o servidor suportar isso.
• Verifique firewall e proxy.

5.35.4 Crashes do servidor

• Consulte os logs em ~/.claude/logs/.
• Confirme se todas as variáveis de ambiente estão definidas.
• Verifique permissões de arquivo.
• Reinstale o pacote do servidor MCP.
• Cheque se há conflito de porta ou processos concorrentes.

5.36 Redução de contexto em escala e execução de código

Quando você conecta dezenas de servidores e centenas ou milhares de ferramentas, aparece o maior problema de MCP em escala: o inchaço de contexto. O custo não está só nas ferramentas em si, mas também nas definições carregadas e nos resultados intermediários que atravessam o modelo.

Uma proposta de solução é usar execução de código como camada intermediária. Em vez de jogar todas as definições e resultados no contexto, o agente escreve código que chama as ferramentas como APIs. O código roda em um ambiente sandbox e apenas o resultado final retorna ao modelo.

5.36.1 Os dois desperdícios de tokens mais comuns

• Definições de ferramentas: carregar tudo antecipadamente pode consumir centenas de milhares de tokens antes mesmo da pergunta do usuário.
• Resultados intermediários: quando um dado passa por várias ferramentas, ele pode atravessar o contexto mais de uma vez. Um transcript longo, por exemplo, pode ser lido e depois reenviado para outro sistema, multiplicando tokens desnecessários.

5.36.2 Como a solução funciona

Em vez de consumir o conteúdo completo no contexto, a execução de código organiza as chamadas em arquivos tipados, com wrappers para cada ferramenta e chamadas diretas ao servidor MCP. O modelo observa a intenção e o resultado final, não o caminho bruto inteiro.

// ./servers/google-drive/getDocument.ts
import { callMCPTool } from "../../../client.js";

interface GetDocumentInput {
  documentId: string;
}

interface GetDocumentResponse {
  content: string;
}

export async function getDocument(
  input: GetDocumentInput
): Promise<GetDocumentResponse> {
  return callMCPTool<GetDocumentResponse>(
    'google_drive__get_document', input
  );
}

import * as gdrive from './servers/google-drive';
import * as salesforce from './servers/salesforce';

const transcript = (
  await gdrive.getDocument({ documentId: 'abc123' })
).content;

await salesforce.updateRecord({
  objectType: 'SalesMeeting',
  recordId: '00Q5f000001abcXYZ',
  data: { Notes: transcript }
});

O ganho pode ser enorme: de algo próximo a 150.000 tokens para cerca de 2.000 tokens, uma redução aproximada de 98,7% em casos favoráveis.

5.36.3 Benefícios principais

• Descoberta progressiva: o agente carrega só o que precisa.
• Resultados mais eficientes: filtros e transformações acontecem fora do contexto do modelo.
• Fluxo de controle real: loops, condicionais e tratamento de erro rodam no código.
• Privacidade: dados intermediários sensíveis não entram no contexto do modelo.
• Persistência: o agente pode salvar arquivos e reaproveitar funções.

5.36.4 Exemplo de filtragem de grandes conjuntos

// Sem execução de código: todas as 10.000 linhas entram no contexto
// TOOL CALL: gdrive.getSheet(sheetId: 'abc123')
//   - retorna 10.000 linhas no contexto

// Com execução de código: filtra no ambiente de execução
const allRows = await gdrive.getSheet({ sheetId: 'abc123' });
const pendingOrders = allRows.filter(
  row => row["Status"] === 'pending'
);
console.log(`Encontrados ${pendingOrders.length} pedidos pendentes`);
console.log(pendingOrders.slice(0, 5));

5.36.5 Exemplo de loop sem ida e volta ao modelo

let found = false;
while (!found) {
  const messages = await slack.getChannelHistory({
    channel: 'C123456'
  });
  found = messages.some(
    m => m.text.includes('deployment complete')
  );
  if (!found) await new Promise(r => setTimeout(r, 5000));
}
console.log('Notificação de deploy recebida');

5.36.6 Trade-offs dessa abordagem

• Exige um ambiente de execução seguro, com limites de recursos.
• Precisa de monitoramento e logs do código executado.
• Impõe mais infraestrutura do que chamadas diretas de ferramenta.

Para alguns casos, especialmente com poucos servidores, chamadas diretas continuam mais simples. Para setups grandes, a execução de código tende a ser uma evolução importante.

5.37 MCPorter como runtime de composição

MCPorter é um runtime em TypeScript e uma ferramenta de linha de comando que facilita chamar servidores MCP sem boilerplate. Ele também ajuda a reduzir contexto expondo só as ferramentas necessárias e criando wrappers tipados.

O objetivo é evitar carregar definições de ferramentas em massa. Em vez disso, você descobre, inspeciona e chama ferramentas específicas sob demanda.

5.37.1 Recursos relevantes

• Descoberta sem configuração: localiza servidores em Cursor, Claude, Codex ou configs locais.
• Clientes tipados: mcporter emit-ts gera interfaces .d.ts e wrappers prontos.
• API composável: createServerProxy() expõe métodos em camelCase com auxiliares .text(), .json() e .markdown().
• Geração de CLI: mcporter generate-cli converte um servidor em uma CLI com filtros --include-tools e --exclude-tools.
• Ocultação de parâmetros: parâmetros opcionais ficam ocultos por padrão, reduzindo verbosidade do esquema.

5.37.2 Instalação e uso

npx mcporter list
pnpm add mcporter
brew install steipete/tap/mcporter

import { createRuntime, createServerProxy } from "mcporter";

const runtime = await createRuntime();
const gdrive = createServerProxy(runtime, "google-drive");
const salesforce = createServerProxy(runtime, "salesforce");

const doc = await gdrive.getDocument({ documentId: "abc123" });
await salesforce.updateRecord({
  objectType: "SalesMeeting",
  recordId: "00Q5f000001abcXYZ",
  data: { Notes: doc.text() }
});

# Chamar uma ferramenta diretamente
npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'

# Listar servidores e ferramentas
npx mcporter list

O MCPorter complementa a estratégia de execução de código porque torna viável tratar ferramentas MCP como APIs tipadas e chamar só o que interessa, mantendo dados intermediários fora do contexto do modelo.

5.38 Recursos adicionais e referências operacionais

Para implementação, compatibilidade e manutenção, vale acompanhar a documentação oficial, a especificação do protocolo e o repositório de servidores disponíveis. Também é importante observar a versão do Claude Code e os recursos introduzidos em releases recentes, já que várias capacidades descritas aqui dependem de versões mínimas específicas.

• Documentação oficial do MCP.
• Especificação do protocolo MCP.
• Repositório oficial de servidores MCP.
• Referência da CLI do Claude Code.
• Documentação da API do Claude.
• Notas de versão para confirmar suporte a recursos como alwaysLoad, headersHelper, CLAUDE_PROJECT_DIR, /mcp com ferramentas contadas, e os comportamentos de timeout e reconexão.

6 Módulo — Hooks, eventos, políticas e automação

6.1 Hooks: automação orientada a eventos no Claude Code

Hooks são scripts automatizados que o Claude Code executa quando eventos específicos acontecem durante uma sessão. Eles servem para automatizar validações, aplicar políticas de permissão, enriquecer respostas, integrar serviços externos e acionar fluxos personalizados sem depender de intervenção manual a cada passo.

Na prática, um hook recebe um payload em JSON pela entrada padrão, toma uma decisão com base nesse contexto e devolve sua saída por código de saída e, quando aplicável, por JSON na saída padrão. Esse mecanismo permite combinar automações simples em shell com integrações mais sofisticadas, como webhooks HTTP, chamadas a ferramentas MCP, prompts avaliados por LLM e verificações executadas por subagentes.

6.1.1 Visão geral do funcionamento

Os hooks são acionados por eventos do ciclo de vida do Claude Code, como início de sessão, uso de ferramentas, submissão de prompt, término de resposta e mudanças de configuração. Eles podem ser usados para:

• validar comandos antes da execução;
• bloquear ações perigosas ou fora de política;
• formatar, inspecionar ou reescrever saídas de ferramentas;
• registrar telemetria e auditoria;
• reagir a eventos da interface e da sessão;
• executar verificações inteligentes com LLMs ou subagentes;
• integrar automações em plugins, skills, agentes e políticas gerenciadas.

Os tipos de hook suportados incluem command, http, mcp_tool, prompt e agent. Alguns recursos são estáveis; outros foram adicionados em versões recentes e devem ser tratados como dependentes de versão.

6.1.2 Onde os hooks são configurados

As configurações podem ser definidas em vários níveis, e isso importa porque há precedência, escopo e até imposições de política organizacional.

• ~/.claude/settings.json — configuração do usuário, válida para todos os projetos.
• .claude/settings.json — configuração do projeto, compartilhável e versionável.
• .claude/settings.local.json — configuração local do projeto, não versionada.
• Managed policy — políticas gerenciadas pela organização, aplicadas centralmente.
• plugins/hooks/hooks.json — hooks vinculados ao escopo de um plugin.
• Frontmatter de skill, agente ou comando — hooks associados ao ciclo de vida de um componente.

Na prática, isso permite aplicar automação em escopos diferentes: global, por projeto, por plugin ou por componente reutilizável.

6.1.3 Estrutura básica de configuração

Um conjunto de hooks é declarado dentro da chave hooks, indexado pelo nome do evento. Cada evento contém uma lista de handlers, e cada handler pode restringir a atuação com um matcher e executar uma ou mais ações em sequência.

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Campos principais:

• matcher: padrão que seleciona ferramentas ou agentes. Em geral, é case-sensitive.
• hooks: lista de definições de hook executadas para o handler.
• type: define o tipo do hook. Pode ser command, prompt, http, mcp_tool ou agent.
• command: comando de shell executado pelo hook do tipo command.
• timeout: tempo máximo de execução, em segundos. O padrão é 60.
• once: se verdadeiro, o hook roda apenas uma vez por sessão.

6.1.4 Padrões de matcher

O matcher decide qual ferramenta, agente ou item relacionado ao evento será atingido. Há diferentes formas de escrever esse padrão, e a escolha errada pode fazer o hook nunca disparar ou disparar mais vezes do que o desejado.

• String exata: casa com uma ferramenta específica, como "Write".
• Expressão regular: permite combinar múltiplas ferramentas, como "Edit|Write".
• Lista separada por vírgula (v2.1.191+): casa com qualquer ferramenta listada, como "Write,Edit".
• Coringa: casa com todas as ferramentas, como "*" ou "".
• Ferramentas MCP: segue o padrão de servidor e ferramenta, como mcp__memory__.*.

Há um comportamento importante nas versões recentes: a correspondência passou a ser exata a partir da v2.1.195+. Isso evita que nomes com hífen ou identificadores parecidos caiam por coincidência em outra ferramenta. Em versões anteriores, havia risco de substring match acidental. Também vale lembrar que matchers separados por vírgula, como "Write,Edit", só passaram a funcionar corretamente na linha atual de versões; em builds anteriores, esse formato podia simplesmente não acionar nada.

6.1.5 Valores de matcher para InstructionsLoaded

O evento InstructionsLoaded usa valores próprios de matcher, porque ele não seleciona ferramentas, mas sim a origem da instrução carregada.

• session_start: instruções carregadas no início da sessão.
• nested_traversal: instruções carregadas durante navegação recursiva de diretórios.
• path_glob_match: instruções carregadas por correspondência com glob de caminho.

6.1.6 Filtragem fina com if em caminhos e argumentos de ferramenta

O matcher escolhe qual ferramenta será observada. Já o campo if restringe qual chamada real vai disparar o handler com base nos argumentos recebidos. Isso é útil quando você quer monitorar Edit e Write, mas apenas em arquivos de um diretório específico, ou bloquear leituras de arquivos sensíveis sem afetar o restante do fluxo.

O if usa a mesma sintaxe de regras de permissão, no formato ToolName(pattern). Ele é avaliado sobre o nome da ferramenta e seus argumentos em conjunto. Para Read, Edit e Write, o padrão de caminho segue semântica gitignore, com os mesmos ancoradores das permissões:

• .env sem barra casa em qualquer profundidade abaixo do diretório atual;
• src/** é relativo ao diretório corrente;
• /src/** fixa a correspondência na raiz do projeto;
• ~/... aponta para o diretório home;
• //... usa caminho absoluto do sistema.

O campo if fica no nível de cada handler, ao lado de type e command, e não no matcher.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "if": "Edit(src/**)",
            "command": "./hooks/lint-src.sh"
          }
        ]
      },
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "if": "Read(.env)",
            "command": "./hooks/block-secret-read.sh"
          }
        ]
      }
    ]
  }
}

Exemplos válidos de if incluem Edit(src/**), Read(~/.ssh/**), Read(.env) e Bash(git push *). Esse recurso é especialmente útil em políticas de segurança e validações condicionais por caminho.

6.2 Tipos de hook

6.2.1 Hooks de comando

É o tipo padrão. Executa um comando de shell e se comunica por JSON via stdin/stdout, além de usar códigos de saída para indicar sucesso, bloqueio ou erro não bloqueante.

{
  "type": "command",
  "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate.py\"",
  "timeout": 60
}

6.2.2 Forma exec com args

Disponível desde v2.1.139. Em vez de passar um comando em string para o shell, o hook pode iniciar o binário diretamente via execve() usando um array args. Isso elimina parsing de shell e reduz risco de injeção de comandos. Também dispensa aspas em placeholders de caminho quando a chamada é direta.

{
  "type": "command",
  "args": ["python3", "$CLAUDE_PROJECT_DIR/.claude/hooks/validate.py", "--strict"],
  "timeout": 60
}

As duas formas são mutuamente exclusivas. Se você definir command e args no mesmo hook, a configuração será rejeitada no carregamento. Use command quando precisar de pipes, redirecionamentos, encadeamentos com && ou expansão de shell. Use args quando a chamada for para um único binário com argumentos estáticos.

6.2.3 Hooks HTTP

Disponíveis desde v2.1.63. São webhooks remotos que recebem o mesmo JSON dos hooks de comando. O Claude Code faz um POST para a URL configurada e espera uma resposta JSON. Quando o sandbox está ativado, as requisições passam por ele. Se a URL interpolar variáveis de ambiente, você precisa liberar explicitamente essas variáveis em allowedEnvVars, por segurança.

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "http",
        "url": "https://my-webhook.example.com/hook",
        "matcher": "Write"
      }
    ]
  }
}

Propriedades importantes:

• type: "http" identifica um hook HTTP;
• url aponta para o endpoint do webhook;
• a execução é roteada pelo sandbox quando ele está habilitado;
• interpolação de variáveis em URL exige allowedEnvVars explícito.

6.2.4 Hooks baseados em prompt

Esse tipo usa uma avaliação por LLM. O conteúdo do hook é um prompt que o próprio Claude avalia, o que é útil quando a decisão exige interpretação semântica e não apenas inspeção estrutural. O uso mais comum é em Stop e SubagentStop, para confirmar se uma tarefa realmente foi concluída.

{
  "type": "prompt",
  "prompt": "Evaluate if Claude completed all requested tasks.",
  "timeout": 30
}

O LLM retorna uma decisão estruturada, normalmente com decision, reason, continue e, quando aplicável, stopReason.

6.2.5 Hooks de ferramentas MCP

Disponíveis desde v2.1.118. O tipo mcp_tool invoca diretamente uma ferramenta MCP já configurada. Em vez de chamar shell ou URL, você informa o servidor MCP e o nome da ferramenta a executar. Isso é valioso quando a lógica de validação ou reação já vive em um servidor MCP existente.

{
  "matcher": "Edit",
  "hooks": [
    {
      "type": "mcp_tool",
      "server": "my-mcp-server",
      "tool": "validate_edit"
    }
  ]
}

Campos principais:

• server: nome do servidor MCP configurado;
• tool: ferramenta desse servidor a ser invocada.

O input do hook, incluindo nome da ferramenta, entrada da ferramenta e contexto da sessão, é repassado como argumentos da tool MCP. Para configurar os servidores, use o guia de MCP correspondente.

6.2.6 Hooks de agente

Hooks do tipo agent sobem um subagente dedicado para avaliar condições complexas ou executar verificações multi-etapa. Ao contrário dos hooks baseados em prompt, esse formato permite o uso de ferramentas como Read, Grep e Bash, dando mais capacidade de raciocínio e inspeção.

{
  "type": "agent",
  "prompt": "Verify the code changes follow our architecture guidelines. Check the relevant design docs and compare.",
  "timeout": 120
}

Esses hooks retornam uma decisão estruturada semelhante à dos hooks de prompt, mas com o diferencial de poderem consultar arquivos, documentação e executar passos intermediários.

6.3 Eventos de hook

O Claude Code suporta 30 eventos de hook. Cada um tem momento de disparo, argumento de matcher, capacidade de bloqueio e uso típico próprios.

• SessionStart: início, retomada, limpeza ou compactação de sessão; útil para preparar ambiente.
• Setup: preparação inicial única por sessão; indicado para instalar dependências ou provisionar ferramentas.
• InstructionsLoaded: após carregar CLAUDE.md ou arquivos de regras; útil para filtrar instruções.
• UserPromptSubmit: quando o usuário envia um prompt; pode bloquear o processamento.
• UserPromptExpansion: quando o prompt é expandido, com menções @ ou comandos de barra resolvidos; pode bloquear.
• PreToolUse: antes da execução de uma ferramenta; pode validar e até alterar entradas.
• PermissionRequest: quando o diálogo de permissão é exibido; pode aprovar ou negar.
• PermissionDenied: quando o usuário nega uma solicitação; não bloqueia, mas permite logging e políticas.
• PostToolUse: após sucesso da ferramenta; útil para verificações e feedback.
• PostToolUseFailure: quando a ferramenta falha; útil para logging e tratamento de erro.
• PostToolBatch: após um lote de usos de ferramentas; bom para relatórios agregados.
• Notification: quando uma notificação é enviada; útil para personalização.
• MessageDisplay: enquanto o texto da mensagem do assistente é exibido; pode transformar ou ocultar o texto exibido.
• SubagentStart: quando um subagente é iniciado; útil para setup específico.
• SubagentStop: quando um subagente termina; pode validar o resultado.
• Stop: quando Claude termina de responder; usado para checagem de conclusão.
• StopFailure: quando um erro de API encerra a vez; útil para recuperação e logging.
• TeammateIdle: quando um integrante da equipe de agentes fica ocioso; serve para coordenação.
• TaskCompleted: quando uma tarefa é marcada como concluída; bom para ações pós-tarefa.
• TaskCreated: quando uma tarefa é criada via TaskCreate; útil para rastreamento.
• ConfigChange: quando arquivos de configuração mudam; pode reagir a updates.
• CwdChanged: quando o diretório de trabalho muda; útil para setup por diretório.
• FileChanged: quando arquivos monitorados mudam; serve para rebuild ou monitoramento.
• PreCompact: antes da compactação de contexto, manual ou automática.
• PostCompact: depois da compactação ser concluída.
• WorktreeCreate: quando um worktree está sendo criado; pode retornar caminho e inicializar estrutura.
• WorktreeRemove: quando um worktree está sendo removido; útil para limpeza.
• Elicitation: quando um servidor MCP pede entrada do usuário; pode validar dados.
• ElicitationResult: quando o usuário responde à elicitação; pode processar a resposta.
• SessionEnd: fim da sessão; ideal para limpeza final e logs de encerramento.

Desde v2.1.119, os hooks PostToolUse e PostToolUseFailure também recebem duration_ms no input, representando o tempo gasto pela ferramenta. Esse valor exclui o tempo consumido em prompts de permissão e na execução de hooks PreToolUse.

6.3.1 PreToolUse

Esse evento roda depois que o Claude monta os parâmetros da ferramenta e antes do processamento efetivo. É o ponto certo para impedir comandos inseguros, corrigir parâmetros ou enriquecer a chamada antes que ela aconteça.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py"
          }
        ]
      }
    ]
  }
}

Matchers comuns incluem Task, Bash, Glob, Grep, Read, Edit, Write, WebFetch e WebSearch.

Esse tipo de hook pode devolver instruções de controle como:

• permissionDecision: allow, deny ou ask;
• permissionDecisionReason: explicação da decisão;
• updatedInput: parâmetros da ferramenta alterados.

6.3.2 PostToolUse

Esse evento roda imediatamente após a ferramenta terminar com sucesso. É apropriado para verificação, logging, análise de segurança e retorno de contexto para o Claude.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/security-scan.py"
          }
        ]
      }
    ]
  }
}

A saída pode usar:

• block: prompt para o Claude com feedback;
• additionalContext: contexto adicional inserido para o Claude.

6.3.3 Bloqueios recuperáveis com continueOnBlock (v2.1.139)

Por padrão, quando um hook PostToolUse retorna uma decisão de bloqueio, a rodada atual é abortada. Se você definir continueOnBlock: true, a rejeição é transformada em um tool_result, permitindo que o modelo leia o motivo e tente ajustar a ação. Isso é útil quando a justificativa é acionável, como “este arquivo é somente leitura; escreva em outro lugar”.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/policy-check.py",
            "continueOnBlock": true
          }
        ]
      }
    ]
  }
}

Use essa opção quando o bloqueio puder orientar um retry inteligente. Não a use quando a interrupção precisar ser definitiva.

6.3.4 UserPromptSubmit

Esse evento dispara quando o usuário envia um prompt, antes de Claude processá-lo. É adequado para aplicar política de conteúdo, bloquear solicitações perigosas e adicionar contexto antes do raciocínio.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-prompt.py"
          }
        ]
      }
    ]
  }
}

Os campos de saída aceitos incluem:

• decision: use block para impedir o processamento;
• reason: motivo do bloqueio;
• additionalContext: contexto acrescentado ao prompt.

6.3.5 Stop e SubagentStop

Esses eventos disparam quando Claude termina de responder ou quando um subagente conclui seu trabalho. São os pontos mais indicados para verificar se a tarefa foi realmente finalizada, se faltaram arquivos, se há erros em aberto ou se alguma validação de encerramento precisa acontecer.

Ambos recebem o campo last_assistant_message no JSON de entrada, contendo a mensagem final antes da parada. Isso facilita inspeções sem precisar reconstruir o fim da conversa.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude completed all requested tasks.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Há um limite de segurança para bloqueios consecutivos em hooks Stop desde v2.1.143. Se o hook retornar bloqueio oito vezes seguidas para a mesma rodada, o Claude Code encerra a sessão com aviso para evitar loop infinito. Esse limite pode ser ajustado com a variável CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=<integer>; defina 0 para desabilitar completamente a proteção.

Desde v2.1.163, um hook de Stop ou SubagentStop pode retornar hookSpecificOutput.additionalContext para orientar o Claude e continuar a rodada sem exibir rótulo de erro. Isso é mais limpo do que depender de bloqueios para “ensinar” o modelo.

{
  "hookSpecificOutput": {
    "hookEventName": "Stop",
    "additionalContext": "Reminder: run the test suite before declaring done."
  }
}

6.3.6 SubagentStart

Esse evento roda quando um subagente começa a executar. O matcher recebe o nome do tipo de agente, o que permite direcionar hooks para subagentes específicos.

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "code-review",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/subagent-init.sh"
          }
        ]
      }
    ]
  }
}

6.3.7 SessionStart

Roda quando a sessão inicia ou é retomada. É um bom lugar para preparar ambiente, registrar estado ou persistir variáveis de ambiente.

Os valores de matcher para esse evento são startup, resume, clear e compact.

Um recurso especial é a possibilidade de persistir variáveis via CLAUDE_ENV_FILE, também disponível em CwdChanged e FileChanged. O hook pode escrever exportações nesse arquivo para que fiquem disponíveis ao longo da sessão.

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=development' >> "$CLAUDE_ENV_FILE"
fi
exit 0

Desde v2.1.152, o SessionStart pode retornar JSON para recarregar skills e definir o título da sessão.

{
  "reloadSkills": true,
  "hookSpecificOutput": {
    "sessionTitle": "Payments migration"
  }
}

O campo top-level reloadSkills: true força uma nova varredura de skills na mesma sessão, o que é útil quando o hook acabou de instalar ou atualizar skills e você quer que elas fiquem disponíveis imediatamente. Já hookSpecificOutput.sessionTitle define o título exibido da sessão no startup e na retomada.

6.3.8 SessionEnd

Esse evento dispara no encerramento da sessão e é ideal para limpeza final, logs persistentes ou pequenos fluxos de revisão. Ele não pode bloquear a terminação da sessão.

Os valores possíveis do campo de razão incluem:

• clear: o usuário limpou a sessão;
• logout: o usuário saiu;
• prompt_input_exit: o usuário saiu pela entrada de prompt;
• other: qualquer outro motivo.

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh\""
          }
        ]
      }
    ]
  }
}

6.3.9 Evento Notification

O evento de notificação usa matchers atualizados para tipos específicos de notificação.

• permission_prompt: notificação de solicitação de permissão;
• idle_prompt: notificação de estado ocioso;
• auth_success: autenticação bem-sucedida;
• elicitation_dialog: diálogo mostrado ao usuário;
• agent_needs_input (v2.1.198): agente em segundo plano precisa de entrada;
• agent_completed (v2.1.198): agente em segundo plano concluiu.

6.4 Hooks com escopo de componente

Skills, agentes e comandos podem declarar hooks diretamente em seu frontmatter. Isso mantém a automação ao lado do componente que a usa, reduzindo dispersão de configuração.

Em SKILL.md, agent.md ou command.md, a estrutura pode ser declarada assim:

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/check.sh"
          once: true
---

Os eventos suportados para hooks de componente são PreToolUse, PostToolUse e Stop.

Em subagentes, há uma conversão automática importante: se você define um Stop no frontmatter do subagente, o Claude Code o transforma em SubagentStop com escopo daquele subagente específico. Isso garante que o hook só dispare quando aquele subagente terminar, e não quando a sessão principal encerrar.

---
name: code-review-agent
description: Automated code review subagent
hooks:
  Stop:
    - hooks:
        - type: prompt
          prompt: "Verify the code review is thorough and complete."
  # The above Stop hook auto-converts to SubagentStop for this subagent
---

6.5 PermissionRequest

Esse evento trata diálogos de permissão com um formato de saída próprio. Ele permite automatizar aprovações, recusas e mensagens personalizadas com controle mais fino que um simples allow/deny.

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow|deny",
      "updatedInput": {},
      "message": "Custom message",
      "interrupt": false
    }
  }
}

6.6 Entrada e saída dos hooks

6.6.1 JSON de entrada via stdin

Todos os hooks recebem um JSON pela entrada padrão. O payload contém informações da sessão, da ferramenta, do agente e, em alguns casos, do trabalho em andamento.

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/directory",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.js",
    "content": "..."
  },
  "tool_use_id": "toolu_01ABC123...",
  "agent_id": "agent-abc123",
  "agent_type": "main",
  "worktree": "/path/to/worktree",
  "effort": {
    "level": "medium"
  }
}

Campos comuns:

• session_id: identificador único da sessão;
• transcript_path: caminho do arquivo de transcript da conversa;
• cwd: diretório de trabalho atual;
• prompt_id (v2.1.196): UUID do prompt em processamento, correlacionável com prompt.id no OpenTelemetry;
• hook_event_name: nome do evento que acionou o hook;
• agent_id: identificador do agente que executa o hook;
• agent_type: tipo do agente, como main ou o nome de um subagente;
• worktree: caminho do worktree git, quando aplicável;
• effort.level (v2.1.133+): nível ativo de esforço, podendo ser low, medium, high, xhigh ou max.

6.6.2 Códigos de saída

O código de saída do processo define como o Claude Code interpreta o resultado.

• 0: sucesso; a saída JSON é lida e o fluxo continua.
• 2: erro bloqueante; a operação é bloqueada e o stderr é exibido como erro.
• outros: erro não bloqueante; o fluxo continua e o stderr aparece apenas em modo verboso.

6.6.3 JSON de saída via stdout

Quando o hook termina com código de saída 0, ele pode devolver um JSON com informações de controle e dados específicos do evento.

{
  "continue": true,
  "stopReason": "Optional message if stopping",
  "suppressOutput": false,
  "systemMessage": "Optional warning message",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "File is in allowed directory",
    "updatedInput": {
      "file_path": "/modified/path.js"
    }
  }
}

Desde v2.1.121+, hookSpecificOutput.updatedToolOutput passou a valer para todas as ferramentas, não apenas para MCP. Isso significa que um hook PostToolUse em Bash, Edit, Read e similares pode reescrever a saída antes que Claude a veja. É útil para redigir segredos, normalizar diffs ou limpar ruído de comando.

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "updatedToolOutput": "<plain-text output with ANSI escapes removed>"
  }
}

6.6.4 terminalSequence (v2.1.141)

Hooks podem emitir sequências OSC brutas definindo terminalSequence no JSON de saída. O host escreve a sequência diretamente no terminal de controle quando o hook termina. Isso é útil para notificações de desktop, atualização de título da janela e sinais sonoros no terminal, sem precisar de um TTY próprio.

{
  "terminalSequence": "]9;Task complete"
}

Um uso comum é colocar isso em um hook Stop para disparar notificação quando Claude concluir uma rodada. O suporte depende do terminal; Kitty, iTerm2 e Windows Terminal aceitam OSC 9.

6.7 Variáveis de ambiente

Há variáveis disponíveis para todos os hooks e outras específicas de alguns eventos ou contextos.

• CLAUDE_PROJECT_DIR: caminho absoluto da raiz do projeto, disponível em todos os hooks.
• CLAUDE_ENV_FILE: arquivo para persistir variáveis, disponível em SessionStart, CwdChanged e FileChanged.
• CLAUDE_CODE_REMOTE: retorna "true" quando o ambiente é remoto.
• ${CLAUDE_PLUGIN_ROOT}: caminho do diretório do plugin, nos hooks de plugin.
• ${CLAUDE_PLUGIN_DATA}: diretório de dados do plugin, nos hooks de plugin.
• CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS: timeout configurável em milissegundos para hooks de SessionEnd.
• CLAUDE_CODE_SESSION_ID (v2.1.132+): UUID da sessão para subprocessos Bash; corresponde ao session_id do input JSON.
• CLAUDE_EFFORT (v2.1.133+): nível de esforço ativo, com os mesmos valores de effort.level.
• CLAUDE_CODE_STOP_HOOK_BLOCK_CAP (v2.1.143+): máximo de bloqueios consecutivos em hooks Stop antes de encerrar a sessão com aviso.

6.8 Hooks baseados em prompt: avaliação por LLM

Nos eventos Stop e SubagentStop, você pode usar uma avaliação feita por LLM para decidir se a tarefa foi concluída e se a sessão deve continuar. Esse padrão é útil quando a conclusão não é puramente sintática e precisa de análise qualitativa.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Review if all tasks are complete. Return your decision.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

O esquema de resposta esperado inclui, em geral:

{
  "decision": "approve",
  "reason": "All tasks completed successfully",
  "continue": false,
  "stopReason": "Task complete"
}

6.9 Exemplos práticos

6.9.1 Exemplo 1: validador de Bash no PreToolUse

Esse hook bloqueia comandos perigosos antes da execução. É um exemplo clássico de política preventiva.

#!/usr/bin/env python3
import json
import sys
import re

BLOCKED_PATTERNS = [
    (r"\brm\s+-rf\s+/", "Blocking dangerous rm -rf / command"),
    (r"\bsudo\s+rm", "Blocking sudo rm command"),
]

def main():
    input_data = json.load(sys.stdin)

    tool_name = input_data.get("tool_name", "")
    if tool_name != "Bash":
        sys.exit(0)

    command = input_data.get("tool_input", {}).get("command", "")

    for pattern, message in BLOCKED_PATTERNS:
        if re.search(pattern, command):
            print(message, file=sys.stderr)
            sys.exit(2)

    sys.exit(0)

if __name__ == "__main__":
    main()

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py\""
          }
        ]
      }
    ]
  }
}

6.9.2 Exemplo 2: scanner de segurança no PostToolUse

Depois que arquivos são escritos ou editados, este hook procura padrões de segredos codificados diretamente no conteúdo e acrescenta contexto de segurança ao Claude.

#!/usr/bin/env python3
import json
import sys
import re

SECRET_PATTERNS = [
    (r"password\s*=\s*['\"][^'\"]+['\"]", "Potential hardcoded password"),
    (r"api[_-]?key\s*=\s*['\"][^'\"]+['\"]", "Potential hardcoded API key"),
]

def main():
    input_data = json.load(sys.stdin)

    tool_name = input_data.get("tool_name", "")
    if tool_name not in ["Write", "Edit"]:
        sys.exit(0)

    tool_input = input_data.get("tool_input", {})
    content = tool_input.get("content", "") or tool_input.get("new_string", "")
    file_path = tool_input.get("file_path", "")

    warnings = []
    for pattern, message in SECRET_PATTERNS:
        if re.search(pattern, content, re.IGNORECASE):
            warnings.append(message)

    if warnings:
        output = {
            "hookSpecificOutput": {
                "hookEventName": "PostToolUse",
                "additionalContext": f"Security warnings for {file_path}: " + "; ".join(warnings)
            }
        }
        print(json.dumps(output))

    sys.exit(0)

if __name__ == "__main__":
    main()

6.9.3 Exemplo 3: autoformatação de código

Esse hook executa formatadores conforme a extensão do arquivo escrito ou editado. Ele é um caso típico de automação pós-edição.

#!/bin/bash

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys, json; print(json.load(sys.stdin).get('tool_name', ''))")
FILE_PATH=$(echo "$INPUT" | python3 -c "import sys, json; print(json.load(sys.stdin).get('tool_input', {}).get('file_path', ''))")

if [ "$TOOL_NAME" != "Write" ] && [ "$TOOL_NAME" != "Edit" ]; then
    exit 0
fi

case "$FILE_PATH" in
    *.js|*.jsx|*.ts|*.tsx|*.json)
        command -v prettier >/dev/null && prettier --write "$FILE_PATH" 2>/dev/null
        ;;
    *.py)
        command -v black >/dev/null && black "$FILE_PATH" 2>/dev/null
        ;;
    *.go)
        command -v gofmt >/dev/null && gofmt -w "$FILE_PATH" 2>/dev/null
        ;;
esac

exit 0

6.9.4 Exemplo 4: validador de prompt no UserPromptSubmit

Esse hook bloqueia prompts perigosos antes que o Claude os processe. Ele é útil para impor política de uso ou evitar instruções destrutivas.

#!/usr/bin/env python3
import json
import sys
import re

BLOCKED_PATTERNS = [
    (r"delete\s+(all\s+)?database", "Dangerous: database deletion"),
    (r"rm\s+-rf\s+/", "Dangerous: root deletion"),
]

def main():
    input_data = json.load(sys.stdin)
    prompt = input_data.get("user_prompt", "") or input_data.get("prompt", "")

    for pattern, message in BLOCKED_PATTERNS:
        if re.search(pattern, prompt, re.IGNORECASE):
            output = {
                "decision": "block",
                "reason": f"Blocked: {message}"
            }
            print(json.dumps(output))
            sys.exit(0)

    sys.exit(0)

if __name__ == "__main__":
    main()

6.9.5 Exemplo 5: hook inteligente de Stop baseado em prompt

Esse exemplo pede ao LLM uma avaliação da conclusão da tarefa, verificando se tudo foi feito e se há pendências.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Review if Claude completed all requested tasks. Check: 1) Were all files created/modified? 2) Were there unresolved errors? If incomplete, explain what's missing.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

6.9.6 Exemplo 6: rastreador de consumo de contexto

Esse padrão usa dois eventos em conjunto: UserPromptSubmit como pré-mensagem e Stop como pós-resposta. O objetivo é estimar consumo de tokens por solicitação, salvando o estado por sessão em um arquivo temporário.

#!/usr/bin/env python3
"""
Context Usage Tracker - Tracks token consumption per request.

Uses UserPromptSubmit as "pre-message" hook and Stop as "post-response" hook
to calculate the delta in token usage for each request.

Token Counting Methods:
1. Character estimation (default): ~4 chars per token, no dependencies
2. tiktoken (optional): More accurate (~90-95%), requires: pip install tiktoken
"""
import json
import os
import sys
import tempfile

CONTEXT_LIMIT = 128000
USE_TIKTOKEN = False

def get_state_file(session_id: str) -> str:
    return os.path.join(tempfile.gettempdir(), f"claude-context-{session_id}.json")

def count_tokens(text: str) -> int:
    if USE_TIKTOKEN:
        try:
            import tiktoken
            enc = tiktoken.get_encoding("p50k_base")
            return len(enc.encode(text))
        except ImportError:
            pass
    return len(text) // 4

def read_transcript(transcript_path: str) -> str:
    if not transcript_path or not os.path.exists(transcript_path):
        return ""

    content = []
    with open(transcript_path, "r") as f:
        for line in f:
            try:
                entry = json.loads(line.strip())
                if "message" in entry:
                    msg = entry["message"]
                    if isinstance(msg.get("content"), str):
                        content.append(msg["content"])
                    elif isinstance(msg.get("content"), list):
                        for block in msg["content"]:
                            if isinstance(block, dict) and block.get("type") == "text":
                                content.append(block.get("text", ""))
            except json.JSONDecodeError:
                continue

    return "\n".join(content)

def handle_user_prompt_submit(data: dict) -> None:
    session_id = data.get("session_id", "unknown")
    transcript_path = data.get("transcript_path", "")

    transcript_content = read_transcript(transcript_path)
    current_tokens = count_tokens(transcript_content)

    state_file = get_state_file(session_id)
    with open(state_file, "w") as f:
        json.dump({"pre_tokens": current_tokens}, f)

def handle_stop(data: dict) -> None:
    session_id = data.get("session_id", "unknown")
    transcript_path = data.get("transcript_path", "")

    transcript_content = read_transcript(transcript_path)
    current_tokens = count_tokens(transcript_content)

    state_file = get_state_file(session_id)
    pre_tokens = 0
    if os.path.exists(state_file):
        try:
            with open(state_file, "r") as f:
                state = json.load(f)
                pre_tokens = state.get("pre_tokens", 0)
        except (json.JSONDecodeError, IOError):
            pass

    delta_tokens = current_tokens - pre_tokens
    remaining = CONTEXT_LIMIT - current_tokens
    percentage = (current_tokens / CONTEXT_LIMIT) * 100

    method = "tiktoken" if USE_TIKTOKEN else "estimated"
    print(f"Context ({method}): ~{current_tokens:,} tokens ({percentage:.1f}% used, ~{remaining:,} remaining)", file=sys.stderr)
    if delta_tokens > 0:
        print(f"This request: ~{delta_tokens:,} tokens", file=sys.stderr)

def main():
    data = json.load(sys.stdin)
    event = data.get("hook_event_name", "")

    if event == "UserPromptSubmit":
        handle_user_prompt_submit(data)
    elif event == "Stop":
        handle_stop(data)

    sys.exit(0)

if __name__ == "__main__":
    main()

Configuração do rastreador:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-tracker.py\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-tracker.py\""
          }
        ]
      }
    ]
  }
}

O fluxo é o seguinte:

1. UserPromptSubmit dispara antes do prompt ser processado e salva a contagem atual de tokens.
2. Stop dispara depois da resposta e calcula a diferença de tokens.
3. Cada sessão fica isolada por session_id no nome do arquivo temporário.

Os métodos de contagem têm características diferentes:

• estimativa por caracteres: cerca de 80% a 90% de precisão, sem dependências, muito rápida;
• tiktoken com p50k_base: cerca de 90% a 95% de precisão, requer pip install tiktoken.

Não existe tokenizer offline oficial da Anthropic. Os valores são aproximações. O transcript inclui prompts do usuário, respostas de Claude e saídas de ferramentas, mas não inclui prompts de sistema nem contexto interno.

6.9.7 Exemplo 7: semeadura de permissões para auto-mode

Esse script de setup único adiciona regras de permissão seguras ao ~/.claude/settings.json, reproduzindo uma base aproximada do auto-mode sem depender de hook. Ele pode ser executado várias vezes porque ignora regras já existentes.

# Preview what would be added
python3 09-advanced-features/setup-auto-mode-permissions.py --dry-run

# Apply
python3 09-advanced-features/setup-auto-mode-permissions.py

O que é incluído:

• ferramentas nativas como Read(*), Edit(*), Write(*), Glob(*), Grep(*), Agent(*) e WebSearch(*);
• comandos de leitura do Git, como Bash(git status:*), Bash(git log:*) e Bash(git diff:*);
• operações locais de escrita do Git, como Bash(git add:*), Bash(git commit:*) e Bash(git checkout:*);
• gerenciadores de pacotes, como Bash(npm install:*), Bash(pip install:*) e Bash(cargo build:*);
• build e teste, como Bash(make:*), Bash(pytest:*) e Bash(go test:*);
• comandos comuns de shell, como Bash(ls:*), Bash(cat:*), Bash(find:*), Bash(cp:*) e Bash(mv:*);
• GitHub CLI, como Bash(gh pr view:*), Bash(gh pr create:*) e Bash(gh issue list:*).

O script exclui intencionalmente ações destrutivas ou de alto risco, como rm -rf, sudo, force push, git reset --hard, DROP TABLE, kubectl delete, terraform destroy, npm publish, curl | bash e deploys em produção.

6.9.8 Exemplo 8: registrador de progresso ao final da sessão

Esse exemplo mostra um SessionEnd que pergunta, ao terminar a sessão, quais módulos foram estudados e grava um histórico fora do repositório. A vantagem de salvar em ~/.claude-howto-progress.json é que o dado sobrevive a git pull e não é sobrescrito por atualizações do projeto.

Ele usa SessionEnd em vez de Stop porque Stop roda depois de cada resposta, enquanto SessionEnd dispara apenas uma vez, no encerramento da sessão. A leitura interativa é feita com /dev/tty porque o stdin do hook já está ocupado com o JSON do evento.

#!/usr/bin/env bash
PROGRESS_FILE="$HOME/.claude-howto-progress.json"

if [[ "$CLAUDE_PROJECT_DIR" != *"claude-howto"* ]] && [[ "$PWD" != *"claude-howto"* ]]; then
  exit 0
fi

if [ ! -f "$PROGRESS_FILE" ]; then
  echo '{"sessions":[]}' > "$PROGRESS_FILE"
fi

DATE=$(date +"%Y-%m-%d")
TIME=$(date +"%H:%M")

echo ""
echo " Which modules did you work on? (e.g. 06,07 or press Enter to skip)"
echo " 01=Slash  02=Memory  03=Skills  04=Subagents  05=MCP"
echo " 06=Hooks  07=Plugins 08=Checkpoints 09=Advanced 10=CLI"
printf " > "
read -r INPUT </dev/tty

if [ -z "$INPUT" ] || [ "$INPUT" = "skip" ]; then
  exit 0
fi

MODULES_JSON=$(echo "$INPUT" | tr ',' '\n' | tr -d ' ' | while read -r m; do
  case "$m" in
    01) echo '"01-slash-commands"' ;;
    02) echo '"02-memory"' ;;
    03) echo '"03-skills"' ;;
    04) echo '"04-subagents"' ;;
    05) echo '"05-mcp"' ;;
    06) echo '"06-hooks"' ;;
    07) echo '"07-plugins"' ;;
    08) echo '"08-checkpoints"' ;;
    09) echo '"09-advanced-features"' ;;
    10) echo '"10-cli"' ;;
    *)  echo "\"$m\"" ;;
  esac
done | paste -sd ',' -)

printf " Notes? (optional, press Enter to skip): "
read -r NOTES </dev/tty

python3 - "$PROGRESS_FILE" "$DATE" "$TIME" "$MODULES_JSON" "$NOTES" <<'PYEOF'
import sys, json

path, date, time_str, modules_raw, notes = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4], sys.argv[5]

new_session = {
    "date": date,
    "time": time_str,
    "modules": json.loads(f"[{modules_raw}]") if modules_raw else [],
    "notes": notes,
}

with open(path, 'r') as f:
    data = json.load(f)

data.setdefault('sessions', []).append(new_session)

with open(path, 'w') as f:
    json.dump(data, f, indent=2)
PYEOF

echo " Saved to $PROGRESS_FILE"

Instalação do script no projeto:

mkdir -p .claude/hooks
cp 06-hooks/session-end.sh .claude/hooks/
chmod +x .claude/hooks/session-end.sh

Configuração correspondente:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-end.sh\""
          }
        ]
      }
    ]
  }
}

O arquivo de saída gravado no home pode ficar assim:

{
  "sessions": [
    {
      "date": "2026-04-18",
      "time": "14:32",
      "modules": ["06-hooks", "07-plugins"],
      "notes": "Installed first hook, tried pre-commit example"
    }
  ]
}

Padrões importantes mostrados nesse exemplo:

• SessionEnd roda uma vez só, no final, e não a cada resposta;
• read -r INPUT </dev/tty é necessário porque o stdin pertence ao hook JSON;
• $CLAUDE_PROJECT_DIR evita caminhos fixos e melhora portabilidade;
• um guard no início impede execução fora do projeto correto;
• salvar em ~/ mantém o progresso mesmo após git pull.

6.10 Hooks de plugin

Plugins também podem incluir hooks no arquivo hooks/hooks.json. Isso permite embalar validações e automações junto com a extensão, mantendo a lógica distribuída e reaproveitável.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  }
}

As variáveis de ambiente específicas de plugin são:

• ${CLAUDE_PLUGIN_ROOT}: caminho do diretório do plugin;
• ${CLAUDE_PLUGIN_DATA}: diretório de dados do plugin.

6.11 Hooks de ferramentas MCP

Ferramentas MCP seguem o padrão mcp__<server>__<tool>. Esse formato permite criar matchers específicos para ferramentas expostas por um servidor MCP.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"systemMessage\": \"Memory operation logged\"}'"
          }
        ]
      }
    ]
  }
}

6.12 Considerações de segurança

6.12.1 Aviso importante

Hooks executam comandos arbitrários. Portanto, o risco técnico é real: você é responsável pelos comandos configurados, pelos caminhos acessados, pelas permissões de modificação e por qualquer perda de dados ou dano ao sistema. Sempre teste em ambiente seguro antes de levar para produção.

6.12.2 Notas de segurança relevantes

• Workspace trust obrigatório: comandos de saída de hooks como statusLine e fileSuggestion precisam de aceitação explícita de trust do workspace antes de surtirem efeito.
• Tamanho do terminal na status line (v2.1.153): scripts de status line recebem COLUMNS e LINES, permitindo adaptar a saída ao tamanho do terminal.
• Variáveis de ambiente em HTTP hooks: URLs com interpolação precisam de allowedEnvVars explícito para evitar vazamento de dados sensíveis.
• Hierarquia de settings gerenciados: disableAllHooks respeita a hierarquia gerenciada, então a organização pode impor desativação que o usuário não consegue reverter.
• Auto-approve para PowerShell (v2.1.119): comandos do PowerShell podem ser aprovados automaticamente em modo de permissão, em paridade com Bash.
• Fechamento do auto-approve para variável solta em Bash (v2.1.145): comandos do tipo FOO=bar somecommand deixaram de ser aprovados automaticamente quando apenas a atribuição isolada estava permitida. Agora a regra precisa cobrir o comando completo.

6.12.3 Boas práticas

• valide e higienize toda entrada recebida pelo hook;
• coloque variáveis de shell entre aspas, como "$VAR";
• bloqueie path traversal com ..;
• use caminhos absolutos baseados em $CLAUDE_PROJECT_DIR;
• ignore arquivos sensíveis como .env, .git/ e chaves;
• teste hooks isoladamente antes de implantar;
• em hooks HTTP, libere explicitamente apenas as variáveis necessárias.

6.13 Depuração e teste

6.13.1 Ativar modo debug

Para obter logs detalhados dos hooks, inicie o Claude com a flag de depuração.

claude --debug

6.13.2 Modo verboso

No Claude Code, Ctrl+O ativa modo verboso e mostra progresso de execução dos hooks.

6.13.3 Testar hooks fora do Claude Code

Uma boa prática é testar o script diretamente com um JSON de exemplo. Isso facilita corrigir parsing, saída e lógica de bloqueio antes de integrar ao fluxo real.

# Test with sample JSON input
echo '{"tool_name": "Bash", "tool_input": {"command": "ls -la"}}' | python3 .claude/hooks/validate-bash.py

# Check exit code
echo $?

6.14 Detalhes de execução

O comportamento operacional dos hooks inclui algumas regras importantes:

• Timeout: padrão de 60 segundos, configurável por hook.
• Paralelização: todos os hooks que casarem com o evento rodam em paralelo.
• Deduplicação: comandos idênticos são deduplicados.
• Ambiente: o hook executa no diretório atual, com o ambiente do Claude Code.

6.15 Problemas comuns e troubleshooting

6.15.1 Hook não executa

• verifique se o JSON de configuração está sintaticamente correto;
• confirme se o matcher realmente casa com o nome da ferramenta ou evento;
• assegure que o script existe e está executável com chmod +x;
• use claude --debug para ver logs de execução;
• lembre-se de que o hook precisa ler JSON do stdin, não de argumentos.

6.15.2 Hook bloqueia quando não deveria

• teste com JSON realista no terminal antes de conectar ao fluxo;
• confira o código de saída: 0 deve permitir, 2 deve bloquear;
• verifique o conteúdo do stderr, que é exibido como erro quando o retorno é bloqueante.

6.15.3 Erros de parsing JSON

• leia sempre de stdin, não de linha de comando;
• use um parser JSON adequado, não manipulação de string;
• trate campos ausentes com segurança.

6.16 Instalação

6.16.1 Passo 1: criar o diretório de hooks

mkdir -p ~/.claude/hooks

6.16.2 Passo 2: copiar hooks de exemplo

cp 06-hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

6.16.3 Passo 3: configurar no arquivo de settings

Edite ~/.claude/settings.json ou .claude/settings.json com a configuração apropriada ao seu caso de uso.

6.17 Conceitos relacionados

• Checkpoints e rewind: salvar e restaurar estado da conversa.
• Slash commands: criar comandos personalizados.
• Skills: capacidades autônomas reutilizáveis.
• Subagents: execução delegada de tarefas.
• Plugins: pacotes de extensão.
• Advanced Features: recursos avançados do Claude Code.

6.18 Recursos adicionais

• Documentação oficial de hooks: referência completa de hooks.
• CLI Reference: documentação da interface de linha de comando.
• Guia de memória: configuração de contexto persistente.

Versão de referência do material: Claude Code 2.1.206, com compatibilidade informada para Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8 e Claude Haiku 4.5.

6.19 Hooks, eventos, políticas e automação

6.19.1 Tracker de contexto por sessão e por requisição

Os dois scripts de context-tracker servem para medir, de forma aproximada, quanto contexto foi consumido em uma interação do Claude Code. A ideia é usar dois eventos complementares:

• UserPromptSubmit como ponto de pré-mensagem, para registrar quantos tokens já existiam antes da nova requisição;
• Stop como ponto de pós-resposta, para calcular a diferença entre o total atual e o valor salvo anteriormente.

Isso é útil para acompanhar crescimento de histórico, identificar prompts longos demais e perceber quando uma sessão está chegando perto do limite de contexto. O comportamento é não invasivo: o relatório vai para stderr, para não interferir no fluxo normal do hook.

6.19.2 context-tracker-tiktoken.py

Esta versão usa tiktoken com a codificação p50k_base, oferecendo uma aproximação mais precisa do consumo real, geralmente na faixa de 90–95% de aderência. Ela depende de instalação adicional:

pip install tiktoken

Se a biblioteca não estiver disponível, o script continua funcionando em modo de fallback, emitindo um aviso e passando a estimativa por caracteres. Esse fallback é menos preciso, mas evita que a automação quebre.

O valor de CONTEXT_LIMIT está configurado para 128000, que representa a janela de contexto assumida para Claude. Na prática, esse número deve ser ajustado conforme o modelo ou a política do ambiente. O cálculo exibirá percentual usado e quantos tokens ainda restam.

A função get_state_file(session_id) cria um arquivo temporário isolado por sessão, usando /tmp ou o diretório temporário da plataforma. Isso evita mistura entre sessões simultâneas.

A função read_transcript(transcript_path) lê o transcript linha por linha, interpretando cada linha como JSON. Ela extrai conteúdo de mensagens em dois formatos:

• content como string simples;
• content como lista de blocos, capturando apenas blocos com type == "text".

Esse detalhe é importante porque o transcript pode conter estruturas diferentes dependendo do tipo de resposta ou da forma como a mensagem foi registrada. Linhas com JSON inválido são ignoradas silenciosamente, o que torna o script tolerante a ruído no arquivo.

No evento UserPromptSubmit, o script calcula os tokens atuais do transcript e grava esse valor em um arquivo temporário com a chave pre_tokens. No evento Stop, ele recarrega esse valor e calcula:

• delta_tokens: diferença entre o total atual e o valor anterior;
• remaining: quanto ainda cabe no limite configurado;
• percentage: porcentagem do limite já consumida.

Se o arquivo de estado não existir, estiver corrompido ou não puder ser lido, o valor anterior assume 0. Isso faz com que o tracker ainda funcione, embora a métrica de delta possa ficar imprecisa no primeiro ciclo.

Na saída de relatório, o script imprime algo como:

Context (tiktoken): ~12,345 tokens (9.6% used, ~115,655 remaining)
This request: ~1,250 tokens

O texto “This request” só aparece quando o delta é positivo. Se o total atual for menor que o valor salvo, o script não tenta explicar o motivo; isso pode acontecer por troca de sessão, limpeza de transcript ou mudança de estado.

6.19.3 context-tracker.py

Esta variante é “zero dependency”, ou seja, não exige instalação externa. Ela mantém a mesma estrutura de hooks, a mesma leitura de transcript e o mesmo mecanismo de armazenamento temporário por sessão, mas usa uma estimativa simples baseada em caracteres:

return len(text) // 4

Essa regra assume aproximadamente quatro caracteres por token. O próprio material deixa claro que ela costuma ser razoável para inglês, mas perde precisão em código, em textos não ingleses e em conteúdos com muita marcação técnica. Na prática, é uma opção adequada quando você quer monitoramento leve, sem depender de pacotes extras.

O restante do fluxo é equivalente ao arquivo com tiktoken:

• salva a estimativa antes da requisição;
• recupera o valor depois da resposta;
• mostra total, percentual e restante;
• reporta o delta da requisição quando positivo.

Use a versão com tiktoken quando a precisão for mais importante. Use a versão estimada quando quiser simplicidade operacional, portabilidade e menos dependências. Em ambos os casos, a métrica é aproximada e não substitui a contagem real do provedor.

6.19.4 Boas práticas e limitações do tracker

• O arquivo de estado é temporário e por sessão; isso evita conflito entre múltiplos atendimentos paralelos.
• O cálculo depende do transcript disponível em transcript_path. Se o caminho vier vazio ou o arquivo não existir, o retorno será uma string vazia.
• O parser ignora linhas quebradas, então falhas parciais no transcript não derrubam o hook.
• Como a saída vai para stderr, ela é ideal para observabilidade humana, mas não deve ser usada para alimentar outros hooks que esperem JSON estruturado.

6.19.5 Exemplo de configuração conceitual

Você normalmente aponta os dois eventos para o mesmo script. O comportamento muda conforme o campo hook_event_name recebido via stdin:

UserPromptSubmit → salva o estado atual
Stop → calcula o delta e reporta uso

6.20 Verificação de dependências e segurança ao editar manifestos

6.20.1 dependency-check.sh

Esse hook é do tipo PostToolUse:Write e foi pensado para rodar logo após a escrita de arquivos de dependência. Ele identifica alterações em manifestos de várias linguagens e executa verificações de vulnerabilidade de forma aditiva e não bloqueante. O objetivo é avisar cedo, sem impedir o fluxo de trabalho.

O script começa recebendo o caminho do arquivo como argumento posicional. Se nada for informado, ele mostra uma mensagem de uso e sai com sucesso. Como o caminho pode vir absoluto, ele usa basename para decidir se o arquivo é um manifesto conhecido.

Os arquivos monitorados incluem:

• Node.js: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml
• Python: requirements.txt, Pipfile, Pipfile.lock, pyproject.toml
• Go: go.mod, go.sum
• Rust: Cargo.toml, Cargo.lock
• Ruby: Gemfile, Gemfile.lock
• PHP/Composer: composer.json, composer.lock
• Java: pom.xml, build.gradle, build.gradle.kts

Se o arquivo não pertencer a essa lista, o script encerra imediatamente. Quando há correspondência, ele marca que houve atualização de manifesto e começa a procurar problemas de segurança com ferramentas específicas por ecossistema.

6.20.2 Fluxo para Node.js, Yarn e pnpm

Quando o arquivo é algum dos manifestos de JavaScript, o script tenta usar npm audit se o comando npm estiver disponível. Ele executa com --audit-level=high e saída JSON. Depois, um trecho em Python interpreta o JSON, soma vulnerabilidades high e critical e trata o resultado como incidente quando houver contagem maior que zero.

Se houver vulnerabilidades, o hook sugere explicitamente:

npm audit fix

Se não houver vulnerabilidades altas ou críticas, ele informa que a checagem foi bem-sucedida.

Quando o arquivo monitorado é yarn.lock e o comando yarn existe, o script também roda yarn audit --level high --json. Nesse caso, ele procura o tipo JSON auditAdvisory. Se encontrar, sinaliza vulnerabilidades e recomenda:

yarn audit --level high

Esse fluxo é opcional e depende do gerenciador disponível no sistema.

6.20.3 Fluxo para Python

Para manifestos Python, o script prefere pip-audit quando ele existe no ambiente. A saída é solicitada em JSON e interpretada por um programa auxiliar que verifica dependências com lista de vulnerabilidades. Quando acha problemas, ele imprime nome, versão, identificador da vulnerabilidade e versões de correção sugeridas.

Se pip-audit não estiver disponível, o script tenta safety check --short-report. Esse caminho é mais sujeito a dependência de rede ou configuração. Se o comando terminar com erro mas sem indícios claros de vulnerabilidade, o hook avisa que a análise não pôde ser concluída, em vez de interpretar automaticamente como incidente.

Esse comportamento é importante: o script distingue “ferramenta não conseguiu executar” de “ferramenta encontrou falhas”.

6.20.4 Fluxo para Go

Quando o manifesto é Go, a ferramenta preferida é govulncheck. O script executa govulncheck ./... e inspeciona o retorno. Se não houver falhas, confirma que não encontrou vulnerabilidades. Se a saída contiver marcações de vulnerabilidade, ela é mostrada ao usuário.

Se o comando falhar por outro motivo, o hook informa que não conseguiu completar a verificação e exibe a mensagem de erro. Isso evita confundir falha de ferramenta com exposição real.

6.20.5 Fluxo para Rust e Ruby

Em projetos Rust, o script usa cargo audit quando disponível. O comando é executado e, se retornar erro, a flag interna ISSUES_FOUND é marcada. O script não tenta interpretar profundamente a saída; ele assume que a ferramenta já comunicou o motivo de forma útil.

Em projetos Ruby, a verificação é feita com bundler-audit check --update, também somente quando o utilitário existe no sistema. Caso o comando retorne erro, o hook assume que há um problema ou que a auditoria não completou com sucesso.

6.20.6 Fallback genérico com Trivy

Independentemente da linguagem, se trivy estiver instalado, o script executa um scan genérico do filesystem com:

trivy fs --exit-code 1 --severity HIGH,CRITICAL --quiet .

Esse caminho funciona como fallback para expor achados de severidade alta ou crítica no diretório atual. Se nada for encontrado, o script registra que o scan não apontou problemas relevantes.

6.20.7 Comportamento de saída e limitação importante

Mesmo quando vulnerabilidades são encontradas, o hook termina com exit 0. Isso significa que ele é estritamente consultivo: avisa, mas não bloqueia gravação nem commit. Essa escolha é útil quando você quer feedback sem travar a automação.

Se ISSUES_FOUND permanecer em 0, a mensagem final confirma que nenhuma vulnerabilidade foi detectada. Se houver achados, o script emite um aviso final dizendo que as dependências devem ser revisadas antes do commit.

6.20.8 Quando usar e riscos práticos

• Use esse hook em time para reduzir a chance de enviar dependências vulneráveis por engano.
• Ele é mais eficaz quando as ferramentas de auditoria do ambiente estão instaladas previamente.
• Como é não bloqueante, não substitui revisão de segurança, lockfiles e políticas de CI.
• O fallback com trivy pode ser mais pesado que as auditorias específicas, então vale observar custo em repositórios grandes.

6.21 Formatação automática e higiene do código

6.21.1 format-code.sh

Esse script roda como PostToolUse:Write e tenta formatar automaticamente o arquivo recém-escrito. Ele lê JSON da entrada padrão, extrai file_path usando sed e só continua se o arquivo realmente existir.

A abordagem é propositalmente portátil: não depende de Python para parsear JSON nem de ferramentas específicas de plataforma. Isso o torna compatível com macOS, Linux e Windows via Git Bash.

A lógica de escolha do formatador é baseada na extensão do arquivo:

• .js, .jsx, .ts, .tsx → prettier --write
• .py → black
• .go → gofmt -w
• .rs → rustfmt
• .java → google-java-format -i

Se a ferramenta correspondente não estiver instalada, o script simplesmente ignora o caso. Isso evita interrupção do fluxo, mas também significa que a formatação não é garantida apenas por existir o hook. Em ambiente profissional, é recomendável instalar os formatadores no workspace ou em imagem de desenvolvimento.

Como o script executa a formatação “in place”, o efeito é imediato no arquivo salvo. Isso pode gerar diffs adicionais logo após a escrita da ferramenta, o que é desejável para padronização, mas deve ser considerado quando o arquivo for sensível a mudanças automáticas.

6.22 Registro de comandos Bash para auditoria

6.22.1 log-bash.sh

Esse hook está voltado ao evento PostToolUse:Bash e registra todos os comandos executados em um arquivo local de log. Ele lê o JSON de entrada, extrai o campo command e grava uma linha com timestamp.

O arquivo de destino é:

$HOME/.claude/bash-commands.log

Se o diretório ainda não existir, ele é criado automaticamente. Cada linha registrada segue o formato:

[2026-07-18 14:35:10] git status

Há uma limitação conhecida na extração via sed: comandos com aspas duplas escapadas podem ser truncados na primeira ocorrência de \\". O próprio script assume isso como aceitável para fins de logging, porque o objetivo é auditabilidade geral, não reconstrução perfeita do JSON original.

Esse hook é útil para:

• rastrear histórico de ações realizadas via Bash;
• investigar alterações em sessões longas;
• complementar políticas de segurança e revisões posteriores.

6.23 Notificação de equipe após ações relevantes

6.23.1 notify-team.sh

Este script foi desenhado para disparar notificações após comandos Bash, com foco em eventos de push Git. Como não existe um evento nativo “PostPush”, a estratégia proposta é usar um hook de PostToolUse com matcher para Bash e filtrar a presença de git push no comando executado.

O script coleta metadados do repositório por comandos Git:

• nome do repositório com git rev-parse --show-toplevel e basename;
• última mensagem de commit com git log -1 --pretty=%B;
• autor do último commit com git log -1 --pretty=%an;
• branch atual com git rev-parse --abbrev-ref HEAD.

Se a variável de ambiente SLACK_WEBHOOK_URL existir, o script envia uma requisição POST para Slack com texto e anexos contendo branch, autor e commit. Se a variável DISCORD_WEBHOOK_URL existir, ele faz uma chamada semelhante para Discord, usando content e embeds. Se TEAM_EMAIL estiver definida, o script também envia um e-mail via comando mail.

Esse desenho permite múltiplos canais ao mesmo tempo, sem tornar nenhum deles obrigatório. Se nenhuma variável estiver configurada, o script apenas imprime que está enviando notificação e encerra sem ação efetiva.

Em uso real, observe os riscos práticos:

• se o repositório não for um Git válido, os comandos de coleta retornam vazios;
• se a mensagem de commit ou nomes tiverem aspas ou caracteres especiais, a montagem do JSON pode exigir cuidado adicional;
• webhooks e e-mail dependem de credenciais e rede disponíveis no ambiente.

6.24 Pré-validação de commit com execução de testes

6.24.1 pre-commit.sh

Esse script representa um guardrail de pré-commit implementado como PreToolUse com matcher de Bash. O comentário deixa claro um ponto importante: não existe um evento nativo “PreCommit” no Claude Code. Em vez disso, você inspeciona o comando do Bash e decide se ele corresponde a um commit.

O fluxo principal é simples: antes de permitir o commit, o hook procura sinais do ecossistema do projeto e executa a suíte de testes adequada.

Para projetos Node.js, ele verifica se existe package.json e se a chave "test" aparece no arquivo. Quando essas condições são verdadeiras, roda npm test. Se o comando falhar, o hook imprime mensagem de bloqueio e sai com exit 1.

Para Python, ele olha a presença de pytest.ini ou setup.py. Se pytest estiver instalado, executa os testes com pytest e bloqueia o commit em caso de falha.

Para Go, se existir go.mod, o script roda go test ./.... Para Rust, se houver Cargo.toml, ele executa Cargo test. Em ambos os casos, qualquer código de saída diferente de zero bloqueia o avanço.

Ao final, quando todas as verificações passam, a mensagem indica que o commit pode prosseguir.

Esse hook é restritivo de propósito: aqui o objetivo é impedir que alterações falhem em testes conhecidos antes do commit local. O custo é que projetos grandes podem demorar mais para validar, então vale ponderar quando ativá-lo sempre versus apenas em branches sensíveis.

6.25 Sala de segurança para comandos Bash antes da execução

6.25.1 pre-tool-check.sh

Este é um dos hooks mais importantes do conjunto porque atua antes de cada execução de Bash. Ele funciona como um filtro de segurança: pode bloquear comandos obviamente destrutivos e apenas advertir sobre operações arriscadas, registrando tudo em log para auditoria.

O script lê o JSON completo da entrada e tenta extrair o campo command com sed. Se a extração falhar, usa o conteúdo bruto como fallback. Isso é útil em teste local, embora não seja tão preciso quanto um parser JSON real.

6.25.2 Formato de saída e comportamento do hook

O próprio arquivo documenta a convenção do Claude Code:

• exit 0 permite a ação;
• exit 2 bloqueia e faz o conteúdo de stderr ser exibido como motivo do bloqueio;
• mensagens em stderr num caminho permitido podem ser descartadas pelo ambiente, então o hook usa log de auditoria para não perder visibilidade.

O log fica em:

$CLAUDE_PROJECT_DIR/.claude/hooks/audit.log

Se CLAUDE_PROJECT_DIR não existir, ele cai para $(pwd). Cada decisão é registrada com timestamp UTC, nível e comando analisado. Isso é essencial para enxergar advertências do tipo “WARN”, porque o ambiente pode suprimir stderr quando o comando é permitido.

6.25.3 Comandos bloqueados de forma absoluta

Os padrões bloqueados são aqueles que quase sempre representam destruição involuntária em contexto automatizado:

• rm -rf / com âncora para evitar falsos positivos em caminhos como /tmp;
• rm -rf *;
• dd if=/dev/zero;
• dd if=/dev/random;
• fork bomb clássica;
• mkfs. para formatação de filesystem;
• format c: para destruição típica em Windows.

Quando encontra um padrão bloqueado, o hook grava a decisão como BLOCK, escreve o motivo em stderr e encerra com exit 2. Isso interrompe a execução e comunica claramente a razão do veto.

6.25.4 Comandos de aviso

Há também padrões de aviso, que não são necessariamente errados, mas merecem atenção. Entre eles:

• rm -rf
• git push --force
• git reset --hard
• git clean -f
• chmod -R 777
• sudo rm
• DROP TABLE
• DROP DATABASE
• truncate

Se um ou mais desses padrões aparecerem, o hook acumula os avisos, registra a decisão como WARN e permite a execução. Em execução manual, ele mostra o alerta no terminal; em Claude Code, a documentação avisa que essa saída pode ser descartada, então o audit log é a fonte confiável.

Essa separação entre bloqueio absoluto e aviso é um bom exemplo de política pragmática: você evita danos quase certos, mas não trava operações legítimas de engenharia que exigem cautela extra.

6.25.5 Como usar na prática

• Ative esse hook para comandos Bash em ambientes com acesso a sistemas sensíveis.
• Revise periodicamente os padrões permitidos e bloqueados conforme a cultura do time.
• Use o audit log para rastrear tentativas de operações arriscadas mesmo quando nada foi bloqueado.

6.26 Varredura de segredos em arquivos gravados

6.26.1 security-scan.sh

Esse hook roda em PostToolUse:Write e analisa arquivos recém-escritos em busca de credenciais embutidas, chaves de API, tokens e chaves privadas. Diferente de um bloqueador, ele foi pensado para emitir aviso contextual, não para interromper a edição.

Assim como os demais hooks portáveis, ele lê o JSON de entrada padrão e extrai file_path com sed. Se o caminho não existir, ou se o arquivo não for de interesse, o script termina sem efeito.

6.26.2 Arquivos ignorados

Para evitar ruído, o scanner pula automaticamente:

• imagens e fontes: .png, .jpg, .jpeg, .gif, .svg, .ico, .woff, .woff2, .ttf, .eot;
• diretórios de terceiros e artefatos: node_modules, .git, dist, build.

6.26.3 Padrões analisados

O script procura sinais típicos de segredo hardcoded em formatos de configuração e código. Ele verifica, por exemplo:

• senha em JSON, como "password": "valor";
• senha em código, como password = 'valor';
• campos de API key, como api_key, apikey e access_token;
• segredos e tokens atribuídos com aspas;
• trechos contendo BEGIN ... PRIVATE KEY;
• chaves AWS que seguem o padrão AKIA mais 16 caracteres alfanuméricos maiúsculos.

Quando encontra problemas, ele monta uma string em ISSUES e depois emite um objeto JSON com hookSpecificOutput e additionalContext. Isso é relevante porque o formato esperado pelo protocolo é estruturado; não basta imprimir texto simples.

6.26.4 Ferramentas complementares: Semgrep e Trufflehog

Se semgrep estiver disponível, o hook roda semgrep --config=auto "$FILE_PATH" --quiet. Se trufflehog existir, executa trufflehog filesystem "$FILE_PATH" --only-verified --quiet. Em ambos os casos, a saída padrão é descartada para não misturar resultados com o JSON da resposta do hook.

Essas execuções complementares não alteram diretamente a lógica de JSON local, mas aumentam a cobertura de detecção. Em ambiente real, isso ajuda a pegar padrões menos óbvios que simples grep não encontraria.

6.26.5 Saída e recomendação prática

Quando há achados, o script entrega uma mensagem do tipo:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Security scan found issues in /caminho/arquivo.env:\n- WARNING: Potential hardcoded password detected\nPlease review and use environment variables instead."
  }
}

O texto final recomenda explicitamente usar variáveis de ambiente em vez de credenciais fixas. Isso é coerente com o uso esperado desse hook: reduzir vazamento acidental, não substituir revisões formais de segurança.

6.27 Registro de aprendizado ao final da sessão

6.27.1 session-end.sh

Esse hook é acionado no evento SessionEnd, ou seja, quando a sessão do Claude Code termina. Diferente dos hooks por comando, ele funciona uma vez por encerramento e foi pensado para registrar progresso de aprendizado em um arquivo persistente no home do usuário.

O arquivo de progresso é:

$HOME/.claude-howto-progress.json

O script tem uma salvaguarda importante: ele só roda se o diretório atual ou CLAUDE_PROJECT_DIR contiverem claude-howto. Isso evita que o mesmo hook grave progresso fora do repositório esperado.

Se o arquivo ainda não existir, ele cria uma estrutura mínima com {"sessions":[]}. Depois, mostra uma interface textual no terminal pedindo os módulos trabalhados na sessão. A entrada é lida de /dev/tty, porque a entrada padrão já está ocupada pelo payload JSON do hook.

6.27.2 Interface de entrada de módulos

O usuário pode digitar números separados por vírgula, como 06,07, ou pressionar Enter para pular. O script apresenta um mapa dos módulos:

• 01 = Slash
• 02 = Memory
• 03 = Skills
• 04 = Subagents
• 05 = MCP
• 06 = Hooks
• 07 = Plugins
• 08 = Checkpoints
• 09 = Advanced
• 10 = CLI

Há um mapeamento interno que converte esses números para rótulos JSON como "06-hooks" ou "10-cli". Se o usuário digitar algo fora do catálogo, o valor é preservado como texto entre aspas, permitindo anotações livres e futuras extensões sem quebrar o formato.

Depois dos módulos, o hook solicita notas opcionais. Isso também é lido via /dev/tty. As notas são passadas para um pequeno bloco Python como argumento separado justamente para evitar problemas de escaping com aspas e barras invertidas.

6.27.3 Persistência via Python

O trecho Python final lê o arquivo existente, adiciona um novo objeto em sessions e regrava o JSON com indentação. Cada sessão salva contém:

• date
• time
• modules
• notes

Essa estrutura é simples, mas adequada para acompanhar evolução ao longo do tempo. Como o salvamento é cumulativo, o arquivo funciona como um pequeno histórico local de prática e progresso.

6.27.4 Exemplo de uso

Which modules did you work on? (e.g. 06,07 or press Enter to skip)
> 06,07

Notes? (optional, press Enter to skip):
> Estudei hooks de PostToolUse e integração com notificações.

Ao final, o hook confirma o caminho do arquivo salvo e, se houver notas, também as ecoa para referência imediata.

6.28 Validação de prompts do usuário antes de executar ações

6.28.1 validate-prompt.sh

Esse script é um hook de UserPromptSubmit. Ele analisa o prompt digitado pelo usuário antes de o sistema prosseguir e pode bloquear operações perigosas ou adicionar contexto de segurança. É uma das melhores linhas de defesa contra instruções destrutivas logo na origem.

O input chega em JSON via stdin. O script tenta extrair, primeiro, o campo user_prompt; se ele não existir, cai para prompt. Se nenhum dos dois estiver presente, o hook encerra sem ação.

6.28.2 Regras de bloqueio

Há um conjunto de padrões considerados perigosos de forma direta:

• rm -rf /
• delete database
• drop database
• format disk
• dd if=

Se algum desses padrões aparecer no prompt, o hook devolve JSON com a decisão de bloqueio e uma razão explicando o motivo. O formato é propositalmente simples, por exemplo:

{
  "decision": "block",
  "reason": "Dangerous operation detected: rm -rf /"
}

O uso de printf e de JSON direto no stdout indica que essa resposta provavelmente será consumida pelo mecanismo de hooks. Não há tentativa de bloquear com exit 1; aqui a decisão é comunicada no payload e o processo termina com sucesso do ponto de vista do shell.

6.28.3 Proteção extra para deploy em produção

O script também examina solicitações que pareçam envolver deploy ou push para produção. A checagem usa uma expressão que procura deploy ou push próximos de production. Se detectar esse tipo de operação, ele exige a existência do arquivo:

.deployment-approved

Se o arquivo não existir, a resposta JSON retorna bloqueio com instrução clara para obter aprovação antes de continuar. Esse mecanismo funciona como uma trava de governança simples e explícita.

6.28.4 Contexto adicional para refatorações

Quando o prompt menciona refactor, o hook verifica se existe um diretório de testes (tests ou test). Se não houver, ele não bloqueia, mas emite additionalContext com um aviso de risco. Essa é uma postura equilibrada: refatorar sem testes não é proibido, mas merece cautela.

{
  "additionalContext": "Warning: Refactoring without tests may be risky. Consider writing tests first."
}

6.28.5 Quando usar esse validador

• Para impedir que prompts destrutivos avancem sem revisão.
• Para aplicar regras específicas de governança, como aprovação prévia de deploy.
• Para enriquecer o contexto de tarefas arriscadas, como refatoração em bases sem testes.

6.28.6 Limitações e comportamento prático

• A detecção é baseada em padrões textuais, então pode haver falsos positivos ou falsos negativos.
• O hook não interpreta intenção semântica profunda; ele apenas inspeciona o texto recebido.
• Regras como “produção” dependem do que o usuário escreveu no prompt, então nomes de ambiente fora desse vocabulário podem escapar da checagem.

7 Módulo — Plugins, marketplaces e distribuição

7.1 Plugins: empacotando comandos, agentes, MCP e hooks em um único pacote

Plugins no Claude Code são pacotes distribuíveis que juntam várias extensões em uma instalação só. Em vez de configurar um comando, um subagente, um servidor MCP e alguns hooks manualmente, você publica tudo como uma unidade coesa e o usuário instala com um único comando.

Na prática, um plugin é o nível mais alto de extensão: ele pode combinar slash commands, subagentes, servidores MCP, hooks, configurações padrão, binários auxiliares, templates, scripts e, em versões recentes, até monitores em background, LSP e opções de usuário.

7.1.1 Arquitetura de um plugin

Um plugin funciona como um contêiner de recursos. Ele não substitui os recursos individuais; ele os distribui e os ativa como conjunto.

• Slash commands: automatizam fluxos operacionais por comando.
• Subagents: especializam tarefas e podem operar com conjunto limitado de ferramentas.
• MCP servers: conectam o Claude Code a sistemas externos e fontes de contexto.
• Hooks: executam validações e tarefas antes, durante ou depois de eventos.
• Configuração: define comportamento padrão, marketplace, restrições e integrações.

O fluxo típico é: o usuário instala o plugin, o manifesto é baixado e lido, os componentes são extraídos e configurados, e então ficam disponíveis na sessão. A partir daí, comandos, agentes, MCP e hooks passam a agir como parte do ambiente do Claude Code.

Observação importante de versão: a partir da versão 2.1.157, plugins colocados em diretórios `.claude/skills` podem carregar automaticamente sem depender de marketplace. Isso reduz atrito para cenários locais. Ainda assim, o modelo de marketplace continua útil para distribuição, controle e versionamento.

7.1.2 Tipos de plugin e formas de distribuição

Os plugins podem ser distribuídos em diferentes escalas, e isso muda governança, público e responsabilidade de manutenção.

• Oficiais: mantidos pela Anthropic, com alcance global.
• Comunitários: publicados publicamente pela comunidade.
• Organizacionais: internos, para times e empresas.
• Pessoais: para uso individual do desenvolvedor.

O critério principal não é apenas “quem publica”, mas também “quem pode instalar”, “quem responde pelo conteúdo” e “qual nível de confiança existe”. Para ambientes corporativos, a governança do marketplace costuma ser mais importante que o conteúdo do plugin em si.

7.2 Estrutura do manifesto do plugin

Todo plugin precisa de um manifesto em JSON dentro de `.claude-plugin/plugin.json`. Esse arquivo descreve o pacote e permite que o Claude Code identifique, valide e carregue o plugin.

{
  "name": "my-first-plugin",
  "description": "A greeting plugin",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "homepage": "https://example.com",
  "repository": "https://github.com/user/repo",
  "license": "MIT"
}

Os campos principais desse manifesto são:

• name: nome do plugin, normalmente em kebab-case.
• description: resumo do objetivo do pacote.
• version: versão semântica para rastrear releases.
• author: informações do responsável.
• homepage: site ou página principal do projeto.
• repository: repositório de código-fonte.
• license: licença de uso e redistribuição.

Em versões mais novas, o manifesto também pode incluir recursos avançados como userConfig, monitors e definições inline de LSP. Esses recursos devem ser tratados com cuidado porque mudam a experiência do usuário e podem depender da versão do Claude Code.

7.3 Estrutura de diretórios de um plugin

Um plugin costuma organizar seus arquivos por tipo de recurso. A estrutura abaixo é um exemplo completo e ajuda a visualizar como os componentes se encaixam.

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # Manifesto do plugin
├── commands/             # Slash commands em Markdown
├── agents/               # Definições de subagentes
├── skills/               # Skills empacotadas com SKILL.md
├── hooks/                # Handlers de eventos
├── .mcp.json             # Configuração de MCP
├── .lsp.json             # Configuração de LSP
├── bin/                  # Executáveis adicionados ao PATH
├── settings.json         # Configuração padrão do plugin
├── themes/               # Temas personalizados opcionais
├── templates/            # Templates reutilizáveis
├── scripts/              # Scripts auxiliares
├── docs/                 # Documentação do pacote
└── tests/                # Testes do plugin

Nem toda pasta é obrigatória. Use apenas o que fizer sentido para o pacote. O importante é manter previsibilidade: o usuário precisa encontrar rapidamente onde ficam comandos, agentes, scripts e integrações.

7.4 Slash commands como parte do pacote

Os comandos são um dos usos mais comuns de plugin. Em vez de ensinar o usuário a montar um fluxo manual, o plugin expõe um comando pronto com etapas, requisitos e comportamento esperado.

Em um pacote bem desenhado, o comando não só “dispara ações”; ele também documenta o fluxo e orienta o Claude Code a coordenar outras peças do próprio plugin, como subagentes e hooks.

7.5 Subagentes no contexto de plugin

Subagentes permitem dividir responsabilidades. Cada um pode ser especializado em um domínio, como deploy, incidentes, documentação ou revisão de código.

Ao colocar subagentes dentro de um plugin, você consegue distribuir um fluxo completo com perfis distintos. Isso é útil quando um único comando precisa consultar especialistas diferentes em sequência.

7.5.1 Limitações de segurança em subagentes de plugin

Subagentes de plugin rodam em sandbox restrito. Isso impede que o pacote escale privilégios ou altere o ambiente além do escopo declarado.

• hooks não são permitidos em subagentes.
• mcpServers não são permitidos em subagentes.
• permissionMode não pode ser sobrescrito por subagentes.

Essa restrição é importante para evitar que um subagente “esconda” comportamentos administrativos dentro de uma definição que deveria apenas analisar ou operar dentro de limites seguros.

7.6 Exemplo prático: plugin de automação DevOps

O plugin devops-automation mostra uma distribuição típica de componentes para deploy, rollback, status e resposta a incidentes.

devops-automation/
├── commands/
│   ├── deploy.md
│   ├── rollback.md
│   ├── status.md
│   └── incident.md
├── agents/
│   ├── deployment-specialist.md
│   ├── incident-commander.md
│   └── alert-analyzer.md
├── mcp/
│   └── kubernetes-config.json
├── hooks/
│   ├── pre-deploy.js
│   └── post-deploy.js
└── scripts/
    ├── deploy.sh
    ├── rollback.sh
    └── health-check.sh

O manifesto desse plugin é simples, mas suficiente para identificação e distribuição:

{
  "name": "devops-automation",
  "version": "1.0.0",
  "description": "Complete DevOps automation for deployment, monitoring, and incident response",
  "author": {
    "name": "Community"
  },
  "license": "MIT"
}

7.6.1 O que esse plugin oferece

• /deploy: implanta aplicação em staging ou produção.
• /rollback: reverte para uma versão anterior.
• /status: verifica saúde geral do sistema.
• /incident: conduz resposta estruturada a incidentes.

• deployment-specialist: especialista em implantação e operações de deploy.
• incident-commander: coordena resposta e comunicação em incidentes.
• alert-analyzer: interpreta alertas e métricas de monitoramento.

• MCP Kubernetes: integra o Claude Code ao cluster para leitura e operação assistida.
• deploy.sh: automatiza etapas de implantação.
• rollback.sh: automatiza reversão.
• health-check.sh: executa checagens de saúde.
• pre-deploy.js: valida pré-requisitos antes do deploy.
• post-deploy.js: executa tarefas após a implantação.

7.6.2 Comandos do DevOps Automation

Os arquivos em commands/ descrevem o fluxo que o usuário aciona. Eles funcionam como instruções operacionais e também como documentação embutida.

/deploy organiza a implantação em passos claros:

1. Executar verificações pré-deploy.
2. Construir a aplicação.
3. Rodar os testes.
4. Implantar no ambiente alvo.
5. Executar checagens de saúde.
6. Notificar o time no Slack.

/rollback orienta a volta para uma versão anterior estável:

1. Identificar a implantação anterior.
2. Verificar se o alvo do rollback está saudável.
3. Executar o procedimento de reversão.
4. Rodar health checks.
5. Notificar o time.

/status foca na leitura do estado do sistema:

1. Consultar pods do Kubernetes.
2. Checar conexões com o banco.
3. Monitorar latência de API.
4. Revisar taxa de erros.
5. Avaliar uso de recursos.
6. Publicar o estado consolidado.

/incident estrutura uma resposta a incidentes em produção:

1. Criar registro do incidente.
2. Avaliar severidade e impacto.
3. Notificar o plantão.
4. Coletar diagnóstico.
5. Coordenar a resposta.
6. Documentar a resolução.
7. Agendar post-mortem.

7.6.3 Subagentes do DevOps Automation

Os agentes do pacote são especializados por tarefa, e suas permissões de ferramentas já indicam o que cada um pode fazer.

---
name: deployment-specialist
description: Handles all deployment operations
tools: read, write, bash, grep
---

# Deployment Specialist

Expert in deployment operations:
- Blue-green deployments
- Canary releases
- Rollback procedures
- Health checks
- Database migrations

O deployment-specialist é o agente mais adequado para escolher estratégias de implantação, lidar com migrações e lidar com saúde pós-deploy.

---
name: incident-commander
description: Coordinates incident response
tools: read, write, bash, grep
---

# Incident Commander

Manages incident response:
- Severity assessment
- Team coordination
- Status updates
- Resolution tracking
- Post-mortem facilitation

O incident-commander coordena o processo, mantendo comunicação e rastreando resolução. Ele não substitui monitoramento nem análise técnica profunda, mas organiza a operação em situação crítica.

---
name: alert-analyzer
description: Analyzes monitoring alerts and system metrics
tools: read, grep, bash
---

# Alert Analyzer

Analyzes system health and alerts:
- Alert correlation
- Trend analysis
- Root cause identification
- Metric visualization
- Proactive issue detection

O alert-analyzer é o componente ideal para leitura de sinais e correlação entre alertas e métricas. Em incidentes reais, ele ajuda a separar ruído de causa provável.

7.6.4 Hooks de pré e pós-deploy

Hooks permitem inserir validações e tarefas automáticas em momentos específicos do ciclo. No exemplo DevOps, há dois hooks em JavaScript.

O hook de pré-deploy verifica dependências e conectividade com o cluster.

#!/usr/bin/env node

/**
 * Pre-deployment hook
 * Validates environment and prerequisites before deployment
 */

O comportamento prático é este:

• Executa which kubectl para verificar se o cliente está instalado.
• Executa kubectl cluster-info para confirmar conexão com o cluster.
• Se qualquer etapa falhar, imprime mensagem de erro e sai com código 1.
• Se tudo estiver correto, registra que os checks passaram.

Esse hook é útil para evitar que um deploy continue quando o ambiente local, o contexto de Kubernetes ou as credenciais não estão corretos.

O hook de pós-deploy espera os pods ficarem prontos e prepara a etapa de smoke test.

#!/usr/bin/env node

/**
 * Post-deployment hook
 * Runs after deployment completes
 */

Seu fluxo prático é:

• Executar kubectl wait --for=condition=ready pod -l app=myapp --timeout=300s.
• Falhar imediatamente se os pods não ficarem prontos dentro do tempo limite.
• Preparar a etapa de smoke tests.
• Encerrar com sucesso somente se as verificações finais passarem.

Esses hooks mostram um ponto importante: um plugin não serve apenas para “automatizar tarefa”, mas para garantir que a tarefa só avance quando as precondições estiverem satisfeitas.

7.6.5 Scripts auxiliares do DevOps

Os scripts em scripts/ são executáveis que o plugin pode chamar para reduzir repetição e centralizar lógica operacional.

deploy.sh realiza a implantação com sequência definida:

1. Define o ambiente com argumento posicional, usando staging por padrão.
2. Executa npm run lint e npm test.
3. Executa npm run build.
4. Aplica manifests com kubectl apply -f k8s/$ENV/.
5. Aguarda um intervalo curto e valida o endpoint de saúde com curl -f.

#!/bin/bash
set -e

echo "🚀 Starting deployment..."

# Load environment
ENV=${1:-staging}
echo "📦 Target environment: $ENV"

# Pre-deployment checks
echo "✓ Running pre-deployment checks..."
npm run lint
npm test

# Build
echo "🔨 Building application..."
npm run build

# Deploy
echo "🚢 Deploying to $ENV..."
kubectl apply -f k8s/$ENV/

# Health check
echo "🏥 Running health checks..."
sleep 10
curl -f http://api.$ENV.example.com/health

echo "✅ Deployment complete!"

rollback.sh automatiza a reversão para uma versão estável anterior:

1. Define o ambiente, com staging como padrão.
2. Consulta o histórico de rollout para obter a revisão anterior.
3. Executa kubectl rollout undo deployment/app -n $ENV.
4. Aguarda a conclusão com kubectl rollout status.
5. Executa health check final no endpoint da API.

#!/bin/bash
set -e

echo "⏪ Starting rollback..."

ENV=${1:-staging}
echo "📦 Target environment: $ENV"

# Get previous deployment
PREVIOUS=$(kubectl rollout history deployment/app -n $ENV | tail -2 | head -1 | awk '{print $1}')
echo "🔄 Rolling back to revision: $PREVIOUS"

# Execute rollback
kubectl rollout undo deployment/app -n $ENV

# Wait for rollback
echo "⏳ Waiting for rollback to complete..."
kubectl rollout status deployment/app -n $ENV

# Health check
echo "🏥 Running health checks..."
sleep 5
curl -f http://api.$ENV.example.com/health

echo "✅ Rollback complete!"

Vale notar uma limitação prática aqui: o script calcula a revisão anterior em PREVIOUS, mas o comando de undo não usa explicitamente essa variável. Em um cenário real, isso merece revisão para evitar confusão operacional.

health-check.sh verifica API, banco e pods do Kubernetes:

• API: usa curl -sf no endpoint /health.
• Database: usa pg_isready apontando para o host do ambiente.
• Pods: conta quantos estão em Running e compara com o total.

#!/bin/bash

echo "🏥 System Health Check"
echo "===================="

ENV=${1:-production}

# Check API
echo -n "API: "
if curl -sf http://api.$ENV.example.com/health > /dev/null; then
  echo "✅ Healthy"
else
  echo "❌ Unhealthy"
fi

# Check Database
echo -n "Database: "
if pg_isready -h db.$ENV.example.com > /dev/null 2>&1; then
  echo "✅ Healthy"
else
  echo "❌ Unhealthy"
fi

# Check Pods
echo -n "Kubernetes Pods: "
PODS_READY=$(kubectl get pods -n $ENV --no-headers | grep "Running" | wc -l)
PODS_TOTAL=$(kubectl get pods -n $ENV --no-headers | wc -l)
echo "$PODS_READY/$PODS_TOTAL ready"

echo "===================="

Esse script é útil para resposta rápida, mas tem uma limitação de robustez: ele depende de texto de saída e de padrões simples como Running. Em ambientes mais críticos, convém enriquecer a checagem com filtragem de estado, namespaces e condições mais explícitas.

7.6.6 MCP Kubernetes do plugin

O arquivo mcp/kubernetes-config.json conecta o plugin ao servidor Kubernetes via MCP. Isso permite que o Claude Code consulte e opere o cluster com contexto estruturado.

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-kubernetes"],
      "env": {
        "KUBECONFIG": "${KUBECONFIG}"
      }
    }
  }
}

Esse tipo de integração depende de configuração correta do ambiente. No exemplo do plugin, a variável KUBECONFIG aponta para o arquivo de credenciais do cluster.

Na prática, o MCP é indicado quando o plugin precisa ler estado atual do sistema, examinar recursos no cluster ou obter contexto operacional sem depender apenas de shell scripts.

7.6.7 Instalação e execução

O comando de instalação via marketplace ou CLI é simples, mas a experiência real depende de permissões, conectividade e compatibilidade de versão.

/plugin install devops-automation

Para usar os comandos do plugin:

• /deploy staging para publicar em staging.
• /deploy production para publicar em produção.
• /rollback production para reverter produção.
• /status para checar saúde geral.
• /incident para iniciar resposta a incidente.

Requisitos do pacote:

• Claude Code 1.0+.
• kubectl disponível.
• Acesso ao cluster configurado.

Para configurar o contexto de Kubernetes, o exemplo usa:

export KUBECONFIG=~/.kube/config

Sem essa configuração, o plugin pode instalar corretamente, mas falhar ao executar hooks, scripts ou MCP que dependam do cluster.

7.6.8 Exemplo de fluxo operacional do DevOps

Um fluxo de deploy completo costuma combinar vários componentes do plugin em sequência. Isso é importante porque o valor do plugin está justamente na orquestração.

1. O usuário aciona /deploy production.
2. O hook de pré-deploy valida kubectl e a conexão com o cluster.
3. O subagente deployment-specialist assume a decisão operacional.
4. O script deploy.sh executa build, testes e apply.
5. O MCP Kubernetes ajuda a acompanhar o estado de implantação.
6. O hook de pós-deploy aguarda pods e prepara smoke tests.
7. O sistema apresenta um resumo final da implantação.

Esse encadeamento é um bom padrão para qualquer plugin de automação: validação, especialização, execução, observabilidade e fechamento.

7.7 Marketplace, distribuição e catálogos de plugins

Plugins normalmente são distribuídos por marketplaces. A Anthropic mantém um diretório oficial, e organizações podem criar marketplaces próprios para uso interno.

O marketplace é o mecanismo de catálogo; o plugin é o pacote instalável. Isso significa que atualizar o marketplace não é o mesmo que atualizar o plugin já instalado.

7.7.1 Estrutura de um marketplace

Um marketplace também possui manifesto, normalmente em .claude-plugin/marketplace.json, com metadados sobre o catálogo e sua lista de plugins.

{
  "name": "my-team-plugins",
  "owner": "my-org",
  "plugins": [
    {
      "name": "code-standards",
      "source": "./plugins/code-standards",
      "description": "Enforce team coding standards",
      "version": "1.2.0",
      "author": "platform-team"
    },
    {
      "name": "deploy-helper",
      "source": {
        "source": "github",
        "repo": "my-org/deploy-helper",
        "ref": "v2.0.0"
      },
      "description": "Deployment automation workflows"
    }
  ]
}

Campos do marketplace:

• name: nome do marketplace em kebab-case.
• owner: organização ou pessoa responsável.
• plugins: lista de entradas de plugin.
• plugins[].name: nome do plugin.
• plugins[].source: origem do plugin.
• plugins[].description: descrição breve.
• plugins[].version: versão do plugin.
• plugins[].author: autor.
• plugins[].renames: mapa de migração de nomes antigos para novos, incluindo null quando um item foi removido.
• plugins[].displayName: nome amigável apenas para interface.
• plugins[].defaultEnabled: controla se o plugin instala habilitado ou não.

Versões relevantes: renames apareceu em 2.1.193, displayName em 2.1.143 e defaultEnabled em 2.1.154.

7.7.2 Tipos de fonte do plugin

Um marketplace pode apontar para plugins locais, remotos ou distribuídos por registries. A escolha afeta rastreabilidade, atualização e controles de segurança.

• Relative path: caminho local relativo, por exemplo "./plugins/my-plugin".
• GitHub: repositório GitHub com repo e, opcionalmente, ref ou sha.
• Git URL: URL Git completa para repositórios em outros provedores.
• Git subdirectory: quando o plugin vive em um subdiretório de um monorepo.
• npm: pacote publicado em registries npm.
• pip: pacote distribuído via Python package index ou repositório compatível.

Exemplos de fontes:

{
  "source": "github",
  "repo": "acme/lint-plugin",
  "ref": "v1.0"
}

{
  "source": "url",
  "url": "https://git.internal/plugin.git"
}

{
  "source": "git-subdir",
  "url": "https://github.com/org/monorepo.git",
  "path": "packages/plugin"
}

{
  "source": "npm",
  "package": "@acme/claude-plugin",
  "version": "^2.0"
}

{
  "source": "pip",
  "package": "claude-data-plugin",
  "version": ">=1.0"
}

GitHub e fontes Git aceitam pinagem com ref e sha, o que é útil para ambientes reprodutíveis. Em ambientes corporativos, isso reduz risco de variação inesperada em installs futuros.

7.7.3 Regras de marketplace, allowlist e blocklist

Organizações podem controlar quais marketplaces podem ser adicionados e quais plugins podem ser instalados. Isso é especialmente importante em ambientes gerenciados.

• extraKnownMarketplaces: adiciona fontes extras de marketplace além das padrão.
• strictKnownMarketplaces: restringe quais marketplaces usuários podem adicionar; é uma configuração gerenciada.
• blockedMarketplaces: bloqueia marketplaces específicos.
• deniedPlugins: bloqueia plugins individuais.

Enforcement importante: desde a versão 2.1.117, blockedMarketplaces e strictKnownMarketplaces são aplicados em todo ciclo de vida do plugin: instalação, atualização, refresh e autoupdate. Não é uma checagem “só no primeiro add”.

Desde a versão 2.1.119, blockedMarketplaces aceita regex em hostPattern e pathPattern para filtros mais precisos.

{
  "blockedMarketplaces": [
    {
      "hostPattern": "^evil\\.example\\.com$",
      "pathPattern": "^/marketplaces/.*"
    }
  ]
}

Com strictKnownMarketplaces, o comportamento varia assim:

• Se não for definido, não há restrição adicional.
• Se for um array vazio, nenhum marketplace é permitido.
• Se contiver padrões, apenas marketplaces compatíveis podem ser adicionados.

{
  "strictKnownMarketplaces": [
    "my-org/*",
    "github.com/trusted-vendor/*"
  ]
}

Em modo estrito, o usuário fica limitado a marketplaces explicitamente autorizados. Isso é útil para compliance, ambientes regulados e distribuição interna controlada.

7.7.4 Definições inline e marketplaces declarados em settings

Desde a versão 2.1.80, plugins podem ser definidos inline em settings por meio de source: "settings". Esse modelo é útil quando você quer embutir uma referência ao plugin sem exigir um marketplace separado.

{
  "pluginMarketplaces": [
    {
      "name": "inline-tools",
      "source": "settings",
      "plugins": [
        {
          "name": "quick-lint",
          "source": "./local-plugins/quick-lint"
        }
      ]
    }
  ]
}

Esse recurso é conveniente para cenários locais ou temporários, mas não substitui um marketplace formal quando você precisa de distribuição ampla, versionamento de catálogo ou governança centralizada.

7.7.5 Opções do plugin para o usuário

Em versões 2.1.83+, o manifesto pode expor userConfig para permitir parametrização pelo usuário sem editar o código do plugin.

{
  "name": "my-plugin",
  "version": "1.0.0",
  "userConfig": {
    "apiKey": {
      "description": "API key for the service",
      "sensitive": true
    },
    "region": {
      "description": "Deployment region",
      "default": "us-east-1"
    }
  }
}

O campo sensitive: true faz com que o valor seja armazenado no keychain do sistema, e não em texto puro nas configurações. Use isso para segredos, tokens e chaves de API. Use valores não sensíveis para defaults operacionais, como região, namespace ou nível de ambiente.

7.7.6 Dados persistentes do plugin

Desde a versão 2.1.78, plugins podem acessar um diretório persistente por meio da variável ${CLAUDE_PLUGIN_DATA}. Esse caminho é único para o plugin e sobrevive entre sessões, o que é ideal para cache, banco local, índices e estado operacional.

{
  "hooks": {
    "PostToolUse": [
      {
        "command": "node ${CLAUDE_PLUGIN_DATA}/track-usage.js"
      }
    ]
  }
}

Os arquivos ali permanecem até o plugin ser desinstalado. É uma solução prática, mas requer disciplina: não grave segredos desnecessários em texto puro e não assuma que o diretório será compartilhado com outros plugins.

7.7.7 Monitores em background

A partir da versão 2.1.105, plugins podem registrar monitores que ficam ativos em background e disparam quando a sessão começa ou quando uma skill do plugin é invocada.

{
  "name": "my-plugin",
  "version": "1.0.0",
  "monitors": [
    {
      "command": "tail -f /var/log/app.log",
      "trigger": "session_start"
    }
  ]
}

Os valores aceitos para trigger são:

• session_start: arma o monitor ao iniciar a sessão.
• skill_invoke: arma o monitor quando a skill do plugin é invocada.

Esse recurso usa internamente o mesmo mecanismo de Monitor tool e streama linhas de stdout como eventos. É muito útil para observabilidade reativa, mas deve ser usado com cuidado para não poluir a sessão com eventos excessivos.

7.7.8 Configurações padrão do plugin

Um plugin pode incluir settings.json para definir defaults. Atualmente, o principal uso é o campo agent, que define o agente principal do plugin.

{
  "agent": "agents/specialist-1.md"
}

Essas configurações são aplicadas na instalação, mas o usuário ainda pode sobrescrevê-las no projeto ou nas configurações pessoais. Em geral, use esse arquivo para garantir uma experiência inicial consistente, e não para impor comportamento impossível de alterar.

7.7.9 Diretório bin/ no PATH

Quando um plugin está habilitado, a pasta bin/ é colocada no início do PATH da sessão. Isso permite chamar executáveis do próprio plugin apenas pelo nome.

my-plugin/
├── plugin.json
└── bin/
    └── my-tool          # executável com chmod +x

# Na sessão com o plugin habilitado:
$ my-tool --help

Esse padrão é útil para scripts auxiliares que hooks, comandos ou outros componentes chamam internamente. Lembre-se de marcar os arquivos como executáveis no repositório com chmod +x; o Git preserva esse bit.

7.7.10 Recursos de LSP dentro de plugins

Plugins podem incluir suporte a Language Server Protocol para inteligência de código em tempo real. Isso dá diagnósticos, navegação por símbolos e informações de hover enquanto você trabalha.

O LSP pode ser configurado em dois lugares:

• arquivo .lsp.json na raiz do plugin;
• chave inline lsp dentro de plugin.json.

Campos suportados na configuração de LSP:

• command: binário do servidor, precisa estar no PATH.
• extensionToLanguage: mapeia extensões de arquivo para IDs de linguagem.
• args: argumentos de linha de comando.
• transport: método de comunicação, stdio por padrão ou socket.
• env: variáveis de ambiente do processo.
• initializationOptions: opções enviadas na inicialização.
• settings: configuração de workspace passada ao servidor.
• workspaceFolder: substitui o caminho da workspace.
• startupTimeout: tempo máximo para startup em milissegundos.
• shutdownTimeout: tempo máximo para desligamento gracioso.
• restartOnCrash: reinicia automaticamente se o servidor cair.
• maxRestarts: número máximo de reinícios antes de desistir.

Exemplos de configuração:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

{
  "python": {
    "command": "pyright-langserver",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".py": "python",
      ".pyi": "python"
    }
  }
}

{
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".ts": "typescript",
      ".tsx": "typescriptreact",
      ".js": "javascript",
      ".jsx": "javascriptreact"
    }
  }
}

Plugins LSP oficiais já vêm pré-configurados para alguns ecossistemas:

• pyright-lsp para Python, com pyright-langserver e instalação via pip install pyright.
• typescript-lsp para TypeScript/JavaScript, com typescript-language-server e instalação via npm global.
• rust-lsp para Rust, com rust-analyzer instalado via rustup component add rust-analyzer.

Depois de configurado, o LSP oferece:

• diagnósticos imediatos;
• navegação para definição, referências e implementações;
• informações de hover com assinaturas e documentação;
• listagem de símbolos do arquivo ou workspace.

7.7.11 Marketplace do plugin e recursos de catálogo

O marketplace oficial é mantido pela Anthropic e pode ser complementado por marketplaces comunitários ou privados. Em versões recentes, o navegador de marketplace ganhou melhorias úteis para adoção em escala.

• Busca no marketplace a partir da versão 2.1.172, filtrando plugins por nome ou palavra-chave.
• Tempo limite de git aumentado de 30s para 120s para repositórios grandes.
• Registries npm personalizados para resolução de dependências.
• Version pinning para ambientes reprodutíveis.
• Custo projetado por turno exibido no navegador e no detalhe do plugin.

O custo projetado ajuda a prever impacto de contexto, já que inclui skills sempre carregadas, hooks e descritores de servidores MCP. Isso é especialmente importante em modelos com janela de contexto limitada.

NAME              VERSION   AUTHOR     CTX/TURN   DESCRIPTION
code-reviewer     1.2.0     anthropic  +1,420     Multi-agent PR review
devops-toolkit    0.4.1     acme       +3,180     SRE playbooks, on-call helpers
docs-helper       0.9.0     community  +610       Doc-style guide enforcement

Além disso, o comando de detalhes do plugin mostra inventário completo e custo estimado.

plugin: code-reviewer (1.2.0)
skills:        3      hooks: 2      mcp: 1      lsp: 0      monitors: 0
commands:      /review, /security-review
projected ctx: +1,420 tokens per turn  ·  +9,800 tokens per /review invocation

O detalhe passou a incluir LSP na versão 2.1.142. O navegador do marketplace passou a exibir custo projetado na versão 2.1.143.

7.7.12 Comandos de linha de comando para plugins

As operações de plugin também existem em CLI. Isso é útil para automação, scripts e ambientes sem interface interativa.

claude plugin install @
claude plugin uninstall 
claude plugin update 
claude plugin list
claude plugin enable 
claude plugin disable 
claude plugin validate
claude plugin tag 
claude plugin prune
claude plugin uninstall  --prune
claude plugin details 

Uso prático de algumas dessas ações:

• claude plugin tag v0.3.0 valida o formato da versão e cria a tag Git correspondente. É o caminho recomendado para release de plugin.
• claude plugin prune remove dependências instaladas automaticamente que ficaram órfãs depois que o plugin pai foi removido.
• claude plugin uninstall <name> --prune faz a remoção e a limpeza em cascata numa única operação.

Há também um comportamento importante de dependência a partir da versão 2.1.143:

• claude plugin disable <name> recusa desabilitar se outro plugin habilitado ainda depender dele.
• claude plugin enable <name> força a habilitação das dependências transitivas após uma única confirmação.

Isso evita quebrar grafos de dependência e reduz a chance de o usuário ficar com um plugin parcialmente funcional.

7.7.13 Instalação, ativação e ciclo de vida

O ciclo de vida de um plugin inclui descoberta, instalação, ativação, uso, atualização, desativação e remoção. Cada etapa pode ser administrada manualmente ou via marketplace.

O usuário pode instalar de várias formas:

• via marketplace;
• via caminho local;
• via GitHub;
• via URL de Git;
• via arquivo .zip local ou remoto;
• via diretório com --plugin-dir durante desenvolvimento.

/plugin install plugin-name
/plugin install ./path/to/plugin-directory
/plugin install github:username/repo

Para testes locais, a CLI aceita múltiplos diretórios e, em versões recentes, arquivos ZIP e URLs ZIP:

claude --plugin-dir ./my-plugin
claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin
claude --plugin-dir ./my-plugin.zip
claude --plugin-url https://example.com/releases/my-plugin-0.3.0.zip

As opções --plugin-dir e --plugin-url são especialmente úteis para validar um pacote antes de publicar. Isso permite testar comandos, agentes, MCP, hooks e LSP sem depender de um marketplace real.

7.7.14 Auto-update, ambiente e preferências de transporte

O Claude Code pode atualizar automaticamente marketplaces e plugins instalados no startup.

• Marketplaces oficiais têm auto-update ativado por padrão.
• Marketplaces de terceiros ou locais vêm com auto-update desativado por padrão.

Quando o auto-update roda, ele:

1. atualiza o catálogo do marketplace;
2. atualiza plugins instalados para a versão mais recente;
3. mostra uma notificação pedindo /reload-plugins.

Variáveis de ambiente relevantes:

• DISABLE_AUTOUPDATER=1: desativa todas as autoatualizações do Claude Code e dos plugins.
• DISABLE_AUTOUPDATER=1 com FORCE_AUTOUPDATE_PLUGINS=1: mantém update de plugins, mas desativa update do Claude Code.
• CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1: força clones GitHub por HTTPS em vez de SSH, útil em CI e containers sem chave SSH.

Em sessões remotas, houve melhoria de desempenho no carregamento de plugins a partir da versão 2.1.179, tornando-os disponíveis mais rapidamente após a conexão.

7.7.15 Quando criar um plugin

Nem toda automação merece virar plugin. A escolha certa depende da quantidade de componentes, do esforço de configuração e da necessidade de distribuição.

• Se o fluxo combina vários comandos, subagentes ou MCPs, o plugin é uma boa escolha.
• Se o objetivo é compartilhar com um time, o plugin simplifica onboarding e padronização.
• Se o setup precisa de configuração automática, o plugin reduz erro humano.
• Se é só um comando curto e isolado, uma feature individual pode ser melhor.

Diretrizes práticas:

• Onboarding de equipe: plugin.
• Setup de framework: plugin.
• Padrões corporativos: plugin.
• Tarefa rápida e pontual: comando ou skill.
• Especialização isolada: skill ou subagente, sem empacotar demais.
• Acesso a dados ao vivo: MCP separado pode ser melhor que empacotar tudo.

7.7.16 Diferença entre abordagem manual e plugin

Sem plugin, o usuário instala cada componente separadamente, configura MCPs, escreve documentação e tenta manter tudo consistente entre máquinas e equipes. Isso normalmente leva mais tempo e aumenta risco de divergência.

Com plugin, o mesmo conjunto vem preparado para instalação e atualização em um único fluxo, o que melhora reprodutibilidade e reduz custo de manutenção.

7.7.17 Teste, hot-reload e depuração

Antes de publicar, teste localmente o pacote com --plugin-dir ou --plugin-url. Valide se os comandos aparecem, se os agentes carregam, se MCP conecta, se hooks disparam e se o LSP inicializa.

Durante o desenvolvimento, o Claude Code suporta hot-reload. Ao alterar arquivos do plugin, ele pode detectar mudanças automaticamente. Se necessário, use:

/reload-plugins

Esse comando recarrega manifestos, comandos, agentes, skills, hooks e configurações de MCP/LSP sem reiniciar a sessão.

Para depuração, é importante checar:

• compatibilidade da versão do Claude Code;
• estrutura dos caminhos no manifesto;
• permissões de execução em scripts e binários;
• erros de sintaxe em Markdown, JSON e scripts;
• conflitos de nomes com comandos já existentes;
• estado de conexão do MCP;
• logs e ferramentas de debug disponíveis para plugins.

7.7.18 Troubleshooting comum

Se o plugin não instalar, verifique a versão do Claude Code, valide o JSON do manifesto, confirme conectividade com o repositório remoto e revise permissões no sistema de arquivos.

Se componentes não carregarem, confira se os caminhos batem com a estrutura real do diretório, se os scripts estão executáveis e se não há erro de sintaxe no arquivo do componente.

Se o MCP falhar, revise variáveis de ambiente, instalação do servidor e configuração no diretório mcp/. Também vale testar a conexão do MCP isoladamente.

Se os comandos não aparecerem após a instalação, confirme que o plugin está instalado e habilitado, verifique possíveis conflitos e, quando necessário, reinicie a sessão do Claude Code.

Se hooks falharem, revise permissões, nomes de eventos, sintaxe do arquivo e logs de execução.

7.7.19 Publicação de plugin

Para publicar um plugin de forma organizada, o fluxo recomendado é:

1. Montar a estrutura completa.
2. Escrever o manifesto em .claude-plugin/plugin.json.
3. Preparar a documentação do repositório.
4. Testar localmente com claude --plugin-dir.
5. Gerar a tag de release com claude plugin tag vX.Y.Z.
6. Submeter ao marketplace adequado.
7. Aguardar revisão e aprovação.
8. Disponibilizar para instalação dos usuários.

O comando claude plugin tag é importante porque valida o formato da versão antes de criar a tag Git. Isso reduz erro humano no processo de release.

7.7.20 Boas práticas

• Escolha nomes claros e descritivos.
• Escreva um README completo e com exemplos.
• Use versionamento semântico consistente.
• Teste todos os componentes em conjunto.
• Mantenha o plugin focado e coeso.
• Documente requisitos e dependências.
• Inclua tratamento de erro nos scripts e hooks.
• Evite agrupar funcionalidades sem relação.
• Não embuta credenciais no código.
• Planeje compatibilidade e migração de nomes quando o plugin evoluir.

7.7.21 Configurações gerenciadas por administradores

Em ambientes corporativos, administradores podem impor políticas para plugins por meio de configuração gerenciada. Isso prevalece sobre preferências do usuário.

• enabledPlugins: allowlist de plugins habilitados por padrão.
• deniedPlugins: blocklist de plugins proibidos.
• extraKnownMarketplaces: marketplaces adicionais permitidos.
• strictKnownMarketplaces: restringe marketplaces permitidos.
• blockedMarketplaces: bloqueia marketplaces específicos.
• allowedChannelPlugins: controla plugins permitidos por canal de release.

Essas regras são úteis quando a organização precisa limitar exposição a código de terceiros, manter compliance ou aprovar apenas um conjunto pequeno de extensões confiáveis.

7.7.22 Exemplos de outros plugins de distribuição

O plugin de documentação mostra outra composição comum: comandos de geração, agentes especializados, templates e integração com GitHub.

documentation/
├── commands/
│   ├── generate-api-docs.md
│   ├── generate-readme.md
│   ├── sync-docs.md
│   └── validate-docs.md
├── agents/
│   ├── api-documenter.md
│   ├── code-commentator.md
│   └── example-generator.md
├── mcp/
│   ├── github-docs-config.json
│   └── slack-announce-config.json
└── templates/
    ├── api-endpoint.md
    ├── function-docs.md
    └── adr-template.md

Esse pacote normalmente serve para gerar documentação de API, criar README, sincronizar docs com o código e melhorar comentários inline. É um bom exemplo de plugin em que o valor vem da consistência entre componentes, não de uma única automação isolada.

7.7.23 Subagentes do plugin de documentação

Os agentes abaixo se complementam para cobrir documentação técnica de forma mais completa.

---
name: api-documenter
description: API documentation specialist
tools: read, write, grep
---

# API Documenter

Creates comprehensive API documentation:
- Endpoint documentation
- Parameter descriptions
- Response schemas
- Code examples (curl, JS, Python)
- Error codes

O api-documenter é voltado para rotas, parâmetros, códigos de resposta e exemplos práticos.

---
name: code-commentator
description: Code comment and inline documentation specialist
tools: read, write, edit
---

# Code Commentator

Improves code documentation:
- JSDoc/docstring comments
- Inline explanations
- Parameter descriptions
- Return type documentation
- Usage examples

O code-commentator melhora o código-fonte em si, deixando comentários e documentação inline mais claros e consistentes.

---
name: example-generator
description: Code example and tutorial specialist
tools: read, write
---

# Example Generator

Creates practical code examples:
- Getting started guides
- Common use cases
- Integration examples
- Best practices
- Troubleshooting scenarios

O example-generator é útil quando a documentação precisa sair do teórico e mostrar uso real, incluindo guias iniciais e cenários de troubleshooting.

7.7.24 Resumo operacional de instalação e uso

Em uma rotina real, você pode navegar, instalar, habilitar, desabilitar, listar e atualizar plugins diretamente pela interface /plugin ou pela CLI. O comportamento é consistente, mas o contexto de execução muda conforme o plugin venha de marketplace, caminho local, Git, ZIP ou URL.

• Use /plugin list para explorar o que está disponível.
• Use /plugin install para instalar.
• Use /plugin enable e /plugin disable para controlar ativação.
• Use /plugin update para atualizar o que já está instalado.
• Use /plugin uninstall para remover.
• Use /reload-plugins quando alterar arquivos localmente.

Para ambientes com restrição de rede ou de credenciais, combine os recursos de pinagem, HTTPS forçado e caches locais com cuidado. Isso evita falhas de instalação em CI, containers e ambientes corporativos fechados.

7.8 Comandos de geração, sincronização e validação de documentação

7.8.1 Generate API Documentation

Este comando serve para produzir documentação completa de API a partir do código-fonte. Ele é útil quando você quer reduzir a divergência entre implementação e documentação, especialmente em projetos com muitos endpoints, funções utilitárias e contratos de entrada e saída bem definidos.

O fluxo esperado é:

1. varrer os endpoints da API;
2. extrair assinaturas de funções e comentários JSDoc;
3. organizar a documentação por módulo ou endpoint;
4. gerar Markdown com exemplos de uso;
5. incluir schemas de request e response;
6. documentar erros e condições de falha.

Na prática, esse comando é mais valioso quando o código já tem contratos relativamente estáveis, porque a geração automática depende de sinais presentes no código, como nomes de funções, tipos e comentários. Se a base estiver mal anotada, a documentação produzida fica incompleta ou genérica.

7.8.2 Generate README

Este comando cria ou atualiza o arquivo README do projeto. Ele é indicado para repositórios que precisam de uma visão de entrada clara para novos colaboradores, usuários finais ou avaliadores internos.

O conteúdo esperado do README inclui:

• visão geral do projeto e sua finalidade;
• instruções de instalação;
• exemplos de uso;
• links para documentação da API;
• orientações de contribuição;
• informações de licença.

O uso correto desse comando evita READMEs superficiais, mas ele só será bom se a base do projeto e a documentação de apoio estiverem bem organizadas. Em projetos com múltiplos pacotes, vale conferir se os links e instruções refletem a estrutura real do repositório.

7.8.3 Sync Documentation

Esse comando sincroniza a documentação com mudanças no código. Ele é importante em times que fazem entregas frequentes e precisam manter exemplos, versões e descrições alinhados ao comportamento atual da aplicação.

O processo descrito pelo comando é:

1. detectar mudanças no código;
2. identificar documentação desatualizada;
3. atualizar os arquivos afetados;
4. verificar se os exemplos continuam funcionando;
5. atualizar números de versão quando necessário.

O risco principal aqui é documentar algo que mudou de comportamento sem atualizar os exemplos. Isso costuma gerar documentação tecnicamente “correta” em texto, mas errada no uso real. Por isso, a validação de exemplos faz parte do processo e não deve ser ignorada.

7.8.4 Validate Documentation

Este comando valida a qualidade da documentação. Ele não cria conteúdo novo; em vez disso, verifica se o material existente está consistente, completo e alinhado ao código.

As checagens listadas incluem:

• links quebrados;
• exemplos de código funcionando corretamente;
• completude do conteúdo;
• formatação;
• aderência ao código real.

Esse tipo de validação é especialmente importante depois de refatorações, renomes, remoção de rotas ou alterações em assinaturas de funções. Em ambientes maduros, ele funciona melhor quando combinado com revisão automática e testes que exercitam os exemplos documentados.

7.9 Integração com MCP para documentação do GitHub

7.9.1 Configuração documentation/mcp/github-docs-config.json

Este arquivo define um servidor MCP para integração com GitHub, usando o pacote @modelcontextprotocol/server-github executado via npx. A configuração expõe o servidor github e injeta o token por variável de ambiente.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

O comportamento esperado é que o runtime resolva ${GITHUB_TOKEN} a partir do ambiente do usuário ou da sessão. Sem esse token, o servidor GitHub tende a falhar em operações autenticadas, o que pode impactar tanto leitura de dados privados quanto automações de documentação baseadas em PRs, issues ou repositórios restritos.

Esse tipo de integração é dependente de configuração correta do ambiente e de permissões válidas no GitHub. Se o token estiver ausente, revogado ou sem escopos suficientes, a coleta de dados para documentação não será confiável.

7.10 Templates para documentação e decisões de arquitetura

7.10.1 Template de ADR: documentation/templates/adr-template.md

O template de ADR organiza decisões arquiteturais de forma rastreável. Ele é útil quando uma equipe precisa registrar por que uma escolha foi feita, quais impactos ela traz e quais alternativas foram descartadas. Isso evita decisões “apagadas” pelo tempo e ajuda na manutenção em longo prazo.

Estrutura do template:

• ADR [Number]: [Title] — identificador e título da decisão;
• Status — pode ser Proposed, Accepted, Deprecated ou Superseded;
• Context — problema, pressão ou necessidade que motivou a decisão;
• Decision — o que será adotado ou alterado;
• Consequences — efeitos práticos positivos, negativos e neutros;
• Alternatives Considered — opções avaliadas e motivo de rejeição;
• References — documentos relacionados, links externos e discussões.

O campo Status merece atenção porque ele mostra o ciclo de vida da decisão. Proposed indica discussão em andamento; Accepted, decisão consolidada; Deprecated, algo que perdeu validade; e Superseded, uma decisão substituída por outra mais nova.

Exemplo de uso adequado: documentar a adoção de um novo mecanismo de cache, registrando o problema atual, os ganhos esperados, as desvantagens, as alternativas como cache em memória ou Redis, e os links para a discussão da equipe. Isso facilita auditoria técnica e onboarding.

7.10.2 Template de endpoint de API: documentation/templates/api-endpoint.md

Este template padroniza a documentação de endpoints HTTP. Ele é apropriado para APIs públicas ou internas que precisam de descrição clara de autenticação, parâmetros, payloads, respostas e limites de uso.

Campos e seções principais:

• [METHOD] /api/v1/[endpoint] — substitua pelo verbo HTTP e rota real;
• Description — resumo do comportamento do endpoint;
• Authentication — método de autenticação exigido, como Bearer token;
• Parameters — separa parâmetros de path e query;
• Request Body — corpo da requisição com exemplo JSON;
• Responses — exemplos de respostas por status code;
• Examples — cURL, JavaScript e Python;
• Rate Limits — limites de uso por perfil de acesso;
• Related Endpoints — navegação para rotas associadas.

O template já traz exemplos para Path Parameters e Query Parameters. O primeiro caso cobre variáveis embutidas na URL, como id; o segundo cobre filtros e paginação, como page e limit. O campo Required ajuda a distinguir o que é obrigatório do que é opcional, e a descrição deve incluir valores padrão sempre que existirem.

Na seção de respostas, os exemplos cobrem três cenários importantes:

• 200 OK para sucesso com campo success: true;
• 400 Bad Request para erro de validação com código VALIDATION_ERROR;
• 404 Not Found para ausência de recurso com código NOT_FOUND.

Os exemplos de uso em cURL, JavaScript e Python mostram como consumir a API em clientes diferentes. Isso é especialmente útil para reduzir atrito na adoção do endpoint por equipes com perfis variados.

Os Rate Limits informados no template são exemplos de política de uso:

• 1000 requisições por hora para usuários autenticados;
• 100 requisições por hora para endpoints públicos.

Na documentação real, esse campo deve refletir a política efetiva, porque limites incorretos geram expectativas erradas e, em casos de produção, podem causar falhas de integração.

7.10.3 Template de função: documentation/templates/function-docs.md

Este template documenta funções de forma estruturada. Ele é ideal para bibliotecas, SDKs e módulos de domínio que expõem funções reutilizáveis, principalmente quando a assinatura carrega tipos relevantes.

Seções do template:

• Function — nome da função;
• Description — o que ela faz;
• Signature — assinatura tipada da função;
• Parameters — tabela com nome, tipo, obrigatoriedade e descrição;
• Returns — tipo e explicação do retorno;
• Throws — exceções possíveis e quando ocorrem;
• Examples — uso básico e avançado;
• Notes — observações, advertências e boas práticas;
• See Also — links para itens relacionados.

O campo Required é importante para distinguir parâmetros obrigatórios dos opcionais. A tabela do template já ilustra esse padrão com Yes e No, e isso ajuda a evitar ambiguidades em funções com muitos argumentos.

A seção Throws deve ser usada com precisão: documente apenas erros realmente possíveis. No exemplo, aparecem Error para entrada inválida e TypeError para tipo incorreto. Em funções críticas, isso é útil para quem quer tratar falhas de forma previsível no código consumidor.

Os exemplos incluem uso simples e uso avançado com objeto de opções. Esse segundo caso é importante para mostrar como a função se comporta em cenários mais realistas, como configurações complexas, flags e parâmetros compostos.

7.11 Plugin de revisão de PR: estrutura, recursos e distribuição

7.11.1 Manifesto do plugin: pr-review/.claude-plugin/plugin.json

O arquivo de manifesto define os metadados básicos do plugin pr-review. Ele informa nome, versão, descrição, autor e licença.

{
  "name": "pr-review",
  "version": "1.0.0",
  "description": "Complete PR review workflow with security, testing, and docs",
  "author": {
    "name": "Anthropic"
  },
  "license": "MIT"
}

Esses campos são importantes para distribuição em marketplace ou instalação por pacote porque permitem identificar o plugin, controlar evolução de versão e deixar claro o licenciamento. A versão 1.0.0 sugere uma publicação estável, mas a confiança operacional ainda depende do restante do conteúdo do plugin, dos comandos e da compatibilidade com a versão do Claude Code e dos modelos suportados.

7.11.2 Visão geral do plugin: pr-review/README.md

O README descreve um fluxo completo de revisão de pull request com foco em segurança, testes, documentação e impacto de performance. Ele também inclui branding visual, configuração mínima, requisitos e um exemplo de execução.

Recursos declarados no plugin:

• análise de segurança;
• checagem de cobertura de testes;
• verificação de documentação;
• avaliação de qualidade de código;
• análise de impacto de performance.

Os comandos slash incluídos são:

• /review-pr — revisão completa do PR;
• /check-security — revisão focada em segurança;
• /check-tests — análise de cobertura de testes.

Os subagents incluídos são:

• security-reviewer — detecção de vulnerabilidades de segurança;
• test-checker — análise de cobertura e qualidade de testes;
• performance-analyzer — avaliação de impacto em performance.

O plugin também declara suporte a MCP Servers para integração com GitHub e um hook pre-review.js para validação antes da revisão.

Os requisitos listados são:

• Claude Code 1.0+;
• acesso ao GitHub;
• um repositório Git.

A configuração indicada no README usa variável de ambiente para o token:

export GITHUB_TOKEN="your_github_token"

O fluxo de uso exemplificado mostra a sequência esperada quando o usuário executa /review-pr:

1. o hook de pré-revisão valida se o ambiente é um repositório Git;
2. os dados do PR são obtidos via MCP do GitHub;
3. o subagent de segurança analisa vulnerabilidades;
4. o subagent de testes avalia cobertura e casos ausentes;
5. o subagent de performance revisa impacto algorítmico e estrutural;
6. o sistema consolida os achados;
7. um relatório final é produzido com recomendações.

O exemplo também deixa claro o tipo de saída esperada: um sumário com itens aprovados, alertas e recomendações práticas, como elevar cobertura de testes de 65% para 80% ou mais. Esse tipo de resposta é adequado para um workflow de revisão assistida por IA porque combina diagnóstico e próximo passo.

Metadados adicionais do README indicam:

• Last Updated: June 2, 2026;
• Claude Code Version: 2.1.160;
• Sources: documentação oficial e releases do Claude Code;
• Compatible Models: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5.

Esses dados são relevantes para distribuição porque ajudam a distinguir compatibilidade estável de dependências recentes de versão. Se a instalação ocorrer em um ambiente com versão mais antiga do Claude Code ou com modelos não listados, o comportamento pode variar ou os recursos podem não estar disponíveis como documentado.

7.11.3 Comando de revisão completa: pr-review/commands/review-pr.md

Este comando inicia uma revisão abrangente de pull request. Ele foi desenhado para não olhar apenas segurança ou testes isoladamente, mas combinar vários critérios em uma única análise.

O escopo descrito inclui:

1. análise de segurança;
2. verificação de cobertura de testes;
3. atualizações de documentação;
4. checagens de qualidade de código;
5. avaliação de impacto em performance.

Na prática, esse comando faz sentido quando o objetivo é uma revisão mais completa antes de merge, release ou aprovação de mudança significativa. Ele depende do restante da infraestrutura do plugin, como subagents e acesso ao GitHub, para produzir um resultado útil.

7.11.4 Comando de segurança: pr-review/commands/check-security.md

Este comando concentra a análise em riscos de segurança nas mudanças do código. Ele é apropriado para revisar alterações sensíveis, como autenticação, autorização e manipulação de dados confidenciais.

As verificações descritas são:

• autenticação e autorização;
• risco de exposição de dados;
• vulnerabilidades de injeção;
• fragilidades criptográficas;
• presença de dados sensíveis em logs.

O uso isolado desse comando é útil quando a equipe já validou testes e documentação, mas quer um foco profundo em segurança. Em mudanças críticas, porém, ele deve ser interpretado junto com revisão geral e contexto do PR, porque alguns riscos só aparecem quando se considera a interação entre módulos.

7.11.5 Comando de testes: pr-review/commands/check-tests.md

Este comando avalia cobertura e qualidade dos testes associados às mudanças. Ele é útil para descobrir áreas sem testes, casos de borda ausentes e sinais de teste superficial.

O checklist inclui:

• percentual de cobertura;
• caminhos de código sem teste;
• qualidade dos testes existentes;
• sugestão de casos faltantes;
• cobertura de edge cases.

Esse comando não se limita a medir porcentagem. Cobertura alta pode coexistir com testes frágeis, e o template já reforça a necessidade de avaliar qualidade e casos extremos. Em projetos profissionais, esse é um ponto crucial para evitar falsa sensação de segurança.

7.11.6 Subagent security-reviewer: pr-review/agents/security-reviewer.md

Este subagent é especializado em detectar vulnerabilidades de segurança. Ele declara uso das ferramentas read, grep e bash, o que sugere uma abordagem baseada em inspeção de arquivos, busca textual e execução de comandos auxiliares.

As áreas de foco são:

• problemas de autenticação e autorização;
• exposição de dados;
• ataques de injeção;
• configuração segura.

Esse agente é especialmente útil quando a revisão precisa localizar sinais de risco no código e na configuração, como permissões excessivas, segredos embutidos ou validação insuficiente de entrada.

7.11.7 Subagent test-checker: pr-review/agents/test-checker.md

Este subagent analisa cobertura e qualidade de testes. Ele usa as ferramentas read, bash e grep, o que permite verificar conteúdo de arquivos, buscar padrões de teste e executar comandos de suporte.

Os tópicos de análise são:

• percentual de cobertura;
• casos de teste ausentes;
• qualidade dos testes;
• identificação de edge cases.

Esse agente é apropriado quando se deseja separar a revisão de testes do restante da análise de PR. Isso melhora a clareza do feedback, porque o relatório final pode indicar com precisão se o problema é ausência de cobertura, má qualidade de asserções ou falta de casos de borda.

7.11.8 Subagent performance-analyzer: pr-review/agents/performance-analyzer.md

Este subagent avalia impacto de performance. Ele também usa read, grep e bash, suficiente para inspecionar implementação, procurar padrões custosos e executar verificações auxiliares.

Os aspectos analisados incluem:

• complexidade de algoritmos;
• eficiência de consultas ao banco;
• uso de memória;
• oportunidades de cache.

Esse tipo de agente é muito útil em mudanças que parecem corretas funcionalmente, mas podem introduzir regressões de desempenho, como loops desnecessários, consultas repetidas, carregamento excessivo de dados ou ausência de cache em caminhos quentes.

7.12 Hook de pré-revisão: validação antes de iniciar o fluxo

7.12.1 pr-review/hooks/pre-review.js

O hook de pré-revisão é um script Node.js executado antes da revisão do PR. Ele valida pré-requisitos mínimos para evitar iniciar uma análise em um ambiente inadequado.

#!/usr/bin/env node

/**
 * Pre-review hook
 * Runs before starting PR review to ensure prerequisites are met
 */

async function preReview() {
  console.log('Running pre-review checks...');

  // Check if git repository
  const { execSync } = require('child_process');
  try {
    execSync('git rev-parse --git-dir', { stdio: 'pipe' });
  } catch (error) {
    console.error('❌ Not a git repository');
    process.exit(1);
  }

  // Check for uncommitted changes
  try {
    const status = execSync('git status --porcelain', { encoding: 'utf-8' });
    if (status.trim()) {
      console.warn('⚠️  Warning: Uncommitted changes detected');
    }
  } catch (error) {
    console.error('❌ Failed to check git status');
    process.exit(1);
  }

  console.log('✅ Pre-review checks passed');
}

preReview().catch(error => {
  console.error('Pre-review hook failed:', error);
  process.exit(1);
});

O comportamento do script é direto:

• ele imprime uma mensagem inicial;
• verifica se o diretório atual é um repositório Git usando git rev-parse --git-dir;
• se não for Git, encerra com erro e status não zero;
• consulta git status --porcelain para detectar alterações não commitadas;
• se houver mudanças, emite apenas um aviso, sem bloquear o fluxo;
• se tudo estiver correto, confirma que os checks passaram.

Esse hook é importante porque evita revisar código em um contexto inconsistente. Por exemplo, se houver mudanças locais não commitadas, a revisão pode não refletir exatamente o estado do PR. O hook não impede esse cenário, mas avisa o usuário para que ele decida se continua ou ajusta o ambiente.

Limitações práticas:

• ele só confirma a presença de Git, não a existência de um branch remoto específico;
• ele não valida se o PR atual está corretamente referenciado;
• ele não faz inspeção de qualidade do código, apenas pré-checagens de ambiente.

7.13 Configuração MCP para GitHub no plugin de revisão

7.13.1 pr-review/mcp/github-config.json

Este arquivo repete a configuração do servidor MCP GitHub para o contexto do plugin de PR review. Ele segue o mesmo padrão de execução via npx e usa GITHUB_TOKEN como credencial.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Na prática, essa configuração é a base para o plugin conseguir buscar dados do repositório, PRs e metadados do GitHub. Como se trata de um componente dependente de ambiente, os principais problemas costumam ser:

• token não exportado no shell;
• token com permissões insuficientes;
• npx indisponível ou bloqueado;
• ambiente sem acesso à internet ou ao registry necessário;
• configuração localizada no arquivo errado para o contexto de execução.

Para distribuição, isso significa que o plugin não é apenas um pacote de comandos: ele depende de infraestrutura externa para funcionar plenamente. Em um curso profissional, esse é um ponto importante, porque recursos de marketplace e distribuição devem sempre deixar claro o que é empacotado localmente e o que depende de serviços autenticados, como o GitHub.

8 Módulo — Checkpoints, rewind e experimentação segura

8.1 Checkpoints e rewind: como experimentar com segurança no Claude Code

Checkpoints são instantâneos do estado da sua sessão no Claude Code. Eles permitem voltar para um ponto anterior da conversa e, dependendo da opção escolhida, também restaurar o código alterado. Na prática, isso reduz o risco de explorar soluções agressivas, testar hipóteses diferentes e recuperar um estado bom sem depender de refazer tudo manualmente.

Esse recurso é especialmente útil quando você quer comparar abordagens, desfazer um refactor que deu errado ou continuar um trabalho complexo sem perder o contexto anterior.

8.1.1 O que um checkpoint guarda

Um checkpoint registra o estado da sessão naquele momento, incluindo:

• todas as mensagens trocadas até ali;
• modificações feitas em arquivos;
• histórico de uso de ferramentas;
• contexto da sessão.

Isso significa que o rewind não é apenas “voltar a conversa”; ele pode reconstruir o estado do trabalho de forma muito mais completa.

8.1.2 Conceitos principais

• Checkpoint: foto do estado da conversa, dos arquivos e do contexto.
• Rewind: retorno a um checkpoint anterior, descartando o que veio depois, conforme a opção escolhida.
• Branch point: checkpoint usado como base para testar caminhos diferentes a partir do mesmo ponto.

8.1.3 Como acessar os checkpoints

Há duas formas principais de abrir a interface de checkpoints:

• Atalho de teclado: pressione Esc duas vezes (Esc + Esc).
• Comando de barra: use /rewind ou o alias /checkpoint.

# Abrir a interface de rewind
/rewind

# Alias equivalente
/checkpoint

8.1.4 Opções disponíveis ao fazer rewind

Ao selecionar um checkpoint, o Claude Code oferece seis ações. Cada uma tem comportamento diferente e serve para um tipo específico de recuperação ou experimentação.

1. Restaurar código e conversa: reverte arquivos e mensagens para o estado daquele checkpoint. Use quando você quer voltar exatamente para onde estava.
2. Restaurar conversa: volta apenas as mensagens, mantendo o código atual. É útil quando a conversa se desviou, mas você quer preservar as mudanças em disco.
3. Restaurar código: reverte somente os arquivos, mantendo o histórico completo da conversa. Serve quando a linha de raciocínio ainda é boa, mas a implementação precisa voltar atrás.
4. Resumir a partir daqui: compacta a conversa do ponto selecionado em diante em um resumo gerado por IA para economizar contexto. As mensagens anteriores continuam intactas. Nenhum arquivo no disco é alterado. As mensagens originais permanecem no transcript da sessão. Você pode orientar o resumo para focar temas específicos.
5. Resumir até aqui: faz o oposto do item anterior, compactando tudo antes do ponto selecionado e preservando as mensagens depois dele. Juntando essa opção com “Resumir a partir daqui”, você ganha compactação bidirecional e direcionada do contexto. Também não altera arquivos no disco e preserva as mensagens originais no transcript.
6. Não importa: cancela a operação e mantém o estado atual.

Depois de restaurar a conversa ou resumir, o prompt original da mensagem escolhida volta para o campo de entrada. Isso permite reenviar o texto como estava ou editá-lo antes de continuar.

Observação importante: a partir da versão v2.1.191+, /clear deixou de ser uma fronteira rígida. Agora é possível usar /rewind para voltar para um checkpoint criado antes de um /clear. Na prática, limpar a conversa não apaga de forma permanente o estado que existia antes disso, desde que o checkpoint correspondente ainda esteja disponível.

8.1.5 Criação automática de checkpoints

O Claude Code cria checkpoints automaticamente, sem exigir ação manual do usuário.

• Cada prompt do usuário gera um novo checkpoint.
• Os checkpoints persistem entre sessões, então não desaparecem ao encerrar e reabrir o ambiente.
• Há limpeza automática após 30 dias para evitar crescimento ilimitado de armazenamento.

Esse comportamento garante que você sempre tenha um ponto de retorno recente, e também checkpoints mais antigos, enquanto ainda estiverem dentro da janela de retenção.

8.1.6 Quando checkpoints são mais úteis

• explorar abordagens diferentes sem medo de quebrar algo irreversivelmente;
• recuperar rapidamente um estado que funcionava;
• comparar duas ou mais soluções lado a lado;
• testar refactors grandes com segurança;
• voltar atrás após um erro de implementação ou de estratégia.

8.1.7 Padrões práticos de uso

Em vez de pensar em checkpoints como “backup”, pense neles como pontos de ramificação de experimentação.

• Exploração em bifurcação: você faz uma primeira tentativa, volta ao ponto inicial e testa outra abordagem para comparar resultados.
• Refatoração segura: você altera o código, executa testes e, se houver regressão, volta ao checkpoint anterior.
• Recuperação de erro: ao perceber que a última alteração foi ruim, você retorna ao último estado bom e ajusta a estratégia.

8.1.8 Exemplo prático: explorando duas abordagens

Usuário: Vamos adicionar uma camada de cache na API

Claude: Vou implementar cache com Redis nos endpoints...
[altera o código no checkpoint A]

Usuário: Na verdade, quero testar cache em memória

Claude: Vou voltar para explorar outra abordagem...
[usuário pressiona Esc + Esc e retorna ao checkpoint A]
[implementa cache em memória no checkpoint B]

Usuário: Agora consigo comparar as duas opções

8.1.9 Exemplo prático: recuperando-se de um erro

Usuário: Refatore o módulo de autenticação para usar JWT

Claude: Vou refatorar o módulo...
[faz mudanças extensas]

Usuário: Isso quebrou a integração OAuth. Vamos voltar.

Claude: Vou ajudar a retornar para antes da refatoração...
[usuário pressiona Esc + Esc e seleciona o checkpoint anterior à refatoração]

Usuário: Agora vamos tentar uma abordagem mais conservadora

8.1.10 Exemplo prático: experimentação controlada

Usuário: Vamos reescrever isso em estilo funcional
[checkpoint criado antes do experimento]

Claude: [faz mudanças experimentais]

Usuário: Os testes falharam. Vamos fazer rewind.
[usuário pressiona Esc + Esc e volta ao checkpoint]

Claude: Reverti as mudanças. Vamos tentar um caminho diferente.

8.1.11 Exemplo prático: criar ramificações de solução

Usuário: Quero comparar dois designs de banco de dados
[checkpoint inicial "Start"]

Claude: Vou implementar o primeiro design...
[implementa o Schema A]

Usuário: Agora quero voltar e testar a segunda opção
[usuário pressiona Esc + Esc e retorna ao "Start"]

Claude: Agora vou implementar o Schema B...
[implementa o Schema B]

Usuário: Ótimo, agora tenho os dois schemas para decidir

8.1.12 Detalhes exibidos em cada checkpoint

Ao abrir o navegador de checkpoints, você vê uma lista dos estados disponíveis, geralmente com timestamps. Cada item pode mostrar:

• data e hora em que foi criado;
• arquivos modificados naquele ponto;
• quantidade de mensagens na conversa;
• ferramentas utilizadas.

Esses detalhes ajudam a identificar rapidamente o ponto certo de retorno, principalmente em sessões longas.

8.1.13 Retenção e limpeza

O Claude Code gerencia checkpoints automaticamente:

• cada prompt do usuário gera um novo checkpoint;
• os checkpoints antigos ficam retidos por até 30 dias;
• a limpeza automática evita crescimento indefinido de armazenamento.

Na prática, isso significa que você tem um histórico de trabalho útil sem precisar fazer manutenção manual constante.

8.1.14 Boas práticas

Como os checkpoints já são automáticos, o seu foco deve ser escolher bem quando voltar e qual opção de rewind usar.

• Faça revisão visual da lista antes de reverter, para não escolher um ponto errado.
• Use rewind para explorar caminhos diferentes, especialmente quando houver mais de uma solução plausível.
• Mantenha checkpoints como comparação entre alternativas.
• Entenda o efeito de cada opção: restaurar código e conversa, restaurar só conversa, restaurar só código ou resumir.

Evite usar checkpoints como única forma de proteção. Eles são excelentes para experimentação, mas não substituem práticas formais de versionamento.

8.1.15 O que não fazer

• não dependa de checkpoints para preservar código de forma permanente;
• não espere que eles capturem alterações feitas fora do Claude Code;
• não trate checkpoints como substitutos de commits no git.

8.1.16 Configuração

Checkpoints são comportamento padrão integrado ao Claude Code e não exigem ativação manual. Todo prompt do usuário já cria um checkpoint automaticamente.

A única configuração relacionada é cleanupPeriodDays, que define por quantos dias o histórico de sessões e checkpoints será mantido.

{
  "cleanupPeriodDays": 30
}

• cleanupPeriodDays: número de dias para reter histórico e checkpoints; valor padrão: 30.

Atualização da v2.1.117: o parâmetro cleanupPeriodDays passou a controlar a retenção de quatro caches em disco, não apenas checkpoints:

• checkpoints de sessão;
• ~/.claude/tasks/ — listas persistentes de tarefas;
• ~/.claude/shell-snapshots/ — snapshots capturados do ambiente de shell;
• ~/.claude/backups/ — backups em rotação de configurações e do arquivo CLAUDE.md.

Ou seja: um único ajuste aplica a mesma política de expurgo aos quatro diretórios, com a mesma janela de retenção.

8.1.17 Limitações importantes

• Alterações de comandos Bash não são rastreadas: operações como rm, mv e cp no sistema de arquivos não entram no checkpoint.
• Mudanças externas não são capturadas: edições feitas fora do Claude Code, como no editor ou terminal, não fazem parte do snapshot.
• Não substituem controle de versão: use git para mudanças permanentes, auditáveis e compartilháveis.

Na prática, checkpoints são ótimos para estado conversacional e experimentação dentro da sessão, mas não devem ser tratados como backup total do sistema.

8.1.18 Troubleshooting

Quando algo não parece correto, os problemas mais comuns costumam ser estes:

8.1.19 Checkpoint ausente

Problema: o checkpoint esperado não aparece na lista.

Possíveis causas e ações:

• verifique se os checkpoints foram limpos automaticamente;
• confirme se há espaço em disco suficiente;
• ajuste cleanupPeriodDays para um valor maior, se você precisar manter histórico por mais tempo;
• lembre que o padrão é 30 dias.

8.1.20 Falha ao fazer rewind

Problema: não é possível voltar para o checkpoint selecionado.

Possíveis causas e ações:

• verifique se há mudanças não commitadas que entrem em conflito;
• considere que o checkpoint pode estar corrompido;
• teste outro checkpoint mais próximo do estado desejado.

8.1.21 Integração com git

Checkpoints e git resolvem problemas diferentes e funcionam melhor juntos.

• Git é para mudanças permanentes, versionadas e compartilháveis.
• Checkpoints são para explorar, comparar e recuar rapidamente durante a sessão.

Comparação prática:

• Escopo: git cobre o sistema de arquivos e o histórico do projeto; checkpoints cobrem conversa + arquivos da sessão.
• Persistência: git é permanente; checkpoints são baseados em sessão e retenção.
• Granularidade: git usa commits; checkpoints podem ser criados em qualquer ponto de interação.
• Velocidade: checkpoints são instantâneos; commits são mais lentos.
• Compartilhamento: git é compartilhável; checkpoints têm alcance limitado.

Fluxo recomendado:

1. use checkpoints para experimentar rapidamente;
2. quando encontrar a solução certa, consolide em git;
3. crie um checkpoint antes de operações importantes de git;
4. faça commit do estado que ficou aprovado.

8.1.22 Fluxo básico para começar

1. trabalhe normalmente; o Claude Code cria checkpoints automaticamente;
2. quando quiser voltar, pressione Esc duas vezes ou use /rewind;
3. escolha o checkpoint desejado na lista;
4. selecione o que restaurar: código, conversa, ambos, ou um resumo;
5. continue a partir do ponto recuperado.

8.1.23 Atalhos úteis

• Esc + Esc: abre o navegador de checkpoints;
• /rewind: abre os checkpoints por comando;
• /checkpoint: alias de /rewind.

8.1.24 Monitoramento de contexto: saber quando é hora de fazer rewind

Checkpoints permitem voltar no tempo, mas ainda existe uma pergunta importante: quando vale a pena fazer isso? Conforme a conversa cresce, a janela de contexto vai se enchendo e a qualidade do modelo pode cair sem aviso. Você pode acabar produzindo código com um modelo já degradado, sem perceber.

Uma solução prática citada no ecossistema é o projeto cc-context-stats, que adiciona zonas de contexto em tempo real à barra de status do Claude Code. Ele indica sua posição dentro da janela de contexto, com faixas como:

• Plan em verde: zona segura para planejar e codar;
• Code em amarelo: zona em que é melhor evitar iniciar novos planos;
• Dump em laranja: hora de finalizar e fazer rewind.

Quando a zona muda, o sinal prático é simples: faça checkpoint, limpe o excesso e recomece com contexto fresco, em vez de insistir com uma sessão já degradada.

8.1.25 Exemplos adicionais de uso real

Os exemplos a seguir mostram como checkpoints ajudam em cenários comuns de desenvolvimento profissional.

8.1.26 Migração de banco de dados

Usuário: Vamos fazer uma migração direta de MySQL para PostgreSQL
[Checkpoint A criado automaticamente]

Claude: Vou implementar a migração direta...
[altera driver de banco, consultas e esquema]

Usuário: Rode os testes
[Checkpoint B criado automaticamente]

Claude: Executando testes...
❌ 15 testes falhando - problemas no pool de conexões

Usuário: Essa abordagem não está boa. Vamos tentar dual-write.

[usuário pressiona Esc + Esc, escolhe o Checkpoint A e seleciona "Restaurar código e conversa"]

Usuário: Agora implemente um padrão de dual-write, gravando nos dois bancos

Claude: Vou implementar a migração gradual com dual-write...
[cria camada de gravação dupla e estratégia de migração progressiva]

Usuário: Rode os testes

Claude: Executando testes...
✅ Todos os testes passando

Usuário: A abordagem dual-write é bem mais segura. Vamos commitar isso.

8.1.27 Otimização de performance

Usuário: Vamos otimizar o tempo de resposta da API. Atual: 450ms
[Checkpoint "Baseline" criado automaticamente]

Claude: Vou adicionar cache de consultas no banco...
[implementa Redis caching]

Usuário: Rode os testes de performance

Claude: Resultado: 280ms em média (melhoria de 38%)

Usuário: Quero tentar outra abordagem.
[usuário pressiona Esc + Esc, escolhe "Baseline" e usa "Restaurar código e conversa"]

Usuário: Tente otimização de queries do banco

Claude: Vou otimizar as consultas...
[adiciona índices e corrige N+1]

Usuário: Rode os testes de performance

Claude: Resultado: 180ms em média (melhoria de 60%)

Usuário: Quero testar uma terceira alternativa.
[usuário pressiona Esc + Esc, volta ao "Baseline" e escolhe "Restaurar código e conversa"]

Usuário: Tente compressão de resposta e CDN

Claude: Vou adicionar compressão e CDN...
[implementa gzip e configura CDN]

Usuário: Rode os testes de performance

Claude: Resultado: 320ms em média (melhoria de 29%)

Usuário: A otimização de queries foi a melhor. Vamos voltar e combinar com cache.
[usuário pressiona Esc + Esc, escolhe o checkpoint após a otimização de queries e seleciona "Restaurar código e conversa"]

Usuário: Agora adicione Redis caching em cima dessas queries otimizadas

Claude: [adiciona Redis caching sobre as queries já otimizadas]

Usuário: Rode os testes de performance

Claude: Resultado: 95ms em média (melhoria de 79%)

Usuário: Perfeito. Essa é a solução final. Vamos commitar.

8.1.28 Iteração de interface e experiência do usuário

Usuário: Vamos redesenhar o dashboard com sidebar
[Checkpoint "Start" criado automaticamente]

Claude: [implementa layout com sidebar]

Usuário: Mostre um screenshot

Claude: [mostra screenshot]

Usuário: A sidebar ficou apertada. Vamos tentar navegação no topo.
[usuário pressiona Esc + Esc, retorna ao "Start" e escolhe "Restaurar código e conversa"]

Usuário: Tente layout com navegação superior

Claude: [implementa top navigation]

Usuário: Mostre um screenshot

Claude: [mostra screenshot]

Usuário: Melhor, mas vamos tentar uma grade baseada em cards.
[usuário pressiona Esc + Esc, volta ao "Start" e escolhe "Restaurar código e conversa"]

Usuário: Tente um layout em grid com cards

Claude: [implementa card grid]

Usuário: Mostre um screenshot

Claude: [mostra screenshot]

Usuário: Ficou ótimo. Mas dá para combinar o topo com a grade de cards?
[usuário pressiona Esc + Esc, escolhe o checkpoint após a grade e seleciona "Restaurar código e conversa"]

Usuário: Adicione navegação superior ao layout em grid

Claude: [adiciona navegação superior ao card grid]

Usuário: Perfeito. Esse será o design final.

8.1.29 Debug com hipóteses concorrentes

Usuário: Existe um vazamento de memória no aplicativo
[Checkpoint "Before debugging" criado automaticamente]

Claude: Vou investigar...
[analisa o código]

Usuário: Acho que está nos event listeners. Vamos corrigir isso.

Claude: [corrige a limpeza dos listeners]

Usuário: Rode o profiler de memória

Claude: Ainda está vazando memória - os listeners não eram o problema

Usuário: Vamos voltar e testar outra hipótese.
[usuário pressiona Esc + Esc, escolhe "Before debugging" e seleciona "Restaurar código e conversa"]

Usuário: Talvez sejam as conexões de banco?

Claude: [corrige o pooling de conexões]

Usuário: Rode o profiler de memória

Claude: Ainda vaza - não era isso

Usuário: Vamos voltar e tentar outro caminho.
[usuário pressiona Esc + Esc, volta ao "Before debugging" e escolhe "Restaurar código e conversa"]

Usuário: Vamos verificar referências circulares

Claude: [encontra e corrige referências circulares no cache]

Usuário: Rode o profiler de memória

Claude: ✅ Vazamento de memória corrigido. As referências circulares na camada de cache eram a causa.

Usuário: Excelente. Vamos commitar essa correção.

8.1.30 Evolução de design de API

Usuário: Crie uma API REST para nossa plataforma de blog
[Checkpoint "Before API design" criado automaticamente]

Claude: [cria uma API CRUD básica]

Usuário: Está simples demais. Adicione paginação e filtro.

Claude: [adiciona paginação e filtragem]

Usuário: Precisamos de relacionamentos de recursos melhores.

Claude: [implementa links HATEOAS]

Usuário: Na verdade, vamos testar GraphQL em vez de REST.
[usuário pressiona Esc + Esc, volta ao "Before API design" e escolhe "Restaurar código e conversa"]

Usuário: Em vez disso, implemente uma API GraphQL para nossa plataforma de blog

Claude: [implementa GraphQL]

Usuário: Acho que REST é melhor para o nosso caso.
[usuário pressiona Esc + Esc, escolhe o checkpoint após HATEOAS e seleciona "Restaurar código e conversa"]

Usuário: Vamos finalizar a abordagem REST.

8.1.31 Gestão de configuração

Usuário: Mova a configuração para variáveis de ambiente
[Checkpoint "Original config" criado automaticamente]

Claude: [implementa configuração via env vars]

Usuário: Teste no ambiente de desenvolvimento

Claude: Funciona localmente, mas há problemas na produção

Usuário: Quero tentar outra abordagem.
[usuário pressiona Esc + Esc, escolhe "Original config" e seleciona "Restaurar código e conversa"]

Usuário: Tente um arquivo de configuração com validação

Claude: [implementa configuração YAML com validação por JSON Schema]

Usuário: Teste no ambiente de desenvolvimento

Claude: ✅ Funciona bem e gera erros de validação claros

Usuário: Também podemos suportar variáveis de ambiente para valores sensíveis?

Claude: [adiciona override por env vars para segredos]

Usuário: Teste o deploy

Claude: ✅ Todos os ambientes funcionando corretamente

Usuário: Perfeito. Agora está pronto para produção.

8.1.32 Estratégia de testes

Usuário: Adicione testes unitários para o módulo de auth
[Checkpoint criado automaticamente]

Claude: [adiciona testes unitários com Jest]

Usuário: Rode os testes

Claude: 45 testes passando, cobertura de 78%

Usuário: Adicione testes de integração também

Claude: [adiciona testes de integração]

Usuário: Rode os testes

Claude: 89 testes passando, cobertura de 92%, mas está lento (3 minutos)

Usuário: Os testes estão lentos demais. Vamos otimizar.

Claude: [otimiza a preparação dos testes e adiciona execução paralela]

Usuário: Rode os testes

Claude: 89 testes passando, cobertura de 92%, 35 segundos

Usuário: Ótimo. Agora adicione testes E2E para os fluxos críticos

Claude: [adiciona testes E2E com Playwright]

Usuário: Rode todos os testes

Claude: 112 testes passando, cobertura de 94%, 2 minutos

Usuário: Excelente equilíbrio entre cobertura e velocidade!

8.1.33 Resumindo uma conversa longa

Depois de uma sessão extensa, você pode usar a opção de resumo para reduzir a pressão sobre a janela de contexto sem perder a linha de raciocínio principal.

Usuário: [Depois de 20+ mensagens de debug e exploração]

[usuário pressiona Esc + Esc, seleciona um checkpoint antigo e escolhe "Summarize from here"]
[opcionalmente informa: "Concentre-se no que testamos e no que funcionou"]

Claude: [gera um resumo da conversa a partir daquele ponto]
[as mensagens originais continuam preservadas no transcript]
[o resumo substitui a conversa visível, reduzindo o uso de contexto]

Usuário: Agora vamos continuar com a abordagem que funcionou.

8.1.34 Resumo dos pontos mais importantes

• checkpoints são automáticos; não há necessidade de salvar manualmente;
• Esc + Esc e /rewind são as formas de acessar o navegador de checkpoints;
• escolha com cuidado entre restaurar código, conversa, ambos ou resumir;
• checkpoints tornam seguro testar mudanças radicais e reverter quando necessário;
• git continua sendo essencial para versionamento final e auditável;
• em sessões longas, usar resumo ajuda a manter o contexto administrável.

8.1.35 Informações de compatibilidade e versão

Este comportamento é suportado nas versões documentadas do Claude Code, com destaque para as mudanças de retenção introduzidas na v2.1.117 e para o tratamento de /clear como não sendo mais uma fronteira rígida a partir da v2.1.191+.

Os modelos compatíveis informados para esse conjunto de funcionalidades incluem:

• Claude Sonnet 5
• Claude Sonnet 4.6
• Claude Opus 4.8
• Claude Haiku 4.5

9 Módulo — Recursos avançados e operação profissional

9.1 Recursos avançados

Os recursos avançados do Claude Code ampliam o uso básico com planejamento, raciocínio aprofundado, automação, controle de permissões, execução em segundo plano, gerenciamento de sessão e integrações com ambiente local, navegador e nuvem. Eles são úteis quando a tarefa deixa de ser “editar um arquivo” e passa a envolver múltiplas etapas, várias sessões, validações, revisão humana, CI/CD ou coordenação de agentes.

Nem tudo aqui tem o mesmo nível de maturidade: alguns recursos são estáveis, outros são pesquisa prévia, e alguns dependem da versão, do modelo, do plano ou do provedor de acesso.

9.2 Visão geral

Os recursos avançados do Claude Code servem para resolver problemas mais longos e mais arriscados sem perder controle. Em vez de responder apenas com uma alteração imediata, o sistema pode planejar, pensar por mais tempo, executar tarefas em paralelo, pedir aprovação em pontos críticos, rodar sem interface, manter estado entre sessões e até distribuir trabalho entre subagentes.

• Planning Mode: cria um plano antes de editar, permitindo revisão prévia.
• Ultraplan: transfere o planejamento para a nuvem no Claude Code on the web.
• Extended Thinking: usa mais tempo e orçamento de raciocínio para problemas complexos.
• Auto Mode: modo de permissões com classificador de segurança em segundo plano. É Research Preview.
• Background Tasks: executa tarefas longas sem travar a conversa.
• Monitor Tool: reage a eventos em streams de stdout, evitando polling com sleep.
• Dynamic Workflows: orquestra vários subagentes de forma determinística.
• Scheduled Tasks: agenda prompts recorrentes ou lembretes pontuais.
• Permission Modes: controla o que pode acontecer sem confirmação.
• Print Mode: executa o Claude sem interação, ideal para automação e CI/CD.
• Session Management: retoma, renomeia e bifurca sessões.
• Interactive Features: atalhos, entrada multiline e histórico.
• Voice Dictation: entrada por voz com suporte a STT em 20 idiomas.
• Channels: servidores MCP podem empurrar mensagens para sessões ativas.
• Chrome Integration, Remote Control, Web Sessions e Desktop App: diferentes formas de operar no navegador e na aplicação desktop.
• Task List e Prompt Suggestions: organização persistente e sugestões inteligentes.
• Git Worktrees e Sandboxing: isolamento operacional.
• Managed Settings: distribuição corporativa.
• Agent Teams: coordenação entre agentes.
• Configuration and Settings: personalização por arquivos JSON e variáveis de ambiente.

9.3 Planning Mode

O Planning Mode faz o Claude primeiro analisar o problema e montar um plano detalhado; só depois, se você aprovar, ele parte para a implementação. Isso é especialmente valioso quando a mudança é grande, arriscada ou espalhada por vários arquivos.

9.3.1 Como funciona

O fluxo é em duas fases. Na fase de planejamento, o Claude lê o contexto, identifica dependências, sugere etapas e aponta riscos. Na fase de implementação, ele executa o plano aprovado. Esse padrão reduz retrabalho e ajuda a expor dúvidas antes de modificar o código.

9.3.2 Quando usar

• Refatorações grandes com muitos arquivos.
• Implementação de funcionalidades novas.
• Mudanças arquiteturais.
• Migrações de banco de dados.
• Redesenho de APIs.

9.3.3 Quando evitar

• Correções pequenas e pontuais.
• Ajustes de formatação.
• Edições em um único arquivo sem complexidade.
• Perguntas rápidas de leitura ou diagnóstico.

9.3.4 Como ativar

Você pode ativar o modo de planejamento por comando de barra, por flag de CLI, por configuração padrão ou por atalho de teclado.

/plan Implement user authentication system
claude --permission-mode plan

{
  "permissions": {
    "defaultMode": "plan"
  }
}

• Shift + Tab alterna entre os modos de permissão na interface interativa.
• Alt + M faz a mesma alternância no Windows e Linux.
• Ctrl + G abre o plano atual no seu editor externo para ajustes mais extensos.

9.3.5 Benefícios práticos

• Estrutura melhor da implementação.
• Revisão antes de mudar o código.
• Detecção antecipada de riscos.
• Separação clara entre preparação e execução.

9.3.6 Exemplo de uso

Ao pedir para adicionar um sistema de notificações em tempo real, o Claude pode propor fases como infraestrutura, backend, frontend e testes. O plano costuma indicar tempo estimado, quantidade de arquivos alterados e arquivos novos a criar. Depois ele pede confirmação, como yes, no ou modify plan.

User: /plan Add a real-time notification system

Claude: I'll create a plan for implementing real-time notifications.

Implementation Plan
Phase 1: Infrastructure Setup
1. Install WebSocket libraries (socket.io)
2. Set up WebSocket server
3. Configure connection management

Phase 2: Backend Implementation
4. Create notification service
5. Implement notification queue
6. Add database schema for notifications
7. Create API endpoints

Phase 3: Frontend Integration
8. Set up WebSocket client
9. Create notification UI components
10. Implement notification state management
11. Add notification permissions

Phase 4: Testing & Deployment
12. Write unit tests
13. Write integration tests
14. Update documentation
15. Deploy to staging

Estimated time: 3-4 hours
Files to modify: 12
New files to create: 8

Ready to proceed? (yes/no/modify plan)

Se você pedir alteração, o plano é ajustado antes da execução. Isso é útil quando uma etapa, como fila assíncrona, deve ser deixada para depois.

9.3.7 Configuração e comportamento por versão

O modo de planejamento pode ser usado com o alias de modelo opusplan, que usa Opus para planejar e Sonnet para executar. Esse comportamento é útil quando você quer raciocínio mais forte no planejamento sem necessariamente manter o custo mais alto durante toda a execução.

claude --model opusplan "design and implement the new API"

Desde a versão v2.1.112, os arquivos de plano passaram a receber nomes baseados no prompt que os gerou, em vez de nomes aleatórios. Isso facilita encontrar e reutilizar planos.

Na v2.1.136, o bloqueio de escrita no Planning Mode ficou mais rígido: qualquer gravação em arquivo é bloqueada de forma incondicional, inclusive quando existe uma regra permissiva Edit(...) em permissions.allow. Antes, esse tipo de regra podia abrir uma exceção; agora isso não acontece. Se um fluxo dependia desse comportamento antigo, você precisa sair do modo de planejamento antes de editar.

9.4 Ultraplan

Ultraplan é um recurso de Research Preview que envia a tarefa de planejamento do terminal local para uma sessão do Claude Code on the web, já em modo de planejamento. O Claude pesquisa o repositório na nuvem, elabora o plano com uma interface mais rica e depois você decide se a execução acontece no próprio ambiente web ou se volta para o terminal local.

9.4.1 Quando vale a pena usar

• Quando a revisão precisa de uma superfície melhor que o terminal, com comentários inline, reações por emoji, barra lateral de outline e histórico persistente.
• Quando você quer continuar codando localmente enquanto o Claude faz a pesquisa na nuvem.
• Quando o plano precisa ser compartilhado com stakeholders antes da execução.

9.4.2 Requisitos e limitações

• É preciso ter uma conta no Claude Code on the web.
• É necessário um repositório GitHub, porque a sessão cloud clona o repositório para trabalhar em código real.
• Não está disponível em Amazon Bedrock, Google Cloud Vertex AI nem Microsoft Foundry.
• Requer Claude Code v2.1.91 ou superior.

9.4.3 Como iniciar

Há três formas de disparar o recurso: comando explícito, palavra-chave no prompt normal ou transferência a partir de um plano local já gerado.

/ultraplan migrate the auth service from sessions to JWTs

• Comando: /ultraplan <prompt>
• Palavra-chave: incluir ultraplan em um prompt comum pode redirecionar a tarefa para a nuvem.
• A partir de plano local: no diálogo de aprovação, escolha a opção para refinar com Ultraplan no Claude Code on the web.

A partir da v2.1.101, a primeira invocação cria automaticamente o ambiente cloud, sem configuração manual e sem esperar warm-up de container.

9.4.4 Status e execução

Durante a execução, o status aparece como indicações textuais na interface:

• ◇ ultraplan: o Claude está pesquisando o código e redigindo o plano.
• ◇ ultraplan needs your input: há uma pergunta de esclarecimento; você precisa abrir o link da sessão no navegador.
• ◆ ultraplan ready: o plano está pronto para revisão.

Quando o plano fica pronto, existem duas rotas de execução. Você pode aprovar no navegador e deixar o Claude implementar na própria sessão cloud, o que pode até abrir um pull request pela interface web. Ou pode escolher “Approve plan and teleport back to terminal” para trazer a execução para o ambiente local.

Ao “teleportar” para o terminal, surgem três opções:

• Implement here: executa o plano aprovado na sessão atual do terminal.
• Start new session: abre uma sessão nova no mesmo diretório de trabalho.
• Cancel: salva o plano em um arquivo para retomada futura.

Há uma limitação importante: o Remote Control se desconecta quando Ultraplan começa. Os dois recursos compartilham a interface claude.ai/code, então apenas um pode estar ativo por vez.

9.5 Extended Thinking

Extended Thinking permite que o Claude gaste mais tempo raciocinando antes de responder. Na prática, isso melhora a qualidade quando o problema exige decomposição cuidadosa, comparação de alternativas, análise de trade-offs e consideração de casos de borda.

9.5.1 O que esse modo faz

Esse recurso não é apenas “responder mais devagar”; ele incentiva um raciocínio passo a passo. O Claude pode quebrar um problema complexo em partes menores, testar caminhos diferentes mentalmente e avaliar consequências antes de propor uma resposta.

9.5.2 Como ativar

Você pode alternar o modo com atalho de teclado, ajustar a configuração por variável de ambiente, usar a flag de CLI ou o comando /effort.

• Option + T no macOS.
• Alt + T no Windows e Linux.
• /effort high dentro da interface.
• claude --effort high na linha de comando.

export MAX_THINKING_TOKENS=16000
export CLAUDE_CODE_EFFORT_LEVEL=high
claude --effort high "complex architectural review"
/effort high

9.5.3 Budgets e níveis de esforço

O orçamento de raciocínio pode ser ajustado por token budget e por nível de esforço.

• MAX_THINKING_TOKENS: define um teto customizado para o raciocínio.
• CLAUDE_CODE_EFFORT_LEVEL: define o nível de esforço de raciocínio.

Os níveis variam por modelo e versão. Em Opus 4.8, Opus 4.7, Opus 4.6 e Sonnet 4.6, os níveis suportados são low, medium, high, xhigh e max, com diferenças entre versões quanto ao padrão e disponibilidade. O nível xhigh existe em Opus 4.8 e Opus 4.7; em Opus 4.6 e Sonnet 4.6 ele faz fallback para high. O nível max é sessão-local e funciona em Opus 4.8, Opus 4.7, Opus 4.6 e Sonnet 4.6. O modelo Haiku 4.5 não possui níveis de esforço.

Há também um orçamento fixo para outros modelos, chegando a até 31.999 tokens. Isso significa que nem todo modelo usa os mesmos controles de profundidade.

9.5.4 Comportamento por versão e observações importantes

• Opus 4.8 e Opus 4.7 têm janela nativa de contexto de 1 milhão de tokens.
• Em v2.1.117, foi corrigida a contagem de contexto do Opus 4.7 para essa janela de 1M; antes disso, /context podia contar errado como se a janela fosse de 200K e disparar compactação automática cedo demais.
• Desde v2.1.129, /context mostra a visualização apenas na interface; a visualização ASCII não entra mais no contexto da conversa, economizando cerca de 1,6k tokens por chamada.
• No v2.1.154, o sistema passou a usar um system prompt mais enxuto como padrão para todos os modelos, exceto Haiku, Sonnet e Opus 4.7 e anteriores, reduzindo overhead de tokens base no Opus 4.8.
• Para assinantes Pro/Max em Opus 4.6 e Sonnet 4.6, o esforço padrão subiu de medium para high na v2.1.117.

9.5.5 Palavra de ativação e menu

O termo ultrathink no prompt aciona o modo de raciocínio profundo. É importante não confundir isso com ultracode, que aparece no menu /effort e não é um nível de esforço do modelo. ultracode envia xhigh e também faz o Claude orquestrar workflows dinâmicos, sendo um comportamento de sessão.

9.5.6 Exemplo prático

Quando você pede ao Claude para comparar microserviços e monólito para um e-commerce, o raciocínio expandido pode incluir análise de contexto, prós e contras de cada abordagem, fatores de decisão e uma recomendação fundamentada.

User: ultrathink Should we use microservices or a monolith for our e-commerce platform?

Claude: Let me think through this architectural decision carefully...

Context Analysis
- Team size: 5 developers
- Expected traffic: 10k daily users initially
- Need to scale to 100k+ users
- Limited DevOps resources
- 6-month timeline to MVP

Approach 1: Microservices
Pros:
+ Independent scaling
+ Technology flexibility
+ Team independence
+ Fault isolation

Cons:
- Operational complexity
- Network overhead
- Distributed tracing needed
- Requires DevOps expertise
- Slower initial development

Approach 2: Monolith
Pros:
+ Simpler deployment
+ Faster initial development
+ Easier debugging
+ Lower operational overhead
+ Single codebase

Cons:
- Scaling challenges later
- All-or-nothing deployments
- Technology lock-in
- Potential for tight coupling

Decision Factors
1. Team size (5 devs) → Favors monolith
2. DevOps resources (limited) → Favors monolith
3. Timeline (6 months) → Favors monolith
4. Future scale (100k users) → Achievable with monolith + caching
5. Complexity budget → Limited

Recommendation
Start with a modular monolith:
- Single deployment unit
- Clear module boundaries
- Clean interfaces between modules
- Prepare for future extraction to microservices if needed

Migration path: When you reach 50k+ users or specific modules need independent scaling, extract those modules into microservices.

A recomendação resultante costuma ser começar com um monólito modular quando a equipe é pequena, os recursos de DevOps são limitados e a pressão por entrega é alta. Depois, se houver necessidade clara, módulos específicos podem ser extraídos.

9.6 Auto Mode

Auto Mode é um modo de permissão de Research Preview introduzido em março de 2026. Ele usa um classificador de segurança em segundo plano para revisar cada ação antes da execução, permitindo que o Claude trabalhe com mais autonomia e bloqueando operações perigosas.

9.6.1 Requisitos

• Plano: Team, Enterprise ou API. Não está disponível para Pro ou Max.
• Modelo: Claude Sonnet 4.6 ou Opus 4.8.
• Provedor: apenas Anthropic API; não há suporte em Bedrock, Vertex ou Foundry para a forma original do recurso.
• Classificador: executa em Claude Sonnet 4.6, o que adiciona custo extra de tokens.

9.6.2 Como habilitar

Em versões mais antigas, era preciso desbloquear com flag antes de alternar para o modo. Isso foi relaxado em versões posteriores, inclusive com acesso direto para Max em Opus 4.7. Há também suporte para opt-in em alguns provedores de nuvem corporativos, via variável de ambiente.

claude --enable-auto-mode
claude --permission-mode auto

{
  "permissions": {
    "defaultMode": "auto"
  }
}

CLAUDE_CODE_ENABLE_AUTO_MODE=1 claude

Esse opt-in via CLAUDE_CODE_ENABLE_AUTO_MODE=1 é necessário para ativar o recurso em Bedrock, Vertex e Foundry nas versões mais novas com Opus 4.7/4.8.

9.6.3 Como a decisão acontece

O classificador avalia ações em uma ordem específica:

1. Primeiro verifica regras explícitas de permissão.
2. Depois aprova automaticamente leitura de arquivos e edições simples.
3. Em seguida, o classificador de fundo revisa a ação.
4. Se houver bloqueios consecutivos demais, o sistema volta a pedir confirmação.

9.6.4 Ações bloqueadas por padrão

Algumas ações são consideradas perigosas e costumam ser bloqueadas, como instalações via pipe para shell, vazamento de dados sensíveis, deploy para produção, deleções em massa, mudanças de IAM e force push para main.

Ação bloqueada	Exemplo
Instalação via pipe para shell	curl | bash
Envio de dados sensíveis para fora	chaves de API e credenciais pela rede
Deploy em produção	comandos de deploy apontando para produção
Exclusão em massa	rm -rf em diretórios grandes
Alterações em IAM	mudança de permissões e papéis
Force push para main	git push --force origin main

9.6.5 Ações permitidas por padrão

Operações locais e seguras costumam ser aceitas automaticamente, especialmente leitura e escrita em arquivos do projeto, instalações declaradas no manifesto e consultas HTTP somente leitura.

Ação permitida	Exemplo
Operações locais	ler, escrever e editar arquivos do projeto
Instalações declaradas	npm install, pip install a partir de manifesto
HTTP somente leitura	curl para documentação
Push para branch atual	git push origin feature-branch

9.6.6 Regras de configuração e extensões

É possível imprimir as regras padrão em JSON com o comando claude auto-mode defaults. Em ambientes corporativos, o setting gerenciado autoMode.environment permite definir infraestruturas confiáveis, destinos de deploy e padrões de infraestrutura que o classificador deve reconhecer como legítimos.

claude auto-mode defaults

A partir da v2.1.118, os campos autoMode.allow, autoMode.soft_deny e autoMode.environment aceitam o token "$defaults". Esse token faz append das suas regras às listas internas em vez de substituir tudo. Antes disso, qualquer array definido pelo usuário substituía silenciosamente as regras embutidas.

{
  "autoMode": {
    "allow": ["$defaults", "Bash(gh pr list:*)"],
    "soft_deny": ["$defaults", "Bash(kubectl delete:*)"],
    "environment": ["$defaults", "trusted-ci.internal"]
  }
}

O campo autoMode.hard_deny, disponível a partir da v2.1.136, bloqueia uma classe de ações independentemente da intenção inferida. Ele serve para ações que nunca devem rodar no Auto Mode, como remover árvores inteiras com rm -rf em caminhos de raiz ou force push em branches protegidas.

{
  "autoMode": {
    "hard_deny": ["Bash(rm -rf /:*)", "Bash(git push --force*)"]
  }
}

A partir da v2.1.193, o campo autoMode.classifyAllShell permite mandar todos os comandos Bash/PowerShell para o classificador do Auto Mode.

{
  "autoMode": {
    "classifyAllShell": true
  }
}

Na mesma versão, o sistema passou a exibir o motivo da negação quando uma ação é bloqueada. Esse motivo aparece no transcript, no toast de negação e na lista de itens negados recentemente dentro de /permissions.

9.6.7 Proteção embutida por intenção

Além das regras configuradas por você, existe uma camada de proteção padrão baseada em intenção inferida. Se você não pediu explicitamente por esses comandos nesta sessão, o Auto Mode bloqueia operações destrutivas como:

• git reset --hard
• git checkout -- .
• git clean -fd
• git stash drop
• git commit --amend quando o commit não foi criado pelo agente nesta sessão
• terraform destroy, pulumi destroy e cdk destroy, a menos que você tenha pedido especificamente aquele stack

Essa proteção embutida não precisa ser adicionada manualmente ao hard_deny. Ela já vem como padrão de segurança.

9.6.8 Como o fallback funciona

Se o classificador ficar inseguro, o Auto Mode abandona a autonomia e volta a perguntar ao usuário. Isso acontece após 3 bloqueios consecutivos ou 20 bloqueios totais na sessão. O objetivo é impedir que um fluxo fique travado em decisões repetidamente recusadas sem intervenção humana.

9.6.9 Seeding de permissões equivalentes sem plano Team

Se você não tem um plano Team ou prefere não usar o classificador em segundo plano, pode inicializar um baseline conservador em ~/.claude/settings.json com regras seguras. Um script dedicado monta uma base de leitura e inspeção local e deixa liberações opcionais para edição, testes, escrita em git, instalação de pacotes e ações de GitHub somente quando você explicitamente pedir.

O arquivo associado é 09-advanced-features/setup-auto-mode-permissions.py.

# Preview do que seria adicionado, sem gravar nada
python3 09-advanced-features/setup-auto-mode-permissions.py --dry-run

# Aplicar o baseline conservador
python3 09-advanced-features/setup-auto-mode-permissions.py

# Liberar mais recursos conforme a necessidade
python3 09-advanced-features/setup-auto-mode-permissions.py --include-edits --include-tests
python3 09-advanced-features/setup-auto-mode-permissions.py --include-git-write --include-packages

As categorias cobertas incluem ferramentas de leitura, inspeção local, edições opcionais, teste e build opcionais, escrita em git, gerenciadores de pacotes, comandos comuns de shell e GitHub CLI.

• Core read-only tools: Read(*), Glob(*), Grep(*), Agent(*), WebSearch(*), WebFetch(*)
• Local inspection: Bash(git status:*), Bash(git log:*), Bash(git diff:*), Bash(cat:*)
• Optional edits: Edit(*), Write(*), NotebookEdit(*)
• Optional test/build: Bash(pytest:*), Bash(python3 -m pytest:*), Bash(cargo test:*)
• Optional git writes: Bash(git add:*), Bash(git commit:*), Bash(git stash:*)
• Git local write: Bash(git add:*), Bash(git commit:*), Bash(git checkout:*)
• Package managers: Bash(npm install:*), Bash(pip install:*), Bash(cargo build:*)
• Build & test: Bash(make:*), Bash(pytest:*), Bash(go test:*)
• Common shell: Bash(ls:*), Bash(cat:*), Bash(find:*), Bash(cp:*), Bash(mv:*)
• GitHub CLI: Bash(gh pr view:*), Bash(gh pr create:*), Bash(gh issue list:*)

Operações perigosas como rm -rf, sudo, force push, DROP TABLE e terraform destroy ficam intencionalmente fora da lista. O script é idempotente, então executá-lo novamente não duplica regras.

9.7 Background Tasks

Background Tasks permitem executar operações demoradas sem bloquear a conversa. Isso é útil quando você quer continuar trabalhando enquanto um teste, build, migração ou análise roda em paralelo.

9.7.1 Casos típicos

• Suites longas de testes.
• Processos de build.
• Migrações de banco.
• Scripts de deploy.
• Ferramentas de análise.

9.7.2 Uso básico

Quando o Claude inicia uma tarefa em segundo plano, ele gera um identificador como bg-1234. Depois disso, você pode listar, consultar o status, inspecionar a saída ou cancelar a tarefa.

User: Run tests in background

Claude: Started task bg-1234

/task list
/task status bg-1234
/task show bg-1234
/task cancel bg-1234

9.7.3 Fluxo prático

Um padrão comum é iniciar a suíte completa de testes em background e, enquanto ela roda, continuar uma refatoração. Quando a tarefa termina, o Claude notifica o resultado com contagem de testes aprovados e falhos, e você pode abrir os detalhes com /task show.

9.7.4 Gerenciamento

• /task list: lista tarefas ativas, com progresso e tempo estimado restante.
• /task status <id>: mostra estado detalhado, progresso, horário de início e ETA.
• /task show <id>: exibe a saída da tarefa.
• /task cancel <id>: cancela a tarefa.

User: /task list

Active background tasks:
1. [bg-1234] Running tests (50% complete, 2min remaining)
2. [bg-1235] Building Docker image (25% complete, 8min remaining)
3. [bg-1236] Deploying to staging (90% complete, 30sec remaining)

User: /task status bg-1234

Task bg-1234: Running tests
Status: In progress
Progress: 120/245 tests (49%)
Started: 2025-11-08 10:30:15
Estimated completion: 2025-11-08 10:34:22

9.7.5 Configuração

{
  "backgroundTasks": {
    "enabled": true,
    "maxConcurrentTasks": 5,
    "notifyOnCompletion": true,
    "autoCleanup": true,
    "logOutput": true
  }
}

maxConcurrentTasks limita quantas tarefas podem rodar em paralelo. notifyOnCompletion controla se você recebe aviso quando algo termina. autoCleanup ajuda a remover tarefas concluídas, e logOutput preserva a saída para inspeção posterior.

9.8 Monitor Tool

O Monitor Tool, novo em v2.1.98, permite que o Claude observe o stdout de um comando em segundo plano e reaja no instante em que um evento correspondente aparece. Isso substitui loops de polling com sleep quando você precisa esperar por sinais específicos em processos longos.

9.8.1 Como ele funciona

O Monitor se conecta a qualquer comando de shell que escreva para stdout. Cada linha emitida vira um evento que pode acordar a sessão. O comando é executado pelo harness, que transmite a saída para o Claude conforme os eventos acontecem.

9.8.2 Por que usar

Polling com /loop ou sleep consome uma ida e volta completa de API a cada ciclo, mesmo quando nada mudou. O Monitor fica silencioso até que algo realmente apareça, consumindo zero tokens enquanto o comando está quieto. Quando o evento ocorre, a resposta é imediata.

9.8.3 Padrões comuns

Stream filters são indicados quando existe um fluxo contínuo, como logs de aplicação.

tail -f /var/log/app.log | grep --line-buffered "ERROR"

Poll-and-emit filters são melhores quando a fonte não é naturalmente streaming, como API ou banco de dados.

last=$(date -u +%Y-%m-%dT%H:%M:%SZ)
while true; do
  gh api "repos/owner/repo/issues/123/comments?since=$last" || true
  last=$(date -u +%Y-%m-%dT%H:%M:%SZ)
  sleep 30
done

9.8.4 Exemplo concreto

Se você pedir para iniciar um servidor de desenvolvimento e monitorar erros, o Claude pode subir o processo como background task e anexar um filtro como tail -F server.log | grep --line-buffered -E "ERROR|FATAL". Quando aparecer uma linha de erro, ele é notificado e pode agir sem que você precise ficar verificando manualmente.

Há um cuidado importante: ao usar grep em um pipe, sempre use grep --line-buffered. Sem isso, o grep pode acumular saída em blocos de 4KB, atrasando eventos por minutos em streams pouco movimentados. Esse é o motivo mais comum de o Monitor parecer “silencioso” quando não deveria.

9.9 Dynamic Workflows

Dynamic Workflows, introduzido na v2.1.154, permite que o Claude orquestre dezenas ou centenas de subagentes de forma determinística. Em vez de improvisar a sequência a cada execução, o fluxo é descrito em script, com fan-out, pipelines e etapas paralelas bem definidas.

9.9.1 Quando usar

• Cobertura abrangente em muitos arquivos ou dimensões em paralelo.
• Maior confiança por meio de perspectivas independentes e validação adversarial.
• Escala além do que cabe em uma única janela de contexto.

Para tarefas isoladas e já bem compreendidas, um único agente ou uma edição direta ainda costuma ser melhor. Workflows fazem mais sentido quando o trabalho realmente se divide em várias frentes.

9.9.2 Execução e visualização

• Launch: peça para o Claude criar um workflow para o trabalho.
• View: o comando /workflows mostra execuções ativas e concluídas com progresso ao vivo.
• ultracode: no menu /effort, ativa workflows dinâmicos e envia xhigh ao modelo. Esse comportamento é apenas de sessão e não é aceito em arquivo de settings.

A partir da v2.1.160, o gatilho passou a ser explicitamente ultracode; a palavra isolada workflow não inicia mais uma execução.

Os workflows se apoiam no modelo de subagentes, então o comportamento de cada agente individual depende de como os subagentes foram definidos e escopados.

9.10 Scheduled Tasks

Scheduled Tasks permitem executar prompts automaticamente em agenda recorrente ou como lembretes únicos. Eles têm escopo de sessão: funcionam enquanto o Claude Code está ativo e são removidos quando a sessão termina. Esse recurso está disponível desde a v2.1.72.

9.10.1 Routines e nomenclatura

Na documentação do claude.com e no app desktop, o nome de produto usado pode ser Routines. A interface de linha de comando continua usando /schedule. Aqui, o nome “Scheduled Tasks” é mantido para continuidade conceitual.

9.10.2 Comando /loop

O comando /loop permite definir intervalos explícitos ou instruções em linguagem natural. A forma cron padrão de 5 campos também é suportada para quem precisa de precisão maior.

/loop 5m check if the deployment finished
/loop check build status every 30 minutes

9.10.3 Lembretes pontuais

Também é possível agendar algo para acontecer apenas uma vez em um horário específico.

remind me at 3pm to push the release branch
in 45 minutes, run the integration tests

9.10.4 Gerenciamento

Os agendamentos podem ser criados, listados e removidos por ferramentas internas chamadas CronCreate, CronList e CronDelete. A partir da v2.1.136, o resultado do CronList inclui também os qualifiers e o corpo completo do prompt, o que facilita auditoria sem abrir cada item separadamente.

9.10.5 Limites e comportamento

• Até 50 tarefas agendadas por sessão.
• Escopo de sessão: tudo é limpo quando a sessão termina.
• Tarefas recorrentes expiram automaticamente após 3 dias.
• O sistema só dispara quando o Claude Code está em execução; não há recuperação de execuções perdidas.

9.10.6 Variação de tempo

• Recorrente: jitter de até 10% do intervalo, limitado a 15 minutos.
• Execução única: jitter de até 90 segundos em torno de limites :00 e :30.
• Perdas: se o Claude Code não estiver rodando, o evento é perdido.
• Persistência: não persiste após reinício local.

9.10.7 Cloud Scheduled Tasks

Com /schedule, você pode criar tarefas na infraestrutura da Anthropic. Essas tarefas persistem entre reinicializações e não dependem do Claude Code rodando localmente.

/schedule daily at 9am run the test suite and report failures

9.10.8 Desativação e restrições por credenciais

Você pode desabilitar tarefas agendadas locais com a variável CLAUDE_CODE_DISABLE_CRON=1.

export CLAUDE_CODE_DISABLE_CRON=1

A partir da v2.1.139, o agendamento em nuvem via /schedule fica silenciosamente indisponível quando qualquer uma destas credenciais está definida: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN ou apiKeyHelper. Isso vale mesmo se você também estiver autenticado com claude.ai. A mesma condição desabilita Remote Control, conectores MCP do claude.ai e preferências de notificação. Para usar /schedule, remova a chave de API ou opere em um tier OAuth de Pro/Max. O CronCreate local não é afetado.

9.10.9 Exemplo de monitoramento

/loop 5m check the deployment status of the staging environment.
        If the deploy succeeded, notify me and stop looping.
        If it failed, show the error logs.

Para automação persistente que sobreviva a reinícios, prefira pipelines de CI/CD, GitHub Actions ou tarefas agendadas do Desktop App.

9.11 Permission Modes

Os modos de permissão controlam o que o Claude pode fazer sem pedir aprovação explícita. Eles são a camada central de segurança operacional e variam desde leitura somente até bypass total.

9.11.1 Modos disponíveis

Modo	Comportamento
manual	lê arquivos e pede confirmação para o restante; esse nome substituiu default na v2.1.200, mas default ainda funciona como alias
acceptEdits	lê e edita arquivos; pede confirmação para comandos
plan	apenas leitura, sem edições, para modo de pesquisa
auto	executa ações com classificador de segurança em segundo plano; é Research Preview
bypassPermissions	executa tudo sem checagens; é perigoso
dontAsk	executa apenas ferramentas previamente aprovadas; todo o resto é negado

Na interface, Shift + Tab alterna os modos. O padrão pode ser definido com --permission-mode ou com permissions.defaultMode no arquivo de configuração.

A partir da v2.1.200, o modo interativo “default” passou a se chamar Manual na interface, na ajuda e nos plugins editoriais. Um badge cinza de pausa aparece no rodapé quando ele está ativo na v2.1.203. Tanto --permission-mode manual quanto --permission-mode default continuam válidos, assim como "defaultMode": "manual" e "defaultMode": "default" nas configurações.

Na v2.1.160, mesmo o modo acceptEdits passou a pedir confirmação antes de gravar arquivos de startup do shell e alguns arquivos de build que executam código, porque eles podem causar execução involuntária de comandos.

Além disso, a flag --dangerously-skip-permissions e o modo equivalente bypassPermissions passaram a cobrir um conjunto maior de caminhos, incluindo diretórios internos do Claude, Git, VS Code e arquivos de shell. Mesmo assim, remoções catastróficas como rm -rf / continuam pedindo confirmação em qualquer modo. Trate essa opção como uma ferramenta mais agressiva do que antes e use somente em sandboxes descartáveis.

No Windows, a detecção de shell também evoluiu. Quando o Git Bash não está presente, o Claude Code passa a usar PowerShell. Em versões mais novas, o PowerShell é o shell primário quando a ferramenta está habilitada, incluindo instalações via Microsoft Store, MSI sem PATH ou como global tool do .NET.

Para usuários Bedrock, Vertex e Foundry no Windows, a ferramenta PowerShell passou a vir habilitada por padrão na v2.1.143. O Claude Code chama o PowerShell com -ExecutionPolicy Bypass; se você quiser respeitar a política do sistema, use CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1. Para desabilitar a ferramenta de PowerShell por completo, use CLAUDE_CODE_USE_POWERSHELL_TOOL=0.

9.11.2 Como ativar

Shift + Tab
/plan
claude --permission-mode plan
claude --permission-mode auto

{
  "permissions": {
    "defaultMode": "auto"
  }
}

9.11.3 Exemplos de uso

No modo Manual, o Claude pede confirmação para ações relevantes. Em Plan mode, ele mostra o plano antes de executar. Em acceptEdits, ele aceita modificações em arquivos sem perguntar, mas ainda pede para comandos.

Default Mode
User: Fix the bug in auth.ts

Claude: I need to modify src/auth.ts to fix the bug.
The change will update the password validation logic.

Approve this change? (yes/no/show)

Plan Mode
User: /plan Implement user authentication system

Claude: I'll create a plan for implementing authentication.

Implementation Plan
[Detailed plan with phases and steps]

Ready to proceed? (yes/no/modify)

Accept Edits Mode
User: acceptEdits
User: Fix the bug in auth.ts

Claude: [Makes changes without asking]

9.11.4 Casos de uso

• Code review: use plan para ler e opinar sem modificar.
• Pair programming: use manual para aprovar cada mudança crítica.
• Automação: use acceptEdits quando a escrita em arquivos for segura, mas ainda quiser controle sobre comandos.

9.12 Print Mode

Print Mode, acionado com claude -p, faz o Claude Code rodar sem entrada interativa. É a forma não interativa recomendada para automação, integração com CI/CD, processamento em lote e tarefas programadas. Ele substitui a antiga flag --headless.

9.12.1 O que ele permite

• Execução automatizada de scripts.
• Integração com pipelines de CI/CD.
• Processamento em lote.
• Uso combinado com tarefas agendadas.

9.12.2 Exemplos

claude -p "Run all tests"
cat error.log | claude -p "Analyze these errors"
claude -p "Run all tests and generate coverage report"
claude -p --output-format json "Analyze code quality"
echo "Analyze code quality" | claude -p "explain this"

9.12.3 Integração com GitHub Actions

Um cenário comum é rodar uma revisão de código em um workflow do GitHub Actions, capturar a saída em JSON e publicar o resultado como comentário em um pull request.

# .github/workflows/code-review.yml
name: AI Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Claude Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p --output-format json \
            --max-turns 3 \
            "Review this PR for:
            - Code quality issues
            - Security vulnerabilities
            - Performance concerns
            - Test coverage
            Output results as JSON" > review.json

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = JSON.parse(fs.readFileSync('review.json', 'utf8'));
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: JSON.stringify(review, null, 2)
            });

9.12.4 Flags úteis

• --max-turns: limita quantas voltas autônomas o Claude pode dar.
• --output-format json: força saída estruturada.
• --json-schema: valida a saída contra um schema.
• --no-session-persistence: desliga persistência da sessão para tarefas únicas.

claude -p --max-turns 5 "refactor this module"
claude -p --output-format json "analyze this codebase"
claude -p --json-schema '{"type":"object","properties":{"issues":{"type":"array"}}}' \
  "find bugs in this code"
claude -p --no-session-persistence "one-off analysis"

9.12.5 Safe Mode para troubleshooting

O --safe-mode e a variável CLAUDE_CODE_SAFE_MODE=1 iniciam o Claude Code com todas as customizações desligadas: CLAUDE.md, plugins, skills, hooks e MCP servers ficam inativos. Esse modo é uma ferramenta de diagnóstico para separar problema de configuração do problema no próprio Claude Code.

claude --safe-mode
CLAUDE_CODE_SAFE_MODE=1 claude

9.13 Session Management

O gerenciamento de sessão permite continuar conversas, dar nomes para sessões e criar bifurcações para testar caminhos alternativos sem perder o histórico original.

9.13.1 Comandos principais

Comando	Descrição
/resume	retoma uma conversa por ID ou nome
/rename	atribui nome à sessão atual
/fork	cria um fork da sessão em uma nova ramificação
claude -c	continua a conversa mais recente
claude -r "session"	retoma uma sessão por nome ou ID

9.13.2 Retomando sessões

claude -c
claude -r "auth-refactor" "finish this PR"

Também é possível renomear a sessão atual dentro da REPL.

/rename auth-refactor

9.13.3 Fork de sessão

O fork é útil quando você quer testar uma abordagem alternativa sem apagar a original. No CLI, existe também a combinação --resume com --fork-session para abrir um novo ramo a partir de uma sessão existente.

/fork

claude --resume auth-refactor --fork-session "try OAuth instead"
claude --resume auth-refactor
claude -r "auth-refactor"
claude --resume auth-refactor --fork-session "alternative approach"

9.13.4 Persistência e recap

As sessões são salvas automaticamente e podem ser retomadas depois. A partir da v2.1.108, ao voltar para uma sessão após um tempo fora, o Claude pode exibir um breve resumo do que já foi feito. Esse recap vem habilitado por padrão para usuários com telemetria desativada, como em Bedrock, Vertex e Foundry.

Em ambientes com OpenTelemetry, organizações podem reativar a pesquisa de qualidade da sessão com CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL=1. Além disso, desde a v2.1.193, o Claude Code emite o evento de log claude_code.assistant_response, que transporta o texto da resposta do modelo para pipelines OTEL.

Você pode controlar o recap manualmente com /recap ou ajustar essa preferência em /config. Também é possível forçar ou desabilitar via variável de ambiente.

/recap
/config
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0 claude
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1 claude

Como o recap é um apoio de retomada, ele não substitui manter nomes claros de sessão nem usar forks quando houver experimentação real.

9.14 Recursos interativos da interface

9.14.1 Atalhos de teclado padrão

Claude Code inclui atalhos para acelerar navegação, edição e controle da sessão. Eles funcionam no terminal interativo e, em alguns casos, podem depender do emulador de terminal, do multiplexador ou da versão instalada.

Os atalhos a seguir fazem parte da referência oficial de uso interativo:

• Ctrl+C: cancela a entrada atual ou interrompe a geração em andamento.
• Ctrl+D: encerra o Claude Code.
• Ctrl+G: abre a edição do plano em um editor externo.
• Ctrl+L: limpa a tela do terminal.
• Ctrl+O: alterna a saída verbosa, mostrando mais detalhes do transcript; em versões atuais, isso não é o mesmo que focus view.
• Ctrl+R: faz busca reversa no histórico. A partir da versão v2.1.129+, o padrão é pesquisar em todos os prompts de todos os projetos; dentro do seletor, pressione Ctrl+S para restringir ao projeto atual. Versões anteriores pesquisavam apenas o projeto corrente.
• Ctrl+T: alterna a visualização da lista de tarefas.
• Ctrl+B: mostra tarefas executando em segundo plano.
• Esc Esc: retrocede no código ou na conversa.
• Shift+Tab ou Alt+M: alterna os modos de permissão.
• Option+P ou Alt+P: troca de modelo.
• Option+T ou Alt+T: alterna o extended thinking.

9.14.2 Edição de linha com atalhos padrão de readline

Claude Code também respeita os atalhos clássicos de edição de linha, úteis para corrigir comandos antes de enviar:

• Ctrl+A: vai para o início da linha.
• Ctrl+E: vai para o final da linha.
• Ctrl+K: recorta do cursor até o fim da linha.
• Ctrl+U: recorta do cursor até o início da linha.
• Ctrl+W: apaga a palavra anterior.
• Ctrl+Y: cola o trecho recortado.
• Tab: completa automaticamente.
• ↑ e ↓: navegam pelo histórico de comandos.

9.14.3 Personalização de atalhos com keybindings

É possível criar atalhos próprios executando o comando /keybindings. Ele abre o arquivo ~/.claude/keybindings.json para edição. Esse recurso está disponível a partir da versão v2.1.18+.

A estrutura do arquivo segue um esquema JSON com contexto e bindings. Exemplo:

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+u": null,
        "ctrl+k ctrl+s": "chat:stash"
      }
    },
    {
      "context": "Confirmation",
      "bindings": {
        "ctrl+a": "confirmation:yes"
      }
    }
  ]
}

Ao definir um binding como null, você desativa o atalho padrão correspondente. Isso é útil quando um atalho conflita com seu fluxo de trabalho ou com o terminal.

9.14.4 Contextos disponíveis para keybindings

Os atalhos não são globais por padrão: eles ficam limitados ao contexto atual da interface. Isso evita que a mesma tecla tenha efeitos indesejados em áreas diferentes da aplicação.

• Chat: submit, cancel, cycleMode, modelPicker, thinkingToggle, undo, externalEditor, stash, imagePaste
• Confirmation: yes, no, previous, next, nextField, cycleMode, toggleExplanation
• Global: interrupt, exit, toggleTodos, toggleTranscript
• Autocomplete: accept, dismiss, next, previous
• HistorySearch: search, previous, next
• Settings: navegação de configurações conforme o painel aberto
• Tabs: alternância e gerenciamento de abas
• Help: navegação do painel de ajuda

Além desses, existem 18 contextos no total, incluindo Transcript, Task, ThemePicker, Attachments, Footer, MessageSelector, DiffDialog, ModelPicker e Select.

9.14.5 Sequências de teclas encadeadas

Os keybindings aceitam chords, isto é, sequências de múltiplas teclas ou combinações simultâneas de modificadores.

"ctrl+k ctrl+s"   → sequência de duas teclas: pressione ctrl+k e depois ctrl+s
"ctrl+shift+p"    → modificadores pressionados ao mesmo tempo

A sintaxe aceita os seguintes elementos:

• Modificadores: ctrl, alt ou opt, shift, meta ou cmd
• Letras maiúsculas: uma letra como K equivale a shift+k
• Teclas especiais: escape, enter, return, tab, space, backspace, delete e setas direcionais

9.14.6 Teclas reservadas e conflitos comuns

Alguns atalhos não podem ser reatribuídos porque fazem parte do funcionamento básico da sessão ou entram em conflito com ferramentas de terminal.

• Ctrl+C: reservado; não pode ser remapeado, pois interrompe a execução.
• Ctrl+D: reservado; não pode ser remapeado, pois encerra a sessão.
• Ctrl+B: pode conflitar com o prefixo do tmux.
• Ctrl+A: pode conflitar com o prefixo do GNU Screen.
• Ctrl+Z: pode suspender o processo no terminal.

Se um atalho não funcionar, verifique primeiro o emulador de terminal, o multiplexador e qualquer remapeamento do sistema operacional.

9.14.7 Tab completion

O Claude Code oferece autocompletar inteligente para comandos e subcomandos. Isso reduz erros de digitação e ajuda iniciantes a descobrir comandos válidos.

Usuário: /rew<TAB>
→ /rewind

Usuário: /plu<TAB>
→ /plugin

Usuário: /plugin <TAB>
→ /plugin install
→ /plugin enable
→ /plugin disable

9.14.8 Histórico de comandos

O histórico permite repetir, revisar ou pesquisar instruções anteriores, algo especialmente útil em sessões longas ou com testes iterativos.

Usuário: <↑>   # comando anterior
Usuário: <↓>   # próximo comando
Usuário: Ctrl+R # busca no histórico

(reverse-i-search)`test': run all tests

9.14.9 Entrada em múltiplas linhas

Para prompts complexos, você pode escrever em várias linhas antes de enviar. Isso melhora a legibilidade de requisitos extensos, listas de tarefas e especificações técnicas.

Usuário: \
> Implement a user authentication system
> with the following requirements:
> - JWT tokens
> - Email verification
> - Password reset
> - 2FA support
> \end

Exemplo prático:

Usuário: \
> Implement a user authentication system
> with the following requirements:
> - JWT tokens
> - Email verification
> - Password reset
> - 2FA support
> \end

Claude: [processa a solicitação em múltiplas linhas]

9.14.10 Edição inline antes do envio

Você pode corrigir o texto enquanto ele ainda está no campo de entrada, sem precisar reescrever a mensagem inteira. Isso é útil para ajustar nomes de arquivos, branches e comandos rapidamente.

Usuário: Deploy to prodcution<Backspace><Backspace>uction

[edição aplicada no próprio texto antes do envio]

9.14.11 Modo Vim

O Claude Code suporta keybindings no estilo Vi/Vim para quem prefere manipulação modal de texto. O recurso não é mais ativado pelo comando independente /vim; agora ele depende de configuração, o que é importante para evitar ambiguidades entre sessões e perfis.

Ativação:

• Use /config e habilite a opção Editor / Vim mode.
• Ou defina editorMode: "vim" em ~/.claude/settings.json.
• O comando /vim foi removido e não deve mais ser esperado no fluxo atual.
• A troca de modos ocorre com Esc para NORMAL, i/a/o para INSERT, v para VISUAL e V para VISUAL-LINE a partir da versão v2.1.118+.

Navegação no modo Vim:

• h e l: mover para esquerda e direita.
• j e k: mover para baixo e cima.
• w, b e e: mover por palavra.
• 0 e $: ir para o início ou fim da linha.
• gg e G: saltar para o início ou fim do texto.

Text objects:

• iw / aw: palavra interna ou palavra com arredores.
• i" / a": string entre aspas, interna ou completa.
• i( / a(: conteúdo interno ou com parênteses.

Modos visuais a partir de v2.1.118+:

• v ativa seleção visual por caractere, com feedback visível; você pode estender a seleção com movimentos.
• V ativa seleção por linha, sempre escolhendo linhas inteiras.
• y copia a seleção atual.
• d ou x apagam a seleção atual.
• c remove a seleção e entra em modo INSERT.
• Esc sai e retorna ao modo NORMAL.

As seleções visuais ficam destacadas no campo de entrada, o que reduz erros ao copiar, apagar ou substituir blocos longos de texto.

9.14.12 Modo Bash

O modo Bash permite executar comandos do shell diretamente a partir do prompt, prefixando a linha com !. Ele é indicado para comandos rápidos que você deseja testar sem alternar para outra janela ou contexto.

! npm test
! git status
! cat src/index.js

Esse recurso é útil para inspeção, validação e automação leve. A partir da versão v2.1.193, o modo Bash ganhou autocompletar de caminhos em tempo real, o que ajuda a completar caminhos de arquivos enquanto você digita o comando.

A partir da versão v2.1.186, a saída de comandos iniciados com ! passa a ser enviada automaticamente ao Claude, que responde com base nela. Se você quiser o comportamento anterior, em que a saída apenas entrava no contexto sem gerar resposta imediata, defina "respondToBashCommands": false em settings.json.

9.15 Modo TUI em tela cheia

Novidade em v2.1.110

O modo TUI (Text User Interface) renderiza o Claude Code em tela cheia, com saída estável e sem flicker. Ele é especialmente útil em ambientes como tmux ou divisões de janela no iTerm2, onde a atualização visual pode ficar mais limpa e previsível.

9.15.1 Como ativar o TUI

Você pode alternar o modo com o comando /tui durante a sessão ou iniciar diretamente com a flag --tui:

/tui          # alterna dentro de uma sessão
claude --tui   # inicia diretamente em TUI

9.15.2 Configuração

Há um ajuste específico para rolagem automática da visualização:

Configuração	Descrição	Padrão
autoScrollEnabled	faz a interface acompanhar automaticamente a mensagem mais recente	true

Você pode desativar a rolagem automática em /config ou no arquivo settings.json:

{
  "autoScrollEnabled": false
}

9.15.3 Focus view

O comando /focus ativa uma visualização sem distrações, mostrando apenas a saída mais relevante. Isso é diferente de Ctrl+O: na versão atual, Ctrl+O alterna apenas entre transcript normal e verboso, enquanto o modo de foco é controlado por /focus.

9.16 Ditado por voz

O recurso de ditado por voz oferece entrada por voz com push-to-talk, permitindo que você fale seus prompts em vez de digitá-los.

9.16.1 Como ativar

/voice

9.16.2 Recursos

• Push-to-talk: pressione e segure uma tecla para gravar e solte para enviar.
• 20 idiomas: o reconhecimento de voz suporta 20 idiomas.
• Atalho personalizável: a tecla de push-to-talk pode ser definida em /keybindings.
• Dependência de conta: o processamento de STT exige uma conta Claude.ai.

Para ajustar o comportamento, edite o arquivo de keybindings aberto por /keybindings. O ditado usa sua conta Claude.ai para o processamento de speech-to-text, então esse recurso não funciona como um reconhecimento puramente local.

9.17 Channels

Channels é um recurso em Research Preview que envia eventos de serviços externos para uma sessão em execução do Claude Code por meio de servidores MCP. Ele permite reagir a notificações em tempo real, sem polling.

Autenticação a partir de v2.1.128+: a flag --channels passou a funcionar tanto com autenticação OAuth de planos Pro/Max quanto com autenticação por API key/console. Em versões anteriores, ela exigia OAuth.

9.17.1 Como assinar canais

# Assinar plugins de canal na inicialização
claude --channels discord,telegram

# Assinar múltiplas fontes
claude --channels discord,telegram,imessage,webhooks

9.17.2 Integrações suportadas

• Discord: recebe e responde mensagens do Discord dentro da sessão.
• Telegram: recebe e responde mensagens do Telegram dentro da sessão.
• iMessage: recebe notificações do iMessage dentro da sessão.
• Webhooks: recebe eventos de fontes arbitrárias via webhook.

9.17.3 Configuração administrativa

Em ambientes corporativos, a organização pode restringir quais plugins de canal são permitidos usando o setting gerenciado allowedChannelPlugins:

{
  "allowedChannelPlugins": ["discord", "telegram"]
}

Esse controle vale para toda a organização e evita que um usuário habilite integrações não aprovadas.

9.17.4 Como funciona na prática

1. Servidores MCP atuam como plugins de canal e conectam o Claude Code a serviços externos.
2. Mensagens e eventos de entrada são empurrados para a sessão ativa.
3. Claude lê esses dados e pode responder no próprio contexto da sessão.
4. Os plugins precisam estar aprovados por allowedChannelPlugins.
5. Não há polling; os eventos chegam em tempo real.

9.18 Integração com Chrome

A integração com Chrome conecta o Claude Code ao navegador Google Chrome ou Microsoft Edge para automação web em tempo real e depuração. É um recurso beta, disponível desde v2.0.73+; suporte ao Edge foi adicionado em v1.0.36+.

9.18.1 Como habilitar

No início da sessão:

claude --chrome      # habilita a conexão com o Chrome
claude --no-chrome   # desabilita a conexão com o Chrome

Durante a sessão:

/chrome

Depois, selecione Enabled by default para ativar a integração automaticamente nas próximas sessões. O Claude Code compartilha o estado de login do navegador, então ele consegue interagir com aplicações autenticadas sem você repetir o login em cada execução.

9.18.2 Capacidades

• Depuração ao vivo: lê logs do console, inspeciona elementos do DOM e depura JavaScript em tempo real.
• Verificação de design: compara páginas renderizadas com mockups visuais.
• Validação de formulários: testa envios, validações e tratamento de erros.
• Testes de web apps: interage com apps autenticados como Gmail, Google Docs e Notion.
• Extração de dados: coleta e processa conteúdo de páginas web.
• Gravação de sessão: registra interações do navegador em arquivos GIF.

9.18.3 Permissões por site

A extensão do Chrome controla o acesso por site. Você pode conceder ou revogar permissões a qualquer momento pelo popup da extensão. O Claude Code só interage com sites explicitamente autorizados.

9.18.4 Como o recurso opera

O navegador é controlado em uma janela visível, então você acompanha as ações em tempo real. Quando o navegador encontra uma página de login ou CAPTCHA, o Claude pausa e aguarda sua ação manual antes de continuar.

9.18.5 Limitações conhecidas

• Compatibilidade de navegador: apenas Chrome e Edge são suportados. Brave, Arc e outros navegadores Chromium não são suportados.
• WSL: não disponível no Windows Subsystem for Linux.
• Provedores de terceiros: não funciona com Bedrock, Vertex ou Foundry como provedores de API.
• Service worker ocioso: o service worker da extensão pode entrar em estado idle durante sessões longas.

Como se trata de um beta, a cobertura de navegadores e o comportamento da extensão podem mudar em versões futuras.

9.19 Remote Control

O Remote Control permite continuar uma sessão local do Claude Code a partir do celular, tablet ou navegador. A sessão continua executando na sua máquina; nada é movido para a nuvem. O recurso está disponível nos planos Pro, Max, Team e Enterprise a partir de v2.1.51+.

9.19.1 Como iniciar

Na linha de comando:

# Inicia com nome padrão de sessão
claude remote-control

# Inicia com nome personalizado
claude remote-control --name "Auth Refactor"

Dentro de uma sessão interativa:

/remote-control
/remote-control "Auth Refactor"

9.19.2 Flags disponíveis

• --name "title": define um título personalizado para facilitar a identificação da sessão.
• --verbose: mostra logs detalhados de conexão.
• --sandbox: ativa isolamento de sistema de arquivos e rede.
• --no-sandbox: desativa sandboxing; esse é o padrão quando não especificado.

9.19.3 Como conectar por outro dispositivo

1. URL da sessão: o terminal exibe o endereço quando a sessão começa; abra-o em qualquer navegador.
2. Código QR: pressione a barra de espaço após iniciar para exibir um QR code escaneável.
3. Busca por nome: navegue pelas sessões em claude.ai/code ou no app móvel do Claude para iOS/Android.

9.19.4 Segurança

• Sem portas de entrada abertas no seu computador.
• Apenas HTTPS de saída, protegido por TLS.
• Credenciais com escopo limitado: múltiplos tokens de curta duração e escopo estreito.
• Isolamento de sessão: cada sessão remota é independente.

9.19.5 Remote Control versus Claude Code na web

Esses dois modos parecem semelhantes, mas têm arquiteturas diferentes:

• Remote Control: executa na sua máquina e mantém acesso total a MCPs locais, arquivos e CLI.
• Claude Code na web: executa na nuvem da Anthropic e não depende de ferramentas locais.
• Remote Control é ideal para continuar um trabalho local em outro dispositivo.
• Claude Code na web é melhor para começar algo do zero diretamente no navegador.

9.19.6 Limitações

• Há apenas uma sessão remota por instância do Claude Code.
• O terminal precisa permanecer aberto no host.
• A sessão expira após cerca de 10 minutos se a rede ficar indisponível.

9.19.7 Cenários de uso

• Controlar o Claude Code pelo celular ou tablet longe da mesa.
• Usar a interface mais rica do claude.ai enquanto mantém a execução local das ferramentas.
• Fazer revisões rápidas de código em movimento, sem perder o ambiente de desenvolvimento local.

9.19.8 Push notifications

Novidade em v2.1.110

Quando o Remote Control está ativo e a opção Push when Claude decides está habilitada em /config, o Claude pode enviar notificações push para o celular. Isso é útil quando uma tarefa demorada termina ou quando a interação humana é necessária.

Para habilitar:

1. Ative o Remote Control com /remote-control ou claude --rc.
2. Abra /config e habilite Push when Claude decides.

As notificações exigem assinatura Claude e o aplicativo móvel Claude.

9.19.9 Desativação administrativa com disableRemoteControl

v2.1.128+: administradores dos planos Team ou Enterprise podem bloquear completamente o recurso usando o setting gerenciado disableRemoteControl. Quando definido como true, tanto claude remote-control quanto /remote-control recusam a inicialização.

{
  "disableRemoteControl": true
}

Esse ajuste é aplicado no escopo managed/policy, por exemplo em /Library/Application Support/ClaudeCode/managed-settings.json no macOS. Isso impede que usuários sobrescrevam a política localmente, o que é apropriado quando a organização precisa garantir execução apenas local ou restringir acesso remoto.

Desativação silenciosa em tiers com API key (v2.1.139): Remote Control é desabilitado automaticamente quando qualquer uma das variáveis abaixo está definida, mesmo que você também esteja logado com claude.ai:

• ANTHROPIC_API_KEY
• ANTHROPIC_AUTH_TOKEN
• apiKeyHelper em settings.json

Esse mesmo bloqueio afeta também /schedule, conectores MCP do claude.ai e preferências de notificação. Em outras palavras, esses quatro recursos dependem de a autenticação OAuth ser a credencial ativa. Para reabilitá-los, remova a API key ou use um plano Pro/Max baseado em OAuth.

9.20 Sessões Web

As Web Sessions permitem executar o Claude Code diretamente no navegador em claude.ai/code ou criar sessões web a partir do terminal.

9.20.1 Criando uma sessão web

# Cria uma nova sessão web a partir do CLI
claude --remote "implement the new API endpoints"

Isso inicia uma sessão do Claude Code na infraestrutura web da Anthropic, acessível de qualquer navegador.

9.20.2 Retomando uma sessão web localmente

Se você iniciou o trabalho na web e quer continuar no terminal local:

# Retoma uma sessão web no terminal local
claude --teleport

Ou, dentro do REPL interativo:

/teleport

9.20.3 Casos de uso

• Começar em uma máquina e continuar em outra.
• Compartilhar a URL da sessão com membros da equipe.
• Usar a interface web para revisar diffs visualmente e depois migrar para o terminal para execução.

9.21 Aplicativo Desktop

O Claude Code Desktop App é um aplicativo independente com revisão visual de diffs, sessões paralelas e conectores integrados. Ele está disponível para macOS e Windows nos planos Pro, Max, Team e Enterprise.

9.21.1 Instalação

Baixe a versão adequada para sua plataforma em claude.ai:

• macOS: build universal para Apple Silicon e Intel.
• Windows: instaladores x64 e ARM64.

Consulte o Desktop Quickstart para instruções de configuração.

9.21.2 Transferindo uma sessão do CLI

Você pode entregar a sessão atual do terminal para o aplicativo Desktop com:

/desktop

9.21.3 Recursos principais

• Diff view: revisão visual arquivo por arquivo com comentários inline; Claude lê os comentários e revisa conforme solicitado.
• App preview: inicia servidores de desenvolvimento automaticamente com navegador embutido para verificação ao vivo.
• PR monitoring: integração com GitHub CLI para corrigir falhas de CI e fazer auto-merge quando os checks passam.
• Parallel sessions: múltiplas sessões na barra lateral com isolamento automático via Git worktree.
• Scheduled tasks: tarefas recorrentes por hora, dia, dia útil ou semana, executadas enquanto o app estiver aberto.
• Rich rendering: renderização de código, markdown e diagramas com destaque de sintaxe; caixas de tarefa do GitHub-Flavored Markdown (- [ ] / - [x]) aparecem como checkboxes a partir de v2.1.149+.

9.21.4 Configuração do App Preview

O comportamento do servidor de desenvolvimento é definido em .claude/launch.json:

{
  "command": "npm run dev",
  "port": 3000,
  "readyPattern": "ready on",
  "persistCookies": true
}

Esse arquivo informa como iniciar o app, qual porta observar, qual texto indica que o servidor está pronto e se os cookies devem ser preservados entre execuções.

9.21.5 Connectors

É possível conectar serviços externos para enriquecer o contexto da sessão:

• GitHub: monitoramento de PRs, rastreamento de issues e revisão de código.
• Slack: notificações e contexto de canais.
• Linear: acompanhamento de issues e sprints.
• Notion: documentação e base de conhecimento.
• Asana: gerenciamento de tarefas e projetos.
• Calendar: consciência de agenda e contexto de reuniões.

Observação: conectores não estão disponíveis para sessões remotas na nuvem.

9.21.6 Sessões remotas e SSH

• Sessões remotas: executam na infraestrutura em nuvem da Anthropic; continuam mesmo com o app fechado e podem ser acessadas em claude.ai/code ou pelo app móvel.
• Sessões SSH: conectam a máquinas remotas via SSH com acesso total ao filesystem e às ferramentas do host remoto. O Claude Code precisa estar instalado nessa máquina.

9.21.7 Modos de permissão no Desktop

O aplicativo Desktop suporta os mesmos 4 modos de permissão do terminal:

• Ask permissions (padrão): revisa e aprova cada edição e comando.
• Auto accept edits: edições em arquivos são aprovadas automaticamente; comandos ainda exigem aprovação manual.
• Plan mode: revisão da abordagem antes de qualquer alteração.
• Bypass permissions: execução automática, restrita a sandbox e controlada por administrador.

9.21.8 Recursos Enterprise

• Admin console: controla acesso à aba Code e as configurações de permissão da organização.
• MDM deployment: distribuição via MDM no macOS ou MSIX no Windows.
• SSO integration: exige login único para membros da organização.
• Managed settings: gerencia centralmente configurações da equipe e disponibilidade de modelos.

9.22 Task List

O recurso de lista de tarefas oferece rastreamento persistente de atividades que sobrevive às compactações de contexto, isto é, quando o histórico da conversa é podado para caber na janela de contexto.

9.22.1 Alternando a lista de tarefas

Pressione Ctrl+T durante a sessão para ligar ou desligar a visualização da lista de tarefas.

9.22.2 Tarefas persistentes

As tarefas permanecem mesmo após a compactação do contexto. Isso evita perder itens importantes em implementações longas, especialmente quando o trabalho envolve múltiplas etapas ou depende de acompanhamento contínuo.

9.22.3 Diretórios nomeados de tarefas

Você pode criar diretórios de tarefas compartilhados entre sessões usando a variável de ambiente CLAUDE_CODE_TASK_LIST_ID:

export CLAUDE_CODE_TASK_LIST_ID=my-project-sprint-3

Isso permite que várias sessões consultem a mesma lista, o que é útil em fluxos de equipe ou em projetos com mais de uma sessão simultânea.

9.23 Sugestões de prompt

As sugestões de prompt aparecem como textos acinzentados com exemplos de comandos baseados no histórico do git e no contexto atual da conversa.

9.23.1 Como funcionam

• As sugestões aparecem abaixo do prompt de entrada, em cinza.
• Pressione Tab para aceitar a sugestão.
• Pressione Enter para aceitar e enviar imediatamente.
• As sugestões são contextuais, usando histórico do git e o estado da conversa.

9.23.2 Desativando sugestões

export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false

9.24 Git Worktrees

Git worktrees permitem iniciar o Claude Code em uma cópia isolada do repositório, possibilitando trabalho paralelo em branches diferentes sem precisar fazer stash ou trocar de branch o tempo todo.

9.24.1 Como iniciar em um worktree

# Inicia o Claude Code em um worktree isolado
claude --worktree
# ou
claude -w

9.24.2 Localização do worktree

Os worktrees criados pelo Claude ficam em:

<repo>/.claude/worktrees/<name>

9.24.3 Sparse checkout para monorepos

Em monorepos, a configuração worktree.sparsePaths permite usar sparse-checkout para baixar apenas partes específicas do repositório, reduzindo uso de disco e tempo de clone.

{
  "worktree": {
    "sparsePaths": ["packages/my-package", "shared/"]
  }
}

9.24.4 Base branch com worktree.baseRef

worktree.baseRef foi adicionado em v2.1.133 e controla se claude --worktree cria a branch a partir de origin/<default> ou do HEAD local.

• "fresh" (padrão): cria a branch a partir de origin/<default-branch>, ignorando commits locais ainda não enviados. Esse comportamento reverte a mudança introduzida em v2.1.128; quem dependia do branch local após essa versão precisa optar explicitamente por outro modo.
• "head": cria a branch a partir do HEAD local, preservando commits não enviados.

Exemplo em ~/.claude/settings.json:

{ "worktree": { "baseRef": "head" } }

9.24.5 Isolamento de sessões em background com worktree.bgIsolation

worktree.bgIsolation foi adicionado em v2.1.143 e define se sessões em segundo plano — como as iniciadas por /bg, claude --bg ou pela Agent View — ganham seu próprio worktree ou alteram diretamente a cópia de trabalho em primeiro plano.

• Padrão: sessões em background criam um worktree isolado em <repo>/.claude/worktrees/, igual ao que acontece com --worktree.
• "none": sessões em background editam diretamente a working copy atual. Use essa opção quando worktrees forem inviáveis, por exemplo em repositórios com artefatos nativos pesados, ou quando um agente em segundo plano precisar coordenar edições com a sessão ativa.

{ "worktree": { "bgIsolation": "none" } }

A desvantagem de "none" é a perda da proteção oferecida pelo isolamento: edições simultâneas entre sessão em background e foreground podem gerar conflitos na working copy viva.

9.24.6 Ferramentas e hooks de worktree

O Claude Code expõe ferramentas e eventos específicos para integração com o ciclo de vida de worktrees:

• EnterWorktree: ferramenta para entrar em um worktree; a partir de v2.1.157, ela pode alternar entre worktrees gerenciados pelo Claude no meio da sessão.
• ExitWorktree: ferramenta para sair e limpar o worktree atual.
• WorktreeCreate: evento de hook disparado quando um worktree é criado.
• WorktreeRemove: evento de hook disparado quando um worktree é removido.

Também a partir de v2.1.157, os worktrees gerenciados pelo Claude ficam desbloqueados quando o agente termina, permitindo que git worktree remove e git worktree prune façam a limpeza.

9.24.7 Limpeza automática

Se nenhuma alteração for feita no worktree, ele é limpo automaticamente ao final da sessão.

9.24.8 Quando usar

• Trabalhar em uma feature branch sem mexer na branch principal.
• Executar testes isoladamente sem afetar a working directory principal.
• Experimentar mudanças descartáveis com segurança.
• Usar sparse-checkout em monorepos para iniciar mais rápido.

9.25 Sandboxing

Sandboxing fornece isolamento de filesystem e rede em nível de sistema operacional para comandos Bash executados pelo Claude Code. Ele complementa as regras de permissão e adiciona uma camada extra de proteção.

9.25.1 Como habilitar

Você pode ativar por comando ou por flag de inicialização:

/sandbox

claude --sandbox       # habilita sandboxing
claude --no-sandbox    # desabilita sandboxing

9.25.2 Configurações disponíveis

As opções de sandbox permitem ajustar leitura, escrita e rede com granularidade fina:

• sandbox.enabled: liga ou desliga o sandboxing.
• sandbox.failIfUnavailable: faz a sessão falhar se o sandbox não puder ser ativado.
• sandbox.filesystem.allowWrite: caminhos liberados para escrita.
• sandbox.filesystem.allowRead: caminhos liberados para leitura.
• sandbox.filesystem.denyRead: caminhos bloqueados para leitura.
• sandbox.network.allowedDomains: domínios acessíveis pelos processos iniciados via Bash; aceita curinga *..
• sandbox.network.deniedDomains: domínios bloqueados mesmo quando o curinga em allowedDomains permitiria acesso; disponível a partir de v2.1.113+.
• sandbox.enableWeakerNetworkIsolation: habilita isolamento de rede mais fraco no macOS.
• sandbox.bwrapPath: a partir de v2.1.133+ em Linux/WSL, informa o caminho do binário bubblewrap; padrão: busca via $PATH.
• sandbox.socatPath: a partir de v2.1.133+ em Linux/WSL, informa o caminho do binário socat; padrão: busca via $PATH.
• sandbox.credentials: a partir de v2.1.187+, impede que comandos em sandbox leiam arquivos de credenciais e variáveis de ambiente secretas.
• sandbox.allowAppleEvents: a partir de v2.1.181+ no macOS, permite que comandos em sandbox enviem Apple Events.

9.25.3 Exemplo com caminhos personalizados no Linux/WSL

{
  "sandbox": {
    "bwrapPath": "/opt/bubblewrap/bin/bwrap",
    "socatPath": "/opt/socat/bin/socat"
  }
}

9.25.4 Exemplo com bloqueio específico de domínios

{
  "sandbox": {
    "network": {
      "allowedDomains": ["*.example.com"],
      "deniedDomains": ["evil.example.com"]
    }
  }
}

Nesse caso, o curinga libera subdomínios de example.com, mas deniedDomains continua bloqueando explicitamente evil.example.com.

9.25.5 Exemplo completo de sandbox

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "filesystem": {
      "allowWrite": ["/Users/me/project"],
      "allowRead": ["/Users/me/project", "/usr/local/lib"],
      "denyRead": ["/Users/me/.ssh", "/Users/me/.aws"]
    },
    "enableWeakerNetworkIsolation": true
  }
}

9.25.6 Como funciona

• Comandos Bash são executados em ambiente isolado com acesso restrito ao filesystem.
• O acesso de rede pode ser controlado para evitar conexões externas não intencionais.
• O sandbox funciona junto com regras de permissão, reforçando a segurança em profundidade.
• No macOS, usa-se sandbox.enableWeakerNetworkIsolation porque isolamento total de rede não está disponível.

9.25.7 Casos de uso

• Executar código não confiável ou gerado automaticamente com mais segurança.
• Evitar modificações acidentais fora do projeto.
• Restringir rede durante tarefas automatizadas.

9.26 Managed Settings (Enterprise)

Managed Settings permitem que administradores de empresas distribuam configurações do Claude Code usando ferramentas nativas da plataforma, mantendo políticas centralizadas e consistentes.

9.26.1 Formas de implantação

Plataforma	Método	Desde
macOS	Arquivos plist gerenciados via MDM	v2.1.51+
Windows	Windows Registry	v2.1.51+
Multiplataforma	Arquivos de configuração gerenciados	v2.1.51+
Multiplataforma	Managed drop-ins em managed-settings.d/	v2.1.83+

9.26.2 Managed drop-ins

A partir de v2.1.83, administradores podem publicar vários arquivos de política em um diretório managed-settings.d/. Os arquivos são mesclados em ordem alfabética, o que permite organizar defaults de organização, políticas de equipe e ajustes por projeto de maneira modular.

~/.claude/managed-settings.d/
  00-org-defaults.json
  10-team-policies.json
  20-project-overrides.json

9.26.3 Configurações gerenciadas disponíveis

• disableBypassPermissionsMode: impede usuários de ativarem o modo de bypass.
• availableModels: restringe quais modelos podem ser selecionados.
• enforceAvailableModels: a partir de v2.1.175, quando true, a lista de availableModels também restringe o modelo padrão; se o default configurado não estiver na lista, o Claude Code usa o primeiro modelo permitido. Configurações de usuário e projeto não conseguem ampliar uma lista gerenciada.
• allowedChannelPlugins: controla quais plugins de canal são permitidos.
• autoMode.environment: define infraestrutura confiável para o modo automático.
• wslInheritsWindowsSettings: apenas Windows/WSL, a partir de v2.1.118+; quando true, o Claude Code executado no WSL herda as configurações gerenciadas do host Windows, aplicando as políticas do Registry/MDM também ao shell WSL.
• parentSettingsBehavior: a partir de v2.1.133+ e em nível admin, controla como o SDK mescla managedSettings com configurações do processo pai. "first-wins" mantém a precedência atual; "merge" faz deep merge de valores.
• Políticas customizadas da organização para permissões e ferramentas.

9.26.4 Exemplo de plist no macOS

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>disableBypassPermissionsMode</key>
  <true/>
  <key>availableModels</key>
  <array>
    <string>claude-sonnet-4-6</string>
    <string>claude-haiku-4-5</string>
  </array>
</dict>
</plist>

9.27 Configuração e arquivos de settings

9.27.1 Locais dos arquivos de configuração

1. Config global: ~/.claude/config.json
2. Config do projeto: ./.claude/config.json
3. Config do usuário: ~/.config/claude-code/settings.json

9.27.2 Exemplo completo de configuração avançada

Configuração base com permissões, hooks e MCP:

{
  "permissions": {
    "mode": "default"
  },
  "hooks": {
    "PreToolUse:Edit": "eslint --fix ${file_path}",
    "PostToolUse:Write": "~/.claude/hooks/security-scan.sh"
  },
  "mcp": {
    "enabled": true,
    "servers": {
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"]
      }
    }
  }
}

Exemplo estendido com permissões de ferramenta, múltiplos hooks e variáveis de ambiente para MCP:

{
  "permissions": {
    "mode": "default",
    "allowedTools": ["Bash(git log:*)", "Read"],
    "disallowedTools": ["Bash(rm -rf:*)"]
  },

  "hooks": {
    "PreToolUse": [{ "matcher": "Edit", "hooks": ["eslint --fix ${file_path}"] }],
    "PostToolUse": [{ "matcher": "Write", "hooks": ["~/.claude/hooks/security-scan.sh"] }],
    "Stop": [{ "hooks": ["~/.claude/hooks/notify.sh"] }]
  },

  "mcp": {
    "enabled": true,
    "servers": {
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
}

9.27.3 Configurações adicionais por usuário

Os itens abaixo ficam em ~/.claude/settings.json ou em ./.claude/settings.json e controlam comportamento interativo individual:

• askUserQuestionTimeout: continua automaticamente uma caixa de diálogo AskUserQuestion após um período ocioso. A partir de v2.1.200, esses diálogos não continuam automaticamente por padrão; definir essa chave reativa o auto-continue com timeout.
• enableArtifact: habilita ou desabilita, por usuário, a ferramenta Artifact. Disponível em v2.1.196.

9.27.4 Modelos de fallback com fallbackModel

O setting fallbackModel permite configurar até três modelos de fallback, usados em ordem quando o modelo principal está sobrecarregado ou indisponível.

{
  "fallbackModel": ["claude-opus-4-8", "claude-sonnet-4-6", "claude-haiku-4-5"]
}

A partir de v2.1.166, a flag --fallback-model também vale para sessões interativas, e não apenas para modos headless. Em caso de fallback, o Claude Code tenta novamente uma vez um erro inesperado classificado como não-retryable; entretanto, erros de autenticação, rate-limit, tamanho de requisição e transporte continuam falhando imediatamente.

9.27.5 Variáveis de ambiente

As variáveis de ambiente podem sobrescrever configurações e são úteis para perfis, automação e execução em CI.

Seleção de modelo:

export ANTHROPIC_MODEL=claude-opus-4-8
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-8
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

API e autenticação:

export ANTHROPIC_API_KEY=sk-ant-...

Thinking e esforço:

export MAX_THINKING_TOKENS=16000
export CLAUDE_CODE_EFFORT_LEVEL=high   # low, medium, high, xhigh (Opus 4.8/4.7) ou max — padrão high no Opus 4.8; suportado em Opus 4.8, Opus 4.7, Opus 4.6 e Sonnet 4.6

Feature toggles:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=true
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=true
export CLAUDE_CODE_DISABLE_CRON=1
export CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=true
export CLAUDE_CODE_DISABLE_TERMINAL_TITLE=true
export CLAUDE_CODE_DISABLE_1M_CONTEXT=true
export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=true
export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false
export CLAUDE_CODE_ENABLE_TASKS=true
export CLAUDE_CODE_SIMPLE=true              # definido pela flag --bare

MCP e busca de ferramentas:

export MAX_MCP_OUTPUT_TOKENS=50000
export ENABLE_TOOL_SEARCH=true

Prompt caching:

export ENABLE_PROMPT_CACHING_1H=1      # usa TTL de 1 hora; padrão é 5 minutos

Task management:

export CLAUDE_CODE_TASK_LIST_ID=my-project-tasks

Agent teams experimentais:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Subagent e plugins:

export CLAUDE_CODE_SUBAGENT_MODEL=sonnet
export CLAUDE_CODE_PLUGIN_SEED_DIR=./my-plugins
export CLAUDE_CODE_NEW_INIT=1

Subprocesso e streaming:

export CLAUDE_CODE_SUBPROCESS_ENV_SCRUB="SECRET_KEY,DB_PASSWORD"
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80
export CLAUDE_STREAM_IDLE_TIMEOUT_MS=30000
export ANTHROPIC_CUSTOM_MODEL_OPTION=my-custom-model
export SLASH_COMMAND_TOOL_CHAR_BUDGET=50000

Saída e package manager (v2.1.129+):

export CLAUDE_CODE_FORCE_SYNC_OUTPUT=1
export CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

Ferramenta PowerShell no Windows (v2.1.143+), padrão ligado para Bedrock/Vertex/Foundry no Windows:

export CLAUDE_CODE_USE_POWERSHELL_TOOL=0
export CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1

Workload identity federation (v2.1.141+):

export ANTHROPIC_WORKSPACE_ID=ws_abc123

Stop hook safety cap (v2.1.143+):

export CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=8

Observações importantes sobre versões:

• ENABLE_PROMPT_CACHING_1H=1 surgiu em v2.1.108 para aumentar o TTL do cache de prompt para 1 hora e reduzir cache misses em sessões longas e estáveis. Em v2.1.129, foi corrigido um bug que rebaixava silenciosamente o TTL para 5 minutos.
• CLAUDE_CODE_FORCE_SYNC_OUTPUT=1 resolve terminais cuja detecção automática falha, como o eat do Emacs.
• CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 habilita upgrades em segundo plano para instalações via Homebrew ou WinGet, que de outro modo não se atualizariam automaticamente.

9.27.6 Comandos de gerenciamento de configuração

O comando /config abre um menu interativo para ajustar opções como thinking, saída verbosa, modo de permissão e modelo ativo.

Usuário: /config
[abre o menu interativo de configuração]

No menu, pressione Enter ou Espaço para alternar a opção selecionada. A partir de v2.1.183+, Esc salva e fecha o menu.

Você também pode alterar uma opção diretamente pelo prompt sem abrir o menu:

/config thinking=false      # define uma chave única inline (v2.1.181+)
/config --help              # lista atalhos de configuração disponíveis (v2.1.183+)

A forma abreviada key=value funciona em sessões interativas, com -p e também em Remote Control.

9.27.7 Configuração por projeto

Crie .claude/config.json no diretório do projeto para aplicar regras específicas daquele repositório.

{
  "hooks": {
    "PreToolUse": [{ "matcher": "Bash", "hooks": ["npm test && npm run lint"] }]
  },
  "permissions": {
    "mode": "default"
  },
  "mcp": {
    "servers": {
      "project-db": {
        "command": "mcp-postgres",
        "env": {
          "DATABASE_URL": "${PROJECT_DB_URL}"
        }
      }
    }
  }
}

9.28 Agent Teams

Agent Teams é um recurso experimental que permite que várias instâncias do Claude Code colaborem em uma mesma tarefa. Ele vem desativado por padrão e pode mudar em releases futuras.

9.28.1 Como ativar

Você pode habilitar o recurso por variável de ambiente ou em settings:

# Variável de ambiente
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

{
  "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}

9.28.2 Como funciona

• Um team lead coordena a tarefa principal e distribui subtarefas.
• Teammates trabalham de forma independente, cada um com sua própria janela de contexto.
• Uma task list compartilhada ajuda na coordenação entre os membros da equipe.
• Você pode usar definições de subagentes em .claude/agents/ ou pela flag --agents para especializar papéis.

9.28.3 Modos de exibição

O recurso suporta três modos de apresentação, escolhidos com a flag --teammate-mode:

• in-process (padrão): os teammates executam no mesmo processo de terminal.
• tmux: cada teammate recebe um painel separado; requer tmux ou iTerm2.
• auto: o sistema escolhe automaticamente o modo mais adequado.

# Usa split panes do tmux para exibir os teammates
claude --teammate-mode tmux

# Usa explicitamente o modo in-process
claude --teammate-mode in-process

9.28.4 Casos de uso

• Refatorações grandes em que cada teammate cuida de módulos diferentes.
• Revisão e implementação em paralelo.
• Alterações coordenadas em vários arquivos do código.

Por ser experimental, o comportamento e as interfaces do Agent Teams podem mudar. Consulte a documentação oficial específica do recurso para referência completa.

9.29 Boas práticas operacionais

9.29.1 Plan mode

• Use para tarefas complexas com várias etapas.
• Revise os planos antes de aprovar.
• Edite o plano quando necessário.
• Não use para tarefas simples demais, pois adiciona atrito desnecessário.

9.29.2 Extended thinking

• Use para decisões arquiteturais.
• Use para resolução de problemas difíceis.
• Revise o raciocínio quando isso for útil para auditoria ou aprendizado.
• Não use para consultas simples, onde o custo adicional não compensa.

9.29.3 Background tasks

• Use para operações longas.
• Monitore o progresso das tarefas.
• Trate falhas com tolerância e retomada quando possível.
• Evite iniciar concorrência excessiva.

9.29.4 Permissões

• Use plan para revisão de código em modo leitura.
• Use default para desenvolvimento interativo.
• Use acceptEdits para automação com aprovação de edições.
• Use auto para trabalho autônomo com guardrails.
• Evite bypassPermissions a menos que seja absolutamente necessário.

9.29.5 Sessões

• Use sessões separadas para tarefas diferentes.
• Salve estados importantes da sessão.
• Limpe sessões antigas quando não forem mais úteis.
• Não misture trabalhos sem relação na mesma conversa.

9.30 Recursos e referências adicionais

Para aprofundar em recursos relacionados ao Claude Code, consulte a documentação oficial e os guias especializados sobre cada capacidade.

• Documentação oficial do modo interativo
• Documentação oficial do modo headless
• Referência da CLI
• Guia de Checkpoints — gerenciamento de sessão e rewind
• Slash Commands — referência de comandos
• Memory Guide — contexto persistente
• Skills Guide — capacidades autônomas
• Subagents Guide — execução delegada de tarefas
• MCP Guide — acesso a dados externos
• Hooks Guide — automação orientada a eventos
• Plugins Guide — extensões empacotadas
• Documentação oficial de tarefas agendadas
• Documentação oficial da integração com Chrome
• Documentação oficial do Remote Control
• Documentação oficial de keybindings
• Documentação oficial do aplicativo Desktop
• Documentação oficial do Agent Teams

Este material foi atualizado em 11 de julho de 2026, com base na versão 2.1.206 do Claude Code, e é compatível com os modelos Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8 e Claude Haiku 4.5.

9.31 Exemplos de configuração para cenários práticos

9.31.1 Ambiente de desenvolvimento

Um perfil de desenvolvimento tende a priorizar produtividade, tarefas em paralelo e automações leves.

{
  "general": {
    "model": "claude-sonnet-4-6",
    "temperature": 0.7
  },
  "planning": {
    "autoEnter": true,
    "complexityThreshold": 3,
    "requireApproval": true
  },
  "permissions": {
    "mode": "unrestricted"
  },
  "backgroundTasks": {
    "enabled": true,
    "maxConcurrentTasks": 3
  },
  "hooks": {
    "PreToolUse:Write": "prettier --write ${file_path}",
    "PostToolUse:Write": "eslint ${file_path}"
  }
}

9.31.2 Modo de code review

Para revisão sem alterações, a configuração tende a ser mais conservadora e focada em análise.

{
  "general": {
    "model": "claude-sonnet-4-6",
    "temperature": 0.3
  },
  "permissions": {
    "mode": "plan"
  },
  "extendedThinking": {
    "enabled": true,
    "showThinkingProcess": true
  },
  "planning": {
    "autoEnter": false
  }
}

9.31.3 Modo de aprendizado

Esse perfil favorece explicação, experimentação e checkpoint de progresso.

{
  "general": {
    "model": "claude-sonnet-4-6",
    "temperature": 0.5
  },
  "permissions": {
    "mode": "confirm"
  },
  "extendedThinking": {
    "enabled": true,
    "showThinkingProcess": true
  },
  "planning": {
    "autoEnter": true,
    "requireApproval": true,
    "showTimeEstimates": true
  },
  "checkpoints": {
    "autoCheckpoint": true
  }
}

9.31.4 Implantação em produção

Em produção, o objetivo é reduzir risco operacional e exigir validações explícitas.

{
  "general": {
    "model": "claude-opus-4-7",
    "temperature": 0.1
  },
  "permissions": {
    "mode": "confirm",
    "requireConfirmationFor": ["Bash", "Git", "Write", "Edit"]
  },
  "hooks": {
    "PreToolUse": "~/.claude/hooks/pre-commit.sh"
  },
  "checkpoints": {
    "autoCheckpoint": true
  },
  "planning": {
    "autoEnter": true,
    "requireApproval": true
  }
}

9.31.5 Pipeline CI/CD

Para automação em CI, o foco é previsibilidade, logs detalhados e falha explícita.

{
  "general": {
    "model": "claude-sonnet-4-6",
    "temperature": 0
  },
  "permissions": {
    "mode": "unrestricted"
  },
  "headless": {
    "exitOnError": true,
    "verbose": true,
    "timeout": 3600
  },
  "logging": {
    "level": "debug",
    "file": "./ci-claude.log"
  },
  "planning": {
    "autoEnter": false,
    "requireApproval": false
  }
}

9.31.6 Auditoria de segurança

Para análise de segurança, é comum aumentar a profundidade do raciocínio e aplicar hooks de varredura.

{
  "general": {
    "model": "claude-opus-4-7",
    "temperature": 0.2
  },
  "permissions": {
    "mode": "plan"
  },
  "extendedThinking": {
    "enabled": true,
    "showThinkingProcess": true,
    "minThinkingTime": 10
  },
  "hooks": {
    "PostToolUse:Read": "~/.claude/hooks/security-scan.sh ${file_path}"
  }
}

9.31.7 Otimização de performance

Nesse cenário, tarefas paralelas e checkpoints ajudam a comparar hipóteses com segurança.

{
  "general": {
    "model": "claude-sonnet-4-6",
    "temperature": 0.4
  },
  "planning": {
    "autoEnter": true,
    "requireApproval": true
  },
  "backgroundTasks": {
    "enabled": true,
    "maxConcurrentTasks": 5
  },
  "checkpoints": {
    "autoCheckpoint": true
  }
}

9.31.8 Pair programming

Em programação em dupla, o ideal é equilibrar visibilidade, aprovação e feedback contínuo.

{
  "general": {
    "model": "claude-sonnet-4-6",
    "temperature": 0.6
  },
  "permissions": {
    "mode": "confirm"
  },
  "planning": {
    "autoEnter": true,
    "requireApproval": true,
    "showTimeEstimates": true
  },
  "extendedThinking": {
    "enabled": true,
    "showThinkingProcess": true
  },
  "ui": {
    "compactMode": false,
    "showProgress": true
  }
}

9.31.9 Refatoração grande

Refatorações extensas exigem checkpoints, hooks de segurança e conferência explícita de mudanças.

{
  "general": {
    "model": "claude-opus-4-7",
    "temperature": 0.3
  },
  "planning": {
    "autoEnter": true,
    "requireApproval": true,
    "showTimeEstimates": true
  },
  "checkpoints": {
    "autoCheckpoint": true
  },
  "hooks": {
    "PreToolUse:Edit": "~/.claude/hooks/backup-file.sh ${file_path}",
    "PostToolUse:Edit": "npm test -- --findRelatedTests ${file_path}"
  },
  "permissions": {
    "mode": "confirm"
  }
}

9.31.10 Desenvolvimento autônomo

Para automação com autonomia controlada, combine modo automático com sandbox e tarefas em segundo plano.

{
  "general": {
    "model": "claude-sonnet-4-6",
    "temperature": 0.5
  },
  "permissions": {
    "mode": "auto"
  },
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": false
  },
  "backgroundTasks": {
    "enabled": true,
    "maxConcurrentTasks": 3
  }
}

9.31.11 Escrita de documentação

Quando o foco é documentação, você pode permitir maior liberdade de escrita e validar a saída com ferramentas de lint.

{
  "general": {
    "model": "claude-sonnet-4-6",
    "temperature": 0.7
  },
  "permissions": {
    "mode": "unrestricted"
  },
  "hooks": {
    "PostToolUse:Write": "markdownlint ${file_path}"
  }
}

9.32 Exemplos práticos de Planning Mode

O Planning Mode é mais útil quando você quer transformar uma intenção ampla em um plano executável, com fases, estimativas, riscos e critérios de sucesso antes de começar a modificar código. Em projetos reais, isso evita que o agente “mergulhe” na implementação cedo demais e deixe requisitos importantes de fora.

9.32.1 Exemplo 1: criar uma API REST para um blog

Sem planejamento, o fluxo costuma começar direto no código. Isso pode funcionar para tarefas pequenas, mas em uma API real existe risco de esquecer autenticação, modelagem de dados, paginação, validação, testes e entrega.

User: Build a REST API for a blog

Claude: I'll create the API...
[Starts coding immediately, may miss requirements]

Com Planning Mode, o comando /plan força a construção de uma estrutura de trabalho antes da implementação. O plano abaixo mostra o comportamento esperado para um projeto mais profissional: dividir o trabalho em fases, estimar tempo por etapa, listar tecnologias e pedir aprovação para seguir.

User: /plan Build a REST API for a blog

Claude: Let me create a comprehensive plan for the blog API.

## Blog REST API Implementation Plan

### Phase 1: Project Setup (15 min)
1. Initialize Node.js project with Express
2. Set up TypeScript configuration
3. Install dependencies (express, pg, jwt, joi)
4. Configure environment variables
5. Set up project structure

### Phase 2: Database Layer (30 min)
6. Design database schema
   - users table (id, email, password_hash, created_at)
   - posts table (id, user_id, title, content, published, created_at, updated_at)
   - comments table (id, post_id, user_id, content, created_at)
7. Create migration files
8. Set up database connection pool
9. Implement database models

### Phase 3: Authentication (45 min)
10. Implement user registration endpoint
11. Implement login endpoint with JWT
12. Create authentication middleware
13. Add password hashing with bcrypt
14. Implement token refresh logic

### Phase 4: Posts API (40 min)
15. GET /api/posts - List all published posts (with pagination)
16. GET /api/posts/:id - Get single post
17. POST /api/posts - Create new post (auth required)
18. PUT /api/posts/:id - Update post (auth required, ownership check)
19. DELETE /api/posts/:id - Delete post (auth required, ownership check)
20. GET /api/users/:id/posts - Get user's posts

### Phase 5: Comments API (30 min)
21. GET /api/posts/:id/comments - Get post comments
22. POST /api/posts/:id/comments - Add comment (auth required)
23. DELETE /api/comments/:id - Delete comment (auth required, ownership check)

### Phase 6: Validation & Error Handling (30 min)
24. Add request validation with Joi
25. Implement global error handler
26. Add input sanitization
27. Implement rate limiting

### Phase 7: Testing (60 min)
28. Write unit tests for models
29. Write integration tests for auth endpoints
30. Write integration tests for posts endpoints
31. Write integration tests for comments endpoints
32. Achieve 80%+ code coverage

### Phase 8: Documentation & Deployment (30 min)
33. Generate API documentation with Swagger
34. Create README with setup instructions
35. Add Docker configuration
36. Set up CI/CD pipeline

**Estimated Time**: 4.5 hours
**Files to Create**: ~25
**Key Technologies**: Express, PostgreSQL, JWT, TypeScript

**API Endpoints Summary**:
- Authentication: 2 endpoints
- Posts: 6 endpoints
- Comments: 3 endpoints
- Total: 11 endpoints

Ready to proceed? (yes/no/modify)

User: yes

Claude: Starting Phase 1: Project Setup...
[Implements each phase systematically]

Na prática, o valor do Planning Mode aqui está em quatro pontos: deixa explícito o escopo, antecipa os objetos do banco, organiza a ordem de implementação e reduz o risco de descobrir tarde demais que autenticação, paginação ou ownership precisam ser tratados.

9.32.2 Exemplo 2: migração de MongoDB para PostgreSQL

Migrações de banco exigem mais cuidado porque misturam compatibilidade de dados, risco de indisponibilidade e estratégia de rollback. O Planning Mode ajuda a transformar isso em uma sequência controlada.

User: /plan Migrate from MongoDB to PostgreSQL

Claude: This is a complex migration. Let me create a detailed plan.

## MongoDB to PostgreSQL Migration Plan

### Phase 1: Analysis & Preparation (Day 1)
1. Analyze current MongoDB schema
2. Identify data relationships and constraints
3. Document current data volume and growth rate
4. Design equivalent PostgreSQL schema
5. Plan data type mappings
6. Identify potential migration challenges

### Phase 2: PostgreSQL Setup (Day 1)
7. Set up PostgreSQL database
8. Create schema with tables, indexes, constraints
9. Set up connection pooling
10. Configure backup strategy

### Phase 3: Dual-Write Implementation (Day 2-3)
11. Create database abstraction layer
12. Implement dual-write to both databases
13. Add data consistency checks
14. Deploy dual-write to staging
15. Monitor for issues

### Phase 4: Data Migration (Day 4)
16. Create data export scripts for MongoDB
17. Create data import scripts for PostgreSQL
18. Implement data transformation logic
19. Run initial migration on copy of production data
20. Validate migrated data integrity

### Phase 5: Gradual Cutover (Day 5-7)
21. Enable dual-write in production
22. Migrate historical data in batches
23. Continuously validate data consistency
24. Monitor both databases
25. Fix any data synchronization issues

### Phase 6: PostgreSQL Primary (Day 8)
26. Switch read operations to PostgreSQL
27. Monitor query performance
28. Optimize slow queries
29. Continue dual-write for safety

### Phase 7: MongoDB Retirement (Day 9-10)
30. Stop writing to MongoDB
31. Keep MongoDB as backup for 2 weeks
32. Remove MongoDB dependencies from code
33. Archive MongoDB data
34. Decommission MongoDB instance

**Estimated Time**: 10 days
**Risk Level**: High
**Rollback Strategy**: Keep MongoDB running with dual-write
**Success Criteria**:
- Zero data loss
- <5% performance regression
- All tests passing

**Key Risks**:
1. Data inconsistency during migration
2. Query performance degradation
3. Application downtime
4. Data loss

**Mitigation**:
- Dual-write pattern for safety
- Gradual cutover
- Continuous monitoring
- Quick rollback capability

Proceed with this plan? (yes/no/modify)

User: Modify - let's add a rollback plan for each phase

Claude: Updated plan with rollback procedures for each phase...

Esse caso mostra uma prática avançada importante: não basta listar tarefas; o plano precisa mencionar risco, impacto e uma estratégia de retorno. Em migrações críticas, isso costuma ser obrigatório para operação profissional.

9.32.3 Exemplo 3: refatoração de frontend React de classes para hooks

Refatorações amplas também se beneficiam do planejamento porque têm dependências internas entre componentes, testes e bibliotecas de terceiros. O plano abaixo explicita ordem de migração, categorias de complexidade e pontos de checagem.

User: /plan Refactor our React app from class components to hooks

Claude: I'll create a systematic refactoring plan.

## React Class to Hooks Migration Plan

### Phase 1: Preparation & Analysis (2 hours)
1. Audit all class components (find all .jsx/.tsx files)
2. Categorize by complexity:
   - Simple (state only): ~15 components
   - Medium (lifecycle methods): ~23 components
   - Complex (multiple lifecycle, refs): ~8 components
3. Identify third-party libraries that need updates
4. Create component dependency graph
5. Plan migration order (leaf nodes first)

### Phase 2: Setup & Tooling (1 hour)
6. Update React to v18+
7. Set up ESLint rules for hooks
8. Create conversion templates
9. Set up automated tests
10. Create checkpoint before starting

### Phase 3: Migrate Simple Components (4 hours)
11. Convert simple stateful components (15 components)
12. Replace this.state with useState
13. Replace this.setState with state setters
14. Test each component after conversion
15. Update tests

### Phase 4: Migrate Medium Components (8 hours)
16. Convert components with lifecycle methods (23 components)
17. Replace componentDidMount with useEffect
18. Replace componentDidUpdate with useEffect
19. Replace componentWillUnmount with useEffect cleanup
20. Test thoroughly

### Phase 5: Migrate Complex Components (12 hours)
21. Convert complex components (8 components)
22. Replace refs with useRef
23. Extract custom hooks for shared logic
24. Handle edge cases (multiple useEffect)
25. Extensive testing

### Phase 6: Shared Logic Extraction (6 hours)
26. Identify duplicated logic across components
27. Create custom hooks:
    - useAuth
    - useFetch
    - useLocalStorage
    - useDebounce
28. Refactor components to use custom hooks
29. Test custom hooks independently

### Phase 7: Performance Optimization (4 hours)
30. Add React.memo where needed
31. Optimize with useCallback
32. Optimize with useMemo
33. Profile and fix performance regressions

### Phase 8: Cleanup & Documentation (2 hours)
34. Remove unused class component utilities
35. Update documentation
36. Update coding guidelines
37. Create migration guide for team

**Estimated Time**: 5 days (39 hours)
**Files to Modify**: 46 components
**Risk Level**: Medium

**Migration Order**:
1. Leaf components (no dependencies)
2. Mid-level components
3. Top-level container components
4. App.jsx (last)

**Testing Strategy**:
- Unit tests for each component
- Integration tests for user flows
- Visual regression tests
- Performance benchmarks

**Success Metrics**:
- All tests passing
- No visual regressions
- Performance maintained or improved
- Bundle size not significantly increased

Proceed? (yes/no/modify)

Esse tipo de plano deixa claro que a migração não deve começar pelo componente raiz. Primeiro vêm os nós-folha, depois os níveis intermediários, e só no fim o App.jsx, porque ele concentra dependências e pode amplificar regressões.

9.32.4 Exemplo 4: implementação de segurança abrangente

Quando o objetivo é segurança, Planning Mode precisa capturar controles preventivos, detecção, conformidade e treino da equipe. O plano abaixo cobre os eixos mais relevantes de uma aplicação web profissional.

User: /plan Implement comprehensive security for our web app

Claude: Let me create a thorough security implementation plan.

## Web Application Security Implementation Plan

### Phase 1: Security Audit (Day 1)
1. Run automated security scanners (npm audit, Snyk)
2. Review dependencies for vulnerabilities
3. Check OWASP Top 10 compliance
4. Audit authentication flows
5. Review data handling practices
6. Document current security gaps

### Phase 2: Authentication Hardening (Day 2-3)
7. Implement strong password requirements
8. Add password strength meter
9. Implement rate limiting on login
10. Add account lockout after failed attempts
11. Implement 2FA (TOTP)
12. Add session management improvements
13. Implement secure password reset flow

### Phase 3: Authorization & Access Control (Day 3-4)
14. Implement RBAC (Role-Based Access Control)
15. Add permission checks on all endpoints
16. Implement principle of least privilege
17. Add audit logging for sensitive operations
18. Implement resource-level permissions

### Phase 4: Data Protection (Day 4-5)
19. Implement encryption at rest (sensitive fields)
20. Ensure TLS/SSL for all communications
21. Implement secure session storage
22. Add PII data masking in logs
23. Implement data retention policies
24. Add secure file upload handling

### Phase 5: Input Validation & Sanitization (Day 5-6)
25. Implement input validation on all endpoints
26. Add XSS protection (Content Security Policy)
27. Implement SQL injection prevention (parameterized queries)
28. Add CSRF protection
29. Implement request size limits
30. Add file upload type validation

### Phase 6: Security Headers & Configuration (Day 6)
31. Add security headers:
    - Strict-Transport-Security
    - X-Content-Type-Options
    - X-Frame-Options
    - X-XSS-Protection
    - Content-Security-Policy
32. Configure CORS properly
33. Disable unnecessary HTTP methods
34. Remove server version headers

### Phase 7: Monitoring & Logging (Day 7)
35. Implement security event logging
36. Add anomaly detection
37. Set up intrusion detection
38. Implement real-time alerting
39. Create security dashboard

### Phase 8: Testing & Documentation (Day 8-9)
40. Perform penetration testing
41. Run security scanners
42. Test all security features
43. Create security documentation
44. Train team on security practices
45. Create incident response plan

### Phase 9: Compliance & Policies (Day 10)
46. GDPR compliance check
47. Create privacy policy
48. Implement data subject rights
49. Add cookie consent
50. Create security policies documentation

**Estimated Time**: 10 days
**Risk Level**: Critical
**Priority**: High

**Security Improvements Summary**:
- Authentication: 7 enhancements
- Authorization: 5 enhancements
- Data Protection: 6 enhancements
- Input Validation: 6 enhancements
- Infrastructure: 9 enhancements
- Monitoring: 5 enhancements

**Compliance**: OWASP Top 10, GDPR

**Success Criteria**:
- Zero critical vulnerabilities
- All OWASP Top 10 mitigated
- Security score >90/100
- All pen test issues resolved

Proceed? (yes/no/modify)

Nesse caso, o plano separa autenticação, autorização, proteção de dados, sanitização, cabeçalhos, observabilidade e compliance. Isso é importante porque segurança não é uma única tarefa; é uma combinação de camadas que se reforçam.

9.32.5 Exemplo 5: otimização de performance para e-commerce

Em problemas de performance, o Planning Mode ajuda a diagnosticar antes de otimizar. Sem isso, é comum mexer em pontos de baixo impacto ou alterar a aplicação sem medir ganho real.

User: /plan Optimize our slow e-commerce website

Claude: Let me create a comprehensive performance optimization plan.

## E-commerce Performance Optimization Plan

### Phase 1: Performance Audit (4 hours)
1. Run Lighthouse audit
2. Analyze Chrome DevTools performance profile
3. Measure Core Web Vitals:
   - LCP (Largest Contentful Paint)
   - FID (First Input Delay)
   - CLS (Cumulative Layout Shift)
4. Identify performance bottlenecks
5. Create baseline performance metrics

**Current Metrics**:
- LCP: 4.2s (target: <2.5s)
- FID: 280ms (target: <100ms)
- CLS: 0.25 (target: <0.1)
- Page Load: 8.3s (target: <3s)

### Phase 2: Image Optimization (6 hours)
6. Convert images to WebP format
7. Implement responsive images
8. Add lazy loading for images
9. Optimize image sizes (compression)
10. Implement CDN for images
11. Add image placeholders

**Expected Impact**: -40% load time

### Phase 3: Code Splitting & Lazy Loading (8 hours)
12. Implement route-based code splitting
13. Lazy load non-critical components
14. Split vendor bundles
15. Optimize chunk sizes
16. Implement dynamic imports
17. Add preloading for critical resources

**Expected Impact**: -30% initial bundle size

### Phase 4: Caching Strategy (6 hours)
18. Implement browser caching (Cache-Control)
19. Add service worker for offline support
20. Implement API response caching
21. Add Redis cache for database queries
22. Implement stale-while-revalidate
23. Configure CDN caching

**Expected Impact**: -50% API response time

### Phase 5: Database Optimization (8 hours)
24. Add database indexes
25. Optimize slow queries (>100ms)
26. Implement query result caching
27. Add connection pooling
28. Denormalize where appropriate
29. Implement database read replicas

**Expected Impact**: -60% database query time

### Phase 6: Frontend Optimization (10 hours)
30. Minimize and compress JavaScript
31. Minimize and compress CSS
32. Remove unused CSS (PurgeCSS)
33. Implement critical CSS
34. Defer non-critical JavaScript
35. Reduce DOM size
36. Optimize React rendering (memo, useMemo)
37. Implement virtual scrolling for long lists

**Expected Impact**: -35% JavaScript execution time

### Phase 7: Network Optimization (4 hours)
38. Enable HTTP/2
39. Implement resource hints (preconnect, prefetch)
40. Reduce number of HTTP requests
41. Enable Brotli compression
42. Optimize third-party scripts

**Expected Impact**: -25% network time

### Phase 8: Monitoring & Testing (4 hours)
43. Set up performance monitoring (Datadog/New Relic)
44. Add Real User Monitoring (RUM)
45. Create performance budgets
46. Set up automated Lighthouse CI
47. Test on real devices

**Estimated Time**: 50 hours (2 weeks)

**Target Metrics** (90th percentile):
- LCP: <2.0s (from 4.2s) ✅
- FID: <50ms (from 280ms) ✅
- CLS: <0.05 (from 0.25) ✅
- Page Load: <2.5s (from 8.3s) ✅

**Expected Revenue Impact**:
- 100ms faster = 1% conversion increase
- Target: 5.8s improvement = ~58% conversion increase
- Estimated additional revenue: Significant

**Priority Order**:
1. Image optimization (quick wins)
2. Code splitting (high impact)
3. Caching (high impact)
4. Database optimization (critical)
5. Frontend optimization (polish)

Proceed with this plan? (yes/no/modify)

Aqui aparecem também métricas-base, metas-alvo e impacto esperado por fase. Em operação profissional, isso é o que permite saber se a otimização está funcionando ou apenas “mudando o código”.

9.32.6 O que esses exemplos ensinam

• Clareza: o plano mostra a rota antes da execução, reduzindo ambiguidade.

• Estimativa: tempo e esforço são explicitados para calibrar expectativa.

• Análise de risco: problemas prováveis aparecem cedo, antes de virar incidente.

• Priorização: tarefas ficam em ordem lógica e segura.

• Aprovação: o usuário valida o plano antes do agente agir.

• Modificação: feedback pode alterar o plano, inclusive adicionando rollback ou etapas de validação.

9.32.7 Quando usar Planning Mode

O modo de planejamento é recomendado quando o trabalho é grande, interdependente ou sensível a risco. Ele é útil para alinhar expectativas e reduzir retrabalho.

• Use sempre para projetos de vários dias, colaboração em equipe, mudanças críticas em sistema, aprendizado de um conceito novo e refatorações complexas.

• Evite usar para correções simples, ajustes pequenos, perguntas diretas e experimentos rápidos.

Na prática, isso significa que Planning Mode tende a valer a pena quando o custo de começar errado é alto. Em tarefas pequenas, o plano pode virar burocracia desnecessária.

9.32.8 Boas práticas ao trabalhar com planos

1. Revise o plano com atenção antes de aprovar.

2. Peça ajustes quando identificar lacunas, suposições erradas ou ordem inadequada.

3. Quebre tarefas complexas em fases menores e verificáveis.

4. Use estimativas realistas, evitando prazos otimistas demais.

5. Inclua rollback sempre que houver risco operacional.

6. Defina critérios de sucesso mensuráveis.

7. Planeje testes em cada fase, não apenas no final.

Essas práticas fazem diferença porque um bom plano não serve só para organizar; ele também cria um contrato operacional entre intenção, execução e validação.

9.33 Configuração segura de permissões para Auto Mode

O script setup-auto-mode-permissions.py cria ou atualiza o arquivo ~/.claude/settings.json com uma base conservadora de permissões para Claude Code. O objetivo é habilitar um conjunto mínimo e seguro de ações, principalmente leitura e inspeção local, e permitir ampliação controlada por flags opcionais.

Esse utilitário é útil quando você quer preparar um ambiente de Auto Mode sem liberar de início comandos perigosos, como edição de arquivos, execução de testes arbitrários, mutação de repositório ou instalações de pacotes.

9.33.1 Objetivo e comportamento geral

Por padrão, o script adiciona permissões de leitura e comandos locais de baixo risco. A lista principal inclui inspeção de arquivos, busca, leitura de informações do sistema e vários comandos de Git em modo apenas leitura. Recursos mais sensíveis ficam atrás de flags explícitas.

A lógica também evita duplicar permissões já existentes no arquivo de configuração. Se a regra já estiver presente, ela não é inserida novamente.

O script grava o JSON de forma atômica: primeiro cria um arquivo temporário na mesma pasta e depois substitui o destino. Isso reduz risco de corrupção de arquivo caso a escrita seja interrompida.

9.33.2 Permissões-base incluídas por padrão

O conjunto CORE_PERMISSIONS representa a camada básica e mais conservadora. Ele cobre leitura de conteúdo, descoberta de arquivos, pesquisa textual, uso de agentes e habilidades, além de busca e acesso web.

Read(*)
Glob(*)
Grep(*)
Agent(*)
Skill(*)
WebSearch(*)
WebFetch(*)

Também são liberados comandos Bash considerados de inspeção local ou baixa capacidade de alteração, como navegação, leitura e inspeção de metadados.

Bash(ls:*)
Bash(pwd:*)
Bash(which:*)
Bash(echo:*)
Bash(cat:*)
Bash(head:*)
Bash(tail:*)
Bash(wc:*)
Bash(sort:*)
Bash(uniq:*)
Bash(find:*)
Bash(dirname:*)
Bash(basename:*)
Bash(realpath:*)
Bash(file:*)
Bash(stat:*)
Bash(diff:*)
Bash(md5sum:*)
Bash(sha256sum:*)
Bash(date:*)
Bash(env:*)
Bash(printenv:*)

Para Git, o baseline permite consultas de estado e histórico, sem escrita de repositório:

Bash(git status:*)
Bash(git log:*)
Bash(git diff:*)
Bash(git branch:*)
Bash(git show:*)
Bash(git rev-parse:*)
Bash(git remote -v:*)
Bash(git remote get-url:*)
Bash(git stash list:*)

Esse desenho é intencional: ele permite diagnosticar o ambiente, entender o estado do código e inspecionar dados sem conceder mutação por padrão.

9.33.3 Permissões opcionais e quando usá-las

O script oferece categorias adicionais via flags. Cada uma amplia a superfície de ação e deve ser habilitada somente quando houver necessidade real.

9.33.4 --include-edits

Adiciona permissões de edição local:

Edit(*)
Write(*)
NotebookEdit(*)
TaskCreate(*)
TaskUpdate(*)

Use essa opção quando o agente precisar modificar arquivos, criar conteúdo ou atualizar tarefas. Ela é opcional porque sai da postura somente leitura. Em ambientes sensíveis, habilitar edição sem revisão pode causar alterações indesejadas em código, documentação ou notebooks.

9.33.5 --include-tests

Libera comandos de teste e build local, incluindo:

Bash(npm test:*)
Bash(cargo test:*)
Bash(go test:*)
Bash(pytest:*)
Bash(python3 -m pytest:*)
Bash(make:*)
Bash(cmake:*)

Essa opção é útil para fluxo de desenvolvimento e validação automatizada, mas continua sendo opt-in porque esses comandos podem executar scripts do projeto e hooks com efeitos colaterais. Em outras palavras, “rodar testes” não é sempre inofensivo; em alguns repositórios, o comando pode compilar, gerar arquivos ou chamar etapas personalizadas.

9.33.6 --include-git-write

Adiciona operações de escrita no Git local:

Bash(git add:*)
Bash(git commit:*)
Bash(git checkout:*)
Bash(git switch:*)
Bash(git stash:*)
Bash(git tag:*)

Esse grupo fica fora do baseline porque é fácil causar confusão com mudanças de branch, criação de tags ou operações de stash. O próprio comentário do script destaca que comandos de reescrita de histórico permanecem fora da base por serem fáceis de usar de forma indevida. Mesmo assim, até essas permissões incluídas aqui devem ser tratadas com cautela em automação.

9.33.7 --include-packages

Adiciona comandos de instalação de dependências e pacotes:

Bash(npm ci:*)
Bash(npm install:*)
Bash(pip install:*)
Bash(pip3 install:*)

Essa categoria é excluída por padrão porque instalações podem disparar hooks, baixar código, alterar lockfiles ou executar scripts do projeto. Em pipelines controlados ela pode ser necessária, mas o risco operacional é maior que em permissões de leitura.

9.33.8 --include-gh-write

Permite escrita via GitHub CLI para criação de pull requests:

Bash(gh pr create:*)

Use quando o fluxo automatizado precisar abrir PRs. É uma permissão de impacto externo, então deve ficar explicitamente habilitada apenas em cenários aprovados.

9.33.9 --include-gh-read

Adiciona leitura via GitHub CLI para consultas sobre PRs, issues e repositórios:

Bash(gh pr view:*)
Bash(gh pr list:*)
Bash(gh issue view:*)
Bash(gh issue list:*)
Bash(gh repo view:*)

Essa opção amplia a visibilidade do agente sobre o GitHub sem conceder escrita. É útil para triagem, revisão e acompanhamento, especialmente quando o fluxo depende de contexto remoto.

9.33.10 Interface de linha de comando

O script usa argparse para expor um conjunto claro de flags:

python3 setup-auto-mode-permissions.py
python3 setup-auto-mode-permissions.py --dry-run
python3 setup-auto-mode-permissions.py --include-edits --include-tests

As opções disponíveis são:

• --dry-run: mostra o que seria adicionado, sem gravar settings.json.

• --include-edits: adiciona permissões de edição.

• --include-tests: adiciona testes e builds locais.

• --include-git-write: adiciona mutações locais de Git.

• --include-packages: adiciona instalações de pacotes.

• --include-gh-write: adiciona escrita no GitHub CLI.

• --include-gh-read: adiciona leitura no GitHub CLI.

9.33.11 Como o arquivo de configuração é carregado

A função load_settings(path) lê o arquivo alvo e aplica validações importantes. Se o arquivo não existir, o script considera que a configuração começa vazia. Se o JSON estiver inválido, o programa interrompe com uma mensagem clara. Se o conteúdo do arquivo não for um objeto JSON, também ocorre erro.

Esse comportamento protege contra um cenário comum em automação: tentar inserir permissões em uma configuração corrompida ou em formato inesperado.

9.33.12 Como a lista final de permissões é montada

A função build_permissions(args) começa com CORE_PERMISSIONS e acrescenta os blocos opcionais conforme as flags escolhidas. O resultado é uma lista única de regras prontas para serem mescladas no arquivo de settings.

Isso significa que a política padrão é sempre a mesma, e os acréscimos dependem da intenção explícita do usuário. O script não habilita edição, testes ou Git write por inferência.

9.33.13 Como o script evita duplicação

Antes de escrever, a função append_unique(existing, new_items) verifica quais permissões já estavam na lista allow. Apenas as novas são adicionadas e relatadas ao usuário. Esse detalhe é importante em execuções repetidas, porque o script pode ser rodado várias vezes sem poluir o arquivo com duplicatas.

Na prática, se nenhuma regra nova for encontrada, o script encerra com a mensagem de que não há nada para adicionar.

9.33.14 Escrita atômica do JSON

A função atomic_write_json(path, payload) cria o diretório pai se necessário, grava o JSON em um arquivo temporário com indentação de dois espaços e depois substitui o destino final. Esse processo reduz risco de perda de dados caso haja interrupção durante a gravação.

Esse comportamento é relevante para ambientes em que o arquivo ~/.claude/settings.json é editado por automação, sincronização ou múltiplas execuções em sequência.

9.33.15 Fluxo principal de execução

A função main() segue esta ordem:

1. lê os argumentos de linha de comando;

2. monta a lista de permissões selecionadas;

3. carrega as configurações existentes;

4. garante que permissions seja um objeto JSON;

5. garante que permissions.allow seja um array;

6. adiciona apenas regras novas;

7. mostra o que será ou foi inserido;

8. em --dry-run, não grava nada;

9. caso contrário, escreve o arquivo com segurança.

Se added ficar vazio, o script não reescreve o arquivo e informa que tudo já estava presente. Isso evita operações desnecessárias e reduz ruído em automações.

9.33.16 Comportamento das mensagens de saída

Quando houver novas regras, o script imprime a contagem e lista item a item com o prefixo +. Em seguida:

• se for --dry-run, exibe que nenhuma mudança foi gravada;

• se não for dry-run, confirma a gravação em ~/.claude/settings.json.

Esse retorno textual é útil tanto para uso humano quanto para logs de automação.

9.33.17 Exemplo prático de uso

Para iniciar com o baseline mais conservador, sem gravação, use:

python3 setup-auto-mode-permissions.py --dry-run

Para permitir edição e testes locais ao mesmo tempo:

python3 setup-auto-mode-permissions.py --include-edits --include-tests

Para um fluxo mais amplo, que inclua manipulação local de Git, instalação de dependências e integração com GitHub CLI:

python3 setup-auto-mode-permissions.py --include-edits --include-tests --include-git-write --include-packages --include-gh-read --include-gh-write

9.33.18 Validações e erros que podem ocorrer

O script é intencionalmente rígido com a estrutura de configuração. Isso evita que permissões sejam escritas em formatos inconsistentes. Os principais erros são:

• JSON inválido em settings.json: o script interrompe a execução com a posição do erro.

• Conteúdo não for objeto JSON: o arquivo precisa ser um objeto, não uma lista ou valor escalar.

• permissions não for objeto: a estrutura esperada é { "permissions": { ... } }.

• permissions.allow não for array: a lista de permissões permitidas deve ser um array JSON.

Essas verificações são importantes porque mantêm a configuração previsível e previnem gravações acidentais em formatos inválidos.

9.33.19 Riscos e limitações práticas

Embora o script comece com um baseline conservador, ele ainda amplia permissões de forma bastante poderosa quando as flags opcionais são usadas. Em especial:

• permissões de teste e build podem executar scripts arbitrários do projeto;

• instalações de pacotes podem rodar hooks e baixar código;

• mutações de Git podem alterar branch, index e histórico local;

• escrita no GitHub CLI pode criar PRs e interagir com recursos remotos.

Por isso, a política correta é habilitar apenas o que for necessário para a tarefa atual. O padrão do script é seguro por design, mas a segurança final depende da combinação de flags escolhida.

9.33.20 Dependência de versão e compatibilidade

O código usa recursos estáveis do Python 3, como pathlib, tempfile.NamedTemporaryFile, json e anotações modernas com from __future__ import annotations. Não há dependência de biblioteca externa. Isso torna o utilitário simples de portar e fácil de executar em ambientes de automação básicos.

A compatibilidade do arquivo gerado depende do esquema esperado pelo Claude Code na versão em uso. O próprio material de planejamento mostra compatibilidade com modelos recentes como Claude Sonnet 4.6, Claude Opus 4.8 e Claude Haiku 4.5, mas a política de permissões deve ser sempre validada no contexto da instalação e da versão do produto.

10 Módulo — CLI completa, headless, sessões e CI/CD

10.1 CLI Reference

10.1.1 Visão geral

A interface de linha de comando do Claude Code é o ponto de entrada principal para conversar com o assistente fora da UI gráfica. Ela serve para executar consultas rápidas, manter sessões longas, ajustar o modelo em uso, controlar permissões e integrar o Claude ao fluxo de desenvolvimento, inclusive em automação e CI/CD.

10.1.2 Arquitetura de execução

Na prática, o comando claude pode seguir caminhos diferentes conforme o modo escolhido:

• modo interativo, com conversa contínua no terminal;
• modo de impressão, usado para executar uma única solicitação e sair;
• retomada de sessão, para carregar contexto anterior;
• integrações com API, sessões web, agentes, MCP e automação remota.

Terminal do usuário
  └─ claude [opções] [consulta]
      ├─ modo interativo
      ├─ modo print (-p)
      ├─ retomar sessão (-c / -r)
      └─ integração com ferramentas, modelos e permissões

10.1.3 Empacotamento e runtime

A partir da versão v2.1.113, o Claude Code CLI passou a iniciar um binário nativo por plataforma, distribuído via dependências opcionais do npm. Isso significa que macOS, Linux e Windows recebem o binário apropriado no momento da instalação, e o runtime JavaScript empacotado deixou de ser o padrão em macOS e Linux.

O comando de instalação continua o mesmo e segue como o caminho recomendado:

npm install -g @anthropic-ai/claude-code

Em ambientes corporativos com proxy ou allowlist, é preciso liberar o host de downloads nativos. Desde v2.1.116+, os artefatos são servidos por:

https://downloads.claude.ai/claude-code-releases

Se a rede já permitia apenas storage.googleapis.com ou o registro npm, a instalação inicial e o comando claude update podem falhar até a política de saída ser ajustada.

O pacote JavaScript antigo ainda existe para Windows e para cenários que o fixam explicitamente. Nessas instalações, Glob e Grep continuam expostos como ferramentas de primeira classe. Em builds nativos de macOS e Linux, esses recursos são fornecidos por binários embutidos invocados via Bash, com substituição transparente nas regras de permissão.

10.1.4 Comandos principais da CLI

• claude: abre a sessão interativa.
• claude "consulta": abre a REPL já com um prompt inicial.
• claude -p "consulta": executa em modo print e encerra.
• cat arquivo | claude -p "consulta": processa conteúdo vindo por pipe.
• claude -c: continua a conversa mais recente.
• claude -c -p "consulta": continua a sessão mais recente, mas em modo não interativo.
• claude -r "<sessão>" "consulta": retoma uma sessão pelo nome ou ID.
• claude update: atualiza para a versão mais recente.
• /doctor: diagnostica instalação, configuração e plugins.
• claude mcp: configura servidores MCP, incluindo login e logout de autenticação nas versões v2.1.186+.
• claude mcp serve: expõe o Claude Code como servidor MCP.
• claude agents: abre a visão de agentes/sessões em segundo plano.
• claude auto-mode defaults: imprime regras padrão do modo automático em JSON.
• claude remote-control: inicia o servidor de Remote Control.
• claude plugin: gerencia plugins.
• claude plugin init <nome>: cria um novo plugin em .claude/skills e o carrega automaticamente, sem marketplace, desde v2.1.157+.
• claude plugin tag <versão>: cria uma tag de release para plugin com validação de versão.
• claude install [versão]: instala uma versão específica do binário nativo; aceita stable, latest ou uma string de versão explícita.
• claude project purge [path]: apaga o estado local de um projeto.
• claude plugin prune: remove dependências órfãs de plugins instalados automaticamente.
• claude ultrareview [target]: executa /ultrareview sem interface.
• claude auth login: faz login na conta.
• claude auth logout: encerra a sessão autenticada.
• claude auth status: verifica o estado da autenticação.

O comando /doctor evoluiu em duas frentes importantes: desde v2.1.116 ele pode ser aberto enquanto o Claude está respondendo, exibe ícones de status inline e aceita a tecla f para corrigir automaticamente problemas detectados; em v2.1.178 a interface passou a usar uma árvore plana com ícones mais claros e comandos destacados.

10.1.5 Modo interativo versus modo print

Por padrão, claude abre a sessão interativa, também chamada de REPL. Esse modo é ideal para diálogos de várias rodadas, navegação por histórico, autocompletar com Tab e uso de slash commands.

Quando você usa -p ou --print, o Claude responde uma vez e encerra. Esse formato é mais apropriado para scripts, pipes, integrações com outras ferramentas e saídas estruturadas.

# Modo interativo
claude

# Inicia a sessão já com uma pergunta
claude "explique o fluxo de autenticação"

# Modo print
claude -p "o que essa função faz?"

# Processando um arquivo via pipe
cat error.log | claude -p "explique este erro"

# Encadeando com outros comandos
claude -p "liste tarefas pendentes" | grep "URGENTE"

10.1.6 Flags centrais de controle de sessão e execução

• -p, --print: desativa a interação contínua e imprime a resposta.
• -c, --continue: carrega a conversa mais recente.
• -r, --resume: retoma uma sessão específica por ID ou nome.
• -v, --version: mostra a versão instalada.
• -w, --worktree: inicia em um worktree git isolado.
• -n, --name: define o nome de exibição da sessão.
• --from-pr <url-ou-número>: retoma sessões vinculadas a pull requests ou merge requests.
• --remote "tarefa": cria uma sessão web no claude.ai.
• --remote-control / --rc: abre sessão interativa com Remote Control.
• --teleport: traz uma sessão web para o ambiente local.
• --teammate-mode: define o modo de exibição da equipe de agentes, por exemplo tmux.
• --bare: inicia em modo mínimo, ignorando hooks, skills, plugins, MCP, auto memory e CLAUDE.md.
• --safe-mode: desativa todas as personalizações para isolar problemas de configuração.
• --enable-auto-mode: libera o modo de permissões automáticas quando disponível.
• --channels: assina plugins de canais MCP.
• --chrome / --no-chrome: habilita ou desabilita integração com navegador Chrome.
• --effort: ajusta o nível de esforço de raciocínio.
• --init / --init-only: executa hooks de inicialização.
• --maintenance: executa hooks de manutenção e encerra.
• --disable-slash-commands: desativa skills e slash commands.
• --no-session-persistence: evita salvar a sessão no modo print.
• --exclude-dynamic-system-prompt-sections: remove seções dinâmicas do system prompt para melhorar o cache de prompts.

O modo --safe-mode também pode ser acionado pela variável de ambiente CLAUDE_CODE_SAFE_MODE=1, introduzida em v2.1.169. É a opção mais indicada quando você suspeita de conflito entre CLAUDE.md, plugins, skills, hooks ou MCP.

10.1.7 Retomada, forks e limpeza de estado

As sessões podem ser continuadas, retomadas por nome/ID ou até bifurcadas. Isso é útil quando você quer testar uma alternativa sem destruir o contexto principal.

# Continuar a conversa mais recente
claude -c

# Retomar uma sessão nomeada
claude -r "feature-auth" "continue implementando login"

# Retomar e criar uma ramificação experimental
claude --resume feature-auth --fork-session "tente uma abordagem alternativa"

# Usar um ID específico
claude --session-id "550e8400-e29b-41d4-a716-446655440000" "continue"

O fork de sessão cria uma nova sessão independente a partir de uma existente. O fluxo original não é alterado, o que permite experimentar implementações paralelas, testar mudanças quebradiças e comparar abordagens.

Desde v2.1.126+, claude project purge remove todo o estado local de um projeto: transcrições, listas de tarefas, logs de debug, histórico de edições de arquivo, linhas de histórico de prompts e a entrada correspondente em ~/.claude.json. Use primeiro --dry-run para visualizar o que será apagado. Com --all, a operação percorre todos os projetos da máquina.

# Pré-visualizar a limpeza
claude project purge ~/work/repo --dry-run

# Apagar o estado de um projeto sem perguntas
claude project purge ~/work/repo --yes

# Percorrer todos os projetos com confirmação
claude project purge --all --interactive

10.1.8 Modelos e seleção de modelo

O Claude Code trabalha com diferentes modelos, cada um com perfil próprio de velocidade, capacidade e janela de contexto. O modelo pode ser selecionado por nome curto ou ID completo.

• --model: define o modelo principal.
• --fallback-model: define um modelo de contingência quando o principal está sobrecarregado ou indisponível.
• --agent: escolhe um agente para a sessão.
• --agents: injeta agentes personalizados via JSON.
• --effort: define o nível de esforço.

Exemplos práticos:

# Opus para tarefas complexas
claude --model opus "desenhe uma estratégia de cache"

# Haiku para tarefas rápidas
claude --model haiku -p "formate este JSON"

# Nome completo do modelo
claude --model claude-sonnet-4-6-20250929 "revise este código"

# Com fallback de confiabilidade
claude -p --model opus --fallback-model sonnet "analise a arquitetura"

# Modo opusplan: Opus planeja, Sonnet executa
claude --model opusplan "projete e implemente a camada de cache"

Quando você usa um gateway compatível com Anthropic via ANTHROPIC_BASE_URL, a descoberta de modelos pode ser ligada com CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1. Nessa condição, o comando /model passa a consultar o endpoint /v1/models do gateway. Sem essa variável, a interface usa uma lista estática embutida. Essa funcionalidade é opt-in a partir de v2.1.129; houve um período em que ela era implícita, mas esse comportamento foi revertido porque a descoberta poderia expor modelos que o usuário não tem direito de usar.

Quando um administrador da organização define um modelo padrão, o comando /model o exibe como “Org default” ou “Role default” a partir de v2.1.196.

10.1.9 Personalização do system prompt

Há quatro formas principais de alterar o system prompt:

• --system-prompt: substitui completamente o prompt padrão.
• --system-prompt-file: carrega o prompt a partir de um arquivo.
• --append-system-prompt: acrescenta instruções ao prompt padrão.
• --append-subagent-system-prompt: adiciona texto ao prompt de todos os subagentes, em execução não interativa.

# Persona completa personalizada
claude --system-prompt "Você é uma engenheira sênior de segurança. Foque em vulnerabilidades."

# Acrescentar instruções específicas
claude --append-system-prompt "Sempre inclua testes unitários com os exemplos de código"

# Carregar um prompt complexo de arquivo
claude -p --system-prompt-file ./prompts/code-reviewer.txt "revise main.py"

Importante: --system-prompt-file deve ser usado apenas no modo print. Para sessões interativas, a abordagem correta é usar --system-prompt ou --append-system-prompt. O primeiro substitui tudo; o segundo preserva o comportamento padrão e apenas adiciona instruções.

10.1.10 Gerenciamento de ferramentas e permissões

O Claude Code permite controlar quais ferramentas podem ser usadas, quais podem executar sem confirmação e quais devem ser completamente removidas do contexto. Isso é essencial para segurança, reprodutibilidade e automação confiável.

• --tools: restringe o conjunto de ferramentas embutidas disponíveis.
• --allowedTools: define ferramentas que executam sem prompt de permissão.
• --disallowedTools: remove ferramentas do contexto.
• --dangerously-skip-permissions: ignora todos os prompts de permissão.
• --permission-mode: inicia em um modo de permissão específico.
• --permission-prompt-tool: usa uma ferramenta MCP para tratar permissões.
• --enable-auto-mode: libera o modo automático.

Exemplos típicos:

# Modo somente leitura para revisão
claude --permission-mode plan "revise esta base de código"

# Liberar apenas ferramentas seguras
claude --tools "Read,Grep,Glob" -p "encontre todos os comentários TODO"

# Permitir comandos git específicos sem prompt
claude --allowedTools "Bash(git status:*)" "Bash(git log:*)"

# Bloquear operações perigosas
claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)"

As regras de permissão seguem o formato Tool para liberar ou bloquear todas as ocorrências, ou Tool(especificador) quando você quer restringir por comando, caminho ou argumento. A partir de v2.1.178, o especificador também pode casar parâmetros do input da ferramenta usando a forma Tool(param:value), com suporte a curingas. Isso amplia o que já era comum em Bash(...) e Read(...), permitindo escopar outros tools pelos argumentos. Como os nomes de parâmetros variam por ferramenta, consulte sempre a referência atual de permissões antes de escrever uma regra.

Exemplos adicionais de comportamento prático:

• em builds nativos de macOS e Linux, Glob e Grep continuam aparecendo nas regras, mesmo quando internamente são mapeados para binários embutidos;
• em Windows e em instalações JavaScript antigas, esses tools permanecem como ferramentas independentes;
• com PowerShell, o auto-approve funciona igual ao Bash a partir de v2.1.119, inclusive com matchers como PowerShell(Get-ChildItem:*);
• desde v2.1.132+, a flag --permission-mode é respeitada ao retomar sessões com --continue ou --resume; antes disso, o modo podia ser perdido silenciosamente.

10.1.11 Formato de saída e serialização

Quando o foco é automação, o modo print pode emitir texto puro, JSON ou JSON em streaming. Há ainda suporte a schema de validação e a limites de orçamento.

• --output-format: escolhe o formato de saída. Valores: text, json e stream-json.
• --input-format: define como a entrada será interpretada. Valores: text e stream-json.
• --verbose: ativa logs detalhados.
• --include-partial-messages: inclui eventos parciais durante streaming; exige stream-json.
• --json-schema: força uma saída validada contra um schema JSON.
• --max-budget-usd: limita o gasto máximo no modo print.

# Texto simples
claude -p "explique este código"

# JSON para uso programático
claude -p --output-format json "liste todas as funções em main.py"

# JSON em streaming para processamento em tempo real
claude -p --output-format stream-json "gere um relatório longo"

# Saída estruturada com validação de schema
claude -p --json-schema '{"type":"object","properties":{"bugs":{"type":"array"}}}' \
  "encontre bugs neste código e retorne em JSON"

O uso de --json-schema é o caminho mais confiável quando o resultado será consumido por outra automação, porque ele reduz a ambiguidade do texto gerado. Já --include-partial-messages é útil quando você quer reagir aos eventos antes do término completo da resposta, por exemplo para barra de progresso, logs ao vivo ou pipelines com baixa latência.

10.1.12 Diretórios de trabalho e fontes de configuração

É possível ampliar o workspace e controlar de onde vêm as configurações carregadas.

• --add-dir: adiciona diretórios de trabalho extras.
• --setting-sources: define, em lista separada por vírgulas, quais origens de settings devem ser consideradas.
• --settings: carrega configurações de um arquivo ou de um JSON inline.
• --plugin-dir: carrega plugins de um diretório; a flag é repetível.

Desde v2.1.119, alterações feitas interativamente pelo comando /config são persistidas em ~/.claude/settings.json e entram na cadeia normal de precedência: política, local, projeto e usuário. Antes dessa versão, parte das mudanças do /config podia valer apenas para a sessão atual.

# Trabalhar em múltiplos diretórios
claude --add-dir ../frontend ../backend ../shared "encontre todos os endpoints da API"

# Carregar settings personalizados
claude --settings '{"model":"opus","verbose":true}' "tarefa complexa"

10.1.13 Configuração de MCP

Os servidores MCP também podem ser carregados por JSON ou restritos de forma estrita.

• --mcp-config: carrega servidores MCP de um arquivo JSON.
• --strict-mcp-config: usa exclusivamente a configuração fornecida, ignorando outras fontes.
• --channels: assina plugins de canal MCP.

# Carregar MCP do GitHub
claude --mcp-config ./github-mcp.json "liste PRs abertos"

# Modo estrito - apenas servidores especificados
claude --strict-mcp-config --mcp-config ./production-mcp.json "faça deploy para staging"

10.1.14 Gerenciamento de agentes

O parâmetro --agents recebe um objeto JSON que define subagentes personalizados para a sessão. Cada agente precisa de um nome, uma descrição e um prompt; ferramentas e modelo são opcionais.

{
  "agent-name": {
    "description": "Obrigatório: quando invocar este agente",
    "prompt": "Obrigatório: system prompt do agente",
    "tools": ["Opcional", "array", "de", "ferramentas"],
    "model": "opcional: sonnet|opus|haiku"
  }
}

Campos obrigatórios:

• description: explica em linguagem natural quando o agente deve ser usado.
• prompt: define o papel e o comportamento do subagente.

Campos opcionais:

• tools: lista de ferramentas disponíveis; se omitida, o agente herda todas.
• model: escolhe sonnet, opus ou haiku.

{
  "code-reviewer": {
    "description": "Revisor de código especialista. Use proativamente depois de mudanças no código.",
    "prompt": "Você é uma revisora sênior. Foque em qualidade, segurança e boas práticas.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Especialista em debugging para erros e falhas de teste.",
    "prompt": "Você é uma especialista em depuração. Analise erros, identifique a causa raiz e proponha correções.",
    "tools": ["Read", "Edit", "Bash", "Grep"],
    "model": "opus"
  },
  "documenter": {
    "description": "Especialista em documentação para gerar guias.",
    "prompt": "Você é uma redatora técnica. Crie documentação clara e completa.",
    "tools": ["Read", "Write"],
    "model": "haiku"
  }
}

É possível definir agentes inline, carregar de arquivo e combiná-los com outras flags:

# Definir agentes personalizados inline
claude --agents '{
  "security-auditor": {
    "description": "Especialista em segurança para análise de vulnerabilidades",
    "prompt": "Você é um especialista em segurança. Encontre vulnerabilidades e sugira correções.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "opus"
  }
}' "audite esta base de código em busca de problemas de segurança"

# Carregar agentes de um arquivo
claude --agents "$(cat ~/.claude/agents.json)" "revisar o módulo de autenticação"

# Combinar com outros flags
claude -p --agents "$(cat agents.json)" --model sonnet "analise performance"

A precedência de agentes é importante: definições passadas pela CLI com --agents vencem as definições do projeto e do usuário para aquela sessão. Agentes do projeto substituem agentes do usuário quando há colisão de nomes. Existe ainda uma camada de agentes em plugins, descrita na documentação de subagentes, que participa da mesma tabela de prioridade.

10.1.15 Agent View

O comando claude agents, introduzido como Research Preview em v2.1.139+, abre uma visão consolidada de todas as sessões do Claude Code na máquina. Essa tela substitui a necessidade de gerenciar várias abas de terminal quando você trabalha com agentes em segundo plano, tarefas agendadas ou sessões disparadas com --bg.

A lista mostra o estado atual de cada sessão, como running, blocked on you e done. A feature é estável o suficiente para uso diário, mas ainda pode mudar em detalhes de interface e fluxo.

claude agents

Ao despachar uma sessão por essa visão, ou com claude --bg <prompt>, você pode passar as mesmas flags básicas do próprio Claude. A partir do caminho de despacho do Agent View, algumas flags adicionais passaram a ser aceitas:

• --cwd <path> (v2.1.141): limita a lista ou a nova sessão a um diretório de trabalho específico.
• --add-dir <path> (v2.1.142): adiciona diretórios ao workspace da sessão despachada.
• --settings <path> (v2.1.142): usa um settings.json específico.
• --mcp-config <path> (v2.1.142): usa uma configuração MCP específica.
• --plugin-dir <path> (v2.1.142): usa um diretório de plugin específico.
• --permission-mode <mode> (v2.1.142): define o modo de permissão da sessão despachada.
• --model <model> (v2.1.142): fixa um modelo na sessão despachada.
• --effort <level> (v2.1.142): fixa o nível de esforço.
• --dangerously-skip-permissions (v2.1.142): roda a sessão sem prompts de permissão; use apenas em sandboxes.
• --json (v2.1.145): imprime a lista de agentes em JSON para scripts e integrações.

Há um ajuste importante de comportamento: sessões que concluem o trabalho, mas deixam um shell em segundo plano aberto, passaram a migrar de Working para Completed em v2.1.141. Dentro de uma sessão anexada no Agent View, Shift+Tab alterna os modos de permissão, inclusive o modo automático, desde v2.1.143.

Também é possível fixar sessões: no Agent View, pressione Ctrl+T para “pin”. Sessões fixadas permanecem vivas quando o sistema fica ocioso, são reiniciadas no lugar para receber atualizações do Claude Code e só são descartadas por pressão de memória depois das sessões não fixadas. Essa combinação de teclas vale apenas na visão de agentes; na sessão principal, Ctrl+T alterna a visualização da lista de tarefas.

10.1.16 Casos de uso de alto valor: CI/CD

Uma aplicação prática muito forte da CLI é usar Claude Code em pipelines de integração e entrega contínua para revisão automática de código, análise de testes e geração de documentação.

No GitHub Actions, por exemplo, você instala o pacote, injeta a chave da API e roda o Claude em modo print com saída JSON. Depois, um passo adicional pode ler o arquivo gerado e publicar comentários na pull request.

name: AI Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p --output-format json \
            --max-turns 1 \
            "Revise as mudanças deste PR para:
            - Vulnerabilidades de segurança
            - Problemas de performance
            - Qualidade de código
            Retorne em JSON com um array 'issues'" > review.json

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = JSON.parse(fs.readFileSync('review.json', 'utf8'));
            // Processar e publicar comentários de revisão

No Jenkins, o mesmo padrão funciona com um estágio de shell:

pipeline {
    agent any
    stages {
        stage('AI Review') {
            steps {
                sh '''
                    claude -p --output-format json \
                      --max-turns 3 \
                      "Analise a cobertura de testes e sugira testes ausentes" \
                      > coverage-analysis.json
                '''
            }
        }
    }
}

Para gates de PR mais diretos, claude ultrareview é especialmente útil. Ele roda sem interface, imprime os achados e retorna código de saída 0 quando a revisão está limpa e 1 quando há descobertas. Isso o torna adequado para bloquear merge automaticamente. Se necessário, ajuste o tempo máximo com --timeout <minutes>; o padrão é 30 minutos.

# .github/workflows/ultrareview.yml
- name: Claude ultrareview
  run: claude ultrareview ${{ github.event.pull_request.number }} --json > review.json

10.1.17 Casos de uso de alto valor: pipe e processamento de arquivos

O modo print é excelente para processar logs, históricos e arquivos de código. O Claude pode receber qualquer entrada textual via stdin.

# Analisar logs de erro
tail -1000 /var/log/app/error.log | claude -p "resuma estes erros e sugira correções"

# Encontrar padrões em logs de acesso
cat access.log | claude -p "identifique padrões de acesso suspeitos"

# Analisar histórico git
git log --oneline -50 | claude -p "resuma a atividade recente de desenvolvimento"

# Revisar um arquivo específico
cat src/auth.ts | claude -p "revise este código de autenticação em busca de problemas de segurança"

# Gerar documentação
cat src/api/*.ts | claude -p "gere a documentação da API em markdown"

# Encontrar TODOs e priorizar
grep -r "TODO" src/ | claude -p "priorize estes TODOs por importância"

10.1.18 Trabalhos com múltiplas sessões

Projetos grandes normalmente exigem mais de uma linha de conversa. O Claude Code permite alternar entre sessões nomeadas, continuar o trabalho de onde parou e bifurcar uma sessão para explorar outra implementação.

# Iniciar uma sessão para uma feature
claude -r "feature-auth" "vamos implementar autenticação de usuário"

# Continuar depois
claude -r "feature-auth" "adicionar recuperação de senha"

# Criar um fork para testar outra abordagem
claude --resume feature-auth --fork-session "tentar OAuth em vez de senha"

# Alternar entre diferentes frentes de trabalho
claude -r "feature-payments" "continue com a integração Stripe"

Esse padrão é útil quando você quer preservar um contexto bem-sucedido e, ao mesmo tempo, testar ideias alternativas sem risco para a linha principal de trabalho.

10.1.19 Automação segura e consciente de permissões

Quando o Claude vai atuar de forma mais autônoma, o ideal é restringir ferramentas e aprovações. O modo plan é adequado para auditoria e revisão, porque reduz o risco de alterações não intencionais. Já o bloqueio explícito de comandos perigosos protege ambientes compartilhados e pipelines.

# Auditoria somente leitura
claude --permission-mode plan \
  --tools "Read,Grep,Glob" \
  "audite esta base de código em busca de vulnerabilidades"

# Bloquear comandos perigosos
claude --disallowedTools "Bash(rm:*)" "Bash(curl:*)" "Bash(wget:*)" \
  "me ajude a organizar este projeto"

# Automação restrita
claude -p --max-turns 2 \
  --allowedTools "Read" "Glob" \
  "encontre todas as credenciais hardcoded"

O parâmetro --dangerously-skip-permissions existe para cenários automatizados muito controlados, como sandboxes descartáveis. Ele não deve ser usado como padrão, porque remove a última camada de proteção antes de ações reais no sistema.

10.1.20 Integração JSON e consumo por jq

Quando o Claude é tratado como uma API programável, o modo JSON simplifica bastante a integração com ferramentas de shell. O padrão recomendado é combinar --output-format json com schema opcional, armazenar a saída e então processá-la com jq.

# Análise estruturada
claude -p --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array"},"complexity":{"type":"string"}}}' \
  "analise main.py e retorne a lista de funções com nível de complexidade"

# Consumir com jq
claude -p --output-format json "liste todos os endpoints da API" | jq '.endpoints[]'

# Usar em scripts
RESULT=$(claude -p --output-format json "este código é seguro? responda com {secure: boolean, issues: []}" < code.py)
if echo "$RESULT" | jq -e '.secure == false' > /dev/null; then
  echo "Problemas de segurança encontrados!"
  echo "$RESULT" | jq '.issues[]'
fi

Alguns padrões úteis com jq:

# Extrair um campo
claude -p --output-format json "analise este código" | jq '.result'

# Filtrar itens com severidade alta
claude -p --output-format json "liste problemas" | jq -r '.issues[] | select(.severity=="high")'

# Extrair vários campos
claude -p --output-format json "descreva o projeto" | jq -r '.{name, version, description}'

# Converter para CSV
claude -p --output-format json "liste funções" | jq -r '.functions[] | [.name, .lineCount] | @csv'

# Processamento condicional
claude -p --output-format json "verifique segurança" | jq 'if .vulnerabilities | length > 0 then "UNSAFE" else "SAFE" end'

# Ler valor aninhado
claude -p --output-format json "analise performance" | jq '.metrics.cpu.usage'

# Contar array
claude -p --output-format json "encontre todos os TODOs" | jq '.todos | length'

# Transformar saída inteira
claude -p --output-format json "liste melhorias" | jq 'map({title: .title, priority: .priority})'

10.1.21 Modelos disponíveis

O Claude Code suporta vários modelos, cada um com janela de contexto e perfil de uso diferentes. Alguns são mais rápidos, outros mais capazes, e há também variantes específicas para planejamento e execução.

• Sonnet 5 (claude-sonnet-5): janela de 1M tokens; padrão em seats Pro, Team Standard e Enterprise desde v2.1.197. O Opus 4.8 continua como padrão em Max, Team Premium, Enterprise pay-as-you-go e na API Claude.
• Opus 4.8 (claude-opus-4-8): janela de 1M tokens; o mais capaz; níveis adaptativos de esforço de low até max; esforço padrão high desde v2.1.154.
• Sonnet 4.6 (claude-sonnet-4-6): janela de 1M tokens; equilíbrio entre velocidade e capacidade; o esforço padrão para assinantes Pro/Max foi elevado de medium para high em v2.1.117.
• Haiku 4.5 (claude-haiku-4-5): janela de 200K tokens; o mais rápido para tarefas curtas; não suporta níveis de esforço.
• Fable 5 (claude-fable-5): modelo de classe Mythos, preparado para uso geral desde v2.1.170.

Seleção por nome curto e alias de planejamento:

# Nomes curtos
claude --model opus "revisão arquitetural complexa"
claude --model sonnet "implemente esta feature"
claude --model haiku -p "formate este JSON"

# Alias opusplan
claude --model opusplan "desenhe e implemente a API"

# Alternar para fast mode durante a sessão
/fast

O modo /fast passou a rodar em Opus 4.8 por padrão a partir de v2.1.154, como preview de pesquisa. Isso representa cerca de 2x da taxa padrão para aproximadamente 2,5x da velocidade de saída. Antes disso, a base do fast mode mudou de Opus 4.6 para Opus 4.7 em v2.1.142. A variável CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE ficou obsoleta em v2.1.154 e foi removida em 2026-06-01. Se você realmente precisar de fast mode sobre Opus 4.6, primeiro selecione o modelo com /model claude-opus-4-6[1m] e depois ligue /fast on.

10.1.22 Níveis de esforço

Os modelos Opus 4.8 e Opus 4.7 usam raciocínio adaptativo com níveis ordenados do mais leve ao mais pesado: low, medium, high, xhigh e max. O padrão é high no Opus 4.8, no Opus 4.6 e no Sonnet 4.6; no Opus 4.7 o padrão é xhigh. O nível xhigh existe em Opus 4.8 e 4.7; max funciona em Opus 4.8/4.7/4.6 e Sonnet 4.6, mas apenas na sessão. O Haiku 4.5 não possui níveis de esforço.

# Definir esforço pela flag
claude --effort high "revisão complexa"

# Definir esforço por slash command
/effort high

# Definir por variável de ambiente
export CLAUDE_CODE_EFFORT_LEVEL=high   # low, medium, high, xhigh (Opus 4.8/4.7) ou max

A palavra-chave ultrathink dentro do prompt ativa raciocínio profundo. Já a opção ultracode no menu /effort não é um nível de esforço de modelo; ela envia xhigh e faz o Claude orquestrar fluxos dinâmicos de trabalho, sempre em contexto de sessão.

10.1.23 Variáveis de ambiente importantes

Além das flags, muitas configurações podem ser controladas por ambiente. Algumas são simples substituições de modelo ou esforço; outras desativam recursos, alteram comportamento de execução ou melhoram observabilidade.

• ANTHROPIC_API_KEY: chave de API para autenticação.
• ANTHROPIC_MODEL: substitui o modelo padrão.
• ANTHROPIC_CUSTOM_MODEL_OPTION: opção de modelo customizada para a API.
• ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL: sobrescrevem o ID padrão de cada família.
• MAX_THINKING_TOKENS: define orçamento estendido para pensamento.
• CLAUDE_CODE_EFFORT_LEVEL: define o nível de esforço.
• CLAUDE_CODE_SIMPLE: modo mínimo equivalente a --bare.
• CLAUDE_CODE_SAFE_MODE: desativa todas as customizações, equivalente a --safe-mode.
• CLAUDE_CODE_DISABLE_BUNDLED_SKILLS: oculta skills, workflows e comandos embarcados.
• CLAUDE_CODE_DISABLE_AUTO_MEMORY: desliga atualizações automáticas de CLAUDE.md.
• CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: desativa tarefas em segundo plano.
• CLAUDE_CODE_DISABLE_CRON: desativa tarefas agendadas/cron.
• CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS: remove instruções relacionadas a git.
• CLAUDE_CODE_DISABLE_TERMINAL_TITLE: impede atualização do título do terminal.
• CLAUDE_CODE_DISABLE_1M_CONTEXT: desativa a janela de 1M tokens.
• CLAUDE_CODE_DISABLE_MOUSE_CLICKS: bloqueia cliques, arrastar e hover na tela cheia; scroll da roda continua funcionando.
• CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK: desativa fallback não-streaming.
• CLAUDE_CODE_ENABLE_TASKS: habilita a lista de tarefas.
• CLAUDE_CODE_TASK_LIST_ID: define um diretório nomeado de tarefas compartilhado entre sessões.
• CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION: liga ou desliga sugestões de prompt.
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: ativa equipes de agentes experimentais.
• CLAUDE_CODE_NEW_INIT: usa o novo fluxo de inicialização.
• CLAUDE_CODE_SUBAGENT_MODEL: modelo usado por subagentes.
• CLAUDE_CODE_PLUGIN_SEED_DIR: diretório de seeds de plugin.
• CLAUDE_CODE_SUBPROCESS_ENV_SCRUB: variáveis a serem removidas dos subprocessos.
• CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: substitui o percentual de auto-compaction.
• CLAUDE_STREAM_IDLE_TIMEOUT_MS: timeout de inatividade do stream em milissegundos.
• SLASH_COMMAND_TOOL_CHAR_BUDGET: orçamento de caracteres para ferramentas de slash command.
• ENABLE_TOOL_SEARCH: habilita busca de ferramentas.
• MAX_MCP_OUTPUT_TOKENS: número máximo de tokens para saída de ferramentas MCP.
• CLAUDE_CODE_PERFORCE_MODE: ativa modo Perforce, tratando arquivos como somente leitura por padrão.
• DISABLE_UPDATES: bloqueia todos os caminhos de atualização, inclusive claude update.
• CLAUDE_CODE_HIDE_CWD: oculta o diretório atual no logo inicial.
• CLAUDE_CODE_FORK_SUBAGENT: habilita subagentes forkados em builds externos como Bedrock, Vertex e Foundry.
• CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN: opta por não usar o renderer fullscreen de tela alternada.
• CLAUDE_CODE_SESSION_ID: preenchido automaticamente em subprocessos Bash para correlacionar logs e telemetria.
• CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL: reabilita a pesquisa de qualidade de sessão em ambientes com OpenTelemetry.
• OTEL_LOG_TOOL_DETAILS: remove a redaction de nomes de comandos customizados e MCP em eventos OTEL.
• ANTHROPIC_BEDROCK_SERVICE_TIER: seleciona a camada de serviço do Bedrock.
• AI_AGENT: marcado automaticamente em subprocessos para que CLIs externas atribuam o tráfego ao Claude Code.
• CLAUDE_CODE_FORCE_SYNC_OUTPUT: força saída síncrona em terminais onde a detecção automática falha.
• CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE: habilita upgrades em background para instalações via Homebrew/WinGet.
• CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: opta por descobrir modelos via gateway quando ANTHROPIC_BASE_URL estiver definido.
• CLAUDE_CODE_ENABLE_AUTO_MODE: opta por modo automático em Bedrock, Vertex e Foundry para Opus 4.7/4.8.
• CLAUDE_CLIENT_PRESENCE_FILE: suprime notificações push móveis enquanto você está na máquina.
• CLAUDE_CODE_MAX_RETRIES: número máximo de tentativas de retry da API, limitado a 15 desde v2.1.186.
• CLAUDE_CODE_RETRY_WATCHDOG: recomendado para sessões não assistidas como alternativa a aumentar o número máximo de retries.
• CLAUDE_ENABLE_STREAM_WATCHDOG: watchdog de inatividade do streaming, ativado por padrão, com possibilidade de desativação.
• CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT: ajusta o timeout de 5 minutos para chamadas remotas de ferramentas MCP que travam sem resposta.
• CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE: removida e sem efeito; antes travava o fast mode no Opus 4.6.

Há um detalhe específico para Vertex AI: ENABLE_TOOL_SEARCH vem desabilitado por padrão em implantações do Google Cloud Vertex. Quem quiser usar busca de ferramentas no Vertex precisa ativar explicitamente export ENABLE_TOOL_SEARCH=true. Na API Anthropic direta, o recurso continua habilitado por padrão.

10.1.24 Chaves de settings.json

Algumas configurações vivem em settings.json, não em flags nem em variáveis de ambiente. Isso vale tanto para ~/.claude/settings.json no escopo do usuário quanto para .claude/settings.json no escopo do projeto.

• respondToBashCommands (v2.1.186): responde automaticamente à saída de comandos Bash iniciados com !. O padrão é true; defina false para o comportamento antigo, apenas contextual.
• wheelScrollAccelerationEnabled (v2.1.174): desativa a aceleração da roda do mouse no renderer fullscreen.
• footerLinksRegexes (v2.1.176): lista de regexes cujos links aparecem como badges no rodapé.
• language: define a língua preferida de resposta e também a língua da ditado por voz; desde v2.1.176, fixa a língua dos títulos automáticos de sessão.

{
  "wheelScrollAccelerationEnabled": false,
  "language": "french",
  "footerLinksRegexes": ["https://jira\\.example\\.com/.*"]
}

10.1.25 Referência rápida

Os comandos mais usados no dia a dia combinam sessão interativa, modo print, retomada, leitura de arquivos e saída JSON:

# Sessão interativa
claude

# Pergunta rápida
claude -p "como eu..."

# Continuar conversa
claude -c

# Processar um arquivo
cat file.py | claude -p "revise isto"

# Saída JSON para scripts
claude -p --output-format json "consulta"

Combinações úteis:

• revisão rápida: cat file | claude -p "review"
• saída estruturada: claude -p --output-format json "query"
• exploração segura: claude --permission-mode plan
• autonomia com segurança: claude --enable-auto-mode --permission-mode auto
• integração com CI/CD: claude -p --max-turns 3 --output-format json
• retomar trabalho: claude -r "session-name"
• modelo customizado: claude --model opus "tarefa complexa"
• modo mínimo: claude --bare "consulta rápida"
• execução com orçamento: claude -p --max-budget-usd 2.00 "analise o código"

10.1.26 Troubleshooting

Quando a CLI não funciona como esperado, vale isolar a falha por categoria: instalação, autenticação, sessão, saída ou permissões.

• Comando não encontrado: se claude: command not found aparecer, reinstale com npm install -g @anthropic-ai/claude-code, confira se o diretório global do npm está no PATH e, em último caso, teste com npx claude.
• Problema de API key: erros de autenticação normalmente exigem definir ANTHROPIC_API_KEY, validar se a chave é válida, se há créditos suficientes e se ela tem permissão para o modelo solicitado.
• Sessão não encontrada: para retomar uma conversa, liste sessões disponíveis, verifique se o nome/ID está correto e lembre que sessões podem expirar por inatividade. Se quiser apenas a última conversa, use -c.
• Saída JSON inválida: prefira --output-format json, acrescente instruções explícitas no prompt e, quando necessário, aplique --json-schema para forçar estrutura.
• Permissão negada: revise --permission-mode, --allowedTools e --disallowedTools; em automação controlada, --dangerously-skip-permissions pode ser usado com extrema cautela.

Em ambientes com problemas de proxy, o sintoma mais comum é falha na atualização ou na instalação inicial após a mudança de host de download. Nesse caso, o ajuste da allowlist para downloads.claude.ai costuma resolver.

Se a sessão parecer “presa” em espera de ferramentas remotas ou MCP, considere ajustar CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT e verificar se o servidor remoto responde antes do corte de 5 minutos. Em contextos de pipeline, também ajuda habilitar --verbose para enxergar melhor os passos intermediários.

10.2 Recursos adicionais e referências de apoio

Quando você já está trabalhando com a CLI do Claude em modo de terminal, em automações e em fluxos mais avançados de execução, estes materiais complementares ajudam a fechar lacunas importantes. Eles não substituem a prática, mas servem como referência para recursos específicos, comportamento de execução e integração com o ecossistema da ferramenta.

• Referência oficial da CLI — catálogo completo de comandos, flags e sintaxe de uso. É o ponto mais confiável para validar opções suportadas pela versão instalada e entender diferenças entre releases.

• Documentação de headless mode — descreve a execução automatizada sem interface interativa, útil para scripts, pipelines e tarefas agendadas.

• Slash commands — atalhos personalizados dentro do Claude, usados para padronizar tarefas repetitivas e acelerar fluxos de trabalho guiados por comando.

• Memory guide — explica o uso de CLAUDE.md para persistir contexto entre sessões e manter instruções recorrentes do projeto.

• MCP protocol — integração com ferramentas externas por meio do Model Context Protocol, importante quando o Claude precisa conversar com sistemas, serviços ou dados fora do ambiente local.

• Advanced features — cobre recursos como planning mode e extended thinking, que alteram a forma de raciocínio e decomposição de tarefas em cenários mais complexos.

• Subagents guide — descreve a execução delegada de tarefas, útil quando você quer dividir trabalho em partes, isolar responsabilidades ou paralelizar raciocínio em um fluxo controlado.

10.3 Como posicionar esses recursos em um fluxo profissional

Na prática, a CLI completa fica mais poderosa quando você combina esses tópicos de forma intencional:

• use a CLI reference para confirmar comandos e flags antes de automatizar;

• aplique headless mode em CI/CD, scripts e jobs sem operador humano;

• crie slash commands para tarefas internas repetidas, como revisões, scaffolding ou checagens de padrão;

• mantenha contexto em CLAUDE.md para reduzir repetição de instruções em cada sessão;

• adicione MCP quando houver dependência de sistemas externos, como bancos, APIs internas, geradores ou ferramentas de build;

• use advanced features quando a tarefa exigir planejamento explícito, raciocínio prolongado ou quebra em etapas;

• empregue subagents quando a execução precisar ser separada por função, escopo ou fase.

10.4 Detalhes de versão, estabilidade e compatibilidade

Este conjunto de referências está ancorado na versão Claude Code 2.1.206, com atualização registrada em 11 de julho de 2026. Isso importa porque a CLI e os modos avançados evoluem rapidamente, e alguns comportamentos podem ter mudado em versões anteriores ou posteriores.

Os modelos compatíveis listados para este conjunto são:

• Claude Sonnet 5

• Claude Sonnet 4.6

• Claude Opus 4.8

• Claude Haiku 4.5

Na prática, isso significa que você deve verificar o casamento entre versão da CLI, modelo selecionado e recurso desejado. Nem toda função avançada estará disponível em qualquer combinação de plano, versão ou modelo.

10.5 Fontes usadas como base técnica

Os tópicos acima se apoiam em documentação oficial, changelog e páginas específicas de produto. Isso inclui a referência da CLI, variáveis de ambiente, configurações, troubleshooting, comandos slash, modelo, plugins, visão geral do produto e notas de release. Em ambientes profissionais, esse conjunto é essencial para validar comportamento e diagnosticar divergências entre o que foi documentado e o que está acontecendo localmente.

10.6 Como usar a documentação para resolver problemas reais

Se algo não funcionar como esperado, a sequência mais eficiente costuma ser esta:

1. confirmar a sintaxe na referência oficial da CLI;

2. verificar se a execução está em modo interativo ou headless;

3. comparar a versão instalada com a versão citada na documentação;

4. checar se há dependência de modelo compatível;

5. investigar se há configuração local, CLAUDE.md, variáveis de ambiente ou integrações MCP interferindo no resultado;

6. consultar o troubleshooting oficial quando houver erro de autenticação, permissões, execução automatizada ou comportamento inesperado do terminal.

10.7 Exemplo de organização prática de consulta

Em um projeto real, você pode adotar esta ordem de consulta para evitar retrabalho:

1. CLI Reference
2. Headless Mode
3. Slash Commands
4. Memory Guide
5. MCP Protocol
6. Advanced Features
7. Subagents Guide
8. Troubleshooting
9. Changelog

Essa sequência funciona bem porque começa pelo contrato de uso, passa pelo modo de execução e depois avança para recursos de automação, contexto persistente, integração externa e capacidades mais sofisticadas.

10.8 Observação sobre recursos recentes e dependentes de evolução

Como o ecossistema do Claude Code muda com frequência, é importante tratar alguns itens como recentes ou dependentes de versão, especialmente os relacionados a modos avançados, compatibilidade com modelos e integrações novas. Antes de adotar em produção, valide se o comportamento observado corresponde ao que a sua versão suporta hoje, e não apenas ao que foi descrito em releases anteriores.

10.9 Conclusão

O caminho profissional começa com contexto confiável e permissões mínimas, avança para capacidades reutilizáveis e só então adiciona paralelismo e integrações externas. Use cada recurso para o problema que ele resolve, valide resultados com ferramentas determinísticas e mantenha aprovação humana nas ações externas ou destrutivas.

10.10 Referências

• Claude How To
• Documentação oficial do Claude Code
• Model Context Protocol