DEV Community: Johan Garcia

El problema de la confianza ciega: cómo reducir las alucinaciones en agentes de IA parte 2

Johan Garcia — Tue, 14 Jul 2026 04:33:38 +0000

En una arquitectura multiagente típica, el Orchestrator delega tareas a agentes especializados y procesa sus respuestas. El problema aparece cuando un agente devuelve una salida mal formada: XML con etiquetas desbalanceadas, JSON inválido, campos obligatorios ausentes o tipos de datos incorrectos. En estos casos, el Orchestrator no siempre puede detectar el error de forma confiable, lo que provoca fallos silenciosos y aumenta la probabilidad de alucinaciones.

Plantillas de datos estructurados y Output Contracts para reducir alucinaciones

Los Output Contracts son una estrategia de validación estructurada para la comunicación entre agentes y el Orchestrator en arquitecturas multiagente. Consisten en encapsular la respuesta de cada agente dentro de un envelope XML que contiene un payload JSON validado mediante un JSON Schema específico para ese agente.

Un Output Contract define de forma explícita el formato que el agente debe producir. Mientras que los system prompts establecen reglas de comportamiento, los contratos de salida eliminan la ambigüedad sobre la estructura de la respuesta.

En un sistema multiagente, un output es el input del siguiente agente. Si ese output no respeta un formato conocido, el agente receptor puede interpretar la información de manera incorrecta, y es precisamente en esa interpretación donde suelen aparecer las alucinaciones de acción. Al establecer un contrato de formato entre subagentes, ese margen de interpretación desaparece, reduciendo errores sin necesidad de añadir lógica adicional de validación en cada paso.

Los tres bloques que componen un Output Contract son:

Arquitectura

El sistema está compuesto por:

Un Contract Validator encargado de analizar y validar las respuestas.
Un schema base con los campos comunes.
Un schema específico por agente (Developer, Planner, Reviewer, Orchestrator, etc.).
Un conjunto de pruebas automatizadas para verificar el comportamiento.

El flujo de validación consiste en:

Extraer el envelope XML.
Parsear el JSON.
Validar los campos base.
Validar el payload contra el schema del agente.
Retornar un resultado indicando si el contrato es válido.

Implementación paso a paso

Paso 1: Crear el Schema base
El primer paso consiste en definir un Schema base con los campos obligatorios que debe incluir toda respuesta generada por un agente. Este esquema representa la estructura mínima del output y sirve como punto de partida para que todos los subagentes compartan un formato consistente antes de aplicar las validaciones específicas de cada rol.

Paso 2: Crear Schemas específicos por agente
Cada agente requiere reportar información distinta según las responsabilidades definidas en su system prompt. Por ello, cada uno cuenta con un Schema específico que amplía el Schema base, incorporando únicamente los campos necesarios para ese rol. De esta forma, se mantiene una estructura común para todos los agentes sin perder la flexibilidad de validar respuestas especializadas.

Paso 3: Modificar los system prompts de los agentes (formato del envelope)
En este paso se modifican los system prompts de los agentes que deberán responder utilizando el formato definido por el Output Contract. En este ejemplo, se actualizará el Developer, indicándole explícitamente que todas sus respuestas deben ajustarse al envelope establecido y referenciando la ubicación del Schema específico del agente para que pueda generar un output válido.

Paso 4: Crear el validador (contractValidator.js)
Una vez definidos los Schemas y configurados los system prompts, el siguiente paso es implementar el Contract Validator. Este componente será el encargado de recibir la respuesta del agente, extraer el envelope XML, parsear el payload JSON y validar tanto el Schema base como el Schema específico del agente. Si el contrato es válido, la respuesta podrá continuar con el flujo de ejecución; de lo contrario, se devolverán los errores de validación correspondientes.

Con esto validamos, en tiempo real, que la respuesta de cada agente cumpla con el contrato definido.

Esta implementación es solo un ejemplo. Si deseas ver el contenido completo del validador, puedes consultarlo en contractValidator.js

Paso 4.5: Invocar el validador
Existen dos formas de validar el output de cada agente utilizando contractValidator.js:

Usar el hook nativo tool.execute.after de OpenCode. Esta sería la solución más limpia y apropiada, ya que permitiría ejecutar automáticamente contractValidator.js después de cada respuesta del agente. Sin embargo, actualmente esta opción está bloqueada debido al *Blocked by OpenCode Issue #25918, por lo que, de momento, no es viable.

Realizar la validación desde el system prompt. Como alternativa temporal, el propio agente invoca contractValidator.js, enviando su output para ser validado. En la práctica, esta estrategia emula el comportamiento que tendría tool.execute.after y podrá reemplazarse por el hook nativo cuando este esté disponible.

Cuando el agente genera una respuesta, el proceso de validación sigue el siguiente flujo:

Se extrae el contenido del bloque .
Se parsea el payload JSON.
Se carga el Schema correspondiente al agente.
Se ejecuta validatePayload(payload, schema).
Si la validación falla, la ejecución se detiene y se solicita al agente generar nuevamente la respuesta.

¿Por qué hacerlo? Porque permite detectar errores de formato antes de que la respuesta continúe en el flujo de trabajo, garantizando consistencia entre agentes y reduciendo la propagación de errores.

Paso 5: Validar la respuesta del agente
Todo comienza con una única cadena de texto (raw input): la respuesta que produce el agente. A partir de esta salida, el validador extrae el contrato, interpreta su contenido y verifica que cumpla con la estructura esperada.

A continuación veremos un ejemplo real de la respuesta generada por un Developer después de implementar un middleware de autenticación basado en JWT.

En este ejemplo pueden identificarse claramente las partes que conforman un Output Contract:

Etiqueta XML (): marca el inicio y el final del bloque estructurado. Corresponde al formatting prompt y permite localizar de forma confiable el contenido que debe validarse.
JSON interno: contiene el payload con la información estructurada que el resto del flujo puede consumir de manera fiable.
Campos fijos (agent, timestamp, version, etc.): pertenecen al Schema base y garantizan que el Orchestrator o cualquier otro agente disponga siempre de la misma información para continuar el flujo de trabajo.

¿Qué estamos ganando con esta estrategia?
Antes (solo texto libre)
Sin un Output Contract, cada agente responde en lenguaje natural y el Orchestrator debe interpretar qué quiso decir. Esto genera múltiples problemas:

No existe un formato garantizado para las respuestas.
Cada agente puede estructurar la información de forma diferente.
Un JSON inválido o un XML mal formado puede romper todo el flujo.
El Orchestrator debe asumir e interpretar datos, aumentando las probabilidades de alucinación.
Los errores suelen detectarse tarde, cuando ya se propagaron al resto de agentes.
Integrar nuevos subagentes requiere adaptar constantemente la lógica de interpretación.

Después (Markdown + Output Contract)
Con un Output Contract, el agente deja de responder con texto libre y entrega una estructura predecible y validable.

¿Qué cambia?

El Orchestrator ya no necesita interpretar el texto para saber qué ocurrió.
El estado de la ejecución, los errores y el resultado vienen en campos explícitos.
Cada respuesta sigue exactamente el mismo formato.
El contrato puede validarse automáticamente antes de continuar el flujo.
Los agentes consumidores reciben datos consistentes, reduciendo las alucinaciones y los errores en cascada.

El Orchestrator deja de "adivinar" el significado de la respuesta y pasa a trabajar con datos estructurados y confiables. Esto hace que la comunicación entre agentes sea más robusta, predecible y fácil de mantener, especialmente a medida que la arquitectura crece en complejidad.

El resultado
La respuesta sigue siendo igual de legible para una persona; continúas leyendo el mismo texto generado por el agente. La diferencia es que, al final, se incluye un pequeño bloque estructurado (Output Contract) que el Orchestrator procesa internamente.

De esta forma, humanos y agentes consumen la misma respuesta, pero cada uno utiliza la parte que le corresponde: el desarrollador lee el contenido en lenguaje natural, mientras que el Orchestrator interpreta el contrato estructurado para continuar el flujo de trabajo de forma segura y consistente.

¿Qué mejora en la experiencia?
Si el Orchestrator puede leer esos datos estructurados, deja de depender de interpretar texto libre y puede ofrecer respuestas mucho más inteligentes y precisas. Por ejemplo, puede:

