Continuous Learning v2.1 - Aprendizado por Instintos

Continuous Learning v2.1 - Arquitetura Baseada em Instintos

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

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

Quando Ativar

• Configurando aprendizado automático a partir 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 para skills, comandos ou agentes completos
• Gerenciando instintos com escopo de projeto vs. globais
• Promovendo instintos do escopo de projeto para o global

Novidades na v2.1

Característica	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 do git remote / caminho do repositório
Promoção	N/A	Projeto → global quando visto em 2+ projetos
Comandos	4 (status/evolve/export/import)	6 (+promote/projects)
Contaminação cruzada	Risco de contaminação	Isolado por padrão

Novidades na v2 (vs v1)

Característica	v1	v2
Observação	Hook de parada (final da sessão)	PreToolUse/PostToolUse (100% confiável)
Análise	Contexto principal	Agente em background (Haiku)
Granularidade	Skills completas	Instintos atômicos
Confiança	Nenhuma	0.3-0.9 ponderado
Evolução	Direta para skill	Instintos -> cluster -> skill/command/agent
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
Usar padrões funcionais em vez de classes quando apropriado.

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

Propriedades:

• Atômico — um gatilho, uma ação
• Ponderado por confiança — 0.3 = tentativo, 0.9 = quase certo
• Marcado por domínio — estilo-de-codigo, teste, git, depuracao, workflow, etc.
• Baseado em evidências — rastreia quais observações o criaram
• Ciente 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ê (background, Haiku)
      v
+---------------------------------------------+
|          DETECÇÃO DE PADRÕES                |
|   * Correções do usuário -> instinto        |
|   * Resoluções de erros -> instinto         |
|   * Workflows repetidos -> instinto         |
|   * Decisão de escopo: projeto ou global?   |
+---------------------------------------------+
      |
      | Cria/atualiza
      v
+---------------------------------------------+
|  projects/<hash-do-projeto>/instincts/personal/ |
|   * preferir-estilo-funcional.yaml (0.7) [projeto] |
|   * usar-react-hooks.yaml (0.9) [projeto]    |
+---------------------------------------------+
|  instincts/personal/  (GLOBAL)               |
|   * sempre-validar-entrada.yaml (0.85) [global] |
|   * grep-antes-de-editar.yaml (0.6) [global] |
+---------------------------------------------+
      |
      | /evolve clusters + /promote
      v
+---------------------------------------------+
|  projects/<hash>/evolved/ (escopo de projeto) |
|  evolved/ (global)                           |
|   * commands/nova-funcionalidade.md          |
|   * skills/workflow-de-teste.md              |
|   * agents/especialista-em-refatoracao.md    |
+---------------------------------------------+

Detecção de Projeto

O sistema detecta automaticamente seu projeto atual:

1. Variável de ambiente CLAUDE_PROJECT_DIR (maior prioridade) — honrada como uma substituição explícita mesmo quando o diretório não é um repositório git (hash é gerado pelo caminho absoluto)
2. git remote get-url origin — hash para criar um ID de projeto portátil (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 por humanos.

Diretório de Dados

O Continuous-learning-v2 armazena dados do observador fora de ~/.claude para que a proteção de caminhos sensíveis do Claude Code não bloqueie as gravações de instintos em background:

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 plugin (recomendado):

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

Se você copiou observe.sh anteriormente para ~/.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 isto 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 skills/commands
/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 skills/commands, 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 background:

{
  "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 background
observer.run_interval_minutes	5	Com que frequência o observador analisa as 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 de plataforma para o observador

O observador em background requer WSL2, Linux ou macOS. No Windows nativo (Git Bash / MSYS2) ele inicia e relata sucesso, mas o processo é encerrado quando o hook que o criou sai e seu Job Object é fechado, portanto 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 depois que o observador falha em sobreviver várias vezes consecutivas.

Variável de ambiente	Padrão	Descrição
ECC_OBSERVER_NOSURVIVE_WARN_AFTER	3	Falhas consecutivas de sobrevivência 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/remote
+-- observations.jsonl      # Observações globais (fallback)
+-- instincts/
|   +-- personal/           # Instintos globais aprendidos automaticamente
|   +-- inherited/          # Instintos globais importados
+-- evolved/
|   +-- agents/             # Agentes globais gerados
|   +-- skills/             # Skills globais geradas
|   +-- commands/           # Comandos globais gerados
+-- projects/
    +-- a1b2c3d4e5f6/       # Hash do projeto (da URL do git remote)
    |   +-- project.json    # Espelho de metadados por projeto (id/nome/raiz/remote)
    |   +-- 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	"Usar React hooks", "Seguir padrões Django REST"
Preferências de estrutura de arquivos	projeto	"Testes em __tests__/", "Componentes em src/components/"
Estilo de código	projeto	"Usar estilo funcional", "Preferir dataclasses"
Estratégias de tratamento de erros	projeto	"Usar tipo Result para erros"
Práticas de segurança	global	"Validar entrada do usuário", "Sanitizar SQL"
Melhores práticas gerais	global	"Escrever testes primeiro", "Sempre tratar erros"
Preferências de workflow de ferramentas	global	"Grep antes de Editar", "Ler antes de Escrever"
Práticas Git	global	"Commits convencionais", "Commits pequenos e focados"

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

Quando o mesmo instinto aparece em múltiplos projetos com alta confiança, ele é candidato à promoção para 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 à 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 certo	Comportamento central

A confiança aumenta quando:

• O padrão é observado repetidamente
• O usuário não corrige o comportamento sugerido
• Instintos semelhantes 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 Skills para Observação?

"v1 dependia de skills para observar. Skills 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 Retroativa

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
• Skills ~/.claude/skills/learned/ existentes 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 da comunidade 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.