DOMINICODE

Category: AI

  • Automatiza tareas avanzadas con Claude Code sin programar

    Automatiza tareas avanzadas con Claude Code sin programar

    Claude Code no es solo para devs: 3 cosas que puedes hacer sin escribir una línea de código

    Tiempo estimado de lectura: 4 min

    • Claude (modelo) permite resolver problemas técnicos sin instalar herramientas.
    • Puedes orquestar flujos en n8n, transformar datos y generar documentación técnica sin escribir JS.
    • La diferencia clave: la CLI modifica repos locales; el modelo responde a instrucciones conceptuales.

    Introducción

    Claude Code no es solo para devs: 3 cosas que puedes hacer sin escribir una línea de código. Si leíste “CLI” y cerraste la pestaña, vuelve. La herramienta CLI existe y exige terminal, Git y permisos. Pero el ecosistema Claude —el modelo razonador accesible vía web y API— te permite resolver problemas técnicos reales sin teclear una sola línea de código. Aquí explico cómo, con ejemplos y enlaces para que lo pruebes.

    Resumen rápido (lectores con prisa)

    Qué es: Claude Code (CLI) es una herramienta para desarrolladores; Claude como modelo es un motor de razonamiento accesible vía web y API.

    Cuándo usarlo: Usa la CLI cuando necesites que un agente toque tu repo y ejecute tests; usa el modelo web/API para diseño de flujos, limpieza de datos, diagramas o specs.

    Por qué importa: Si sabes describir un problema técnico con precisión, puedes extraer valor sin instalar nada.

    Cómo funciona: El CLI actúa sobre repos locales; el modelo responde a instrucciones bien formuladas y genera artefactos accionables.

    1) Orquestar automatizaciones avanzadas en n8n — sin tocar JS

    Problema común

    Un webhook llega con JSON irregular y el flujo se rompe. Solución habitual: pedir a un dev un snippet de JavaScript. Alternativa real: usar Claude.

    Qué pedirle al modelo

    • “Este es el payload (pega ejemplo). Necesito extraer user.id, normalizar created_at a ISO y crear un campo active (true/false) según status. Dame el fragmento listo para pegar en un Code Node de n8n.”

    Qué obtendrás

    • Código listo para pegar que itera arrays, maneja nulos y transforma fechas.
    • Instrucciones de configuración del nodo HTTP (headers, auth).
    • Un plan de manejo de errores: retry con backoff exponencial, alertas en caso de 500/429.

    Por qué importa

    Reduces la fricción de integración y acortas el tiempo desde idea a flujo en producción. Documentación n8n: Documentación n8n

    2) Transformar datos y generar consultas SQL sin abrir una hoja de cálculo

    Caso real

    Recibes CSV/XML legacy y necesitas convertirlo a un esquema usable o sacar métricas complejas.

    Lo que puedes pedir

    • “Toma estas 50 filas (pega muestra). Genera un JSON Schema y un script de transformación (pseudocódigo) que normalice fechas, campos anidados y valores por defecto.”
    • “Explícame la regex para extraer IDs que empiezan por TX- seguido de 8 dígitos.” (Ejemplo: TX-\d{8})

    Qué devuelve Claude

    • JSON Schema validado y reglas de transformación.
    • Consultas SQL optimizadas para tu motor (Postgres, BigQuery), con JOINs, window functions y filtros temporales.

    Por qué importa: eliminas horas de limpieza manual y reduces errores humanos en pipelines de datos. Si necesitas precisión, adjunta la estructura de tablas y el motor SQL para que la query sea ajustada.

    3) Generar documentación técnica y diagramas antes de la implementación

    Usos prácticos

    • Describe el flujo de registro y pide código Mermaid.js para un diagrama de secuencia; pega el resultado en Notion o GitHub y obtén el gráfico inmediato. (Mermaid.js (diagramas))
    • Describe un endpoint (inputs, outputs, errores) y pide un contrato OpenAPI/Swagger listo para revisión. (OpenAPI Spec)
    • Pide un mapa de infraestructura cloud (colas, bases, funciones) con puntos de fallo y recomendaciones de mitigación.

    Qué ganas

    Conversaciones técnicas más cortas, menos malentendidos y decisiones con criterios concretos en lugar de intuición.

    Cómo decidir: CLI o modelo web/API

    Usa Claude Code (CLI) cuando quieras que un agente toque tu repo, ejecute tests o refactorice código localmente. Requiere desenvoltura con terminal y control de versiones.

    Usa Claude Web/API o integraciones (p. ej. n8n) cuando necesites diseño de flujos, limpieza de datos, diagramas o specs. Necesitas claridad conceptual, no sintaxis.

    La ventaja real no es escribir código: es estructurar problemas. Si puedes describir el estado actual, los invariantes y el resultado esperado, Claude lo transforma en artefactos técnicos accionables.

    Dominicode Labs

    Si quieres explorar integración práctica de automatizaciones y artefactos generados por IA en procesos de ingeniería, considera profundizar con recursos adicionales en Dominicode Labs. Es una continuación lógica para llevar los fragmentos y especificaciones que genera Claude hacia pruebas reproducibles y gobernanza de despliegue.

    FAQ

    ¿Necesito instalar algo para usar Claude como modelo?

    No. Claude como modelo está accesible vía web y API, por lo que puedes usarlo sin instalar la CLI ni herramientas locales.

    ¿Cuándo debo preferir la CLI de Claude?

    Prefiérela cuando necesites que un agente modifique repositorios locales, ejecute tests o interactúe con tu entorno de desarrollo. Requiere terminal y control de versiones.

    ¿Puedo usar Claude para generar código listo para n8n?

    Sí. Puedes pedir fragmentos listos para pegar en Code Nodes, junto con configuración HTTP y planes de manejo de errores.

    ¿Claude puede generar consultas SQL optimizadas?

    Sí. Claude devuelve queries ajustadas por motor (Postgres, BigQuery) incluyendo JOINs, window functions y filtros temporales si proporcionas la estructura de tablas.

    ¿Es seguro usar el modelo para datos sensibles?

    El artículo no añade recomendaciones de seguridad concretas, pero sugiere integrar artefactos en procesos de gobernanza y despliegue para que la automatización sea segura y mantenible.

    ¿Dónde encuentro documentación oficial de Claude y herramientas relacionadas?

    Referencias citables en el artículo: Anthropic – Claude Code overview, Claude (Anthropic), n8n (automatización), Mermaid.js (diagramas) y OpenAPI Spec.

  • Cómo implementar Spec-Driven Development con generación de código

    Cómo implementar Spec-Driven Development con generación de código

    Spec-Driven Development y la librería sin código: lecciones prácticas para equipos que usan IA

    Tiempo estimado de lectura: 4 min

    • Los tests y las especificaciones pasan a ser el activo estratégico principal.
    • Los agentes aceleran la prototipación, pero la última milla exige juicio humano y arquitectura.
    • Modularidad y contratos claros son imprescindibles para desarrollo paralelo con agentes.
    • Trátalo como diseño de comportamiento: invierte en especificaciones y suites de pruebas vivas.

    Spec-Driven Development con IA no es una moda; es una reordenación de prioridades. Cuando los agentes pueden generar sintaxis fiable, el verdadero valor deja de estar en el archivo .js o .rs y pasa a estar en la especificación y la suite de tests. Eso no lo hace más fácil: lo hace más exigente.

    Resumen rápido (lectores con prisa)

    Spec-Driven Development centra el valor en especificaciones y suites de tests para permitir que agentes generen implementaciones confiables. Útil cuando las specs y tests son completos; no sustituye el juicio humano en la última milla. Diseña módulos con contratos claros y valida invariantes del sistema.

    Spec-Driven Development y la librería sin código: qué es y por qué importa

    El experimento es simple y brutal. Publicas en GitHub una librería sin código: un README/markdown que define el comportamiento, cientos —o miles— de pruebas de conformidad y un prompt de instalación para que un agente genere el código. Drew Brunig y otros mostraron que eso funciona para problemas acotados y deterministas: el agente lee la spec, ejecuta tests y genera código que pasa las pruebas.

    Los ejemplos más ambiciosos han escalado esto: reimplementaciones de Bash en TypeScript, intérpretes de Python en Rust o intentos de compilar C usando agentes. Vercel, Anthropic y otros equipos han probado variantes de este enfoque; el patrón es claro: la implementación fluye si la especificación y la suite de tests son precisas.

    Fuentes: Anthropic, Vercel.

    Tres razones por las que esto cambia la arquitectura del equipo

    1) Los tests son tu nuevo activo estratégico

    El código generado es barato; las pruebas no. Todos los proyectos que escalaron partieron de suites de testing masivas ya existentes. Si quieres que agentes produzcan un sistema confiable, primero inviertes en definir con precisión cada comportamiento, cada caso borde y cada ambigüedad. Eso es trabajo intelectual, no texto que copia una IA.

    2) La velocidad inicial es real. La última milla, no tanto.

    Con suficientes agentes y presupuesto puedes alcanzar rápidamente un prototipo que pasa el 80–90% de pruebas. Pero los últimos porcentajes —casos borde, coherencia entre módulos, performance y seguridad— requieren arquitectura, diseño y juicio humano. Ahí los agentes tropiezan: arreglar un fallo local puede romper otro subsistema.

    3) La modularidad ya no es sólo bonita; es imprescindible

    Si vas a ejecutar múltiples agentes en paralelo, necesitas módulos con contratos claros y dependencias mínimas. Un sistema fuertemente acoplado multiplica regresiones y conflictos de merge. Diseñar para desarrollo paralelo es diseñar para agentes: interfaces estables, tests de contrato y boundaries claros.

    Qué aprenden los equipos grandes (ejemplos y síntesis)

    • Reutiliza suites de tests fiables cuando existan; son la fruta madura.
    • Divide el problema en paquetes pequeños y bien definidos que puedan implementarse y probarse de forma independiente.
    • Añade pruebas que validen propiedades transversales (invariantes del sistema), no sólo outputs unitarios. Las pruebas que capturan invariantes evitan que arreglos locales creen fallos sistémicos.
    • Mantén la especificación viva: la implementación te enseñará dónde la spec era ambigua. No es un fallo; es el flujo natural: la implementación mejora la spec.

    Historia y perspectiva académica no son decoración: Margaret Hamilton acuñó “software engineering” para evitar exactamente este problema —la complejidad que excede la capacidad cognitiva de una persona— y para recordarnos que el software es diseño de sistemas, no solo código (https://en.wikipedia.org/wiki/Margaret_Hamilton_(computer_scientist)).

    Cómo aplicar esto en tu equipo hoy (guía práctica)

    • Prioriza las pruebas de dominio antes de automatizar la generación. Invierte en casos reales y casos borde.
    • Diseña el repo como una colección de contratos y tests: cada módulo debe tener su spec y su suite independiente.
    • Automate CI con pruebas de contrato y pruebas de integración reducidas que se ejecuten en cada PR generado por un agente.
    • Establece guardrails: linters, análisis estático y políticas de seguridad que los agentes deben respetar.
    • Trátalo como arquitectura colaborativa: los PRs no solo corrigen código; corrigen intención. Revisa tests con la misma seriedad que revisarías código.

    Qué no esperar (y por qué el hype falla)

    No esperes que este enfoque elimine la necesidad de ingenieros senior. No lo hará. Lo que cambia es la naturaleza del trabajo senior: menos tipografía de código, más diseño de comportamiento, más política de pruebas y más pensamiento sistémico. Los agentes son amplificadores; sin criterio técnico, amplifican errores más rápido.

    No esperes soluciones mágicas para sistemas no deterministas: sistemas distribuidos, UI con estados complejos, políticas de seguridad o requisitos de latencia siguen necesitando diseño humano profundo.

    Conclusión

    Spec-Driven Development con IA es una herramienta poderosa, pero exige una reorientación: de escribir código a diseñar comportamientos verificables. El activo que deberías proteger no es el repo, sino la suite de pruebas y los contratos que definen tu dominio. Si empiezas hoy a convertir ambigüedades en tests, estarás construyendo la infraestructura que permite a los agentes realmente escalar tu producto sin destruirlo. Haz eso y la IA deja de ser un truco y pasa a ser una línea de producción fiable.

    Para equipos que exploran flujos de trabajo con agentes y automatización, puede ser útil revisar enfoques prácticos y herramientas en Dominicode Labs. Esto complementa la práctica de convertir especificaciones en suites de tests desplegables.

    FAQ

    Respuesta: Spec-Driven Development con IA es un enfoque donde la especificación y una suite de tests rigurosa son la fuente de verdad; agentes generan implementaciones que son validadas contra esas pruebas.

    Respuesta: Es apropiado para problemas acotados y deterministas donde puedes definir comportamientos y casos borde exhaustivamente. Funciona menos bien en dominios no deterministas sin especificaciones completas.

    Respuesta: No. Los agentes amplifican productividad, pero el trabajo senior evoluciona hacia diseño de comportamiento, arquitectura de pruebas y evaluación de trade-offs.

    Respuesta: Las suites de tests de dominio y las pruebas que validan invariantes transversales son las más valiosas. Tests de contrato e integración automatizados evitan que soluciones locales rompan el sistema.

    Respuesta: Diseña módulos con contratos estables, limita dependencias y ejecuta pruebas de contrato en CI para cada PR generado por un agente. Linters y análisis estático ayudan como guardrails.

    Respuesta: Anticipa limitaciones en casos borde, performance, seguridad y sistemas no deterministas. La última milla requiere diseño humano; no es una solución automática para todos los dominios.

  • Cómo sincronizar especificaciones, pruebas y código en el desarrollo

    Cómo sincronizar especificaciones, pruebas y código en el desarrollo

    El Triángulo del Desarrollo Dirigido por Especificaciones: cómo evitar gestionar un proceso de programación que superó la capacidad de manejo de un solo hombre. Ni siquiera de un equipo; de un solo hombre..

    Tiempo estimado de lectura: 5 min

    • Ideas clave:
    • El triángulo fundamental: especificación, tests y código deben mantenerse sincronizados.
    • Los agentes aceleran implementación pero introducen decisiones trazables que deben registrarse.
    • Herramientas como Plum extraen decisiones de diffs y traces para actualizar la spec y generar artefactos auditable.
    • Procesos claros (captura de traces, aprobación humana, sync en CI) son necesarios para evitar deuda técnica acelerada.

    El triángulo es simple y brutal: especificación, tests y código. Si uno se despega, el proyecto se rompe. So welcome: este artículo explica por qué el Spec‑Driven Development dejó de ser una ecuación lineal y cómo convertir ese triángulo en una práctica gobernable cuando agentes de IA escriben código.

    Resumen rápido (lectores con prisa)

    Qué es: Un enfoque que trata a la especificación, la suite de tests y el código como un triángulo que debe permanecer sincronizado.

    Cuándo usarlo: Cuando agentes (LLMs/automations) o equipos múltiples generan cambios rápidos y necesitas trazabilidad.

    Por qué importa: Para evitar deuda técnica acelerada y pérdida de intención por decisiones no documentadas.

    Cómo funciona (resumen): Captura diffs y traces, extrae decisiones, confirma con humanos y sincroniza spec↔tests↔código.

    El triángulo: Spec, Tests, Código — So welcome: por qué no basta con una spec

    So welcome: si piensas que subir una spec y soltar agentes en ella es todo lo que hace falta, estás confundiendo velocidad con control. La spec define qué debe pasar. Los tests validan. El código implementa y descubre cosas. Pero la implementación introduce decisiones —humanas y de IA— que permanecen en los traces. Si no capturas esas decisiones, la spec se queda atrás y el sistema deriva. Resultado: managing a coding process that grew beyond one man’s ability to manage. Not even a team, one man.

    ¿Por qué esto importa hoy?

    • Porque los agentes aceleran la implementación.
    • Porque la implementación revela ambigüedades que la spec no anticipó.
    • Porque los hotfixes y cambios urgentes suelen entrar directo al código y no a la spec.

    Si no sincronizas, la velocidad se vuelve deuda técnica exponencial.

    Señales que te indican que el triángulo está roto

    • Commits frecuentes sin cambios en la spec.
    • Pull requests que corrigen tests porque la spec no reflejaba decisiones recientes.
    • Conversaciones largas con el agente donde se tomaron decisiones y nadie las documentó.
    • Cobertura de tests alta en líneas, baja en intención (las pruebas no cubren los requisitos del producto).

    Estas señales son tangibles. Úsalas. Git te cuenta qué cambió. Los traces de los agentes (chats, prompts, respuestas) contienen las decisiones. Los tests te dicen qué se ejecuta. Cruza esas fuentes y tendrás diagnóstico.

    Plum — la plomada que mide la verticalidad del triángulo

    No es teoría: existen herramientas prácticas. Plum (sí, como plomada) busca las decisiones en los diffs y en los traces y las convierte en artefactos verificables. Flujo resumido:

    Plum: Flujo resumido

    1. Ejecutas commit.
    2. Plum lee los diffs y analiza los traces del agente.
    3. Extrae decisiones, las dedupea y te pide aprobación.
    4. Actualiza la spec (Markdown) según lo aprobado.
    5. Ejecuta sync y te muestra brechas spec↔tests↔código.

    Genera además un archivo .jsonl con el historial de decisiones: pregunta, decisión, autor (humano/LLM), rama, timestamps. Eso pasa de “intención perdida en Slack” a “artefacto auditable en el repo”.

    Plum: Instalación mínima

    Instalación mínima: pip install plum-dev. (Limitación actual: integrado con pytest; funciona mejor cuando la spec está por delante del código.)

    Prácticas para mantener el triángulo en sincronía

    • Escribe la spec como un contrato de comportamiento, no como un manifiesto aspiracional. Casos de borde incluidos.
    • Prioriza la suite de tests como activo estratégico: invierte en pruebas que describan la intención, no solo en asserts unitarios.
    • Trata los traces de agente como código: captúralos, régistralos y asócialos a commits.
    • En cada PR generado por agente: exige la checklist de decisiones aprobadas y la actualización del spec.
    • Añade pruebas de invariantes sistémicas (property tests) que detecten regresiones causadas por cambios locales.
    • Diseña módulos con contratos estables para permitir paralelismo de agentes sin colisiones.

    Qué no esperar de los agentes (y por qué necesitas humanos

    • No esperes que un LLM mantenga la visión de producto a largo plazo. Puede sugerir cambios documentales, pero la validación de negocio es humana.
    • No esperes que arreglen deuda técnica sistémica solos. Pueden parchar, pero no rediseñar la arquitectura sin dirección.
    • No esperes que la spec se actualice mágicamente: necesita decisiones aprobadas y trazables.

    Checklist rápido para equipos que van a integrar agentes

    1. Tener specs en Markdown rastreables en repo.
    2. Tener suite de tests ejecutable en CI (pytest u otro).
    3. Integrar captura de traces de agentes (logs/JSON).
    4. Añadir herramienta de reconciliación (ej. Plum) en el pipeline local/CI.
    5. Forzar aprobación humana de decisiones extraídas antes de merge.
    6. Ejecutar sync spec↔tests↔código en cada PR.

    Cierre (acción clara)

    Si tu equipo ya usa agentes y no tiene un proceso de reconciliación entre spec, tests y código, estás acelerando la creación de un legado ilegible. Haz esto hoy: instala plum‑dev, apunta la herramienta a tu spec y a tus tests, y corre plum sync en tu CI. Si no puedes hacerlo aún, al menos comienza a registrar las decisiones en cada PR. No es glamour. Es gobernanza. Y sin eso, la velocidad que prometen los agentes solo te dará más problemas.

    Haz clic aquí para empezar: pip install plum-dev y corre plum init en un repo con spec y pytest.

    Para equipos que integran agentes y workflows de automatización, una continuación natural es explorar recursos y prácticas en Dominicode Labs, donde se agrupan experimentos y herramientas relacionadas con reconciliación de specs, capture de traces y pipelines de pruebas.

    FAQ

    ¿Qué es el “triángulo” en Spec‑Driven Development?

    Es la idea de que especificación, tests y código forman un conjunto interdependiente. Si cualquiera de los tres se desincroniza, el proyecto corre riesgo de perder intención y acumular deuda técnica.

    ¿Por qué los agentes rompen la sincronía entre spec, tests y código?

    Porque aceleran la implementación y toman decisiones durante el desarrollo (en prompts, chats, respuestas) que a menudo no quedan reflejadas en la spec ni en los tests, creando discrepancias trazables en diffs y commits.

    ¿Qué hace Plum exactamente?

    Plum analiza diffs y traces de agentes, extrae decisiones, las dedupea, solicita aprobación y actualiza la spec en Markdown. También genera un archivo .jsonl con el historial de decisiones para auditoría.

    ¿Cómo debo tratar los traces de agentes?

    Captúralos y regístralos como artefactos vinculados a commits; trátalos como código: deben estar versionados, asociados a PRs y revisados por humanos para extraer decisiones verificables.

    ¿Qué requisitos mínimos necesito para integrar este flujo?

    Specs en Markdown rastreables, suite de tests ejecutable en CI (por ejemplo pytest), captura de traces (logs/JSON) e integración de una herramienta de reconciliación en el pipeline.

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

    Siempre un humano con responsabilidad de producto o arquitectura. Las herramientas extraen y proponen; la validación de negocio y la aprobación final deben ser humanas.

  • Cómo construir un SaaS con IA resiliente y escalable

    Cómo construir un SaaS con IA resiliente y escalable

    ¿Quieres un SaaS con IA que sobreviva seis meses en producción o solo un demo viral de 48 horas?

    Tiempo estimado de lectura: 5 min

    • Ideas clave:
    • La diferencia entre un demo viral y un SaaS real no es la idea ni el modelo, sino la arquitectura.
    • Diseña asumiendo que la IA falla: latencia, rate limits y respuestas inconsistentes son inevitables.
    • Separación clara de responsabilidades (frontend, backend, orquestador, workers, persistencia) y asincronía por defecto salvan proyectos.
    • Contratos estrictos (JSON + validación) y observabilidad desde el inicio son imprescindibles para producción.

    ¿Quieres un SaaS con IA que sobreviva seis meses en producción o solo un demo viral de 48 horas?

    La diferencia no es la idea ni el modelo que uses. Es la arquitectura. Y sí: la IA te hace sentir productivo en minutos. También te hace pagar por la reescritura en semanas.

    Voy al grano. Si tu apuesta es “poner un prompt en un endpoint y ver qué pasa”, estás construyendo un wrapper, no un producto. Un wrapper se rompe cuando el proveedor cambia precios, cuando la latencia sube o cuando un caso borde que nunca imaginaste llega a producción. Un SaaS real convierte la IA en un componente confiable dentro de un sistema diseñado para fallar sin morir.

    Aquí tienes un plan práctico y sin postureo para construir un SaaS real con IA sin improvisar.

    Resumen rápido (lectores con prisa)

    Qué es: Buenas prácticas de arquitectura para convertir modelos de IA en componentes fiables dentro de un SaaS.

    Cuándo usarlo: Desde el MVP que pretende escalar hasta productos en producción con múltiples tenants y requisitos de coste y seguridad.

    Por qué importa: Evita que un prototipo se convierta en deuda técnica cara y en incidentes de producción.

    Cómo funciona, en pocas palabras: Separación de responsabilidades, asincronía por defecto, contratos estrictos (JSON + validación), observabilidad y pruebas que incluyan fallos de IA.

    Primera regla: asume que la IA falla… constantemente

    No es pesimismo. Es ingeniería. Latencia, rate limits, respuestas inconsistentes, cambios en la API: todo será parte de la vida diaria. Diseña para eso.

    Qué separar desde el minuto uno

    No mezcles interfaz, orquestación y persistencia. Divide responsabilidades claras:

    • Frontend: experiencia, manejo de latencia, feedback al usuario.
    • Backend de negocio: validaciones, reglas, monetización, seguridad.
    • Orquestador de IA: flujos, reintentos, parsing y almacenamiento de resultados.
    • Workers: procesamiento asíncrono, reintentos idempotentes.
    • Persistence: PostgreSQL (con pgvector), logs, metadatos.

    Si todo está en el mismo contenedor, el sistema se romperá bonito y rápido.

    Patrón que salva proyectos: asincronía por defecto

    Olvida la llamada síncrona “cliente→server→LLM→cliente”. Es la receta del timeout.

    • Client envía tarea → server registra job (estado: pending) → responde 202.
    • Worker (o n8n) toma job, hace llamadas a LLMs, actualiza estado.
    • Notifica por WebSocket/SSE o el cliente hace polling leve.

    Resultado: interfaz reactiva, control de reintentos y mejor experiencia cuando la IA tarda.

    Orquestación: usa n8n, no code spaghetti

    Sí, puedes encadenar prompts en código. También puedes terminar con funciones de mil líneas. Usa un orquestador (n8n o equivalente) para:

    • Encadenar pasos (call LLM → transformación → persistencia).
    • Ejecutar retries con backoff.
    • Manejar errores y circuit breakers visualmente.
    • Mantener logs de cada ejecución.

    El día que la API de IA se ponga inestable, agradecerás no tener que rastrear todo en un repo lleno de lambdas.

    Contratos > Prompts

    No pidas “texto bonito”. Pide JSON estricto. No hay excusas.

    • Define interfaces TypeScript o OpenAPI.
    • Obliga a la IA a devolver un objeto con esquema verificado.
    • Usa Zod o codegen para validar la respuesta y fallar rápido si hay desviaciones.

    Esto convierte a la IA en un microservicio con contrato, no en una caja negra caprichosa.

    RAG = potencia + responsabilidad

    Si vas a permitir que usuarios suban documentos para chatear con ellos, aplica aislamiento absoluto:

    • Cada vector con tenant_id.
    • Filtrado por tenant_id a nivel de consulta (antes de enviar contexto al LLM).
    • Escapa la tentación de “mezclar para mejores embeddings”. Eso rompe privacidad y compliance.

    Si trabajas con datos sensibles, aíslalo, audítalo y documenta quién lo puede ver.

    Costos y medición: que no te coja desprevenido

    Un SaaS con IA vive o muere por el coste por petición.

    • Metering por job: tokens consumidos, llamadas a terceros, tiempo de ejecución.
    • Alerts por coste semanal y por job atípico.
    • Fallbacks: versiones más baratas del modelo para tareas no críticas.
    • Caching inteligente: respuestas deterministas pueden cachearse.

    No hay nada más caro que ejecutar un modelo grande para una operación que podía resolverse con reglas.

    Idempotencia y seguridad en flujos asíncronos

    Reintentos inevitables → diseñalos bien:

    • Usa IDs de correlación.
    • Diseña workers idempotentes: reintentar no debe duplicar registros ni cobrar dos veces.
    • Aplica locks por job cuando haga falta.

    Observabilidad: telemetría desde el minuto cero

    Si no puedes medir, no puedes mejorar. Instrumenta todo:

    • Traces distribuidos (OpenTelemetry).
    • Métricas por endpoint, por modelo y por tenant.
    • Logs estructurados con contexto de job.
    • Dashboards y alertas (latencia, error rates, coste por tenant).

    Tests y contratos automáticos

    Haz que cada contrato tenga tests que fallen en CI si la IA devuelve algo fuera de esquema.

    • Mockea respuestas de LLM (positivas y negativas).
    • Tests de integración que simulen timeouts y retries.
    • Tests de seguridad: inyección de prompt, accesos cruzados entre tenants.

    Checklist MVP vs. Producción

    MVP mínimo viable (rápido, medible):

    • Job queue + worker básico.
    • Interfaces TypeScript + validación Zod.
    • Persistencia en PostgreSQL + pgvector.
    • Orquestación simple (n8n optional).
    • Métricas básicas y alertas de coste.

    Preparación para producción:

    • Observabilidad completa (traces, metrics, logs).
    • Políticas de multi-tenancy estrictas.
    • Circuit breakers, retries con backoff y dead-letter queues.
    • Billing y metering por tokens/calls.
    • Testing de resiliencia y chaos experiments.

    Plantilla rápida de SPEC.md que debes tener ya

    Pon esto en la raíz del repo. Si no lo haces ahora, lo pagarás después.

    • Objetivo del módulo (1 frase).
    • Stack aprobado y versiones.
    • Reglas innegociables (ej.: “No exponer secretos en frontend”, “Todo job idempotente”).
    • Contratos principales: Endpoints + interfaces TS.
    • Criterios de aceptación (tests que deben pasar).
    • Responsable técnico y proceso de cambios.

    Prompt maestro que funciona (ejemplo)

    Contexto + restricciones + output estricto:

    <contexto_negocio>Resumen en 3 frases</contexto_negocio>
    <stack>Next.js, Node 20, Postgres + pgvector</stack>
    <restricciones>No usar microservicios, respuesta JSON valida Zod</restricciones>
    <output_esperado>JSON { result: string, score: number, metadata: { sourceId: string } }</output_esperado>

    No es glamour. Es ingeniería que evita tickets nocturnos.

    El nuevo rol del equipo: menos héroes, más guardias

    Con IA el que más aporta no es el que teclea más rápido. Es el que fija límites, define contratos y establece el ritmo de iteración. El senior deja de ser “code god” para ser “arquitecto de fronteras”. Eso es lo que realmente escala.

    CTA corto y útil

    Si quieres, te doy ahora:

    • Una SPEC.md lista para pegar en tu repo.
    • Un prompt maestro para Claude + ejemplos de Zod.
    • Un .n8n workflow básico para encadenar llamadas a modelos con retries.

    Respóndeme con “Plantilla SaaS” y te lo envío. Hazlo ahora: crea el SPEC.md en la raíz antes del próximo commit generado por IA.

    Dominicode Labs

    Si quieres continuidad práctica y recursos relacionados con orquestación, workflows y automatización para productos de IA, visita Dominicode Labs. Es una continuación lógica para poner en práctica los enfoques descritos en este artículo.

    FAQ

    ¿Por qué no debería hacer llamadas síncronas al LLM desde el cliente?

    Porque los timeouts, latencias y rate limits hacen que la experiencia sea impredecible. La arquitectura asíncrona (jobs + workers) permite reintentos, control de costes y una interfaz más robusta.

    ¿Qué es un orquestador y por qué usar n8n?

    Un orquestador encadena pasos: llamadas a LLM, transformaciones, persistencia y retries. n8n ofrece visualización de flujos, gestión de errores y menos código espagueti en repositorios complejos.

    ¿Cómo obligo a la IA a devolver JSON válido?

    Define un contrato (TypeScript/OpenAPI) y valida con Zod u otro validador. Rechaza respuestas que no cumplan el esquema y trata esos casos en tus retries o dead-letter queues.

    ¿Qué medidas tomar para multi-tenancy en RAG?

    Aislamiento absoluto: cada vector con tenant_id, filtrado por tenant_id antes de consultas y auditoría de accesos. No mezclar datos entre tenants.

    ¿Qué métricas debo medir desde el primer día?

    Tokens consumidos por job, latencia por endpoint, error rate por modelo y coste por tenant. También traces distribuidos y logs estructurados por job.

    ¿Qué debe incluir mi SPEC.md mínimo?

    Objetivo del módulo, stack y versiones, reglas innegociables, contratos principales (endpoints + interfaces TS), criterios de aceptación y responsable técnico.

  • Cómo gestionar la gobernanza de IA para evitar la deuda técnica

    Cómo gestionar la gobernanza de IA para evitar la deuda técnica

    ¿Te vas a mirar el correo mientras la IA reescribe tu código… y luego vuelves a casa de locos?

    Tiempo estimado de lectura: 6 min

    • La delegación ciega a agentes que ejecutan cambios produce deuda técnica documentada fuera del repo.
    • La solución práctica es gobernar decisiones: exigir artefactos versionables con autoría y timestamp.
    • Plum: herramienta que intercepta commits, extrae decisiones y fuerza aprobaciones antes del commit.

    Poca gente lo dice en voz alta: dejar que un agente “lo corra y volvemos” es exactamente la forma más rápida de cavar una trampa de deuda técnica. Sales cinco minutos. Vuelves y el LLM te dejó un “decision” que grita: eso es una locura. No lo hagas.

    Esto no es un problema de postureo. Es práctico. Es urgente.

    Resumen rápido (lectores con prisa)

    Un agente que ejecuta cambios sin gobernanza introduce decisiones sin autoría en el repo. Necesitas un mecanismo externo que intercepte commits, extraiga decisiones y requiera aprobación, convirtiéndolas en artefactos versionables y auditable—eso reduce deuda técnica y mejora trazabilidad.

    1) Lo que pasa cuando “lo dejamos correr”

    Un agente se queda ejecutando tareas. Encuentra ambigüedades. Encuentra dependencias rotas. Para avanzar, toma atajos. Guarda esos atajos en su chat. Tú haces commit y pum: el código llega a la rama, los tests pasan y la intención se evapora.

    Resultado: hacks documentados en conversaciones privadas, no en el repo. Atajos que nadie planeó. Deuda técnica que aparece al lado del despliegue.

    2) Por qué esto es peor que un bug cualquiera

    Un bug puedes rastrearlo. Una decisión sin autoría es un agujero negro. Nadie recuerda por qué cambó la fórmula de impuestos a las 3 AM. Nadie puede auditar la razón. Y cuando el problema explota en producción, el “blame” no sirve: no hay decisión firmada, solo un commit huérfano y un chat que nadie va a revisar.

    3) La solución no es prohibir la IA. Es gobernarla.

    No más fe ciega. No más prompts que funcionan en beta pero rompen en prod. Necesitamos que cada decisión que importe deje rastro formal. Que sea un artefacto. Que sea buscable. Que tenga autoría y timestamp. Que puedas preguntar: “¿por qué esto existe?” y obtener una respuesta concreta.

    4) Plum: la plomada que obliga a decidir en serio

    Imagina una herramienta que corre al lado de Git y te fuerza a responder. No genera código por ti. No es una skill adentro del LLM. Es un checkpoint.

    Básicos del flujo

    • plum init → crea .plum y .plumignore, añade hooks.
    • Cambias código con un agente.
    • Intentas git commit. Plum compara diffs y scans de traces.
    • Si hay decisiones, el commit falla hasta que apruebes, edites o rechaces.
    • Si apruebas, plum actualiza la spec (Markdown) y agrega una entrada .jsonl con: pregunta, decisión, autor, branch y timestamps.

    ¿La ventaja? Cuando vuelvas del mail, no te encuentras sorpresas sin contexto. Te encuentras una decisión con nombre y apellido.

    5) No puede ser una “skill” del agente —y punto

    Una skill dentro del LLM es una sugerencia. Las sugerencias se ignoran. La gobernanza debe estar fuera. Tiene que poder bloquear commits, integrarse en CI y ser determinista. Si es opcional, no sirve.

    6) ¿Qué hay dentro del .jsonl y por qué importa?

    Ese archivo no es solo logs. Es la historia de la intención del proyecto. Cada entrada contiene:

    • El dilema técnico.
    • La decisión tomada.
    • Quién aprobó.
    • Si fue propuesto por el LLM o por un humano.
    • Vínculo a la diff/PR.
    • Marcas de tiempo.

    Eso convierte la intención en dato: indexable, auditable, útil para auditorías y forensics.

    7) Problemas reales —sin romanticismos

    • Deduping de decisiones es fuzzy. Detectar “la misma decisión” entre conversaciones distintas no es trivial. Requiere heurísticas y ajuste repo-específico.
    • Rollbacks automáticos: si rechazas la decisión, idealmente el sistema revierte el cambio o pide al agente rehacerlo. Hoy eso es work-in-progress.
    • Ruido: si cada hotfix dispara cinco decisiones, la herramienta es odiada. Necesitas umbrales configurables.
    • Specs crecen como malas hierbas. Hay que shardearlas en requerimientos atómicos, y sí: un LLM puede ayudar a fragmentarlas, pero diseña el flujo.

    8) Umbrales: sensibilidad y contexto

    La clave práctica es permitir tolerancias dinámicas:

    • Modo strict: todo pasa por aprobación (fintech, salud).
    • Modo sane: decisiones no críticas se agrupan y se presentan en lote.
    • Modo fast-lane: “dangerously approve all” para prototipos.
    • Filtros por carpeta: core = strict; ui-experiments = lenient.

    Hazlo configurable por módulo y por rama. No es capricho: es supervivencia.

    9) Integración con DSPy y el determinismo

    Cuando puedas validar con código, hazlo. Usa parsers, tests y reglas. Donde necesites LLMs (p.ej. parse semántico del spec), estructura las llamadas con DSPy: inputs y outputs tipados. Menos alucinaciones, más predictibilidad. Enrutamiento por velocidad: dedupe puede ir a modelos OSS rápidos; parsing pesado a modelos más potentes.

    10) ¿Qué debería cambiar en GitHub?

    Markdown no es solo texto. Debe ser ciudadano de primera clase. Tu spec tiene que ser operable, con vínculos directos a decisiones, código y tests. Visualizar esa malla en GitHub (decisiones ↔ requisitos ↔ tests ↔ diffs) debería ser trivial. Imagina abrir un diff de markdown y ver “este requisito cambia X líneas de código” con enlaces directos. Eso es la próxima generación de repositorios.

    11) Cultura y proceso: lo que no puedes automatizar

    No automatices la cultura. Exige que cada PR responda:

    • ¿Qué decisión justificó este cambio?
    • ¿Qué requirement se actualiza?
    • ¿Qué test cubre el cambio?

    Haz que la herramienta extraiga esos metadatos y los convierta en entradas .jsonl. Convierte la disciplina en hábito.

    12) Checklist mínimo para empezar hoy (15–30 minutos)

    1. Versiona tu spec en Markdown en la raíz del repo.
    2. Asegura tests automatizados (si eres Python, Pytest; si no, prepara adapter).
    3. pip install plum-dev
    4. plum init → apunta specs.md y carpeta de tests.
    5. Añade .plumignore (README, docs, assets).
    6. Configura umbrales: prod = strict; feature branches = lenient.
    7. Prueba: haz un cambio via agente, intenta commit, observa el fail y aprueba la decisión.
    8. Ejecuta plum sync -> revisa gaps spec↔tests↔code.

    13) Si no lo haces: la factura llegará

    Velocidad hoy = caos mañana. Cuando explote algo crítico a las 2 AM, nadie sabrá por qué la regla cambió. El time-to-fix se multiplicará. La deuda técnica se vuelve refractorable, y cada refactor cuesta más que el ahorro inicial de haber delegado.

    14) Beneficios reales (sí, más allá del miedo)

    • Auditoría real para compliance.
    • Onboarding más rápido: nuevos devs leen el árbol de decisiones.
    • Menos debates eternos en PRs: la intención está documentada.
    • Productividad con control: velocidad sin descontrol.

    15) Cierre y acción concreta

    No es sexy. Es necesario. Instala la plomada. Prueba en una rama. No por postureo: por supervivencia técnica.

    Quiero ayudarte a empezar ya. ¿Quieres que te mande:

    • el template de .jsonl listo para copiar,
    • el flujo de PR + configuración de CI que bloquea merges hasta sync exitoso,
    • y un checklist de integración de Plum en 15 minutos?

    Respóndeme “Mándame el template” y te lo doy ahora mismo.
    Y mientras lo instalas, recuerda esto: velocidad sin plomada es solo una forma elegante de cavar tu propia trampa.

    Esto no acaba aquí.

    Si quieres profundizar en prácticas de gobernanza y automatización que encajan con este enfoque, revisa Dominicode Labs para recursos y experimentos relacionados.

    FAQ

    ¿Qué hace exactamente Plum cuando detecta una decisión?

    Intercepta el commit, extrae decisiones desde los traces del agente y falla el commit hasta que alguien apruebe, edite o rechace la decisión.

    ¿Plum bloquea commits automáticamente?

    Sí: si detecta decisiones relevantes, el commit falla hasta que se resuelva la aprobación o edición de esa decisión.

    ¿Cómo se almacena la autoría y los timestamps?

    Se agregan entradas .jsonl con campos como pregunta, decisión, autor, branch y timestamps; además la spec en Markdown se actualiza para reflejar la decisión.

    ¿Cómo evito que la herramienta genere ruido?

    Configura umbrales y filtros por carpeta, agrupa decisiones no críticas en lotes y ajusta sensibilidad por rama o módulo.

    ¿Se puede integrar Plum en CI/CD?

    Sí. La gobernanza debe integrarse en CI para ser efectiva; Plum puede bloquear merges hasta que el sync y las aprobaciones sean exitosas.

    ¿Qué contiene una entrada .jsonl?

    Cada entrada incluye el dilema técnico, la decisión, quién aprobó, si fue propuesto por LLM o humano, vínculo a la diff/PR y marcas de tiempo.

    ¿Qué pasa si rechazo una decisión detectada?

    Idealmente el sistema revierte el cambio o solicita al agente rehacerlo; hoy ese comportamiento es work-in-progress y depende de la configuración del repositorio.

    ¿Cómo empezar en 15 minutos?

    Versiona la spec en Markdown, asegura tests automatizados, instala plum-dev, ejecuta plum init, configura .plumignore y umbrales, y prueba el flujo con un cambio vía agente.

  • Automatización en n8n: Cómo usar Claude Code sin saber programar

    Automatización en n8n: Cómo usar Claude Code sin saber programar

    ¿No sabes programar? Claude Code puede cambiar igual tu forma de trabajar

    Tiempo estimado de lectura: 5 min

    • Claude Code (CLI) ≠ Claude (modelo): la CLI interactúa con tu repo/terminal; el motor se puede usar vía web/API y en integraciones.
    • No necesitas saber sintaxis para obtener valor: se requiere criterio sobre datos, límites y salida esperada.
    • Tres escenarios prácticos: automatizaciones en n8n, limpieza/transformación de datos y documentación/diseño técnico.
    • Prompts efectivos: ejemplos concretos, formato de salida, entorno objetivo y verificación con ejemplos de entrada/salida.

    Si tu respuesta fue “no” al leer la palabra terminal, tranquilo: ¿No sabes programar? Claude Code puede cambiar igual tu forma de trabajar. La distinción clave es simple y práctica: Claude Code (la CLI) no es lo mismo que Claude, el motor de razonamiento que puedes usar vía web, API o en integraciones como n8n. Entender eso cambia todo.

    Fuentes para comprobar:

    Resumen rápido (lectores con prisa)

    Claude Code es la CLI que puede manipular tu repositorio y ejecutar acciones locales. Claude (el motor) está disponible vía web y API y es útil para transformar criterio en artefactos técnicos sin necesidad de escribir mucho código. Usa la CLI para cambios locales y la API/web para flujos visuales, automatizaciones y generación de snippets.

    ¿No sabes programar? Claude Code puede cambiar igual tu forma de trabajar — lo que realmente importa

    No necesitas saber sintaxis para obtener valor técnico real. Sí necesitas criterio: saber qué quieres, de dónde vienen los datos y cuáles son los límites aceptables. Claude transforma ese criterio en artefactos técnicos —snippets, esquemas, queries, diagramas— que cualquiera puede usar.

    La CLI es potente y exige terminal, Git y permisos. Pero el motor (Claude) puede integrarse en flujos visuales o atender peticiones desde la web. Esa capa intermedia es la que permite a product managers, automation builders y responsables de operaciones avanzar sin depender de un dev full-time.

    A continuación, tres escenarios concretos donde este cambio se nota en horas, no en semanas.

    Tres escenarios concretos

    1) Automatizaciones en n8n sin aprender JavaScript

    Problema real: un webhook te llega con JSON mal formado y tu flujo se rompe. Solución clásica: abrir VS Code y escribir un snippet. Solución práctica hoy: pedirle al modelo.

    Qué hacer:

    • Pega 3–5 ejemplos del payload entrante.
    • Describe la salida deseada (campos, tipos, defaults).
    • Pide el fragmento para un Code Node de n8n y las instrucciones de configuración del nodo HTTP Request (headers, auth).

    Qué recibes:

    • Código listo para pegar (manejo de nulos, conversión de fechas, normalización).
    • Un plan de reintentos (backoff exponencial) y puntos de alerta para errores 429/500.

    Por qué es útil: reduces fricción y tiempo de integración. n8n docs

    2) Limpieza y transformación de datos sin depender de un analista

    Problema real: CSV legacy con fechas en 5 formatos y IDs mezclados. El backlog técnico explota.

    Qué pedir:

    • “Convierte estas 50 filas en JSON válido y genera un JSON Schema. Indica transformaciones campo a campo y regex para IDs que empiecen por TX- y 8 dígitos.”

    Qué recibes:

    • JSON Schema para validar importación.
    • Reglas de transformación (pseudocódigo) y la regex exacta.
    • Si quieres, la consulta SQL para insertar/normalizar en Postgres o BigQuery.

    Beneficio: automatizas pipelines de datos sin hojas de cálculo infernales ni tickets eternos al equipo de datos.

    3) Documentación y diseño técnico antes de escribir una sola línea de código

    Problema real: reunión técnica de 40 minutos sin artefactos concretos. Resultado: ambigüedad y retrabajo.

    Qué pedir:

    • Describe el flujo de negocio y pide un diagrama en Mermaid.js.
    • Describe un endpoint y pide la especificación OpenAPI/Swagger.

    Qué recibes:

    • Código Mermaid listo para pegar en Notion/GitHub y visualizar el diagrama. (Mermaid)
    • Un contrato OpenAPI que el equipo de backend puede implementar sin interpretaciones vagas. (OpenAPI)

    Resultado tangible: reuniones más cortas, decisiones con base y menos tickets de aclaración.

    Cómo estructurar prompts que funcionen (reglas prácticas)

    1. Muestra ejemplos concretos. No abstracciones.

    2. Describe el resultado esperado con formatos y límites: tipos de datos, formatos de fecha, tolerancia a errores.

    3. Indica el entorno objetivo: n8n Code Node, Postgres, BigQuery, Notion, etc.

    4. Pide verificación: un ejemplo de entrada y salida esperada.

    Una plantilla compacta:

    “Ejemplo de entrada: [pega]. Objetivo: [qué quieres]. Reglas: [validaciones]. Entorno: [n8n/Postgres/Notion]. Devuélveme: [snippet/JSON Schema/diagram mermaid/OpenAPI].”

    Cuándo deberías usar la CLI de Claude y cuándo el modelo web/API

    – Usa Claude Code (CLI) si necesitas que un agente toque tu repo, ejecute tests o refactorice código localmente. Requiere comodidad con la terminal y Git.

    – Usa Claude Web/API si tu necesidad es transformar datos, diseñar flujos, generar specs o prototipos visuales. Requiere claridad conceptual, no sintaxis.

    La IA no te da la respuesta mágica si no sabes qué preguntar. Pero convierte tu criterio en artefactos operativos que acortan ciclos y reducen dependencias.

    Esto no acaba aquí: prueba pedir a Claude un solo fragmento pequeño en tu flujo n8n y mide la diferencia. Verás que la ventaja no está en escribir código, sino en convertir ideas ordenadas en resultados reproducibles.

    Dominicode Labs

    Si quieres explorar plantillas, ejemplos y flujos de automatización adaptados a equipos no especializados en programación, considera revisar recursos adicionales en Dominicode Labs. Encontrarás ejemplos prácticos y plantillas que complementan lo que puedes generar con Claude y flujos como n8n.

    FAQ

    ¿Qué es Claude Code?

    Claude Code es la interfaz de línea de comandos (CLI) de Anthropic diseñada para que un agente automatizado interactúe con repositorios, ejecute tareas locales y aplique cambios programáticos sobre código y artefactos del proyecto.

    ¿En qué se diferencia Claude (motor) de la CLI?

    El motor Claude es el servicio de razonamiento accesible vía web o API para generar texto, código y artefactos. La CLI (Claude Code) actúa como un agente que puede tocar el sistema de archivos, ejecutar comandos y modificar repositorios localmente.

    ¿Necesito saber programar para obtener valor?

    No necesitas dominar sintaxis para extraer valor. Necesitas criterio: definir entradas, salidas y límites. Con esa claridad, Claude puede generar snippets, esquemas y transformaciones utilizable por equipos no especializados.

    ¿Cómo usar Claude con n8n?

    Para integrarlo en n8n, proporciona ejemplos del payload, especifica la salida deseada y pide un fragmento listo para un Code Node más instrucciones para el nodo HTTP Request (headers, auth). El modelo puede devolver código manejando nulos, fechas y estrategias de reintento.

    ¿Qué debo incluir en un prompt para obtener un snippet útil?

    Incluye ejemplos concretos de entrada, el objetivo claro (campos, tipos, defaults), reglas de validación y el entorno objetivo (p. ej. n8n Code Node). Pide además ejemplo de entrada/salida para verificación.

    ¿Dónde puedo verificar fuentes y documentación?

    Revisa la documentación oficial citada: Anthropic — Claude Code overview, Claude (Anthropic), n8n, Mermaid.js y la OpenAPI Spec.

  • Cómo implementar CLAUDE.md para agentes de código automatizados

    Cómo implementar CLAUDE.md para agentes de código automatizados

    CLAUDE.md: el contrato entre tú y el agente

    Tiempo estimado de lectura: 6 min

    • Define reglas operativas claras para evitar que agentes automaticen o “improvisen” sobre código base.
    • Estandariza stack, comandos y convenciones para que el agente genere cambios compatibles con el repositorio.
    • Mantén el archivo actualizado y versiónalo junto con cambios en el stack para evitar divergencias.

    Introducción

    CLAUDE.md: el contrato entre tú y el agente es el punto de control que evita que Claude Code “improvise” sobre tu base de código. Colocar ese archivo en la raíz del repo cambia la relación: el agente deja de adivinar y empieza a obedecer reglas explícitas antes de generar cualquier cambio.

    Claude Code incorpora los CLAUDE.md al contexto inicial de la sesión. Si quieres que el agente respete decisiones de arquitectura, convenciones y restricciones operativas, no hay atajo: ponlas por escrito en un CLAUDE.md que Claude pueda leer. Para entender el diseño técnico del protocolo, revisa la documentación oficial (Anthropic — claude-code) y la página de Claude en Anthropic.

    ¿Qué debe contener un CLAUDE.md?

    Un CLAUDE.md no es un README para humanos ni un changelog. Es un contrato operativo para máquinas. Limítalo a lo esencial que el agente necesita conocer para no romper invariantes del sistema. Divide el archivo en cuatro bloques obligatorios:

    • 1. Stack técnico y decisiones no negociables.
    • 2. Comandos operativos (build, test, lint).
    • 3. Convenciones de código que el linter no puede forzar.
    • 4. Patrones prohibidos y límites de seguridad.

    A continuación, una plantilla mínima que puedes adaptar.

    Plantilla mínima

    ## Stack
