ia-engineer-framework: como hacer que tu agente IA funcione de verdad

El problema: tu agente dice "listo" pero no funciona

Si usas Claude Code, Codex, Cursor o cualquier agente IA para programar, conoces este patrón: le pides una feature, dice "completado", pero los tests fallan. Cambias de modelo. Sigue fallando.

El problema no es el modelo. Es el entorno. Las especificaciones son vagas, las convenciones no están documentadas, no hay verificación automática y cada sesión empieza de cero.

ia-engineer-framework es un framework open-source (MIT, español nativo) que cierra este gap con 6 capas progresivas.

Arquitectura: 6 tiers progresivos

No necesitas implementar los 6 tiers. Empieza con Tier 1 (10 minutos) y añade capas cuando las necesites.

Tier 1: Harness (10 minutos)

Templates que copias a tu proyecto. El agente los lee automáticamente y sigue las instrucciones:

• CLAUDE.md: comandos, convenciones, arquitectura, reglas de trabajo
• feature_list.json: features con criterios de verificación machine-readable
• init.sh: script que verifica que el entorno funciona
• progress.md y session-handoff.md: estado entre sesiones

git clone https://github.com/pedri77/ia-engineer-framework.git
cp -r ia-engineer-framework/harness/ tu-proyecto/
# Edita CLAUDE.md con tus comandos reales
# Edita feature_list.json con tus features

Tier 2: Eval (30 minutos)

Datasets JSONL con escenarios y respuestas esperadas. Un runner que ejecuta contra cualquier LLM (Anthropic, OpenAI, local). Un scorer que mide accuracy. Un gate que bloquea CI si baja del umbral.

# Ejecutar evals
python3 run-evals.py --dataset prompting-basics.jsonl --output results.jsonl

# Scoring
python3 score-evals.py --results results.jsonl
# Accuracy: 87.5%

# Gate para CI
python3 ci-gate.py --results results.jsonl --threshold 0.8
# PASS

Incluye 4 datasets con 32 escenarios: prompting, fiabilidad de agentes, automatización y calidad de código.

Tier 3: Observe (1 hora)

Logger que registra 10 campos por interacción: timestamp, modelo, tokens entrada/salida, coste USD, latencia, tool calls, éxito/error. Cost tracker que agrega por sesión, modelo y período.

Incluye dashboard Grafana importable y guía de eventos PostHog.

Tier 4: Hooks (15 minutos)

Automatización para Claude Code que se ejecuta en eventos del agente:

• pre-commit-lint.py: lint antes de cada commit
• post-task-verify.py: tests después de editar código
• cost-guard.py: bloquea si coste de sesión supera límite ($10 por defecto)
• security-scan.py: detecta secretos, API keys y patrones vulnerables

Tier 5: Patterns (lectura)

8 documentos de referencia con patrones probados en producción:

• Diagnostic loop: diagnostica que capa fallo (especificación, contexto, entorno, verificación, estado) en vez de cambiar de modelo
• Multi-session: como mantener continuidad entre sesiones con 3 artefactos
• Graph engineering: 14 patrones para pipelines multi-agente (fan-out, verificación adversarial, model tiering)
• Circuit breaker: prevenir agentes desbocados con límites de retry, coste y tiempo
• Y 4 más: model routing, prompt versioning, agent testing, human-in-the-loop

Tier 6: CI/CD (1 hora)

GitHub Action que ejecuta evals en cada PR. Quality gate que bloquea merge si accuracy cae. Pre-push check con lint + tests + security scan.

El patrón más útil: Diagnostic Loop

Cuando tu agente falla, no cambies de modelo. Diagnostica la capa:

1. Especificación: la tarea era clara? Habia Definition of Done?
2. Contexto: el agente tenia la info necesaria? Conocia las convenciones?
3. Entorno: dependencias instaladas? Versiones correctas?
4. Verificación: habia tests? El agente los ejecuto?
5. Estado: el agente recordaba el trabajo previo?

Corrige la capa que fallo. Repite. Tras 3-5 rondas tu entorno es robusto. Sin gastar más dinero.

Principios del framework

1. Automatización antes que IA: si un test o regex lo resuelve, no uses LLM
2. Verificable > inteligente: un eval dataset de 8 preguntas vale más que un prompt "perfecto"
3. Copy-paste to production: cada archivo funciona standalone, sin instalar nada
4. Progresivo: Tier 1 en 10 minutos, Tier 6 cuando tengas equipo
5. Sin lock-in: funciona con Claude Code, Codex, Cursor o cualquier agente

Ejemplos incluidos

3 proyectos de ejemplo con harness completo y eval dataset:

• FastAPI + SQLAlchemy: CRUD, búsqueda, validación Pydantic
• Next.js 14 + TypeScript: Server/Client Components, responsive, accesibilidad
• n8n + Python workers: webhooks, pipelines, notificaciones multi-canal

Empieza en 5 minutos

git clone https://github.com/pedri77/ia-engineer-framework.git
cp -r ia-engineer-framework/harness/ tu-proyecto/
# Edita CLAUDE.md y feature_list.json
# Ejecuta tu agente IA

Ver en GitHub — MIT. 63 archivos, 5,097 líneas, 0 dependencias externas.