Promote

/si:promote — Graduar Aprendizados para Regras

Move um padrão comprovado da auto-memória do Claude para o sistema de regras do projeto, onde se torna uma instrução aplicada em vez de uma nota de contexto.

Uso

/si:promote <descrição do padrão>                    # Detectar automaticamente o melhor alvo
/si:promote <padrão> --target claude.md             # Promover para CLAUDE.md
/si:promote <padrão> --target rules/testing.md      # Promover para regra escopada
/si:promote <padrão> --target rules/api.md --paths "src/api/**/*.ts"  # Escopado com caminhos

Fluxo de Trabalho

Passo 1: Entender o padrão

Analisar a descrição do usuário. Se for vaga, fazer uma pergunta de esclarecimento:

• "Qual comportamento específico o Claude deve seguir?"
• "Isso se aplica a todos os arquivos ou a caminhos específicos?"

Passo 2: Encontrar o padrão na auto-memória

# Pesquisar MEMORY.md por entradas relacionadas
MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory"
grep -ni "<palavras-chave>" "$MEMORY_DIR/MEMORY.md"

Mostrar as entradas correspondentes e confirmar que são o que o usuário quer dizer.

Passo 3: Determinar o alvo correto

Se o usuário não especificou um alvo, recomendar um com base no escopo.

Passo 4: Destilar em uma regra concisa

Transformar o aprendizado do formato de nota do MEMORY.md para o formato de instrução do CLAUDE.md:

Antes (MEMORY.md — descritivo):

O projeto usa workspaces pnpm. Quando tentei npm install falhou. O arquivo de lock é pnpm-lock.yaml. Devo usar pnpm install para dependências.

Depois (CLAUDE.md — prescritivo):

## Build & Dependências
- Gerenciador de pacotes: pnpm (não npm). Use `pnpm install`.

Regras para destilação:

• Uma linha por regra quando possível
• Voz imperativa ("Use X", "Sempre Y", "Nunca Z")
• Inclua o comando ou exemplo, não apenas o conceito
• Sem histórico — apenas a instrução

Passo 5: Escrever no alvo

Para CLAUDE.md:

1. Ler o CLAUDE.md existente
2. Encontrar a seção apropriada (ou criar uma)
3. Acrescentar a nova regra sob o cabeçalho correto
4. Se o arquivo exceder 200 linhas, sugerir usar .claude/rules/

Para .claude/rules/:

1. Criar o arquivo se não existir
2. Adicionar frontmatter YAML com paths se escopado
3. Escrever o conteúdo da regra

---
paths:
  - "src/api/**/*.ts"
  - "tests/api/**/*"
---

# Regras de Desenvolvimento de API

- Todos os endpoints devem validar a entrada com schemas Zod
- Use a classe `ApiError` para respostas de erro (não Error puro)
- Inclua comentários JSDoc OpenAPI nas funções de handler

Passo 6: Limpar a auto-memória

Após promover, remover ou marcar a entrada original no MEMORY.md:

# Mostrar o que será removido
grep -n "<padrão>" "$MEMORY_DIR/MEMORY.md"

Pedir confirmação ao usuário para remoção. Então editar o MEMORY.md para remover a entrada promovida. Isso libera espaço para novos aprendizados.

Passo 7: Confirmar

Promovido para {{alvo}}

Regra: "{{regra destilada}}"
Origem: MEMORY.md linha {{n}} (removida)
MEMORY.md: {{linhas}}/200 linhas restantes

O padrão agora é uma instrução aplicada. O Claude irá segui-la em todas as sessões futuras.

Guia de Decisão de Promoção

Promover quando:

• O padrão apareceu 3+ vezes na auto-memória
• Você corrigiu o Claude sobre isso mais de uma vez
• É uma convenção do projeto que qualquer colaborador deveria saber
• Previne um erro recorrente

Não promover quando:

• É uma nota de debugging pontual (deixar na auto-memória)
• É contexto específico de sessão (a memória de sessão cuida disso)
• Pode mudar em breve (ex.: durante uma migração)
• Já está coberto por regras existentes

CLAUDE.md vs .claude/rules/

Dicas

• Mantenha CLAUDE.md com menos de 200 linhas — use rules/ para overflow
• Uma regra por linha é mais fácil de manter do que parágrafos
• Inclua o comando concreto, não apenas o conceito
• Revise as regras promovidas trimestralmente — remova o que não é mais relevante