DOMINICODE

Category: AI

  • Cómo Crear una Especificación Técnica Efectiva para Claude

    Cómo Crear una Especificación Técnica Efectiva para Claude

    ¿Quieres convertir una idea brillante en un plan técnico que no se desmorone en la primera integración?

    Tiempo estimado de lectura: 6 min

    • Empieza por el porqué: describir el valor antes de pedir diseño técnico.
    • Documenta y estructura: volcado de contexto organizado en secciones claras.
    • Limita y pide artefactos: define stack, restricciones y solicita outputs machine-readable.
    • Itera con pruebas: divide en fases, genera tests y checklist de aceptación desde el inicio.

    Introducción

    Poca gente habla de esto en voz alta: usar a Claude sin método es como dar un GPS a alguien que no sabe leer mapas. Te lleva rápido. Te deja en medio de la nada.

    Descubrí algo curioso trabajando con equipos: los proyectos con mejor documentación no son los más lentos. Son los que sobreviven. Y con IA, la supervivencia depende de tu habilidad para traducir intuiciones en contratos técnicos claros. Claude puede ser el mejor compañero para eso —si sabes cómo pedirle las cosas.

    Esto no es un manual académico. Es un plan para usar Claude y salir del “hacer que funcione” hacia “hacer que dure”.

    Resumen rápido (lectores con prisa)

    Qué es: método para convertir intuiciones en especificaciones técnicas usando Claude.

    Cuándo usarlo: cuando las decisiones afectan contratos, seguridad o arquitectura.

    Por qué importa: reduce ambigüedad, acelera integración y baja la deuda técnica.

    Cómo funciona: estructura el prompt, define stack y límites, pide artefactos machine-readable y tests en fases.

    Guía paso a paso

    1) Empieza por el porqué, no por el cómo

    No le sueltes al modelo: “Hazme el CRUD.” Suéltale: “Esto existe porque…”

    Explica el negocio en 3–5 frases. Quién usa el producto. Qué métricas importan. Qué es un éxito y qué es un fallo. Claude necesita entender el valor antes de diseñar la estructura. Si no sabe el porqué, propondrá soluciones bonitas que no resuelven nada real.

    2) Brain dump: vacía la cabeza en orden

    Haz un volcado de contexto. Todo. Usuarios, roles, integraciones, datos sensibles, presupuestos, deadlines. Todo en bruto. Luego organízalo en secciones:

    • Objetivo del producto.
    • Requisitos no negociables.
    • Integraciones externas.
    • Restricciones de coste o tiempo.

    Si no lo pones por escrito, la IA lo “olvidará” cuando la conversación crezca. La ventana de contexto es grande, pero limitada. La spec fija el rumbo.

    3) Define límites claros: el terreno de juego

    Un LLM sin límites propone arquitectura épica. Kubernetes para un formulario. Event Sourcing para un blog. Fija el stack y las reglas: Next.js o Angular, Postgres o Mongo, monolito o microservicios. Di lo que está permitido y lo que está prohibido.

    Esto no es control por control. Es evitar decisiones peligrosas. Cuanto más concreto seas, más útiles serán las propuestas de Claude.

    4) Usa a Claude como auditor: Red Teaming

    Hazle preguntas desagradables. Pídele que rompa el diseño.

    “Si la base de datos recibe 10k req/s, ¿qué falla?”

    “¿Qué pasa si el OAuth provider devuelve 500 por 30 segundos?”

    “Describe tres formas en que esto puede ser explotado.”

    Pedir a Claude que actúe como Staff Engineer es oro. Suele encontrar cuellos de botella y escenarios que no ves en la primera pasada.

    5) Pide un Plan Técnico Estructurado (no un ensayo)

    No le pidas “un diseño”. Pide un plan accionable y dividido en entregables. Que incluya:

    • Arquitectura general (componentes y responsabilidades).
    • Modelos de datos (tablas o colecciones, relaciones).
    • Contratos de API (endpoints, métodos, payloads).
    • Reglas de seguridad y manejo de secretos.
    • Estrategia de testing y despliegue.
    • Checklist de aceptación.

    Exige formatos concretos: interfaces TypeScript, OpenAPI, diagramas Mermaid. Claude los produce con disciplina si se lo pides.

    6) Prompt maestro: estructura rígida para resultados deterministas

    Empaqueta la solicitud final con bloques semánticos. Ejemplo sencillo que Claude entiende bien:

    <contexto_negocio>
    Resumen del problema en 3–5 frases.
    </contexto_negocio>

    <stack_requerido>
    Frontend: Next.js 14. Backend: Node 20. DB: PostgreSQL 15.
    </stack_requerido>

    <restricciones>
    Monolito. No sugerir microservicios. Cumplir GDPR.
    </restricciones>

    <output_esperado>
    Markdown con: arquitectura, modelos TypeScript, OpenAPI y Mermaid.
    </output_esperado>

    Sí: usa algo parecido. Claude procesa estructura. Evita “hazme algo bueno” y usa “hazme esto exacto”.

    7) Itera en pequeños pasos: divide para conquistar

    No le pidas “termina todo en un prompt”. Divide el plan en fases:

    • Fase 1: Modelo de datos y contratos.
    • Fase 2: Endpoints principales + seguridad.
    • Fase 3: Estrategia de despliegue y observabilidad.

    Aprueba cada fase antes de avanzar. Así mantienes coherencia y controlas la complejidad.

    8) Genera pruebas desde el principio

    Pide a Claude que escriba tests de aceptación junto al contrato. Un endpoint sin test es un contrato sin firma.

    Solicita ejemplos de payloads válidos e inválidos. Solicita tests automáticos que fallen si no cumples las reglas. Así la implementación se vuelve una verificación automática del plan.

    9) Convierte la spec en artefactos machine-readable

    No dejes todo en texto. Pide:

    • OpenAPI / Swagger.
    • Esquema DB (SQL o Prisma).
    • Interfaces TypeScript.
    • Mermaid para diagramas.

    Estos artefactos alimentan la fase de implementación y reducen la ambigüedad cuando uses Copilot o agentes de coding.

    10) Añade reglas de guardia: políticas y anti-patrones

    Incluye en la spec lo que NO se debe hacer. Ejemplos útiles:

    • No exponer tokens en el frontend.
    • No usar dependencias sin CVE review.
    • Todas las APIs deben ser idempotentes.
    • Tiempo máximo de respuesta: 500ms en endpoints críticos.

    La IA responde bien a instrucciones negativas si las formulas claras.

    11) Implantación práctica: .cursorrules y SPEC.md

    Pon la spec en el repo. No escondas nada en Google Docs. Dos archivos mínimos:

    • SPEC.md: objetivo, reglas, contratos, checklist de aceptación.
    • .cursorrules (o el archivo que tu herramienta use): reglas automáticas consumibles por agentes.

    Que la spec sea la primera lectura del modelo cada vez que se genere código.

    12) Checklist de revisión para PRs generados por IA

    No es lo mismo revisar un PR humano que uno generado por IA. Usa una checklist específica:

    • ¿Respeta la spec? (sí/no)
    • ¿Hay tests que cubren casos límite?
    • ¿Se siguen convenciones de seguridad?
    • ¿Hay duplicación innecesaria de lógica?
    • ¿Los nombres reflejan la intención del dominio?

    Si falla cualquiera, rechaza y pide reescritura a la IA con referencia a la sección exacta de SPEC.md.

    13) Historias reales (sin fantasías)

    Equipo A: arrancó sin spec. 10 librerías distintas, 3 sistemas de auth, un pico y nada funcionó. Reescritura completa en 3 semanas.

    Equipo B: escribió spec en 2 días, usó Claude para generar contratos y tests. Demo en 48 horas. Integración estable en producción. ¿Qué prefieres?

    14) Cuándo no usar Claude para esto

    Claude es excelente en diseño. No lo necesitas para:

    • Tiny fixes en funciones locales.
    • Tests unitarios triviales.
    • Autocompletado en IDE (usa Copilot si quieres velocidad inline).

    Usa Claude cuando la decisión impacte contratos, seguridad o arquitectura.

    15) Plantilla mínima de SPEC.md (pégala ya)

    Pon esto en la raíz del repo. No la copies palabra por palabra sin adaptar. Pero hazlo.

    – Título y objetivo en una frase.

    – Stack aprobado (y versiones).

    – Reglas arquitectónicas innegociables (3).

    – Interfaces/contratos principales.

    – Criterios de aceptación (tests que deben pasar).

    – Política de secretos.

    – Responsables y permisos de cambio.

    Hazlo ahora. No mañana.

    16) Metáfora que pega y no falla

    La spec es la brújula. Claude es el marinero diestro. Sin brújula, el marinero navega. Rápido. Pero a la deriva. Con la brújula, llega al puerto. A salvo.

    17) Urgencia real: la deuda técnica no perdona

    Cada PR aceptado sin spec es una deuda invisible. Se acumula. Multiplica el coste de cada iteración futura. Actuar ahora es barato. Reescribir después es caro.

    CTA: hazlo en 60 minutos

    Abre el repo. Crea SPEC.md con las seis secciones mínimas que te di.

    Si quieres, te doy la plantilla lista para pegar. Respóndeme con “Quiero la plantilla” y te la envío ahora mismo.

    Esto no acaba aquí. Si quieres, te enseño:

    • Un prompt maestro listo para Claude.
    • Un SPEC.md completo para un proyecto típico (Next.js + PostgreSQL).
    • Un .cursorrules ejemplo para que la spec sea leída por agentes.

    Dime cuál quieres y te lo mando. Tus commits lo agradecerán. Y dentro de seis meses, tu equipo también.

    Si quieres recursos y experimentos prácticos sobre automatización, agentes y workflows, revisa Dominicode Labs. Es una continuación lógica para quienes aplican estas prácticas en repos reales y pipelines de integración continua.

    FAQ

    ¿Qué debe contener la sección “Objetivo del producto” en SPEC.md?

    Respuesta

    Debe resumir en una frase el problema que se resuelve, los usuarios principales, y las métricas que determinan éxito o fallo. Manténlo en 2–3 líneas claras.

    ¿Cómo estructuro un prompt maestro para Claude?

    Respuesta

    Usa bloques semánticos: contexto negocio, stack requerido, restricciones y output esperado. Entrega ejemplos concretos y formatos de salida (TypeScript, OpenAPI, Mermaid).

    ¿Qué artefactos machine-readable son prioritarios?

    Respuesta

    Prioriza OpenAPI, esquema de BD (SQL/Prisma) e interfaces TypeScript. Estos permiten plug-and-play con herramientas de generación y tests automáticos.

    ¿Cuándo debo usar Claude vs Copilot?

    Respuesta

    Usa Copilot para autocompletado y fixes locales. Usa Claude para diseño, contratos, análisis de riesgos y generación de artefactos estructurados que guían implementaciones.

    ¿Qué incluir en la checklist de PRs generados por IA?

    Respuesta

    Incluye verificación de spec, cobertura de tests (casos límite), cumplimiento de reglas de seguridad y ausencia de duplicación. Si falla cualquiera, rechaza el PR.

    ¿Cómo integrar .cursorrules en el flujo CI?

    Respuesta

    Añádelo al repo raíz y configura el pipeline para validar que la spec se carga antes de generar artefactos. Automatiza checks que garanticen que los agents leen .cursorrules en cada run.

  • Mejorando rendimiento y SEO al migrar de Angular a Next.js 16

    Mejorando rendimiento y SEO al migrar de Angular a Next.js 16

    De Angular a Next.js 16: lo que aprendí migrando un proyecto real

    Tiempo estimado de lectura: 4 min

    • Rendimiento y SEO fueron el motor: migramos por Core Web Vitals malos, TTFB lento y bundle que penalizaba conversión móvil.
    • Server-first cambia la mentalidad: Next.js 16 y React Server Components mueven carga y lógica al servidor, reduciendo JavaScript en cliente.
    • Menos boilerplate para mutaciones: Server Actions permiten llamar funciones server-side desde formularios sin endpoints REST intermedios.
    • Fricciones reales: cache, alcance de “use client” y observabilidad requieren disciplina adicional en producción.

    De Angular a Next.js 16: lo que aprendí migrando un proyecto real empezó como un problema de negocio: Core Web Vitals malos, TTFB lento y un bundle que penalizaba conversión móvil. La migración no fue una moda técnica; fue una necesidad para reducir fricción de usuario y mejorar SEO técnico. Esto marcó cada decisión técnica que tomamos.

    Resumen rápido (lectores con prisa)

    Qué es: Next.js 16 (App Router) usa React Server Components para renderizar HTML en servidor y enviar JavaScript mínimo al cliente.

    Cuándo usarlo: cuando SEO, Core Web Vitals o TTFB afectan métricas de negocio y necesitas ejecutar lógica sensible en servidor.

    Por qué importa: reduce bundle inicial, mejora TTFB y simplifica flujos de datos server-side.

    Cómo funciona (resumen): renderizado server-side con funciones asíncronas para fetch/ORM, Server Actions para llamadas server desde forms y control explícito de caché y revalidación.

    De Angular a Next.js 16: por qué no es solo “aprender otra sintaxis”

    Angular es un framework opinado para SPAs: inyección de dependencias, RxJS y templates declarativos. Next.js 16 (App Router) invierte ese paradigma con React Server Components (RSC): renderizado en servidor, HTML entregado al cliente y JavaScript mínimo para interactividad. Documentación oficial Next.js.

    La diferencia no es menor: pasas de pensar “qué corre en el cliente” a “qué debe correr en el servidor”. Ese cambio impacta performance, seguridad y la forma en que estructuras estado y dependencias.

    Tres lecciones técnicas que cambiaron nuestro código

    1) RxJS se queda fuera del camino principal

    En Angular, RxJS orquesta peticiones, eventos y sincronizaciones. Eso ofrece control fino (cancelaciones, operadores), pero añade complejidad de mantenimiento (unsubscribe, memory leaks).

    En Next.js 16, Server Components son funciones async: await fetch() o llamadas al ORM desde el servidor. La simplicidad reduce boilerplate y evita parpadeos de carga en el cliente. Ejemplo real: reemplazar múltiples subscriptions por una única llamada asíncrona en el server simplificó la lógica y redujo errores de sincronización.

    Nota práctica: para cancelaciones del lado del cliente hay que usar explícitamente AbortController; la ergonomía de RxJS no existe por defecto.

    2) La inyección de dependencias se reimagina

    El contenedor DI de Angular es una comodidad arquitectónica (services providedIn: 'root'). React/Next no tienen un DI integrado. Las alternativas que adoptamos:

    • Instancias únicas exportadas desde módulos ES6 (clientes DB, SDKs).
    • React Context solo para estado UI que vive en cliente (tema, sesión).
    • Props/Composición para inyección explícita en componentes que dependen de servicios.

    Resultado: más explicitud y trazabilidad, pero más disciplina para no propagar dependencias globales por accidente.

    3) Server Actions: menos endpoints, menos boilerplate

    Migrar formularios del flujo Angular (form → HttpClient → endpoint REST → backend) a Server Actions colapsó la cadena. En Next.js 16 puedes llamar funciones en el servidor directamente desde el form:

    export async function updateUser(formData: FormData) {
  'use server';
  const name = formData.get('name') as string;
  await db.user.update({ where: { id: session.userId }, data: { name } });
  revalidatePath('/profile');
}

    El beneficio es claro: menos endpoints internos y menos código repetitivo. El riesgo: mezclar lógica de negocio en componentes si no separamos responsabilidades adecuadamente. Docs de Server Actions

    Fricciones reales que te van a doler en producción

    • Cache y freshness: Next.js App Router tiene capas de caché (memoization, data cache, route cache). Sin revalidate o cache: 'no-store' puedes servir datos obsoletos. Leer.
    • “use client” propagate cost: marcar un componente como cliente arrastra su subárbol y puede romper los beneficios del SSR si importas librerías pesadas.
    • Observabilidad de comportamiento: la frontera servidor/cliente exige testing más exhaustivo (end-to-end + integración server actions) y pipelines de CI que validen rendimiento.
    • Seguridad y surface area: Server Actions facilitan lógica server-side, pero exigen revisar permisos y sanitización con más rigor.

    Criterio práctico para Tech Leads: ¿vale la pena migrar?

    No migres por moda. Migra si:

    • Tu producto es público y SEO o Core Web Vitals impactan conversiones (ver métricas en web.dev/vitals).
    • El bundle inicial y TTFB están bloqueando métricas de negocio.
    • Necesitas ejecutar lógica sensible en servidor para reducir exposición o proteger IP.

    Mantén Angular si:

    • Es un dashboard interno con poca necesidad SEO.
    • El equipo domina RxJS y la arquitectura actual es sostenible.
    • El coste de migración supera el beneficio económico esperado.

    Conclusión

    La migración De Angular a Next.js 16: lo que aprendí migrando un proyecto real fue menos una reescritura técnica y más una reorganización de responsabilidades: qué corre en el servidor, cómo se inyectan dependencias y cómo se gestionan mutaciones. Next.js 16 ofrece ganancias reales en rendimiento y simplicidad operativa, pero exige disciplina (caché, límites use client, separación de responsabilidades). Si tu negocio lo justifica, la inversión devuelve rendimiento y una arquitectura más alineada con un futuro server-first. Si no, Angular sigue siendo una opción sólida y productiva.

    FAQ

    ¿Por qué migraron desde Angular?

    Migramos porque Core Web Vitals malos, TTFB lento y un bundle grande estaban afectando conversión móvil y SEO. La migración fue una decisión de negocio para reducir fricción de usuario y mejorar SEO técnico.

    ¿Qué reemplaza a RxJS en Next.js 16?

    No hay un reemplazo directo. En Next.js 16 se usa programación asíncrona en Server Components (await fetch(), llamadas al ORM) y, para cancelaciones cliente, AbortController. La lógica de orquestación que RxJS ofrecía suele simplificarse en el servidor o con patrones de composición en cliente.

    ¿Cómo funcionan las Server Actions?

    Server Actions son funciones que se ejecutan en el servidor y se pueden invocar desde formularios en el cliente. Reducen la necesidad de endpoints REST intermedios. Requieren separar responsabilidades para no mezclar lógica de negocio en componentes. Más detalles.

    ¿Cuáles son los mayores riesgos en producción?

    Los riesgos principales son caché y freshness (servir datos obsoletos sin revalidate), el coste de marcar componentes como cliente que arrastran subárboles pesados y la necesidad de mayor observabilidad y testing para la frontera servidor/cliente.

    ¿Cuándo no conviene migrar?

    No conviene migrar si el proyecto es un dashboard interno con poca necesidad SEO, si el equipo domina la arquitectura actual o si el coste de migración supera el beneficio económico esperado.

    ¿Cómo gestionar la inyección de dependencias sin DI?

    Usar instancias únicas exportadas desde módulos ES6 (clientes DB, SDKs), React Context para estado UI cliente y props/composición para inyección explícita en componentes. Esto aporta trazabilidad a costa de disciplina para evitar dependencias globales indeseadas.

  • Crea un agente en TypeScript con Mastra para soporte técnico

    Crea un agente en TypeScript con Mastra para soporte técnico

    Crea tu primer agente en TypeScript con Mastra

    Tiempo estimado de lectura: 6 min

    • Mastra es un framework nativo en TypeScript para construir agentes y flujos de IA con validación de esquemas en runtime.
    • Separar Agent, Tool y Model permite pruebas unitarias y facilita cambiar proveedor de LLM.
    • Usa Zod para convertir inputs/outputs del LLM en contratos verificables.
    • Incluye un ejemplo práctico listo para ejecutar (agente de soporte técnico) y reglas operativas para producción.

    Crear tu primer agente en TypeScript con Mastra es la forma más práctica de evitar la fragmentación entre Node.js y microservicios Python. Si tu stack es TypeScript, mantener todo en el mismo lenguaje reduce latencia, elimina fricciones en despliegue y preserva tipos end-to-end. En las siguientes secciones veremos qué es Mastra, su arquitectura y un ejemplo práctico listo para ejecutar.

    Resumen rápido (lectores con prisa)

    Mastra es un framework en TypeScript para agentes de IA que integra validación de esquemas con Zod.

    Separa responsabilidades en Agent, Tool y Model para pruebas y cambio de proveedor de LLM.

    Usa Zod para que las invocaciones a tools sean contratos verificables en runtime.

    Incluye un ejemplo práctico (agente de soporte) y recomendaciones para producción.

    Documentación y repositorio oficiales están disponibles para referencia.

    Crea tu primer agente en TypeScript con Mastra: por qué importa y cuándo usarlo

    Mastra es un framework nativo en TypeScript para construir agentes y flujos de IA. Su ventaja principal no es solo técnica: es contractual. Al integrar Zod para la validación de esquemas como parte del runtime, convierte las llamadas del LLM en contratos verificables, no en texto libre que “parece correcto”. Documentación: mastra.ai/docs. Repositorio: github.com/mastra-ai/mastra.

    Úsalo cuando quieras:

    • Ejecutar agentes dentro del mismo proceso Node/Next.js.
    • Forzar esquemas de entrada/salida con Zod.
    • Testear herramientas aisladas sin invocar modelos.

    No es la solución si necesitas capacidades avanzadas aún no soportadas por Mastra; evalúa la madurez del proyecto antes de producción.

    Arquitectura mínima: Agent, Tool y Model

    Divide responsabilidades desde el inicio:

    • Agent: orquesta la conversación, mantiene historial e instrucciones del sistema.
    • Tool: funciones asíncronas fuertemente tipadas (Zod). Son la única forma controlada en la que el agente “toca” el mundo.
    • Model: abstracción del proveedor de LLM (OpenAI, Anthropic, etc.). Cambiar proveedor debe ser un cambio mínimo.

    Esa separación permite testing unitario de herramientas y garantiza que la lógica de negocio no quede oculta en un prompt.

    Paso a paso: ejemplo práctico (Agente de soporte técnico)

    Instalación rápida

    mkdir mastra-agent && cd mastra-agent
