DOMINICODE

Category: AI

  • Recursos prácticos para aprender Spec-Driven Development

    Recursos prácticos para aprender Spec-Driven Development

    Listado de recursos para aprender SDD en castellano

    Tiempo estimado de lectura: 4 min

    • Ideas clave:
    • Spec-Driven Development (SDD) propone escribir especificaciones deterministas antes de codificar.
    • Un buen spec es el contrato entre el equipo humano y los agentes de IA; cuando es claro, reduce fragilidad en el código generado.
    • Lee la teoría primero, aplica en un proyecto pequeño y luego usa agentes (por ejemplo Claude Code) para cerrar el ciclo.
    • Versiona specs junto al código, declara contratos formales (OpenAPI/JSON Schema) y valida en runtime.

     

    Introducción

    El Spec-Driven Development (SDD) ya no es una moda: es la forma práctica de obtener código fiable cuando trabajas con agentes de IA. Si buscas un listado de recursos para aprender SDD en castellano, este artículo reúne lo esencial —teoría, práctica y pasos accionables— y muestra cómo convertir especificaciones en artefactos ejecutables por agentes como Claude Code.

    En las primeras líneas: el Spec-Driven Development consiste en escribir especificaciones deterministas antes de codificar. Esa especificación es el contrato que el equipo humano y el agente de IA van a cumplir. Si no está clara, el código generado será frágil; si está bien definida, el agente actúa como un ejecutor reproducible.

    Resumen rápido (lectores con prisa)

    SDD = escribir especificaciones deterministas y ejecutables antes de codificar. Úsalo cuando delegues trabajo repetible a agentes de IA o necesites contratos claros entre equipos. Importa porque reduce errores de generación y facilita trazabilidad. Funciona definiendo contratos formales (OpenAPI/JSON Schema), validándolos en runtime y versionándolos junto al código.

    Listado de recursos para aprender SDD en castellano

    SDD — Spec-Driven Development (libro)

    SDD — Spec-Driven Development

    Por qué leerlo: es la base conceptual sobre cómo diseñar especificaciones que funcionen tanto para personas como para modelos. Explica estructura de especificaciones, convenciones de contratos, ejemplos de modelos de datos y patrones para casos límite. Ideal para tech leads y arquitectos que deben estandarizar cómo se escribe el “qué” antes de generar el “cómo”.

    Construye con IA: de la idea al producto con Claude Code (curso Udemy)

    Construye con IA: de la idea al producto con Claude Code (curso Udemy)

    Por qué hacerlo: Claude Code es un agente que opera en tu entorno de desarrollo. El curso enseña a estructurar especificaciones que el agente pueda ingerir, supervisar la ejecución y corregir desviaciones. Es la práctica necesaria para ver cómo una especificación bien escrita reduce iteraciones y errores de generación.

    Cómo usar estos recursos de forma práctica (secuencia recomendada)

    1. Lee el libro primero. Construye el marco mental: ¿qué debe contener una especificación? ¿cómo documentar invariantes, límites y errores esperados?

    2. Aplica lo leído a un pequeño proyecto: escribe una especificación completa (archivo Markdown) para una funcionalidad simple: endpoint, modelo de datos y flujos de error.

    3. Realiza el curso y usa Claude Code para ejecutar la especificación. Observa dónde el agente alucina o omite pasos; corrige la especificación y repite.

    Esta secuencia cierra el ciclo: teoría → especificación real → ejecución con agente → ajuste de especificación.

    Paso 1

    Lee el libro y define la estructura mínima de tu spec: título, objetivo, invariantes y errores esperados.

    Paso 2

    Escribe la especificación en Markdown dentro del repo y convierte contratos en OpenAPI/JSON Schema.

    Paso 3

    Usa Claude Code para ejecutar; recopila fallos, ajusta la spec y repite hasta estabilidad.

    Plantilla mínima de una especificación SDD (práctica)

    Incluye estos apartados en un archivo Markdown dentro del repo (Docs-as-code):

    • Título y objetivo (1–2 frases).
    • Requisitos no funcionales (latencia, SLAs, seguridad).
    • Modelos de datos (ej. JSON Schema / OpenAPI snippets).
    • Casos de uso y flujos (máquina de estados simplificada).
    • Invariantes y restricciones (qué no debe pasar).
    • API contract (endpoint, métodos, parámetros, errores).
    • Tests de aceptación (inputs esperados y resultados).
    • Checklist de despliegue y rollback.

    Guardar la especificación cerca del código facilita que los agentes la lean como contexto y que el equipo la mantenga sincronizada.

    Buenas prácticas técnicas para equipos que adoptan SDD

    • Versiona las especificaciones en el mismo repo que el código. Nada de Confluence aislado.
    • Declara contratos formales (OpenAPI, JSON Schema). Convierte esos esquemas en herramientas ejecutables por agentes.
    • Usa prompts y archivos de contexto estándar (por ejemplo .cursorrules o system prompts) para que los agentes carguen las convenciones del proyecto.
    • Implementa validación: transforma tus schemas en validadores runtime (Zod o Ajv) y aplícalos a cada tool_use.
    • Instrumenta trazabilidad: cada ejecución automatizada debe dejar un rastro del prompt, la versión del spec y el resultado del agente.

    Limitaciones y siguientes pasos

    El ecosistema en castellano está creciendo; estos dos recursos son el núcleo. Para necesidades avanzadas —memoria a largo plazo, flujos que duran días, trazabilidad distribuida— añade prácticas e infraestructuras: persistencia (PostgreSQL/pgvector), orquestadores (n8n, LangGraph) y observabilidad (OpenTelemetry). Pero no conviertas la arquitectura en excusa: domina la especificación primero.

    Conclusión

    Si vas a trabajar con agentes de IA, aprender SDD es priorizar el acto más rentable: especificar bien. Empieza por leer el libro en Leanpub y practica con Claude Code en Udemy. Transforma la especificación en contrato vivo, versionado y ejecutable. Con eso, reduces iteraciones, controlas costos por token y, sobre todo, dejas de depender de la suerte cuando delegas en agentes.

    Para equipos interesados en implementar prácticas de SDD y automatización con agentes, una continuación lógica es revisar recursos y experimentos en Dominicode Labs.

     

    FAQ

    ¿Qué es Spec-Driven Development (SDD)?

    SDD consiste en escribir especificaciones deterministas antes de codificar; estas actúan como contrato entre equipos humanos y agentes de IA.

    ¿Por qué es útil versionar las especificaciones en el mismo repo?

    Versionar las especificaciones en el mismo repo garantiza sincronía con el código, facilita revisiones y evita documentación aislada que se queda obsoleta.

    ¿Qué formatos de contrato se recomiendan?

    Se recomiendan contratos formales como OpenAPI y JSON Schema porque son legibles por herramientas y agentes, y permiten generar validadores y mocks.

    ¿Cómo integrar validación runtime?

    Transforma tus schemas en validadores runtime (por ejemplo Zod o Ajv) y ejecútalos en cada tool_use o etapa donde el agente entregue artefactos.

    ¿Qué papel juegan los agentes como Claude Code?

    Agentes como Claude Code ejecutan especificaciones en tu entorno; su papel es reproducir flujos definidos por la spec y permitir iteración rápida sobre fallos.

    ¿Cuáles son los siguientes pasos tras aprender la teoría?

    Tras la teoría, aplica en un proyecto pequeño: escribe una spec, ejecútala con un agente, corrige las desviaciones y automatiza validaciones y trazabilidad.

  • Aprende a escribir especificaciones efectivas para LLMs

    Aprende a escribir especificaciones efectivas para LLMs

    Por qué dejé de escribir código desde cero y empecé a hacer specs primero

    Tiempo estimado de lectura: 3 min

    • Menos correcciones manuales: las specs reducen el tiempo invertido en ajustar código generado por LLMs.
    • Contratos ejecutables: una spec bien definida evita ambigüedades y deuda técnica.
    • Escalabilidad y previsibilidad: la spec es la fuente de verdad para cambios y nuevos colaboradores.

    ¿Sabes qué consume más tiempo que escribir código? Corregir el código que generó la IA porque nadie le dejó claro qué hacer.

    Hace un par de años disfrutaba abrir un editor en blanco. Era adrenalina pura: estructura, imports, resolver problemas “sobre la marcha”. Parecía productividad. Era ilusión.

    La transición a escribir specs primero cambió eso por completo. No porque sea más elegante, sino porque es más efectivo. Aquí te cuento por qué dejé de escribir código desde cero y empecé a hacer specs primero, qué contiene una spec útil y cómo eso transforma la relación entre humanos, agentes y código.

    Resumen rápido (lectores con prisa)

    Spec‑Driven Development: definir specs precisas antes de implementar reduce ambigüedades, minimiza correcciones manuales y convierte la spec en la fuente de verdad. Útil cuando el producto se mantiene, la lógica es compleja o hay múltiples integradores. Implementación: especifica stack, datos, contratos de API, reglas de negocio y casos de aceptación.

    Por qué dejé de escribir código desde cero y empecé a hacer specs primero

    El catalizador fue simple: gastaba horas ajustando código generado por LLMs. No es culpa de la IA. Es culpa de la ambigüedad. Un modelo no conoce tus convenciones, tus límites ni las decisiones que tomaste el martes. Para un LLM, lo que no está escrito no existe.

    Cuando trabajas sin spec, cada prompt es un microcontrato mal redactado. Resultado: fragmentos que funcionan aisladamente y rompen la coherencia global. El coste no es solo tiempo; es deuda técnica que aparece en sprint 3 y se siente en el cuello del repo.

    Escribir specs primero no es volver a la documentación de los 90. Es escribir contratos ejecutables: lo suficiente para que un agente implemente sin inventar nada. Eso cambió mi productividad: menos correcciones, menos parches, más iteraciones reales.

    ¿Qué lleva una spec que funcione con IA?

    No basta con una descripción bonita. Una spec útil es precisa, limitada y accionable. Esto es lo que siempre incluyo:

    • Stack exacto con versiones. No “React moderno”. React 18.3, Next.js 14, etc.
    • Modelo de datos. Tablas, campos, tipos y restricciones. Si usas UUID, dilo.
    • Contratos de API. Endpoints, payloads de ejemplo, códigos de error y formatos.
    • Reglas de negocio explícitas. Qué hacer y, más importante, qué no hacer.
    • Casos de aceptación. Escenarios claros que definen el comportamiento visible.
    • Límites del MVP. Qué se queda fuera en esta iteración y por qué.

    El documento vive en el repo (spec.md), versionado. Si algo cambia, la spec cambia primero. No al revés.

    Si quieres una guía práctica para redactar specs que funcionen con LLMs, uso y recomiendo el libro Spec‑Driven Development.

    Cómo cambiaron mis sesiones con agentes

    Antes: abría un chat, pedía componentes, pegaba código. Después de dos horas, el sistema era Frankenstein.

    Ahora: escribo la spec, lanzo al agente en terminal con la instrucción clara—lee spec.md e implementa la Fase X—y reviso diffs. El agente crea archivos, instala dependencias y propone un conjunto coherente desde la raíz. Mi rol pasa de “peón que teclea” a “arquitecto que aprueba”.

    Regla de oro

    Nunca corrijo el código directamente para resolver una ambigüedad. Actualizo la spec y mando al agente a refactorizar. Si corriges el código sin tocar la spec, el día siguiente volverás a ver el mismo fallo cuando el agente regenera algo incompatible.

    Beneficios reales (sin poesía)

    • Menos tiempo en ajustes menudos. Más tiempo en decisiones estratégicas.
    • Menos deuda técnica porque las reglas de diseño se establecen antes.
    • Cambios más predecibles: si una feature cambia, la spec es la fuente de verdad.
    • Escalabilidad del equipo: nuevos desarrolladores o agentes arrancan en horas, no en días.

    Cuando esto no aplica

    No todos los proyectos necesitan SDD. Si estás escribiendo un script de 50 líneas o prototipando algo desechable para validar una idea, un prompt rápido tiene sentido. SDD brilla cuando el producto crece, hay datos críticos o múltiples integradores.

    Regla práctica: si la base de código será mantenida más de un mes o la lógica de negocio es compleja, escribe la spec.

    El cambio de rol del developer

    Adoptar specs no elimina el trabajo humano; lo eleva. Ahora se pide que tomes decisiones tempranas y explícitas: límites, trade-offs, casos borde. La ejecución se delega, la responsabilidad de diseño sigue siendo humana.

    Ese es el valor real: profesionales que saben diseñar sistemas se vuelven más valiosos porque delegan la repetición y retienen la toma de decisiones estratégicas.

    El libro Spec‑Driven Development recoge las plantillas, patrones y ejemplos que uso todos los días para que un LLM implemente sin inventos. Si estás cansado de arreglar lo que la IA rompe, empieza por escribir la spec. Es incómodo al principio, pero harás más en menos tiempo y sin excusas.

    La próxima iteración de tu proyecto debería empezar con un archivo spec.md, no con un editor en blanco. Hazlo y verás que tu trabajo deja de parecer frenético: se vuelve deliberado.

    Para equipos que adoptan automatización y agentes como parte del flujo de desarrollo, una práctica centralizada de especificaciones acelera la coordinación entre humanos y máquinas. Si estás explorando flujos donde agentes y workflows son críticos, mira iniciativas y recursos prácticos en Dominicode Labs para ejemplos aplicables y plantillas.

    FAQ

    ¿Qué es Spec‑Driven Development (SDD)?

    Spec‑Driven Development es la práctica de definir especificaciones precisas y accionables antes de implementar. Las specs actúan como contratos ejecutables para equipos humanos y agentes.

    ¿Cuándo debería escribir una spec en lugar de prototipar?

    Escribe una spec cuando la base de código será mantenida más de un mes, la lógica de negocio es compleja o hay múltiples integradores. Para scripts pequeños o prototipos muy tempranos, un prompt rápido puede bastar.

    ¿Qué debe incluir una spec mínima?

    Una spec mínima incluye: stack y versiones, modelo de datos, contratos de API con ejemplos, reglas de negocio claras y casos de aceptación. También define los límites del MVP.

    ¿Cómo integro specs en el flujo con agentes?

    Mantén la spec en el repo, lanza al agente con instrucciones que apunten al archivo (por ejemplo, “lee spec.md e implementa la Fase X”) y revisa diffs en lugar de editar código directamente.

    ¿Qué pasa si alguien modifica código sin actualizar la spec?

    Si alguien modifica código sin actualizar la spec, la siguiente regeneración por parte del agente puede reintroducir el fallo. La regla de oro es: actualiza la spec y vuelve a ejecutar al agente.

    ¿Dónde guardo las specs y cómo las versiono?

    Guarda las specs en el repositorio como archivos versionados (ej.: spec.md). Cualquier cambio debe pasar por control de versiones para que la spec sea la fuente de verdad.

  • Aprende a convertirte en AI Engineer en 2026

    Aprende a convertirte en AI Engineer en 2026

    De dev a AI Engineer: qué necesitas aprender en 2026

    Tiempo estimado de lectura: 3 min

    Ideas clave

    • Prompt Engineering como contrato tipado y versionable para reducir alucinaciones.
    • Tool Calling y agentes: definir herramientas con responsabilidades únicas y schemas JSON.
    • RAG en producción usando embeddings, chunking y pgvector para memoria privada eficiente.
    • LLMOps con tracing y LLM-evaluadores para medir costes y alucinaciones.

    Introducción

    Buscar De dev a AI Engineer: qué necesitas aprender en 2026 ya no es curiosidad de fin de semana; es una decisión profesional con impacto directo en tu carrera. Si vienes de React, Angular o NestJS, tienes la base técnica. Lo que falta es reaprender cómo estructurar sistemas cuando la lógica principal es probabilística y depende de modelos externos.

    En las siguientes líneas encontrarás un roadmap concreto, orientado a ingenieros web/backend, con prioridades prácticas, enlaces a documentación útil y criterios para decidir qué aprender primero.

    Resumen rápido (lectores con prisa)

    Prompt Engineering: diseñar prompts como artefactos versionables que produzcan salidas tipadas y validables.

    Tool Calling / Agentes: definir herramientas con schemas JSON y orquestar invocaciones desde un Agent Loop.

    RAG: almacenar embeddings por chunk (pgvector), recuperar top-k y re-rankear antes de inyectar contexto.

    LLMOps: traza sesiones, registra tokens y usa un LLM evaluador para medir pertinencia y alucinaciones.

    De dev a AI Engineer: qué necesitas aprender en 2026 (roadmap concreto)

    No te doy una lista genérica. Te doy cuatro pilares con tareas prácticas y recursos.

    1) Prompt Engineering estructurado — De texto a contrato

    • Qué aprender: diseñar prompts como artefactos versionables: system prompts, ejemplos (few-shot), y salidas tipadas.
    • Práctica concreta: escribe prompts que devuelvan JSON con un esquema Zod; automatiza tests que validen esos esquemas en CI.
    • Por qué importa: reduce alucinaciones y permite integrar respuestas en pipelines sin parsing frágil.
    • Recurso: Vercel AI SDK para integrar outputs tipados en TypeScript.

    2) Tool Calling y diseño de agentes — Orquesta, no suplentes

    • Qué aprender: definir herramientas (APIs) como JSON-schema que el LLM puede invocar (function/tool calling).
    • Práctica concreta: implementa un Agent Loop mínimo en NestJS:
      • Enviar mensaje + herramientas (schemas) al LLM.
      • Si respuesta indica tool_use, validar args y ejecutar el Service correspondiente.
      • Devolver tool_result y repetir hasta end_turn.
    • Criterio: cada herramienta = responsabilidad única (no “herramienta dios”).
    • Recurso: Anthropic Tool Use

    3) RAG (Retrieval-Augmented Generation) avanzado — Memoria privada usable

    • Qué aprender: embeddings, chunking semántico, re-ranking y vectores en producción.
    • Práctica concreta: usa pgvector sobre PostgreSQL para empezar; implementa pipeline:
      • Normaliza y chunkea documentos.
      • Genera embeddings por chunk.
      • Recupera top-k por similitud y re-rankea por señal de negocio antes de inyectar al prompt.
    • Criterio: prioriza latencia y coste. Evita enviar “todo” en cada petición.
    • Recurso: pgvector

    4) LLMOps y Evaluaciones — Operar lo no determinista

    • Qué aprender: tracing por sesión, LLM-as-a-judge y métricas de negocio.
    • Práctica concreta: registra cada interacción (tokens, latencia, tools invocadas). Configura un job que use un LLM evaluador para puntuar respuestas por pertinencia y alucinaciones.
    • Herramientas: Langfuse para trazabilidad, LangSmith para visualización.
    • Métricas clave: coste por sesión, iteraciones por solicitud, p95 latencia por tool, tasa de fallos por tool.

    Stack técnico recomendado (práctico y defendible)

    Si trabajas en TypeScript, prioriza estos componentes (con orden de adopción):

    1. SDKs oficiales

    Recomendación: Anthropic/OpenAI — aprende sus modelos, límites y formatos de tool-calling.

    2. Backend

    Recomendación: NestJS — implementa providers para LLM, ToolRegistry y AgentService.

    3. Vector DB inicial

    Recomendación: pgvector + PostgreSQL; escala a Pinecone/Qdrant si el volumen lo exige.

    4. Orquestación y workflows

    Recomendación: n8n para pipelines asíncronos y conectores empresariales.

    5. Observabilidad

    Recomendación: Langfuse o LangSmith para tracing y análisis de coste.

    Evita caer en frameworks que abstraen demasiado al principio. Aprende la API real: sabes más cuanto menos le pidas al framework que haga por ti.

    Errores que vas a cometer (y cómo evitarlos)

    • No versionar prompts: guarda prompts junto al código y pruébalos.
    • Herramientas multifunción: separa responsabilidades y aplica autorización por herramienta.
    • No medir tokens: integra métricas de coste desde el primer día.
    • Tests ausentes: mockea LLMs y valida esquemas de salida en CI.

    Prioridad de aprendizaje (3 pasos rápidos)

    1. Practica Tool Calling con un mini-proyecto en NestJS: define 4 herramientas y un Agent Loop.
    2. Implementa RAG con pgvector para un dominio de 100 documentos. Mide latencia y coste.
    3. Añade tracing (Langfuse) y un evaluador LLM que puntúe respuestas en lotes.

    Conclusión

    Convertirse en AI Engineer en 2026 no implica abandonar lo que ya sabes. Implica extender tu disciplina: convertir prompts en contratos, convertir respuestas probabilísticas en flujos controlados y operar sistemas con métricas reales. Si dominas eso, liderarás la integración de IA en producto, no sólo la experimentación.

    Dominicode Labs

    Para equipos que implementan agentes, RAG y pipelines de observabilidad, un siguiente paso natural es consolidar prácticas en proyectos pilotos y reproducibles. Una opción para explorar experimentos y plantillas es Dominicode Labs, que puede servir como repositorio de referencia para workflows y pruebas de concepto.

    FAQ

    ¿Qué es Prompt Engineering estructurado?

    Diseñar prompts como artefactos versionables que incluyan system prompts, ejemplos (few-shot) y produzcan salidas tipadas. El objetivo es generar respuestas que se puedan validar automáticamente (por ejemplo, JSON con esquema Zod).

    ¿Cómo funciona Tool Calling y por qué usarlo?

    Se definen herramientas con schemas JSON que el LLM puede invocar. Un Agent Loop envía mensajes y herramientas al LLM; si el LLM indica uso de herramienta, se validan los argumentos, se ejecuta el servicio y se devuelve el resultado, repitiendo hasta finalizar.

    ¿Por qué usar pgvector para RAG?

    pgvector sobre PostgreSQL permite comenzar con una solución integrada para embeddings y búsquedas vectoriales. Es práctica para dominios iniciales antes de escalar a Pinecone o Qdrant.

    ¿Qué incluye LLMOps en producción?

    Tracing por sesión, registrar tokens, latencia y tools invocadas; configurar jobs que usen un LLM evaluador para puntuar respuestas por pertinencia y alucinaciones; y medir métricas como coste por sesión y p95 latencia por tool.

    ¿Qué stack priorizar si trabajo en TypeScript?

    Prioriza SDKs oficiales (Anthropic/OpenAI), backend en NestJS, pgvector + PostgreSQL, orquestación con n8n y observabilidad con Langfuse o LangSmith.

    ¿Cuáles son los primeros proyectos prácticos recomendados?

    Tres pasos rápidos: (1) mini-proyecto en NestJS para Tool Calling con 4 herramientas y un Agent Loop; (2) implementar RAG con pgvector para ~100 documentos; (3) añadir tracing y un evaluador LLM para puntuar respuestas.

  • Cómo integrar Codex CLI en tu flujo de trabajo de manera segura

    Cómo integrar Codex CLI en tu flujo de trabajo de manera segura

    posts sobre codex cli — repositorio en GitHub

    Tiempo estimado de lectura: 4 min

    • Ideas clave:
    • Codex CLI demostró la capacidad de transformar lenguaje natural en comandos de shell; su valor actual está en el patrón arquitectónico más que en copiar la herramienta tal cual.
    • Flujo seguro: captura del prompt → contexto mínimo → petición al modelo → plan → revisión humana → ejecución (sandbox opcional).
    • Reglas operativas: uso estricto de git, human-in-the-loop, .codexignore, sandboxing y logs.
    • Considera alternativas modernas (Copilot CLI, Aider, Claude Code) según modelo, coste y conciencia git.

    Buscar “posts sobre codex cli https://github.com/openai/codex” es algo que cualquier developer que pasa tiempo en la terminal hace tarde o temprano. El repositorio de OpenAI en GitHub contiene código que convirtió instrucciones en lenguaje natural en comandos de shell ejecutables; aquí tienes un análisis técnico, práctico y con criterio para decidir si merece entrar en tu flujo de trabajo —y cómo hacerlo sin romper nada.

    Resumen rápido (lectores con prisa)

    Codex CLI traduce prompts en comandos de shell con confirmación humana. Úsalo para automatizar refactorizaciones y tareas repetitivas, pero siempre con git, .codexignore y sandboxing. No lo ejecutes en producción sin revisión.

    posts sobre codex cli https://github.com/openai/codex — qué era y qué es hoy

    Codex CLI nació como experimento para demostrar que un modelo podía traducir prompts a comandos de bash, zsh o PowerShell. El repositorio en https://github.com/openai/codex contiene el código fuente, ejemplos y el patrón básico: capturar prompt → enriquecer con contexto mínimo → pedir al modelo → mostrar comando para confirmación.

    Con el tiempo el ecosistema evolucionó. Los modelos Codex originales fueron consolidados dentro de las familias GPT y las implementaciones prácticas deben adaptarse a nuevas APIs y consideraciones de seguridad. El valor técnico del repositorio no está tanto en copiar y pegar la herramienta tal cual, sino en entender su arquitectura: contexto, plano de acción propuesto por el modelo y control humano en el loop.

    Arquitectura práctica del Codex CLI (resumen técnico)

    Un flujo seguro y repetible que tomes del repo:

    Paso 1: Captura del prompt en la CLI

    Captura del prompt en la CLI.

    Paso 2: Construcción de contexto

    Construcción de contexto: sistema operativo, shell, archivos relevantes.

    Paso 3: Petición al modelo

    Petición al modelo con instrucciones claras (incluyendo límites).

    Paso 4: Recepción de plan

    Recepción de plan: comandos y diffs.

    Paso 5: Capa de revisión humana

    Capa de revisión humana (confirmación Y/N).

    Paso 6: Ejecución en sandbox o contexto real

    Ejecución en sandbox o en contexto real según el modo.

    El repositorio muestra esa cadena end-to-end y facilita experimentar. Link: https://github.com/openai/codex

    Cómo integrar Codex CLI hoy sin liarla

    Si vas a usar ideas o código del repo, aplica estas reglas operativas:

    • Git obligatorio: nunca en modo autónomo sin control de versiones. Todo cambio debe poder revertirse con un git reset o revert.
    • Human-in-the-loop: exige confirmación explícita (Y/N) para cualquier comando que altere el FS fuera de una carpeta de prueba.
    • .codexignore: crea un archivo para excluir node_modules, dist, build, archivos binarios y .env. Reduce coste de tokens y evita filtrar secretos.
    • Sandboxing: para experimentos, usa contenedores Docker con red deshabilitada. Configura volúmenes limitados.
    • Tokens y coste: limita el contexto que envías al modelo. No adjuntes todo el repo; adjunta solo los ficheros necesarios o extractos relevantes.
    • Logs y auditoría: guarda los prompts y las respuestas (hashed si hay datos sensibles) para trazabilidad.

    Ejemplo mínimo de instalación (adaptado del repo)

    npm install -g @openai/codex