Detectar automáticamente si una tarea finalizó con éxito o falló.
Identificar el agente que produjo la respuesta y actuar en consecuencia.
Mostrar errores claros y contextualizados sin analizar lenguaje natural.
Reintentar únicamente la tarea que falló, en lugar de reiniciar todo el flujo.
Encadenar agentes de forma más confiable al consumir datos validados.
Generar métricas, auditorías y trazabilidad de cada ejecución.

En otras palabras, los Output Contracts no solo reducen las alucinaciones, sino que también mejoran la confiabilidad, la observabilidad y la experiencia general de trabajar con arquitecturas multiagente.

En resumen
No pierdes legibilidad; ganas automatización.

Tú sigues leyendo un Markdown claro, estructurado y fácil de entender.
El Orchestrator consume el JSON del Output Contract, lo valida y puede gestionar el flujo de trabajo de forma profesional, sin depender de interpretar texto libre ni de cometer errores de interpretación.

En definitiva, una misma respuesta satisface dos necesidades: una experiencia de lectura cómoda para las personas y un formato estructurado y confiable para los agentes.

El problema de la confianza ciega: cómo reducir las alucinaciones en agentes de IA parte 1

Johan Garcia — Fri, 03 Jul 2026 07:10:07 +0000

Dentro de lo que una alucinación puede hacer, encontramos:

Problemas de seguridad: Supply chain security problems, AI package hallucination.
También podemos encontrar los problemas de toda la vida: mala implementación de requerimientos por falta de controles.
Llamados incorrectos a tools.

Estaremos viendo varias estrategias y la aplicación de técnicas de prompt engineering orientadas a la reducción de alucinaciones en los LLMs (Large Language Models). Nos enfocaremos en la aplicación de agentes, subagentes y su orquestación.

Como consideración, algunas de las estrategias estarán directamente ligadas a la creación de archivos de contexto en Markdown. Estos archivos, al ser leídos por el LLM de turno, inyectarán su contenido en la context window del modelo, haciendo que el LLM disponga de nuevo contexto. A continuación veremos cómo aprovechar esto mediante las siguientes estrategias.

AGENTS.md y CLAUDE.md

Estos dos son los más conocidos hasta el momento, pero existen diferentes estándares dependiendo de la compañía o la herramienta que estemos usando. Entre ellos se encuentran:

Agentes de terminal y CLI

CLAUDE.md: El estándar oficial y nativo de Claude Code (la herramienta de línea de comandos de Anthropic).
AGENTS.md: El estándar universal y abierto, compatible con múltiples agentes autónomos dentro del ecosistema open source.

Editores de código e IDEs

.cursorrules: Utilizado por Cursor. Es el archivo más popular para proporcionar instrucciones globales de estilo y comportamiento al chat y al modo Composer dentro de este editor.
.copilotrules: Utilizado por GitHub Copilot (en VS Code y entornos JetBrains) para personalizar las respuestas del chat del copiloto.
.roo-cline-rules: Utilizado por Roo Cline (anteriormente Cline), una extensión avanzada de agente autónomo para VS Code.
.windsurfrules: Utilizado por Windsurf, el IDE de Codeium enfocado en flujos de trabajo con agentes.

Plataformas de repositorios (contexto web)

.github/copilot-instructions.md: Ubicación alternativa oficial que GitHub lee automáticamente para enriquecer el contexto de Copilot dentro de su plataforma web y en los pull requests.

Un truco profesional de configuración
Si utilizas varias herramientas al mismo tiempo (por ejemplo, programas con Cursor, pero ejecutas comandos con Claude Code desde la terminal), no necesitas copiar y pegar el mismo contenido en cuatro archivos diferentes.

Puedes crear un único archivo centralizado (como AGENTS.md) y utilizar enlaces simbólicos (symlinks) para que los demás archivos se actualicen automáticamente. Algunas estrategias son las siguientes:

Ahora bien, en lo que nos concierne como desarrolladores, ¿cómo disminuimos las alucinaciones utilizando esta estrategia?

Gestión del contexto: A medida que un proyecto crece y se agregan nuevas funcionalidades, los modelos de IA tienden a perder contexto. Como consecuencia, pueden sobrescribir código que ya funcionaba, romper reglas de negocio o proponer implementaciones inconsistentes.

Uso de archivos de contexto (CLAUDE.md, AGENTS.md, etc.): Un ingeniero de software no depende únicamente de prompts. Utiliza archivos de configuración para definir la arquitectura, las convenciones, las restricciones y las reglas del proyecto. De esta forma, la IA trabaja dentro de un marco conocido y tiene menos margen para desviarse o inventar soluciones.

Pensar en restricciones, no en prompts: La diferencia entre un usuario y un ingeniero no está en escribir mejores prompts, sino en diseñar un sistema con reglas claras. Cuantas más restricciones tenga el modelo sobre cómo debe trabajar, menor será la probabilidad de que alucine o genere cambios incompatibles con la arquitectura.

En otras palabras, un buen archivo de contexto tiene mucho más impacto que cientos de prompts aislados. En lugar de repetir instrucciones en cada conversación, se establece un marco de trabajo consistente que guía a la IA, reduce las alucinaciones y facilita detectar comportamientos incorrectos mucho antes de que lleguen a producción.

Typist y Architect

Cuando se le pide a un agente: "implementa el sistema de autenticación", el LLM debe tomar decisiones de arquitectura, diseño, estructura de carpetas, librerías y convenciones al mismo tiempo que escribe el código, todo ello sin conocer realmente el contexto del proyecto. Cada una de esas microdecisiones representa una oportunidad para generar una solución plausible, pero incorrecta para ese caso específico.

El agente no alucina porque no sepa programar; alucina porque intenta completar el contexto que el desarrollador ya tiene en su cabeza, pero que nunca le fue proporcionado.

Aquí es donde entra la estrategia Architect vs Typist. En lugar de delegar todas las decisiones al modelo, primero se define la arquitectura, las restricciones, las convenciones y las reglas del proyecto. Una vez acotado ese espacio de trabajo, el agente se limita a ejecutar dentro de esos límites, reduciendo drásticamente las posibilidades de alucinación y aumentando la consistencia del código generado.

Typist (cómo se usa la IA normalmente):

Tú: "Implementa un feature de x"
Agente: [decide estructura, elige librerías, define interfaces, escribe todo]

↑ cada decisión es una alucinación potencial

Architect (la técnica):

Tú: [defines estructura, eliges librerías, defines interfaces, estableces restricciones]
Agente: [solo escribe el código dentro de ese espacio ya definido]

↑ las decisiones ya no son del agente, solo la ejecución

Imaginemos una arquitectura de agentes con un flujo como Orchestrator → Planner → Developer → Reviewer → QA Engineer. Este es un ejemplo básico, pero podría extenderse hasta simular un equipo completo de IT compuesto por múltiples subagentes.

El problema aparece cuando el Planner comienza a tomar decisiones de arquitectura sin conocer qué patrones utiliza el proyecto, qué librerías ya están instaladas, cuáles son las convenciones de la codebase o qué trade-offs son aceptables. Todo aquello que el Planner desconoce lo completa con "lo más probable", y eso es, precisamente, una alucinación en el contexto del desarrollo de software.

Este problema se hace aún más evidente en escenarios como integrar un nuevo servidor MCP al flujo de trabajo (el agente asume una estructura inexistente), refactorizar un módulo (inventa dependencias que cree que deberían existir) o implementar una funcionalidad que involucra varios subagentes, donde cada uno toma microdecisiones distintas y termina generando inconsistencias.

La diferencia no está en cuánto código escribe el agente, sino en quién toma las decisiones de diseño.

Una estrategia eficaz para mitigar este tipo de alucinaciones es definir un Architecture Decision Record (ADR) antes de solicitar la implementación al Planner o al subagente responsable de las decisiones arquitectónicas. De esta forma, las decisiones críticas dejan de ser suposiciones del modelo y pasan a ser restricciones explícitas que todos los agentes deben seguir.

## DECISIÓN ARQUITECTÓNICA — [nombre del componente]

### Qué construir
[una sola oración, sin ambigüedad]

### Archivos involucrados
- Crear: .opencode/proxy/index.js
- Crear: .opencode/proxy/targets.js
- Crear: .opencode/proxy/semantic.js
- NO tocar: opencode.json (solo se muestra como referencia)

### Stack y librerías
- Runtime: Node.js ESM (type: module en package.json)
- MCP SDK: @modelcontextprotocol/sdk ^1.0.0 — usar StdioServerTransport
- Embeddings: @xenova/transformers — modelo Xenova/all-MiniLM-L6-v2
- NO usar: langchain, openai SDK, ni ninguna otra dependencia

