Habilidade de Autoaperfeiçoamento

O que Habilidade de Autoaperfeiçoamento faz?

Registre aprendizados e erros em arquivos markdown para melhoria contínua. Agentes de codificação podem processá-los posteriormente para corrigir problemas, e aprendizados importantes são promovidos para a memória do projeto.

Referência Rápida

Situação	Ação
Comando/operação falha	Registrar em .learnings/ERRORS.md
Usuário te corrige	Registrar em .learnings/LEARNINGS.md com categoria correction
Usuário quer funcionalidade ausente	Registrar em .learnings/FEATURE_REQUESTS.md
API/ferramenta externa falha	Registrar em .learnings/ERRORS.md com detalhes de integração
Conhecimento estava desatualizado	Registrar em .learnings/LEARNINGS.md com categoria knowledge_gap
Encontrou abordagem melhor	Registrar em .learnings/LEARNINGS.md com categoria best_practice
Semelhante a entrada existente	Vincular com **Veja Também**, considerar aumentar prioridade
Aprendizado amplamente aplicável	Promover para CLAUDE.md, AGENTS.md, e/ou .github/copilot-instructions.md
Melhorias de fluxo de trabalho	Promover para AGENTS.md (workspace OpenClaw)
Armadilhas de ferramentas	Promover para TOOLS.md (workspace OpenClaw)
Padrões comportamentais	Promover para SOUL.md (workspace OpenClaw)

Configuração OpenClaw (Recomendado)

OpenClaw é a plataforma principal para esta habilidade. Ela usa injeção de prompt baseada em workspace com carregamento automático de habilidades.

Instalação

Via ClawdHub (recomendado):

clawdhub install self-improving-agent

Manual:

git clone https://github.com/peterskoett/self-improving-agent.git ~/.openclaw/skills/self-improving-agent

Estrutura do Workspace

O OpenClaw injeta estes arquivos em toda sessão:

~/.openclaw/workspace/
├── AGENTS.md          # Fluxos de trabalho multiagente, padrões de delegação
├── SOUL.md            # Diretrizes comportamentais, personalidade, princípios
├── TOOLS.md           # Capacidades de ferramentas, armadilhas de integração
├── MEMORY.md          # Memória de longo prazo (apenas sessão principal)
├── memory/            # Arquivos de memória diária
│   └── YYYY-MM-DD.md
└── .learnings/        # Arquivos de registro desta habilidade
    ├── LEARNINGS.md
    ├── ERRORS.md
    └── FEATURE_REQUESTS.md

Criar Arquivos de Aprendizado

mkdir -p ~/.openclaw/workspace/.learnings

Em seguida, crie os arquivos de registro (ou copie de assets/):

• LEARNINGS.md — correções, lacunas de conhecimento, melhores práticas
• ERRORS.md — falhas de comando, exceções
• FEATURE_REQUESTS.md — funcionalidades solicitadas pelo usuário

Alvos de Promoção

Quando os aprendizados se mostrarem amplamente aplicáveis, promova-os para arquivos do workspace:

Tipo de Aprendizado	Promover Para	Exemplo
Padrões comportamentais	SOUL.md	"Seja conciso, evite ressalvas"
Melhorias de fluxo de trabalho	AGENTS.md	"Crie subagentes para tarefas longas"
Armadilhas de ferramentas	TOOLS.md	"Git push precisa de autenticação configurada primeiro"

Comunicação Entre Sessões

O OpenClaw fornece ferramentas para compartilhar aprendizados entre sessões:

• sessions_list — Visualizar sessões ativas/recentes
• sessions_history — Ler a transcrição de outra sessão
• sessions_send — Enviar um aprendizado para outra sessão
• sessions_spawn — Criar um subagente para trabalho em segundo plano

Opcional: Ativar Gancho

Para lembretes automáticos no início da sessão:

# Copiar gancho para o diretório de ganchos do OpenClaw
cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement

# Ativá-lo
openclaw hooks enable self-improvement