export OPENAI_API_KEY="sk-…"
codex

    No copies sin validar; el repo original puede requerir adaptaciones a la API actual.

    Casos de uso donde realmente aporta valor

    No todo para todo. Usa Codex CLI (o una implementación basada en su diseño) cuando:

    • Necesites refactorizaciones a escala: renombrar símbolos en todo el repo siguiendo reglas concretas.
    • Generación de tests coherentes con la base existente: pide que imite la convención de tests del proyecto.
    • Automatización de infra/DevOps repetitiva: plantillas de Dockerfile, small CI changes, hooks de Git.
    • Onboarding: un agente que explique snippets o genere tareas repetitivas para nuevos miembros.

    No lo uses para operaciones críticas sin revisión (migraciones de BD sin script probado, cambios en infra prod).

    Alternativas y posición en el ecosistema

    El diseño del repo de OpenAI es la semilla. Hoy existen herramientas más pulidas y con integraciones específicas (Copilot CLI, Aider, Claude Code). La decisión práctica se basa en tres factores: modelo y coste, git-awareness (capacidad para trabajar con commits y diffs), y controles de seguridad integrados.

    • Si quieres integración empresarial y soporte nativo con GitHub: considera Copilot CLI.
    • Si necesitas un agente git-aware que haga commits atómicos: mira Aider.
    • Si trabajas con repositorios enormes y razonamiento arquitectónico: Claude Code es fuerte en contexto pesado.

    Codex CLI (repositorio) sigue siendo un recurso para aprender el patrón arquitectónico y prototipar. En https://github.com/openai/codex encontrarás el material de referencia.

    Conclusión: lee los posts, adapta las ideas, no copies el script

    Los posts sobre codex cli https://github.com/openai/codex deben leerse con criterio. El valor real está en el patrón: contexto mínimo, plan claro, revisión humana y ejecución controlada. Si vas a incorporar agentes en tu terminal, hazlo con Git como red de seguridad, ignores claros y entornos aislados. Empieza por prototipos en carpetas no productivas, automatiza tareas repetitivas y escala solo cuando la trazabilidad y la seguridad estén resueltas.

    El repo es útil. Pero la responsabilidad técnica es tuya: la IA puede sugerir un comando brillante y peligroso a la vez. Mantén el control, y usa la terminal como un asistente, no como un sustituto de tu juicio.

    Dominicode Labs

    Si trabajas en automatización, agentes o workflows y quieres prototipar con control de seguridad, considera explorar recursos adicionales en Dominicode Labs. Sirve como continuación lógica para experimentar con patrones de agente git-aware y sandboxing.

    FAQ

    ¿Qué es Codex CLI y dónde está el código?

    Codex CLI fue un experimento que convierte prompts en comandos de shell con confirmación humana. El código está disponible en el repositorio de OpenAI en GitHub; accede a él desde el enlace proporcionado en el artículo.

    ¿Por qué no debo ejecutar comandos sin control de versiones?

    Sin git no puedes revertir fácilmente cambios peligrosos. Usar control de versiones permite deshacer operaciones con git reset o revertir commits, reduciendo el riesgo al probar comandos generados por IA.

    ¿Qué debe incluir un .codexignore?

    Incluye node_modules, dist, build, archivos binarios y .env. Esto reduce coste de tokens y evita filtrar secretos al modelo.

    ¿Cómo aplicar sandboxing para experimentos?

    Usa contenedores Docker con la red deshabilitada y volúmenes limitados para ejecutar comandos de prueba. Esto aísla el entorno y minimiza el impacto de cambios inesperados.

    ¿Para qué casos de uso es recomendable usar Codex CLI?

    Es útil para refactorizaciones a escala, generación de tests coherentes, automatización repetitiva de infra/CI, y onboarding que requiera generación de tareas o explicaciones de snippets.

    ¿Qué alternativas existen hoy?

    Alternativas mencionadas incluyen Copilot CLI, Aider y Claude Code, cada una con puntos fuertes según integración con GitHub, git-awareness y capacidad para contextos grandes.

    ¿Cómo auditar prompts y respuestas?

    Guarda los prompts y respuestas en logs. Si contienen datos sensibles, almacena versiones hasheadas. Mantén trazabilidad para revisar decisiones y reproducir resultados.

  • Cómo usar SDKs de AI tipados en TypeScript para reducir errores

    Cómo usar SDKs de AI tipados en TypeScript para reducir errores

    Typed AI SDKs: por qué usar el SDK de Anthropic o OpenAI en TypeScript y no JavaScript puro

    Tiempo estimado de lectura: 3 min

    • TypeScript tipado reduce errores silenciosos: convierte fallos indetectables en errores visibles en desarrollo.
    • Zod aporta validación en runtime: evita confiar en casts y valida la forma real de respuestas del modelo.
    • Patrón “esquema primero, prompt segundo”: serializa el esquema en el prompt y valida antes de persistir.

    Typed AI SDKs: por qué usar el SDK de Anthropic o OpenAI en TypeScript y no JavaScript puro — si vas a poner LLMs en producción, esa decisión cambia el perfil de riesgo de tu sistema. TypeScript no arregla la aleatoriedad del modelo, pero convierte fallos indetectables en errores visibles mientras desarrollas. Eso es todo; y es suficiente.

    Resumen rápido (lectores con prisa)

    Un SDK tipado (OpenAI o Anthropic) + validación runtime (Zod) convierte errores silenciosos en errores detectables durante desarrollo. Diseña el esquema primero, serialízalo en el prompt, parsea y valida la respuesta antes de usarla.

    Introducción

    Cuando integras un LLM en un flujo de trabajo (agentes, pipelines n8n, microservicios de extracción) no luchas contra la IA: luchas contra su impredecibilidad. JavaScript puro acepta promesas rotas y propiedades ausentes hasta que explotjan en producción. Un SDK tipado (OpenAI o Anthropic) empuja la mayoría de esos errores al compilador.

    Fuentes prácticas:

    Errores en compile time, no en producción

    – Modelos como valores literales: los SDK tipados exponen uniones de strings para modelos. Intentar model: 'gpt-5' fallará en el editor, no en prod.

    – Parámetros obligatorios: el compilador te obliga a rellenar lo que la API realmente necesita.

    – Propiedades opcionales: TS fuerza comprobaciones (?., if) antes de operar con datos potencialmente nulos.

    Resultado: menos hotfixes nocturnos. Detectas que algo está mal cuando escribes, no cuando lo usan clientes.

    Autocompletado real: productividad que importa

    IntelliSense deja de ser un lujo y pasa a ser documentación viva. Parámetros como temperature, response_format o function_call aparecen en el editor con sus tipos exactos. En equipos, esto reduce discusiones sobre “¿qué forma tenía ese objeto?” y evita JSON mal formado en llamadas a herramientas.

    La trampa del casting y por qué Zod es obligatorio

    TypeScript desaparece en runtime. Hacer const x = JSON.parse(s) as MyType es mentirle al compilador. Si el modelo devuelve "age":"veinticinco" habrás metido basura en tu flujo.

    Zod ofrece validación en tiempo de ejecución y genera el tipo TypeScript desde el esquema. Patrones recomendados:

    Patrones recomendados

    • Definir el esquema Zod como fuente única de verdad.
    • Incluir el esquema (o un resumen) en el prompt para guiar al LLM.
    • Parsear y validar la respuesta con Zod antes de usarla.

    Ejemplo práctico (OpenAI/Anthropic + Zod):

    import { z } from 'zod';
