herdar-estilo-legado

Herdar Estilo Legado

Previne o desvio de estilo de código gerado por IA em projetos legados, examinando a base de código em busca de convenções implícitas em 4 dimensões meta-arquiteturais, resolvendo conflitos com o usuário um de cada vez e cristalizando o consenso em um .ai-style-rules.md acionável. Totalmente independente de linguagem e framework.

Quando Ativar

• Usuário digitar /herdar-estilo-legado
• Usuário mencionar embarcar IA em um projeto legado escrito à mão
• Usuário estiver preocupado com o código gerado por IA "desviando" das convenções existentes do projeto
• Usuário quiser extrair e codificar as regras de codificação implícitas do seu projeto

Quando Usar

Use esta habilidade quando precisar preservar o estilo de projeto legado e evitar o desvio de estilo gerado por IA. Veja Quando Ativar acima para condições de gatilho.

Pré-requisitos

• Git (recomendado; projetos não-Git usam timestamps de arquivo para modo incremental)
• Acesso de leitura/escrita à raiz do projeto (gera .ai-style-rules.md e opcionalmente CLAUDE.md)

Fluxo de Trabalho

Passo 0 — Modo de Detecção Automática

Verifique silenciosamente a existência de .ai-style-rules.md na raiz do projeto:

Arquivo existe?	Modo
Não	Branch A — Primeira Varredura Completa
Sim	Branch B — Checagem Incremental

Anuncie o modo em uma linha e prossiga — nunca peça ao usuário para escolher.

Branch A — Primeira Varredura Completa

1. Medir escala, escolher um nível de varredura

git ls-files | grep -cE '\.(js|ts|jsx|tsx|vue|py|go|rs|java|kt|rb|php|cs|swift|c|cpp|h)$'

Nível	Arquivos-fonte	Estratégia
Pequeno	≲ 50	Leitura completa de cada fonte
Médio	50–500	Camada de infra = leitura completa; camada de negócio = amostrar 2–3 por dimensão
Grande	≳ 500	Amostragem estrita + limite de orçamento; resumo --stat primeiro, depois leituras direcionadas

2. Escanear ao longo de 4 dimensões

1. Anatomia de Arquivo — ordem de declaração no arquivo (imports → tipos → lógica principal → helpers → export)
2. Fluxo de Estado e Controle — convenções de nomenclatura para estado assíncrono, paginação, flags
3. Infraestrutura — onde vivem utilitários transversais (interceptadores, formatadores, middlewares)
4. Tratamento de Erros — try/catch vs interceptador global vs retorno Result; hábitos de verificação de nulo

3. Aplicar redução de ruído por limite de sinal

Antes de interromper o usuário, avalie a força do sinal:

• Sinal fraco → suprimir automaticamente: minoria <5% E contagem <10 → maioria vence, minoria vai para DONTs
• Sinal forte → interrogar: divisão quase igual, ou bifurcação semântica em uma dimensão central
• Exceção de projeto pequeno: fontes ≲50, "3 contra 2" NÃO é maioria → interrogar

4. Resolver conflitos um de cada vez (Protocolo de Interrogatório)

Para cada conflito de sinal forte, apresente EXATAMENTE uma pergunta com 4 opções:

Evidência: pathA usa estilo X, pathB usa estilo Y AVISO: Risco: misturar ambos fragmenta o estilo do projeto Escolha: 1 seguir X 2 seguir Y 3 isso é evolução, atualizar regras 4 Eu tenho uma nova regra

Suspenda até o usuário responder, então prossiga para o próximo conflito. Nunca acumule perguntas.

5. Gerar .ai-style-rules.md com três seções obrigatórias:

• [Arquivos Dourados] — caminhos de exemplares reais anotados com o que demonstram
• [Regras de Nomenclatura e Controle de Estado] — convenções concretas e verificáveis
• [DONTs] — anti-padrões que não devem se propagar

6. Instalar o gancho persistente

Pergunte ao usuário pela força de aplicação (use AskUserQuestion):

