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.
Top comments (0)