/si:promote — Promover Aprendizados para Regras
Move um padrão comprovado da memória automática 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> # Detecta automaticamente o melhor alvo
/si:promote <padrão> --target claude.md # Promove para CLAUDE.md
/si:promote <padrão> --target rules/testing.md # Promove 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
Analise a descrição do usuário. Se vaga, faça uma pergunta esclarecedora:
- "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 memória automática
# Buscar no 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"
Mostre as entradas correspondentes e confirme se são o que o usuário quer.
Passo 3: Determinar o alvo correto
| Escopo do padrão | Alvo | Exemplo |
|---|---|---|
| Aplica-se a todo o projeto | ./CLAUDE.md | "Use pnpm, não npm" |
| Aplica-se a tipos de arquivo específicos | .claude/rules/<tópico>.md | "Handlers de API precisam de validação" |
| Aplica-se a todos os seus projetos | ~/.claude/CLAUDE.md | "Prefira tratamento explícito de erros" |
Se o usuário não especificou um alvo, recomende um com base no escopo.
Passo 4: Destilar em uma regra concisa
Transforme 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 pnpm workspaces. Quando tentei npm install, falhou. O arquivo de lock é pnpm-lock.yaml. Deve-se usar pnpm install para dependências.
Depois (CLAUDE.md — prescritivo):
## Build e Dependências
- Gerenciador de pacotes: pnpm (não npm). Use `pnpm install`.
Regras para destilação:
- Uma regra por linha quando possível
- Voz imperativa ("Use X", "Sempre Y", "Nunca Z")
- Inclua o comando ou exemplo, não apenas o conceito
- Sem contexto prévio — apenas a instrução
Passo 5: Escrever no alvo
Para CLAUDE.md:
- Leia o CLAUDE.md existente
- Encontre a seção apropriada (ou crie uma)
- Adicione a nova regra sob o cabeçalho correto
- Se o arquivo exceder 200 linhas, sugira usar
.claude/rules/em vez disso
Para .claude/rules/:
- Crie o arquivo se ele não existir
- Adicione frontmatter YAML com
pathsse for escopado - Escreva o conteúdo da regra
---
paths:
- "src/api/**/*.ts"
- "tests/api/**/*"
---
# Regras de Desenvolvimento da 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 handler
Passo 6: Limpar a memória automática
Após a promoção, remova ou marque a entrada original no MEMORY.md:
# Mostra o que será removido
grep -n "<padrão>" "$MEMORY_DIR/MEMORY.md"
Peça ao usuário para confirmar a remoção. Em seguida, edite o MEMORY.md para remover a entrada promovida. Isso libera espaço para novos aprendizados.
Passo 7: Confirmar
✅ Promovido para {{alvo}}
Regra: "{{regra destilada}}"
Fonte: MEMORY.md linha {{n}} (removida)
MEMORY.md: {{linhas}}/200 linhas restantes
O padrão agora é uma instrução aplicada. Claude o seguirá em todas as sessões futuras.
Guia de Decisão de Promoção
Promova quando:
- O padrão apareceu 3+ vezes na memória automática
- Você corrigiu o Claude sobre isso mais de uma vez
- É uma convenção do projeto que qualquer contribuidor deveria saber
- Previne um erro recorrente
Não promova quando:
- É uma nota de debug única (deixe na memória automática)
- É um 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/
| Use CLAUDE.md para | Use .claude/rules/ para |
|---|---|
| Regras globais do projeto | Padrões específicos de tipo de arquivo |
| Comandos de build | Convenções de teste |
| Decisões de arquitetura | Regras de design de API |
| Convenções de equipe | Peculiaridades específicas de framework |
Dicas
- Mantenha o CLAUDE.md abaixo de 200 linhas — use rules/ para o excedente
- 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 for mais relevante