El escenario
Una empresa de logística solicita: "Queremos que Claude ayude a nuestro equipo de soporte al cliente a resolver tickets más rápido usando nuestra base de conocimiento interna, y también queremos que los desarrolladores usen Claude Code en su trabajo diario — ¿podemos hacer ambas cosas con una misma arquitectura unificada?".
Esta solicitud, tal como fue formulada, no es una especificación de ingeniería — es una visión general que oculta al menos seis decisiones arquitectónicas fundamentales: qué superficie de interacción utilizar para cada carga de trabajo, cómo exponer la base de conocimiento, quién audita los entregables antes de que lleguen al cliente final, cómo gestiona un ticket de soporte un historial de conversación creciente, qué telemetría se registra ante fallos y dónde se traza la frontera de seguridad entre las herramientas internas de desarrollo y el sistema de cara al cliente. Resolver ambigüedades a este nivel es la esencia de un capstone de arquitectura: no solo dominar mecanismos aislados, sino articular un argumento arquitectónico coherente que resuelva las seis decisiones de forma consistente entre sí.
Esta lección de integración no introduce conceptos nuevos. Exige sintetizar los marcos de decisión de las 21 lecciones anteriores en un Registro de Decisión Arquitectónica (ADR - Architecture Decision Record).
La estructura esencial de un ADR
Un ADR no es un informe exhaustivo de todo lo analizado. Es un registro conciso y auditable de una decisión, estructurado en cuatro secciones fijas:
- Contexto: identifica las restricciones técnicas y de negocio reales detrás de la solicitud (la restricción de fondo, no la petición superficial).
- Decisión: establece la elección arquitectónica en una frase declarativa clara e inequívoca.
- Alternativas descartadas: enumera otras opciones consideradas y explica con precisión qué restricciones violaban para ser rechazadas.
- Consecuencias: detalla los compromisos (tradeoffs) que introduce la decisión (costo de mantenimiento, latencia, superficie de riesgo) a cambio de lo que resuelve.
El error más común es pasar directamente a la "Decisión" sin articular las restricciones en "Contexto" — generando una propuesta que parece correcta, pero que nadie puede evaluar sin adivinar qué problema intentaba solucionar.
Recorriendo los cinco dominios en el mismo escenario
Arquitectura agéntica y orquestación: el flujo de soporte requiere un bucle de herramientas controlado (consultar la base de conocimiento, verificar el estado de pedidos, redactar la respuesta) — no un chat abierto ni un enjambre sobrecargado de subagentes. La intuición de que "multiagente es más robusto" es un distractor clásico: una canalización corta con pocas herramientas no gana nada con la coordinación de agentes, solo adquiere latencia y puntos de fallo.
Diseño de herramientas e integración MCP: la base de conocimiento interna debe exponerse como un servidor MCP con ámbito de proyecto, con descrições semánticas precisas para evitar selecciones erróneas — y sus resultados deben tratarse como superficie de riesgo (datos no confiables, nunca instrucciones del sistema).
Configuración y flujos de Claude Code: el entorno de desarrollo para ingenieros es una superficie completamente aislada del soporte al cliente — gobernada mediante CLAUDE.md, comandos y Skills versionadas en el repositorio. Intentar unificar ambas superficies bajo una sola arquitectura por el hecho de pertenecer a la misma empresa ignora que sus requisitos de seguridad, audiencia y revisión son incompatibles.
Ingeniería de prompts y salidas estructuradas: el borrador de respuesta al cliente es una salida estructurada con un contrato estricto (tono profesional, metadatos requeridos, prohibición de afirmaciones no verificadas) — validado programáticamente antes de presentarse a un agente humano.
Gestión de contexto y confiabilidad: una conversación de soporte que se prolonga durante días no debe convertirse en una ventana de contexto gigantesca y monolítica — exige compactación estructurada periódica (scratchpads y resúmenes continuos) combinada con una política clara de escalamiento a operadores humanos ante umbrales de incertidumbre.
El objetivo del capstone es comprender cómo las decisiones de un dominio condicionan las decisiones en los demás. Separar el soporte de Claude Code (topología agéntica) es lo que permite aplicar políticas de seguridad de menor privilegio a cada entorno (seguridad y MCP). Una arquitectura correcta en cada dominio por separado puede seguir siendo defectuosa si carece de consistencia global.
El modo de fallo más peligroso
En entornos de soporte en producción, el fallo más grave rara vez es el más evidente (que el modelo falle con un error de sintaxis). Es mucho más sutil: que el agente elabore una respuesta plausible, con redacción impecable pero no sustentada por la base de conocimiento, y que esta se despache al cliente sin revisión porque su formato generó una falsa impresión de certeza.
La mitigación no consiste en agregar más validaciones de formato — el JSON ya era correcto. La defensa es exigir trazabilidad de proveniencia: cada afirmación factual debe referenciar un documento de la base de conocimiento, bloqueando el envío si la referencia está ausente.
Ponlo en práctica
En el laboratorio de esta lección elaborarás y validarás la estructura de un ADR: contexto, decisión, alternativas descartadas y consecuencias para este escenario de soporte logístico, asegurando que cada decisión esté fundamentada en restricciones concretas.