Mods do Claude Code no time: o que combinar antes de todo mundo instalar?

Se cada dev do time instala os próprios mods, vocês passam a revisar código gerado por agentes que se comportam de jeitos diferentes

E aí o code review vira adivinhação haha

Fala aí, beleza? A Anthropic lançou no início de outubro de 2026 os mods do Claude Code, com o anúncio Customize Claude Code with mods in TypeScript no blog oficial e divulgação pelo perfil ClaudeDevs no X

E tem um detalhe que muda tudo: a partir da v2.1.287 os mods vêm ativos por padrão

Ou seja, a conversa no time precisa acontecer ANTES de todo mundo sair instalando, não depois 🙂

O que são os mods do Claude Code e por que mexem na revisão de código?

Segundo a documentação oficial de mods, um mod é uma função pequena em TypeScript que muda o funcionamento do Claude Code

Pode reescrever um prompt, adicionar UI, substituir um recurso nativo ou criar uma funcionalidade nova

E dá pra escrever o mod na mão ou pedir pro próprio Claude Code escrever pra você

O que um mod consegue fazer no comportamento do agente?

Aqui é onde a coisa fica séria, se liga na lista:

• Reescrever o prompt antes de chegar ao modelo
• Bloquear ou reescrever uma chamada de ferramenta
• Aprovar ou negar pedidos de permissão
• Remover segredos da saída de ferramentas antes do Claude ler
• Editar ou substituir partes da interface (o resultado de uma ferramenta, por exemplo)
• Adicionar botões e campos

Os exemplos que a própria Anthropic citou dão uma ideia do potencial: o token weather (um medidor de contexto), o blast radius (prévia de exclusões) e o replay theater (replay passo a passo das edições)

Muito massa, né? 😀

Tá, e o que isso tem a ver com code review?

Tudo!

Pensa assim: se um mod reescreve o prompt ou aprova permissão na máquina de um dev e não na de outro, o diff que chega no PR nasceu de agentes diferentes

É como dois devs usando o mesmo linter com regras totalmente diferentes, só que agora o "linter" mexe no que o agente pensa e no que ele pode fazer

Quem revisa não tem como saber de onde veio aquele comportamento estranho…

Mods rodam em sandbox?

Não, e esse é o ponto mais importante do post

O mod roda com as mesmas permissões do usuário e do Claude Code: lê e grava arquivos, inicia processos e faz requisições de rede

Por isso a Anthropic orienta instalar só de autores e marketplaces confiáveis

Tome cuidado! Antes de botar qualquer coisa no projeto, vale avaliar um sistema para Claude Code com calma, porque um mod mal feito tem acesso aos mesmos rm -rf da vida que você tem

Quem escolhe os mods do projeto: o acordo de governança

Essa parte é decisão de gente, não de ferramenta

O time precisa definir um responsável por aprovar mods ou, melhor ainda, um processo: mod novo no projeto só entra via PR, com revisão de alguém

O porquê é técnico: como o mod roda com as permissões do usuário, adicionar um mod é parecido com adicionar uma dependência que roda direto na máquina de todo mundo

E se o mod veio de alguma lista da comunidade, o mesmo cuidado de avaliar um recurso do awesome-claude-code vale aqui

Quais recursos o admin tem nos planos Team e Enterprise?

Nos planos Team e Enterprise, e em qualquer máquina com managed settings, o mod nativo sec-default carrega primeiro

Ele impede que os mods instalados pelo usuário façam coisas arriscadas, como sobrescrever regras de deny de permissão

Se o time quiser ir além, existem duas opções nas configurações:

• allowManagedModsOnly: nas managed settings, impede que os mods trazidos pelos usuários carreguem
• strictKnownMarketplaces: true: limita ao marketplace oficial da Anthropic

O allowManagedModsOnly fica dentro de pluginConfigs, na entrada do mod nativo:

{
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": {
        "allowManagedModsOnly": true
      }
    }
  }
}

Nenhuma das duas é obrigatória

São opções pro time discutir: quanto mais travado, mais previsível o agente fica, e menos liberdade cada dev tem pra experimentar

O que entra no repositório e o que fica na máquina de cada dev?

Todo mod vive dentro de um plugin e é instalado como plugin

E a instalação tem três escopos:

Pra que serve o .claude/settings.json?

O .claude/settings.json é a configuração compartilhada do projeto, versionada no git

Quem clona e confia na pasta recebe as mesmas permissões, hooks e marketplace

Dentro dele, duas chaves importam pros mods:

• extraKnownMarketplaces: onde vai o marketplace
• enabledPlugins: onde vai cada plugin, no formato plugin@marketplace

É esse arquivo que vira a "lista oficial" de mods do time

Qual configuração ganha quando duas brigam?

A ordem de precedência, da mais forte pra mais fraca, é:

1. Managed settings
2. Argumentos de linha de comando
3. .claude/settings.local.json (pessoal, do projeto)
4. .claude/settings.json (compartilhado)
5. ~/.claude/settings.json (usuário)

Repara que o .claude/settings.local.json fica ACIMA do compartilhado