Consulte references/openclaw-integration.md para detalhes completos.

---

Configuração Genérica (Outros Agentes)

Para Claude Code, Codex, Copilot ou outros agentes, crie .learnings/ no seu projeto:

mkdir -p .learnings

Copie os modelos de assets/ ou crie arquivos com cabeçalhos.

Formato de Registro

Entrada de Aprendizado

Acrescente a .learnings/LEARNINGS.md:

## [APR-YYYYMMDD-XXX] categoria

**Registrado**: timestamp ISO-8601
**Prioridade**: baixa | média | alta | crítica
**Status**: pendente
**Área**: frontend | backend | infra | testes | docs | config

### Resumo
Descrição em uma linha do que foi aprendido

### Detalhes
Contexto completo: o que aconteceu, o que estava errado, o que está correto

### Ação Sugerida
Correção ou melhoria específica a ser feita

### Metadados
- Fonte: conversa | erro | feedback_do_usuário
- Arquivos Relacionados: caminho/para/arquivo.ext
- Tags: tag1, tag2
- Veja Também: APR-20250110-001 (se relacionado a entrada existente)

---

Entrada de Erro

Acrescente a .learnings/ERRORS.md:

## [ERR-YYYYMMDD-XXX] nome_da_habilidade_ou_comando

**Registrado**: timestamp ISO-8601
**Prioridade**: alta
**Status**: pendente
**Área**: frontend | backend | infra | testes | docs | config

### Resumo
Breve descrição do que falhou

### Erro

Mensagem de erro real ou saída

### Contexto
- Comando/operação tentada
- Entrada ou parâmetros usados
- Detalhes do ambiente, se relevantes

### Correção Sugerida
Se identificável, o que pode resolver

### Metadados
- Reproduzível: sim | não | desconhecido
- Arquivos Relacionados: caminho/para/arquivo.ext
- Veja Também: ERR-20250110-001 (se recorrente)

---

Entrada de Solicitação de Funcionalidade

Acrescente a .learnings/FEATURE_REQUESTS.md:

## [FUNC-YYYYMMDD-XXX] nome_da_capacidade

**Registrado**: timestamp ISO-8601
**Prioridade**: média
**Status**: pendente
**Área**: frontend | backend | infra | testes | docs | config

### Capacidade Solicitada
O que o usuário queria fazer

### Contexto do Usuário
Por que ele precisava, qual problema estava resolvendo

### Estimativa de Complexidade
simples | médio | complexo

### Implementação Sugerida
Como isso poderia ser construído, o que poderia estender

### Metadados
- Frequência: primeira_vez | recorrente
- Funcionalidades Relacionadas: nome_da_funcionalidade_existente

---

Geração de ID

Formato: TIPO-YYYYMMDD-XXX

• TIPO: APR (aprendizado), ERR (erro), FUNC (funcionalidade)
• YYYYMMDD: Data atual
• XXX: Número sequencial ou 3 caracteres aleatórios (ex.: 001, A7B)

Exemplos: APR-20250115-001, ERR-20250115-A3F, FUNC-20250115-002

Resolvendo Entradas

Quando um problema é corrigido, atualize a entrada:

1. Altere **Status**: pendente → **Status**: resolvido
2. Adicione bloco de resolução após Metadados:

### Resolução
- **Resolvido**: 2025-01-16T09:00:00Z
- **Commit/PR**: abc123 ou #42
- **Notas**: Breve descrição do que foi feito

Outros valores de status:

• em_andamento - Sendo trabalhado ativamente
• nao_vai_corrigir - Decidiu não abordar (adicione motivo nas notas de Resolução)
• promovido - Elevado para CLAUDE.md, AGENTS.md, ou .github/copilot-instructions.md

Promovendo para a Memória do Projeto

Quando um aprendizado é amplamente aplicável (não é uma correção única), promova-o para a memória permanente do projeto.

Quando Promover

• O aprendizado se aplica a vários arquivos/funcionalidades
• Conhecimento que qualquer contribuidor (humano ou IA) deve saber
• Previne erros recorrentes
• Documenta convenções específicas do projeto

