continuous-learning-v2

Aprendizado Contínuo v2.1 - Arquitetura Baseada em Instintos

Um sistema de aprendizado avançado que transforma suas sessões do Claude Code em conhecimento reutilizável através de "instintos" atômicos – pequenos comportamentos aprendidos com pontuação de confiança.

v2.1 adiciona instintos com escopo de projeto — padrões React ficam no seu projeto React, convenções Python ficam no seu projeto Python, e padrões universais (como "sempre validar entrada") são compartilhados globalmente.

Quando Ativar

• Configurando aprendizado automático de sessões do Claude Code
• Configurando extração de comportamento baseada em instintos via hooks
• Ajustando limites de confiança para comportamentos aprendidos
• Revisando, exportando ou importando bibliotecas de instintos
• Evoluindo instintos em habilidades, comandos ou agentes completos
• Gerenciando instintos com escopo de projeto vs. globais
• Promovendo instintos de escopo de projeto para global

Novidades na v2.1

Funcionalidade	v2.0	v2.1
Armazenamento	Global (~/.claude/homunculus/)	Escopo de projeto (${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<hash>/)
Escopo	Todos os instintos se aplicam em qualquer lugar	Escopo de projeto + global
Detecção	Nenhuma	URL remota do git / caminho do repositório
Promoção	N/A	Projeto → global quando visto em 2+ projetos
Comandos	4 (status/evolve/export/import)	6 (+promote/projects)
Cross-projeto	Risco de contaminação	Isolado por padrão

Novidades na v2 (vs v1)

Funcionalidade	v1	v2
Observação	Hook de parada (fim da sessão)	PreToolUse/PostToolUse (100% confiável)
Análise	Contexto principal	Agente em segundo plano (Haiku)
Granularidade	Habilidades completas	Instintos atômicos
Confiança	Nenhuma	0.3-0.9 ponderada
Evolução	Direto para habilidade	Instintos -> cluster -> habilidade/comando/agente
Compartilhamento	Nenhum	Exportar/importar instintos

O Modelo de Instinto

Um instinto é um pequeno comportamento aprendido:

---
id: preferir-estilo-funcional
gatilho: "ao escrever novas funções"
confianca: 0.7
dominio: "estilo-de-codigo"
fonte: "observacao-de-sessao"
escopo: projeto
project_id: "a1b2c3d4e5f6"
nome_projeto: "meu-app-react"
---

# Preferir Estilo Funcional

## Ação
Use padrões funcionais em vez de classes quando apropriado.

## Evidência
- Observadas 5 instâncias de preferência por padrão funcional
- Usuário corrigiu abordagem baseada em classe para funcional em 2025-01-15

Propriedades:

• Atômico — um gatilho, uma ação
• Ponderado por confiança — 0.3 = tentativo, 0.9 = quase certeza
• Marcado por domínio — estilo-de-codigo, teste, git, depuracao, fluxo-de-trabalho, etc.
• Baseado em evidências — rastreia quais observações o criaram
• Consciente de escopo — projeto (padrão) ou global

Como Funciona

Atividade da Sessão (em um repositório git)
      |
      | Hooks capturam prompts + uso de ferramentas (100% confiável)
      | + detectam contexto do projeto (git remote / caminho do repo)
      v
+---------------------------------------------+
|  projects/<hash-do-projeto>/observations.jsonl  |
|   (prompts, chamadas de ferramentas, resultados, projeto) |
+---------------------------------------------+
      |
      | Agente observador lê (em segundo plano, Haiku)
      v
+---------------------------------------------+
|          DETECÇÃO DE PADRÕES                   |
|   * Correções do usuário -> instinto           |
|   * Resoluções de erros -> instinto            |
|   * Fluxos de trabalho repetidos -> instinto   |
|   * Decisão de escopo: projeto ou global?      |
+---------------------------------------------+
      |
      | Cria/atualiza
      v
+---------------------------------------------+
|  projects/<hash-do-projeto>/instincts/personal/ |
|   * preferir-funcional.yaml (0.7) [projeto]   |
|   * usar-react-hooks.yaml (0.9) [projeto]     |
+---------------------------------------------+
|  instincts/personal/  (GLOBAL)               |
|   * sempre-validar-entrada.yaml (0.85) [global]|
|   * usar-grep-antes-editar.yaml (0.6) [global]|
+---------------------------------------------+
      |
      | /evolve clusters + /promote
      v
+---------------------------------------------+
|  projects/<hash>/evolved/ (escopo de projeto)  |
|  evolved/ (global)                           |
|   * commands/nova-funcionalidade.md          |
|   * skills/fluxo-teste.md                    |
|   * agents/especialista-refatoracao.md       |
+---------------------------------------------+

Detecção de Projeto

O sistema detecta automaticamente seu projeto atual:

1. Variável de ambiente CLAUDE_PROJECT_DIR (maior prioridade) -- homenageada como uma substituição explícita mesmo quando o diretório não é um repositório git (hash é gerado a partir do caminho absoluto)
2. git remote get-url origin -- hash para criar um ID de projeto portátil (o mesmo repositório em máquinas diferentes obtém o mesmo ID)
3. git rev-parse --show-toplevel -- fallback usando o caminho do repositório (específico da máquina)
4. Fallback global -- se nenhum projeto for detectado, os instintos vão para o escopo global

Cada projeto recebe um ID hash de 12 caracteres (ex.: a1b2c3d4e5f6). Um arquivo de registro em ${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects.json mapeia IDs para nomes legíveis.

Diretório de Dados

O continuous-learning-v2 armazena dados do observador fora de ~/.claude para que a proteção de caminho sensível do Claude Code não bloqueie gravações de instintos em segundo plano:

1. CLV2_HOMUNCULUS_DIR quando definido para um caminho absoluto
2. $XDG_DATA_HOME/ecc-homunculus
3. $HOME/.local/share/ecc-homunculus

Usuários existentes com dados em ~/.claude/homunculus podem migrar uma vez:

bash skills/continuous-learning-v2/scripts/migrate-homunculus.sh

Início Rápido

1. Ativar Hooks de Observação

Se instalado como um plugin (recomendado):

Nenhum bloco extra de hook settings.json é necessário. O Claude Code v2.1+ carrega automaticamente o plugin hooks/hooks.json, e observe.sh já está registrado lá.

Se você copiou anteriormente observe.sh em ~/.claude/settings.json, remova esse bloco PreToolUse / PostToolUse duplicado. Duplicar o hook do plugin causa execução dupla e erros de resolução de ${CLAUDE_PLUGIN_ROOT} porque essa variável só está disponível dentro de entradas hooks/hooks.json gerenciadas pelo plugin.

Se instalado manualmente em ~/.claude/skills, adicione isso ao seu ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
      }]
    }]
  }
}

