Template CLAUDE.md para Claude Code em projetos existentes

CLAUDE.md reduz o contexto repetido no início de cada sessão

Em um código existente, Claude Code precisa de mais do que uma tarefa bem escrita. Ele precisa saber qual package manager usar, onde fica a aplicação, quais pastas são geradas, quais comandos são perigosos e qual é o critério de conclusão. Quando isso fica apenas no chat, cada nova sessão começa fria.

CLAUDE.md é o menor arquivo operacional para resolver esse problema. A documentação oficial de Claude Code memory explica que o arquivo é carregado como instrução persistente no início da sessão. Mas ele é contexto, não bloqueio rígido. Para restringir comandos e caminhos, combine com settings, permissões, hooks, CI e regras do repositório. Para secrets e deploys, leia também a documentação de security.

Aqui, harness significa uma estrutura de apoio para o agente trabalhar com limites. O objetivo não é criar um manual gigante. O objetivo é impedir o próximo erro repetido. Para outros modelos, veja templates de CLAUDE.md e o guia de permissões do Claude Code.

Template CLAUDE.md pronto para copiar

A primeira versão deve ser curta: visão do projeto, comandos, limites, regras de qualidade e definition of done.

# CLAUDE.md

## Project snapshot
- Product: content site and paid template store
- Stack: Astro, TypeScript, MDX, npm
- Main app: site/
- Source articles: site/src/content/blog*/
- Owner voice: practical, evidence-based, no hype

## Commands
- Install dependencies: cd site && npm install
- Start local dev server: cd site && npm run dev
- Build check: cd site && npm run build
- Search fast: rg "keyword" site/src
- Inspect git state: git status --short

## Working rules
- Read existing files before editing.
- Keep changes scoped to the requested slug or feature.
- Do not edit .env, dist, generated reports, or unrelated locale files.
- Preserve pubDate, category, tags, author, lang, and heroImage unless they are broken.
- Ask before destructive git operations, production deploys, or secret rotation.

## Article quality
- Japanese canonical articles should be 4000-6000 characters excluding code.
- Include at least three real use cases.
- Include concrete pitfalls and how to avoid them.
- Include runnable code or config examples, not pseudocode.
- Check official docs when the topic may have changed.

## Definition of done
- The requested files are edited.
- Code fences and JSON/YAML examples are valid.
- Links to internal pages and official docs are present.
- Verification commands have run or skipped checks are explained.
- Remaining risks are stated in the final message.

Salve comoCLAUDE.mdna raiz do repositório. Se o projeto já usaAGENTS.md, crie umCLAUDE.mdpequeno que importe a regra comum e acrescente apenas instruções específicas para Claude Code. Preferências pessoais ficam melhor emCLAUDE.local.md.

Use settings para limites de execução

Escrever “não faça push” emCLAUDE.mdajuda, mas não bloqueia a ação. Limites críticos devem ficar em settings, CI, proteção de branch ou aprovação de deploy.

{
  "permissions": {
    "allow": [
      "Read",
      "Edit(site/src/content/blog/**)",
      "Bash(rg:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(node:*)"
    ],
    "deny": [
      "Bash(git reset:*)",
      "Bash(git checkout --:*)",
      "Bash(git push:*)",
      "Bash(npm publish:*)",
      "Edit(.env*)",
      "Edit(reports/**)"
    ]
  }
}

Use.claude/settings.local.jsonpara uma proteção pessoal e.claude/settings.jsonpara padrão do time. Antes de copiar, confirme o schema atual na página oficial de settings. CLAUDE.md dá contexto; settings definem o que pode ser executado.

Três casos de uso práticos

Caso de uso	O que escrever no CLAUDE.md	Melhoria
Manutenção de artigos localizados	slug alvo, lista de locales, frontmatter preservado, tamanho mínimo, CTA, verificação	Menos idiomas esquecidos, restos em inglês, links quebrados e datas antigas
Correção pequena em SaaS	diretórios editáveis, comando de teste, aprovação para banco, regra de logs	Menos refactor fora de escopo e menos migrations arriscadas
Code review em time	severidade, arquivo, linha, impacto, reprodução, teste ausente	Comentários viram ação em PR ou issue

Em conteúdo multilíngue, o erro comum é ter todos os arquivos, mas o texto no idioma errado. Especificar diretórios, rotas internas e limite de description reduz esse problema.

Em SaaS, escopo é essencial. Um bug visual não deve alterar billing, auth ou migration. Escreva que Claude Code deve ler primeiro, mudar a menor área possível, rodar o teste certo e pedir aprovação antes de mexer em dados.

Em review, o formato decide a utilidade. Peça severity, path, line, impacto no usuário, reprodução e test gap. Para rodar via script, veja a CLI reference.

Armadilhas comuns

A primeira armadilha é escrever demais. Um arquivo de 300 linhas parece completo, mas consome contexto e fica menos seguido. Deixe regras frequentes no arquivo principal e mova regras específicas para path-scoped rules ou docs separadas.

A segunda armadilha é incluir secrets. API keys, nomes de clientes, URLs internas e números de receita não publicados não entram emCLAUDE.md. Escreva só a regra: secrets ficam em variáveis de ambiente, não são impressos e arquivos sensíveis exigem confirmação.

A terceira armadilha é manter comandos antigos. Se o projeto mudou de Yarn para npm, de Jest para Vitest ou de Next.js para Astro, atualizeCLAUDE.mdno mesmo momento. Comando velho faz Claude Code trabalhar errado com confiança.

A quarta armadilha é esquecer o recibo de verificação. A resposta final deve dizer comandos executados, resultados, arquivos modificados, links checados e riscos restantes. Isso pega muitos erros pequenos antes da publicação.

Introdução gradual

Comece com este template e use em três tarefas pequenas: edição de conteúdo, ajuste de UI e review. Depois adicione apenas regras que teriam evitado um erro real. Limites obrigatórios vão para settings, CI, branch protection ou aprovação de deploy.

Em sites com monetização, CTA também é qualidade. Products, checkout, training e formulário de consulta precisam continuar funcionando depois de mudanças de texto ou layout. Coloque isso na definition of done.

Para prompts, templates e checklists reutilizáveis, veja ClaudeCodeLab products. Para rollout de time com permissões, review gates, treinamento eCLAUDE.mdadaptado ao repositório, use Claude Code training and consultation. O melhor template é o que evita o próximo erro repetido.