Alvos de Promoção

Alvo	O Que Pertence Lá
CLAUDE.md	Fatos do projeto, convenções, armadilhas para todas as interações Claude
AGENTS.md	Fluxos de trabalho específicos de agente, padrões de uso de ferramentas, regras de automação
.github/copilot-instructions.md	Contexto do projeto e convenções para o GitHub Copilot
SOUL.md	Diretrizes comportamentais, estilo de comunicação, princípios (workspace OpenClaw)
TOOLS.md	Capacidades de ferramentas, padrões de uso, armadilhas de integração (workspace OpenClaw)

Como Promover

1. Destile o aprendizado em uma regra ou fato conciso
2. Adicione à seção apropriada no arquivo de destino (crie o arquivo se necessário)
3. Atualize a entrada original:
   • Altere **Status**: pendente → **Status**: promovido
   • Adicione **Promovido**: CLAUDE.md, AGENTS.md, ou .github/copilot-instructions.md

Exemplos de Promoção

Aprendizado (detalhado):

O projeto usa workspaces pnpm. Tentativa de npm install falhou. O arquivo de lock é pnpm-lock.yaml. Deve-se usar pnpm install.

Em CLAUDE.md (conciso):

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

Aprendizado (detalhado):

Ao modificar endpoints de API, é necessário regenerar o cliente TypeScript. Esquecer isso causa incompatibilidades de tipo em tempo de execução.

Em AGENTS.md (acionável):

## Após Mudanças na API
1. Regenerar cliente: `pnpm run generate:api`
2. Verificar erros de tipo: `pnpm tsc --noEmit`

Detecção de Padrões Recorrentes

Se estiver registrando algo semelhante a uma entrada existente:

1. Pesquise primeiro: grep -r "palavra-chave" .learnings/
2. Vincule entradas: Adicione **Veja Também**: ERR-20250110-001 nos Metadados
3. Aumente a prioridade se o problema continuar recorrente
4. Considere correção sistêmica: Problemas recorrentes geralmente indicam:
   • Documentação ausente (→ promover para CLAUDE.md ou .github/copilot-instructions.md)
   • Automação ausente (→ adicionar a AGENTS.md)
   • Problema arquitetural (→ criar ticket de dívida técnica)

Revisão Periódica

Revise .learnings/ em pontos de parada naturais:

Quando Revisar

• Antes de iniciar uma nova tarefa importante
• Após concluir uma funcionalidade
• Ao trabalhar em uma área com aprendizados passados
• Semanalmente durante o desenvolvimento ativo

Verificação Rápida de Status

