HABILIDADE MESTRA CLAUDE.md (Criar/Atualizar/Melhorar)

--- name: claude-md-master description: Habilidade mestre para o ciclo de vida do CLAUDE.md - criar, atualizar, melhorar com conteúdo verificado no repositório e suporte a múltiplos módulos. Use ao criar ou atualizar arquivos CLAUDE.md. --- # CLAUDE.md Master (Criar/Atualizar/Melhorar) ## Quando usar - O usuário pede para criar, melhorar, atualizar ou padronizar arquivos CLAUDE.md. ## Regras principais - Incluir apenas informações verificadas no repositório ou na configuração. - Nunca incluir segredos, tokens, credenciais ou dados do usuário. - Nunca incluir instruções específicas de tarefas ou temporárias. - Manter conciso: raiz <= 200 linhas, módulo <= 120 linhas. - Usar marcadores; evitar prosa longa. - Comandos devem ser copiáveis e originados de docs/scripts/CI do repositório. - Pular seções vazias; evitar preenchimento desnecessário. ## Entradas obrigatórias (analisar antes de gerar) - Configuração de build/package relevante para a stack detectada (raiz + módulos). - Configuração de análise estática usada no repositório (se presente). - Estrutura real de módulos e padrões de código-fonte (verificar diretórios/arquivos reais). - Raízes de código-fonte representativas por módulo para extrair: estrutura de pacotes/features, tipos-chave e anotações em uso. ## Descoberta (rápida + direcionada) 1. Localizar variantes existentes de CLAUDE.md: `CLAUDE.md`, `.claude.md`, `.claude.local.md`. 2. Identificar stack e pontos de entrada por meio de leituras mínimas: - `README.md`, `docs/*` relevantes - Arquivos de build/package (ver referências de stack) - Runtime/config: `Dockerfile`, `docker-compose.yml`, `.env.example`, `config/*` - CI: `.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/*` 3. Extrair comandos apenas se existirem em scripts/config/docs do repositório. 4. Detectar estrutura de múltiplos módulos: - Android/Gradle: ler includes de `settings.gradle` ou `settings.gradle.kts`. - iOS: detectar múltiplos targets/workspaces em `*.xcodeproj`/`*.xcworkspace`. - Se mais de um módulo/target tiver `src/` ou configuração de build, planejar arquivos CLAUDE.md de módulo. 5. Para cada candidato a módulo, ler seu arquivo de build + docs mínimas para capturar propósito específico do módulo, pontos de entrada e comandos. 6. Escanear raízes de código-fonte para: - Pastas de pacotes/features de nível superior e convenções de camadas. - Anotações/tipos-chave em uso (conforme referência de stack). - Convenções de nomenclatura usadas no codebase. 7. Capturar fluxos de trabalho não óbvios/armadilhas de docs ou padrões de código. Desempenho: - Preferir listagem de arquivos + leituras direcionadas. - Evitar leituras completas de arquivos quando uma seção ou símbolo for suficiente. - Pular diretórios grandes: `node_modules`, `vendor`, `build`, `dist`. ## Referências específicas por stack (Padrão 2) Ler a referência relevante apenas quando sinais de detecção aparecerem: - Android/Gradle → `references/android.md` - iOS/Xcode/Swift → `references/ios.md` - PHP → `references/php.md` - Go → `references/go.md` - React (web) → `references/react-web.md` - React Native → `references/react-native.md` - Rust → `references/rust.md` - Python → `references/python.md` - Java/JVM → `references/java.md` - Ferramentas Node → `references/node.md` - .NET/C# → `references/dotnet.md` - Dart/Flutter → `references/flutter.md` - Ruby/Rails → `references/ruby.md` - Elixir/Erlang → `references/elixir.md` - C/C++/CMake → `references/cpp.md` - Outro/Desconhecido → `references/generic.md` (fallback quando nenhuma referência específica corresponde) Se múltiplas stacks forem detectadas, ler múltiplas referências. Se nenhuma stack for reconhecida, usar a referência genérica. ## Política de saída para múltiplos módulos (obrigatória quando detectado) - Sempre criar um `CLAUDE.md` raiz. - Também criar `CLAUDE.md` dentro de cada raiz de módulo/target relevante. - "Relevante" = tem sua própria configuração de build e `src/` (ou equivalente). - Pular diretórios apenas de ferramentas como `buildSrc`, `gradle`, `scripts`, `tools`. - O arquivo do módulo deve ser específico do módulo e evitar duplicação: - Incluir propósito, caminhos-chave, pontos de entrada, testes do módulo e comandos do módulo (se houver). - Referenciar informações compartilhadas via `@/CLAUDE.md`. ## Política de CLAUDE.md para módulos de negócio (todas as stacks) Para diretórios de lógica de negócio em monorepo (`src/`, `lib/`, `packages/`, `internal/`): - Criar `CLAUDE.md` para módulos com >5 arquivos OU README próprio - Pular diretórios apenas de utilitários: `Helper`, `Utils`, `Common`, `Shared`, `Exception`, `Trait`, `Constants` - Estrutura em camadas não é obrigatória; fornecer informações do módulo independentemente da arquitetura - Máximo de 120 linhas por CLAUDE.md de módulo - Referenciar a raiz via `@/CLAUDE.md` para arquitetura/padrões compartilhados - Incluir: propósito, estrutura, classes-chave, dependências, pontos de entrada ## Seções de saída obrigatórias (por CLAUDE.md de módulo) Incluir estas seções se detectadas no codebase (pular apenas se não presentes): - **Inventário de features/componentes**: listar diretórios de nível superior sob a raiz do código-fonte - **Módulos core/compartilhados**: diretórios de código utilitário, comum ou compartilhado - **Estrutura de navegação/roteamento**: grafos de navegação, rotas ou roteadores - **Padrão de camada de rede/API**: clientes de API, endpoints, wrappers de resposta - **Padrão de DI/injeção**: módulos, contêineres ou configuração de injeção - **Arquivos de build/config**: configurações específicas do módulo (proguard, manifests, etc.) Ver referências específicas por stack para padrões exatos a detectar e relatar. ## Fluxo de atualização (deve ser seguido) 1. Propor apenas adições direcionadas; mostrar diffs por arquivo. 2. Pedir aprovação antes de aplicar atualizações: **Cursor IDE:** Usar a ferramenta AskQuestion com estas opções: - id: "approval" - prompt: "Aplicar estas atualizações do CLAUDE.md?" - options: [{"id": "yes", "label": "Sim, aplicar"}, {"id": "no", "label": "Não, cancelar"}] **Claude Code (Terminal):** Exibir as alterações propostas e perguntar: "Você aprova estas atualizações? (sim/não)" Parar e aguardar a resposta do usuário antes de prosseguir. **Outros Ambientes (Fallback):** Se nenhuma ferramenta de pergunta estruturada estiver disponível: 1. Exibir as alterações propostas claramente 2. Perguntar: "Você aprova estas atualizações? Responda 'sim' para aplicar ou 'não' para cancelar." 3. Aguardar confirmação explícita do usuário antes de prosseguir 3. Aplicar atualizações, preservando conteúdo personalizado. Se nenhum CLAUDE.md existir, propor um novo arquivo para aprovação. ## Regras de extração de conteúdo (obrigatórias) - Apenas do codebase: - Extrair: nomes de tipos/classes/anotações usados, padrões de caminho reais, convenções de nomenclatura. - Nunca: valores codificados, segredos, chaves de API, lógica específica de negócio. - Nunca: trechos de código em regras Faça/Não Faça. ## Verificação antes de escrever - [ ] Cada regra referencia tipos/caminhos reais do codebase - [ ] Sem exemplos de código nas seções Faça/Não Faça - [ ] Padrões correspondem ao que realmente está no codebase (não desatualizados) ## Regras de conteúdo - Incluir: comandos, resumo da arquitetura, caminhos-chave, testes, armadilhas, peculiaridades de fluxo de trabalho. - Excluir: melhores práticas genéricas, informações óbvias, declarações não verificadas. - Usar imports `@caminho/para/arquivo` para evitar duplicação. - O formato Faça/Não Faça é opcional; manter apenas se já usado no arquivo. - Evitar exemplos de código, exceto comandos curtos copiáveis. ## Estratégia para arquivos existentes Detecção: - Se `<!-- Gerado pela habilidade claude-md-editor -->` existir → execução subsequente - Caso contrário → primeira execução Primeira execução + arquivo existente: - Fazer backup de `CLAUDE.md` → `CLAUDE.md.bak` - Usar `.bak` como fonte e extrair apenas informações reutilizáveis e específicas do projeto - Gerar um novo arquivo conciso e adicionar o marcador Execução subsequente: - Preservar seções personalizadas e redação, a menos que desatualizadas ou incorretas - Atualizar apenas o que conflita com o estado atual do repositório - Adicionar seções ausentes apenas se agregarem valor real Nunca modificar `.claude.local.md`. ## Saída Após atualizações, imprimir um relatório conciso: ``` ## Relatório de Atualização do CLAUDE.md - /CLAUDE.md [CRIADO | BACKUP+CRIADO | ATUALIZADO] - /<módulo>/CLAUDE.md [CRIADO | ATUALIZADO] - Backups: listar quaisquer arquivos `.bak` ``` ## Checklist de validação - A descrição é específica e inclui termos de gatilho - Sem placeholders restantes - Sem segredos incluídos - Comandos são reais e copiáveis - Regra de relatório primeiro respeitada - Referências com um nível de profundidade