Tu agente IA dice 'listo' pero no funciona: un framework open-source para arreglarlo

Llevo más de un año trabajando con agentes IA en producción (Claude Code, Codex, Cursor). El patrón siempre es el mismo: 1. Le pides algo al agente 2. Dice "listo" 3. No funciona4. Cambias de modelo5. Sigue sin funcionarEl problema no es el modelo. Es el entorno.## El gapHay un gap enorme entre "demo que funciona" y "sistema que produce resultados consistentes". Los modelos son capaces, pero fallan por:- Especificaciónes vagas: el agente adivina- Sin verificación: dice "listo" sin ejecutar tests- Sin estado: cada sesión empieza de cero- Sin observabilidad: no sabes cuánto cuesta ni si la calidad baja## La solución: 6 tiers progresivosHe publicado ia-engineer-framework, un framework open-source (MIT, español nativo) que cierra este gap con 6 capas:### Tier 1: Harness (10 min)Templates que copias a tu proyecto. CLAUDE.md con instrucciones, feature_list.json con features machine-readable, init.sh para verificar entorno.

bashcp -r ia-engineer-framework/harness/ tu-proyecto/# Edita CLAUDE.md con tus comandos# Edita feature_list.json con tus features# Ejecuta tu agente — lee los archivos automáticamente

Tier 2: Eval (30 min)Datasets JSONL con escenarios y respuestas esperadas. Un runner que ejecuta contra cualquier LLM. Un scorer que mide accuracy. Un gate que bloquea CI si baja del umbral.

bashpython3 run-evals.py --dataset prompting-basics.jsonl --output results.jsonlpython3 score-evals.py --results results.jsonl# Accuracy: 87.5% — PASS

Tier 3: Observe (1h)Logger que registra 10 campos por interacción (tokens, coste, latencia, tools, errores). Cost tracker que agrega por sesión/modelo/dia. Dashboard Grafana importable.### Tier 4: Hooks (15 min)Automatización para Claude Code: lint pre-commit, tests post-tarea, guard de coste por sesión, scan de seguridad.### Tier 5: Patterns (lectura)8 documentos de referencia: díagnostic loop, multi-session, graph engineering, circuit breaker, HITL, model routing, prompt versioning, agent testing.### Tier 6: CI/CD (1h)GitHub Action que ejecuta evals en cada PR. Quality gate que bloquea merge si fallan.## Diagnostic Loop: el patrón más útilCuando tu agente falla, no cambies de modelo. Diagnostica la capa: 1. Especificación — la tarea era clara?2. Contexto — el agente tenía la info? 3. Entorno — dependencias correctas? 4. Verificacion — había tests? 5. Estado — recordaba el trabajo previo?Corrige la capa que falló. Repite. Tras 3-5 rondas tu entorno es robusto. Sin gastar más dinero.## Comparativa con Learn Harness Engineering (11.3K stars)| | LHE | ia-engineer-framework ||---|---|---|| Scope | Solo harness | Harness + eval + observe + CI || Eval pipeline | No | Runner + scorer + CI gate || Observabilidad | No | Logger + cost tracker + alertas || CI/CD | No | GitHub Action + quality gate || Idioma | Inglés | Español nativo || Formato | Curso | Copy-paste to production |## Principios1. Automatización antes que IA — si un test lo resuelve, no uses LLM2. Verificable > inteligente — un eval dataset de 8 preguntas > un prompt "perfecto"3. Copy-paste to production — cada archivo funciona standalone4. Progresivo — Tier 1 en 10 min, Tier 6 cuando tengas equipo5. Sin lock-in — Claude Code, Codex, Cursor, cualquiera## Empieza en 5 minutos

bashgit clone https://github.com/pedri77/ia-engineer-framework.gitcp -r ia-engineer-framework/harness/ tu-proyecto/

Edita CLAUDE.md y feature_list.json con tus datos. Ejecuta tu agente.GitHub: pedri77/ia-engineer-frameworkMIT. Usa, modifica, distribuye.---Esto es parte de IAcademy, academia de IA aplicada al trabajo real.