- Next.js 14 (App Router). No Pages Router.
- TypeScript (strict: true).
- Tailwind CSS. No CSS Modules ni styled-components.
- Prisma como ORM. No SQL raw salvo migraciones.

## Comandos
- `pnpm dev` — dev server
- `pnpm test` — Jest (coverage >= 80%)
- `pnpm lint` — ESLint (project config)
- `pnpm build` — build prod (sin warnings)

## Convenciones
- Componentes: PascalCase en `/src/components`.
- Hooks: prefijo `use` en `/src/hooks`.
- Errores: usar tipos, no `any`. `catch(e: unknown)` -> narrow.
- No llamadas a APIs desde componentes: usar `/src/services`.

## Patrones prohibidos
- No introducir dependencias sin PR aprobado.
- No usar `useEffect` para sincronización derivada.
- No crear contextos globales nuevos; usar Zustand.

    ¿Dónde colocarlo en monorepos?

    Claude Code respeta jerarquías: lee CLAUDE.md en la raíz y en submódulos relevantes. En monorepos, combina reglas globales con reglas locales:

    • /CLAUDE.md — reglas globales (tooling, CI, linters)
    • /apps/web/CLAUDE.md — reglas específicas del frontend
    • /packages/ui/CLAUDE.md — reglas del diseño compartido

    El agente fusiona las reglas aplicables según el contexto del archivo que edita. Esto te permite mantener consistencia sin replicar todo el contrato en cada paquete.

    Cómo cambia el flujo de trabajo con un CLAUDE.md

    Sin CLAUDE.md, cada sesión de Claude Code es una pizarra limpia: el agente infiere patrones, instala dependencias y propone cambios que “funcionan” pero rompen la coherencia del repo. Con CLAUDE.md:

    • El agente conoce el tooling exacto (ej. pnpm vs npm) y no ejecuta comandos incorrectos.
    • No propone o instala librerías fuera del stack definido.
    • Genera código que cumple las convenciones locales: ubicación de archivos, nombres, patrones de error.
    • Respeta las reglas de seguridad y de auditoría (por ejemplo, rutas que requieren autorización).

    El resultado práctico: menos PRs de corrección, menos reescrituras y menos deuda técnica introducida por el agente.

    Mantenimiento: el contrato debe evolucionar con el código

    Un CLAUDE.md desactualizado es peor que no tenerlo. El agente aplicará reglas obsoletas con tanta disciplina como aplicaría las correctas.

    Reglas simples de mantenimiento:

    • Actualiza CLAUDE.md en el mismo PR que cambia el stack o introduce un patrón nuevo.
    • Versiona las secciones críticas (ej. Stack v2) si el cambio es migratorio.
    • Añade ejemplos de I/O cuando la interacción es ambigua (ej. formatos JSON esperados).
    • No uses el archivo para documentación extensa de negocio; su propósito es técnico y operativo.

    Casos prácticos y límites

    – Si tu agente debe interactuar con la UI (acciones del DOM), documenta los casos en CLAUDE.md pero combina con una especificación de UI semántica (p. ej., WebMCP).
    – No almacenes secretos ni variables de entorno en CLAUDE.md. Usa vaults y referencias a los secretos gestionados por CI/CD.
    – Si tu repositorio permite múltiples stacks (ej. experimentos), usa CLAUDE.md por carpeta para evitar ambigüedades.

    Conclusión

    CLAUDE.md: el contrato entre tú y el agente es una inversión pequeña con retorno inmediato. Poner las reglas por escrito antes de pedirle a Claude Code que haga cambios transforma una relación de adivinanza en una colaboración predecible. Si tu objetivo es integrar agentes de forma práctica y segura, escribir y mantener CLAUDE.md debería ser parte del proceso de desarrollo —actualizado en el mismo PR que cambia tu arquitectura— no una tarea opcional.

    Dominicode Labs

    Para equipos que trabajan con agentes, automatización y flujos de trabajo técnicos, la práctica de formalizar contratos operativos como CLAUDE.md encaja con iniciativas de investigación aplicada. Más recursos y experimentos relacionados están disponibles en Dominicode Labs.

    FAQ

    Respuesta: ¿Qué es un CLAUDE.md y para qué sirve?

    Un CLAUDE.md es un archivo de reglas operativas que define cómo un agente (ej. Claude Code) debe comportarse respecto al repositorio. Sirve para evitar que el agente realice cambios incompatibles o no autorizados.

    Respuesta: ¿Dónde debe ubicarse en un monorepo?

    Colócalo en la raíz del repositorio para reglas globales y en subcarpetas relevantes para reglas locales (por ejemplo, /apps/web/CLAUDE.md). Claude Code combinará las reglas aplicables.

    Respuesta: ¿Qué pasa si no lo actualizo?

    Si está desactualizado, el agente aplicará reglas obsoletas, lo que puede introducir errores o incoherencias. Actualízalo en el mismo PR que modifica el stack o las convenciones.

    Respuesta: ¿Puedo incluir secretos en CLAUDE.md?

    No. No almacenes secretos ni variables de entorno en CLAUDE.md. Usa vaults o referencias gestionadas por CI/CD.

    Respuesta: ¿Cómo integro cambios en el contrato durante una migración del stack?

    Versiona secciones críticas (ej. “Stack v2”) y añade la actualización en el mismo PR que realiza la migración para mantener coherencia entre el código y el contrato.

  • Implementa Spec-First y TDD para asegurar código con Claude Code

    Implementa Spec-First y TDD para asegurar código con Claude Code

    Spec-First + TDD: el combo que hace que Claude Code no rompa nada

    Tiempo estimado de lectura: 4 min

    • Spec-First transforma requisitos en contratos ejecutables que eliminan ambigüedades.
    • TDD convierte esos contratos en tests que fallan primero (Red) y obligan a implementar hasta pasar (Green).
    • El flujo reduce suposiciones del agente, evita happy-paths y deuda técnica silenciosa.
    • Requiere versionar specs y tests junto a la implementación para trazabilidad y control.

    Spec-First + TDD: el combo que hace que Claude Code no rompa nada. Díselo a cualquier equipo que delega implementaciones críticas a un agente y observarás tres problemas: suposiciones, happy-paths y deuda técnica que aparece en silencio. Este patrón invierte el orden habitual: especificación primero, tests que fallan después, implementación solo para pasar tests. Resultado: la IA implementa contra contratos ejecutables, no contra intuiciones.

    Resumen rápido (lectores con prisa)

    Spec-First convierte requisitos en contratos ejecutables. TDD transforma esos contratos en tests rojos que deben pasar. El agente implementa únicamente para lograr que pnpm test devuelva exit code 0. Menos ambigüedad, más trazabilidad, menos regresiones.

    Spec-First + TDD: qué es y por qué lo necesitas con Claude Code

    Claude Code y otros agentes son excelentes generadores de código, pero su entrenamiento los empuja a soluciones “plausibles”, no necesariamente correctas para tu dominio. La solución no es prompts más largos; es cambiar el flujo de trabajo.

    Spec-First + TDD combina:

    • Spec-First: transformar requisitos en un contrato preciso y ejecutable (feature-spec.md).
    • TDD: traducir ese contrato a tests que inicialmente fallan (Red).
    • Implementación: conceder al agente la tarea de alcanzar el verde (Green) ejecutando y corrigiendo hasta que pnpm test devuelva exit code 0.

    Links útiles: Claude Code docs y Vitest para ejemplos de runners.

    Flujo operativo paso a paso

    1) Escribir la especificación (Spec)

    La especificación no es un texto largo: es un contrato. Define funciones, inputs, outputs, errores y reglas inmutables.

    Ejemplo (feature-spec.md):

    Feature: applyDiscount(order, coupon)

