Del chat al sistema agéntico

OpenRouter y el desarrollo guiado por especificaciones

Edimer David Jaramillo

2026-10-13

Pregunta de apertura: ¿qué falla si el prompt es excelente, pero el sistema no conoce los datos, los paquetes que usamos ni cómo se verifica el resultado?

Un prompt orienta al modelo. Un sistema agéntico es modelo + orquestación + contexto + herramientas + reglas, con capacidad de observar resultados y corregir. El criterio de éxito cambia: no basta una respuesta plausible; buscamos ejecución reproducible, pruebas y trazabilidad.

No es “web contra IA”: las apps web de Claude o ChatGPT también tienen memoria, proyectos y conectores. La diferencia está en dónde ocurre el trabajo: un sistema agéntico local lee y edita los archivos del proyecto, ejecuta R, Quarto y las pruebas, usa git, carga el AGENTS.md y permite elegir el modelo.

Hermes Agent · Para explorar: skills · MCP · Context7 · subagentes · cron

Hermes Agent (Nous Research, licencia MIT). Interesa la separación de responsabilidades, no la herramienta: lo mismo aplica a otros sistemas agénticos.

• Ciclo: lee el pedido, consulta el modelo, actúa con herramientas y revisa el resultado, hasta terminar.
• Herramientas: archivos, terminal (aquí corren R y Quarto), búsqueda web.
• Contexto: carga el AGENTS.md del proyecto; guarda notas entre sesiones y puede buscar en conversaciones pasadas.
• Controles: pide aprobación antes de comandos riesgosos y bloquea siempre los destructivos.

La franja inferior no se trabaja hoy: son temas para explorar después (los enlaces están debajo). - Skills: “recetas” reutilizables, carpetas con un SKILL.md (estándar abierto de Agent Skills). - MCP: protocolo para conectar el sistema con servicios externos (“el USB-C de la IA”). - Context7: documentación actualizada de paquetes, vía MCP. - Subagentes: delega tareas en paralelo. Cron: tareas programadas.

OpenRouter · crear llave · modelos gratuitos · límites · descargar Hermes · guía de la app de escritorio

OpenRouter: una sola API (compatible con OpenAI) para cientos de modelos de distintos proveedores. Es transversal: sirve con Hermes y con muchas otras herramientas. No cobra recargo sobre el precio de los proveedores; cobra una comisión al comprar créditos.

Hermes Desktop: el paquete incluye el agente, Python y sus dependencias; el primer arranque no compila nada. Se instala abriendo el archivo .appinstaller (instala un paquete MSIX firmado). No usar el instalador “Hermes-Setup”, que descarga el código fuente y compila la app. En el asistente inicial se puede elegir “Choose provider later”.