### Interfaces y contratos
- El proxy recibe --target=<nombre> como arg CLI
- Expone tools/list y tools/call únicamente
- tools/list devuelve máximo TOP_K tools (default 8, configurable por env PROXY_TOP_K)
- tools/call hace forward directo sin modificar params ni resultado

### Restricciones explícitas
- Sin estado en memoria entre sesiones (cache solo en cache.json en disco)
- Sin servidor HTTP — solo stdio transport
- Auth: leer token desde ~/.local/share/opencode/mcp-auth.json, fallback a env var
- Si el archivo de tokens no existe o el token es null → lanzar error descriptivo, NO silenciar

### Lo que NO debe decidir el agente
- Estructura de carpetas (ya definida arriba)
- Qué librería de embeddings usar (ya definida)
- Cómo manejar errores de auth (ya definido)
- El valor por defecto de TOP_K (es 8)

Consideración
Esta plantilla es solo un ejemplo. Muchas de sus secciones pueden omitirse si se aprovechan correctamente archivos como AGENTS.md, donde es posible definir la arquitectura, el stack tecnológico, las convenciones del proyecto y otras restricciones globales. Del mismo modo, parte de este contexto puede vivir en el system prompt del Orchestrator o de los subagentes encargados de las decisiones arquitectónicas, como el Planner o el Spec Manager.

Cuando el Orchestrator recibe este contexto, prácticamente no hay nada que "adivinar": las decisiones de diseño ya están tomadas. El Developer simplemente traduce la especificación a código. Cabe aclarar que el ADR puede haber sido escrito previamente por el equipo o generarse automáticamente por el Spec Manager, como se verá más adelante.

El segundo gran ajuste para que esta estrategia funcione correctamente es modificar los system prompts de los subagentes. En este caso, se ajustará el Spec Manager, el agente especializado en la creación de changes con OpenSpec siguiendo la metodología SDD.

El cambio clave consiste en añadir un gate de decisión arquitectónica dentro de su system prompt. Este mecanismo determinará si es necesario crear un ADR antes de generar el change. La decisión dependerá de si el plan afecta algún aspecto arquitectónicamente significativo del proyecto.

La guía AWS Prescriptive Guidance establece uno de los criterios más utilizados en la industria: se debe crear un ADR por cada decisión arquitectónicamente significativa que impacte el proyecto, ya sea en su estructura (por ejemplo, la adopción de un patrón como microservicios) o en requisitos no funcionales como seguridad, alta disponibilidad o tolerancia a fallos. Si el cambio no afecta ninguno de estos aspectos, el Spec Manager puede generar el change sin necesidad de crear un ADR.

Ahora aplicaremos una técnica de prompt engineering conocida como one-shot/few-shot prompting. Esta consiste en proporcionar ejemplos dentro del system prompt; en este caso, al Spec Manager, para guiar su comportamiento y reducir la ambigüedad en la toma de decisiones.

A partir de este punto, continuaremos ajustando los artefactos generados por el agente, tanto el Architecture Decision Record (ADR) como los artefactos de OpenSpec, con el objetivo de que sean más consistentes, precisos y alineados con la arquitectura del proyecto.

Con esta técnica se le muestra al modelo un ejemplo concreto de entrada → salida esperada para un patrón específico, en lugar de limitarse a describir la regla de forma abstracta (por ejemplo, "ejecuta el comando delegado tal cual"). A partir de ese ejemplo, el modelo generaliza el comportamiento y lo aplica a comandos similares que no estaban presentes en el prompt, reduciendo la ambigüedad y aumentando la consistencia de sus respuestas.

Ahora continuaremos con el contenido del comando /opsx-adr, el cual sigue la metodología Command Driven Development (CDD) y extiende el conjunto de comandos proporcionados por OpenSpec.

---
description: Create an Architecture Decision Record (ADR) for an existing change, capturing a significant architectural decision
---

Create an Architecture Decision Record (ADR) for a change that has already been explored and proposed.

I'll create an ADR that:
- documents the decision made, the alternatives considered, and its consequences
- lives outside the change folder so it persists after the change is archived
- stays in `Proposed` status until @reviewer accepts it during `/opsx-verify`

This command does not decide whether an ADR is needed — that decision is made by @orchestrator or @planner before this command is delegated. `/opsx-adr` only executes the creation.

---

**Input**: The argument after `/opsx-adr` is the change name (kebab-case) this decision belongs to. Optionally, `--supersedes <adr-id>` if this decision replaces a previously accepted ADR.

**Steps**

1. **If no input provided, ask which change this ADR belongs to**

   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
   > "Which change is this architectural decision for? Provide the change name."

   **IMPORTANT**: Do NOT proceed without a valid, existing change name — an ADR cannot be created standalone, only against an already-explored change.

2. **Verify the change has enough context to justify an ADR**
   openspec status --change "<name>" --json

   Confirm the `proposal` and `design` artifacts both show `status: "done"`. If either is missing or pending, halt and report:
   > "ADR requires a completed design before it can be created — run /opsx-propose first."

3. **Confirm the schema supports ADRs**

   Parse the `artifacts` array from step 2. If `adr` is not listed, halt and report:
   > "This project's schema doesn't define an ADR artifact. Switch to the spec-driven-with-adr schema in openspec/config.yaml."

4. **Get ADR instructions**
   openspec instructions adr --change "<name>" --json

   Parse:
   - `context`, `rules`: constraints for you (never copied into the output file)
   - `template`: structure to use for the ADR
   - `instruction`: schema-specific guidance for this artifact type
   - `outputPath`: where to write it (outside `changes/`, under `openspec/adr/`)
   - `dependencies`: `proposal.md` and `design.md` — read these for context before writing

5. **If `--supersedes <adr-id>` was provided**
   - Read the referenced prior ADR at its existing path for context
   - Reference it in the new ADR's "Supersedes" section
   - Do NOT edit the prior ADR's content or status here — the actual status change on the prior ADR happens during `/opsx-verify`, when @reviewer accepts the new one

6. **Create the ADR file**
   - Use `template` as the structure — fill in its sections
   - Ground `Context` in the problem statement from `proposal.md`
   - Ground `Decision` and `Alternatives Considered` in the approach discussion from `design.md`
   - Set `Status: Proposed`
   - Show brief progress: `"Created adr"`

7. **Show final status**
   openspec status --change "<name>"


**Output**

After creating the ADR, summarize:
- ADR file path and the change it belongs to
- Status: `Proposed`
- Prompt: "Ready for @reviewer to accept during `/opsx-verify`."

**Artifact Creation Guidelines**

- Follow the `instruction` field from `openspec instructions adr` for what the ADR should contain
- Read `proposal.md` and `design.md` before writing — the ADR is grounded in the change, never invented independently
- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file — never copy them into the output
- Never set `Status` to anything other than `Proposed` on creation — acceptance is a review-time decision, not a creation-time one

**Guardrails**
- Never create an ADR for a change without a completed `design.md`
- Never overwrite an existing ADR for this change without `--supersedes` — if one exists, ask the user whether to supersede it
- Never modify a prior ADR's content or status when superseding — only reference it in the new file
- Verify the ADR file exists after writing before reporting success

Una aclaración
Actualmente trabajo con un setup de orquestación de agentes basado en OpenCode y OpenSpec (SDD). En este punto es normal que la estrategia de los ADR pueda parecer confusa o que surjan dudas sobre cómo está construido todo el flujo.

La idea de esta serie es ir presentando el setup, las configuraciones y las implementaciones de forma progresiva. Un ejemplo de ello es la extensión de OpenSpec mediante /opsx-adr, un comando que desarrollé para integrar los Architecture Decision Records (ADR), ya que no forma parte del conjunto de comandos nativos de OpenSpec.

Si quieres comprender mejor cómo conviven los ADR con OpenSpec dentro de este flujo de trabajo, te recomiendo la siguiente lectura.

Architectural Decision Records with Spec-Driven Development using OpenSpec

Aun implementando estas estrategias, es posible que las alucinaciones sigan apareciendo. Sin embargo, su incidencia suele ser considerablemente menor que cuando no se aplica ningún tipo de control sobre el contexto, la arquitectura o el comportamiento de los agentes.

