Gerador de CLAUDE.md
Leia o código-fonte. Escreva um CLAUDE.md que diga exatamente o que o Claude precisa: nem mais, nem menos.
Regra crítica: Um bom CLAUDE.md tem menos de 100 linhas. Contém apenas informações que o Claude não consegue derivar da leitura do código em si. Não escreva o arquivo automaticamente: sempre mostre o rascunho e aguarde a aprovação do usuário primeiro.
Regra de snippets de código: Nunca inclua exemplos de código inline no CLAUDE.md. Em vez disso, use referências como arquivo.ts:42. Código no CLAUDE.md desperdiça tokens e fica desatualizado.
Etapa 1: Detectar Modo
Determine qual dos três modos executar:
create: Nenhum CLAUDE.md existe. Escreva um do zero. update: Um CLAUDE.md existe. Melhore-o sem descartar conteúdo personalizado. audit: Pontue todos os arquivos CLAUDE.md no projeto de A a F e gere um relatório de qualidade. Se o usuário disser "auditar", "verificar", "revisar" ou "avaliar" meu CLAUDE.md, execute o modo audit.
# Descubra TODOS os locais de CLAUDE.md
find . -name "CLAUDE.md" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null
ls ~/.claude/CLAUDE.md 2>/dev/null && echo "CLAUDE.md global encontrado"
ls .claude.local.md 2>/dev/null && echo ".claude.local.md encontrado"
Se vários arquivos CLAUDE.md forem encontrados: liste-os. Pergunte: "Encontrei CLAUDE.md em [locais]. Devo atualizar todos ou apenas [raiz]?"
Etapa 2: Modo de Auditoria (pule para a Etapa 3 se for create/update)
Para cada CLAUDE.md encontrado, atribua uma nota de A a F usando esta rubrica:
| Critério | O que verificar |
|---|---|
| Comandos | Comandos de build/teste/lint presentes e executáveis? |
| Arquitetura | Estrutura não óbvia explicada? |
| Padrões não óbvios | Pegadinhas, arquivos gerados, ordem de variáveis de ambiente documentada? |
| Concisão | Menos de 100 linhas? Sem preenchimento óbvio? |
| Atualidade | Comandos ainda correspondem ao package.json/Makefile atual? |
| Acionabilidade | Um novo contribuidor pode seguir isso sem fazer perguntas? |
Pontuação: 90-100 = A, 70-89 = B, 50-69 = C, 30-49 = D, 0-29 = F
Apresente como uma tabela:
## Relatório de Auditoria do CLAUDE.md
| Arquivo | Pontuação | Nota | Principais Problemas |
|---------|-----------|------|----------------------|
| ./CLAUDE.md | 72 | B | Seção de pegadinhas ausente, comando de teste desatualizado |
| ./packages/api/CLAUDE.md | 45 | D | Nenhum comando, 340 linhas (muito longo), anotações de arquitetura obsoletas |
**Geral: B (72/100)**
Problemas encontrados:
- ./packages/api/CLAUDE.md: 340 linhas: muito acima do alvo de 100 linhas
- ./packages/api/CLAUDE.md: Comando de teste referencia `jest` mas package.json usa `vitest`
- ./CLAUDE.md: Nenhuma seção de Pegadinhas: a seção mais valiosa está faltando
Após o relatório, pergunte: "Quer que eu corrija algum destes? (todos / apenas raiz / especifique)"
Se o usuário disser sim, continue para a Etapa 3 para cada arquivo que ele deseja corrigir.
Etapa 3: Escanear Estrutura do Projeto
# Tipo de projeto e gerenciador de pacotes
ls package.json yarn.lock pnpm-lock.yaml bun.lockb requirements.txt pyproject.toml Cargo.toml go.mod 2>/dev/null
# Estrutura de diretórios de nível superior
find . -maxdepth 2 -type d \
| grep -v node_modules | grep -v .git | grep -v __pycache__ \
| grep -v ".next" | grep -v dist | grep -v build | sort
Etapa 4: Extrair Comandos de Build e Teste
# Scripts npm/yarn/pnpm/bun
cat package.json 2>/dev/null \
| python3 -c "
import sys, json
d = json.load(sys.stdin)
for name, cmd in d.get('scripts', {}).items():
print(f'{name}: {cmd}')
"
# Makefiles Python, Go, Rust
cat Makefile 2>/dev/null | grep -E "^[a-z].*:" | head -20
# Go
cat go.mod 2>/dev/null | head -5
# Rust
cat Cargo.toml 2>/dev/null | grep -E "^\[" | head -10
Identifique os comandos exatos para: build, teste (todos), teste (arquivo/nome único), servidor de desenvolvimento, lint/typecheck. Anote quaisquer variáveis de ambiente necessárias para executá-los.
Etapa 5: Encontrar Estilo de Código e Pegadinhas
# Aliases de importação (mais comumente esquecidos)
python3 -c "
import json, sys
try:
d = json.load(open('tsconfig.json'))
paths = d.get('compilerOptions', {}).get('paths', {})
if paths: print('Aliases de importação:', json.dumps(paths, indent=2))
except: pass
" 2>/dev/null
# Variáveis de ambiente necessárias
cat .env.example 2>/dev/null | grep -v "^#" | grep -v "^$" | head -20
# Arquivos gerados automaticamente (não devem ser editados)
find . -path "*/node_modules" -prune -o -name "*.ts" -print \
| xargs grep -l "DO NOT EDIT\|@generated\|Generated by" 2>/dev/null | head -5
# Requisitos de configuração de teste
cat jest.config.js jest.config.ts vitest.config.ts 2>/dev/null | head -30
# Configuração de banco de dados/migração
ls migrations/ prisma/ drizzle/ db/ 2>/dev/null
O que conta como Pegadinha (inclua estas, pule todo o resto):
- Arquivos que são gerados automaticamente (não devem ser editados)
- Variáveis de ambiente necessárias ANTES da execução dos testes
- Mapeamentos de aliases de importação não padrão
- Comandos de teste que exigem um serviço em execução
- Peculiaridades intencionais conhecidas (soluções alternativas, não bugs)
Etapa 6: Gerar Rascunho do CLAUDE.md com Gemini
Compile todas as descobertas e gere o rascunho:
cat > /tmp/claude-md-request.json << 'ENDJSON'
{
"system_instruction": {
"parts": [{
"text": "Escreva um arquivo CLAUDE.md para um projeto de software. Regras: (1) Menos de 100 linhas no total. (2) Inclua apenas o que o Claude não pode derivar da leitura do código. (3) Sem exemplos de código inline: use referências como arquivo.ts:42. (4) Seções: Comandos, Estilo de Código (apenas não padrões), Testes (apenas se for necessária configuração), Pegadinhas (obrigatório: o que pega as pessoas). Pule qualquer seção que não tenha nada de não óbvio para dizer. (5) Todos os comandos em blocos de código. (6) Ordem preferida: Breve Visão Geral do Projeto (1-2 frases, apenas se não óbvia), Comandos, Arquitetura (apenas estrutura não óbvia), Estilo de Código, Testes, Pegadinhas. (7) Não use travessões. (8) Produza apenas o conteúdo do CLAUDE.md, sem comentários."
}]
},
"contents": [{
"parts": [{
"text": "ANALISE_DO_PROJETO_AQUI"
}]
}],
"generationConfig": {
"temperature": 0.3,
"maxOutputTokens": 2048
}
}
ENDJSON
curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d @/tmp/claude-md-request.json \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(d['candidates'][0]['content']['parts'][0]['text'])"
Substitua ANALISE_DO_PROJETO_AQUI pelas descobertas das Etapas 3-5.
Para projetos grandes (50+ arquivos): Adicione um ponteiro @path no final do CLAUDE.md em vez de detalhes inline:
## Referência Estendida
Veja @docs/ai-context/architecture.md para o mapa completo do módulo.
Veja @docs/ai-context/testing.md para detalhes da configuração de teste de integração.
Escreva os arquivos referenciados em docs/ai-context/ com os detalhes que não caberiam em 100 linhas.
Etapa 7: Auto-Verificação
Antes de apresentar o rascunho, verifique:
- Menos de 100 linhas (conte:
echo "$CONTEUDO" | wc -l) - Sem exemplos de código inline (apenas referências
arquivo.ts:42ou comandos shell) - Todos os comandos em blocos de código e executáveis como estão
- Seção de Pegadinhas presente com pelo menos uma entrada real
- Nenhuma seção que diz apenas coisas óbvias a partir dos arquivos
- Sem travessões
- Sem palavras de marketing ou frases de preenchimento ("Este projeto usa React para...")
- Aliases de importação documentados se existirem
- Arquivos gerados automaticamente marcados como "não editar" se existirem
Se alguma verificação falhar, revise antes de apresentar.
Etapa 8: Apresentar Rascunho e Aguardar Aprovação
Nunca escreva o arquivo sem a aprovação do usuário.
Apresente o rascunho em um bloco de código:
## Rascunho do CLAUDE.md ([N] linhas)
[conteúdo completo do rascunho aqui]
---
Escrever isso no CLAUDE.md? (sim / editar primeiro / cancelar)
Se o usuário disser sim: escreva o arquivo e confirme: "CLAUDE.md escrito ([N] linhas). Seções: [lista de ## cabeçalhos]."
Se o usuário disser editar primeiro: aplique as edições e mostre o rascunho novamente.
Se o usuário disser cancelar: pare.
O que NÃO Incluir
- Versão da linguagem/framework ("Este é um projeto TypeScript")
- Como o framework funciona (o Claude já conhece React, FastAPI, etc.)
- Lista de todas as dependências
- Regras de estilo que o linter já aplica (tamanho da indentação, estilo de aspas)
- Conteúdo que duplica o README.md
- Exemplos de código inline ou snippets de várias linhas
- Qualquer coisa que seria idêntica para qualquer projeto usando a mesma pilha