• Proveedor y llave: Settings → Providers.
• Modelo por defecto: Settings → Model; para el chat actual, el selector junto al micrófono.
• Carpeta de trabajo: selector de carpeta del chat (Settings → Workspace para descubrir repositorios).
• Terminal integrada en la barra lateral derecha: Ctrl + `.

Conviene tener R instalado. Lo demás (paquetes de R, Quarto) lo puede instalar el propio sistema: pedirle que avise qué instaló y aprobar cada instalación.

Mostrar en vivo: los nombres de menú pueden cambiar entre versiones.

agents.md · Agentic AI Foundation · archivos de contexto en Hermes · AGENTS.md en Claude Code

Tres textos distintos: el prompt (lo que pido ahora; se pierde al cerrar la sesión), AGENTS.md (cómo se trabaja aquí; estable) y SYSTEM_DESIGN.md (qué se construye; evoluciona con el diseño).

AGENTS.md: formato abierto impulsado por OpenAI Codex, Amp, Jules (Google), Cursor y Factory. Desde diciembre de 2025 lo custodia la Agentic AI Foundation (Linux Foundation), junto con MCP y goose.

Hermes carga un solo archivo de contexto por sesión, en este orden: .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules. Claude Code lo lee desde la versión 2.1.277 cuando no hay CLAUDE.md; si existe CLAUDE.md, basta con incluir @AGENTS.md dentro de él.

La regla “si falta un paquete o Quarto, instálalo y dime qué instalaste” habilita al sistema a preparar el entorno sin perder trazabilidad.

GitHub Spec Kit · Kiro: specs · B. Böckeler, martinfowler.com · Thoughtworks Radar

SDD (Spec-Driven Development): la especificación se escribe primero y es la fuente de verdad para la persona y para la IA. Spec Kit lo resume como “definir qué y por qué antes de decidir cómo”.

Niveles según Birgitta Böckeler (2025): spec-first (la spec sirve para la tarea), spec-anchored (se conserva para mantener la funcionalidad) y spec-as-source (la spec es el artefacto principal y el código se genera).

Thoughtworks la ubica en “Assess”: técnica emergente; advierte que escribir reglas muy detalladas a mano puede no escalar. Por eso: disciplina, no dogma.

A. Kladov, ARCHITECTURE.md · requisitos en notación EARS (Kiro) · readxl · Quarto

SYSTEM_DESIGN.md no es una convención estándar: es una práctica recomendable. Lo importante es el hábito de escribir el diseño antes de pedir código. Equivalentes: design.md de Kiro, plan.md + data-model.md + contracts/ de Spec Kit, o ARCHITECTURE.md (Kladov: vista general, mapa del código e invariantes). Evitar llamarlo DESIGN.md: hoy ese nombre se asocia al formato de Google Stitch para diseño visual.

La sección clave es la pregunta técnica: es lo que cada persona edita en su ejercicio. Todo lo demás (datos, requisitos, módulos) se ajusta a esa pregunta.

Diseñado para repetirse: cada semana llega un nuevo .xlsx, se vuelve a renderizar y el informe se actualiza sin reescribir código.

testthat (R) · pytest (Python) · readxl

Parte 1, juntos: comparto archivos .xlsx con datos simulados (granjas, vacas, producción de leche). Construimos en vivo un informe semanal: AGENTS.md, SYSTEM_DESIGN.md con la pregunta, Hermes construye y verifica. El informe identifica la semana actual por el nombre del archivo (produccion_AAAA_semana_NN.xlsx): basta con guardar en datos/ el archivo de una semana nueva y volver a renderizar para que se actualice solo. Así se emula lo que podría hacerse cada semana con los datos reales de un hato.

Parte 2, cada persona: sus propios datos (cualquier formato) y su propia pregunta técnica en SYSTEM_DESIGN.md. Si alguien no tiene datos, puede usar los simulados con otra pregunta.

Pedido para pegar en Hermes (todos el mismo): “Lee AGENTS.md y SYSTEM_DESIGN.md. Construye el informe siguiendo el diseño: primero las funciones en R, luego las pruebas y al final informe.qmd. Ejecuta las pruebas y genera informe.html. Al terminar, dime qué instalaste, qué archivos creaste y el resultado de las pruebas.”

Para una semana nueva: guardar el archivo en datos/ con el formato produccion_AAAA_semana_NN.xlsx y pedir “Genera de nuevo el informe con los datos actuales”.

Requisitos previos: R instalado y Hermes Desktop configurado con la llave de OpenRouter. Quarto y los paquetes de R los puede instalar Hermes (pide permiso).

Los cinco pasos: 1. AGENTS.md con carpetas, comandos (pruebas y quarto render) y límites. 2. SYSTEM_DESIGN.md: pregunta técnica, columnas de los datos y qué debe mostrar el informe. 3. “Construye el informe según SYSTEM_DESIGN.md”: el sistema instala lo que falte (aprobar cada instalación). 4. Pruebas automáticas que validen los datos (columnas, faltantes, negativos) y render del HTML. En R usamos testthat; la misma idea aplica con pytest en Python u otro marco. 5. Abrir informe.html y auditar: ¿responde la pregunta? ¿los números tienen sentido? Si no, ajustar SYSTEM_DESIGN.md y repetir.

Idea final: prompt = intención; AGENTS.md = reglas y contexto estable; SYSTEM_DESIGN.md = diseño; modelo vía OpenRouter = razonamiento; herramientas = acción; pruebas = evidencia. Skills y Context7 quedan como próximos pasos.

Práctica sugerida con Context7 (mostrar en vivo cómo crear la cuenta y configurarlo): 1. Crear una cuenta gratuita en context7.com (1.000 consultas al mes). 2. Generar una API key en el panel (es privada, como la de OpenRouter). 3. Agregar Context7 a Hermes como servidor MCP: en ~/.hermes/config.yaml, sección mcp_servers, url https://mcp.context7.com/mcp y la llave en los headers. 4. Pedir: “consulta Context7 sobre Quarto y ggplot2 antes de construir el informe”. 5. Comparar el resultado con la versión sin Context7. Context7 tiene dos herramientas MCP: resolve-library-id y query-docs. No garantiza que el código funcione: las pruebas siguen siendo la evidencia.

No es obligatorio adoptar todo: la invitación es a descubrir qué pieza les ahorra trabajo hoy y les enseña algo en el camino.

Para seguir: SDD con agentes de código

Full Course: Spec-Driven Development with Coding Agents · DeepLearning.AI · clic en la imagen para verlo en YouTube

Curso completo de DeepLearning.AI sobre Spec-Driven Development con agentes de código: la invitación es a seguir explorando el paradigma por su cuenta.

La imagen abre el video en YouTube en una pestaña nueva. No se incrusta el reproductor porque YouTube lo bloquea (error 153) al abrir la presentación como archivo local o desde el visor de RStudio/Positron.

Recursos de información

• Hermes Agent · documentación · app de escritorio
• OpenRouter · documentación · modelos gratuitos
• AGENTS.md · Agentic AI Foundation · AGENTS.md en Claude Code
• GitHub Spec Kit · Kiro: specs · Thoughtworks Radar: SDD
• B. Böckeler, Understanding Spec-Driven-Development
• A. Kladov, ARCHITECTURE.md
• Quarto · readxl · testthat
• Para explorar: Agent Skills · Model Context Protocol · Context7 (cuenta y llave, MCP en Hermes)
• DeepLearning.AI, Spec-Driven Development with Coding Agents

edimer.netlify.app/es