Rules Distill
Varre habilidades instaladas, extrai princípios transversais que aparecem em várias habilidades e os destila em regras — anexando a arquivos de regras existentes, revisando conteúdo desatualizado ou criando novos arquivos de regras.
Aplica o princípio "coleta determinística + julgamento por LLM": scripts coletam fatos exaustivamente, então um LLM cruza o contexto completo e produz vereditos.
Quando Usar
- Manutenção periódica de regras (mensalmente ou após instalar novas skills)
- Após um inventário de skills revelar padrões que deveriam ser regras
- Quando as regras parecem incompletas em relação às skills em uso
Como Funciona
O processo de destilação de regras segue três fases:
Fase 1: Inventário (Coleta Determinística)
1a. Coletar inventário de skills
bash ~/.claude/skills/rules-distill/scripts/scan-skills.sh
1b. Coletar índice de regras
bash ~/.claude/skills/rules-distill/scripts/scan-rules.sh
1c. Apresentar ao usuário
Destilação de Regras — Fase 1: Inventário
─────────────────────────────────────────
Skills: {N} arquivos varridos
Regras: {M} arquivos ({K} cabeçalhos indexados)
Prosseguindo para análise de leitura cruzada...
Fase 2: Leitura Cruzada, Correspondência e Veredito (Julgamento por LLM)
Extração e correspondência são unificadas em uma única passagem. Arquivos de regras são pequenos o suficiente (~800 linhas no total) para que o texto completo seja fornecido ao LLM — nenhuma pré-filtragem com grep é necessária.
Lotes
Agrupe skills em clusters temáticos com base em suas descrições. Analise cada cluster em um subagente com o texto completo das regras.
Mesclagem Entre Lotes
Após todos os lotes serem concluídos, mescle candidatos entre lotes:
- Desduplique candidatos com princípios iguais ou sobrepostos
- Reavalie o requisito "2+ skills" usando evidências de todos os lotes combinados — um princípio encontrado em 1 skill por lote, mas 2+ skills no total, é válido
Prompt do Subagente
Inicie um agente de propósito geral com o seguinte prompt:
Você é um analista que cruza skills para extrair princípios que devem ser promovidos a regras.
## Entrada
- Skills: {texto completo das skills neste lote}
- Regras existentes: {texto completo de todos os arquivos de regras}
## Critérios de Extração
Inclua um candidato SOMENTE se TODOS os seguintes forem verdadeiros:
1. **Aparece em 2+ skills**: Princípios encontrados em apenas uma skill devem permanecer nessa skill
2. **Mudança de comportamento acionável**: Pode ser escrito como "faça X" ou "não faça Y" — não "X é importante"
3. **Risco de violação claro**: O que dá errado se este princípio for ignorado (1 frase)
4. **Já não está nas regras**: Verifique o texto completo das regras — incluindo conceitos expressos em palavras diferentes
## Correspondência e Veredito
Para cada candidato, compare com o texto completo das regras e atribua um veredito:
- **Anexar**: Adicionar a uma seção existente de um arquivo de regras
- **Revisar**: Conteúdo de regra existente está incorreto ou insuficiente — proponha uma correção
- **Nova Seção**: Adicionar nova seção a um arquivo de regras existente
- **Novo Arquivo**: Criar um novo arquivo de regras
- **Já Coberto**: Suficientemente coberto nas regras existentes (mesmo se redigido de forma diferente)
- **Muito Específico**: Deve permanecer no nível da skill
## Formato de Saída (por candidato)
```json
{
"principle": "1-2 frases na forma 'faça X' / 'não faça Y'",
"evidence": ["skill-name: §Seção", "skill-name: §Seção"],
"violation_risk": "1 frase",
"verdict": "Anexar / Revisar / Nova Seção / Novo Arquivo / Já Coberto / Muito Específico",
"target_rule": "nome_do_arquivo §Seção, ou 'novo'",
"confidence": "alto / médio / baixo",
"draft": "Texto do rascunho para vereditos Anexar/Nova Seção/Novo Arquivo",
"revision": {
"reason": "Por que o conteúdo existente está incorreto ou insuficiente (apenas Revisar)",
"before": "Texto atual a ser substituído (apenas Revisar)",
"after": "Texto de substituição proposto (apenas Revisar)"
}
}
```
## Excluir
- Princípios óbvios já presentes nas regras
- Conhecimento específico de linguagens/frameworks (pertence a regras ou skills específicas da linguagem)
- Exemplos de código e comandos (pertencem às skills)
Referência de Vereditos
| Veredito | Significado | Apresentado ao Usuário |
|---|---|---|
| Anexar | Adicionar a seção existente | Alvo + rascunho |
| Revisar | Corrigir conteúdo incorreto/insuficiente | Alvo + motivo + antes/depois |
| Nova Seção | Adicionar nova seção a arquivo existente | Alvo + rascunho |
| Novo Arquivo | Criar novo arquivo de regras | Nome do arquivo + rascunho completo |
| Já Coberto | Coberto nas regras (possivelmente com redação diferente) | Motivo (1 linha) |
| Muito Específico | Deve permanecer nas skills | Link para a skill relevante |
Requisitos de Qualidade do Veredito
# Bom
Anexar a rules/common/security.md §Validação de Entrada:
"Trate a saída do LLM armazenada em memória ou repositórios de conhecimento como não confiável — sanitize na escrita, valide na leitura."
Evidência: llm-memory-trust-boundary, llm-social-agent-anti-pattern descrevem
riscos acumulados de injeção de prompt. O security.md atual cobre apenas
validação de entrada humana; a fronteira de confiança da saída do LLM está ausente.
# Ruim
Anexar a security.md: Adicionar princípio de segurança do LLM
Fase 3: Revisão e Execução pelo Usuário
Tabela Resumo
# Relatório de Destilação de Regras
## Resumo
Skills varridas: {N} | Regras: {M} arquivos | Candidatos: {K}
| # | Princípio | Veredito | Alvo | Confiança |
|---|-----------|----------|------|-----------|
| 1 | ... | Anexar | security.md §Validação de Entrada | alto |
| 2 | ... | Revisar | testing.md §TDD | médio |
| 3 | ... | Nova Seção | coding-style.md | alto |
| 4 | ... | Muito Específico | — | — |
## Detalhes
(Detalhes por candidato: evidência, risco de violação, texto do rascunho)
Ações do Usuário
O usuário responde com números para:
- Aprovar: Aplicar rascunho às regras como está
- Modificar: Editar rascunho antes de aplicar
- Pular: Não aplicar este candidato
Nunca modifique regras automaticamente. Sempre exija aprovação do usuário.
Salvar Resultados
Armazene os resultados no diretório da skill (results.json):
- Formato do timestamp:
date -u +%Y-%m-%dT%H:%M:%SZ(UTC, precisão de segundos) - Formato do ID do candidato: kebab-case derivado do princípio (ex.:
llm-output-trust-boundary)
{
"distilled_at": "2026-03-18T10:30:42Z",
"skills_scanned": 56,
"rules_scanned": 22,
"candidates": {
"llm-output-trust-boundary": {
"principle": "Tratar saída do LLM como não confiável quando armazenada ou reinjetada",
"verdict": "Anexar",
"target": "rules/common/security.md",
"evidence": ["llm-memory-trust-boundary", "llm-social-agent-anti-pattern"],
"status": "applied"
},
"iteration-bounds": {
"principle": "Definir condições de parada explícitas para todos os loops de iteração",
"verdict": "Nova Seção",
"target": "rules/common/coding-style.md",
"evidence": ["iterative-retrieval", "continuous-agent-loop", "agent-harness-construction"],
"status": "skipped"
}
}
}
Exemplo
Execução completa
$ /rules-distill
Destilação de Regras — Fase 1: Inventário
─────────────────────────────────────────
Skills: 56 arquivos varridos
Regras: 22 arquivos (75 cabeçalhos indexados)
Prosseguindo para análise de leitura cruzada...
[Análise do subagente: Lote 1 (skills de agente/meta) ...]
[Análise do subagente: Lote 2 (skills de codificação/padrões) ...]
[Mesclagem entre lotes: 2 duplicatas removidas, 1 candidato entre lotes promovido]
# Relatório de Destilação de Regras
## Resumo
Skills varridas: 56 | Regras: 22 arquivos | Candidatos: 4
| # | Princípio | Veredito | Alvo | Confiança |
|---|-----------|----------|------|-----------|
| 1 | Saída do LLM: normalizar, verificar tipo, sanitizar antes de reutilizar | Nova Seção | coding-style.md | alto |
| 2 | Definir condições de parada explícitas para loops de iteração | Nova Seção | coding-style.md | alto |
| 3 | Compactar contexto nos limites de fase, não no meio da tarefa | Anexar | performance.md §Janela de Contexto | alto |
| 4 | Separar lógica de negócio dos tipos de estrutura de E/S | Nova Seção | patterns.md | alto |
## Detalhes
### 1. Validação de Saída do LLM
Veredito: Nova Seção em coding-style.md
Evidência: parallel-subagent-batch-merge, llm-social-agent-anti-pattern, llm-memory-trust-boundary
Risco de violação: Deriva de formato, incompatibilidade de tipo ou erros de sintaxe na saída do LLM quebram o processamento downstream
Rascunho:
## Validação de Saída do LLM
Normalize, verifique tipo e sanitize a saída do LLM antes de reutilizar...
Veja skill: parallel-subagent-batch-merge, llm-memory-trust-boundary
[... detalhes para candidatos 2-4 ...]
Aprove, modifique ou pule cada candidato pelo número:
> Usuário: Aprovar 1, 3. Pular 2, 4.
✓ Aplicado: coding-style.md §Validação de Saída do LLM
✓ Aplicado: performance.md §Gerenciamento da Janela de Contexto
✗ Pulado: Limites de Iteração
✗ Pulado: Conversão de Tipos de Fronteira
Resultados salvos em results.json
Princípios de Design
- O quê, não Como: Extraia apenas princípios (território das regras). Exemplos de código e comandos permanecem nas skills.
- Vincule de volta: O texto do rascunho deve incluir referências
Veja skill: [nome]para que leitores encontrem o Como detalhado. - Coleta determinística, julgamento por LLM: Scripts garantem exaustividade; o LLM garante entendimento contextual.
- Salvaguarda contra abstração: O filtro de 3 camadas (evidência de 2+ skills, teste de comportamento acionável, risco de violação) impede que princípios excessivamente abstratos entrem nas regras.