2. Inicializar Estrutura de Diretórios

O sistema cria diretórios automaticamente no primeiro uso, mas você também pode criá-los manualmente:

# Diretórios globais
mkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/ecc-homunculus"/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}

# Diretórios de projeto são criados automaticamente quando o hook é executado pela primeira vez em um repositório git

3. Usar os Comandos de Instinto

/instinct-status     # Mostrar instintos aprendidos (projeto + global)
/evolve              # Agrupar instintos relacionados em habilidades/comandos
/instinct-export     # Exportar instintos para arquivo
/instinct-import     # Importar instintos de outros
/promote             # Promover instintos de projeto para escopo global
/projects            # Listar todos os projetos conhecidos e suas contagens de instintos

Comandos

Comando	Descrição
/instinct-status	Mostrar todos os instintos (escopo de projeto + global) com confiança
/evolve	Agrupar instintos relacionados em habilidades/comandos, sugerir promoções
/instinct-export	Exportar instintos (filtrável por escopo/domínio)
/instinct-import <arquivo>	Importar instintos com controle de escopo
/promote [id]	Promover instintos de projeto para escopo global
/projects	Listar todos os projetos conhecidos e suas contagens de instintos

Configuração

Edite config.json para controlar o observador em segundo plano:

{
  "version": "2.1",
  "observer": {
    "enabled": false,
    "run_interval_minutes": 5,
    "min_observations_to_analyze": 20
  }
}

Chave	Padrão	Descrição
observer.enabled	false	Habilitar o agente observador em segundo plano
observer.run_interval_minutes	5	Com que frequência o observador analisa observações
observer.min_observations_to_analyze	20	Mínimo de observações antes da análise ser executada

Outros comportamentos (captura de observação, limites de instinto, escopo de projeto, critérios de promoção) são configurados via padrões de código em instinct-cli.py e observe.sh.

Suporte a plataformas do observador

