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 posteriormente processá-los em correções, 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 corrige você	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
Abordagem melhor encontrada	Registrar em .learnings/LEARNINGS.md com categoria best_practice
Simplificar/Endurecer padrões recorrentes	Registrar/atualizar .learnings/LEARNINGS.md com Source: simplify-and-harden e uma Pattern-Key estável
Semelhante a entrada existente	Vincular com See Also, considerar aumento de 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

Refeito para openclaw a partir do repositório original: https://github.com/pskoett/pskoett-ai-skills - https://github.com/pskoett/pskoett-ai-skills/tree/main/skills/self-improvement

Estrutura do Workspace

O OpenClaw injeta estes arquivos em cada sessão:

~/.openclaw/workspace/
├── AGENTS.md          # Fluxos de trabalho multi-agente, 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ários
│   └── YYYY-MM-DD.md
└── .learnings/        # Arquivos de log desta habilidade
    ├── LEARNINGS.md
    ├── ERRORS.md
    └── FEATURE_REQUESTS.md

Criar Arquivos de Aprendizado

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

Em seguida, crie os arquivos de log (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 mostram amplamente aplicáveis, promova-os para arquivos do workspace:

Tipo de Aprendizado	Promover para	Exemplo
Padrões comportamentais	SOUL.md	"Seja conciso, evite avisos"
Melhorias de fluxo de trabalho	AGENTS.md	"Gere 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 o transcript de outra sessão
• sessions_send — Enviar um aprendizado para outra sessão
• sessions_spawn — Gerar um subagente para trabalho em segundo plano

Opcional: Ativar Gancho

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

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

# Ativar
ganchos activate 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 modelos de assets/ ou crie arquivos com cabeçalhos.

Adicionar referência aos arquivos de agente AGENTS.md, CLAUDE.md ou .github/copilot-instructions.md para lembrar-se de registrar aprendizados. (esta é uma alternativa aos lembretes baseados em gancho)

Fluxo de Trabalho de Autoaperfeiçoamento

Quando erros ou correções ocorrerem:

1. Registre em .learnings/ERRORS.md, LEARNINGS.md ou FEATURE_REQUESTS.md
2. Revise e promova aprendizados amplamente aplicáveis para:
   • CLAUDE.md - fatos e convenções do projeto
   • AGENTS.md - fluxos de trabalho e automação
   • .github/copilot-instructions.md - contexto do Copilot

Formato de Registro

Entrada de Aprendizado

Adicione a .learnings/LEARNINGS.md:

## [LRN-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 de 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_usuário
- Arquivos Relacionados: caminho/para/arquivo.ext
- Tags: tag1, tag2
- Veja Também: LRN-20250110-001 (se relacionado a entrada existente)
- Chave-Padrão: simplify.dead_code | harden.validation_input (opcional, para rastreamento de padrão recorrente)
- Contagem-Reincidência: 1 (opcional)
- Primeira-Visualização: 2025-01-15 (opcional)
- Última-Visualização: 2025-01-15 (opcional)

---

Entrada de Erro

Adicione 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 relevante

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

### 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

Adicione a .learnings/FEATURE_REQUESTS.md:

## [FEAT-YYYYMMDD-XXX] nome_da_funcionalidade

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

### Funcionalidade 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édia | complexa

### 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: LRN (aprendizado), ERR (erro), FEAT (funcionalidade)
• YYYYMMDD: Data atual
• XXX: Número sequencial ou 3 caracteres aleatórios (ex.: 001, A7B)

Exemplos: LRN-20250115-001, ERR-20250115-A3F, FEAT-20250115-002

Resolvendo Entradas

Quando um problema for 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 - Ativamente sendo trabalhado
• nao_vai_corrigir - Decidido não abordar (adicione motivo nas notas de Resolução)
• promovido - Elevado para CLAUDE.md, AGENTS.md ou .github/copilot-instructions.md

Promovendo para Memória do Projeto

Quando um aprendizado é amplamente aplicável (não é uma correção pontual), 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 e convenções do projeto para 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 alvo (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 (verboso):

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

No CLAUDE.md (conciso):

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

Aprendizado (verboso):

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

No 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 recorrendo
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 ao AGENTS.md)
   • Problema arquitetural (→ criar ticket de dívida técnica)

Fluxo de Simplificação e Endurecimento

Use este fluxo de trabalho para ingerir padrões recorrentes da habilidade simplify-and-harden e transformá-los em orientação de prompt durável.

Fluxo de Ingestão

1. Leia simplify_and_harden.learning_loop.candidates do resumo da tarefa.
2. Para cada candidato, use pattern_key como a chave de desduplicação estável.
3. Pesquise .learnings/LEARNINGS.md por uma entrada existente com essa chave:
   • grep -n "Chave-Padrão: <chave_padrao>" .learnings/LEARNINGS.md
4. Se encontrado:
   • Incremente Contagem-Reincidência
   • Atualize Última-Visualização
   • Adicione links Veja Também para entradas/tarefas relacionadas
5. Se não encontrado:
   • Crie uma nova entrada LRN-...
   • Defina Fonte: simplify-and-harden
   • Defina Chave-Padrão, Contagem-Reincidência: 1, e Primeira-Visualização/Última-Visualização

Regra de Promoção (Feedback do Prompt do Sistema)

Promova padrões recorrentes para arquivos de contexto/prompt do sistema do agente quando todos os itens abaixo forem verdadeiros:

• Contagem-Reincidência >= 3
• Visto em pelo menos 2 tarefas distintas
• Ocorreu dentro de uma janela de 30 dias

Alvos de promoção:

• CLAUDE.md
• AGENTS.md
• .github/copilot-instructions.md
• SOUL.md / TOOLS.md para orientação em nível de workspace OpenClaw quando aplicável

Escreva regras promovidas como regras curtas de prevenção (o que fazer antes/durante a codificação), não longos relatos de incidentes.

Revisão Periódica

Revise .learnings/ em pontos de interrupção 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 quando notar:

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

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

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

• "Você pode também..."
• "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 não-zero
• Exceção ou stack trace
• Saída ou comportamento inesperado
• Timeout 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 cliente
backend	API, serviços, código 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 está 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 correções
5. Sugira correções concretas - não apenas "investigar"
6. Use categorias consistentes - permite filtragem
7. Promova agressivamente - em caso de dúvida, adicione ao CLAUDE.md ou .github/copilot-instructions.md
8. Revise regularmente - aprendizados desatualizados 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 Gancho

Habilite 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)

...