npm init -y
npm install @mastra/core zod
npm install -D typescript @types/node tsx
npx tsc --init
export OPENAI_API_KEY="tu_api_key"

    1) Define la herramienta (Tool)

    Controla exactamente qué parámetros acepta el LLM:

    // src/tools/check-service.ts
import { createTool } from '@mastra/core';
import { z } from 'zod';

export const checkServiceTool = createTool({
  id: 'check-service-status',
  description: 'Consulta el estado operativo de un servicio interno por nombre.',
  inputSchema: z.object({
    service: z.enum(['api', 'database', 'frontend']),
  }),
  execute: async ({ context }) => {
    // Reemplaza por consultas reales a monitorización/DB
    const statuses = { api: 'degraded', database: 'operational', frontend: 'operational' };
    return { service: context.service, status: statuses[context.service], checkedAt: new Date().toISOString() };
  },
});

    2) Instancia el agente

    Define instrucciones claras (system prompt) que actúen como contrato operativo:

    // src/agent.ts
import { Agent } from '@mastra/core/agent';
import { checkServiceTool } from './tools/check-service';

export const supportAgent = new Agent({
  name: 'TechSupportAgent',
  instructions: `
    Eres un ingeniero de soporte de nivel 1.
    Antes de concluir que un servicio está caído, INVÓCAME la herramienta de estado.
    Responde con datos y recomendaciones técnicas claras.
  `,
  model: { provider: 'OPENAI', name: 'gpt-4o-mini' },
  tools: { checkServiceTool },
});

    3) Ejecuta el flujo

    Ejecuta el agente y deja que Mastra coordine modelo y tools:

    // src/main.ts