O observador em segundo plano requer WSL2, Linux ou macOS. No Windows nativo (Git Bash / MSYS2) ele inicia e relata sucesso, mas o processo é encerrado quando o hook de criação sai e seu Objeto de Job fecha, então nenhuma análise é executada — definir observer.enabled: true lá é efetivamente um no-op (veja issue #2489).

observe.sh detecta isso na próxima invocação do hook e escreve um aviso explicativo em observer-start.log quando o observador falha em sobreviver várias vezes seguidas.

Variável de ambiente	Padrão	Descrição
ECC_OBSERVER_NOSURVIVE_WARN_AFTER	3	Não-sobrevivências consecutivas antes do aviso ser registrado

Estrutura de Arquivos

${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/
+-- identity.json           # Seu perfil, nível técnico
+-- projects.json           # Registro: hash do projeto -> nome/caminho/remoto
+-- observations.jsonl      # Observações globais (fallback)
+-- instincts/
|   +-- personal/           # Instintos globais aprendidos automaticamente
|   +-- inherited/          # Instintos globais importados
+-- evolved/
|   +-- agents/             # Agentes globais gerados
|   +-- skills/             # Habilidades globais geradas
|   +-- commands/           # Comandos globais gerados
+-- projects/
    +-- a1b2c3d4e5f6/       # Hash do projeto (da URL remota do git)
    |   +-- project.json    # Espelho de metadados por projeto (id/nome/raiz/remoto)
    |   +-- observations.jsonl
    |   +-- observations.archive/
    |   +-- instincts/
    |   |   +-- personal/   # Aprendido automaticamente específico do projeto
    |   |   +-- inherited/  # Importado específico do projeto
    |   +-- evolved/
    |       +-- skills/
    |       +-- commands/
    |       +-- agents/
    +-- f6e5d4c3b2a1/       # Outro projeto
        +-- ...

Guia de Decisão de Escopo

Tipo de Padrão	Escopo	Exemplos
Convenções de linguagem/framework	projeto	"Use React hooks", "Siga padrões Django REST"
Preferências de estrutura de arquivos	projeto	"Testes em __tests__/", "Componentes em src/components/"
Estilo de código	projeto	"Use estilo funcional", "Prefira dataclasses"
Estratégias de tratamento de erros	projeto	"Use tipo Result para erros"
Práticas de segurança	global	"Valide entrada do usuário", "Sanitize SQL"
Melhores práticas gerais	global	"Escreva testes primeiro", "Sempre trate erros"
Preferências de fluxo de trabalho de ferramentas	global	"Use grep antes de editar", "Leia antes de escrever"
Práticas de Git	global	"Commits convencionais", "Commits pequenos e focados"

Promoção de Instintos (Projeto -> Global)

Quando o mesmo instinto aparece em vários projetos com alta confiança, ele é candidato a promoção para o escopo global.

Critérios de autopromoção:

• Mesmo ID de instinto em 2+ projetos
• Confiança média >= 0.8

Como promover:

# Promover um instinto específico
python3 instinct-cli.py promote preferir-erros-explicitos

# Autopromover todos os instintos qualificados
python3 instinct-cli.py promote

# Visualizar sem alterações
python3 instinct-cli.py promote --dry-run

O comando /evolve também sugere candidatos a promoção.

Pontuação de Confiança

A confiança evolui ao longo do tempo:

Pontuação	Significado	Comportamento
0.3	Tentativo	Sugerido, mas não aplicado
0.5	Moderado	Aplicado quando relevante
0.7	Forte	Aprovado automaticamente para aplicação
0.9	Quase certeza	Comportamento central

A confiança aumenta quando:

• O padrão é observado repetidamente
• O usuário não corrige o comportamento sugerido
• Instintos similares de outras fontes concordam

A confiança diminui quando:

• O usuário corrige explicitamente o comportamento
• O padrão não é observado por longos períodos
• Evidências contraditórias aparecem

Por que Hooks vs. Habilidades para Observação?

"A v1 dependia de habilidades para observar. Habilidades são probabilísticas — elas disparam ~50-80% das vezes com base no julgamento do Claude."

Hooks disparam 100% das vezes, deterministicamente. Isso significa:

• Cada chamada de ferramenta é observada
• Nenhum padrão é perdido
• O aprendizado é abrangente

Compatibilidade Reversa

A v2.1 é totalmente compatível com v2.0 e v1:

• Instintos globais existentes podem ser migrados de ~/.claude/homunculus/instincts/ com scripts/migrate-homunculus.sh
• Habilidades existentes de ~/.claude/skills/learned/ da v1 ainda funcionam
• O hook de parada ainda é executado (mas agora também alimenta a v2)
• Migração gradual: execute ambos em paralelo

Privacidade

• As observações permanecem locais na sua máquina
• Instintos com escopo de projeto são isolados por projeto
• Apenas instintos (padrões) podem ser exportados — não observações brutas
• Nenhum código real ou conteúdo de conversa é compartilhado
• Você controla o que é exportado e promovido

Relacionados

• ECC-Tools GitHub App - Gerar instintos a partir do histórico do repositório
• Homunculus - Projeto comunitário que inspirou a arquitetura baseada em instintos da v2 (observações atômicas, pontuação de confiança, pipeline de evolução de instintos)
• The Longform Guide - Seção de aprendizado contínuo

---

Aprendizado baseado em instintos: ensinando seus padrões ao Claude, um projeto de cada vez.