O CLAUDE.md para projeto WordPress que funciona é curto: versões, onde pode mexer, comandos do projeto e o que é proibido tocar. O Claude Code lê esse arquivo da raiz em toda sessão, então cada linha ali vira regra fixa. Eu começo com o /init, que gera um rascunho lendo o código, e depois corto mais da metade.
O que fica no arquivo
# Loja do cliente: WordPress 6.9, PHP 8.3
## Onde pode mexer
- Só em wp-content/themes/loja-filho/ e wp-content/mu-plugins/.
- Tema pai e plugin de terceiro: nunca. Precisou? Proponha um hook no tema filho.
## Comandos
- WP-CLI: wp --path=/var/www/loja (ex.: wp plugin list)
- Padrão de código: vendor/bin/phpcs wp-content/themes/loja-filho
## Padrões
- Prefixo lf_ em função, hook e opção; text domain loja-filho.
- Saída com esc_html, esc_attr ou esc_url; formulário com nonce.
## Proibido
- wp-config.php, wp-content/uploads/ e qualquer comando no banco de produção.A regra do tema filho é a que mais salva. Sem ela, o Claude acha a função no tema pai e corrige lá mesmo, e a próxima atualização do tema apaga a correção. Com o “proponha um hook”, ele procura o filtro certo em vez de copiar o arquivo inteiro.
Por que curto funciona melhor
Manual de 300 linhas dilui as regras: o que importa fica no meio de explicação que o Claude descobriria sozinho lendo o código. Eu deixo de fora estrutura de pastas, lista de plugins e história do projeto. Fica o que ele erraria sem aviso.
Se o time já tem um AGENTS.md ou um guia de padrões, não copie o conteúdo: uma linha @AGENTS.md no CLAUDE.md importa o arquivo.
Instrução não é trava
O CLAUDE.md orienta, mas não impede nada. Para barrar comando de verdade, como um wp db reset, a regra vai nas permissões do .claude/settings.json, que o Claude Code aplica antes de rodar.
Toda vez que o Claude errar a mesma coisa duas vezes, vira uma linha nova no arquivo; o resto continua no código.