# Contar itens pendentes
grep -h "Status\*\*: pendente" .learnings/*.md | wc -l

# Listar itens pendentes de alta prioridade
grep -B5 "Prioridade\*\*: alta" .learnings/*.md | grep "^## \["

# Encontrar aprendizados para uma área específica
grep -l "Área\*\*: backend" .learnings/*.md

Ações de Revisão

• Resolver itens corrigidos
• Promover aprendizados aplicáveis
• Vincular entradas relacionadas
• Escalar problemas recorrentes

Gatilhos de Detecção

Registre automaticamente ao perceber:

Correções (→ aprendizado com categoria correction):

• "Não, isso não está certo..."
• "Na verdade, deveria ser..."
• "Você está errado sobre..."
• "Isso está desatualizado..."

Solicitações de Funcionalidade (→ solicitação de funcionalidade):

• "Você também pode..."
• "Gostaria que você pudesse..."
• "Existe uma maneira de..."
• "Por que você não pode..."

Lacunas de Conhecimento (→ aprendizado com categoria knowledge_gap):

• Usuário fornece informações que você não sabia
• Documentação que você consultou está desatualizada
• Comportamento da API difere do seu entendimento

Erros (→ entrada de erro):

• Comando retorna código de saída diferente de zero
• Exceção ou rastreamento de pilha
• Saída ou comportamento inesperado
• Tempo limite ou falha de conexão

Diretrizes de Prioridade

Prioridade	Quando Usar
crítica	Bloqueia funcionalidade principal, risco de perda de dados, problema de segurança
alta	Impacto significativo, afeta fluxos de trabalho comuns, problema recorrente
média	Impacto moderado, solução alternativa existe
baixa	Pequeno inconveniente, caso extremo, bom ter

Tags de Área

Use para filtrar aprendizados por região do código:

Área	Escopo
frontend	UI, componentes, código do lado do cliente
backend	API, serviços, código do lado do servidor
infra	CI/CD, implantação, Docker, nuvem
testes	Arquivos de teste, utilitários de teste, cobertura
docs	Documentação, comentários, READMEs
config	Arquivos de configuração, ambiente, configurações

Melhores Práticas

1. Registre imediatamente - o contexto é mais fresco logo após o problema
2. Seja específico - agentes futuros precisam entender rapidamente
3. Inclua etapas de reprodução - especialmente para erros
4. Vincule arquivos relacionados - facilita as correções
5. Sugira correções concretas - não apenas "investigue"
6. Use categorias consistentes - permite filtragem
7. Promova agressivamente - na dúvida, adicione a CLAUDE.md ou .github/copilot-instructions.md
8. Revise regularmente - aprendizados antigos perdem valor

Opções de Gitignore

Manter aprendizados localmente (por desenvolvedor):

.learnings/

Rastrear aprendizados no repositório (para toda a equipe): Não adicione ao .gitignore - os aprendizados se tornam conhecimento compartilhado.

Híbrido (rastrear modelos, ignorar entradas):

.learnings/*.md
!.learnings/.gitkeep

Integração de Ganchos

Ative lembretes automáticos através de ganchos de agente. Isso é opt-in - você deve configurar explicitamente os ganchos.

Configuração Rápida (Claude Code / Codex)

Crie .claude/settings.json no seu projeto:

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/activator.sh"
      }]
    }]
  }
}

Isso injeta um lembrete de avaliação de aprendizado após cada prompt (~50-100 tokens de custo adicional).

Configuração Completa (Com Detecção de Erros)

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/activator.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/error-detector.sh"
      }]
    }]
  }
}

Scripts de Gancho Disponíveis

Script	Tipo de Gancho	Propósito
scripts/activator.sh	UserPromptSubmit	Lembra de avaliar aprendizados após tarefas
scripts/error-detector.sh	PostToolUse (Bash)	Aciona em erros de comando

Consulte references/hooks-setup.md para configuração detalhada e solução de problemas.

Extração Automática de Habilidade

Quando um aprendizado é valioso o suficiente para se tornar uma habilidade reutilizável, extraia-o usando o auxiliar fornecido.

Critérios de Extração de Habilidade

Um aprendizado qualifica-se para extração de habilidade quando QUALQUER um destes se aplica:

Critério	Descrição
Recorrente	Possui links Veja Também para 2+ problemas semelhantes
Verificado	Status é resolvido com correção funcional
Não óbvio	Exigiu depuração/investigação real para ser descoberto
Amplamente aplicável	Não é específico do projeto; útil em várias bases de código
Sinalizado pelo usuário	Usuário diz "salve isso como uma habilidade" ou semelhante

Fluxo de Trabalho de Extração

1. Identifique o candidato: O aprendizado atende aos critérios de extração
2. Execute o auxiliar (ou crie manualmente):

   ./skills/self-improvement/scripts/extract-skill.sh nome-da-habilidade --dry-run
   ./skills/self-improvement/scripts/extract-skill.sh nome-da-habilidade
   

3. Personalize o SKILL.md: Preencha o modelo com o conteúdo do aprendizado
4. Atualize o aprendizado: Defina o status como promovido_para_habilidade, adicione Caminho-Habilidade
5. Verifique: Leia a habilidade em uma sessão nova para garantir que é autocontida

Extração Manual

Se preferir manual

...

[truncado para tradução]