Claude Code /doctor prompt-audit: como auditar o CLAUDE.md e as skills em busca de instruções desatualizadas, e o que ele encontrou nas nossas

O /doctor prompt-audit do Claude Code é um comando que faz o Claude ler seus arquivos de instruções (CLAUDE.md, AGENTS.md, skills, comandos etc.), procurar instruções que ficaram desatualizadas ou que se contradizem e propor correções. Tudo o que você recebe é um relatório e diffs sugeridos: nenhum caractere dos seus arquivos muda até você pedir ao Claude que aplique algo. Digitar /checkup prompt-audit executa exatamente a mesma auditoria.

Este artigo explica o que a auditoria de prompts verifica, como executá-la e o que fazer com os resultados, com base no texto original da documentação oficial do Claude Code (a seção "Audit your instruction files" de How Claude remembers your project, além de Commands e Skills), no CHANGELOG e no guia de auditoria que vem embutido no Claude Code. Tudo o que diz respeito à especificação foi conferido nesses originais em 3 de outubro de 2026. As seções 7 e 8 também mostram o que aconteceu quando a rodamos nos arquivos de instruções deste site (9 apontamentos, 7 aplicados) e os cuidados que descobrimos no caminho.

1. O que é o /doctor prompt-audit? Uma auditoria de instruções desatualizadas e conflitantes

O Claude Code carrega o CLAUDE.md e seus outros arquivos de instruções toda vez que inicia. Esses arquivos crescem com o uso e vão acumulando textos enfáticos demais escritos para modelos antigos, nomes de arquivos e comandos que já não existem e regras que contradizem outro arquivo. O /doctor prompt-audit é o comando que coloca o Claude para procurar exatamente isso.

Resumindo a documentação oficial:

• O que procura: instruções escritas para modelos antigos, referências a arquivos ou comandos que não existem e arquivos que se contradizem.
• O que devolve: um relatório dos problemas encontrados e correções sugeridas em forma de diffs. Nada nos seus arquivos muda até você pedir ao Claude que as aplique.
• Como funciona: por meio da skill /claude-api que vem embutida no Claude Code. Se você desligou essa skill nas configurações (desativando-a com skillOverrides ou ativando disableBundledSkills), a auditoria não fica disponível.
• Versão: Claude Code v2.1.283 ou posterior. /checkup prompt-audit é o mesmo comando.

A entrada da v2.1.283 no CHANGELOG adiciona o /doctor prompt-audit (e o /checkup prompt-audit) para auditar CLAUDE.md, skills, agentes e comandos em busca de padrões de prompting escritos para modelos antigos. Na mesma versão, a auditoria também passou a colocar no topo do relatório os caminhos desatualizados, os comandos desatualizados e os arquivos de instruções conflitantes, e a manter as palavras-chave de profundidade de raciocínio, como "think", que o Claude Code suporta oficialmente.

Por que instruções desatualizadas importam? O guia de auditoria embutido explica assim: os modelos atuais seguem as instruções com mais rigor e mais ao pé da letra do que os anteriores. A ênfase empilhada de "CRITICAL" e "MUST", acrescentada para que os modelos antigos não deixassem passar uma regra, agora pesa demais: a regra é aplicada onde não é necessária e o modelo fica engessado. O guia deixa claro que o objetivo não é encurtar as instruções, e sim encontrar as instruções que já não combinam com o modelo atual, com o projeto atual ou com suas outras instruções.

2. Como usar: basta digitar, e o escopo se restringe com um caminho

Dentro de uma sessão do Claude Code, basta digitar:

/doctor prompt-audit

Sem argumento, segundo a documentação oficial, ele audita estes arquivos:

Para auditar só um arquivo ou uma pasta, passe um caminho. O exemplo da documentação oficial:

/doctor prompt-audit .claude/skills/deploy

Segundo o guia embutido, a auditoria foi feita para ir até o fim sem parar para fazer perguntas. Ela deduz o escopo e o modelo de referência a partir do seu pedido e dos próprios arquivos, e registra essas premissas no início do relatório. Se alguma premissa estiver errada, rode de novo com um caminho mais restrito. Para arquivos de instruções, a referência costuma ser o modelo que está executando a auditoria (ou, se uma skill ou um subagente fixa o próprio modelo, esse modelo).

