CLAUDE.md para Claude Code: regras verificáveis

Uma lista longa de preferências não torna o Claude Code previsível. Uma regra útil define a mudança permitida, o limite e a evidência: arquivo, diff, comando e código de saída.

Contrato pequeno

# Project rules
## Goal
- Keep changes limited to the requested feature.
## Checks
- Run npm test and report the command, exit code, and changed files.
## Forbidden
- Do not read .env or run deploy.
## Scope
- packages/payments/CLAUDE.md wins only inside that directory.
- Root security rules always apply.

“Escreva código de qualidade” não é verificável. “Execute npm test e informe comando, código e caminhos alterados” é.

Segredos e conflitos

Não coloque API Keys, tokens de CI nem dados pessoais reais em CLAUDE.md. Use placeholders e passe valores necessários pelo ambiente ou secret store do CI. Regras gerais ficam na raiz; regras do pacote, perto do pacote. Uma exceção local não pode cancelar segurança global.

Teste reversível

1. Peça para renomear uma variável local em um único arquivo de teste.
2. Execute git diff --check e examine git diff --stat.
3. Rode o teste indicado no contrato.
4. Rejeite se outro arquivo mudou ou se faltam comando e código de saída.

Para um fluxo API separado do Claude Code, confira Base URL e modelo na documentação BetterToken.