Flujos de trabajo eficientes: cuatro patrones de arquitectura junto con un coding agent
💡 Objetivo: domina en unos 44 minutos los cuatro patrones de arquitectura del documento oficial de Patterns y monta tu primer flujo de trabajo de Jev de nivel de producción: una sola solicitud con un lote de preguntas, enrutado por niveles de confianza, puntuación atómica con fusión ponderada, y al final deja que Claude Code escriba por ti el código que llama a Jev.
🎯 Objetivos de la etapa
- Descomponer un proceso de negocio en juicios atómicos y explicar qué problema resuelve cada uno de los cuatro patrones de arquitectura oficiales y cuáles son sus beneficios respectivos
- Escribir el código de «una sola solicitud con tres tipos de preguntas» y poder decir cuánto más barato y rápido es frente a una solicitud por pregunta
- Ponerle frenos a la automatización: usar los niveles de confidence para decidir entre ejecución automática, pedir confirmación al usuario o escalar a un humano
- Instalar en Claude Code el Agent Skill de TypeSafe para que el agent genere el código correcto de llamadas a Jev
⏳ Tiempo estimado
- 4 lecciones suman unos 44 minutos; con margen de holgura, calcula unos 31–57 minutos
- Cada lección es independiente y también puede leerse por separado según lo necesites; 3.1 es la base de las lecciones siguientes, se recomienda empezar por ahí
🚀 Antes de empezar
- has completado Uso diario: domina las cinco formas de preguntar de Jev: sabes plantear los tres tipos de preguntas Choice / Score / Noul; la compuerta de confianza de esta etapa depende por completo de lo aprendido en la lección de Confidence, la confianza
- el entorno de la lección Instalación y primera solicitud sigue funcionando:
TYPESAFE_API_KEYestá en las variables de entorno - (solo la lección 4 lo necesita) tienes instalado Claude Code u otro coding agent; si no lo tienes, no afecta a las tres primeras lecciones
- un vaso de agua ☕: en esta etapa lo principal es montar la arquitectura, la cantidad de código no es grande
📚 Lecciones de esta etapa
Primero mira qué problemas puede resolverte este flujo de trabajo de Jev. Si sueles escribir así a diario, esta etapa está hecha para ti:
| Tu forma actual de escribir | Cambiarla por un flujo de trabajo de Jev |
|---|---|
| ❌ Pedirle al LLM en el prompt «devuelve JSON, por favor» y luego escribir un montón de código de parsing para cubrir la deriva de formato | ✅ La respuesta nace dentro de las opciones que tú das, el código hace directamente if, sin recuperar valores de texto generado |
| ❌ Una solicitud por mensaje; cuando el volumen sube, el costo y la latencia suben con él | ✅ Una sola solicitud con N preguntas en paralelo: añadir preguntas casi no aumenta el tiempo de respuesta, solo unos tokens más por cada pregunta |
| ❌ El modelo nunca admite «no estoy seguro» y responde incluso cuando se equivoca, así que hay que vigilarlo manualmente todo el tiempo | ✅ confidence es el grado de certeza calculado a partir de la distribución de probabilidad (0–1); si es bajo, se escala automáticamente a un humano |
El documento oficial de Patterns resume estas prácticas en cuatro patrones de arquitectura. Las primeras 3 lecciones de esta etapa los desmenuzan uno por uno, y la lección 4 resuelve el problema de «quién escribe este código»:
| Patrón | En una frase | Beneficio |
|---|---|---|
| Speculative fan-out,扇出 especulativo | Todas las preguntas «posiblemente necesarias» van en una sola solicitud; el código decide después cuál usar | Costo, velocidad |
| Confidence-gated routing, enrutado con compuerta de confianza | La respuesta te dice «qué es»; confidence te dice «hacerlo o no» | Fiabilidad, seguridad |
| Composite scoring, puntuación compuesta | Los juicios complejos se descomponen en puntuaciones atómicas y se fusionan ponderadas en el código | Costo, fiabilidad, velocidad |
| Intent routing, enrutado por intención | Primero clasifica la intención y luego enruta a lógica determinista, un LLM experto o un humano | Costo, velocidad |
¿Cómo elegir? La documentación oficial no tiene una sección de «selección de patrones» lista para usar; la columna de beneficios es el criterio más práctico: si el problema es costo y velocidad, mira primero el fan-out y el enrutado; si el miedo es equivocarse y necesitas seguridad, mira primero la compuerta de confianza.
Plan de lecciones:
| Lección | Contenido | Duración |
|---|---|---|
| 3.1 Preguntas paralelas y speculative fan-out | Prueba oficial con 13 preguntas en una sola solicitud: 12.2 veces más barato, 10.0 veces más rápido, con las mismas respuestas; las preguntas especulativas «que se hacen pero no se usan» salen casi gratis | 12 minutos |
| 3.2 Enrutado inteligente | Choice clasifica la intención + Score evalúa la complejidad; según confidence se asigna a código determinista, un LLM experto o un humano; los umbrales se ajustan según el riesgo: 0.6 como red de seguridad, transferencias automáticas exigen 0.85 | 12 minutos |
| 3.3 Puntuación compuesta | Caso de filtrado de currículums: 4 dimensiones cada una con su Score, normalizadas y fusionadas con ponderación; si el ranking no es el esperado, cambia los pesos, no el prompt | 10 minutos |
| 3.4 para desarrollar junto con Claude Code | Jev no es un modelo para coding agents: instala el Agent Skill de TypeSafe para que el agent escriba código que llame a Jev; 3 prompts de ejemplo oficiales y 5 preguntas frecuentes | 10 minutos |
💡 pruébalo ahora mismo
El Agent Skill de TypeSafe de la lección 4 se instala en Claude Code con solo dos comandos:
claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-aiTras instalarlo, menciona en la conversación «use the TypeSafe skill», o llama directamente a /typesafe:typesafe-ai. Otros agents (Codex, etc.) usan npx skills add typesafe-ai/skills --skill typesafe-ai.
🎒 Lo que aprenderás
- El método de diseño de «descomponer primero en juicios atómicos y luego elegir un patrón para ensamblarlos»: la documentación oficial lo llama la habilidad clave para usar bien TypeSafe
- Los escenarios de aplicación y las ventajas y desventajas de los cuatro patrones de arquitectura, con esqueletos de código oficiales para copiar en cada lección
- El criterio práctico para graduar la automatización: alta confianza, ejecución automática; confianza media, pedir confirmación; baja confianza, pasar a un humano
- La forma correcta de colaborar con un coding agent: Jev toma las decisiones, tú revisas las preguntas y los umbrales, y el agent escribe el código
¿Ya terminaste de practicar los patrones y quieres ver cómo se aplican en proyectos reales? La siguiente etapa Escenarios prácticos: elige tu ruta tiene 15 casos completos (por ejemplo Guardarraíles para LLM: en una sola solicitud se inspeccionan todos los mensajes de entrada y salida de una aplicación con LLM).
¿Listo? Empieza la primera lección: preguntas en paralelo y speculative fan-out →