O guia também diz que a auditoria não lê os arquivos de configuração do Claude Code (.claude/settings*.json) nem a configuração de MCP (.mcp.json), porque eles podem conter segredos. Problemas de permissões ou de hooks ficam fora desta auditoria; isso é tarefa do /doctor simples (veja a seção 6).

3. O que a auditoria considera "desatualizado"

O que a auditoria verifica está escrito no guia embutido no Claude Code (as instruções de prompt-audit dentro da skill /claude-api). Ao lermos os arquivos embutidos na v2.1.286, vimos que as verificações se dividem em quatro grupos. Para arquivos de instruções, os dois primeiros fazem quase todo o trabalho.

Dentro do grupo 2, os "caminhos e comandos que não existem" recebem um tratamento especialmente rigoroso no guia. Ele verifica se cada caminho dos seus arquivos de instruções existe de fato no projeto e se os comandos e as flags estão definidos nos seus scripts ou na sua configuração, lendo arquivos em vez de executar comandos. Tudo o que contradiz o que realmente existe no projeto vira um apontamento de confiança alta.

Quando dois arquivos entram em conflito, a auditoria usa o git blame (o registro de quem escreveu cada linha e quando) para decidir qual é o mais recente, e propõe alinhar o mais antigo. Mas, se um dos lados for uma proibição ou regra de segurança que a correção afrouxaria, ou se o histórico não permitir saber qual é o mais recente, o guia manda não propor correção e apenas relatar o caso como uma decisão do usuário.

4. O que ela não apaga: não é uma auditoria para "encurtar"

O que mais gostamos nesta auditoria é que o guia explica com todas as letras o que não deve ser apagado. Ele alerta que uma auditoria que corta tudo penaliza justamente quem escreveu instruções com cuidado, e diz que o seguinte deve ficar mesmo que o texto coincida com algum padrão:

• Contexto que só o autor conhece: fatos sobre o público, o produto e o ambiente, padrões de qualidade, restrições e os motivos por trás deles. O guia afirma sem rodeios que contexto nunca é desperdício.
• O tamanho em si: nada é cortado só por ser longo. O que causa dano são instruções desatualizadas, não o volume.
• Passos exatos para operações delicadas: trabalhos que têm só um procedimento seguro, como comandos de exclusão ou fluxos de autenticação, podem continuar totalmente especificados.
• Proibições contra falhas que ainda acontecem: se a falha ainda se reproduz com os modelos atuais, a regra fica.
• Duplicação que funciona: o mesmo conteúdo em dois lugares é questão de gosto na organização, não algo a auditar, desde que as cópias não se contradigam.

Ela também funciona no sentido contrário. Se os modelos atuais se beneficiariam de uma instrução a mais, ela sugere isso. E diz que, quando nada aparece, não mudar nada é o resultado correto.

5. Como ler os resultados: o relatório e os diffs sugeridos

Você recebe duas coisas: um relatório de auditoria e correções sugeridas em forma de diffs. Cada apontamento do relatório tem seis campos:

Só os apontamentos de confiança alta e média entram nos diffs sugeridos. Os de confiança baixa aparecem apenas no relatório. Os diffs são divididos em um trecho (hunk) por apontamento, então você pode escolher só os que quiser.

Para aplicá-los, peça ao Claude algo como "aplique o 1, o 3 e o 4". O guia também diz que conflitos entre arquivos e reescritas de textos que não batem com o projeto não são aplicados a partir de um pedido genérico como "arrume tudo". Qualquer pessoa com permissão de escrita no repositório poderia ter alterado o texto mais recente ou o próprio projeto, então o desenho parte do princípio de que um humano confere cada um.

6. Diferenças em relação a /doctor, /claude-api prompt-audit e claude doctor

Existem quatro coisas com nomes parecidos. Comparando o que dizem a documentação oficial (Commands e Skills) e o CHANGELOG:

A parte confusa é que o próprio /doctor também mexe com o CLAUDE.md. A diferença está no objetivo. O /doctor quer reduzir o que é carregado sempre (remover duplicatas, cortar o que o código já diz ao Claude, mover coisas para lugares que só são carregados quando necessário). O /doctor prompt-audit verifica se o conteúdo ficou desatualizado ou se contradiz. O claude doctor do terminal não executa auditoria de prompts.

