Framework open-source para hacer agentes IA fiables en produccion.
Hay un gap enorme entre "demo que funciona" y "sistema que produce resultados consistentes". Este framework lo cierra con 6 capas progresivas: desde controlar tu agente en 10 minutos hasta tener CI/CD con evaluaciones automaticas.
Los modelos de IA son capaces, pero fallan en tareas reales por defectos en el entorno:
- Especificaciones vagas: el agente solo puede adivinar
- Convenciones no escritas: el agente no puede cumplir lo que no conoce
- Sin verificacion: el agente dice "listo" cuando no lo esta
- Sin estado entre sesiones: cada sesion empieza de cero
- Sin observabilidad: no sabes cuanto cuesta ni si la calidad baja
- Sin CI/CD: los cambios del agente llegan a produccion sin verificar
block-beta
columns 1
block:t1["Tier 1: HARNESS — Control del agente (10 min)"]
A1["CLAUDE.md"] A2["AGENTS.md"] A3["init.sh"] A4["feature_list.json"]
end
block:t2["Tier 2: EVAL — Verificacion y calidad (30 min)"]
B1["Eval datasets"] B2["Rubrics"] B3["Runners"] B4["CI gates"]
end
block:t3["Tier 3: OBSERVE — Observabilidad (1h)"]
C1["Agent logger"] C2["Cost tracker"] C3["Dashboards"] C4["Alertas"]
end
block:t4["Tier 4: HOOKS — Automatizacion Claude Code (15 min)"]
D1["Pre-commit lint"] D2["Post-task verify"] D3["Cost guard"] D4["Security scan"]
end
block:t5["Tier 5: PATTERNS — Patrones de produccion"]
E1["Diagnostic loop"] E2["Multi-session"] E3["Circuit breaker"] E4["Graph Eng."]
end
block:t6["Tier 6: CI/CD — Integracion continua con IA (1h)"]
F1["GitHub Action"] F2["Quality gate"] F3["Pre-push check"]
end
style t1 fill:#2d6a4f,color:#fff
style t2 fill:#1b4332,color:#fff
style t3 fill:#184e77,color:#fff
style t4 fill:#1e3a5f,color:#fff
style t5 fill:#3c1642,color:#fff
style t6 fill:#5a189a,color:#fff
Adopcion progresiva: empieza con Tier 1. Anade tiers cuando los necesites.
# 1. Clona el framework
git clone https://github.com/pedri77/ia-engineer-framework.git
# 2. Copia harness/ a tu proyecto
cp -r ia-engineer-framework/harness/ tu-proyecto/
# 3. Edita con tus datos
nano tu-proyecto/CLAUDE.md # Tus comandos y convenciones
nano tu-proyecto/feature_list.json # Tus features
# 4. Ejecuta tu agente IA — vera los archivos automáticamentePara setup completo: docs/getting-started.md
ia-engineer-framework/
├── README.md
├── LICENSE # MIT
├── CHANGELOG.md
│
├── harness/ # Tier 1: Control del agente
│ ├── CLAUDE.md # Template instrucciones Claude Code
│ ├── AGENTS.md # Template instrucciones Codex/Cursor
│ ├── init.sh # Bootstrap entorno
│ ├── feature_list.json # Tracker features machine-readable
│ ├── progress.md # Log progreso entre sesiones
│ ├── session-handoff.md # Traspaso entre sesiones
│ └── definition-of-done.md # Guia criterios de aceptación
│
├── eval/ # Tier 2: Verificación y calidad
│ ├── templates/
│ │ ├── eval-dataset.jsonl # Template formato JSONL
│ │ ├── rubric.md # Rubrica 6 dimensiones
│ │ └── quality-doc.md # Quality document por dominio
│ ├── runners/
│ │ ├── run-evals.py # Ejecutar evals contra LLM
│ │ ├── score-evals.py # Scoring automatico
│ │ └── ci-gate.py # Gate para CI/CD
│ └── datasets/
│ ├── prompting-basics.jsonl # 8 escenarios prompting
│ ├── agent-reliability.jsonl # 8 escenarios fiabilidad
│ ├── automation-workflows.jsonl # 8 escenarios automatizacion
│ └── code-quality.jsonl # 8 escenarios calidad código
│
├── observe/ # Tier 3: Observabilidad
│ ├── logging/
│ │ ├── agent-logger.py # Logger 10 campos por interacción
│ │ └── cost-tracker.py # Tracking coste por sesion
│ ├── dashboards/
│ │ ├── grafana-agent.json # Dashboard Grafana importable
│ │ └── posthog-events.md # Eventos PostHog recomendados
│ └── alerts/
│ ├── budget-alert.py # Alerta coste > umbral
│ └── quality-drift.py # Alerta accuracy baja
│
├── hooks/ # Tier 4: Automatización Claude Code
│ ├── pre-commit-lint.py # Lint antes de commit
│ ├── post-task-verify.py # Tests tras completar tarea
│ ├── context-check.py # Aviso contexto > umbral
│ ├── cost-guard.py # Bloquea si coste > limite
│ └── security-scan.py # Scan vulnerabilidades pre-commit
│
├── patterns/ # Tier 5: Patrones de producción
│ ├── diagnostic-loop.md # Framework diagnóstico fallos
│ ├── multi-session.md # Continuidad entre sesiones
│ ├── agent-testing.md # Shadow, canary, eval pipeline
│ ├── prompt-versioning.md # Versionado prompts producción
│ ├── model-routing.md # Regla > barato > caro > humano
│ ├── circuit-breaker.md # Limites retry, fallback, dead letter
│ └── human-in-the-loop.md # Cuando y como escalar a humano
│
├── ci/ # Tier 6: CI/CD con IA
│ ├── github-action.yml # Action: evals en PR
│ ├── pre-push-check.sh # Verificación pre-push
│ └── quality-gate.py # Gate: bloquea merge si evals fallan
│
├── examples/ # Proyectos ejemplo
│ ├── fastapi-agent/ # Agente FastAPI con harness completo
│ ├── nextjs-assistant/ # Asistente Next.js con eval pipeline
│ └── n8n-automation/ # Workflow n8n con observabilidad
│
└── docs/
├── getting-started.md # Quickstart 5 minutos
├── philosophy.md # Principios del framework
├── faq.md # Preguntas frecuentes
└── contributing.md # Como contribuir
| Dimension | Learn Harness Eng (11.3K stars) | ia-engineer-framework |
|---|---|---|
| Scope | Solo harness | Harness + eval + observe + CI + patterns |
| Idioma | Inglés | Español nativo |
| Eval pipeline | No | Runner + scorer + CI gate |
| Observabilidad | No | Logger + cost tracker + dashboards + alertas |
| CI/CD | No | GitHub Action + quality gate |
| Formato | Curso (lectures) | Copy-paste to production |
| Lock-in | Especifico | Claude Code, Codex, Cursor, cualquiera |
- Automatización antes que IA. Si un regex, test o regla resuelve el problema, no uses LLM.
- Verificable > inteligente. Un sistema que verifica outputs es mejor que uno que genera outputs mas inteligentes.
- Copy-paste to production. Cada archivo funciona standalone. No requiere instalar framework.
- Progresivo. Tier 1 en 10 minutos. Tier 6 cuando tengas equipo.
- Medible. Si no puedes medir si mejoro, no lo implementes.
- Sin lock-in. Funciona con Claude Code, Codex, Cursor, o cualquier agente.
- Espanol primero. README, docs, comentarios en ES. Codigo y nombres tecnicos en EN.
- FastAPI + agente IA — CLAUDE.md + eval dataset para proyecto Python
- Next.js + asistente IA — CLAUDE.md + eval dataset para proyecto frontend
- n8n + observabilidad — CLAUDE.md + observabilidad para workflows
Este framework es parte de IAcademy, la academia de IA aplicada al trabajo real.
- Modulo 02: Prompt Engineering — Prompts efectivos
- Modulo 07: Observabilidad y calidad — Eval datasets, versionado
- Modulo 08: IA para desarrollo — CLAUDE.md enterprise, agentes
- Blog: Claude Code guia completa — Todo sobre Claude Code
PRs bienvenidos. Lee docs/contributing.md antes de enviar.
MIT — Usa, modifica, distribuye libremente.