import { supportAgent } from './agent';

async function main() {
  const prompt = 'Los usuarios reportan lentitud. ¿Está la API bien?';
  const res = await supportAgent.generate(prompt);
  console.log(res.text);
}

main().catch(console.error);

    Lanza con npx tsx src/main.ts. Mastra coordina al LLM y las herramientas: si el modelo decide invocar checkServiceTool, el framework valida el input con Zod, ejecuta la función y alimenta la respuesta final.

    Reglas prácticas para llevar esto a producción

    1. Observabilidad desde el día 0: logs estructurados en cada invocación de tool (request id, input validado, tiempo, resultado).

    2. Errores como datos: las herramientas deben devolver errores tipados que el agente pueda razonar y comunicar (no lanzar excepciones sin contexto).

    3. Testing aislado: tests unitarios para execute y tests de integración para la orquestación. No confundas velocidad con cobertura.

    4. CI/CD: bloquea merges que introduzcan nuevas dependencias sin revisión de licencia/reputación. En entornos corporativos, valida paquetes recomendados por LLMs.

    5. Ownership y ADRs: cualquier herramienta crítica debe tener un Architecture Decision Record que explique por qué existe y cómo se prueba.

    Para guiar verificaciones de seguridad y dependencia sigue prácticas de NIST/OWASP (por ejemplo: owasp.org).

    Conclusión: Mantén el criterio humano donde importa

    Mastra te da la ergonomía de TypeScript y contratos verificables con Zod. Eso reduce alucinaciones estructurales y acelera integración en stacks web. Pero la ganancia real viene cuando aplicas disciplina: diseño previo, validación estricta, observabilidad y pruebas. Implementa el agente, mide cómo toma decisiones y exige que cualquier acción en producción esté documentada y testeada. En la próxima entrega de Dominicode mostraremos cómo añadir memoria persistente y encadenar múltiples tools para workflows complejos.

    Dominicode Labs

    Si trabajas en automatización, agentes o workflows y quieres ejemplos prácticos y guías operativas, consulta Dominicode Labs. Encontrarás recursos que complementan patrones de diseño y pruebas para agentes en producción.

    FAQ

    ¿Qué es Mastra?

    Mastra es un framework nativo en TypeScript para construir agentes y flujos de IA que integra Zod para validación de esquemas en runtime.

    ¿Cuándo debo usar Mastra?

    Cuando tu stack principal es TypeScript/Node.js y quieres ejecutar agentes en proceso, forzar esquemas de entrada/salida y testear herramientas sin invocar modelos externos.

    ¿Cómo asegura Mastra la validez de las llamadas a herramientas?

    Integra Zod como parte del runtime: las entradas a las tools se validan contra esquemas definidos y solo se ejecutan si cumplen el contrato tipado.

    ¿Puedo cambiar fácilmente el proveedor de LLM?

    Sí. La arquitectura separa Model como una abstracción, de modo que cambiar proveedor (OpenAI, Anthropic, etc.) debe ser un cambio mínimo en la configuración.

    ¿Qué prácticas de producción recomiendan?

    Observabilidad desde el día 0, errores como datos tipados, testing aislado, control de dependencias en CI/CD y ADRs para herramientas críticas.

    ¿Dónde encuentro la documentación y el código?

    La documentación oficial está en mastra.ai/docs y el repositorio en github.com/mastra-ai/mastra.

  • Cómo crear un MCP Server para integrar LLMs con seguridad

    Cómo crear un MCP Server para integrar LLMs con seguridad

    MCP servers explicados: qué son, para qué sirven y cómo crear el tuyo

    Entender los MCP servers explicados: qué son, para qué sirven y cómo crear el tuyo es importante si quieres conectar un LLM con datos y acciones de tu infraestructura sin abrir una caja negra insegura. El Model Context Protocol (MCP) busca estandarizar esa capa: separa el razonamiento del modelo de la ejecución real que hace tu código.

    Documentación y recursos oficiales:

    Tiempo estimado de lectura: 4 min

    Ideas clave

    • Un MCP Server expone Resources (solo lectura), Tools (acciones ejecutables) y Prompts (templates) para clientes LLM.
    • La comunicación puede ser por stdio (local) o SSE/HTTP (remoto) manteniendo credenciales en el servidor.
    • Empieza con capacidades de solo lectura; exige confirmación humana para escrituras peligrosas.
    • Implementa autenticación, rate limiting y auditoría con trace IDs para producción.

    Introducción

    Un MCP Server es un proceso ligero (local o remoto) que expone al cliente de IA tres tipos de capacidades bien definidas: Resources (solo lectura), Tools (acciones ejecutables) y Prompts (templates). El cliente (por ejemplo Claude Desktop, Cursor, Windsurf, o un agente en n8n) descubre esas capacidades y decide cuándo invocarlas. La comunicación suele usar stdio para ejecuciones locales o SSE/HTTP para conexiones remotas. Crucial: las credenciales y el acceso real permanecen en tu servidor; el LLM no las recibe.

    Resumen rápido (lectores con prisa)

    MCP es un protocolo para separar razonamiento (LLM) de ejecución (tu infra).

    Expone Resources (lectura), Tools (acciones) y Prompts (templates) para clientes LLM.

    Transporte: stdio local o SSE/HTTP remoto; credenciales se quedan en el servidor.

    Útil para integrar múltiples clientes LLM con una capa única, segura y versionable.

    Qué es un MCP Server

    Un MCP Server publica capacidades que los clientes LLM pueden descubrir y usar en tiempo de ejecución. Las capacidades son:

    • Resources: datos de solo lectura (esquemas, logs resumidos, métricas).
    • Tools: acciones ejecutables con entradas definidas por esquema.
    • Prompts: plantillas que combinan contextos y recursos relevantes.

    Por qué usar MCP en vez de una API ad-hoc

    • Estándar único: el mismo servidor puede trabajar con múltiples clientes LLM sin reescribir integraciones.
    • Seguridad mejorada: las credenciales no viajan en prompts.
    • Descubrimiento dinámico: el cliente lista herramientas y recursos disponibles en tiempo de ejecución.

    Arquitectura mínima de un MCP Server

    • Transporte: stdio (local) o SSE/HTTP (remoto).
    • Registro de capabilities: lista de tools/resources que el servidor publica.
    • Handlers: funciones que ejecutan las herramientas y devuelven contenido estructurado.
    • Logging/auditoría: registros de llamadas, inputs y outputs con firma/trace-id.

    Ejemplo práctico (Node.js + TypeScript)

    Instalación y preparación

    mkdir mi-mcp-server && cd mi-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript @types/node
npx tsc --init

    Ejemplo mínimo: src/index.ts

    import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
import os from "os";

const server = new Server({name:"mi-mcp", version:"0.1.0"}, {capabilities:{tools:{}}});

server.setRequestHandler(ListToolsRequestSchema, async ()=>({
  tools: [{ name: "get_system_info", description: "Info SO y memoria", inputSchema: { type: "object", properties: {}, required: [] } }]
}));

server.setRequestHandler(CallToolRequestSchema, async (req)=>{
  if (req.params.name === "get_system_info") {
    return { content: [{ type:"text", text: JSON.stringify({ platform: os.platform(), totalMemory: os.totalmem() }, null, 2) }] };
  }
  throw new Error("tool-not-found");
});