Función: applyDiscount(order, coupon)
Inputs:
- order: { id, subtotal, userId, items[] }
- coupon: { code, type: 'percentage'|'fixed', value, minOrder, expiresAt }

Reglas:
- Si coupon.expiresAt < now -> DiscountExpiredError
- Si order.subtotal < coupon.minOrder -> OrderBelowMinimumError
- total = max(0, subtotal - discount)

    Si necesitas respuesta HTTP o formatos JSON exactos, escríbelos. Nada queda implícito.

    2) Generar esqueletos de tests que fallen (Red)

    Pide a Claude que genere solo los tests: archivos Vitest/Jest que describan las aserciones exactas. Estos tests deben fallar inicialmente porque la implementación aún no existe.

    Ejemplo breve (applyDiscount.test.ts):

    import { applyDiscount } from './applyDiscount'
import { DiscountExpiredError } from './errors'

it('lanza DiscountExpiredError si el cupón expiró', () => {
  expect(() => applyDiscount(orderExpired, couponExpired)).toThrow(DiscountExpiredError)
})

    Ejecuta pnpm test localmente o desde el agente. Verás rojo: eso es correcto. Tienes un contrato ejecutable.

    3) Implementación: el agente repara hasta verde

    Autoriza a Claude a escribir el código con una instrucción clara:

    “Implementa applyDiscount() conforme a feature-spec.md. Ejecuta pnpm test y corrige hasta que todos los tests pasen. No modifiques los tests.”

    El agente iterará: escribir, ejecutar, leer errores, corregir. Termina cuando el runner devuelve 0. Esa condición objetiva sustituye la “autovalidación” del modelo.

    Beneficios reales y medibles

    • Trazabilidad: cada cambio está ligado a un test derivado de una especificación humana.
    • Determinismo: el criterio de finalización es el estado del test runner, no el juicio subjetivo del agente.
    • Menos regresiones: CI bloqueará commits que rompan contratos; el agente ya trabaja para pasar esa barrera.
    • Refactor seguro: optimizar sin romper es posible porque la suite revisa invariantes.

    Métricas a monitorear: porcentaje de PRs que pasan en la primera ejecución de CI, número de reverts por errores de negocio, tiempo medio para retomar trabajo en sesiones de agente.

    Cuándo aplicar este combo (y cuándo no)

    Aplica Spec-First + TDD cuando:

    • La lógica tiene invariantes críticas: facturación, pagos, permisos.
    • La feature afecta múltiples consumidores del API.
    • Vas a delegar implementación a sesiones autónomas del agente.

    No lo uses para:

    • Prototipos visuales donde la iteración UX prima.
    • Scripts puntuales o migraciones one-off.
    • Cambios triviales donde crear tests cuesta más que la implementación.

    Buenas prácticas y guardrails

    • Versiona feature-spec.md junto con la PR que implementa la feature.
    • No permitas que el agente modifique tests sin revisión humana.
    • Mantén artefactos pequeños: especificaciones por feature, no documentos gigantes.
    • Incluye en CLAUDE.md la referencia a specs y al contrato de proyecto para que Claude cargue el contexto inicial: esto reduce fricción y errores de interpretación (ver docs).

    Spec-First + TDD no es un ritual: es control. Si quieres que Claude Code deje de ser creativo y empiece a ser fiable, escribe contratos ejecutables primero, exige tests rojos y permite que la IA solo implemente para pasar tests. El resultado no es menos velocidad: es menos correcciones, menos deuda y más confianza en el código que llega a producción.

    Dominicode Labs

    Para equipos que automatizan con agentes y workflows, un laboratorio de pruebas y plantillas de specs acelera la adopción. Consulta Dominicode Labs como continuación lógica para crear artefactos y plantillas reutilizables.

    FAQ

    Respuesta: Spec-First es un contrato ejecutable que define funciones, inputs, outputs y errores de forma precisa. La documentación normal puede ser descriptiva; la spec exige reglas inmutables y formatos exactos que pueden traducirse a tests automatizados.

    Respuesta: Forzar tests rojos crea un criterio objetivo: la implementación debe satisfacer el contrato verificable. Evita que el agente implemente “por intuición” y asegura que el código cumpla casos límites y errores definidos.

    Respuesta: Usa runners como Vitest o Jest para ejecutar tests. Ejecuta pnpm test en CI y localmente para validar que el agente alcanzó exit code 0.

    Respuesta: Políticas de revisión de PR que bloqueen merges si los tests cambian sin aprobación humana y reglas de CI que rechacen cambios en archivos de tests son medidas efectivas. Además, incluye en el proceso de aceptación la verificación de artefactos versionados.

    Respuesta: Hay una inversión inicial: escribir specs y tests. Esa sobrecarga se compensa con menos rework, menos regresiones y mayor velocidad a largo plazo cuando los agentes trabajan contra contratos claros.

    Respuesta: Métricas recomendadas: porcentaje de PRs que pasan en la primera ejecución de CI, número de reverts por errores de negocio y tiempo medio para retomar trabajo en sesiones de agente.

  • Cómo evitar problemas al pedir código a la IA sin especificaciones

    Cómo evitar problemas al pedir código a la IA sin especificaciones

    ¿Quieres velocidad o quieres un desastre bonito en producción?

    Tiempo estimado de lectura: 6 min

    • Ideas clave:
    • Pedir código antes de una spec convierte velocidad aparente en deuda técnica real.
    • La spec funciona como el “system prompt” del repositorio: contratos, reglas y criterios de aceptación evitan improvisaciones.
    • Procesos concretos —plan, contratos, red teaming, tests— transforman las respuestas rápidas de IA en soluciones sostenibles.
    • El rol senior evoluciona hacia guardián de límites y políticas, no solo autor de código.

    Poca gente dice esto en las charlas con café gratis: pedir código antes de dar contexto es como contratar a un pintor y no decirle qué pared. Va a pintar rápido. Va a quedar espectacular al principio. Y al primer olor a humo descubrirás que pintó sobre el sistema eléctrico.

    Resumen rápido (lectores con prisa)

    La IA genera código probables según datos y prompts. Sin una spec que defina objetivos, stack, contratos y criterios de aceptación, las soluciones serán rápidas pero frágiles. Escribe SPEC.md, publica contratos, exige plan y tests; audita con red teaming. Conserva disciplina para convertir velocidad en sostenibilidad.

    Poca gente habla de esto: la IA no entiende tu negocio

    Los modelos de lenguaje son máquinas de probabilidades. No entienden SLAs, ni GDPR, ni las peleas internas por usar Next.js o Svelte. Responden con lo más probable según su entrenamiento y tu prompt. Si no les das reglas, toman decisiones por ti. Decisiones elegantes, pero improvisadas. Y la improvisación no escala.

    Lo que pasa cuando pides código demasiado pronto

    No es teoría. Es patrón repetido en equipos que adoptan IA rápido y disciplina lenta:

    Demo brillante en 48 horas. Integración rota, tokens expuestos, tests que fallan en producción. Dos semanas de refactor para rescatar el proyecto.

    Síntomas concretos

    • Componentes gigantes que hacen todo: UI, llamadas HTTP, validaciones y cambios en la base de datos. Un archivo de 500 líneas que asusta.
    • Mezcla de librerías por impulso: Fetch aquí, Axios allá, una dependencia vieja que “funcionaba” en un tutorial.
    • Flujos automatizados (n8n, Zapier) que fallan ante el primer timeout porque nadie pensó en idempotencia.
    • Tests que existen pero no validan casos reales. O peor: pruebas que pasan porque la spec nunca fue clara.

    Alucinación arquitectónica: la versión elegante del desastre

    No es solo que la IA invente funciones. Inventará abstracciones. Te propondrá un patrón porque en sus datos aparece muchas veces. Puede recomendarte Event Sourcing para una app de encuestas. Te entregará un PR perfecto. Y tú, encantado, lo mergeas.

    Hasta que llega la primera incidencia. Hasta que un miembro nuevo del equipo abre ese PR y no entiende nada. La IA actúa con convicción. Por eso hace falta liderazgo humano que coloque límites.

    La spec: no es burocracia. Es supervivencia

    Quien sigue llamando a la spec “ese PDF que nadie lee” está mirando el problema con los ojos cerrados. En la era de la IA la spec es la única forma de que la creatividad de la herramienta aterrice donde debe.

    Piensa en la spec como el System Prompt del repositorio. No es un texto largo que nadie abre; es la brújula del proyecto. Contiene: objetivos, stack, reglas innegociables, modelos de datos, respuestas ante fallos, y criterios de aceptación.

    Si la IA fuera un barco y tu equipo fuera la tripulación, la spec es la brújula. Sin ella, el barco navega rápido y choca.

    Cómo evitar pedir código demasiado pronto (pasos concretos)

    No es magia. Es disciplina con sentido. Haz esto antes del primer commit generado por IA.

    1) Escribe el objetivo en una frase

    ¿Qué problema resuelve este módulo? ¿Qué NO debe hacer? Si no puedes decirlo en una frase, no lo pidas. La IA no lo adivina.

    2) Define el stack y las reglas innegociables

    Next.js 14 OK. No usar SSR en X páginas. No introducir nueva dependencia sin CVE-check. ¿Postgres o Mongo? ¿Monolito o microservicios? Quítale opciones a la IA para que deje de improvisar.

    3) Publica contratos antes que código

    Interfaces TypeScript, esquemas Prisma, OpenAPI. Si la IA tiene contratos, genera lógica que encaje. Si no los tiene, generará sutilezas que rompen todo.

    4) Exige plan antes de ejecución

    Pide un plan en pasos. Repite: plan. No “hazlo tú ahora”. Pide la lista de entregables, aprobala y luego ejecuta cada paso con prompts acotados.

    5) Red Teaming desde el minuto cero

    Pídele a la IA que sea adversaria: “Rompe este diseño.” “¿Qué falla con 10k req/s?” “¿Qué pasa si el proveedor OAuth cae 30s?” Esto saca a la luz cuellos de botella y casos límite.

    6) Testes y ejemplos junto al contrato

    Cada endpoint debe venir con payloads válidos e inválidos y tests de aceptación. Si la IA genera código sin tests que validen la spec, recházalo.

    7) Guarda la spec en el repo (no en Google Docs)

    SPEC.md, .cursorrules, spec.json. Ponlo en la raíz. Que sea lo primero que lea el agente cuando genere código.

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

    No la copies sin adaptar, pero ten algo así en la raíz del repo:

    • Título en una frase: Objetivo del módulo.
    • Stack aprobado: Next.js 14, Node 20, Postgres 15.
    • Reglas innegociables:
      • No exponer secretos en frontend.
      • Mutaciones por Server Actions.
      • Máximo 2 dependencias nuevas sin revisión de seguridad.
    • Contratos principales:
      • /api/users POST -> CreateUserRequest, CreateUserResponse (interfaces TypeScript)
      • DB: users (id uuid, email text unique, password_hash text)
    • Criterios de aceptación:
      • Test de integración que crea usuario y valida hash.
      • Tiempo máximo respuesta: 500ms en endpoint crítico.
    • Política de secretos: usar Vault, nunca env vars en texto plano.
    • Responsables: Tech Lead: @ana, Owner: @carlos.

    Prompts que funcionan (ejemplos directos)

    Un buen prompt = contexto + restricciones + output esperado.

    Malo: “Hazme un CRUD de users.”

    Bueno: “Te doy la spec (inserta SPEC.md). Genera: 1) Interfaces TS 2) OpenAPI para /api/users 3) Tests de integración con ejemplos válidos/ inválidos. No uses librerías externas para hashing. Tiempo de respuesta <500ms.”

    Divide el trabajo en sprints cortos y verificables

    • Sprint A: Modelo de datos + contratos + tests.
    • Sprint B: Endpoints críticos + seguridad.
    • Sprint C: Observabilidad y despliegue.

    Aprobar cada sprint antes de pasar al siguiente.

    El nuevo rol del Senior: faro y guardián, no solo coder

    Antes bastaba con saber la sintaxis. Hoy el valor está en definir límites, auditar reglas y decidir qué complejidad merece implementarse. El senior no codifica menos; decide mejor. Su trabajo es preguntarse: ¿esta solución respeta la spec? Si no, veto.

    Historias que sirven como espejo

    Junior + Copilot = demo en 48h. Producción = caos. Reescritura 3 semanas.

    Mismo caso con spec: plan en 2 días + Claude para contratos + Copilot para implementación respetando interfaces = demo en 48h. Integración estable. Diferencia: disciplina.

    Metáfora corta y pegadiza

    La spec es el embudo; la IA es la manguera. Sin embudo, el agua corre por todos lados. Con embudo, llega donde debe.

    Cuándo no necesitas spec rígida

    Sí, hay espacio para improvisar. Para generar mocks, para prototipos exploratorios o pequeñas refactors locales. Pero regla práctica: si tocas contratos (APIs, DB, auth, infra), necesitas spec. Punto.

    Checklist rápido antes de pedir código a la IA

    • ¿Existe SPEC.md en la raíz?
    • ¿Hay interfaces/contractos definidos?
    • ¿Hay reglas de seguridad básicas?
    • ¿El prompt pide tests y ejemplos?
    • ¿Se solicitó plan paso a paso y fue aprobado?

    Si respondes no a cualquiera, NO pidas código aún.

    Urgencia real: deuda técnica multiplica costes

    Cada PR aceptado sin spec es una apuesta. Adivina quién paga si pierde la apuesta: tu equipo. La deuda técnica no se desintegra con buenas intenciones. Se compone. Actuar ahora cuesta horas. Rehacer después cuesta semanas, o clientes.

    CTA simple y directo

    Haz esto en los próximos 60 minutos: crea SPEC.md en la raíz con las seis secciones mínimas que te di. Respóndeme con “Quiero la plantilla” y te la mando lista para pegar en tu repo.

    Cierre que no cierra (a propósito)

    Si sigues pensando que la IA es una varita mágica, es tu opción. Tienes otra: gobernarla. La spec es la forma más barata de gobernarla. No es cómoda. Es efectiva. Y esto no acaba aquí: si quieres, te doy la plantilla, un prompt maestro listo para Claude y un .cursorrules de ejemplo. Dime cuál quieres y te lo envío ahora. Tus commits —y tu equipo dentro de seis meses— lo agradecerán.

    Dominicode Labs

    Si trabajas con automatización, agentes o workflows y quieres ejemplos prácticos de especificaciones y .cursorrules, revisa los recursos disponibles en Dominicode Labs. Es una continuación lógica para equipos que buscan convertir experimentos rápidos en procesos repetibles y seguros.

    FAQ

    ¿Qué es una SPEC.md y por qué es necesaria?

    Una SPEC.md es un archivo en la raíz del repositorio que define objetivo, stack, reglas innegociables, contratos y criterios de aceptación. Es necesaria para alinear generación de código automática con las restricciones del negocio y evitar decisiones improvisadas que generen deuda técnica.

    ¿Cuándo puedo pedir código sin spec?

    Para prototipos exploratorios, mocks o pequeños refactors locales. Si el cambio afecta APIs, DB, auth o infra, siempre usar spec. Esa es la regla práctica del artículo.

    ¿Cómo garantizo que la IA respete los contratos?

    Publica interfaces TypeScript, OpenAPI o esquemas en el repo antes de pedir código. Exige tests que validen esos contratos y revisa que las implementaciones pasen los tests de integración definidos en la spec.

    ¿Qué contiene un criterio de aceptación sólido?

    Entradas y salidas esperadas, límites de rendimiento (ej. tiempo máximo 500ms), condiciones de error y tests de integración que validen el comportamiento en casos válidos e inválidos.

    ¿Quién debe ser responsable de la spec?

    Responsables claros: Tech Lead y Product Owner. En el ejemplo: Tech Lead: @ana, Owner: @carlos. Debe estar versionada en el repo y ser lo primero que lea cualquier agente automatizado.

    ¿Cómo auditar seguridad en dependencias sugeridas por IA?

    No introducir nuevas dependencias sin revisión de seguridad: CVE-check, análisis de licencia y una prueba mínima en entorno aislado. La spec puede imponer un máximo de dependencias nuevas sin revisión.

  • Cómo evitar la deuda técnica al integrar agentes de IA en el desarrollo

    Cómo evitar la deuda técnica al integrar agentes de IA en el desarrollo

    ¿Y si la velocidad que te vendieron como progreso es, en realidad, el motor que va a deshacer tu arquitectura?

    Tiempo estimado de lectura: 8 min

    • Ideas clave:
    • Integrar agentes de IA sin capturar intención produce deuda técnica a escala.
    • Necesitas trazar decisiones → requerimiento → test → código y hacerla canónica.
    • Una herramienta como Plum no pinta paredes; convierte intención volátil en artefactos persistentes.
    • Gobernanza debe vivir fuera del agente: hooks, CI y aprobaciones humanas son imprescindibles.

    Introducción

    ¿Y si la velocidad que te vendieron como progreso es, en realidad, el motor que va a deshacer tu arquitectura?

    Poca gente lo dice sin rodeos: integrar agentes de IA para escribir código sin un sistema que capture la intención es una receta perfecta para deuda técnica a escala industrial. Y no hablo de “posibles problemas”. Hablo de que, hoy, el código puede crecer más rápido de lo que cualquier humano puede leer —y eso duele en producción.

    This is her code. This is what she was managing. This is her VS code.

    Margaret Hamilton sujetó esa complejidad con una pila de impresiones. Ella no tenía prompts; tenía procedimientos. Nosotros tenemos prompts y convicciones ingenuas.

    Vamos al punto.

    Resumen rápido (lectores con prisa)

    Plum es una herramienta de gobernanza que intercepta commits, extrae decisiones y las convierte en artefactos trazables. Úsala cuando quieras que las decisiones que toman agentes o developers queden registradas y enlazadas a specs, tests y código. Importa porque previene deuda técnica acelerada por IA y funciona mediante git hooks, diffs, y un flujo de aprobación humana.

    1) El problema (simple y aterrador)

    Si un Product Manager edita una regla en producción, ¿el resto del sistema cambia con ella?

    En la práctica, no.

    Los hotfixes saltan directo al trunk.

    Los tests se rompen en silencio.

    Las specs siguen siendo documentos en Markdown que nadie actualiza.

    Y cuando introduces agentes de IA en ese mix, la cosa se acelera: los LLMs toman micro-decisiones en chats, tú implementas, haces commit y la “intención” se evapora.

    Resultado: código con autoría pero sin porqué. Comportamiento sin contrato. Equipos que arreglan cosas por intuición y no por diseño.

    2) Por qué los tests y specs no bastan

    Un test valida un output. No captura intención.

    Un spec define un contrato —hasta que alguien lo ignora.

    La implementación revela límites: casos borde, problemas de estado, compromisos de rendimiento. La única forma real de enriquecer una spec es escribir el maldito código. Implementar obliga a decidir. Y esas decisiones deben quedar registradas.

    3) ¿Qué hace falta?

    • Capturar decisiones. No dejar que vivan en el chat.
    • Vincular decisión → requerimiento → test → código.
    • Hacer que esa trazabilidad sea canónica y no opcional.

    Sin eso, tus agentes son obreros hiperproductivos que construyen habitaciones sin planos. Velocidad sin planos = casa que se cae.

    4) Plum: la plomada que no pinta paredes

    No es mágica. No genera código bonito.

    Plum hace otra cosa muchísimo más valiosa: transforma intención volátil en artefacto persistente.

    Qué hace Plum (sí, práctico)

    • Intercepta commits via git hooks.
    • Lee diffs y scans de traces de agentes.
    • Extrae decisiones (qué, por qué, quién).
    • Deduplica lógicas repetidas.
    • Te obliga a aprobar/rechazar/editar antes de permitir el commit.
    • Si apruebas, actualiza specs Markdown y genera un .jsonl con la decisión, autoría y trazas.
    • Ejecuta un sync que mapea spec ↔ tests ↔ código y muestra huecos de cobertura.

    Metáfora: la plomada cuelga del trípode y te dice si la pared está vertical. Plum no pinta; evita derrumbes.

    5) Por qué esto no puede ser una “skill” dentro del agente

    Una skill vive dentro del agente. Es una sugerencia.

    Un control de gobernanza tiene que vivir fuera. Debe poder bloquear commits, correr en CI y ser determinista.

    Si la herramienta fuera sólo otra respuesta del LLM, se ignoraría. Punto.

    6) Problemas reales a resolver (y por qué no es trivial)

    • Umbral de interrupción: si cada hotfix genera cinco decisiones para revisar, los devs odian la herramienta. Necesitas tolerancias dinámicas: que el sistema sólo te despierte para decisiones vagas, peligrosas o contradictorias.
    • Dedupe y fuzzy decision ID: identificar decisiones no es binario; es difuso y repo-específico. Necesitamos algoritmos ajustables y feedback humano.
    • Rollbacks automáticos: si rechazas una decisión, el sistema debería revertir el cambio relevante o pedir al agente que rehaga la tarea coherentemente. Hoy eso no está pulido.
    • Spec sharding: las specs crecen. Hay que fragmentarlas en requisitos testables. Un LLM puede ayudar a shardear, pero hay que diseñarlo.
    • Integración de test runners: en la versión actual Plum está acoplado a pytest. Necesitamos soporte agnóstico: conformance tests, runners multi-lenguaje, harnesses de integración.
    • Escalabilidad: en proyectos monolíticos gigantes aún no sabemos si el approach escala. Téstealo en una rama pequeña antes de clonar tu repo legacy.

    7) Cómo se gana valor real (dejando de ser postura)

    • Haz que cada decisión importante deje rastro. No excepciones.
    • Exige aprobación humana para decisiones con impacto.
    • Vuelve la spec viva: que el archivo Markdown no sea un monumento a la intención, sino el contrato vigente.
    • Los tests deben describir intención, no solo outputs. Property tests e invariantes sistémicas son tus nuevos héroes.
    • Si un agente necesita leer 50 archivos para cambiar una función, rehace la arquitectura: modularidad extrema, boundaries claros.

    8) Diseño técnico inteligente (lo que aprendí construyéndolo)

    • Usa git hooks como checkpoint. Si el commit no pasa la validación de decisiones, el commit falla.
    • Mantén un .plumignore para no disparar reviews por cambios triviales (README, docs, etc.).
    • Almacena estado y config en una carpeta oculta (.plum). Versiona el .jsonl.
    • Deduping y parsing de specs: estructura las llamadas LLM con DSPy para hacerlas más deterministas y testables.
    • Router de modelos: no todo exige GPT-costoso. En dedupe puedes usar un modelo OSS rápido. La experiencia del dev gira alrededor de latencia.
    • Diseña la UX: permitir modos (silent, strict, dangerously-approve) para distintos contextos.

    9) Ejemplo mínimo de flujo (para que lo pruebes en 15 minutos)

    • pip install plum-dev
    • cd repo (with specs.md and pytest suite)
    • plum init → apunta a folder de specs y a tests
    • Haz cambios con tu agente y commit
    • Si hay decisiones, git commit fallará y te pedirá revisión
    • Aprobar actualiza spec; reject detona rollback o workflow manual según tu configuración

    10) Umbral y gobernanza: políticas prácticas

    • En sistemas críticos: tolerancia cero. Todo pasa por aprobación humana.
    • En prototipos: modo “agile fast-lane” para no morir de fricción.
    • En equipos mixtos: definir perfiles por carpetas/paquetes. Modules core = strict; UI experimental = lenient.
    • Pipeline: bloquear merges si spec↔tests↔código no están sync. Es duro, sí. Necesario, también.

    11) Cultura y disciplina

    No se automatiza cultura. Se diseña.

    Pide que cada PR incluya:

    • ¿Qué decisión justificó este cambio?
    • ¿Qué requisitos se actualizaron?
    • ¿Qué tests nuevos cubren la decisión?

    Y deja que la herramienta coja esos metadatos y los convierta en .jsonl rastreables.

    12) Lo práctico y lo urgente

    • Si ya usas agentes y no tienes este tipo de control, estás acelerando una deuda técnica que no podrás pagar. No es dramático; es inevitable.
    • Prioridad de adopción:
      • 1. Empezar a capturar traces.
      • 2. Agregar hooks que bloqueen commits sin revisión de intención.
      • 3. Transformar specs en contratos testables.
      • 4. Automatizar sync y coverage mapping.

    13) ¿Qué pasa si no lo haces?

    Velocidad hoy = caos mañana.

    Cuando un bug crítico aparezca a las 2 AM, nadie sabrá por qué la regla se cambió. Commits huérfanos. Blame que no sirve. Migraciones peligrosas. Equipos quemados. Clientes enfadados.

    14) No todo es miedo: oportunidades enormes

    • Auditoría real sobre decisiones: útil para compliance y seguridad.
    • Mejor onboarding: nuevos devs leen el árbol de decisiones para comprender el porqué.
    • Menos discusiones eternas en PRs: si la decisión está bien documentada, la discusión baja y la calidad sube.
    • Productividad con control: velocidad + gobernanza = ventaja competitiva.

    15) Cierre con acción concreta

    Instala la plomada. Prueba en una rama pequeña. No por postureo. Por supervivencia técnica.

    Si quieres:

    • Te mando un template de .jsonl para decisiones.
    • Te paso un flujo de PR que puedes pegar en tu repo.
    • Te doy el checklist para integrar Plum en CI en 15 minutos.

    Respóndeme este mensaje con “Mándame el template” o corre ahora:

    • pip install plum-dev
    • cd tu-repo
    • plum init
    • haz un commit con un agente y observa qué decisiones aparecen.

    Esto no acaba aquí.

    Si no empiezas a capturar intención hoy, tus agentes construirán un legado que nadie querrá mantener mañana. Empieza por un archivo .jsonl. Empieza por una regla dura en tu CI. Haz que la próxima vez que alguien pregunte “¿por qué esto existe?” la respuesta esté en el repo y no en el recuerdo difuso de una conversación vieja.

    ¿Quieres el checklist y el template ahora? Dímelo. Y mientras lo instalas, piensa en esto: velocidad sin plomada es solo una forma elegante de cavar tu propia trampa.

    Para quien está explorando gobernanza de agentes y workflows, una continuación lógica es revisar investigaciones y herramientas de integridad técnica desarrolladas por equipos que experimentan con estos retos. Consulta Dominicode Labs como punto de referencia para materiales y experimentos relacionados con trazabilidad de decisiones y automatización segura.

    FAQ

    ¿Qué es Plum y para qué sirve?

    Plum es una herramienta de gobernanza que intercepta commits, extrae decisiones desde diffs y trazas de agentes, obliga a revisarlas y las convierte en artefactos persistentes (.jsonl) y actualizaciones en specs Markdown. Sirve para capturar intención y vincularla con tests y código.

    ¿Por qué no bastan los tests y las specs?

    Porque un test valida un output y una spec es un contrato que puede quedarse desactualizado. La implementación revela decisiones operacionales que deben quedarse registradas; solo ejecutar y aprobar esos cambios garantiza que la spec refleje intención real.

    ¿Cómo se integra Plum en el flujo de trabajo?

    Plum se integra mediante git hooks que interceptan commits, revisan diffs y traces, y requieren aprobación humana para cambios con decisión. Si se aprueba, Plum actualiza specs y genera el registro .jsonl; si no, puede revertir o pedir una re-ejecución coherente.

    ¿Qué pasa si rechazo una decisión durante el commit?

    Según la configuración, el rechazo puede detonar un rollback automático del cambio relevante o iniciar un workflow manual que pida al agente rehacer la tarea coherentemente. El comportamiento exacto depende de la policy definida.

    ¿Plum afecta la experiencia del desarrollador?

    Sí: introduce una fricción intencional para decisiones relevantes. Para evitar rechazo por exceso de ruido, Plum debe soportar tolerancias dinámicas (modos silent, strict, dangerously-approve) y un .plumignore para cambios triviales.

    ¿Es Plum dependiente de un test runner?

    En su versión inicial Plum está acoplado a pytest, pero el objetivo es soportar runners multi-lenguaje y conformance tests para ser agnóstico respecto al ecosistema de pruebas.

    ¿Cómo empezar con Plum sin romper el equipo?

    Prueba en una rama pequeña, habilita modos lenientes para partes experimentales del repo y aplica tolerancia cero solo en módulos críticos. Empieza por capturar traces y agregar hooks progresivamente.