import OpenAI from 'openai'; // o Anthropic desde '@anthropic-ai/sdk'

const UserProfileSchema = z.object({
  fullName: z.string(),
  age: z.number().int().positive(),
  email: z.string().email(),
  tags: z.array(z.string()).max(5),
});

type UserProfile = z.infer<typeof UserProfileSchema>;

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function extractUserProfile(text: string): Promise<UserProfile> {
  const resp = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: `Devuelve solo JSON válido que cumpla este esquema: ${JSON.stringify(UserProfileSchema.shape)}` },
      { role: 'user', content: text },
    ],
    // response_format o similar según SDK
  });

  const raw = resp.choices?.[0]?.message?.content;
  if (!raw) throw new Error('Respuesta vacía del modelo');

  // Validación runtime: si falla, aquí lo capturas y reintentas o lo registras
  const parsed = UserProfileSchema.parse(JSON.parse(raw));
  return parsed;
}

    Si usas Anthropic, adapta la llamada al cliente: la idea es la misma: pedir JSON estructurado y validar con Zod.

    Patrones que escalan: esquema primero, prompt segundo

    1. Diseña el esquema Zod.
    2. Infiere tipos TypeScript con z.infer.
    3. Serializa el esquema (o una versión legible) en el prompt.
    4. Valida la respuesta antes de persistir o procesar.

    Este patrón convierte al LLM en una fuente estocástica que vive dentro de un perímetro controlado. No reduces la tasa de “alucinaciones”, pero transformas una alucinación en un error tratable y reproducible.

    Cuándo aplicar este enfoque

    – Sistemas críticos: facturación, reconciliaciones, autorizaciones.

    – Workflows orquestados en n8n donde agentes ejecutan cambios de estado.

    – Microservicios que procesan datos externos y alimentan otras partes del sistema.

    Evítalo solo en prototipos desechables donde la velocidad de exploración sea prioritaria frente a la robustez.

    Conclusión

    Usar Typed AI SDKs de Anthropic o OpenAI en TypeScript y validarlos con Zod no es postureo técnico: es una estrategia de mitigación de riesgo. Cambias errores silenciosos por fallos detectables en desarrollo, mejoras la DX y pones una barrera defensiva entre la naturaleza impredecible del LLM y la integridad de tus datos. Implementa el patrón “esquema primero, prompt segundo” y tu siguiente incidente nocturno será opcional, no inevitable.

    Para trabajos relacionados con automatización, agentes y workflows en entornos de producción puedes explorar más prácticas y experimentos en Dominicode Labs. Se integra como una continuación lógica de los patrones descritos y recursos para orquestación y pruebas.

    FAQ

    ¿Por qué TypeScript ayuda con SDKs de LLM?

    TypeScript detecta discrepancias de tipos en tiempo de compilación, obligando a llenar parámetros obligatorios y a tratar opcionales. Reduce errores silenciosos que aparecerían solo en producción.

    ¿No es suficiente validar con ifs y typeof?

    Comprobaciones manuales ayudan, pero son repetitivas y propensas a olvidos. Zod ofrece esquemas reutilizables y validación automatizada en runtime que complementa a TypeScript.

    ¿Zod reemplaza a TypeScript?

    No. Zod aporta validación en runtime; TypeScript aporta seguridad en compile time. Juntos cubren ambos límites: desarrollo y ejecución.

    ¿Cómo incluyo el esquema en el prompt?

    Serializa el esquema o un resumen legible (ej.: propiedades y tipos esperados) y pídelo explícitamente en el prompt. Luego parsea y valida la respuesta con Zod antes de usarla.

    ¿Este patrón funciona con Anthropic?

    Sí. El enfoque es independiente del proveedor: adapta la llamada al cliente de Anthropic pero mantiene la misma estrategia de pedir JSON estructurado y validar con Zod.

    ¿Cuándo no aplicar este enfoque?

    Evítalo en prototipos desechables donde la velocidad de exploración prima sobre la robustez. Para sistemas críticos, es la opción recomendada.

  • Implementación del Agentic Harness para Agentes Autónomos

    Implementación del Agentic Harness para Agentes Autónomos

    Qué es el Agentic Harness y cómo aplicarlo?

    Tiempo estimado de lectura: 5 min

    • Idea clave: Un Agentic Harness es la infraestructura que transforma agentes autónomos experimentales en software operable y seguro.
    • Idea clave: Sus componentes mínimos: sandboxing, mocking de herramientas, trazabilidad y guardrails automatizados.
    • Idea clave: Integrarlo en CI/CD y usar un LLM-judge reduce riesgos antes de dar acceso a producción.

    El Agentic Harness es la infraestructura que convierte agents autónomos experimentales en piezas de software operables y seguras. Si un agente entra en producción sin un harness, no es cuestión de “si” fallará: es cuestión de “cuándo” y con qué coste. Entender qué es el Agentic Harness y cómo aplicarlo es obligado para Tech Leads y equipos que despliegan agentes que actúan sobre sistemas reales.

    Los LLM son probabilísticos. Un agente no devuelve solo un output: planifica, encadena herramientas y decide. Un Agentic Harness controla ese actor: lo aísla, lo simula, lo rastrea y lo limita antes de darle acceso al mundo real.

    Resumen rápido (lectores con prisa)

    Agentic Harness: infraestructura que aísla, simula y limita agentes que razonan. Úsalo siempre que un agente pueda modificar sistemas reales o acceder a datos sensibles. Importa porque reduce riesgos operativos y legales. Funciona combinando sandboxing, mocks, trazabilidad y guardrails automatizados.

    Qué es el Agentic Harness y cómo aplicarlo en la práctica

    Un Agentic Harness hereda la idea del test harness tradicional y la adapta a agentes que razonan. Su objetivo no es solo verificar resultados; es auditar trayectorias de ejecución, interceptar efectos secundarios y bloquear comportamientos peligrosos. Sus componentes mínimos son:

    1) Diseño del sandbox

    • Ejecuta cada run del agente en un contenedor efímero o microVM sin acceso de salida (egress blocked).
    • Monta datasets de prueba y mocks en el filesystem; destruye el entorno al terminar.
    • No expongas secretos ni claves reales: usa vaults de test que devuelvan credenciales ficticias.

    Referencias: Docker, Firecracker.

    2) Mocking y simulación de tools

    • Intercepta function-calls y reemplázalas por mocks que:
      • Regresen respuestas realistas.
      • Generen métricas: latencia simulada, tasa de errores, costes.
      • Registren parámetros y contexto.
    • Ejemplo: delete_user(user_id) devuelve {status: "mocked", user_id} y queda registrado en trazas.

    Referencia: OpenAI Function Calling docs.

    3) Trazabilidad de la trayectoria (traces)

    • Registra: prompts, respuestas intermedias, herramientas invocadas, embeddings consultados, scores de retrieval.
    • Guarda trazas en un formato navegable (JSONL) y con versión del modelo.
    • Integra una capa de observabilidad para análisis post-mortem: Langfuse u otros servicios de tracing. También se puede integrar con herramientas como LangChain/observability.

    4) Guardrails cuantitativos y evaluadores automáticos

    • Umbrales automáticos que abortan la ejecución:
      • Límite de tokens por run (ej. 50k tokens).
      • Límite de coste por evaluación.
      • Número máximo de llamadas a herramientas (ej. 10).
    • Métricas de seguridad: intentos de acceso a APIs prohibidas, intentos de exfiltración.
    • LLM-as-a-Judge: usa un segundo modelo con temperature=0 para revisar la coherencia y seguridad de la trayectoria (evaluación estructurada: PASS/WARN/FAIL).

    5) Integración en CI/CD

    • Cada PR que incluya cambios en agentes debe disparar pipelines del harness.
    • No permitir merge si el harness devuelve FAIL en criterios críticos (seguridad, uso de herramientas prohibidas, loops).
    • Generar reportes legibles: timeline de decisiones, evidencia de mocks, recomendación humana para escalado.

    Ejemplo real (simplificado)

    Objetivo: “Optimizar consultas SQL lentas”.

    • Sin harness: el agente propone eliminar tablas, lo ejecuta y rompe el servicio.
    • Con harness: delete_table está mockeado; el agent llama la herramienta, el harness registra la decisión y el LLM-judge marca la acción como destructiva → FAIL. Equipo revisa prompt y reglas antes de permitir acción real.

    Riesgos, limitaciones y gobernanza

    • No existe aún un estándar único; la industria arma soluciones híbridas (Docker + observabilidad + LLM-judge).
    • El harness reduce riesgos, no los elimina: necesita gobernanza humana sobre qué decisiones puede automatizar el agente.
    • Monitorización continua: el harness debe seguir en producción en modo controlado (shadow runs, canary) incluso después del rollout.

    Checklist mínimo antes de dar acceso real

    • Contenedor sandbox probado y reproducible.
    • Todas las herramientas mockeadas disponibles en harness.
    • Trazas completas y auditable por humanos.
    • Umbrales configurados (tokens, coste, llamadas).
    • LLM-judge integrado y reglas de CI/CD que bloqueen merges.

    Dominicode Labs

    Para equipos que construyen infra de agentes y harnesses, explorar investigaciones y plantillas operativas puede acelerar la adopción segura. Una continuación lógica para experimentar con setups híbridos y pipelines de observabilidad es Dominicode Labs.

    FAQ

    Respuesta: ¿Qué es exactamente un Agentic Harness?

    Es la infraestructura que aísla, simula, traza y limita la ejecución de agentes autónomos para que puedan evaluarse y auditarse antes de interactuar con sistemas reales.

    Respuesta: ¿Cuándo debo usar un harness?

    Cuando un agente pueda modificar sistemas, acceder a datos sensibles o ejecutar acciones con impacto operativo. Es obligatorio antes de dar acceso a producción.

    Respuesta: ¿Qué herramientas necesito para empezar?

    Componentes básicos: sandbox (p. ej. Docker o Firecracker), mocks de APIs, sistema de trazas (JSONL) e integración con una herramienta de observabilidad como Langfuse.

    Respuesta: ¿Cómo funciona el LLM-judge?

    Un segundo modelo con temperatura cero revisa la trayectoria del agente (prompts, herramientas, decisiones) y emite una evaluación estructurada (PASS/WARN/FAIL) basada en reglas predefinidas.

    Respuesta: ¿El harness evita la gobernanza humana?

    No. El harness reduce riesgos operativos y automatiza controles, pero requiere gobernanza humana para decidir qué acciones se delegan y qué reglas son aceptables.

    Respuesta: ¿Dónde guardo las trazas y cómo las analizo?

    Guarda trazas en formato navegable (por ejemplo JSONL) con versión del modelo y métadatos. Analiza con una capa de observabilidad o herramientas de tracing para post-mortem y auditoría.

  • Cómo montar un segundo cerebro con Claude Code para gestión del conocimiento

    Cómo montar un segundo cerebro con Claude Code para gestión del conocimiento

    Como montar un segundo cerebro con Claude code

    Si buscas cómo montar un segundo cerebro con Claude Code, aquí tienes una estrategia técnica, reproducible y orientada a equipos que trabajan con código. No es magia: es arquitectura. Trata tus notas como código fuente, versiona todo en Git y deja que Claude Code razone sobre Markdown estructurado para capturar, recuperar y sintetizar conocimiento técnico.

    Documentación de referencia: Claude Code. Para ingesta automatizada, n8n.

    Resumen rápido (lectores con prisa)

    Qué es: Un repositorio de Markdown gestionado por Claude Code que actúa como segundo cerebro técnico.

    Cuándo usarlo: Cuando quieras operar conocimiento técnico como código, con control de versiones, búsqueda semántica y automatización.

    Por qué importa: Reduce fricción entre captura y reutilización, mejora durabilidad y facilita síntesis automatizada.

    Cómo funciona (esencial): Notas en Markdown con frontmatter, indexadas por búsqueda semántica local, gobernadas por un archivo CLAUDE.md y accionadas por un agente CLI.

    Ideas clave

    • Texto plano + Git: durabilidad, portabilidad y trazabilidad.
    • Metadatos estructurados: frontmatter obligatorio para búsquedas precisas y ahorro de tokens.
    • Claude Code como motor activo: agente CLI que crea, etiqueta, sintetiza y propone cambios (PRs).
    • Ingesta automatizada: usar n8n para pipelines que conviertan señales (Slack, GitHub, newsletters) en notas Markdown.

    Tabla de contenidos

    Como montar un segundo cerebro con Claude code: diseño y principios

    El objetivo es simple: minimizar la fricción entre capturar ideas y convertirlas en artefactos reutilizables (ADRs, snippets, post-mortems). Tres principios guían el diseño:

    • Texto plano y Git: durabilidad y portabilidad.
    • Metadatos estructurados: permiten búsquedas precisas sin cargar todo el repositorio.
    • Agente CLI como motor activo: Claude Code actúa (crea, etiqueta, sintetiza) en lugar de solo devolver resultados.

    La propuesta técnica es un repositorio local de Markdown, indexado por una búsqueda semántica local y gobernado por reglas en un archivo CLAUDE.md. Claude Code usa ese contexto para operar de forma coherente.

    Estructura del repositorio (parámetros prácticos)

    Adapta el método PARA (Projects, Areas, Resources, Archives) con convenciones claras. Una topología sugerida:

    /knowledge-base
    /01-projects
    /02-areas
    /03-resources
    /04-archives
    CLAUDE.md

    Adaptación del método PARA

    • Archivos Markdown (.md) con YAML frontmatter en la cabecera.
    • Nombres de archivo semánticos: 2026-04-migracion-postgres.md o auth-use-cases-login.md.
    • Limita el tamaño de archivos (ideal < 1.5k palabras por nota) para mantener la relevancia en búsquedas semánticas.

    Ejemplo de frontmatter

    —
    title: Rate limiting en Express con Redis
    date: 2025-04-10
    tags: [backend, nodejs, redis, performance]
    status: active
    —

    El frontmatter permite a Claude filtrar sin leer todo el contenido y reduce consumo de tokens.

    CLAUDE.md: memoria persistente y reglas del agente

    CLAUDE.md es la gobernanza del segundo cerebro. Define el rol del agente, las reglas de ingestión, los comandos permitidos y las prioridades de búsqueda.

    Contenido mínimo recomendado:

    • Rol (ej. “Actúa como gestor de conocimiento técnico”).
    • Reglas de escritura (frontmatter obligatorio, plantillas).
    • Reglas de búsqueda (usar Semantic Search antes de cargar archivos completos).
    • Protocolos de modificación (p. ej. “Mostrar PR antes de borrar”).

    Con esto, cada sesión arranca con el mismo contrato operativo, evitando decisiones erráticas del modelo.

    Flujos de trabajo operativos (ejemplos reales)

    Algunos flujos operativos que funcionan en equipos técnicos:

    1) Ingesta rápida (post-reunión)

    • Acción: pega el texto bruto en la terminal.
    • Prompt: “Extrae decisiones, riesgos y tareas; crea /01-projects/migracion-postgres.md con frontmatter y lista de tasks.”
    • Resultado: nota creada, etiquetada y commiteada.

    2) Búsqueda semántica y recuperación

    Prompt: “Busca soluciones documentadas para latencia en queries SQL en los últimos 12 meses y sintetiza los patrones comunes.” Claude usa Semantic Search para limitar los archivos que carga y devuelve una síntesis accionable.

    3) Generación de ADRs

    Prompt: “Lee notas con tags #arquitectura y #microservicios, encuentra trade-offs recurrentes y genera un primer borrador de ADR con pros/cons y migración paso a paso.”

    4) Mantenimiento automatizado

    Prompt: “Lista archivos en /03-resources sin tags; propone tags automáticos y muestra la diff antes de aplicar.”

    Orquestación externa: n8n para captura y pipelines

    Para entradas automáticas (Slack, GitHub stars, newsletters), crea workflows en n8n que:

    • Extraigan el contenido.
    • Conviertan a Markdown con frontmatter básico.
    • Guarden en /03-resources o /01-projects.

    Así tu segundo cerebro se alimenta sin intervención manual y Claude tiene material fresco al iniciar la sesión.

    Consideraciones operativas y limitaciones

    • Costos y tokens: obliga al agente a usar Semantic Search local antes de enviar datos al modelo para ahorrar tokens.
    • Context window: evita pedir que el agente “lea todo”; diseña prompts que recuperen subsets relevantes.
    • Seguridad: el repositorio puede contener notas sensibles. Aplica cifrado o repositorios privados; controla accesos.
    • Evolución: revisa periódicamente las convenciones en CLAUDE.md y actualiza plantillas.

    Integración con flujo de trabajo real (CI / PRs)

    Siempre que Claude genere cambios significativos:

    • Crea un branch y un PR automático.
    • Ejecuta CI (tests, linters, SCA) en un entorno aislado (VM/Container).
    • Usa n8n o pipelines para devolver resultados al CLI y permitir que Claude revise y corrija si es necesario.

    Esto evita merges automáticos sin validación humana.

    Conclusión y primer paso accionable

    Cómo montar un segundo cerebro con Claude code no es un truco de productividad: es una decisión de arquitectura que convierte notas en activos reutilizables. Empieza hoy con estos tres pasos:

    1. crea la topología PARA en un repositorio Git,
    2. añade frontmatter obligatorio y un CLAUDE.md con reglas básicas,
    3. prueba un flujo de ingesta simple (reunión → nota creada por Claude).

    Luego automatiza la captación con n8n y define tu política de PR/CI. Haz esto y tu conocimiento dejará de ser un archivo muerto: se convertirá en una base de decisión viva y accionable.

    Eso es la infraestructura: dónde viven las notas y quién las gobierna. Lo que escribes dentro de cada archivo decide si el agente las recupera enteras o partidas por la mitad, y de eso va Zettelkasten para developers.

    Mención: Dominicode Labs

    Para complementar flujos de trabajo y pruebas de concepto relacionadas con automatización y agentes, considera explorar recursos prácticos y experimentos en Dominicode Labs. Es una continuación lógica para equipos que buscan implementar pipelines y agentes en entornos reales.

    FAQ

    ¿Qué formato deben tener las notas?

    Archivos Markdown con YAML frontmatter en la cabecera. Nombres semánticos y notas cortas (ideal < 1.5k palabras).

    ¿Por qué usar frontmatter?

    El frontmatter permite filtrar y priorizar sin cargar todo el contenido, reduciendo consumo de tokens y haciendo las búsquedas más precisas.

    ¿Cómo ahorro tokens al usar Claude?

    Obliga al agente a ejecutar Semantic Search localmente y solo enviar al modelo los archivos más relevantes; evita pedidos que “lean todo” el repositorio.

    ¿Qué hace CLAUDE.md?

    Es el contrato operativo: define el rol del agente, reglas de ingestión, plantillas, comandos permitidos y protocolos de PR/edición.

    ¿Qué rol juega n8n en esta arquitectura?

    n8n orquesta ingestas automáticas (Slack, GitHub, newsletters): extrae contenido, genera Markdown con frontmatter y lo guarda en las carpetas correspondientes del repositorio.

    ¿Cómo integro cambios de Claude en mi flujo de Git?

    Claude debe crear branches y PRs automáticos; la CI ejecuta tests/linters y se evita el merge automático sin validación humana.

  • Cómo diseñar productos donde la IA es el núcleo

    Cómo diseñar productos donde la IA es el núcleo

    Diseño de productos AI-first — no “le pegamos un chatbot”, sino productos donde la IA es el core. Conecta con tu trabajo del AI Spec Builder

    Tiempo estimado de lectura: 4 min

    • Idea clave: Un producto es AI-first cuando deja de tener sentido sin la IA; no basta con añadir un chatbot.
    • Idea clave: Tres pilares técnicos: interfaces generativas, orquestación/agentic workflows y manejo de estado y resiliencia.
    • Idea clave: Implementa outputs estructurados, streaming, RAG y sandboxes; automatiza observabilidad y testea con mocks deterministas.

    Introducción

    “Diseño de productos AI-first — no ‘le pegamos un chatbot’, sino productos donde la IA es el core.” Si eso suena redundante, prueba a eliminar el modelo de tu producto: ¿qué queda? Si queda una app con una feature menos, no construiste un producto AI-first. Construiste lo que todos ya conocen: un chatbot pegado con cinta.

    Este artículo explica, con criterio técnico, qué implica realmente diseñar productos donde la IA es el núcleo —no un accesorio— y cómo ese criterio guió el diseño del AI Spec Builder.

    Resumen rápido (lectores con prisa)

    Qué es: Un enfoque de producto donde la IA es indispensable para entregar valor.

    Cuándo usarlo: Cuando quitar el modelo deja el producto sin sentido.

    Por qué importa: Cambia arquitectura, UX y requisitos de seguridad/observabilidad.

    Cómo funciona: Interfaces generativas + orquestación de tools + outputs estructurados y bucles de corrección.

    Diseño de productos AI-first — no “le pegamos un chatbot”: la regla que lo define todo

    La regla es simple y brutal: la IA es core cuando el producto deja de tener sentido sin ella. Punto.

    Eso cambia la arquitectura. No hablamos de “mejorar formularios” sino de invertir el flujo: el usuario entrega intención desestructurada; el sistema devuelve estructura accionable. Si tu interfaz puede ser reemplazada por un botón “Generar” y todo sigue funcionando, no entraste en el territorio AI-first.

    Tres pilares técnicos imprescindibles

    1) Interfaces generativas (Generative UI)

    El frontend deja de ser un conjunto de pantallas fijas. El LLM decide qué componente mostrar: formulario, tabla, gráfico, snippet de código. En vez de devolver Markdown, el backend debe enviar instrucciones estructuradas que el cliente renderice como componentes React o Web Components.

    2) Orquestación y agentic workflows

    El modelo no solo predice texto. Invoca herramientas: queries a bases de datos, ejecución de tests en sandboxes, llamadas a APIs internas. Diseña un grafo de capacidades (capability graph) y un mecanismo seguro que otorgue permisos granularmente al agente.

    3) Estado y resiliencia frente a la no-determinación

    Los modelos son probabilísticos. Implementa:

    • Outputs estructurados (JSON + esquemas Zod/JSON Schema) para validación automática.
    • Bucles de autocorrección en backend que reintenten o transformen la respuesta antes de exponerla al usuario.
    • Observabilidad: métricas de tokens, latencia, tasa de corrección.

    Caso práctico: AI Spec Builder — arquitectura y flujo

    AI Spec Builder no es un “formulario con IA”. Es una herramienta donde la IA actúa como Tech Lead.

    Flujo resumido:

    1. Usuario envía intención desestructurada.
    2. LLM ejecuta un bucle de clarificación: detecta lagunas y devuelve preguntas técnicas de alto valor.
    3. Respuestas del usuario actualizan en tiempo real un documento estructurado (Spec). El “chat” es control; el Spec es el producto.
    4. Al confirmar, el sistema dispara tools que generan esquema Prisma, contratos OpenAPI y tickets en el tracker.

    Si quitas el LLM, no queda documento útil. Esa dependencia es la prueba de que la IA es el core.

    Obstáculos reales y soluciones prácticas

    • Latencia: streaming obligatorio (SSE/WebSockets) y renderizado optimista. No bloquees la UI; muestra progreso parcial.
    • Costes de contexto: usa RAG y cachés semánticas para inyectar solo lo esencial en cada prompt. Implementa compresión y chunking del historial.
    • Confianza del output: fuerza structured outputs via esquemas; valida con Zod y aplica transformaciones si hace falta.
    • Seguridad de tools: sandboxes para ejecución de código, límites de tiempo y quotas por sesión; audita cada llamada del agente.
    • Testing: crea harnesses que mockeen el LLM con respuestas deterministas y casos de fallo para validar flujos completos.

    Recomendaciones concretas para Tech Leads

    • Pregunta antes de diseñar: “¿qué deja de resolverse si quitamos el modelo?” Si la respuesta no es clara, replantea el scope.
    • Diseña contrato UI ↔ LLM: define los tipos de respuesta esperados y diseña parsers robustos.
    • Implementa streaming desde el primer MVP. El usuario percibe velocidad; la IA necesita tiempo.
    • Externaliza state semántico a una vector DB y usa RAG; no recargues cada prompt con todo el historial.
    • Automatiza observabilidad: errores de parseo, reintentos, uso de herramientas y costes por sesión.
    • Mantén el control humano en las decisiones críticas; la IA sugiere, el humano valida.

    Lecturas y herramientas útiles

    Diseñar AI-first es más disciplina que magia. No se trata de “meter IA” en un producto existente, sino de reimaginar el flujo de valor alrededor de una capacidad que razona, completa y orquesta. Si tu equipo entiende y aplica eso —como hicimos con AI Spec Builder— estás construyendo algo que sobrevivirá más allá del hype.

    FAQ

    Respuesta: ¿Qué significa exactamente “AI-first”?

    AI-first significa que la propuesta de valor del producto depende de la IA; si quitas el modelo, el producto deja de tener sentido o pierde su función principal.

    Respuesta: ¿Cuándo debo considerar rediseñar un producto como AI-first?

    Cuando el flujo de valor puede optimizarse invirtiendo la dirección: el usuario aporta intención desestructurada y la IA devuelve estructura accionable que no sería práctica sin automatización cognitiva.

    Respuesta: ¿Qué es una “Generative UI”?

    Es una interfaz donde el modelo decide qué componente mostrar y en qué formato, y el backend envía instrucciones estructuradas que el cliente renderiza como componentes dinámicos.

    Respuesta: ¿Cómo se protege la ejecución de tools del agente?

    Mediante sandboxes, límites de tiempo, cuotas por sesión y auditoría de cada llamada; además, otorga permisos granularmente según un grafo de capacidades.

    Respuesta: ¿Qué prácticas reducen la latencia percibida por el usuario?

    Streaming (SSE/WebSockets), renderizado optimista y mostrar progreso parcial en vez de bloquear la UI.

    Respuesta: ¿Cómo validar outputs generados por la IA?

    Forzar salidas estructuradas (JSON + esquemas), validar con Zod o JSON Schema y aplicar bucles de corrección antes de exponer al usuario.

    Respuesta: ¿Qué pruebas recomendar para flujos que dependen del LLM?

    Crear harnesses que mockeen el LLM con respuestas deterministas y casos de fallo para validar flujos completos, incluyendo herramientas y errores de parseo.

    Respuesta: ¿Qué debe contener un contrato UI ↔ LLM?

    Definición de tipos de respuesta, esquemas esperados, reglas de reintento y parsers robustos para validar y transformar respuestas antes de renderizar.

  • Comparativa de Claude Code y Cursor para desarrolladores en 2026

    Comparativa de Claude Code y Cursor para desarrolladores en 2026

    Claude Code vs Cursor en 2026: cuándo usar cada uno — Comparativa honesta basada en flujos reales

    Tiempo estimado de lectura: 4 min

    • Claude Code es la herramienta de maquinaria: automatización, pipelines y transformaciones en lote.
    • Cursor es el artesano: edición visual, diffs en contexto y pair programming asistido por IA.
    • Asignar la tarea a la interfaz correcta reduce fricción: uso CLI/agents para procesos reproducibles y el IDE para juicios semánticos.

    Claude Code vs Cursor en 2026: cuándo usar cada uno — eso no es una discusión de modelos, es una discusión de interfaz y fricción. Ambas herramientas sirven a la misma ambición (hacerte más productivo), pero en 2026 la diferencia práctica está en qué tipo de trabajo quieres sacar de tu cabeza y poner en piloto automático. En este artículo comparo Claude Code (CLI/headless) y Cursor (IDE visual) basándome en flujos reales: refactors masivos, creación de features y debugging en producción. No hay benchmarks sintéticos; hay decisiones que rompen builds o liberan producto.

    Resumen rápido (lectores con prisa)

    Claude Code: CLI para automatización, pipelines y transforms en lote. Cursor: IDE visual para edición interactiva, diffs en contexto y pair programming. Usa Claude Code para reproducibilidad y escala; usa Cursor para juicios semánticos y cambios que requieren inspección visual.

    Claude Code vs Cursor en 2026: resumen rápido

    – Claude Code (CLI): pensado para automatización, pipelines, scripts y trabajo en lote. Ideal para orquestar agentes sin interfaz gráfica, ejecutar transforms en monorepos y procesar logs pesados. (paquete npm: paquete npm, Anthropic: Anthropic)

    – Cursor (IDE): pensado para el trabajo artesanal dentro del editor. Contexto visual, diffs en vivo, edición interactiva y pair programming asistido por IA. (Cursor)

    Ambas pueden usar modelos avanzados; la ganancia real viene de asignar a cada herramienta la tarea que mejor gestiona su interfaz.

    1) Features nuevas: scaffolding y lógica inicial

    Cuando arrancas una funcionalidad, necesitas dos cosas: rapidez para generar boilerplate y control para validar decisiones arquitectónicas.

    Usa Cursor si…

    • tu feature es UI/UX, componentes React/Next/Angular o cambios que requieren vista simultánea de varios archivos.
    • Cursor muestra el diff en contexto, te permite aceptar cambios parciales y mantener el control línea a línea. Es pair programming con atajos.

    Usa Claude Code si…

    • vas a generar servicios backend desde un esquema: scripts que lean un SQL/JSON Schema, generen controladores, tests y terraform en lote.
    • Un workflow típico: un script Bash alimenta Claude con el esquema y crea un PR con estructura inicial, lista para revisión. No abres centenares de archivos; revisas el PR.

    Ejemplo (flujo Claude Code): un comando que toma un esquema y produce controladores, ejecutado desde CI o local en terminal, sin interfaz gráfica interrumpida.

    2) Refactors masivos y migraciones

    Aquí se gana o se pierde integridad del sistema.

    Claude Code brilla cuando…

    • necesitas migraciones sistemáticas: buscar patrones con ast-grep, encadenar transformaciones con sed/perl/jq y delegar la modificación a un agente que produzca PRs.
    • Es fire-and-forget, reproducible y fácil de auditar.

    Cursor es la opción segura cuando…

    • el refactor toca lógica de dominio y contratos implícitos. Necesitas validar cada cambio con pruebas y juicio humano.
    • Cursor te permite intervenir en cada paso con contexto visual.

    Regla práctica: si puedes expresar la transformación como patrón AST y confiar en pruebas automatizadas, usa Claude Code. Si la transformación requiere juicio semántico sobre reglas de negocio, usa Cursor.

    3) Debugging: local vs infra

    – Cursor es superior para errores locales: reproduces, el IDE captura stacktrace, envía contexto al asistente y te marca la línea problemática. El ciclo es inmediato y visual.

    – Claude Code es la herramienta natural para logs y debugging infra: conecta por SSH, procesa gigas de logs con pipelines (cat error.log | claude --print "resume patrón de errores") y no rompe tu máquina local. Ideal para memory leaks, dumps o análisis de trazas distribuidas.

    Integración práctica (hooks y CI)

    No es “usar uno u otro”; es asignar tareas. Ejemplos concretos:

    • Revisor automático de PRs: Claude Code integrado en un job de CI o hook pre-push con Husky. El agente valida patrones y marca “Missing Tests”.
    • Patch iterativo de UI: Cursor para proponer cambios, revisar visualmente y aceptar commits parciales.

    Tabla de decisión rápida

    Escenario Recomendación
    Componentes UI y revisión visual Cursor
    Migraciones masivas (monorepo) Claude Code
    Debugging local (reproducción en IDE) Cursor
    Análisis de logs/infra remota Claude Code
    Scaffolding backend/infra as code Claude Code
    Refactors de lógica de negocio crítica Cursor

    Riesgos y buenas prácticas

    • Tokens y coste: cualquier workflow que pase megabytes de código a un LLM necesita filtrado (excluir node_modules, builds, package-lock.json) y paginar el contexto.
    • Contexto parcial: Claude Code trabaja con lo que le das. Añade tests y fixtures para reducir falsos positivos.
    • Auditoría: versiona prompts y scripts en el repo. Revisa los PRs generados por agentes como revisas cualquier patch humano.

    Conclusión clara

    No es una elección excluyente. Cursor es el artesano: detalle, iteración y control. Claude Code es la maquinaria: automatización, pipelines y transformaciones en lote. En 2026 los equipos más efectivos combinan ambos: Cursor para diseñar y verificar, Claude Code para escalar y ejecutar. Tu criterio técnico consiste en decidir, a diario, qué tipo de fricción quieres eliminar y cuál quieres mantener para no romper la base de código.

    Para equipos interesados en explorar workflows, agentes y automatización aplicados a ingeniería, consulta Dominicode Labs como continuación lógica para experimentar con pipelines reproducibles y hooks de CI.

    FAQ

    ¿Cuándo debo elegir Claude Code sobre Cursor?

    Elige Claude Code para tareas reproducibles y en lote: migraciones sistemáticas, scaffolding backend desde esquemas y análisis de logs a escala.

    ¿Cuándo es mejor Cursor?

    Cursor es mejor para cambios que requieren inspección visual, diffs en contexto y juicios semánticos sobre lógica de negocio o UX.

    ¿Puedo usar ambos en el mismo flujo?

    Sí. Un enfoque práctico es usar Cursor para diseñar y verificar, y Claude Code para ejecutar y escalar los pasos repetibles mediante CI y hooks.

    ¿Cómo gestiono el riesgo de exponer código sensible a modelos?

    Filtra el input (excluir node_modules, builds y lockfiles), paginate el contexto y mantén tests/fixtures para validar salidas antes de aplicar cambios.

    ¿Qué herramientas concretas se mencionan para migraciones y hooks?

    Se mencionan ast-grep para patrones AST y Husky para hooks de pre-push. También se refiere al paquete de Claude Code en paquete npm y a Anthropic.

    ¿Qué prácticas de auditoría recomiendan?

    Versiona prompts y scripts en el repo, revisa PRs generados por agentes como revisas cualquier patch humano y registra cambios automatizados en CI para trazabilidad.

    ¿Dónde puedo probar Cursor y Claude Code?

    Cursor se encuentra en Cursor. Claude Code y recursos relacionados están disponibles via paquete npm y Anthropic.

  • Cómo construir un agente de IA con NestJS y Claude API

    Cómo construir un agente de IA con NestJS y Claude API

    Cómo construir un agente de IA con NestJS + Claude API

    Tiempo estimado de lectura: 4 min

    • Separar cliente LLM, registro de herramientas y loop de agente para modularidad y pruebas.
    • Herramientas como contratos JSON-schema y validación antes de ejecución.
    • Agent loop controlado: límites de iteraciones, métricas y manejo de errores normalizado.
    • Producción: no bloquear peticiones HTTP, usar SSE/WebSockets y proteger PII y costes.
    • Observabilidad y testing: trazas por sesión, mocks para provider y canary releases.

    Introducción

    Saber cómo construir un agente de IA con NestJS + Claude API es lo que separa una demo interesante de una pieza de infraestructura que puedas mantener en producción. En este artículo encontrarás la arquitectura, decisiones técnicas y patrones que realmente importan cuando implementas tool-calling de Claude dentro de un backend modular y tipado como NestJS.

    Un agente no es un chatbot: es un bucle de decisión. Recibe objetivo, decide herramientas, ejecuta, observa resultados y vuelve a razonar hasta resolver la tarea o agotar límites.

    Resumen rápido (lectores con prisa)

    Qué: Un agente es un bucle de decisión que orquesta llamadas a herramientas externas desde un LLM.

    Cuándo: Cuando necesitas que un LLM interactúe con sistemas externos (DB, APIs, logs) de forma controlada.

    Por qué importa: Permite trazabilidad, testing y control de costes frente a soluciones ad-hoc.

    Cómo: Separando un provider LLM, un registro de herramientas con schemas JSON y un agente que controla el loop y límites.

    Cómo construir un agente de IA con NestJS + Claude API: arquitectura y flujo

    Ese bucle —Agent Loop— obliga a diseñar responsabilidades claras. El agente recibe un objetivo, decide qué herramienta usar, ejecuta esa herramienta, observa el resultado y repite hasta resolver la tarea o agotar límites.

    Arquitectura mínima recomendada:

    • Proveedor del cliente LLM (Anthropic) como Provider de NestJS.
    • Registro dinámico de herramientas (ToolRegistryService) que mapea nombres/JSON-schema a métodos de servicios.
    • Motor de ejecución (AgentService) que orquesta el loop y gestiona historial, stop reasons y seguridad.

    Referencias: NestJS Docs y Anthropic Tool Use

    Capa 1 — AnthropicProvider: el cliente como dependencia inyectable

    Nunca newees el cliente de Anthropic en controladores o servicios. Crea un provider que se inyecte y centralice la lógica del cliente.

    • Lee ANTHROPIC_API_KEY mediante ConfigService.
    • Envuelve lógica de retries, backoff y métricas (tokens usados, latencia).
    • Permite mockear en tests unitarios.

    Ejemplo conceptual: el provider expone sendMessage(payload) que encapsula anthropic.messages.create() y normaliza la respuesta (stop_reason, content, tool_call).

    Beneficio: centralizas control de coste y modelo (p. ej. cambiar de Claude 3.5 a otro modelo sin tocar el resto).

    Capa 2 — ToolRegistry: herramientas como contratos JSON y servicios

    Claude espera herramientas descritas por JSON-schema. En el backend conviene modelarlas y validar antes de ejecutar.

    • Definir cada herramienta con nombre, descripción y schema (tipado TypeScript).
    • Mapear cada herramienta a un método de servicio inyectable (p. ej. UsersService.getById, LogsService.append).
    • Implementar granularidad: una herramienta = una responsabilidad.

    Diseño práctico:

    • ToolRegistryService mantiene un mapa { toolName -> { schema, executor } }.
    • executor(args) valida los args contra el schema y ejecuta el método correspondiente en try/catch.

    Así el agent loop no necesita switches gigantes; resuelve métodos dinámicamente.

    Capa 3 — AgentService: el bucle, stop_reasons y límites

    El AgentService orquesta el loop de decisión, mantiene el historial y aplica límites y políticas de seguridad.

    Patrón del Agent Loop

    1. Construir messages + tools (esquemas) y llamar a Anthropic.
    2. Leer stop_reason:
      • end_turn: devolver respuesta final.
      • tool_use: extraer tool_name y arguments.
    3. Ejecutar herramienta vía ToolRegistryService y añadir tool_result al historial.
    4. Repetir hasta end_turn o alcanzar un límite de iteraciones.

    Normas prácticas

    • Límite de iteraciones (p. ej. max 5) para evitar bucles y costes excesivos.
    • Cada iteración registra métricas: tokens, latencia, herramienta invocada.
    • Normaliza errores: si la herramienta falla, devuelve { error: 'timeout' } a Claude, no throws.

    Producción: latencia, UX y seguridad

    Al pasar a producción hay que priorizar experiencia de usuario, seguridad y observabilidad.

    Latencia y UX

    • No bloquees la petición HTTP principal. Emite progreso con SSE o WebSockets: “Pensando…”, “Consultando DB…”.
    • Opcional: respuesta rápida + notificación cuando el resultado final esté listo (webhook / push).

    Seguridad y validación

    • Valida argumentos de herramientas con class-validator/schema JSON antes de ejecutar.
    • Logs sensibles: evita enviar secrets o PII a la API de Claude.
    • Rate limits y circuit breakers en el provider para proteger tu backend y controlar facturación.

    Observabilidad

    Traza cada sesión como un árbol de spans: requests al LLM, ejecuciones de herramientas, errores.

    Integra herramientas de visualización y trazabilidad como Langfuse o LangSmith para visualizar flujos y coste por sesión.

    Testing y despliegue

    • Mockea el AnthropicProvider y el ToolRegistryService en tests unitarios.
    • Tests de integración: entorno con Claude sandbox o replay de respuestas deterministas.
    • Canary releases: habilita el agente en subset de usuarios antes de producir a toda la base.

    Coste y gobernanza

    • Mide tokens por iteración; extrapola a coste por sesión.
    • Define políticas: cuándo permitir tool-calling (p. ej. solo usuarios verificados) y límites diarios.

    Qué evitar (errores comunes)

    • Herramientas “dios” que hacen todo: dificultan autorización y testing.
    • Dejar excepciones sin capturar: provoca loops rotos y mala UX.
    • No auditar llamadas: sin trazabilidad no sabrás por qué el agente falló o costó tanto.

    Cierre práctico

    Construir un agente con NestJS + Claude API no es magia, es disciplina arquitectónica. Si abstraes el cliente, modelas herramientas como contratos y controlas el bucle con límites, obtienes un sistema escalable, testeable y seguro.

    En el siguiente artículo veremos ejemplos concretos de ToolRegistryService y patrones para emitir progreso en SSE desde NestJS para mejorar la experiencia del usuario.

    Dominicode Labs

    Para continuidad en temas de automatización y agentes, consulta recursos adicionales en Dominicode Labs. Es una fuente útil para patrones, ejemplos y plantillas prácticas que complementan esta arquitectura.

    FAQ

    ¿Qué es un agente de IA en este contexto?

    Un agente es un bucle de decisión que recibe un objetivo, decide qué herramienta invocar, ejecuta esa herramienta, observa el resultado y repite hasta completar la tarea o agotar límites.

    ¿Por qué usar un provider para Anthropic?

    Un provider centraliza la configuración del cliente (API key, retries, métricas), facilita el mock en tests y permite cambiar de modelo o proveedor sin modificar la lógica de negocio.

    ¿Cómo se describen las herramientas?

    Las herramientas se describen con nombre, descripción y un JSON-schema (tipado TypeScript). Se valida la entrada antes de ejecutar y se mapea a funciones/executors inyectables.

    ¿Qué es stop_reason y cómo se maneja?

    stop_reason indica la acción del LLM: end_turn para respuesta final o tool_use para invocar una herramienta. El agente interpreta y actúa según ese valor.

    ¿Cómo se asegura la producción respecto a latencia?

    No bloquear la petición HTTP principal; usar SSE o WebSockets para emitir progreso. También considerar respuestas rápidas con notificación posterior y aplicar límites de iteraciones para controlar latencia y coste.

    ¿Qué pruebas son recomendables?

    Mockear el provider y el registry en tests unitarios; usar sandbox o replays deterministas en integración; ejecutar canary releases antes de un despliegue completo.