await server.connect(new StdioServerTransport());
console.error("MCP server listo");

    Compila con npx tsc y ejecuta node dist/index.js. Para clientes como Claude Desktop registra el comando en su config (paths en macOS/Windows según documentación del cliente).

    Qué exponer (y qué no)

    Empieza por recursos de solo lectura y herramientas inofensivas:

    • Recursos: esquemas de DB, logs resumidos, métricas con paginación.
    • Tools (lectura): consultas parametrizadas que devuelven resultados limitados.
    • Prompts: plantillas que pre-cargan recursos relevantes.

    Evita al principio: comandos de escritura (DROP, DELETE), accesos de shell indiscriminados, o cualquier endpoint que pueda cambiar estado sin confirmación humana. Implementa siempre un flujo de validación humana para acciones críticas.

    Producción: seguridad y operativa

    • Autenticación y autorización: el servidor debe gestionar credenciales y validar cada petición con roles.
    • Rate limiting y cuotas: evita que un prompt malicioso dispare herramientas repetidamente.
    • Auditoría inmutable: registra request/response con trace IDs, timestamps y hashes del prompt.
    • Testing: mocks para tools y tests end-to-end con clientes (stdio y SSE).
    • Paginación y resumido: no envíes logs enteros; ofrece ventanas y resúmenes para preservar tokens.

    Casos de uso reales y prácticas recomendadas

    • Integración con n8n: usa el MCP Server como puente para disparar workflows desde lenguaje natural sin exponer credenciales a la interfaz.
    • Revisión de PRs automatizada: expón diffs y reglas como recursos; la tool devuelve checklist y reportes en Markdown.
    • Soporte operador: diagnóstico de infra mediante logs resumidos y herramientas read-only que recogen métricas.

    Registra y versiona tus prompts y esquemas del MCP en el repo; trátalos como código crítico.

    Conclusión

    Los MCP servers explicados aquí son la pieza que convierte LLMs en componentes confiables dentro de una plataforma técnica. No es magia: es disciplina. Empieza pequeño (solo lectura), instrumenta todo, exige confirmación humana para escrituras y versiona los prompts. Si lo haces bien, tendrás agentes que razonan con seguridad y una única capa mantenible que conecta IA con tus sistemas.

    Mención: Dominicode Labs

    Para equipos que exploran automatización y agentes como parte de su plataforma técnica, puede ser útil revisar trabajos y prototipos en Dominicode Labs. Es una referencia contextual para enfoques de integración y experimentación práctica.

    FAQ

    ¿Qué diferencia a un MCP Server de una API tradicional?

    Un MCP Server define un estándar para que clientes LLM descubran y llamen capacidades (Resources, Tools, Prompts). Mantiene credenciales y lógica de ejecución en el servidor, evitando que se incrusten en prompts como suele pasar con APIs ad-hoc.

    ¿Cómo se comunican el cliente LLM y el MCP Server?

    La comunicación común es por stdio para ejecuciones locales o mediante SSE/HTTP para conexiones remotas. El cliente consulta las capabilities y llama handlers definidos por el servidor.

    ¿Qué precauciones de seguridad debo implementar?

    Implementa autenticación y autorización por roles, rate limiting, auditoría inmutable con trace IDs y validation humana para acciones que modifican estado.

    ¿Puedo exponer herramientas de escritura si las requisito?

    Sí, pero siempre detrás de controles estrictos: confirmación humana, autorización granular, pruebas y registros completos. Evita exponer inicialmente comandos destructivos.

    ¿Cómo se versionan prompts y esquemas?

    Registra y versiona prompts y esquemas en el repositorio del proyecto como parte del código crítico; aplica revisiones, pruebas y despliegues controlados.

    ¿Qué formatos de respuesta soportan las tools?

    Las tools devuelven contenido estructurado (por ejemplo objetos JSON con bloques de tipo texto o markdown). El SDK y el spec del MCP describen los schemas esperados.

    ¿Cuál es el transporte recomendado para producción?

    Para local, stdio es simple y seguro. Para entornos distribuidos, SSE/HTTP ofrece mayor flexibilidad; la elección depende de latencia, despliegue y requisitos de auditoría.

  • Cómo Context Engineering Mejora el Uso de IA en Proyectos Técnicos

    Cómo Context Engineering Mejora el Uso de IA en Proyectos Técnicos

    Context Engineering: el skill que separa a quien usa IA de quien la domina — Diferenciar prompt engineering de context engineering, con ejemplos prácticos en proyectos reales

    Context Engineering: el skill que separa a quien usa IA de quien la domina — Diferenciar prompt engineering de context engineering, con ejemplos prácticos en proyectos reales aparece en la primera línea porque esto no es semántica fina: si quieres resultados reproducibles con LLMs, primero dominas el contexto que les das.

    Resumen rápido (lectores con prisa)

    Qué es: Context engineering diseña pipelines que recuperan, filtran, reordenan y entregan exactamente la información que un LLM necesita. Cuándo usarlo: cuando buscas respuestas reproducibles y verificables de modelos. Por qué importa: reduce ruido y evita que el modelo «adivine». Cómo funciona (resumen): chunking semántico, RAG híbrido, re-ranking y trazabilidad del contexto.

    Los modelos no fallan por malos prompts. Fallan porque les lanzas una montaña de información sin estructura y esperan sentido. El paper “Lost in the Middle” documenta por qué contextos enormes con baja señal degradan la precisión: https://arxiv.org/abs/2307.03172.

    Context Engineering: qué es y por qué importa

    Prompt engineering modela la instrucción: rol, formato, few-shot. Es importante, pero es la punta del iceberg.

    Context engineering diseña pipelines que recuperan, filtran, reordenan y entregan exactamente la información que el modelo necesita. Es infraestructura. Es código. Es la diferencia entre un agente que improvisa y uno que actúa con datos verificables.

    Herramientas y lecturas útiles:

    Principios técnicos fundamentales

    • Chunking semántico: corta por límites lógicos (funciones, clases, secciones), no por número de caracteres. Un fragmento coherente = menos ambigüedad.
    • Recuperación híbrida (RAG avanzado): combina búsqueda vectorial con BM25 y filtrado por metadatos. Cada técnica cubre puntos ciegos de la otra.
    • Re-ranking con Cross-Encoders: recupera amplio, reordena preciso. El orden que lee el LLM importa.
    • Grafos de dependencia: extrae import graph para entregar solo archivos que dependen directamente del cambio que quieres hacer.
    • Instrumentación del contexto: registra qué se inyectó, tokens consumidos y rank scores para auditar decisiones.

    Ejemplo 1 — Refactorización en un monorepo TypeScript

    Problema frecuente: cambias la firma de un endpoint y esperas que el asistente actualice todo el frontend y backend.

    Enfoque ingenuo (solo prompt)

    Copias controladores y componentes al chat. Resultado: el modelo inventa imports, omite tipos compartidos y el build falla.

    Enfoque Context Engineering (profesional)

    1) Ejecuta análisis estático con ast-grep para localizar los nodos AST que llaman al endpoint.

    2) Genera un paquete de contexto pequeño: OpenAPI actualizado, la interfaz TypeScript compartida y los snippets AST afectados.

    3) Re-ranquea los fragmentos por relevancia y adjunta tests unitarios mínimos.

    Resultado: PR atómico, compilable y con pruebas que pasan. El LLM actúa sobre lo esencial, no sobre ruido.

    Ejemplo 2 — Agente L2 en n8n que realmente resuelve incidencias

    Problema: un bot en Slack contesta “reinicia” porque carece del estado real del sistema.

    Enfoque ingenuo

    Enviar error text y prompt extenso. Respuestas genéricas.

    Enfoque Context Engineering

    Antes de llamar al LLM, el workflow hace:

    • Query a Datadog/Grafana para obtener los últimos N logs (filtrados por servicio y correlación)
    • Query SQL read-only para validar estado de cuenta/recursos del usuario
    • Búsqueda semántica en documentación interna y re-ranking para extraer la resolución exacta

    El LLM recibe un JSON estructurado con logs, estado y docs. No adivina; redacta una intervención operativa reproducible. En n8n esto se modela como nodos previos que transforman y sanitizan el contexto.

    Guía práctica: checklist para construir pipelines de contexto

    • Define señal mínima: ¿qué datos hacen que la respuesta deje de ser una suposición?
    • Implementa chunking por semántica, no por longitud.
    • Usa RAG híbrido: vector search + BM25 + metadatos.
    • Añade re-ranking con Cross-Encoders para ordenar resultados.
    • Instrumenta: guarda el contexto inyectado (hashes), tokens consumidos y scores.
    • Limita permisos y sanitiza PII antes de inyectar datos sensibles.
    • Versiona specs y pipelines; trátalos como código crítico.

    Riesgos y consideraciones operativas

    • Costo de tokens y latencia: curar contexto reduce tokens inútiles, pero re-ranking y cross-encoders añaden coste computacional.
    • Seguridad y privacidad: nunca inyectes credenciales ni expongas PII sin enmascaramiento. Diseña roles y auditable human-in-the-loop para acciones críticas.
    • Overfitting de contexto: si tu re-ranker prioriza siempre el mismo fragmento, podrías ignorar cambios recientes. Mantén ventanas temporales y freshness rules.

    Conclusión técnica

    Context Engineering no es un nicety; es la capa que convierte IA probabilística en un componente reproducible de tu stack. Los equipos que ganan no son los que escriben mejores prompts; son los que construyen pipelines que entregan al modelo exactamente la señal que necesita, en el formato correcto y con trazabilidad. Eso es lo que separa a quien usa IA de quien la domina.

    Para equipos que trabajan con automatización, agentes, n8n o workflows, explorar prácticas y experimentos adicionales puede acelerar la adopción segura y reproducible. Más recursos y pruebas de concepto están disponibles en Dominicode Labs.

    Tabla de contenidos

    FAQ

    ¿Qué diferencia a prompt engineering de context engineering?

    Prompt engineering diseña la instrucción y el formato de la interacción. Context engineering construye la infraestructura y pipelines que entregan al modelo la información relevante, limpia y ordenada para que esa instrucción produzca resultados reproducibles.

    ¿Cuándo debo priorizar construir pipelines de contexto?

    Cuando las respuestas del modelo necesitan ser verificables, reproducibles o accionables en producción—por ejemplo, cambios de código a gran escala, acciones operativas automatizadas o workflows de soporte.

    ¿Qué es chunking semántico y por qué es importante?

    Es dividir el contenido por límites lógicos (funciones, clases, secciones) en lugar de por caracteres. Reduce ambigüedad y mejora la relevancia de la información entregada al modelo.

    ¿Cómo se integra RAG híbrido en un flujo de trabajo existente?

    Combina búsqueda vectorial para semántica con BM25 para coincidencias léxicas y aplica filtros por metadatos. Recupera amplio, luego re-ranquea con Cross-Encoders para entregar la mejor señal al LLM.

    ¿Qué métricas debo instrumentar para auditar el contexto?

    Guarda hashes del contexto inyectado, tokens consumidos por llamada, scores de recuperación y re-ranking, y un registro de versiones de specs y pipelines.

    ¿Cómo mitigo riesgos de privacidad al inyectar contexto?

    Sanitiza y enmascara PII, limita permisos para queries y usa pipelines read-only para datos sensibles. Diseña revisiones humanas para acciones críticas.

    Tiempo estimado de lectura: 5 min

  • Cómo validar una idea de producto digital en 7 días usando IA

    Cómo validar una idea de producto digital en 7 días usando IA

    Cómo validé una idea de producto digital en 7 días usando IA

    Tiempo estimado de lectura: 5 min

    • Ideas clave:
    • Valida el problema antes de construir la solución: busca señales de intención (registros, uso completo, preguntas por precio).
    • Usa un stack mínimo combinado con orquestación sin código para simular un backend y obtener un producto funcional en horas.
    • Mide intención, no visitas; prioriza iteración rápida sobre infraestructura escalable.

    ¿Se puede pasar de idea a señal de mercado en una semana? Sí. Yo lo hice. Aquí cuento el flujo técnico exacto: herramientas, decisiones y métricas que importan. Sin humo. Sin construir más de lo necesario. La frase clave: cómo validé una idea de producto digital en 7 días usando IA. La repetiré porque importa: no es un truco de marketing, es un proceso reproducible.

    Resumen rápido (lectores con prisa)

    Workflow reproducible para validar demanda en 7 días: investiga el problema (días 1–2), lanza una landing mínima con captura (días 3–4), simula backend con n8n + LLMs (día 5), outreach hipersegmentado y lectura de señales (días 6–7). Mide intención —emails, flujo completo, preguntas por precio— y decide refactorizar solo si hay señales claras.

    Cómo validé una idea de producto digital en 7 días usando IA — resumen operativo

    Objetivo: obtener usuarios reales interactuando con la propuesta y señales de intención (registro, uso completo del flujo, preguntas sobre precio) antes de escribir un backend serio.

    Stack mínimo probado

    Si no conoces alguna de estas piezas, es ok. No necesitas dominarlas todas; sí necesitas entender por qué las encajas.

    Día 1–2: validar el problema, no la solución

    • No escribas código. Haz investigación dirigida.
    • Extrae reseñas negativas de competidores en G2/Capterra. Pide a Perplexity y a Claude que resuman temas recurrentes.
    • Resultado concreto: 1 frase que diga quién sufre, 1 frase que diga por qué le duele, 1 promesa de valor clara y verificable.

    Ejemplo de salida: “CTOs en startups de datos pierden 2–3 días por informe manual X. Si aceptan un análisis automático con output listo para presentar, reducirán ese tiempo y pagarán por ello.” Esa es la hipótesis que vas a probar.

    Día 3–4: landing mínima y captura de intención

    • Crea una landing con Next.js. Título claro, 3 bullets de valor, formulario de captura o botón de pago (Stripe Checkout).
    • Usa asistentes de código para acelerar componentes y estilos.
    • Despliega en Vercel en horas.

    Regla de oro: mide intención, no visitas. Los KPIs iniciales son:

    • % de visitantes que dejan email.
    • % que hacen click en el flujo (o en el botón de pago).
    • Tiempo medio en la página para usuarios técnicos.

    Día 5: Mago de Oz con n8n + LLMs (backend simulado)

    No construyas la API real. Orquesta un workflow en n8n que actúe como backend:

    1. Next.js envía un webhook a n8n.
    2. n8n llama a la API de OpenAI (o Claude) para procesar la petición.
    3. n8n formatea la respuesta y la envía por email o devuelve un webhook al frontend.

    Esto te da un “producto” funcional en horas. Ventaja: iteras la lógica del producto ajustando prompts y el workflow, no código. Limitación obvia: no escala, pero sirve para validar comportamiento humano y precio.

    Día 6–7: outreach y lectura de señales reales

    • Outreach hipersegmentado: mensajes en LinkedIn y X dirigidos a perfiles concretos (CTOs, Tech Leads). Usa IA para personalizar mensajes, no para crear spam.
    • Envía el enlace de la landing. Invita a probar, no a comprar.
    • Prioriza conversaciones cualitativas: quién pregunta por precio, quién propone usarlo en su equipo, quién pide demo.

    Las señales que importan:

    • Conversiones (captura de email → ejecución completa del workflow).
    • Conversaciones que mencionan precio o tiempo de compra.
    • Repetición: usuarios que vuelven a ejecutar el flujo.

    Si consigues las tres, la hipótesis merece inversión.

    Qué puede y qué no puede la IA en esta validación

    La IA acelera la construcción del experimento: genera frontend, ayuda a sintetizar investigación, y actúa como motor lógico dentro de n8n. Pero no sustituye la prueba de mercado real.

    Errores comunes:

    • Preguntar a ChatGPT si la idea es buena (te confirmará por defecto).
    • Medir visitas en vez de intención accionable.
    • Sobrediseñar la infraestructura antes de validar demanda.

    Decisión técnica: cuándo refactorizar y cuándo tirar todo

    Refactoriza cuando:

    • Tienes >5 usuarios pagantes o >20 usuarios activos semanales.
    • El producto requiere latencia, seguridad o integraciones que n8n no puede manejar.

    Desecha o pivota cuando:

    • Conversiones <2% tras 1–2 campañas de outreach y mejoras en copy.
    • Ninguna conversación menciona precio o uso real.

    Conclusión

    Cómo validé una idea de producto digital en 7 días usando IA no es un truco; es disciplina. Menos código, más señales. Usa Next.js + n8n + LLMs para convertir incertidumbre en datos accionables. Si funciona, refactoriza con criterio. Si no, ahorraste semanas o meses de trabajo inútil.

    Para quienes iteran en pipelines de validación y workflows basados en IA, esta metodología conecta bien con recursos de experimentación técnica; ver una continuación práctica en Dominicode Labs.

    FAQ

    ¿Por qué no construir el backend desde el inicio?

    Porque la prioridad es validar demanda y comportamiento de usuario. Construir backend consume tiempo y crea fricción que puede ocultar la verdadera señal de mercado.

    ¿Cómo mido intención en lugar de visitas?

    Mide acciones concretas: captura de email, click en flujo o botón de pago, ejecución completa del workflow y conversaciones que mencionan precio o uso real.

    ¿Qué métricas concretas debo rastrear la primera semana?

    Porcentaje de visitantes que dejan email, porcentaje que inician/terminan el flujo, tiempo medio en la página para usuarios técnicos y número de conversaciones cualitativas que mencionan precio o implementación.

    ¿Cuándo es apropiado usar n8n en producción?

    n8n es útil para prototipos y MVPs de bajo volumen. Refactoriza hacia infraestructuras más controladas cuando necesites latencia garantizada, requisitos de seguridad o integraciones a escala.

    ¿Qué herramientas de IA recomendarías para investigación rápida?

    Herramientas citadas en el artículo: Perplexity para investigación dirigida y LLMs como OpenAI API o Claude para síntesis y generación de prompts.

    ¿Qué hacer si no obtengo señales en 7 días?

    Itera el copy y la segmentación, realiza 1–2 campañas adicionales de outreach segmentado y reevalúa la hipótesis. Si las conversiones siguen <2% y no hay conversación sobre precio, considera pivotar o desechar la idea.

  • Errores comunes al adoptar Claude Code en equipos de desarrollo

    Errores comunes al adoptar Claude Code en equipos de desarrollo

    Errores comunes al adoptar Claude Code en un equipo

    Tiempo estimado de lectura: 4 min

    • Onboarding: enseñar la herramienta no es suficiente; hay que enseñar el paradigma de agentes autónomos.
    • Spec-First: ejecutar cambios sin especificaciones claras genera deuda y decisiones inventadas por el agente.
    • Costes y contexto: control de iteraciones, reglas permissions.deny y límites para evitar facturas y pérdida de foco.
    • Guardrails operativos: PR gating, auditoría y human-in-the-loop previenen cambios destructivos.

    Los primeros días de uso no muestran los verdaderos errores comunes al adoptar Claude Code en un equipo. Aparecen cuando el agente empieza a operar a escala: facturas inesperadas, PRs que compilan pero rompen la arquitectura, y bucles que consumen tokens hasta que alguien corta la ejecución. Si vas a introducir Claude Code en tu flujo, entiende esto desde la primera semana.

    Claude Code no es un autocompletador: es un agente de terminal. Lee archivos, ejecuta comandos y modifica el repositorio. Esa autonomía multiplica la productividad—y los riesgos—si no impones disciplina.

    Resumen rápido (lectores con prisa)

    Claude Code es un agente autónomo que puede leer, ejecutar y modificar un repositorio. Úsalo cuando tengas specs claros y boundaries operativos. Controla contexto y costes; automatiza tareas repetitivas, pero requiere revisión humana para cambios de arquitectura y acciones destructivas.

    Errores comunes al adoptar Claude Code en un equipo: lecciones aprendidas

    1) Onboarding enfocado en la herramienta y no en el paradigma

    Error: enseñar “cómo instalar la CLI” y asumir que el equipo sabe usar un agente autónomo. Resultado: uso ineficiente o delegación total.

    Solución práctica:

    • Onboarder por paradigma: sesiones que enseñen “qué preguntar”, “qué no delegar” y cómo interpretar salidas de la IA.
    • Política obligatoria: cualquier PR generado por Claude pasa por revisión humana con checklist (seguridad, tests, dependencias).
    • Define tareas delegables: por ejemplo, generación de tests unitarios a partir de interfaces, refactorizaciones pequeñas bajo spec, o scaffolding de componentes que ya respetan convenciones.

    Referencia útil: documentación de Claude Code en Anthropic

    2) Lanzar prompts sin specs (Spec-First)

    Error: pedir “implementa autenticación” en la raíz del repo. El agente inventa ORM, mezcla infra y dominio, y produce deuda.

    Solución práctica:

    • Escribe specs antes de ejecutar la CLI: feature-auth.md que incluya interfaces TypeScript, endpoints, casos de error, y tests esperados.
    • Invocación por referencia: claude "Implementa lo descrito en feature-auth.md; respeta interfaces y pruebas".
    • Mantén un CONVENTIONS.md o .claude/instructions.md con reglas de estilo, librerías permitidas y antipatrones a evitar.

    Esto convierte al agente en un ejecutor de decisiones, no en un arquitecto improvisado.

    3) Ignorar costos y permitir bucles infinitos

    Error: ejecutar Claude en la raíz de un monorepo o dejar que itere tests sin límite. Token-cost + ejecuciones = facturas altas y uso indiscriminado.

    Solución práctica:

    • Abre Claude Code en la carpeta del paquete en el que trabajas, no en la raíz del monorepo.
    • Claude Code no tiene .claudeignore. Para que no lea carpetas pesadas o sensibles, usa reglas deny en .claude/settings.json. Ejemplo:
    {
  "permissions": {
    "deny": [
      "Read(./dist/**)",
      "Read(./logs/**)",
      "Read(./*.sqlite)",
      "Read(./.env)"
    ]
  }
}
    • Imponer límites en el prompt: "Si los tests no pasan después de 3 intentos, detén la ejecución y reporta errores con stack traces".
    • Monitorización y alertas: trackea consumo de tokens y costes con dashboards; define budgets por equipo y bloquea continuaciones si se supera el umbral.

    4) Saturar la ventana de contexto (Lost in the Middle)

    Error: dar al agente el repo entero para “entender el proyecto”. El modelo pierde foco—más contexto = peor señal en el medio. Documentado en Lost in the Middle.

    Solución práctica:

    • Contexto quirúrgico: navega al directorio relevante antes de invocar la CLI. Alimenta al agente con fragmentos semánticos (interfaces, esquema DB, tests relacionados), no con 50 controladores.
    • Usa grafos de dependencia o resúmenes (README de módulo, esquema ER, list of public APIs) para que el agente comprenda impacto sin leer todo el código.
    • Divide tareas grandes en sesiones pequeñas y contractuales con outputs claros entre ellas.

    Controles operativos y guardrails que funcionan

    • PR gating: cualquier cambio propuesto por Claude debe pasar por pipeline CI que incluya lint, tests y políticas SCA (software composition analysis).
    • Auditoría: almacenar hashes del contexto inyectado y logs de comandos ejecutados para auditoría forense.
    • Human-in-the-loop para acciones destructivas: merges automáticos solo si cambios son triviales (docs, comentarios). Para código, siempre revisión humana.
    • Backstop de seguridad: sanitiza PII antes de permitir lectura por el agente.

    Conclusión breve y accionable

    Claude Code acelera trabajos repetitivos y eleva la productividad, pero no sustituye la disciplina de ingeniería. La herramienta amplifica lo que ya existe: si tu arquitectura es modular y tienes specs y tests, el agente te hará avanzar más rápido. Si tu repo es un monolito sin reglas, el agente producirá deuda técnica en modo turbo.

    Implementa Spec-First, controla el contexto que das, limita iteraciones y monitoriza costes. Si sigues esos principios, convertirás a Claude Code en un multiplicador de valor en vez de un generador de problemas.

    Para equipos que diseñan workflows y guardrails para agentes, recursos prácticos y experimentos están disponibles en Dominicode Labs. Estos materiales complementan políticas de PR gating, auditoría y límites de coste descritos arriba, sirviendo como punto de partida para pruebas internas.

    FAQ

    ¿Por qué no basta enseñar la CLI para integrar Claude Code?

    Enseñar la CLI cubre cómo ejecutar la herramienta, pero no enseña el paradigma de agentes autónomos: qué delegar, cómo formular prompts seguros y cómo interpretar acciones que modifican el repo. Sin ese contexto, el equipo tiende a delegar decisiones arquitectónicas a la IA o a usarla de forma ineficiente.

    ¿Qué significa Spec-First y cómo se aplica?

    Spec-First es la práctica de definir interfaces, endpoints, casos de error y tests antes de ejecutar el agente. Se aplica mediante documentos como feature-auth.md y convención de invocación que referencia ese spec; así el agente ejecuta decisiones ya tomadas, no inventa arquitectura.

    ¿Cómo evito facturas inesperadas por bucles del agente?

    Impone límites en el prompt (por ejemplo, máximo 3 intentos de test), usa reglas permissions.deny para que no lea carpetas pesadas y monitoriza consumo de tokens con dashboards y budgets por equipo. Bloquea continuaciones automáticas si se supera el umbral.

    ¿Existe .claudeignore en Claude Code?

    No. Claude Code no lee ningún archivo .claudeignore, así que crearlo no protege nada. Para impedir que lea carpetas pesadas o sensibles (dist, logs, .env), usa reglas deny como Read(./dist/**) en .claude/settings.json.

    ¿Cómo limitar el contexto que le doy a Claude Code?

    Proporciona contexto quirúrgico: archivos relevantes (interfaces, esquema DB, tests relacionados), resúmenes de módulo y grafos de dependencia. Divide tareas grandes en sesiones pequeñas para evitar que el agente lea un monolito entero.

    ¿Cuándo debe intervenir un humano en el flujo de trabajo?

    Siempre que el cambio afecte arquitectura, dependencias críticas, seguridad o datos sensibles, debe haber revisión humana. Merges automáticos pueden permitirse solo para cambios triviales como documentación o comentarios.

  • Cómo mejorar la gobernanza del código en proyectos con IA

    Cómo mejorar la gobernanza del código en proyectos con IA

    ¿Te das cuenta de lo que está pasando cuando la IA escribe más código del que puedes leer?

    Tiempo estimado de lectura: 6 min

    • La velocidad de generación de código por IA aumenta la deuda técnica si no hay gobernanza explícita.
    • Spec, tests y código forman un bucle de retroalimentación que debe mantenerse sincronizado.
    • Capturar la intención (traces, decisiones) es crítico para trazabilidad y responsabilidad.
    • Herramientas como Plum actúan como “plomada” para reconciliar intención, spec y tests.

    Introducción

    No es una exageración. Es la nueva crisis del software. Otra vez. Solo que ahora la fábrica es un LLM y la producción no para.

    This is her code. This is what she was managing. This is her VS code. Eso era Margaret Hamilton sujetando la complejidad con una plomada humana. Hoy esa plomada se perdió en un mar de commits y prompts.

    Vamos al grano: la IA te da velocidad. No te da contexto ni responsabilidad. Y velocidad sin control es deuda técnica que crece sin pedir permiso.

    1 línea: si no sincronizas spec, tests y código, la IA no te salva. Te hunde más rápido.

    Por qué la vieja receta falla

    • La industria ya tropezó con esto en los 60 y 70. Entonces el problema eran máquinas que permitían programas inmensos. Hoy el problema es que los modelos permiten escribir esos programas a ritmo industrial.
    • Waterfall nació como orden. Agile llegó como contramedida. CI/CD vino a resolver la paranoia. Ahora la IA devuelve el caos a velocidad Agile.
    • Resultado: waterfall x volumen a la cadencia de Agile. Y nadie puede revisarlo todo.

    ¿La lección? No es un problema técnico nuevo. Es el mismo problema con otro disfraz: la incapacidad humana para gobernar la complejidad.

    El triángulo que nadie respeta

    Imagina un triángulo. Tres vértices: Spec, Tests, Código.

    • Spec = contrato. El porqué.
    • Tests = garantías. El qué.
    • Código = ejecución. El cómo.

    Antes actuábamos como si fuera una ecuación: Spec + Tests + Agente = Código. Falso. Eso es una línea recta donde la realidad acaba por doblarte.

    La verdad: es un feedback loop. Código modifica spec. Código revela tests faltantes. Tests exponen specs rotas. Y si no cierras ese bucle, cada commit es una pequeña traición al diseño original.

    Regla: si tocas el código, el spec y los tests deben moverse contigo. Si no, estás plantando bombas de tiempo.

    Hamilton’s law (versión para hoy)

    Cuando no puedes ver sobre tu código, no puedes supervisarlo.

    Padre orgulloso inventa ley. Útil. Si no puedes leer tu repo entero en una revisión razonable, no puedes asumir la responsabilidad de lo que contiene. Punto.

    Agentes, decisiones y chats

    Los agentes generan decisiones. Esas decisiones viven en chats.

    • Un agente escribe una función.
    • Tú validas rápido.
    • Commit.
    • ¿Dónde quedó la decisión sobre “por qué” se implementó así?

    En chats. En traces. En el aire.

    Eso es la falla: la intención desaparece. El código queda, la intención no. Y meses después, nadie recuerda por qué se hizo X. Sí, tú pensarás “lo vi en el chat”. Lo crees hasta que el repo explota.

    Plum: la plomada digital

    Plum no genera código. Hace otra cosa menos sexy y mucho más necesaria: captura intención.

    ¿Idea? Cada vez que comprometes cambios:

    1. Plum mira el diff.
    2. Plum revisa los traces del agente (conversaciones, prompts, respuestas).
    3. Extrae decisiones —qué se decidió y por qué— y las dedupea.
    4. Te las presenta: “Estas son las decisiones. ¿Las apruebas?”
    5. Si sí, actualiza el spec (Markdown) y genera un registro inmenso en JSONL.
    6. Ejecuta un sync y te muestra las brechas entre spec, tests y código.

    Es la plomada que te dice si estás recto.

    Por qué eso importa: intención como artefacto

    • Commit messages son basura para auditar intención.
    • PRs son discusiones, no contratos.
    • El archivo .jsonl que genera Plum es una línea de tiempo de decisiones: pregunta, respuesta, autor (humano o LLM), rama y timestamps.

    Es trazabilidad con “blame” real. No “quién hizo el commit”, sino “quién decidió y por qué”.

    No es mágico. Es gobernanza.

    • Plum hoy está atado a pytest para cobertura. Sí, limitación.
    • Funciona mejor si la spec está delante del código. Backfilling grande es doloroso.
    • No reemplaza la validación humana. La aprobación es obligatoria.

    Open source y la ilusión del milagro colectivo

    Hay una tentación: “Si lo estructuro perfecto, cualquiera podrá contribuir y la IA hará el resto”. Suena bonito.

    La verdad: incluso en proyectos con specs decentes y tests que pasan, los PRs discuten implementaciones por 20 comentarios. Un test verde no significa que la solución sea correcta o mantenible.

    Implementar el código mejora el spec. Siempre. Esa es la bendita contradicción: la única forma de refinar la especificación es ensuciándote con la implementación.

    Cómo deberían trabajar los equipos que usan agentes

    Si adoptas agentes sin cambiar proceso, vas a crear un legado ilegible. ¿Quieres hacerlo bien? Empieza por esto:

    1. Spec antes que código
      • Especificaciones en Markdown en el repo.
      • Incluye ejemplos, invariantes y casos límite.
      • Hazlas contractibles: comportamientos verificables, no promesas.
    2. Tests que describan intención
      • Tests no solo para pasar; tests que documenten el contrato.
      • Integración y properties (property tests) para invariantes sistémicos.
    3. Captura de traces como estándar
      • Logs estructurados de conversaciones con agentes.
      • Relaciona cada trace a un commit o PR.
    4. Herramienta de reconciliación
      • Plum u otra: extrae decisiones, pide aprobación, actualiza spec.
      • Registro en JSONL: fuente de verdad para auditorías.
    5. Pipeline de bloqueo
      • Si spec↔tests↔código no están en sync, bloqueo del merge.
      • Preferible a permitir que la deuda técnica se vaya multiplicando.
    6. Modularity or die
      • Si un agente necesita entender 50 archivos para cambiar un feature, rehace la arquitectura.
      • Componentes pequeños, contratos claros, dependencia explícita.

    El rol del Tech Lead ahora

    • Olvídate del dev que “código, push, listo”. Tu rol debe mutar.
    • Menos escribir, más editar.
    • Menos features, más criterios de aceptación inquebrantables.
    • Más auditoría de decisiones y menos aprobación de slips superficiales.
    • Ser la defensora/defensor de la intención del producto.

    No confíes únicamente en LLMs para refactorizar la spec

    Los LLMs ayudan a detectar incoherencias locales. Muy bien. Pero carecen de visión de largo plazo del negocio. No delegues la validación del contrato a una IA. Debe haber alguien con criterio humano que apruebe la intención.

    Checklist mínimo para empezar hoy

    • Specs en repo. (Sí, en Markdown y versionadas).
    • Tests automatizados en CI. (Sí, pytest al menos para Plum).
    • Traces guardados. (JSON logs o similar).
    • Plum instalado en la máquina de desarrollo y en el CI.
    • Política de aprobación humana para decisiones extraídas.
    • Sync obligatorio en cada PR.

    Si no puedes hacer todo esto ahora: empieza por uno. Empieza por capturar traces. Eso cambiará cómo miras los PRs.

    Metáfora final (porque me encantan)

    Piensa en tu repo como un edificio. La IA es una flota de obreros hiperactivos que pueden añadir habitaciones a ritmo industrial. Sin planos actualizados y sin quien firme los cambios, terminarás con una casa que se cae por el techo.

    Plum es la plomada. Te dice si las paredes están verticales. No construye. No pinta. Sólo te evita derrumbes.

    Urgencia práctica

    Si tu equipo ya usa agentes y no tiene un proceso de reconciliación, estás acelerando la creación de un legado que nadie entenderá. Hoy es el día para dejar de creer que la velocidad soluciona cosas.

    Haz esto ahora:

    • pip install plum-dev
    • cd a un repo con spec en Markdown y tests con pytest
    • plum init
    • plum sync en una rama de feature

    No es glamour. Es gobernanza. Es aburrido. Y exactamente lo que separa a equipos que escalan de equipos que pagan deuda técnica por décadas.

    ¿Quieres que te pase un template de JSONL para registrar decisiones y un flujo de PR que puedas copiar en tu repo? Responde este mensaje y te lo mando. Porque esto no acaba aquí.

    Dominicode Labs

    Si buscas recursos y experimentos sobre procesos con agentes, automatización y gobernanza técnica, puedes revisar Dominicode Labs. Es una continuación lógica para explorar patrones de concilación entre spec, tests y código en entornos con IA.

    FAQ

    ¿Qué problema principal resuelve Plum?

    Plum captura intención desde los traces del agente, extrae decisiones (qué y por qué), las deduplica, las presenta para aprobación y sincroniza spec, tests y código, además de generar un registro en JSONL para auditoría.

    ¿Por qué son insuficientes los commit messages y los PRs?

    Commit messages y PRs documentan acciones o discuten implementaciones, pero no son un artefacto estructurado de intención. No facilitan una trazabilidad clara de decisiones con autoría y motivo.

    ¿Qué debo capturar en los traces?

    Traces estructurados de conversaciones con agentes: prompts, respuestas relevantes, quién participó y contexto mínimo que relacione la decisión con un diff o commit.

    ¿Cómo se integra Plum con pytest?

    Plum usa pytest para medir cobertura y correlacionar tests con cambios. Hoy esa integración es una limitación conocida: requiere tests y spec alineados para funcionar bien.

    ¿Qué acciones bloquea el pipeline propuesto?

    El pipeline bloquea merges cuando existe desalineación entre spec, tests y código. La idea es prevenir que la deuda técnica crezca sin control.

    ¿Qué sigue si no puedo implementar todo el checklist ahora?

    Empieza por uno: captura traces. Es la intervención más rápida y con mayor impacto para mejorar revisiones y trazabilidad.

    ¿Quién debe aprobar las decisiones extraídas?

    La aprobación final debe ser humana. Plum extrae y propone, pero la validación del contrato y la intención corresponde a un responsable con criterio del equipo.

  • Agentic Coding: Automatizando el Ciclo de Desarrollo con IA

    Agentic Coding: Automatizando el Ciclo de Desarrollo con IA

    Qué es el Agentic coding?

    Tiempo estimado de lectura: 4 min

    Ideas clave

    • Agentic coding es un paradigma donde un agente de IA recibe un objetivo de alto nivel y ejecuta el ciclo completo de implementación.
    • Combina planificación, uso de herramientas y un bucle de retroalimentación que incluye tests y correcciones iterativas.
    • Funciona bien para scaffolding, pruebas y tareas repetitivas; requiere documentación, TDD y revisión humana para evitar riesgos.

     

    Qué es el Agentic coding? Es el paradigma en el que un agente de IA recibe un objetivo de alto nivel y ejecuta el ciclo completo de implementación: planifica subtareas, escribe y modifica archivos, ejecuta tests y se autocorrige hasta cumplir el criterio de éxito. No es autocompletar: es automatizar el flujo de trabajo de desarrollo con bucles de razonamiento y acción.

    Resumen rápido (lectores con prisa)

    Agentic coding transforma LLMs en agentes que planifican, usan herramientas (editar archivos, ejecutar comandos, llamar APIs) y se corrigen mediante un bucle de feedback con tests. Es útil para scaffolding, pruebas y tareas repetitivas, pero requiere documentación, TDD y revisión humana por riesgos de seguridad, coherencia y alucinaciones.

    Qué es el Agentic coding? — definición y componentes técnicos

    Técnicamente, un sistema agéntico combina tres capacidades:

    • Planificación: el modelo descompone una tarea compleja en pasos ejecutables antes de tocar código.
    • Uso de herramientas (tool use): el agente puede leer/editar archivos, ejecutar comandos en la terminal, abrir el navegador o llamar APIs externas.
    • Bucle de retroalimentación (feedback loop): ejecuta tests o builds, analiza fallos (stack traces) y corrige el código iterativamente.

    Esa combinación transforma al LLM de generador de texto en un motor de ejecución: piensa, actúa, verifica, corrige. Ejemplo real: pedir “añade rate limiting al endpoint /api/auth y crea tests unitarios” y recibir, tras múltiples ejecuciones, un PR con código que pasa el pipeline de CI (o al menos repite intentos hasta que los tests locales pasan).

    Herramientas y ecosistema (URLs)

    Las herramientas que ya incorporan capacidades agénticas o facilitan su adopción son relevantes para entender el estado práctico del Agentic coding:

    Estas herramientas muestran dos enfoques: editores/CLI que actúan dentro del flujo de desarrollo, y orquestadores que integran agentes en pipelines y automatizaciones.

    Limitaciones prácticas y riesgos técnicos

    El Agentic coding funciona, pero con condiciones. No es una panacea.

    1. Context window y coherencia arquitectónica

    Los agentes pierden visión global en repositorios grandes. La ventana de contexto de los LLMs mejora, pero no sustituye el conocimiento arquitectónico humano. Técnicas como RAG (retrieval-augmented generation) ayudan a indexar documentación, pero no garantizan decisiones coherentes a nivel sistema.

    2. Seguridad y dependencias

    Un agente optimiza la entrega de la tarea, no la seguridad. Puede introducir dependencias vulnerables o atajos que rompen principios de Clean Architecture. La revisión humana sigue siendo obligatoria antes del merge.

    3. Alucinaciones técnicas

    Los modelos pueden generar llamadas a APIs inexistentes o usar firmas obsoletas. Sin ejecución automática de tests y análisis estático, esas alucinaciones pasan desapercibidas.

    4. Escalabilidad y mantenimiento

    Generar cambios rápidos aumenta la deuda técnica si no se adoptan reglas de estilo, ADRs o documentación que orienten al agente.

    Buenas prácticas para adoptar Agentic coding

    Si vas a integrar agentes en tu flujo, aplica estas reglas mínimas:

    • Documenta el contexto: RULES.md, guías de estilo y ADRs reducen ambigüedad y guían las decisiones del agente.
    • Adopta TDD como protocolo de interacción: escribir tests primero ofrece un criterio de éxito claro para el agente y reduce la supervisión humana.
    • Modula y desacopla: los agentes funcionan mejor en componentes pequeños; refactoriza monolitos antes de delegar tareas significativas.
    • Pipelines de CI como árbitro: ejecuta builds y análisis estático automáticamente en cada PR generado por un agente.
    • Revisión humana con checklist: seguridad, licencias de dependencias y arquitectura deben validarse manualmente antes del merge.

    Cuándo usar y cuándo no usar agentes

    Usa agentes para:

    • Scaffolding y generación de pruebas.
    • Refactorizaciones locales y tareas repetitivas.
    • Automatizar revisiones preliminares de PRs o generar PRs iniciales para revisión humana.

    Evítalos en:

    • Decisiones arquitectónicas críticas.
    • Código con requisitos regulatorios o de seguridad estrictos.
    • Repositorios legacy masivos sin documentación ni tests.

    Conclusión

    Qué es el Agentic coding? Es la evolución de la IA desde asistente pasivo a actor autónomo en el ciclo de desarrollo. Ofrece un multiplicador de productividad si se integra con disciplina: documentación explícita, tests como contrato de aceptación, CI robusto y revisión humana en los puntos críticos. Mal usado acelera la deuda técnica; bien usado multiplica la capacidad del equipo.

    Si exploras integración de agentes, pipelines y automatización en equipos de ingeniería, puede resultar útil revisar recursos y experimentos prácticos. Una continuación lógica para equipos interesados en estos temas es Dominicode Labs, que agrupa proyectos y guías sobre automatización e IA aplicada en flujos de desarrollo.

     

    FAQ

     

    ¿Qué distingue al Agentic coding de un asistente de autocompletar?

    Agentic coding implica que el agente planifique, ejecute cambios en archivos, ejecute tests y se autocorrija mediante bucles de feedback. Un autocompletador solo sugiere fragmentos de texto o código sin ejecutar ni verificar el resultado.

    ¿Qué componentes técnicos hacen falta para un agente agéntico?

    Planificación de tareas, capacidad de usar herramientas (editar archivos, ejecutar comandos, llamar APIs) y un bucle de retroalimentación con tests o builds son los componentes esenciales.

    ¿Cuáles son los riesgos principales al usar agentes?

    Riesgos clave: pérdida de coherencia arquitectónica en repositorios grandes, introducción de dependencias inseguras, alucinaciones técnicas y aumento de deuda si no hay reglas y documentación.

    ¿Cómo debo preparar un repo antes de delegar a un agente?

    Documenta contexto y reglas (RULES.md, ADRs), añade tests y adopta TDD, modula componentes y habilita pipelines de CI para validar PRs generados por agentes.

    ¿Qué herramientas son relevantes hoy para Agentic coding?

    Herramientas representativas incluyen Cursor — editor con modo Composer, Aider, Cognition.ai, OpenHands, n8n, OpenAI (APIs de LLM) y Anthropic (Claude).

    ¿Los agentes pueden reemplazar la revisión humana?

    No. La revisión humana sigue siendo obligatoria para validar seguridad, licencias y decisiones arquitectónicas críticas antes del merge.

    ¿Qué prácticas reducen alucinaciones técnicas?

    Practicas que ayudan: adoptar TDD, ejecutar tests y análisis estático en CI automáticamente, usar RAG para documentar contexto y contar con reglas y ADRs que guíen al agente.

  • Implementando IA Generativa con Claude Code en la Terminal

    Implementando IA Generativa con Claude Code en la Terminal

    IA generativo con Claude Code: programación agéntica en la terminal

    “Tiempo estimado de lectura: 4 min”

    • Claude Code lleva modelos de razonamiento y acción al flujo CLI: inspecciona repos, ejecuta tests y realiza commits.
    • Es potente para refactorizaciones a gran escala, debugging iterativo y automatización de commits/PRs, pero peligroso en repos sin tests o infra crítica.
    • Requiere entornos aislados, confirmaciones humanas para cambios sensibles y límites de consumo de tokens.

    Poca gente lo dice en voz alta: esto no es un plugin más. Hacer IA generativo con Claude Code cambia quién escribe código y quién aprueba los cambios. El agente vive en la terminal, lee tu repo, ejecuta tests y puede hacer commits. No te sugiere; actúa.

    Resumen rápido (lectores con prisa)

    Claude Code es un agente CLI que opera sobre tu repo: indexa código, planea cambios, ejecuta tests y aplica parches. Úsalo para refactorizaciones, debugging iterativo y automatización de PRs —pero solo en entornos aislados con buena cobertura de tests. Es una capa operativa para pipelines CLI y se integra con flujos de CI/CD y herramientas como n8n.

    ¿Qué es IA generativo con Claude Code y cómo funciona?

    IA generativo con Claude Code significa llevar el modelo Claude al flujo de trabajo CLI. En lugar de pedir snippets en una ventana de chat, le pides al agente que opere sobre tu código: inspeccione archivos, ejecute npm test o pytest, lea el stack trace y vuelva a intentar hasta que los tests pasen o se quede sin opciones.

    Arquitectura mínima del flujo

    • Percepción: indexa la base de código, deps y el historial de Git.
    • Razonamiento: traza un plan de cambios (planificando antes de editar).
    • Acción: modifica archivos, corre builds y tests.
    • Iteración: revisa errores, corrige y repite.

    Anthropic documenta Claude Code como una interfaz para operar Claude desde la terminal (Anthropic – Claude Code). El modelo base en estas capacidades es Claude 3.7 Sonnet, pensado para razonamiento extendido y ciclos iterativos.

    ¿Dónde aporta valor real —y dónde no?

    Dónde aporta

    • Refactorizaciones a gran escala: cambiar patrones en cientos de archivos, mantener imports y tests coherentes.
    • Debugging iterativo: ejecutar el código, capturar logs, proponer y aplicar parches.
    • Automatización de commits y PRs: descripciones técnicas generadas a partir de los cambios reales, no de lo que tú crees haber cambiado.
    • Integración en pipelines y flujos n8n: ideal cuando quieres validar artefactos en CI sin intervención manual.

    Dónde falla o es peligroso

    • Bases de código legacy sin tests: el agente puede producir código que compila pero rompe reglas de negocio.
    • Sistemas con secretos o infraestructura crítica: permitir ejecuciones en máquinas no aisladas es un riesgo real.
    • Presupuesto: cada lectura de archivos y cada iteración consume tokens de API. Un loop largo se nota en la factura.

    Si tu repo tiene buena cobertura de tests y puedes aislar el entorno (Docker), la relación riesgo/recompensa inclina hacia el sí.

    Claude Code vs Copilot vs Cursor: una decisión técnica

    No hablo de marcas por postureo. Comparo por arquitectura:

    • GitHub Copilot: autocompletado en el editor. Útil para micro-productividad.
    • Cursor / Windsurf: IA integrada en IDE; buena experiencia GUI.
    • Claude Code: agente autónomo en CLI; pensado para acciones completas sobre el repo.

    El criterio no es “me gusta más”. Es: ¿quieres que la IA sujete el martillo o que haga todo el trabajo de carpintería? Si tu flujo es terminal-first (Neovim, tmux) y tus tareas necesitan ejecución y verificación real, Claude Code encaja mejor. Si prefieres trabajar con una GUI y autocompletados, Copilot o Cursor siguen siendo la opción.

    Riesgos técnicos y cómo mitigarlos

    No seas el que apaga las alarmas cuando la factura llega o cuando un despliegue hace “pop”.

    Medidas prácticas

    • Siempre ejecutar agentes en entornos aislados (contenedores, runners de CI) — nunca con acceso directo a producción.
    • Forzar confirmaciones humanas en cambios críticos y desactivar commits automáticos si el repo contiene secretos.
    • Monitorizar consumo de tokens y establecer límites por proyecto para evitar facturas sorpresa.
    • Mantener cobertura de tests mínima antes de delegar refactorizaciones al agente.

    Estas son medidas técnicas, no buenas prácticas bonitas para slides.

    Qué cambia en la cultura de ingeniería

    Esto no reemplaza ingenieros; los hace mejores —o los deja obsoletos. El valor real pasa de escribir código repetitivo a:

    • definir límites del dominio,
    • orquestar agentes,
    • auditar cambios con criterio técnico.

    El rol del Tech Lead se parece menos a “pedir features” y más a “vigilar la caja negra que genera features”. El que entiende cuándo parar al agente y cómo leer su output gana tiempo real y reduce errores.

    Claude Code está aquí para quedarse como capa operativa en pipelines CLI. Dominarlo es, hoy, tan relevante como dominar Git hace una década.

    Próxima entrega

    En la próxima entrega veremos ejemplos prácticos: un flujo de refactorización en React controlado por Claude Code, con comandos, límites de tokens y checklist de seguridad para no romper producción. Esto no acaba aquí.

    Si quieres profundizar en flujos de agentes, automatización y validación en CI, considera explorar Dominicode Labs como espacio para experimentos y guías prácticas. Es una continuación lógica para trabajar protocolos, checklists y plantillas de seguridad antes de desplegar agentes en proyectos reales.

    FAQ

    ¿Qué es Claude Code y en qué se diferencia de un chat con un LLM?

    Claude Code es un agente CLI que opera directamente sobre el repositorio: indexa archivos, planifica cambios, ejecuta tests y puede aplicar commits. A diferencia de un chat, no se limita a sugerir snippets: actúa en el repo y puede iterar hasta que las pruebas pasen o se agote su plan.

    ¿Es seguro permitir que el agente haga commits automáticos?

    Permitir commits automáticos puede ser útil en workflows controlados, pero es recomendable desactivarlo si el repo contiene secretos o recursos críticos. Forzar confirmaciones humanas en cambios sensibles es la práctica prudente.

    ¿Qué tipo de tareas son mejores para este enfoque?

    Es ideal para refactorizaciones a gran escala, arreglar regresiones detectadas por tests y tareas que requieran ejecutar el código (logs, builds, tests). Es menos seguro en código legacy sin cobertura de tests o en dominios donde las reglas de negocio no están codificadas en pruebas.

    ¿Cómo mitigo el costo por tokens en proyectos grandes?

    Establece límites de tokens por proyecto, monitoriza el consumo y ejecuta agentes en entornos donde puedas controlar la granularidad de las iteraciones. Considera estrategias de cache y segmentación de tareas para reducir lecturas innecesarias del repo.

    ¿Qué pruebas debo exigir antes de confiar en cambios automáticos?

    Exige una cobertura mínima de tests automatizados que verifiquen las reglas de negocio críticas. Además, usa ambientes aislados (Docker/CI) y revisiones humanas para cambios de alto impacto.

    ¿Funciona con flujos GUI como IDEs o está pensado solo para terminal?

    Claude Code está pensado para flujos terminal-first y pipelines CLI, pero puede integrarse en flujos más visuales mediante orquestación. Si prefieres autocompletados en el IDE, herramientas como Copilot o Cursor ofrecen mejor experiencia GUI.