Traduzindo: um ajuste local de um dev pode sobrepor o que o time combinou

Então vale o acordo explícito sobre o que é aceitável deixar no local e o que precisa estar no compartilhado

E aproveita pra conferir o .gitignore do projeto, pra ter certeza de que o arquivo local de ninguém vai parar no repositório sem querer

Commitar o settings.json não instala o mod no colega

Essa é a armadilha clássica

Tu commita o .claude/settings.json com o plugin em enabledPlugins, abre o PR, merge feito… e o colega continua sem o mod

Isso acontece porque a entrada versionada não baixa o plugin na máquina de ninguém

Como cada colaborador instala o mod do projeto?

1. Atualize o repositório e confira se o plugin aparece no .claude/settings.json

2. Rode uma vez, no projeto, o comando de instalação com escopo de projeto:

claude plugin install <nome>@<marketplace> --scope project

O erro comum deste passo: achar que o merge resolveu e pular a instalação, aí o dev roda o agente sem o mod e ninguém percebe

3. Confira no /plugin se o mod apareceu entre os instalados

O formato é sempre nome-do-plugin@nome-do-marketplace, tanto no comando quanto pelo /plugin

Dica: bota esse comando no README ou no checklist de onboarding do projeto, assim quem chega no time já sai com o agente igual ao de todo mundo 🙂

Como fixar versão e avisar o time de uma mudança no mod?

Aqui mora boa parte da previsibilidade

O usuário só recebe uma cópia nova do plugin quando a versão calculada muda

Essa versão vem primeiro do plugin.json e, depois, da entrada do marketplace

E se o plugin não tem o campo version? Aí o usuário acompanha os commits, ou seja, qualquer commit novo pode mudar o comportamento do agente

Outro detalhe: o auto-update em segundo plano vem desligado por padrão pro marketplace

Como fixar o plugin num commit exato?

No marketplace.json, a origem do plugin aceita ref (branch ou tag) e sha

Com os dois definidos, o Claude Code instala exatamente o commit do sha

Já a origem do marketplace aceita só ref, então quem quer travar de verdade trava no plugin

Qual acordo faz sentido pro time?

Uma sugestão simples:

• Mudança de mod só entra por PR
• O PR traz o bump de version ou do sha
• Depois do merge, alguém avisa no canal do time que o comportamento do agente mudou

Assim, quando um PR esquisito aparecer, dá pra olhar a data e saber se foi antes ou depois da mudança do mod

Ordem de execução: dois mods no mesmo evento

Cada mod tem um tier: prepend, user, append ou builtin

Quando dois mods atuam no mesmo evento, eles rodam na ordem de carregamento

E se liga nisso: o primeiro a carregar vê o evento primeiro e recebe o resultado por último

É parecido com um middleware em camadas, cada um embrulha o próximo

O que isso significa pro time?

Um mod pessoal pode alterar o que o mod do projeto recebe

Exemplo: o mod do time reescreve o prompt de um jeito, mas um mod pessoal mexe no mesmo prompt antes ou depois dele

Então vale combinar quais mods podem atuar nos mesmos eventos (prompt, chamada de ferramenta, permissão) e quais ficam fora disso

O agente do colega fez algo diferente: como investigar?

Sintoma:

Chega um PR com comportamento inesperado do agente, ou alguém solta o famoso "no meu funciona" xD

Causa provável:

• Conjunto de mods diferente entre as máquinas
• Versão diferente do mesmo plugin
• Algum ajuste no .claude/settings.local.json sobrepondo o compartilhado

Solução, passo a passo:

1. Rode /plugin na sessão e confira os mods carregados: os instalados ficam na aba Installed e os nativos em Built-in

O erro comum deste passo: comparar só a aba Installed e esquecer que os nativos também estão rodando

2. Se desconfiar de um mod específico, desative o plugin dele pelo /plugin e repita a tarefa

3. Pra rodar uma sessão inteira sem os mods instalados, use:

claude --safe-mode

4. Se quiser desligar em todas as sessões, adicione no ~/.claude/settings.json:

{
  "disableAllHooks": true
}

Caso o comportamento continue: lembre que nos três casos os mods nativos seguem rodando, então o problema pode estar em outro lugar

Como prevenir:

• Versão ou sha fixado no plugin
• Lista de mods do projeto versionada no .claude/settings.json
• Aviso no canal do time a cada mudança

Conclusão: checklist para levar à próxima reunião do time

Os mods do Claude Code são uma ferramenta absurda pra customizar o agente, mas num time eles só ajudam se todo mundo estiver rodando o mesmo conjunto

Leva essa lista pra reunião:

• Quem aprova mods novos (pessoa ou processo de PR)
• Quais marketplaces o time aceita
• Quais plugins entram em enabledPlugins
• O que pode e o que não pode ficar no escopo local
• Versão ou sha fixado pra cada plugin
• Comando de instalação no README ou no onboarding
• Como anunciar mudança de mod
• Como investigar quando o agente de alguém se comporta diferente

O próximo passo é bem prático: abrir um PR adicionando o .claude/settings.json com a lista que vocês combinaram

Bora? 😀

Até o próximo post!