También es importante aclarar que este artículo no aborda la creación de agentes en las diferentes herramientas disponibles en el mercado. Cada plataforma tiene su propia forma de definirlos. Por ejemplo, en OpenCode basta con referenciar el archivo Markdown que contiene el system prompt del agente desde el archivo opencode.json, mientras que en Claude Code este suele ubicarse directamente en .claude/agents/agent-system-prompt.md.

En las siguientes entregas se profundizará en la composición de los system prompts y en el uso de distintas técnicas de prompt engineering para redactar instrucciones más precisas y obtener agentes más consistentes.

Por último, cabe aclarar que esta será una serie de artículos de carácter incremental. Muchas de las estrategias que se abordarán son relativamente avanzadas y sería difícil explicarlas con el nivel de detalle necesario en un único artículo.

AI Agents no son magia: cómo construí un equipo de 7 especialistas que desarrollan software sin alucinar

Johan Garcia — Fri, 22 May 2026 00:28:26 +0000

Todos probamos asistentes de código con AI. Al principio impresionan: escribes un comentario y te generan un endpoint completo. Te sentís como Tony Stark. Luego aparece la realidad. A las cinco interacciones, el agente pierde el contexto.

Te importa una librería que no existe. Mezcla la lógica de autenticación con la de base de datos.

Te manda un PR que no compila. Y mientras tanto, quemás tokens como si fueran infinitos. El problema no es la AI.

El problema es que la tratamos como un oráculo, no como un equipo. Le pedimos que haga todo a la vez: entender el requerimiento, diseñar la arquitectura, escribir el código, revisar su propio trabajo y hacer el commit. Eso no es cómo funciona la ingeniería de software. Y tampoco es cómo debería funcionar cuando la AI está en el medio.

La solución un orquestador

En vez de un solo agente que intenta hacer todo, construí un sistema con 8 agentes especializados.

La arquitectura es simple:

1 Orchestrator: el coordinador. No escribe código. No hace reviews. Solo recibe tu pedido, entiende qué se necesita, delega al subagente correcto y trackea el progreso.
7 Subagents: cada uno con un rol acotado y bien definido.