Se o Claude não segue suas instruções porque elas nem estão sendo carregadas, esta auditoria não vai resolver. Mostramos como verificar o que é carregado em "Por que a IA ignora regras: verificando CLAUDE.md, Cursor Rules e AGENTS.md", e como medir quanto do seu contexto os arquivos de instruções ocupam em "Claude Code: o que está consumindo o seu contexto?".

7. Testamos: auditoria do CLAUDE.md e do AGENTS.md deste site

Em 3 de outubro de 2026, rodamos o /doctor prompt-audit nos arquivos de instruções que usamos para desenvolver este site. Rodamos no aplicativo de desktop do Claude Code (com o Claude Code 2.1.286 embutido e o Opus 5.5 como modelo). Nossos arquivos de instruções são o AGENTS.md (as regras principais, compartilhadas entre o Claude Code e o Codex) e o CLAUDE.md (que o importa e acrescenta observações específicas do Claude Code), com cerca de 10.700 caracteres somados. Não mantemos regras, skills nem comandos dentro de .claude/.

A primeira surpresa foi que ela quase não encontrou prompting escrito para modelos antigos. Não havia nenhum "pense passo a passo" nem roteiro em etapas. A maior parte dos apontamentos estava no grupo 2 da seção 3 (arquivos de configuração frágeis).

O único apontamento de confiança alta era uma divergência real. Ao adicionar as ferramentas de auditoria, colocamos os nomes delas na lista, mas esquecemos de reescrever a explicação ao lado. Toda vez que o arquivo era carregado, o Claude podia entender errado a que "ambas" se referia, e nós não tínhamos percebido a olho nu.

O relatório também registrou que havia confirmado que todos os caminhos, nomes de ferramentas e notas referenciadas nos arquivos de instruções existem de fato. Chegou a conferir a versão do PHP (que batia com a configuração do Docker) e o número de etapas de um procedimento (que batia com uma lista de outro arquivo).

Não aceitamos os diffs sugeridos pelo Claude do jeito que vieram; aplicamos cada um só depois de confrontá-lo com os arquivos originais. Os cinco apontamentos de confiança média foram os que mais exigiram julgamento. A sugestão era apagar os registros de incidentes, mas esses registros são a prova que impede que os mesmos erros se repitam, então os movemos em vez de apagá-los. Quando as datas e os números já existiam em outro arquivo, apenas os tiramos dos arquivos de instruções; os dois que não estavam registrados em nenhum outro lugar copiamos para o arquivo de registros. No fim, os arquivos de instruções passaram de cerca de 10.700 caracteres para apenas uns 40 caracteres a menos. O tamanho quase não mudou; só as contradições desapareceram.

Lembre-se de que isto é uma execução em um projeto. Quem redige a auditoria é o modelo, então rodá-la de novo nos mesmos arquivos pode gerar outro número de apontamentos ou outra redação. Um projeto com muitas skills e comandos dentro de .claude/ provavelmente terá apontamentos bem diferentes.

8. Desvantagens e cuidados

Depois de usá-la e de ler a documentação oficial e o guia, estes são cinco pontos a ter em mente:

• Consome sua cota de uso: o Claude lê e audita seus arquivos de instruções dentro da sessão, então isso conta no seu uso como qualquer outro trabalho. A documentação oficial não menciona nenhuma cobrança separada.
• Não aplique os apontamentos às cegas: o Claude pode não saber por que uma regra foi escrita. No nosso caso, aceitar do jeito que veio a sugestão de "apagar os registros de incidentes" teria jogado fora a prova que evita erros repetidos.
• Os resultados variam de uma execução para outra: um modelo redige a auditoria, então a quantidade e a redação podem mudar a cada vez. Não trate uma execução limpa como prova de que um arquivo não tem problemas.
• Ela não olha os arquivos de configuração: não lê o settings.json nem o .mcp.json, então problemas de permissões, hooks e MCP não aparecem. Para isso, use o /doctor.
• Ela não garante que seu conteúdo esteja certo: detecta caminhos ausentes e contradições, mas não julga se a sua política é a correta. Essa decisão é sua.

O próprio guia trata as exclusões como hipóteses, não como conclusões. Depois de remover uma instrução, espera-se que você confira, no trabalho real, que o comportamento que ela garantia não quebrou.