Opção	Mecanismo
1 Gancho suave (recomendado)	Escrever referência @.ai-style-rules.md no CLAUDE.md do projeto
2 Gancho duro	Gancho suave + Hook `PreToolUse[Write
3 Sem gancho	Manter o arquivo de regras; usuário consulta manualmente

Branch B — Checagem Incremental

1. Ler .ai-style-rules.md existente; se tiver uma impressão digital de commit, git diff <ultimo_hash> HEAD --stat para identificar o delta
2. Ler mudanças recentes do Git (git log -3 --stat → inspecionar arquivos suspeitos sob demanda)
3. Para diffs muito grandes (>centenas de arquivos): apenas resumo --stat + amostrar as maiores mudanças
4. Comparar novo código com regras registradas → conflitos passam pelo Protocolo de Interrogatório
5. Anexar log de evolução ao final de .ai-style-rules.md (nunca sobrescrever regras antigas)

Aplicação por Turno

Quando .ai-style-rules.md estiver em contexto (carregado via CLAUDE.md), toda tarefa de escrita de código deve abrir com uma declaração de conformidade na cadeia de raciocínio, nomeando o exemplar sendo seguido e os DONTs sendo evitados.

Como Funciona

Esta habilidade detecta automaticamente se é uma execução pela primeira vez ou incremental, pela presença de .ai-style-rules.md:

• Primeira vez (Branch A) — Mede a escala do projeto, examina a base de código em 4 dimensões meta-arquiteturais (Anatomia de Arquivo, Fluxo de Estado e Controle, Infraestrutura, Tratamento de Erros), aplica redução de ruído por limite de sinal para suprimir conflitos fracos, resolve conflitos de sinal forte um de cada vez com o usuário, gera .ai-style-rules.md com Arquivos Dourados / Regras de Nomenclatura / DONTs, e oferece ganchos de aplicação opcionais.
• Incremental (Branch B) — Lê regras existentes, verifica diffs recentes do Git em busca de padrões novos ou conflitantes, executa o mesmo protocolo de interrogatório um de cada vez para quaisquer conflitos encontrados, e anexa logs de evolução sem sobrescrever regras existentes.
• Aplicação por Turno — Quando conectado via CLAUDE.md, toda tarefa de escrita de código abre com uma declaração de conformidade nomeando o exemplar seguido e os DONTs evitados.

Especificação de Saída

• .ai-style-rules.md na raiz do projeto (com impressão digital de commit + nível de escala no cabeçalho)
• Opcionalmente CLAUDE.md com referência @.ai-style-rules.md
• Logs de evolução anexados como entradas ### [AAAA-MM-DD] Log de Evolução de Estilo

Anti-Padrões

• FALHA: NÃO pule a etapa de medição de escala — amostrar um projeto de 30 arquivos "o subalimenta"; escanear completamente um repositório de 5.000 arquivos explode
• FALHA: NÃO acumule múltiplas perguntas de conflito de uma vez — o interrogatório é estritamente um de cada vez
• FALHA: NÃO sobrescreva regras antigas no modo incremental — sempre anexe logs de evolução
• FALHA: NÃO use o padrão "gancho duro" sem perguntar — a força de aplicação é decisão do usuário
• FALHA: NÃO julgue sintaxe ou qualidade de stack tecnológico — esta habilidade alinha apenas meta-arquitetura
• FALHA: NÃO copie bugs de arquivos exemplares — reutilize estrutura, sinalize defeitos

Melhores Práticas

• Anuncie o modo detectado (primeira vez vs incremental) e o nível de escala em uma linha antes de escanear
• Para projetos grandes, leia resumos --stat primeiro, depois Read direcionado em arquivos suspeitos
• Deixe o limite de sinal lidar com ruído — uma divisão de nomenclatura 843 contra 8 deve se resolver automaticamente sem interrupção do usuário
• Quando em dúvida sobre a força do sinal, incline-se a perguntar
• O gancho suave CLAUDE.md (@.ai-style-rules.md) é geralmente suficiente; gancho duro apenas se o usuário quiser aplicação mecânica

Habilidades Relacionadas

• init — inicializar um novo CLAUDE.md com documentação da base de código
• code-review — revisar diffs quanto a correção e problemas de estilo
• simplify — revisar código quanto a oportunidades de reutilização e simplificação

Exemplos

1. Primeira integração

   • Usuário: "Ajude-me a integrar IA a esta base de código antiga sem mudar seu estilo."
   • Ação: Executar Branch A varredura completa → medir escala → escanear 4 dimensões → interrogar conflitos → gerar .ai-style-rules.md → oferecer força de gancho (suave/duro/nenhum).

2. Atualização incremental após mudanças na equipe

   • Usuário: "Adicionamos um novo módulo; mantenha as regras de estilo existentes intactas."
   • Ação: Executar Branch B checagem incremental → comparar deltas do Git com regras registradas → interrogar novos conflitos → anexar log de evolução sem sobrescrever.

3. Aplicando DONTs via CLAUDE.md

   • Usuário: "Garanta que todo novo código permaneça consistente com as regras do projeto."
   • Ação: Gancho suave instalado → .ai-style-rules.md carregado automaticamente a cada sessão → toda tarefa de escrita de código abre com declaração de conformidade, reutilizando padrões exemplares e evitando DONTs.