Seu agente erra, você corrige, e amanhã ele erra igual. Este kit acha onde você corrigiu, acha o erro que se repete — até em outro projeto — e transforma a lição num gancho, validador ou teste que o modelo não consegue pular.
O agente-que-aprende é um kit de quatro scripts em Python para quem trabalha com agentes de IA de programação, como o Claude Code e o Codex. Ele lê as suas sessões e os arquivos onde você anota falhas e lições (FALHAS.md, LESSONS.md), mostra onde você corrigiu o agente e quais erros voltam, e ajuda a transformar cada lição numa trava automática em vez de mais uma regra escrita. Precisa só de Python 3; não usa internet nem API, e nenhuma regra é adotada sem a sua decisão.
O projeto explicado em poucos minutos.
Regra escrita é a correção mais fraca: o modelo pode pular. A ordem de força é arquitetura (o erro fica impossível) > gancho/validador (bloqueia) > teste (pega) > checklist > texto.
retro.py lê a sessão e lista cada vez que você corrigiu o agente e cada erro de ferramenta que se repetiu, com o degrau sugerido. Roda sozinho quando a sessão fecha.
degrau.py e jardineiro.py leem FALHAS e LESSONS, juntam o mesmo erro escrito de jeitos diferentes e mostram o que ainda é só texto e se repete.
gancho.py é um hook do Claude Code: cada lição vira uma linha no ganchos.json e o comando que já deu errado é barrado, com a explicação de volta para o agente. Funciona no Claude Code; no Codex, a retro e o jardineiro já funcionam, o gancho ainda não.
O agente executa, recebe retorno, o retorno é conferido, você aprova, e a lição fica onde a próxima execução não consegue ignorar.
1 proteções (testes, tipos, lint) · 2 skills · 3 memória · 4 erro impossível · 5 automação · 6 autoaprimoramento. O topo é o último degrau: sem os de baixo não há do que aprender. A escada é o caminho do time; a ordem de força (arquitetura > gancho > teste > checklist > texto) vale para cada lição.
O degrau atual e a sugestão saem de palavras-sinal em aprende/comum.py ("ausente/pulou" → arquitetura; "conferir antes" → validador; comando perigoso → gancho). As palavras e os relatórios estão em português (com parte em inglês); você ajusta a lista e decide.
O SIL Loop R é outro projeto aberto: um caderno local (SQLite) de ocorrências e lições, em que nada vira regra sem decisão humana. Com --sil <projeto>, cada proposta do kit entra lá como ocorrência + lição proposta. É opcional.
Nenhuma dependência, nenhuma chave, nenhuma chamada de rede. O SIL Loop R é opcional.
Biblioteca padrão apenas.
# conferir python3 --version
Arquivos com estes nomes: FALHAS.md (tabela: data | o que quebrou | menor correção | prompt/infra), LICOES.md (tabela de 3 colunas) e/ou LESSONS.md (lista "- regra (data)"). A linha da tabela começa pela data (AAAA-MM-DD ou dd/mm).
# exemplo de linha
| 2026-11-06 | render caiu: template ausente | rodar o passo antes | prompt |Claude Code (para os hooks), systemd (timer semanal) e o SIL Loop R (para receber as propostas). O kit procura o SIL em ~/projetos/sil-loop-r/, no PATH (sil) ou em AQA_SIL.
git clone https://github.com/inematds/sil-loop-r.git ~/projetos/sil-loop-r python3 ~/projetos/sil-loop-r/sil.py --project ~/projetos/meu-app init
Cada passo usa os comandos do repositório. Os testes usam dados fictícios e rodam sem rede.
Os 10 testes conferem a leitura das tabelas, a retro, o gancho e a integração com o SIL.
git clone https://github.com/inematds/agente-que-aprende.git && cd agente-que-aprende python3 -m unittest discover -s tests -v # OK
Lê as falhas e lições do projeto e lista o que se repete e ainda é só texto, com o degrau sugerido e as linhas de origem.
python3 degrau.py tests/dados/FALHAS.md # demonstração com os dados do repo python3 degrau.py ~/projetos/meu-app/FALHAS.md ~/projetos/meu-app/LESSONS.md --top 10
Mede a reincidência (quanto dos registros é o mesmo erro de novo), mostra os erros que "mudaram de casa" e o ranking geral.
python3 jardineiro.py --raiz tests # demonstração python3 jardineiro.py --raiz ~/projetos --saida jardim/$(date +%F).md
Aponte para o arquivo da sessão (as mais recentes: ls -t ~/.claude/projects/*/*.jsonl | head -3). --pergunta acrescenta o pedido de retro para colar no agente ("o que deu errado aqui?").
python3 retro.py tests/dados/sessao.jsonl --pergunta # demonstração python3 retro.py ~/.claude/projects/<pasta>/<id>.jsonl --pergunta python3 retro.py ~/.codex/sessions/<aaaa/mm/dd>/rollout-<…>.jsonl # Codex também
Um item a mais na lista do ganchos.json (separado por vírgula): o padrão do comando errado, a exceção (opcional), a mensagem e de onde veio a lição. O kit já vem com uma trava universal (pkill-f); mais exemplos em modelos/ganchos-exemplo.json. Para não mexer no arquivo do kit, use um arquivo seu em AQA_GANCHOS=/caminho/meus.json. Teste antes de ligar o passo 6: o gancho ignora o que está entre aspas e dentro de heredoc, então citar o comando num texto, num commit ou num grep não é barrado.
{"id": "pkill-f", "ferramenta": "Bash", "padrao": "\\bpkill\\b[^|;&]*\\s-f\\b",
"mensagem": "Liste com pgrep -af e mate por PID em outro comando.", "origem": "FALHAS (7x)"}
echo '{"tool_name":"Bash","tool_input":{"command":"pkill -f x"}}' | python3 gancho.py; echo $? # 2 = bloqueado
No ~/.claude/settings.json: o gancho antes de cada comando Bash e a retro quando a sessão fecha (relatórios em ~/.local/share/agente-que-aprende/retro/, só quando houve correção ou erro repetido).
"hooks": {
"PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "python3 /caminho/agente-que-aprende/gancho.py"}]}],
"SessionEnd": [{"hooks": [{"type": "command", "command": "bash /caminho/agente-que-aprende/hooks/fim-de-sessao.sh"}]}]
}
Copie o timer e, em jardineiro.service, troque KIT (onde está o kit), SAIDA (onde salvar os relatórios) e o --raiz %h/projetos (onde ficam seus projetos). Toda segunda às 07:30 sai um relatório novo.
cp modelos/systemd/jardineiro.{service,timer} ~/.config/systemd/user/ systemctl --user daemon-reload && systemctl --user enable --now jardineiro.timer
Com o SIL instalado e iniciado no projeto (ver Pré-requisitos), os 5 primeiros candidatos viram ocorrência + lição proposta no SIL Loop R (o retro.py também aceita --sil). Nada é adotado sem você.
python3 jardineiro.py --raiz ~/projetos --sil ~/projetos/meu-app AQA_SIL=/outro/lugar/sil.py python3 retro.py sessao.jsonl --sil ~/projetos/meu-app # SIL fora de ~/projetos
Rodado nos registros reais do INEMA em 07/11/2026: 196 arquivos de falhas e lições, 1.880 registros, em menos de 1 segundo.
180 registros em 84 grupos de repetição; 57 grupos atravessam projetos — o erro só mudou de casa.
Matar processo pelo padrão matava o próprio shell. Cada vez virou uma linha de texto. Agora é o gancho pkill-f: o comando é barrado na hora, com o jeito certo na mensagem.
O render falhava porque um passo anterior não rodou. Sugestão do kit: arquitetura — a cadeia gera o que falta (modelos/validador-passo.sh).
# trecho do relatório do jardineiro
- 196 arquivos em 190 projetos · 1880 registros
- reincidência: 10% (180 registros em 84 grupos de 2+)
1. pkill -f "<padrão>" no mesmo comando matou o próprio shell — 7× em 6 projetos · texto → gancho/validador
4. produce_blocks caiu (templates/pt/scene-01.html ausente) — 4× · texto → servidor/arquitetura
A medida é uma só: a reincidência semanal tem que cair.