9. Quando fazer uma auditoria de prompts

O guia descreve os prompts como produtos de um modelo específico, em que linhas de que uma geração precisava viram peso morto na seguinte, e recomenda auditar de novo sempre que sai um modelo novo. Na nossa avaliação, estas três situações são boas ocasiões:

• Quando você passa para uma geração de modelos mais nova: para procurar textos enfáticos e gambiarras que sobraram dos modelos antigos
• Depois de reescrever a fundo seus arquivos de instruções: como no nosso teste, regras novas e explicações antigas tendem a se desencontrar
• Quando você compartilha arquivos de instruções entre ferramentas como Claude Code e Codex: fica mais fácil notar contradições entre o AGENTS.md e o CLAUDE.md

Por outro lado, se seus arquivos de instruções são curtos e raramente mudam, não há pressa. O guia também diz que não encontrar nada é um resultado correto.

Resumo

O /doctor prompt-audit é um comando que procura nos seus arquivos de instruções (CLAUDE.md, AGENTS.md, skills e mais) textos escritos para modelos antigos, caminhos e comandos que não existem e regras conflitantes, e depois devolve um relatório e diffs sugeridos. Está disponível no Claude Code v2.1.283 e posteriores, e nada muda até você pedir.

O guia de auditoria protege o contexto, os motivos e as proibições contra falhas que ainda acontecem como coisas que não devem ser apagadas, para que ela não vire uma auditoria para "encurtar". Quando a rodamos nos arquivos de instruções deste site, quase não havia prompting ultrapassado, mas ela encontrou uma explicação que esquecemos de reescrever depois de adicionar uma regra, uma divergência real.

O caminho seguro é confrontar cada apontamento com o arquivo original e mover, em vez de apagar, o texto que existe por algum motivo. Rodá-la uma vez depois de trocar de modelo ou de reescrever seus arquivos de instruções pode revelar contradições que passaram despercebidas a olho nu.

Perguntas frequentes

P. O /doctor prompt-audit vai reescrever meu CLAUDE.md sozinho?

R. Não. A documentação oficial diz que ele devolve um relatório e correções sugeridas, e que nada nos seus arquivos muda até você pedir ao Claude que as aplique. Mesmo assim, você pode escolher sugestão por sugestão.

P. Qual é a diferença entre /doctor prompt-audit e /checkup prompt-audit?

R. Nenhuma. /checkup é um alias de /doctor, e a entrada da v2.1.283 no CHANGELOG cita o /doctor prompt-audit junto com o /checkup prompt-audit.

P. Ele também audita o AGENTS.md do Codex?

R. Sim. A documentação oficial lista o AGENTS.md, ao lado do CLAUDE.md e do CLAUDE.local.md, entre os arquivos auditados quando você não passa nenhum argumento. Se você compartilha os dois arquivos, ele também é bom para encontrar contradições entre eles.

P. Digitei, mas a auditoria não começa.

R. Primeiro confira sua versão: o /doctor prompt-audit exige a v2.1.283 ou posterior. Se a sua versão é recente o bastante e mesmo assim ele não roda, verifique se você desligou a skill embutida /claude-api nas configurações (skillOverrides ou disableBundledSkills). Note também que o claude doctor digitado no terminal só diagnostica sua instalação e não executa esta auditoria.

P. Ele consegue auditar o prompt de sistema de um aplicativo que criei sobre a API?

R. Sim, mas para isso use o /claude-api prompt-audit (v2.1.221 ou posterior). Ele audita seus prompts, as descrições de ferramentas e o código que chama a API em busca de padrões escritos para modelos antigos e sugere diffs.

Fontes

• Documentação do Claude Code: How Claude remembers your project (seção "Audit your instruction files")
• Documentação do Claude Code: Commands (as linhas de /doctor e /claude-api)
• Documentação do Claude Code: Skills (subcomandos da skill embutida /claude-api e versões exigidas)
• Claude Code: CHANGELOG (v2.1.283)
• O guia de prompt-audit da skill /claude-api embutida no Claude Code v2.1.286 (consultado na nossa própria máquina)

Todas as fontes foram consultadas no original em 3 de outubro de 2026. O guia embutido é atualizado a cada versão do Claude Code, então o que a auditoria verifica pode mudar de uma versão para outra.