Tu agente se equivoca, lo corriges, y mañana se equivoca igual. Este kit encuentra dónde lo corregiste, encuentra el error que se repite — incluso en otro proyecto — y convierte la lección en un gancho, validador o prueba que el modelo no puede saltarse.
agente-que-aprende es un kit de cuatro scripts en Python para quienes trabajan con agentes de IA de programación, como Claude Code y Codex. Lee tus sesiones y los archivos donde anotas fallas y lecciones (FALHAS.md, LESSONS.md), muestra dónde corregiste al agente y qué errores vuelven, y te ayuda a convertir cada lección en una traba automática en lugar de una regla escrita más. Solo necesita Python 3; no usa internet ni API, y ninguna regla se adopta sin tu decisión.
El proyecto explicado en pocos minutos.
La regla escrita es la corrección más débil: el modelo puede saltársela. El orden de fuerza es arquitectura (el error se vuelve imposible) > gancho/validador (bloquea) > prueba (detecta) > checklist > texto.
retro.py lee la sesión y lista cada vez que corregiste al agente y cada error de herramienta que se repitió, con el peldaño sugerido. Se ejecuta solo cuando la sesión se cierra.
degrau.py y jardineiro.py leen FALHAS y LESSONS, agrupan el mismo error escrito de formas distintas y muestran lo que todavía es solo texto y se repite.
gancho.py es un hook de Claude Code: cada lección se vuelve una línea en ganchos.json y el comando que ya falló queda bloqueado, con la explicación de vuelta para el agente. Funciona en Claude Code; en Codex, la retro y el jardinero ya funcionan, el gancho todavía no.
El agente ejecuta, recibe retorno, el retorno se revisa, tú apruebas, y la lección queda donde la próxima ejecución no puede ignorarla.
1 protecciones (pruebas, tipos, lint) · 2 skills · 3 memoria · 4 error imposible · 5 automatización · 6 automejora. La cima es el último peldaño: sin los de abajo no hay de qué aprender. La escalera es el camino del equipo; el orden de fuerza (arquitectura > gancho > prueba > checklist > texto) vale para cada lección.
El peldaño actual y la sugerencia salen de palabras-señal en aprende/comum.py ("ausente/pulou" (ausente/se saltó) → arquitectura; "conferir antes" (revisar antes) → validador; comando peligroso → gancho). Las palabras y los informes están en portugués (con una parte en inglés); tú ajustas la lista y decides.
SIL Loop R es otro proyecto abierto: un cuaderno local (SQLite) de ocurrencias y lecciones, en el que nada se vuelve regla sin decisión humana. Con --sil <projeto>, cada propuesta del kit entra allí como ocurrencia + lección propuesta. Es opcional.
Ninguna dependencia, ninguna clave, ninguna llamada de red. SIL Loop R es opcional.
Solo la biblioteca estándar.
# verificar python3 --version
Archivos con estos nombres: FALHAS.md (tabla: fecha | qué se rompió | corrección mínima | prompt/infra), LICOES.md (tabla de 3 columnas) y/o LESSONS.md (lista "- regla (fecha)"). La fila de la tabla empieza por la fecha (AAAA-MM-DD o dd/mm).
# ejemplo de fila
| 2026-11-06 | render caiu: template ausente | rodar o passo antes | prompt |Claude Code (para los hooks), systemd (timer semanal) y SIL Loop R (para recibir las propuestas). El kit busca el SIL en ~/projetos/sil-loop-r/, en el PATH (sil) o en 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 paso usa los comandos del repositorio. Las pruebas usan datos ficticios y se ejecutan sin red.
Las 10 pruebas verifican la lectura de las tablas, la retro, el gancho y la integración con el SIL.
git clone https://github.com/inematds/agente-que-aprende.git && cd agente-que-aprende python3 -m unittest discover -s tests -v # OK
Lee las fallas y lecciones del proyecto y lista lo que se repite y todavía es solo texto, con el peldaño sugerido y las líneas de origen.
python3 degrau.py tests/dados/FALHAS.md # demostración con los datos del repo python3 degrau.py ~/projetos/meu-app/FALHAS.md ~/projetos/meu-app/LESSONS.md --top 10
Mide la reincidencia (cuánto de los registros es el mismo error otra vez), muestra los errores que "se mudaron de casa" y el ranking general.
python3 jardineiro.py --raiz tests # demostración python3 jardineiro.py --raiz ~/projetos --saida jardim/$(date +%F).md
Apunta al archivo de la sesión (las más recientes: ls -t ~/.claude/projects/*/*.jsonl | head -3). --pergunta agrega el pedido de retro para pegar en el agente ("¿qué salió mal aquí?").
python3 retro.py tests/dados/sessao.jsonl --pergunta # demostración python3 retro.py ~/.claude/projects/<carpeta>/<id>.jsonl --pergunta python3 retro.py ~/.codex/sessions/<aaaa/mm/dd>/rollout-<…>.jsonl # Codex también
Un elemento más en la lista de ganchos.json (separado por comas): el patrón del comando equivocado, la excepción (opcional), el mensaje y de dónde vino la lección. El kit ya trae una traba universal (pkill-f); más ejemplos en modelos/ganchos-exemplo.json. Para no modificar el archivo del kit, usa un archivo propio en AQA_GANCHOS=/ruta/mios.json. Pruébalo antes de activar el paso 6: el gancho ignora lo que está entre comillas y dentro de un heredoc, así que citar el comando en un texto, en un commit o en un grep no se bloquea.
{"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
En ~/.claude/settings.json: el gancho antes de cada comando Bash y la retro cuando la sesión se cierra (informes en ~/.local/share/agente-que-aprende/retro/, solo cuando hubo corrección o error 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"}]}]
}
Copia el timer y, en jardineiro.service, cambia KIT (dónde está el kit), SAIDA (dónde guardar los informes) y el --raiz %h/projetos (dónde están tus proyectos). Cada lunes a las 07:30 sale un informe nuevo.
cp modelos/systemd/jardineiro.{service,timer} ~/.config/systemd/user/ systemctl --user daemon-reload && systemctl --user enable --now jardineiro.timer
Con el SIL instalado e iniciado en el proyecto (ver Requisitos previos), los 5 primeros candidatos se vuelven ocurrencia + lección propuesta en SIL Loop R (retro.py también acepta --sil). Nada se adopta sin ti.
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 fuera de ~/projetos
Ejecutado sobre los registros reales de INEMA el 7/11/2026: 196 archivos de fallas y lecciones, 1.880 registros, en menos de 1 segundo.
180 registros en 84 grupos de repetición; 57 grupos atraviesan proyectos — el error solo se mudó de casa.
Matar procesos por patrón mataba la propia shell. Cada vez se volvió una línea de texto. Ahora es el gancho pkill-f: el comando se bloquea en el acto, con la forma correcta en el mensaje.
El render fallaba porque un paso anterior no se ejecutó. Sugerencia del kit: arquitectura — la cadena genera lo que falta (modelos/validador-passo.sh).
# fragmento del informe del jardinero
- 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
La medida es una sola: la reincidencia semanal tiene que bajar.