[DIAGRAM: Diagrama mostrando Orchestrator en el centro conectado a los 7 subagentes con etiquetas de sus responsabilidades Los subagentes tienen responsabilidades que no se solapan:

Cada agente sabe exactamente qué le toca y, más importante, qué NO le toca. Esto no es "poner un montón de prompts en un archivo". Es aplicar el mismo principio que usamos en backend: separación de responsabilidades.

No todos los agentes usan el mismo modelo de AI. Y eso es intencional.

Tareas simples: Escribir specs, revisar código, gestionar archivos —usan modelos baratos y rápidos. No necesitás un modelo de 200B de parámetros para revisar si un middleware valida un token.
Tareas complejas implementación de features, resolución de bugs difíciles usan modelos más capaces y más caros. Ahí sí vale la pena invertir. Cada agente tiene permisos granulares definidos en su configuración:

El developer puede escribir archivos y ejecutar comandos bash.
El reviewer solo puede leer y comentar. No toca nada.
El orchestrator solo puede delegar tareas a otros agentes.

Esto es el principio de mínimos privilegios aplicado a agentes de AI. Si un agente no necesita escribir archivos, no debería poder hacerlo. Punto.

El resultado: menos superficie de error, menos alucinaciones, y costos predecibles.

El truco — `/grill-me` y `/caveman` (Skills)

Acá es donde la cosa se pone interesante.

/grill-me: la entrevista antes del código Antes de escribir cualquier spec o línea de código, el sistema te entrevista.

No es un "¿qué querés hacer?" y ya. Es una conversación estructurada que recorre cada rama del árbol de decisiones:

> *"¿Qué pasa si el endpoint recibe datos malformados?"* 
> *"¿Cómo manejamos autenticación vs autorización?"* 
> *"¿Cuál es el alcance exacto de este cambio?"* 
> *"¿Hay edge cases que no estamos viendo?"*

El usuario debe confirmar entendimiento compartido antes de que la AI toque un solo archivo. Esto eliminó el problema #1 de los asistentes de código: hacer rápido lo incorrecto.

Porque el mayor desperdicio no es que la AI sea lenta. Es que sea rápida en la dirección equivocada.

/caveman: comunicación comprimida Los tokens cuestan plata. Y el tiempo del dev también. /caveman es un protocolo de comunicación que reduce el uso de tokens ~75%. Elimina artículos, filler y cortesías innecesarias:

> *"Sure, I'd be happy to help you with that! Let me take a look at the authentication middleware and see what might be causing the issue..."*  

Se convierte en:  

> *"Fix auth middleware. Token expiry uses `<` not `<=`."*  

No es ser grosero. Es ser preciso.

Además, hay una regla de las 20 palabras: si un agente necesita más de 20 palabras para explicar un concepto recurrente, ese concepto se comprime en un glosario central (CONTEXT.md). La próxima vez, el agente solo referencia el término. El efecto compuesto es exponencial:

CONTEXT injection → todos los agentes comparten el mismo vocabulario
Regla de 20 palabras → los conceptos repetidos se comprimen
Caveman mode → la comunicación va directo al grano Menos tokens = menos costo = más interacciones útiles antes de que el contexto se sature.

Ambas skill pertenecen a Matt Pocock y aqui su repositorio → GitHub

Tambien pueden encontrar estas skill en Skills.sh

Spec-Driven Development

Meses atrás, cuando el vibe coding estaba en auge, vi bastante claro hacia dónde iba el problema: desarrollar software sin ningún tipo de control, proceso o sistema estaba destinado a fallar tarde o temprano.

Esa idea terminó de confirmarse cuando un cliente me contactó para ayudarle a arreglar el desastre que había generado utilizando este enfoque. Lo más curioso es que, hasta cierto punto, el sistema “funcionaba”, pero era completamente insostenible.

La aplicación no escalaba, no existían medidas reales de seguridad, no había separación de responsabilidades ni estándares mínimos de calidad. Todo el código estaba altamente acoplado, lleno de lógica duplicada y sin buenas prácticas de desarrollo. Honestamente, me sorprendió que la aplicación siguiera funcionando; parecía hacerlo por pura inercia.

Leer, entender y limpiar ese codebase fue un auténtico infierno.

Y ahí es donde entra Spec Driven Development (SDD).

No voy a profundizar demasiado en el tema porque no es el objetivo principal de esta entrada, pero sí considero importante mencionarlo: SDD es un enfoque de desarrollo que busca aportar coherencia, estructura y control al desarrollo de aplicaciones asistidas por AI.

La idea no es únicamente generar código más rápido, sino construir sistemas mantenibles, escalables y entendibles, donde exista trazabilidad entre requerimientos, decisiones técnicas, arquitectura e implementación.

Para más información, recomiendo revisar la documentación oficial de OpenSpec → Aqui

También recomiendo este artículo, que considero especialmente valioso de Hari Krishnan → Spec-Driven Development with OpenSpec - Source of Truth Specification

Ahora mi modificación:

La fase 0 (/grill-me) asegura que el plan es correcto antes de invertir tiempo en escribirlo. Esto no es más burocracia. Es la misma disciplina que usamos en ingeniería de software escribir tests antes del código, diseñar la API antes de implementarla pero aplicada a cómo hablamos con la AI.

La diferencia es que antes esa disciplina vivía en la cabeza del senior. Ahora vive en el sistema., esto se combina con la fase de exploracion de OpenSpec para generar Artefactos mas solidos

MCPs: los plugins del sistema

MCP (Model Context Protocol) es el protocolo que conecta los agentes con servicios externos. Piensalo como los plugins del ecosistema: sin ellos, los agentes operan en el vacío.

Dos MCPs están configurados en este sistema:

Composio: Conecta con Trello para project management. El project-manager puede crear cards, moverlas entre listas y actualizar estados sin salir del terminal. El progreso del sprint queda trackeado automáticamente.
Context7: Documentación técnica actualizada al instante. Cuando el developer implementa un endpoint con Express o define un schema con Prisma, consulta la API más reciente en lugar de confiar en su training data. Esto elimina las alucinaciones de imports y APIs deprecadas.

Esto cierra el loop completo: specs escritas en archivos versionados, implementación con documentación fresca, y tracking automático en Trello. Nada queda en el aire.

Algo importante a tener en cuenta al utilizar el protocolo MCP dentro de arquitecturas basadas en agentes es que las tools registradas por cada MCP se cargan directamente en el contexto del modelo. Esto puede generar conflictos o ejecuciones no deseadas de comandos entre agentes, especialmente en arquitecturas con múltiples responsabilidades y acceso compartido a herramientas.

Para evitar este tipo de problemas, es recomendable restringir qué agentes pueden acceder a determinados MCPs. Esto puede controlarse desde la configuración de opencode.json o directamente desde el system prompt de cada agente, definiendo explícitamente sus capacidades, límites y herramientas disponibles.

Comparto tanto la configuración de la arquitectura en OpenCode como los system prompts de cada uno de los agentes. Toda esta información está en inglés, ya que los modelos suelen ofrecer mejores resultados cuando trabajan en el idioma principal con el que fueron entrenados.

No adjunto archivos como CONTEXT.md ni AGENTS.md / CLAUDE.md. El primero funciona principalmente como un diccionario compartido para estandarizar el lenguaje entre agentes y ayudar a reducir el consumo de tokens ligado a /caveman. El segundo corresponde a archivos de configuración y contexto operativo del sistema.

Configuración de opencode → Aqui

System Prompts de cada unos de los agentes → Aqui

La arquitectura implementa un enfoque híbrido combinando Intent Driven Development y Command Driven Development.

La fase inicial comienza con /grill-me, considerada como la fase 0 del flujo. En esta etapa, el orquestador es responsable de realizar la entrevista, validar requerimientos y consolidar el contexto funcional y técnico del problema esto es Intent Driven.

Una vez los requerimientos son suficientemente sólidos y consistentes, el subagente spec-manager entra en acción para encargarse de la creación de los artefactos de OpenSpec y estructurar formalmente las especificaciones del proyecto y aqui empezamos a hacer Command Driven.

Otros apartados que no mencioné anteriormente, pero que también forman parte importante de esta arquitectura, son los procesos de automatización alrededor del ciclo de integración y gestión operativa del proyecto.

Uno de ellos fue la automatización completa del flujo de integración de código en GitHub mediante slash commands. Todo el ciclo puede ejecutarse desde la terminal: generación de commits, estandarización de mensajes, validaciones y procesos de push, reduciendo fricción operativa y manteniendo consistencia dentro del flujo de trabajo.

Otro enfoque que también terminó formando parte de la arquitectura fue la automatización de gestión en Trello bajo un modelo Command Driven. Esto permitió administrar tarjetas, estados y operaciones del tablero directamente desde la TUI (Terminal User Interface) utilizando slash commands.

La idea detrás de este enfoque no era únicamente automatizar tareas repetitivas, sino convertir la terminal en un centro operativo unificado donde los agentes, comandos y flujos de trabajo convivieran dentro de un mismo ecosistema.

Nota final

Este enfoque aún se encuentra en una etapa de maduración, pero ya cuenta con una base sólida y funcional. A futuro, la idea es incorporar memoria persistente mediante herramientas como Engram, además de continuar refinando la arquitectura hasta convertirla en una solución mucho más robusta y profesional.

Actualmente, gran parte del trabajo está centrado en laboratorios y pruebas experimentales alrededor de skills, MCPs, técnicas de orquestación y distintos enfoques de desarrollo con agentes.

Toda esta base también está respaldada por experiencia práctica acumulada durante aproximadamente 7 años trabajando en desarrollo de software, arquitectura y resolución de problemas reales.

Camino a CI/CD pruebas (Testing)

Johan Garcia — Fri, 10 Apr 2026 05:09:40 +0000

El stage de testing es, en la mayoría de pipelines, la etapa que sigue después de la compilación o build. En este punto, el sistema ya es ejecutable, pero aún no es confiable.

Aquí es donde entra el testing: no como un paso opcional, sino como el filtro que evita que errores, regresiones o comportamientos inesperados lleguen a producción.

En esta sección, se busca responder una pregunta clave:

¿Qué debería tener un pipeline a nivel de testing para considerarse realmente sólido?

Tipos de Testing

1. Testing Funcional

El testing funcional valida que el sistema haga lo que se espera que haga. Es decir, se enfoca en el comportamiento, no en cómo está implementado.

Unit Testing (Pruebas Unitarias)

Las pruebas unitarias validan las piezas más pequeñas del sistema: funciones, métodos o componentes individuales.

Su objetivo es detectar errores lo más temprano posible, antes de que escalen.

Qué cubren normalmente:

Lógica de negocio aislada
Validaciones
Transformaciones de datos
Casos borde

Aquí no importa el sistema completo, solo que esa unidad funcione correctamente.

Integration Testing (Pruebas de Integración)

Aquí se sube un nivel: ya no se prueba una pieza aislada, sino cómo interactúan varias partes del sistema.

El objetivo es validar que los componentes colaboren correctamente.

Qué suele incluir:

Componentes + servicios
Acceso a base de datos
APIs simuladas (MSW, mocks controlados)

Ejemplo conceptual:

Un componente llama a un servicio → el servicio consulta datos → el resultado se renderiza correctamente.

Si alguna de esas piezas falla en conjunto, el test lo detecta.

End-to-End Testing (E2E)

Las pruebas E2E validan el sistema completo desde la perspectiva del usuario.

Simulan flujos reales en un entorno lo más cercano posible a producción.

Ejemplo típico:

El usuario entra a la app
Hace login
Crea un registro
Lo visualiza en pantalla

Si todo eso funciona, el sistema cumple su propósito en ese flujo.

Smoke Testing

El smoke testing responde una única pregunta:

¿El sistema funciona lo suficiente como para seguir probándolo?

Se ejecuta justo después del build, y actúa como un primer filtro.

Si falla aquí, no tiene sentido continuar.

Ejemplo:

¿La app levanta?
¿El login responde?
¿una ruta principal carga?

No valida lógica profunda ni reglas complejas.

Solo verifica lo esencial.

Este test no valida:

expiración del token
roles
seguridad avanzada

Solo valida algo clave: “¿el login funciona?”, Si esto falla, todo lo demás deja de tener sentido.

Sanity Testing

El sanity testing es un chequeo rápido y enfocado después de un cambio puntual.

No busca validar todo el sistema, sino algo muy concreto:

¿Lo que se modificó sigue funcionando sin romper lo demás?

Se usa cuando:

Hay un bug fix
Se hace un refactor pequeño
Se ajusta una funcionalidad específica

Características:

Dirigido (no exploratorio)
Ligero (no exhaustivo)
Rápido (busca confianza inmediata)

Regression Testing

El regression testing protege el sistema a medida que evoluciona.

Cada cambio introduce riesgo, y este tipo de pruebas actúa como una red de seguridad.

Valida que:

Lo que funcionaba → siga funcionando
Los cambios → no generen efectos colaterales

No se enfoca en lo nuevo, sino en evitar que lo existente se rompa.

User Acceptance Testing (UAT)

Es la fase donde el sistema deja de evaluarse como “código que funciona” y pasa a validarse como “producto que resuelve un problema real”. Aquí ya no importa tanto si la lógica interna está bien implementada, sino si lo que se construyó realmente cumple con lo que el usuario o el negocio esperaba.

En otras palabras, es el momento en el que alguien del lado del negocio no necesariamente un desarrollador usa la aplicación en escenarios reales y responde una pregunta clave: ¿esto sirve para lo que se necesitaba?

A diferencia de otros tipos de testing:

No se centra en funciones aisladas.
No valida detalles técnicos.
No busca bugs “técnicos” principalmente.

Se enfoca en algo mucho más importante:

Validar que el sistema cumple con los requisitos funcionales desde la perspectiva del usuario final.

Ejemplo

Contexto: Un módulo de inventario.

Requisito de negocio:
“El usuario debe poder registrar un producto y verlo reflejado en el inventario.”

UAT:
Escenario:

El usuario crea un producto: Nombre: “Laptop” Cantidad: 5
Guarda el registro
Va al listado de inventario

Resultado esperado:

El producto aparece
La cantidad es correcta

No hay inconsistencias

Si eso pasa, el sistema cumple el requisito, aunque internamente pueda tener mejoras técnicas pendientes.

Tipos de UAT que suelen aparecer
Aunque muchas veces se agrupan como uno solo, en la práctica se ven variantes:

Alpha Testing → interno (equipo del producto)
Beta Testing → usuarios reales
Business UAT → validación contra requisitos del negocio
Operational UAT → validación en condiciones reales (ambiente, datos, etc.)

Consideraciones

El UAT no lo hace el desarrollador

Normalmente lo ejecutan:

Stakeholders
QA con enfoque de negocio
Cliente final

Porque lo que se valida no es el código, sino la utilidad real del sistema.

Su finalidad es

Ejecutarse en entornos de staging
Ser parcialmente manual (aunque puede automatizarse con criterios de aceptación)
Actuar como último gate antes de producción

Contract Testing

Este tipo de testing se vuelve crítico en arquitecturas distribuidas.

Valida que dos sistemas que se comunican (por ejemplo, frontend y backend) respeten un contrato.

Ese contrato define:

Request
Response
Tipos de datos
Campos obligatorios

Problema típico que resuelve:

El backend funciona, sus tests pasan… pero el frontend se rompe.
El contract testing evita ese tipo de desalineaciones.

El backend funciona
Los tests del backend pasan
Pero el frontend se rompe

Aquí es donde el Contract Testing evita el desastre.

Tipos de Contract Testing
Consumer-Driven Contract Testing (el más usado)
El consumidor (frontend) define lo que necesita.

Ejemplo

Provider Verification
El backend valida que cumple ese contrato.

Ejemplo

2. Testing No Funcional
Aquí no se valida qué hace el sistema, sino cómo se comporta.

Performance Testing
Se centra en evaluar cómo se comporta una aplicación bajo distintas condiciones de carga, no desde la lógica funcional, sino desde atributos como tiempo de respuesta, throughput, uso de recursos y estabilidad. En términos prácticos, lo que se busca es responder preguntas como: ¿cuántos usuarios simultáneos puede soportar el sistema?, ¿qué tan rápido responde bajo presión?, ¿en qué punto comienza a degradarse? Este tipo de pruebas es clave en sistemas reales porque muchos fallos no aparecen en desarrollo, sino cuando el sistema enfrenta tráfico real. Dentro de este enfoque se incluyen variantes como load testing, stress testing y spike testing, cada una orientada a distintos patrones de carga.

Ejemplo

El el ejemplo anterior se simulan 50 usuarios concurrentes durante 30 segundos haciendo peticiones al mismo endpoint. Si el sistema responde rápido y sin errores, el comportamiento es aceptable. Si el tiempo de respuesta aumenta significativamente o aparecen errores (timeouts, 500), entonces ya se está evidenciando un problema de rendimiento.

Security Testing
Aunque forma parte del testing, muchas veces se maneja como un stage independiente.

Incluye:

SAST - Static Application Security Testing (análisis estático)
DAST - Dynamic Application Security Testing (análisis dinámico)
SCA - Software Composition Analysis
Secrets Detection
Container Security
IaC, API, y Compliance
Security Headers
Dependency Scanning

Mutation Testing (Pruebas de Mutación)
El mutation testing pregunta: "Si introduzco un pequeño bug en mi código, ¿mis pruebas realmente lo detectarán?" Esto revela la diferencia crítica entre cobertura de pruebas y efectividad de pruebas.

El resultado se mide con el mutation score.

Ejemplo

Herramientas

Testing Unitario e Integración

Jest (JavaScript/TypeScript)
Pytest (Python):
JUnit (Java)
NUnit (C#/.NET)

Testing E2E y UI

Selenium: Arquitectura empresarial de Selenium Python con Pytest, Allure y patrones de diseño GitHub
Cypress
Playwright
Puppeteer

Contract Testing

Pact: Flujo típico con Pact:
- El frontend define el contrato
- Se guarda como archivo (.json)
- El backend ejecuta tests contra ese contrato Si algo no coincide → falla el pipeline

Testing Performance

Locust (Python)
K6 (JavaScript/TS): Ofrece integración nativa con CI/CD y la nube.
Gatling (Java/Kotlin/JS/Scala)
Apache JMeter Java/GUI): Ideal para equipos QA tradicionales y empresas, siendo opensource.
Atillery (Node.js/YAML)
Vegeta (Go)

Alternativas en la nube para Testing performance

BlazeMeter: Permite ejecutar scripts de JMeter, k6, Locust y Gatling en la nube
LoadNinja: Se enfoca en pruebas con navegadores reales en lugar de simular protocolos, lo que da métricas de experiencia de usuario más precisas. No requiere programación
Azure Load Testing: Un servicio gestionado por Microsoft que permite subir scripts de JMeter y ofrece integraciones profundas con el ecosistema de Azure.
OctoPerf: Diseñado específicamente para usuarios de JMeter que quieren una interfaz web moderna

Testing Mutation

PIT (PITest) para Java con escalabilidad empresarial.
Stryker Mutator con soporte multi-lenguaje (JavaScript, TypeScript, C#, Scala).
MutPy para Python.
Infection para PHP.

Un buen stage de testing no se define por la cantidad de herramientas o tests, sino por su capacidad de generar confianza.

Al final, todo se resume en esto:

Detectar errores lo antes posible, con el menor costo posible, y antes de que impacten al usuario.

Si el pipeline logra eso, entonces está bien diseñado.

Como potenciar tu VS Code con Continue.dev Cline

Johan Garcia — Fri, 25 Apr 2025 05:36:10 +0000

Hoy en día, vemos la inteligencia artificial (IA) en todas partes, y no es de extrañar que, en el mundo del desarrollo de software, se estén explorando una gran variedad de usos. Un claro ejemplo son los editores de código con integración de IA, como Cursor.ai, Windsurf o el más reciente Firebase Studio. Estas herramientas ofrecen funcionalidades avanzadas, como autocompletado inteligente y generación o edición de código a partir de prompts.

Hace unas semanas estuve probando tanto Cursor como Windsurf en algunos de mis proyectos personales, y, sinceramente, es increíble lo que se puede lograr cuando sabes bien lo que estás haciendo. Investigando un poco más, encontré una forma de darle “músculo” a Visual Studio Code —recordemos que Cursor y Windsurf están basados en VS Code—, ya que este, por defecto, no incluye muchas de las características que sí ofrecen estas versiones modificadas de pago.

La solución: integrar Continue.dev y Cline, dos extensiones poderosas y open source para VS Code, que transforman tu editor en un verdadero IDE con esteroides. En este artículo te voy a mostrar cómo configurarlas paso a paso, qué modelos puedes usar, sus limitaciones y por qué esta combinación puede convertirse en tu nuevo entorno favorito para programar con IA.

REQUISITOS PREVIOS

Tener Visual Studio Code instalado.
Contar con una cuenta gratuita en Groq y OpenRouter.
En el apartado de extensiones de VS Code, buscar la extensión Continue y asegurarte de seleccionar al desarrollador: Continue.

Al instalarla, se creará una carpeta llamada .continue/ en la raíz de tu espacio de trabajo, que suele ubicarse en C:\Users\user. (Es importante tener presente este punto)

Luego, en el mismo apartado de extensiones de VS Code, buscar la extensión Cline y seleccionar al desarrollador: Cline.bot.

Existen otros proveedores de modelos de IA, como Together AI, pero, al parecer, este no ofrece modelos open source.

¿Cómo funciona Continue.dev?
Continue.dev actúa como un asistente inteligente dentro de Visual Studio Code. Sus principales funciones incluyen:

Leer y analizar tu código fuente.
Completar funciones o bloques de código completos.
Editar fragmentos mediante prompts.
Responder preguntas técnicas o sugerir mejoras.
Leer el contexto del proyecto (archivos, terminal, errores, etc.).

Está especialmente orientado a desarrolladores que desean integrar modelos de lenguaje (LLMs) para mejorar su flujo de trabajo, particularmente en proyectos de tamaño mediano a grande.

¿Cómo funciona Cline?
Cline es un complemento para VS Code que permite crear un agente personalizado impulsado por LLMs, capaz de ejecutar comandos, navegar entre archivos y mantener conversaciones contextuales. A diferencia de Continue.dev —que se enfoca principalmente en la edición y el completado de código—, Cline está orientado a establecer un flujo de trabajo interactivo bajo un enfoque agente-usuario.

Con Cline puedes:

Chatear con un agente inteligente directamente desde el editor.
Ejecutar tareas específicas mediante comandos configurables.
Definir skills (habilidades) que combinan instrucciones con ejecución de código.
Personalizar completamente el comportamiento del agente mediante archivos YAML.

Está pensado para usuarios avanzados que buscan automatizar flujos repetitivos o construir asistentes que no solo respondan con texto, sino que también ejecuten acciones dentro del entorno de desarrollo.

Archivo config.yaml: explicación completa
El archivo .continue/config.yaml es el núcleo de la configuración de Continue.dev. A través de este archivo puedes definir:

Los modelos a utilizar: como Groq, OpenRouter u otros compatibles con Continue.
El comportamiento de cada modelo: incluyendo roles, mensajes del sistema, temperatura, y otras configuraciones específicas que controlan cómo responde el modelo.
El contexto que tendrá el agente: qué archivos, errores o entradas del terminal podrá leer para generar respuestas más precisas y útiles.

Ejemplo con Groq y OpenRouter:

Explicación de propiedades clave del archivo config.yaml

name: Nombre visible del asistente o modelo en la interfaz de Continue.
provider: Proveedor del modelo, como groq, openrouter, entre otros.
model: Identificador del modelo específico ofrecido por el proveedor.
apiKey: Clave de autenticación necesaria para conectarse con el proveedor.
roles: Define las funciones que puede desempeñar el modelo, como chat, autocomplete o edit.
systemMessage: Mensaje base que establece el comportamiento general del asistente (por ejemplo, su tono, propósito o enfoque).
context: Determina qué fuentes de información se usarán como contexto, como archivos de código, terminal, errores, etc.
apiBase: Dirección base para la conexión con la API, necesaria en algunos proveedores como Groq.
Limitaciones de Continue.dev
No todos los modelos soportan todas las funciones. Por ejemplo, algunos modelos no permiten funciones como edición (edit) o autocompletado (autocomplete). En estos casos, Continue mostrará una alerta indicando qué modelo y qué rol no son compatibles.
No permite entrenamiento ni afinado de modelos desde la interfaz.
Algunas integraciones pueden requerir configuración manual (por ejemplo, definir rutas o parámetros específicos).
Depende en gran medida del modelo seleccionado: si el modelo es limitado, la calidad de las respuestas también lo será.

Limitaciones de los modelos: Groq vs OpenRouter
Groq

Totalmente gratuito y sin necesidad de tarjeta de crédito.
Modelos disponibles: LLaMA 3, Mixtral, Gemma.
Ofrece alta velocidad de respuesta, ideal para flujos interactivos.
Limitado a los modelos disponibles en su plataforma.
No permite configuración avanzada, como ajuste fino (fine-tuning).

OpenRouter

Funciona como un proxy que da acceso a múltiples modelos (Claude, Mistral, GPT, entre otros).
Algunos modelos ofrecen un uso gratuito limitado, mientras que otros requieren pago por uso.
Dispone de una versión gratuita diaria, aunque esta puede agotarse rápidamente si hay alta demanda.
Mayor flexibilidad de modelos, pero con una experiencia menos homogénea según el proveedor seleccionado.

Cuando accedemos a Continue.dev dentro de Visual Studio Code, inicialmente solo contaremos con un asistente por defecto llamado "My First Assistant". Este asistente viene preconfigurado y es completamente funcional desde el primer momento.
Además, desde el sitio web de Continue.dev, es posible seleccionar otros modelos disponibles con uso limitado gratuito, sin necesidad de configurarlos manualmente. Sin embargo, para un control total y acceso a modelos más potentes o personalizados, lo ideal es editar el archivo config.yaml como vimos anteriormente.

En nuestro caso, crearemos un agente personalizado de manera local, el cual dependerá directamente de la configuración definida en nuestro archivo config.yaml (como se mostró en la imagen anterior).

Este archivo será la clave para conectar con proveedores como Groq u OpenRouter, permitiéndonos aprovechar modelos avanzados de lenguaje de forma gratuita o bajo demanda, según el proveedor elegido.

Una vez que hayamos seleccionado y configurado los modelos que vamos a utilizar dentro de Continue.dev, deberíamos tener una vista similar a la que se muestra en la imagen superior.

Con esta configuración, Continue.dev ya estará funcionando correctamente, y solo nos queda comenzar a probar sus funcionalidades: autocompletado, chat o edición, siempre y cuando el modelo seleccionado lo permita.

Ahora continuaremos con Cline. Utilizar esta extensión es mucho más sencillo, siempre y cuando hayamos creado correctamente nuestras API keys en Groq, OpenRouter u otro proveedor de modelos.

Para agregar un modelo en Cline, simplemente seleccionamos la opción "Use your own API key", y desde ahí podemos conectar el modelo que deseamos utilizar con la extensión.

Si seleccionamos la opción "Get started for free", obtendremos acceso al modelo Claude 3.7 con ciertas limitaciones. Este acceso forma parte del free trial que ofrece Cline, el cual es ideal para hacer pruebas rápidas y conocer el funcionamiento de la herramienta.

Una vez que se agote el periodo gratuito, podemos continuar usando Cline integrando un proveedor externo, como Groq o OpenRouter, utilizando nuestra propia API key.

Recomiendo usar OpenRouter como proveedor dentro de Cline, ya que ofrece una amplia gama de modelos disponibles, como Qwen 2.5, LLaMA 3 o Gemini 2.5 Flash. Es importante tener en cuenta que la disponibilidad de estos modelos puede variar dependiendo del momento en que realices la implementación dentro de VS Code.

Por lo tanto, es recomendable verificar qué modelos están accesibles al momento de configurar el agente para asegurarse de elegir el más adecuado según las necesidades del proyecto.

Es importante tener en cuenta que, dado que estamos utilizando modelos opensource, la principal limitación es el tiempo de respuesta o los timeouts, especialmente debido al alto volumen de uso por parte de la comunidad.

Cline está diseñado específicamente para realizar cambios en tu código, lo que lo convierte en un asistente AI. Ambas extensiones, Continue.dev y Cline, pueden ser particularmente útiles en situaciones donde no tengamos acceso a internet y estemos trabajando con un modelo alojado localmente en nuestra PC.

Ahora bien, las letras pequeñas de usar un modelo local son las siguientes: deberás seleccionar un modelo que se ajuste a las especificaciones de tu computadora. Es crucial tener en cuenta los recursos de tu equipo (memoria, procesador, etc.) para evitar problemas de rendimiento.

Cuando trabajamos con un modelo local, podemos integrarlo tanto a Continue.dev como a Cline, lo que nos permite aprovechar las ventajas de ambas herramientas incluso sin conexión a internet.

Internacionalización en Aplicaciones React con i18next

Johan Garcia — Sat, 18 Jan 2025 22:53:57 +0000

Cada dia el mundo esta conectado, ofrecer contenido accesible en múltiples idiomas se ha convertido en una necesidad fundamental para aplicaciones modernas. En este artículo, abordaremos cómo implementar internacionalización en aplicaciones React utilizando i18next, una biblioteca flexible y poderosa para la gestión de traducciones.

¿Qué es la internacionalización de aplicaciones web?

Con la internacionalización (i18n) damos la capacidad a nuestras aplicaciones de ser adaptables a diferentes idiomas y regiones sin la necesidad de realizar cambios en su código fuente.

Esto incluye la traducción de textos, la adaptación de formatos de fecha, moneda, números y cualquier otro aspecto que varíe según la localización cultural de los usuarios.

¿Qué es i18next y por qué utilizarlo?

i18next es una solución popular de internacionalización que simplifica la gestión de traducciones en aplicaciones web, móviles y de escritorio. Ofrece soporte para:

Carga dinámica de idiomas.
Interpolación de variables en textos.
Gestor de recursos centralizado para traducciones.
Cambio de idioma en tiempo real.

Existen otras opciones a i18next, como lo son react-intl, LinguiJS, Polyglot.js, MessageFormat.js y Globalize, pero nos centraremos en i18next, ya que es una librería muy popular, cuenta con un buen número de descargas semanales en npm.js y destaca por su simplicidad a la hora de ser configurada en una aplicación de React.js.

A lo largo de este artículo, exploraremos cómo configurar y utilizar i18next en una aplicación React paso a paso.

Instalación y configuración

Comenzaremos instalando i18next junto con su paquete adaptador para React:

Una vez instalados los paquetes necesarios para la configuración de i18next, configuraremos la instancia principal de i18next en un archivo dedicado, por ejemplo, i18n.js.

Ahora crearemos los archivos que van a contener nuestras traducciones (es.json y en.json). Para ello, crearemos una carpeta en la raíz de nuestro proyecto React.js llamada locale.

es.JSON

en.JSON

Configurar el proveedor global

Para que las traducciones sean accesibles en toda la aplicación, envolveremos el componente principal con el proveedor I18nextProvider. Este paso se realiza en el archivo principal, como index.jsx.

Con esta configuración, todas las traducciones estarán disponibles en los componentes React.

Uso en componentes

Para traducir textos en los componentes, utilizaremos el hook useTranslation que proporciona react-i18next.

En este ejemplo, t es la función que busca las traducciones en el idioma actual.

Cambiar de idioma

Podemos implementar una funcionalidad para cambiar el idioma de la aplicación en tiempo real utilizando el método changeLanguage de la instancia de i18next:

Con esto, los usuarios podrán alternar entre idiomas sin recargar la aplicación.

Conclusión

En este artículo, hemos explorado los fundamentos para implementar internacionalización con i18next en una aplicación React. Hemos configurado el entorno para que funcione con I18nextProvider, pero existen enfoques diferentes, como Context API o HOC (Higher-Order Component). Si desean explorar estos acercamientos, pueden consultarlos en la documentación de react-i18next.

Rutas relativas y absolutas en programación

Johan Garcia — Mon, 13 Jan 2025 22:36:45 +0000

Una ruta es el método mediante el cual podemos referenciar un recurso o directorio en un sistema de archivos dentro de un sistema operativo. Teniendo esto claro, ¿por qué es importante conocer más sobre las rutas? Porque estas te ayudan a evitar errores y a referenciar de forma exacta los recursos o directorios necesarios para ser utilizados en nuestras aplicaciones.

Al saber indicar la localización exacta de un archivo o directorio mediante una cadena de caracteres, podemos trabajar de manera más eficiente y precisa.

Árbol de directorios

Antes de continuar, es importante definir un término clave para entender las rutas absolutas y relativas: el árbol de directorios. Este concepto representa una estructura jerárquica de directorios y archivos en un sistema operativo. Es un enfoque común cuando trabajamos directamente con sistemas de archivos, exploradores de carpetas o comandos de terminal, y es independiente de una aplicación específica.

Concepto del Árbol de Rutas
Un sistema de archivos está organizado en una estructura de árbol, donde:

Cada nodo es un directorio o un archivo.
El nodo raíz (/ en sistemas basados en UNIX o una unidad como C:\ en Windows) es el punto de inicio.
Cada rama conecta un directorio con sus subdirectorios o archivos.
Cada archivo o directorio tiene una ruta única que describe su posición en el árbol.

Estructura Jerárquica del Árbol
La estructura típica de un árbol de rutas en un sistema operativo puede representarse como:

Dentro de este árbol de directorios se encuentran las rutas absolutas y relativas, que es lo que veremos a continuación.

Rutas Absolutas:

Comienzan desde el directorio raíz (/ en sistemas basados en UNIX o C:\ en Windows).
Proporcionan la localización completa del archivo o directorio en el sistema.

Ejemplos:

En UNIX: /home/user/documents/file1.txt
En Windows: C:\Users\User\Documents\file1.txt

Rutas Relativas:

Se definen en relación con el directorio actual.
Ejemplo: Si estás en /home/user, la ruta relativa a file1.txt sería documents/file1.txt.

Rutas

Existen dos formas de expresar una ruta, su forma relativa y su forma absoluta que cumplen funciones distintas, en su mayoria las rutas.

Rutas Relativas
Una ruta relativa indica la ubicación de un archivo o recurso en relación con el directorio actual, o lo que sería lo mismo, la posición en la que nos encontramos dentro del sistema operativo (o el contexto actual). Estas rutas son más flexibles y se utilizan para acceder a archivos más cercanos o relacionados con la misma jerarquía de directorios en la que estamos trabajando.

Referenciación
Utilizaremos . para referenciar el directorio actual. Es útil para referirse a archivos o subdirectorios dentro del mismo directorio donde estás ubicado.

Utilizaremos .. para referenciar al directorio padre. Representa el directorio inmediatamente superior al actual.

Ejemplos

../file.txt se refiere a file.txt en el directorio padre.
../../anotherfile.txt retrocede dos niveles en la jerarquía y busca el archivo.

Tomaremos este directorio como ejemplo para explicar el uso de rutas relativas.

Supongamos que estamos trabajando dentro de Header.js y queremos utilizar las funcionalidades que se encuentran en helpers.js. Haríamos referencia de la siguiente forma:

Las ventajas de utilizar las rutas relativas son que no requieren un conocimiento completo de la estructura global del árbol de directorios.

Una desventaja sería utilizarlas en proyectos grandes, donde puede ser difícil mantener rutas que son especialmente largas, como (../../../).

Rutas Absolutas
Una ruta absoluta indica o señala la ubicación completa de un archivo, recurso o directorio desde la raíz del sistema de archivos. Estas rutas son independientes del directorio actual, más claras y explícitas sobre la ubicación del recurso. Además, pueden ser configuradas en algunos entornos, como TypeScript o Webpack.

Ejemplo
Si no estuviéramos trabajando con TypeScript o Webpack, haríamos uso de la raíz de nuestro árbol de archivos para ubicarnos en el recurso que necesitáramos (por ejemplo: C:\usuarios\usuario1\project\src\utils\helpers).

Sin embargo, en este caso estaremos utilizando TypeScript y haremos uso de baseUrl en tsconfig.json para configurar una URL base desde la cual podemos partir al utilizar rutas absolutas dentro de nuestro proyecto.

Ahora continuaremos con la configuración de nuestro tsconfig.json.

Con esta configuración dentro de TypeScript y tsconfig.json, podremos utilizar los alias en nuestras rutas absolutas sin necesidad de referenciar todo el árbol de rutas existente (C:\usuarios\usuario1\project\src\utils\helpers), lo que evitará definir rutas extensas y difíciles de mantener, o el uso de rutas relativas.

Conclusión
Es esencial que comprendamos el árbol de directorios y las diferencias entre las rutas relativas y absolutas, ya que este conocimiento facilitará enormemente la navegación y gestión de archivos en cualquier sistema operativo o entorno de desarrollo. Las rutas absolutas les ofrecen una referencia precisa y clara a archivos y directorios, lo que asegura que siempre puedan acceder a ellos sin depender del directorio en el que se encuentren. Por otro lado, las rutas relativas son ideales para trabajar dentro del mismo contexto o proyecto, proporcionando flexibilidad y simplicidad.

Saber cuándo y cómo utilizar cada tipo de ruta no solo mejora la organización de sus proyectos, sino que también optimiza la mantenibilidad y reduce los errores relacionados con la ubicación de recursos. En proyectos grandes, las rutas absolutas y los alias bien configurados pueden simplificar las referencias y hacer que el código sea más limpio y fácil de comprender.

Entender estos conceptos es crucial para mejorar la eficiencia y precisión al trabajar con archivos y al desarrollar aplicaciones, garantizando un flujo de trabajo más ágil y un código más robusto.

Si el proyecto es pequeño o no quieres modificar configuraciones, usa rutas relativas.
Si trabajas en un proyecto grande o quieres mejorar la claridad del código, configura rutas absolutas.

DEV Community: Johan Garcia

El problema de la confianza ciega: cómo reducir las alucinaciones en agentes de IA parte 2

Plantillas de datos estructurados y Output Contracts para reducir alucinaciones

Arquitectura

Implementación paso a paso

El problema de la confianza ciega: cómo reducir las alucinaciones en agentes de IA parte 1

AGENTS.md y CLAUDE.md

Agentes de terminal y CLI

Editores de código e IDEs

Plataformas de repositorios (contexto web)

Typist y Architect

AI Agents no son magia: cómo construí un equipo de 7 especialistas que desarrollan software sin alucinar

La solución un orquestador

El truco — /grill-me y /caveman (Skills)

Spec-Driven Development

MCPs: los plugins del sistema

Nota final

Camino a CI/CD pruebas (Testing)

Tipos de Testing

Herramientas

Como potenciar tu VS Code con Continue.dev Cline

Está pensado para usuarios avanzados que buscan automatizar flujos repetitivos o construir asistentes que no solo respondan con texto, sino que también ejecuten acciones dentro del entorno de desarrollo.

Con esta configuración, Continue.dev ya estará funcionando correctamente, y solo nos queda comenzar a probar sus funcionalidades: autocompletado, chat o edición, siempre y cuando el modelo seleccionado lo permita.

Internacionalización en Aplicaciones React con i18next

¿Qué es la internacionalización de aplicaciones web?

¿Qué es i18next y por qué utilizarlo?

Instalación y configuración

es.JSON

en.JSON

Configurar el proveedor global

Uso en componentes

Cambiar de idioma

Conclusión

Rutas relativas y absolutas en programación

Árbol de directorios

Rutas

El truco — `/grill-me` y `/caveman` (Skills)