DOMINICODE

Category: Spec Driven Development

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

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

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

    Tiempo estimado de lectura: 4 min

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

    Introducción

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

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

    Resumen rápido (lectores con prisa)

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

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

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

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

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

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

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

    Tres pilares técnicos imprescindibles

    1) Interfaces generativas (Generative UI)

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

    2) Orquestación y agentic workflows

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

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

    Los modelos son probabilísticos. Implementa:

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

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

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

    Flujo resumido:

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

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

    Obstáculos reales y soluciones prácticas

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

    Recomendaciones concretas para Tech Leads

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

    Lecturas y herramientas útiles

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

    FAQ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • Cómo especificar un agente SDD antes de su implementación

    Cómo especificar un agente SDD antes de su implementación

    SDD + Agentes: cómo especificar un agente antes de construirlo

    Tiempo estimado de lectura: 5 min

    Ideas clave

    • Especificar antes de construir: define flujos de decisión, límites de herramientas y condiciones de parada antes de programar.
    • SDD para agentes ≠ SDD tradicional: los agentes requieren specs que formalicen libertad, herramientas y puntos de escalado humano.
    • Tres bloques críticos: topología de decisión, contratos de herramienta con schemas y guardrails cuantificables.
    • La spec debe ser ejecutable: tests automatizados, simuladores de fallo y verificación en CI/CD.

     

    Introducción

    SDD + Agentes: cómo especificar un agente antes de construirlo — dilo antes de teclear. Si no documentas la caja de arena cognitiva del LLM, lo que construyas será frágil, caro y peligroso. La especificación no es burocracia: es la diferencia entre un experimento que explota y un servicio que vive en producción.

    En las primeras líneas: especificar un agente significa definir flujos de decisión, límites de herramientas y condiciones de parada antes de escribir una sola línea de código. Hazlo así y reduces bucles infinitos, facturas de API descontroladas y escrituras destructivas en tus bases.

    Resumen rápido (lectores con prisa)

    Qué es: Una spec agéntica formaliza topología de decisión, contratos de herramientas y condiciones de parada.

    Cuándo usarla: Antes de implementar agentes que razonan o que pueden tocar recursos críticos.

    Por qué importa: Evita comportamientos estocásticos dañinos, costes inesperados y fallos de integridad de datos.

    Cómo se aplica: Define un patrón operativo único, schemas de entrada/salida para cada tool, y guardrails cuantificables con telemetría y pruebas.

    Por qué SDD para agentes no es lo mismo que SDD tradicional

    En apps CRUD, spec = modelos de datos + endpoints + contratos. Un 404 es un fallo leve. Un agente sin spec puede intentar cien variaciones de la misma consulta SQL, escribir datos corruptos o invocar herramientas fuera de scope. Aquí falla la arquitectura, no el prompt.

    Los agentes razonan de forma estocástica. Por eso la spec debe formalizar:

    • Qué libertad tiene el agente en cada punto.
    • Qué herramientas puede tocar y cómo.
    • Cuándo debe pararse y llamar a un humano.

    Anthropic recomienda priorizar flujos orquestados sobre autonomía total para casos críticos (ver: Anthropic — Building effective agents). Toma nota: la industria no apuesta por “agentes libres” en producción sin guardrails.

    Tres bloques que debe cubrir tu spec agéntica

    1) Flujos de decisión: topología y patrón operativo

    Decide uno (y solo uno) de estos patrones por caso de uso:

    • Enrutamiento semántico: el LLM clasifica intenciones y delega a código determinista.
    • Máquina de estados orquestada: el LLM elige transiciones entre nodos predefinidos (n8n, LangGraph, XState).
    • Bucle ReAct autónomo: pensamiento-observación-acción libre (solo para experimentos controlados).

    No mezcles sin regla. Define explícitamente qué patrón rige cada intent/endpoint y por qué.

    2) Límites de herramientas (Tool Boundaries)

    Una herramienta para un agente no es un endpoint cualquiera. Tu spec de herramienta debe incluir, al menos:

    • Contrato de datos (Zod o JSON Schema). No aceptes “any”.
    • Descripciones semánticas por campo: guía al LLM sobre qué producir exactamente.
    • Precondiciones de uso: cuándo está permitido invocar la tool.
    • Protocolo de fallo: ¿autocorrección (con el error serializado), retry con backoff, usar valor por defecto o abortar y escalar?

    Ejemplo mínimo (JSON Schema + fallback):

    {
  "name": "createUser",
  "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": ["email"] },
  "description": "Crea un usuario. email debe ser un correo válido. No inferir dominios.",
  "precondition": "email provisto por usuario",
  "onError": { "strategy": "abort_and_escalate", "max_retries": 0 }
}

    Si dejas el onError en blanco, el agente decidirá por su cuenta —y lo hará mal.

    3) Guardrails y condiciones de parada

    Los guardrails no son sugerencias; son límites numéricos y verificables:

    • Max Steps: 5–10 iteraciones razonables por sesión antes de forzar cierre.
    • Retries por herramienta: típicamente 1–3, con backoff y registro.
    • Presupuesto operativo: tokens máximos por ejecución y tiempo máximo (p. ej. 30s wall clock).
    • Reglas de escalado humano: por ejemplo, tres fallos consecutivos de la misma tool o confianza del modelo < 0.6 → escalar.

    Documenta esos números en la spec. Implanta telemetría que lo verifique en tiempo real.

    Ingeniería práctica: plantilla rápida para tu spec agéntica

    Un documento mínimo y accionable debe contener:

    1. Directiva principal (system prompt base, objetivo inmutable).
    2. Fronteras negativas (anti-prompts: qué nunca debe hacer el agente).
    3. Contrato de memoria (qué guarda la memoria episódica y qué va a la semántica, p. ej. pgvector).
    4. Matriz de herramientas (schema, descripciones, precondiciones, fallback).
    5. Criterios de interrupción y política de escalado humano.
    6. Tests de comportamiento (simulaciones de fallo: error DB, timeout API, input malicioso).

    Incluye URLs en la spec para APIs críticas, contratos de datos y documentación de seguridad. Un equipo debe poder reproducir el flujo completo sin leer código.

    Trade‑offs y decisiones reales

    – Ventana de contexto gigante vs memoria estructurada: ventajas teóricas hay, pero en producción la memoria estructurada gana por latencia, coste y precisión (ver problema “lost in the middle”: arXiv:2307.03172).

    – Autonomía vs auditabilidad: cuanto más autónomo, menos auditable. Para negocios, prioriza auditabilidad.

    – Retry agresivo vs abort + humano: lo primero puede romper tu DB; lo segundo ralentiza workflows pero salva integridad.

    Cierre operativo: de la spec al CI/CD

    La spec no es un PDF muerto. Debe formar parte del pipeline:

    • Tests automatizados que validen precondiciones y fallbacks.
    • Simuladores que reproduzcan errores de herramientas.
    • Guardrails chequeados en staging y alertas de telemetría en producción.

    Si tu spec no se puede testear automáticamente, no es spec: es promesa. Y las promesas no pagan facturas.

    Define la caja de arena antes de soltar los músculos del agente. Es la única manera de que tus agentes actúen con intención, no con catástrofe.

    Dominicode Labs

    Para equipos que implementan pipelines y simuladores de fallo como parte de la spec, una referencia práctica y recursos complementarios están disponibles en Dominicode Labs. Considéralo como un recurso adicional para integrar tests y telemetría en tu CI/CD.

     

    FAQ

    ¿Por qué no vale con un buen prompt para controlar un agente?

    Un prompt no formaliza contratos ni límites verificables. Los agentes razonan de forma estocástica; sin schemas, precondiciones y guardrails numéricos, el prompt será frágil frente a inputs inesperados.

    ¿Qué es un contrato de herramienta y por qué usar JSON Schema?

    Un contrato de herramienta define tipos, formatos y campos requeridos. JSON Schema o Zod son formalismos que permiten validar entradas/salidas de forma determinista y evitar “any” que produzca comportamiento impredecible.

    ¿Cuántas iteraciones (Max Steps) son razonables?

    La guía práctica sugiere entre 5 y 10 iteraciones por sesión antes de forzar cierre. Ese rango reduce bucles infinitos y consumo excesivo de recursos.

    ¿Cómo debo manejar fallos recurrentes de una herramienta?

    Define un protocolo de fallo en la spec: retries limitados con backoff, registro y una estrategia de escalado (por ejemplo, abort_and_escalate tras N retries). No dejes el comportamiento en blanco.

    ¿Qué pruebas automatizadas son mínimas para una spec agéntica?

    Al menos: validación de precondiciones, simuladores de fallo de tools (DB error, timeout), y tests que verifiquen que los guardrails se activan (Max Steps, budget, retries).

    ¿Dónde documentar la política de escalado humano?

    La política de escalado debe estar en la spec principal, con reglas verificables (ej. tres fallos consecutivos de la misma tool o confianza < 0.6 → escalado) y enlaces a contactos/runbooks en tu repositorio de operaciones.

  • Cómo utilizar OpenSpec para gestionar especificaciones en Brownfield

    Cómo utilizar OpenSpec para gestionar especificaciones en Brownfield

    ¿Es OpenSpec la herramienta para las specs en Brownfield?

    Tiempo estimado de lectura: Calculando con ~220 palabras por minuto.

    Tiempo estimado de lectura: 3 min

    • OpenSpec acelera la obtención de una spec base desde comportamiento observable.
    • Su valor real aparece al combinar generación automática con revisión humana y guardrails en CI/CD.
    • No es una solución mágica: puede cristalizar deuda si se usa sin enriquecimiento semántico.
    • Proceso recomendado: discovery → human-in-the-loop → guardrails → evolución controlada.

    Introducción

    ¿Es OpenSpec la herramienta para las specs en Brownfield? Sí —pero no como solución mágica. OpenSpec (entendido como el ecosistema de herramientas que generan y mantienen OpenAPI/AsyncAPI automáticamente) es el punto de partida más práctico para recuperar contratos en sistemas heredados. Su valor real aparece cuando lo combinas con juicio humano, revisión semántica y guardrails en CI/CD.

    Resumen rápido (lectores con prisa)

    OpenSpec: conjunto de herramientas que generan especificaciones (OpenAPI/AsyncAPI) automáticamente desde tráfico o análisis estático. Útil para Brownfield cuando se usa como extractor inicial, no como fuente final sin revisión. Importante integrarlo con revisión humana y validaciones en pipelines.

    ¿Es OpenSpec la herramienta para las specs en Brownfield? — contexto y por qué importa

    Problema en Brownfield

    En Brownfield tienes código en producción, dependencias cruzadas y documentación que normalmente no refleja la realidad. El problema no es generar YAML: es detener el sangrado de cambios no esperados en producción. Aquí OpenSpec aporta dos cosas fundamentales:

    Qué aporta OpenSpec

    • Rapidez para obtener una línea base estructural a partir del comportamiento real del sistema.
    • Mecanismos para convertir una spec en infraestructura (drift detection, validación en pipelines).

    Herramientas de referencia: Optic, Akita, Specmatic. Para extracción desde código: Springdoc, tsoa. Consulta la especificación OpenAPI.

    Qué puede y qué no puede hacer OpenSpec en un Brownfield

    Lo que sí hace bien

    • Extrae la estructura observable de endpoints, métodos y esquemas de payloads.
    • Produce specs rápidamente desde tráfico en staging o desde análisis estático.
    • Habilita detección de deriva en CI: bloquea merges que cambian respuestas esperadas.

    Lo que no hace

    • No captura semántica de negocio: no sabe que status: 2 significa “Cuenta suspendida”.
    • No documenta edge cases que no aparecieron en el tráfico observado.
    • No corrige malos diseños: puede cristalizar inconsistencias si aceptas la spec sin filtrar.

    Si tratas la generación automática como la verdad absoluta, produces un contrato falso-seguro. Si la usas como un extractor inicial, reduces semanas de trabajo manual a horas.

    Estrategia práctica para implantar OpenSpec en Brownfield

    Implementarlo sin generar más deuda exige disciplina. Siguientes pasos probados en equipos técnicos:

    1. Generación de baseline (Discovery)

    • Captura tráfico en staging o usa análisis estático según el stack.
    • Herramientas: Optic para captura/visualización, Akita para inferencia basada en tráfico, Springdoc/tsoa para extracción desde código.
    • Objetivo: obtener un OpenAPI.yaml que represente el comportamiento observado, no la versión final.

    2. Enriquecimiento semántico (Human-in-the-loop)

    • Asigna a domain owners para revisar y documentar campos críticos, códigos de estado y reglas de negocio.
    • Corrige nombres ambiguos y elimina endpoints internos expuestos por accidente.
    • Añade ejemplos y descripciones para cada campo sensible.

    3. Control automático (Guardrails)

    • Integra la spec en CI: Specmatic u Optic pueden ejecutar contract tests o comparar contratos en PR.
    • Fallo en la spec = bloqueo del merge hasta revisión explícita.
    • Mantén logs de cambios automáticos y un proceso claro para aprobar modificaciones del contrato.

    4. Evolución controlada

    • No distribuyas la spec al consumidor externo hasta que se haya ratificado por el equipo.
    • Versiona la spec y comunica breaking changes con políticas (semver, fechas, deprecations).

    Ejemplo real y conciso

    Situación: monolito en Node que sirve APIs REST sin spec.

    • Paso 1: Instrumenta un proxy de captura en staging con Optic. Ejecuta suites de integración para generar tráfico representativo.
    • Paso 2: Optic genera un OpenAPI básico. Equipo revisa y detecta 3 endpoints con campos inconsistentes.
    • Paso 3: Ajustes manuales, se añaden descripciones de status y se documentan errores 422 y 503 que no aparecieron en tráfico.
    • Paso 4: Integra Specmatic en CI para validar que cambios en PR no alteren respuestas esperadas sin aprobación.

    Resultado: en semanas tienes una spec utilizable y protección automática contra cambios no controlados.

    Riesgos y mitigaciones operativas

    • Riesgo: cristalizar deuda técnica. Mitigación: obligar enriquecimiento semántico antes de promover spec a “source of truth”.
    • Riesgo: cobertura incompleta por tráfico insuficiente. Mitigación: complementar capture con tests orientados a edge cases y análisis estático.
    • Riesgo: falsa confianza en herramientas. Mitigación: auditorías periódicas de la spec por arquitectos y product owners.

    Conclusión — criterio técnico

    OpenSpec es la herramienta indicada para arrancar specs en Brownfield. No reemplaza la discusión humana sobre contratos ni el trabajo de diseño del dominio. Su fuerza está en reducir trabajo mecánico y convertir documentación en infraestructura verificable. Si tu equipo integra generación automática con revisión semántica y guardrails en CI, OpenSpec deja de ser una “herramienta” y pasa a ser una palanca que reduce riesgo y acelera refactors con seguridad.

    Para equipos que trabajan con automatización de workflows, captura de tráfico e integración CI, puede interesar explorar más recursos y experimentos en Dominicode Labs. Es una referencia complementaria para prototipos y pruebas de integración de herramientas OpenSpec en pipelines.

    FAQ

  • Cómo construir un subagente en Claude Code para revisión de PRs

    Cómo construir un subagente en Claude Code para revisión de PRs

    Cómo construir tu primer subagente en Claude Code — Tutorial paso a paso con un caso útil: por ejemplo, un agente revisor de PRs o generador de tests

    Tiempo estimado de lectura: 4 min

    • Patrón práctico: contexto acotado + reglas estrictas + output accionable para integrar IA en pipelines.
    • Dos casos: revisor de PRs (diff) y generador de tests (por archivo).
    • Implementación: scripts CLI que usan Claude Code, prompts versionados y hooks/CI para automatizar.
    • Precauciones: controlar tokens, contexto parcial y mantener revisión humana para decisiones críticas.
    Entender cómo construir tu primer subagente en Claude Code — Tutorial paso a paso con un caso útil: por ejemplo, un agente revisor de PRs o generador de tests, es el salto práctico entre usar IA como chat y convertirla en un componente automatizado de tu pipeline de desarrollo. Aquí tienes un tutorial accionable, sin humo: código, prompts y reglas para que funcione de verdad.

    Resumen rápido (lectores con prisa)

    Un subagente es un script que envía contexto limitado (diff o archivo) a Claude Code con un prompt versionado. Úsalo cuando la tarea sea repetitiva y pueda expresarse con reglas claras. La clave: reducir contexto, reglas estrictas y automatizar en hooks/CI.

    Cómo construir tu primer subagente en Claude Code — paso a paso

    Requisitos mínimos

    • Node.js y npm.
    • Cuenta y credenciales de Anthropic (Claude Code).
    • Repositorio Git con cambios en una rama distinta a main.

    Instalación rápida

    Instala la CLI de Claude Code y autentica:

    npm install -g @anthropic-ai/claude-code
claude auth

    (Referencia: npm package @anthropic-ai/claude-code)

    1. Define el System Prompt (qué puede y qué no puede hacer)

    El System Prompt es la barrera entre ruido y valor. Guarda uno en la raíz: .claude-reviewer-prompt.md.

    Contenido recomendado:

    Eres un Staff Engineer realizando una revisión de código.
Recibirás un `git diff`. Tu objetivo es identificar problemas críticos.

Reglas:
1. Ignora formato y estilo (linters ya hacen eso).
2. Busca: vulnerabilidades, condiciones de carrera, mutaciones de estado no controladas y complejidad innecesaria.
3. Si hay nueva lógica sin tests, marca "Missing Tests" como error crítico.
4. Responde en Markdown. Si todo está correcto, responde solo: "✅ Código limpio. Listo para PR."

    Sé explícito: lo que no está en las reglas, está fuera del subagente.

    2. Script que orquesta el subagente (claude-pr-review.sh)

    Extrae el diff y pásalo al modelo. Crea /scripts/claude-pr-review.sh:

    #!/bin/bash
DIFF=$(git diff main...HEAD -- ':!**/package-lock.json' ':!**/dist/**')

if [ -z "$DIFF" ]; then
  echo "No hay cambios para revisar."
  exit 0
fi

PROMPT=$(cat .claude-reviewer-prompt.md)

claude --print --prompt "$PROMPT

Aquí tienes el diff:
\`\`\`diff
$DIFF
\`\`\`"

    Notas:

    • Excluye archivos generados para ahorrar tokens (-- ':!path').
    • claude --print muestra la respuesta en terminal; puedes redirigirla a un archivo.

    3. Variante: generador de tests por archivo

    Mismo patrón, distinto input. Crea /scripts/claude-gen-tests.sh:

    #!/bin/bash
FILE_PATH=$1
if [ ! -f "$FILE_PATH" ]; then
  echo "Archivo no encontrado: $FILE_PATH"
  exit 1
fi

claude --print --prompt "Actúa como SDET especializado en TypeScript.
Genera tests unitarios con Jest para el siguiente archivo. Usa mocking donde aplique. Devuelve solo el código del test.

Archivo:
$(cat $FILE_PATH)" > "${FILE_PATH%.*}.test.ts"

    El resultado es un punto de partida. No lo aceptes ciegamente: revisa los mocks y aserciones.

    4. Integración práctica: Hooks y CI

    Un script manual se olvida. Integra el revisor en un hook pre-push (Husky) o como job en CI.

    Ejemplo Husky (.husky/pre-push):

    #!/bin/sh
./scripts/claude-pr-review.sh || exit 1

    Si detecta un problema crítico, el script puede devolver exit 1 y bloquear el push.

    En CI, ejecuta el script y falla el job si el output contiene palabras clave (ej. “Missing Tests” o “Error crítico”).

    5. Limitaciones y buenas prácticas

    • Coste de tokens: pasar un diff enorme puede ser caro. Filtra archivos irrelevantes. Regla práctica: apunta a menos de ~20k tokens por invocación.
    • Contexto parcial: el subagente solo ve lo que le das (diff o archivo). Los falsos positivos aparecen cuando la lógica depende de archivos no incluidos.
    • No es reemplazo de humanos: automatiza lo repetitivo; deja decisiones arquitectónicas a desarrolladores senior.
    • Versiona prompts y scripts: audítalos como cualquier herramienta crítica.

    6. Decisión rápida: cuándo usar un subagente local

    Usa subagentes locales si:

    • La tarea es repetitiva y repite reglas claras (seguridad simple, checklists de arquitectura).
    • Tienes un disparador claro (push, PR, commit).
    • Puedes limitar el contexto para controlar coste y precisión.

    Evítalos cuando:

    • Requieres análisis de arquitectura completa de un monorepo.
    • Necesitas pruebas end-to-end dependientes de infra externa.

    Conclusión (y lo que sigue)

    El patrón es simple y poderoso: reduce ruido dando contexto acotado y reglas firmes. Implementa el revisor y el generador de tests como base, obsérvalos un par de semanas, afina el prompt y automatiza su ejecución en hooks o CI. Esto no acaba aquí: un subagente bien definido se convierte en una pieza de infraestructura que reduce fricción y libera criterio humano para lo que realmente importa.

    Dominicode Labs

    Para equipos que investigan automatización y agentes en pipelines, puede ser útil explorar recursos y experimentos adicionales en Dominicode Labs. Considera esto como una continuación lógica para prototipar y versionar subagentes en un entorno experimental controlado.

    FAQ

    ¿Qué es un subagente en este contexto?

    Un subagente es un componente automatizado que envía contexto específico (por ejemplo, un git diff o el contenido de un archivo) a un modelo (Claude Code) junto con un prompt versionado y reglas, para producir output accionable usado en pipelines de desarrollo.

    ¿Cómo protejo credenciales y datos sensibles?

    Almacena credenciales en entornos seguros (secrets en CI, variables de entorno en el sistema) y evita pasar archivos que contengan secretos en los diffs enviados al modelo. Versiona prompts pero no incluyas secretos en ellos.

    ¿Cuándo el subagente debe fallar un push?

    Haz que falle cuando detecte errores críticos claramente definidos en el prompt (por ejemplo, “Missing Tests” o “Error crítico”). Mantén una lista pequeña y precisa de condiciones que realmente justifiquen bloquear un push.

    ¿Cómo controlo el coste de tokens?

    Filtra archivos irrelevantes, limita el tamaño del diff y prioriza invocaciones por carpeta o por cambios significativos. Regla práctica: apunta a menos de ~20k tokens por invocación.

    ¿Puedo usar otros modelos o proveedores?

    Sí. El patrón (contexto acotado + reglas estrictas + output accionable) es agnóstico al proveedor. Ajusta comandos y prompts según la API/CLI del proveedor seleccionado.

    ¿Cómo versiono y audito prompts?

    Guarda prompts en el repositorio (por ejemplo, .claude-reviewer-prompt.md) y trata los cambios como código: revisiones, PRs y registro de cambios. Audítalos como cualquier herramienta crítica operativa.

  • Cómo implementar TDD y Spec-First para mejorar el uso de IA en desarrollo

    Cómo implementar TDD y Spec-First para mejorar el uso de IA en desarrollo

    TDD + Spec-First: el combo que cambia cómo trabajas con IA

    Tiempo estimado de lectura: 5 min

    • Ideas clave:
    • Spec-First define contratos claros (tipos, OpenAPI, GraphQL) antes de implementar.
    • TDD convierte esos contratos en especificaciones ejecutables: tests rojos → implementación → tests verdes.
    • Con LLMs, contrato + tests limitan alucinaciones y convierten a la IA en colaborador predecible.
    • Práctica: versiona specs, entrega solo interfaz + test al modelo, ejecuta CI y refactoriza con seguridad.

    TDD + Spec-First: el combo que cambia cómo trabajas con IA no es una moda. Es la forma práctica de convertir asistentes de código (Cursor, Copilot, Claude, etc.) en colaboradores fiables en lugar de generadores caóticos. Si quieres que la IA entregue código mantenible y predecible, primero le pones un contrato; después, le pones pruebas.

    Resumen rápido (lectores con prisa)

    Spec-First: define el contrato (types/OpenAPI/GraphQL) antes de implementar. TDD: escribe tests que describen comportamiento antes de la lógica. Juntos: contrato define el “qué”, los tests el “cuándo” y la IA queda confinada al “cómo”.

    TDD + Spec-First: el combo que cambia cómo trabajas con IA — qué es y por qué importa

    Qué es Spec-First

    Spec-First significa diseñar el contrato antes de implementar: tipos TypeScript, OpenAPI/Swagger o un esquema GraphQL (GraphQL). Definir la interfaz y errores esperados aclara responsabilidades y límites.

    Qué es TDD

    TDD (Test-Driven Development) obliga a escribir pruebas que expresen comportamiento antes de cualquier línea de lógica. Los tests actúan como una especificación ejecutable que guía la implementación y protege el diseño frente a regresiones.

    Flujo práctico: cómo aplicarlo día a día

    1) Define el contrato (Spec-First)

    • Escribe interfaces o un OpenAPI minimal.
    • Versiona ese archivo en el repo.
    • Hazlo lo más explícito posible: tipos, errores esperados, límites de paginación.

    Por qué? Cambiar una especificación es barato; cambiar la implementación ya entregada cuesta tiempo y bugs.

    2) Escribe los tests antes (Red)

    • Genera tests unitarios que describan casos reales: éxito, validaciones y fallos (timeouts, errores de red).
    • Usa frameworks previstos: Jest, pytest, etc.
    • Aísla dependencias con mocks para que el test sea una especificación ejecutable del comportamiento.

    3) Implementa con la IA (Green)

    • Entrega a la IA solo la interfaz y el test fallido. Nada de documentación amplia ni contexto innecesario.
    • Pide explícitamente: “Implementa X para que pase estos tests. No añadas métodos públicos que no estén en la interfaz.”
    • Ejecuta los tests; si fallan, pega el error en el prompt y haz que la IA itere.

    4) Refactoriza y repite (Refactor)

    Con tests en verde, pide mejoras estructurales (limpieza, reducción de complejidad) y deja que los tests validen que no hay regresiones.

    Ejemplo rápido (esquema)

    – Spec-First: IUserService { getById(id): Promise | throws NotFound }
    – Tests (Jest): caso exitoso, user no existe, DB timeout.
    – Implementación: la IA crea UserService respetando la interfaz; los tests pasan.

    Ese flujo evita que la IA invente un método “findUserOrCreate()” si no estaba en la spec.

    Ventajas reales en equipos técnicos

    • Arquitectura consistente: los tech leads definen límites arquitectónicos, la IA implementa sin salirse de ellos.
    • Documentación viva: specs + tests = documentación ejecutable.
    • Escalabilidad del trabajo: developers junior pueden entregar valor siguiendo contratos y tests claros.
    • Refactor seguro: la suite de tests permite que la IA haga cambios con garantía.

    Riesgos y cómo mitigarlos

    1. Tests tautológicos

    Riesgo: si la IA escribe spec, tests e implementación, todo estará autoconsistente pero puede no cubrir requerimientos reales.

    Mitigación: la spec inicial la define un humano con conocimiento del dominio. Revisa y aprueba los tests generados.

    2. Overfitting en tests

    Riesgo: tests que verifican la implementación concreta y no el comportamiento observable.

    Mitigación: escribe tests orientados a contratos (inputs/outputs/efectos observables), no a estructuras internas.

    3. Explosion de tests irrelevantes

    Riesgo: la IA puede generar multitud de casos triviales que aumenten la carga de mantenimiento.

    Mitigación: prioriza tests del Core Domain; define criterios claros de cobertura (p. ej. casos críticos y límites).

    Integración práctica y mejores prácticas

    • Prompts minimalistas y restrictivos: entrega solo interface + test. Menos contexto = menos alucinaciones.
    • Versiona prompts y ejemplos de tests en el repo para auditar cambios.
    • CI como guardián: exige que todos los PRs pasen la suite antes de merge.
    • Métricas: trackea flakiness de tests y tiempo medio hasta tests verdes cuando la IA implementa; son indicadores de calidad del flujo.

    Recursos y lectura recomendada

    Spec-First + TDD no es una camisa de fuerza; es un marco que transforma a la IA en una herramienta que ejecuta diseño, no que lo inventa. Si quieres resultados reproducibles y menos deuda técnica, deja de pedir “escribe esto” y comienza a exigir contratos y pruebas. El resto viene solo.

     

    FAQ

     

    ¿Por qué empezar por la spec en lugar de por el código?

    Porque la spec define límites y responsabilidades antes de que alguien implemente. Cambiar una spec es más barato y menos propenso a introducir bugs que ajustar implementaciones ya en producción.

    ¿Qué pruebas debería escribir primero?

    Empieza por casos críticos: caminos felices, validaciones y fallos esperados (timeouts, errores de red). Prioriza comportamiento observable sobre detalles de implementación.

    ¿Cómo evitar que la IA genere funciones fuera de la interfaz?

    Entrega al modelo sólo la interfaz y el test fallido; pide explícitamente que no añada métodos públicos que no estén en la spec. Usa revisión humana y CI para bloquear cambios no autorizados.

    ¿Qué frameworks de tests son recomendables?

    Depende del stack: Jest para JavaScript/TypeScript, pytest para Python, y frameworks nativos para otros lenguajes. Lo importante es que permitan mocks y pruebas aisladas.

    ¿Cómo integrar esto en CI?

    Configura la pipeline para ejecutar la suite completa en cada PR. Rechaza merges si hay tests fallidos. Versiona specs y prompts en el repo para auditar cambios.

    ¿Qué métricas debo trackear?

    Trackea flakiness de tests, tiempo medio hasta tests verdes cuando la IA implementa, y número de PRs que requieren intervención humana. Esos indicadores reflejan calidad y estabilidad del flujo.

  • 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

    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.

    Respuesta

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

    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.

    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.

    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.

    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.

  • 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

     

    Respuesta: 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.

    Respuesta: 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.

    Respuesta: 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.

    Respuesta: 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.

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

    Respuesta: 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.

  • Automatización de la Revisión de Código con IA en 2026

    Automatización de la Revisión de Código con IA en 2026

    Revisión de código con IA y validación automatizada de especificaciones (2026)

    Tiempo estimado de lectura: 4 min

    • Automatizar validaciones contra especificaciones convierte las specs en guardrails operativos, no en mera documentación.
    • Pipeline agentico: inyección de contexto (RAG), validación determinista en entornos aislados y bucle agentico con autocorrección controlada.
    • Riesgos reales: especificaciones ausentes/contradictorias, sesgo de automatización, límites de contexto y responsabilidades legales.
    • Checklist operativo para Tech Leads: versionar OpenAPI/ADRs, cobertura de tests, modularidad y políticas de autocorrección.

    La revisión de código con IA y validación automatizada de especificaciones (2026) ya no es un experimento: es una capa que muchos equipos productivos están integrando en sus pipelines. Escribir código dejó de ser el cuello de botella; ahora lo es verificar que ese código cumpla contratos, reglas de negocio y decisiones arquitectónicas. Este artículo explica cómo funciona hoy la automatización, qué riesgos reales merece tu atención y qué pasos prácticos debe ejecutar un Tech Lead antes de activar agentes en CI.

    Resumen rápido (lectores con prisa)

    La automatización combina RAG para extraer contexto del repo, entornos efímeros para ejecutar tests y validaciones deterministas contra OpenAPI/AsyncAPI. Se puede permitir autocorrección en cambios triviales y bloquear cambios de diseño para revisión humana. Requiere especificaciones versionadas, cobertura de tests y modularidad.

    Revisión de código con IA y validación automatizada de especificaciones: cómo funciona hoy

    El salto respecto a herramientas tradicionales (SonarQube, Semgrep) es que los agentes modernos cruzan el diff del PR con documentación estructurada y ejecutan validaciones deterministas:

    • Capturan contexto del repositorio (ADRs, OpenAPI, tests y convenciones).
    • Vectorizan y recuperan fragmentos relevantes vía RAG (retrieval‑augmented generation).
    • Levantan entornos efímeros para ejecutar tests y comprobar contratos OpenAPI/AsyncAPI.
    • Pueden proponer o aplicar parches automáticos y re‑ejecutar la suite antes de notificar al revisor humano.

    Herramientas y referencias relevantes

    El resultado: PRs más rápidos, menos fricción y menos errores de contrato que escapan a producción —siempre que el sistema esté bien montado.

    Arquitectura práctica: pipeline agentico y validación de especificaciones

    Implementarlo con seguridad implica estructurar el pipeline en tres bloques:

    1. Inyección de contexto (RAG para repositorios)

    • Indexa ADRs, OpenAPI, README, tests y convenciones del repo en un vector store (p. ej. Pinecone).
    • Cuando abre un PR, extrae el contexto específico del área afectada para construir prompts y reglas de validación.

    2. Validación determinista en entorno aislado

    • Levanta un contenedor efímero con la rama del PR.
    • Ejecuta tests unitarios, contract tests (Specmatic/Optic) y llamadas end‑to‑end contra la API.
    • Compara respuestas reales con la especificación OpenAPI versionada.

    3. Agentic loop (autocorrección controlada)

    • Si hay desviaciones menores (tipos, campos faltantes), el agente genera un parche y abre un commit automático.
    • Re‑ejecuta tests; si todo pasa, marca la verificación como “verde” y agrega una nota en el PR.
    • Las acciones que implican diseño (breaking changes, cambios semánticos) quedan bloqueadas para revisión humana.

    Este flujo convierte la spec en guardrail operativo, no en mera documentación.

    Límites reales y riesgos que no puedes ignorar

    • Especificaciones inexistentes o contradictorias: la IA solo puede validar lo que está formalizado. En Brownfield, primero escribe specs consumibles por máquinas.
    • Ventana de contexto: los modelos actuales pierden precisión al razonar sobre cambios transversales en monolitos enormes; la modularidad importa.
    • Automation bias: equipos que confían ciegamente en un “check verde” aceleran fallos operativos. El humano sigue siendo responsable.
    • Seguridad y liability: un agente puede aprobar un PR que introduce vulnerabilidad lógica; la responsabilidad legal recae en la organización.

    Checklist operativo para Tech Leads antes de activar agentes

    1. Mantén OpenAPI/AsyncAPI actualizados y versionados en el repo (source of truth).
    2. Versiona ADRs junto al código y define reglas claras en CONVENTIONS.md o .repo_rules.
    3. Asegura cobertura de tests: unitarios, contract tests (Specmatic/Optic) y un set mínimo de E2E para paths críticos.
    4. Modulariza dominios (DDD, bounded contexts) para acotar la precisión del agente.
    5. Implementa un entorno de staging efímero en CI donde el agente pueda ejecutar validaciones reales.
    6. Define políticas claras de autocorrección: qué puede commitear automáticamente y qué queda bloqueado.
    7. Añade auditoría y logging: cada parche automático debe tener trazabilidad y motivación textual.

    Cómo medir si te funciona

    Métricas accionables:

    • Reducción del tiempo medio de revisión (MTTR para PRs).
    • Porcentaje de PRs con fallos de contrato detectados en CI vs. en producción.
    • Número de commits automáticos revertidos por humanos (indicador de sobre‑autonomía).
    • Tiempo que el equipo destina a revisiones de criterio vs. a correcciones triviales.

    Conclusión técnica

    La revisión de código con IA y validación automatizada de especificaciones en 2026 es una palanca real: acelera ciclos y reduce errores de contrato si y solo si la organización invierte antes en especificación, tests y modularidad. Sin ese trabajo previo, la IA añade ruido y riesgo. Haz la inversión estructural primero; luego deja que los agentes hagan lo repetible. Así, tus ingenieros podrán dedicar su juicio a lo que realmente importa: arquitectura, impacto en el negocio y diseño de largo plazo.

    Para equipos que exploran flujos de automatización y agentes dentro de pipelines, una continuación natural de este trabajo es revisar proyectos y experimentos en Dominicode Labs, donde se documentan plantillas y patrones aplicables a pipelines agenticos.

    FAQ

    ¿Qué tipo de especificaciones debo versionar en el repo?

    Versiona OpenAPI/AsyncAPI como source of truth y mantén ADRs alineados con el código. Estas especificaciones deben ser consumibles por máquinas y estar en la misma rama o en rutas versionadas del repo.

    ¿Qué puede commitear automáticamente un agente?

    Cambios triviales y deterministas: correcciones de tipos, campos faltantes obvios o parches que no alteren la semántica. Las políticas deben definir límites claros: breaking changes y decisiones de diseño requieren revisión humana.

    ¿Cómo evito el automation bias en el equipo?

    Establece métricas de calidad, revisiones periódicas de commits automáticos revertidos y responsabilidades claras. Mantén a los revisores enfocados en criterio y diseño, no en correcciones triviales.

    ¿Qué pruebas son imprescindibles antes de activar agentes en CI?

    Cobertura de tests unitarios, contract tests (Specmatic/Optic) y un set mínimo de E2E para paths críticos. Además, entornos de staging efímeros donde el agente pueda ejecutar validaciones reales.

    ¿Cómo audito los parches automáticos?

    Registra trazabilidad y motivación textual para cada parche, conserva commits con mensajes generados por el agente y almacena logs completos de ejecución en un sistema de auditoría accesible al equipo de seguridad y arquitectura.

    ¿Qué límites de contexto tienen los modelos actuales?

    Los modelos pierden precisión en cambios transversales dentro de monolitos enormes debido a la ventana de contexto. La modularidad y bounded contexts reducen este problema y mejoran la precisión del agente.

  • Implementa Plum para Mejorar la Trazabilidad en tus Commits

    Implementa Plum para Mejorar la Trazabilidad en tus Commits

    ¿Te da pánico pensar que la IA pueda llenar tu repo de código que nadie entiende? Bienvenido a la nueva crisis del software.

    Tiempo estimado de lectura: 5 min

    • La velocidad de generación de código por IA supera la capacidad humana de registrar intención.
    • Plum captura decisiones en el momento del commit para mantener spec, tests y código sincronizados.
    • Sin checkpoints canónicos (hooks de Git) la intención se evapora y se pierde propiedad intelectual.

    Introducción

    Poca gente lo dice claro: ahora la IA escribe más rápido de lo que podemos entender. Y velocidad sin intención es solo ruido estructural.

    This is her code. This is what she was managing. This is her VS code. Margaret Hamilton tenía la plomada mental de la arquitectura. Hoy tenemos agentes que empiezan a escribir habitaciones enteras sin planos. ¿Quién firma eso cuando se cae el techo?

    Resumen rápido (lectores con prisa)

    Plum captura y versiona decisiones (humanas y de agentes) en el momento del commit mediante hooks de Git; obliga a validar intenciones y sincroniza spec ↔ tests ↔ código. Es un checkpoint canónico para trazabilidad y responsabilidad.

    ¿Qué hace Plum en una frase?

    Captura decisiones (humano + agente) en el momento del commit, te pide que las valides, las convierte en artefactos versionables y sincroniza spec ↔ tests ↔ código.

    ¿Por qué no puede ser simplemente “una skill” dentro del agente?

    Porque una skill es una sugerencia. Una sugerencia se ignora cuando el plazo aprieta. Necesitamos un checkpoint canónico que no puedas saltar: un hook de Git que detenga el commit hasta que la intención quede registrada. Eso es lo que hace Plum.

    Cómo se ve en la práctica (sin tecnicismos aburridos)

    • Instalas Plum.
    • Ejecutas plum init en la raíz del repo.
    • Plum crea una carpeta .plum, un .plumignore y agrega hooks a Git.
    • Haces cambios usando un agente.
    • Intentas git commit.
    • Plum analiza diffs + traces del agente.
    • Si hay decisiones detectadas, el commit falla hasta que las apruebes, edites o rechaces.
    • Si apruebas, Plum actualiza la spec (Markdown) y genera un registro en JSONL con la decisión, quién la aprobó, branch, timestamps y si el LLM sugirió o el humano decidió.

    Ventajas prácticas que notarás rápido

    • Un agente ya no “olvida” reglas que le dijiste hace semanas. El agente puede consultar el árbol de decisiones antes de actuar.
    • Cuando alguien pregunta “¿por qué esto está así?”, la respuesta no es “creo que lo discutimos en Slack”. Es un enlace a la decisión y su justificación.
    • El code review pasa de revisar sintaxis a revisar intención. Eso reduce regresiones silenciosas.

    Limitaciones honestas (sí, las tiene)

    • Hoy Plum enlaza pruebas vía Pytest. Si tu pipeline usa otro runner, la cobertura spec→tests no funcionará todavía.
    • Identificar decisiones no es perfecto. La deduplicación es fuzzy y repo-específica. Hay parámetros que ajustar.
    • Reversión automática al rechazar decisiones aún no es robusta. Si rechazaste una decisión en la CLI, el rollback con el agente es un flujo que requiere trabajo fino.
    • En proyectos extremadamente grandes sin spec previa (legacy), Plum no hace magia: necesita spec por delante para funcionar bien. Backfilling masivo aún está en la hoja de ruta.

    Diseños críticos que no puedes ignorar

    • Debe ser externa al LLM. Si la gobernanza vive dentro del agente, la gente la ignorará.
    • Debe fallar commits. Sin ese checkpoint, es teoría bonita y nadie la respeta.
    • Usa DSPy u otro framework para estructurar LLM calls cuando sea absolutamente necesario. Pero siempre que puedas, valida con código determinista: la verificación debe ser programable, repetible y testeable.
    • La experiencia humana importa. Si cada hotfix genera 5 decisiones triviales, la herramienta se vuelve molesta. Debe existir un umbral de interrupción configurable. Tú decides: banca cero tolerancia para banca; modo “dangerously approve all” para experimentos.

    Casos reales, concretos

    • PM cambia la regla de comisiones a las 3am. El agente aplica el hotfix. Plum detecta 3 decisiones: cambio de fórmula, invalidación de cache, ajuste de test. Te las muestra. Apruebas. Plum actualiza el spec y enlaza el test que cubre la nueva regla. Un auditor te lo agradece en el futuro.
    • Fix urgente en prod. Actúas rápido. Plum puede configurarse para no interrumpir decisiones triviales en ramas específicas. O puedes exigir aprobación humana para cambios en main o en módulos críticos.
    • Refactor mayor. Plum obliga a agrupar decisiones y a shardar la spec. El árbol de decisiones te ayuda a no romper invariantes.

    Checklist para empezar hoy (sin dramas)

    1. Poner spec en Markdown y versionarla. Sí, en el repo.
    2. Tener tests automatizados. Si usas Python: Pytest. Si no, prepara el adapter.
    3. pip install plum-dev
    4. plum init (apunta a tu carpeta de specs y al directorio de tests)
    5. Añade .plumignore para excluir archivos ruidosos
    6. Configura tolerancias: qué decisiones bloquean commit y cuáles no
    7. Empieza con una rama pequeña y haz dogfooding: úsenlo para gestionar el proyecto que desarrolla Plum. Si no duele, no funciona.

    Comportamientos que salvarán tu empresa (si los adoptas)

    • Nunca permitas que un cambio de negocio se quede solo en Slack.
    • No confíes en mensajes de commit como única fuente de intención.
    • Exige artefactos: decisión aprobada, spec actualizada, test que falla sin la decisión.

    Metáfora rápida porque las metáforas funcionan

    Tu repo es un edificio. Los agentes son obreros hiperactivos con taladros. Si no tienes planos actualizados y un inspector que firme cada cambio, terminarás con un edificio que parece Frankenstein. Plum es la plomada. No construye paredes. Te dice si las paredes están verticales.

    Lo práctico, ahora mismo

    • Sí, puedes pip install plum-dev y jugar en una rama de feature.
    • Sí, puedes ajustar el umbral para que no te moleste en hotfixes.
    • No, no es todavía plug-and-play para proyectos legacy gigantes.
    • Sí, si usas agentes en producción sin registrar decisiones, estás acelerando una deuda técnica que alguien pagará caro.

    ¿Quieres el template JSONL + flujo de PR listo para copiar en tu repo? Respóndeme este mensaje y te lo envío.
    Quieres algo más directo: pip install plum-dev, plum init, haz un commit con un agente y verás cómo el commit falla hasta que registras la intención. Prueba en una rama de sandbox.

    No es sexy. Es aburrido. Y es exactamente lo que separa equipos que escalan de equipos que heredarán un desastre técnico eterno.

    Dominicode Labs

    Si trabajas con automatización, agentes o workflows y quieres seguir explorando prácticas de gobernanza y trazabilidad, revisa Dominicode Labs como continuación lógica de estas ideas. Encontrarás recursos y experimentos sobre integración de agentes y control de intención.

    FAQ

    ¿Qué es Plum?

    Plum es una herramienta que captura decisiones (humanas y de agentes) en el momento del commit mediante hooks de Git, convierte esas decisiones en artefactos versionables y sincroniza spec, tests y código para mantener trazabilidad.

    ¿Por qué necesito un hook de Git para registrar decisiones?

    Porque un hook crea un checkpoint canónico que no se puede saltar: obliga a registrar intención antes de completar el commit. Sin ese mecanismo la gobernanza se vuelve opcional y se pierde trazabilidad.

    ¿Cómo integra Plum spec y tests?

    Plum analiza diffs y traces de agente, propone cambios en la spec (Markdown) y genera enlaces entre requisitos atómicos, tests y commits. Además crea un registro JSONL con las decisiones para auditoría.

    ¿Qué pasa en hotfixes de emergencia?

    Plum puede configurarse para reducir la interrupción en ramas específicas o para exigir aprobación humana en ramas críticas como main. También puedes ajustar umbrales para decisiones que no bloqueen el commit.

    ¿Funciona con pipelines que no usan Pytest?

    Hoy Plum enlaza pruebas vía Pytest por defecto. Si tu runner es otro, necesitarás un adapter: la cobertura spec→tests no funcionará hasta que exista soporte para tu runner.

    ¿Cómo evita Plum el ruido en cambios triviales?

    Plum usa un .plumignore para excluir archivos ruidosos y tiene parámetros configurables que definen umbrales de interrupción para que no genere decisiones por cada cambio menor.

    ¿Dónde están los registros de decisiones?

    Plum genera un archivo JSONL con entradas que incluyen la decisión, quién la aprobó, branch, timestamps y si fue sugerida por LLM o aprobada por humano. Es un fichero indexable y enlazable a PRs.

  • Cómo usar especificaciones en desarrollo con IA para evitar problemas

    Cómo usar especificaciones en desarrollo con IA para evitar problemas

    ¿Quieres acelerar el desarrollo con IA o quieres estrellarte más rápido?

    Tiempo estimado de lectura: 6 min

    • La spec corta y accesible es imprescindible cuando usas IA para generar código.
    • Sin spec aparecen tres síntomas: incoherencia de estilo, pérdida de contexto y acoplamiento brutal.
    • Implementa una SPEC.md en la raíz, define contratos y divide el trabajo en prompts modulares.
    • Convierte al desarrollador senior en guardián de la spec para revisar PRs generados por IA.

    Poca gente habla de esto en las charlas brillantes de conferencias: darle a una IA permiso para escribir código sin una spec es como dejar a un pintor con un bote de pintura en la cocina de tu casa. Va a pintar rápido. Va a ser espectacular durante cinco minutos. Y luego tendrás harina pegada en la pared, cables pelados y una silla rota.

    Esto no es exageración. Es un patrón. Lo veo en proyectos pequeños y en réplicas gigantes: la velocidad instantánea convierte decisiones críticas de arquitectura en improvisación. Y la improvisación, por definición, no escala.

    Resumen rápido (lectores con prisa)

    • Qué es: Una spec es un archivo vivo y accesible que define objetivos, límites, reglas y contratos que la IA debe respetar.
    • Cuándo usarla: Siempre que el código toque dominio, datos, seguridad o infraestructura crítica.
    • Por qué importa: Evita decisiones locales de la IA que llevan a incoherencia, pérdida de contexto y acoplamiento.
    • Cómo funciona: Sirve al agente como brújula: convierte prompts vagos en contratos concretos y verificables.

    ¿Por qué la spec es el arma secreta (y olvidada) al programar con IA?

    La spec no es burocracia. No es un PDF que acumula polvo. Es el plano que limita la creatividad sin matarla. Es la instrucción que obliga a la IA a optimizar por coherencia, no por conveniencia momentánea. En términos sencillos: la spec transforma “hacer que funcione” en “hacer que funcione y siga funcionando”.

    Modelos probabilísticos y decisiones

    Poca gente entiende algo crucial: los modelos de lenguaje son motores probabilísticos. Responden con la solución más probable según su entrenamiento y tu prompt. No saben ni les importa tu SLA, tu GDPR ni el culto interno a las serverless functions que montaste el año pasado. Si no les pones una spec, toman decisiones por ti. Y esas decisiones rara vez son las correctas para tu sistema.

    Descubrí algo curioso: cuando un equipo usa IA sin spec, aparecen siempre tres síntomas en el código.

    1) Incoherencia estilística que mata el mantenimiento.

    Un archivo usa Fetch, otro Axios, otro una función casera que alguien copió de StackOverflow. Ninguna regla es compartida. El README promete TypeScript y encuentras middleware en JavaScript puro. La IA actúa por contexto inmediato, no por coherencia global.

    2) Pérdida de contexto.

    Las ventanas de los modelos tienen límite. Lo que no está fijado en una spec, desaparece del escenario cuando la conversación se estira. Resultado: soluciones que olvidan requisitos críticos (idempotencia, manejo de errores, validaciones).

    3) Acoplamiento brutal.

    Funciones monolíticas que mezclan acceso a datos, lógica de negocio y presentación. Todo junto. Porque la IA optimizó para el prompt: “haz que funcione ya”, no para testabilidad o escalabilidad.

    Esto tiene nombre: alucinación arquitectónica

    No es que la IA invente una ruta inexistente; inventa la forma en que tu sistema debería operar. Propone abstracciones que no encajan. Implementa patrones que rompen tus contratos. Y lo peor: lo hace con convicción. Te entrega un PR impecable y peligroso.

    Si trabajas con Next.js y pides “sistema de autenticación” sin más, la IA te va a devolver lo que suele devolver: la solución más popular en sus datos. ¿Que tu empresa requiere tokens rotativos y encriptación extra? La IA lo ignora. ¿Que solo se debe usar server components para ciertas páginas? La IA lo ignora. No lo hace con malicia. Lo hace por probabilidad estadística.

    Entonces, ¿qué es una spec moderna para desarrollo con IA?

    No es el viejo documento de 50 páginas que nadie lee. Es el System Prompt del repositorio. Es un archivo vivo, legible por humanos y por agentes. Contiene las respuestas a las preguntas que la IA no puede inferir del código: objetivos, límites, reglas y modelos de datos.

    Una spec efectiva incluye:

    • Objetivo funcional claro: qué problema resuelve este módulo y qué no debe hacer.
    • Stack y versiones permitidas: qué frameworks, librerías y versiones están aprobadas.
    • Reglas de arquitectura: patrones obligatorios (ej. “usar Server Components en Next.js salvo casos X”) y prácticas prohibidas.
    • Contratos de datos: interfaces TypeScript, esquemas de BD, formatos de API.
    • Políticas de seguridad y privacidad: qué información no puede exponerse, cómo manejar secretos.
    • Estrategia de testing y criterios de aceptación.

    Piensa en la spec como la brújula del proyecto. La IA es el marinero con experiencia, pero sin brújula se va con la corriente.

    Cómo empezar ahora mismo (sí, ahora): 5 pasos prácticos para evitar el caos

    1) Crea un SPEC.md en la raíz del repo.

    No lo escondas en Google Docs. Ponlo en el repo para que cualquier agente lo consuma. Que sea corto, directo y accionable. Primera frase: “Si esto cambia, consulta al team lead”. Segunda frase: “No uses X, usa Y”. Las reglas deben ser bullet points fáciles de aplicar.

    2) Define los contratos antes de pedir ejecución.

    Antes de pedir a la IA que escriba la lógica, define las interfaces. Si pides que implemente una función, dale la firma TypeScript y los tests. Esto convierte la tarea en un contrato a cumplir, no en una sugerencia.

    3) Usa archivos de reglas a nivel proyecto.

    Si tu herramienta lo permite, añade reglas que la IA lea automáticamente (.cursorrules, spec.json, etc.). Es la diferencia entre decir “por favor” y obligar. Hazlo parte del flujo de CI.

    4) Divide el trabajo en prompts modulares.

    No le pidas a la IA “haz todo”. Pide un plan paso a paso. Revisa el plan. Apruébalo. Luego pide que ejecute cada paso. Así preservas control y contexto, además de poder auditar decisiones.

    5) Convierte al desarrollador senior en guardián del criterio.

    El trabajo del senior no es escribir menos código; es decidir qué se debe escribir. Revisar PRs seguirá siendo necesario, pero con otro foco: ¿esto respeta la spec? ¿Esto escala? Si la respuesta es no, no merges.

    Historias reales: el junior, el senior y la IA

    Imagínate esto.

    El junior llega, emocionado. “Voy a acelerar. Uso Copilot y saco features.” En 48 horas hay un demo impresionante. El producto parece volar. La dirección está feliz.

    Luego viene la integración con otros servicios. El equipo descubre tokens rotos, errores raros en producción y tests que fallan en horarios impredecibles. El senior se sienta, mira el repo y ve 12 formas distintas de autenticación. Decide reescribir. Dos semanas perdidas en refactor. El demo se apaga.

    Cambia el final: el senior escribió la spec antes de empezar. El junior pidió permisos y la IA generó código que ya respetaba validaciones, logs y pruebas. Todo encajó. El demo no solo funcionó; aguantó.

    Metáfora rápida: la spec es el embudo

    La spec es el embudo que convierte la creatividad desenfrenada de la IA en soluciones útiles. Sin el embudo, la creatividad sale por todos lados y cubre el proyecto como aceite en el motor. Con el embudo, la creatividad llega donde debe y no inunda lo que no corresponde.

    No todo necesita spec rígida (también hay límites)

    Sí, hay casos donde pedirle a la IA que improvise está bien. Refactorizaciones locales, generación de mocks, o prototipos exploratorios. No necesitas una spec para cada línea de código. Pero necesitas reglas cuando el código toca el dominio, los datos, la seguridad o la infraestructura crítica.

    Regla práctica: cuando lo que cambias rompe contratos (APIs, bases de datos, auth, flujos críticos), necesitas una spec. Punto.

    Qué poner en la spec para que la IA realmente la entienda

    • Comandos claros: “No usar X”, “Usar Y con versión Z”.
    • Ejemplos: un snippet de código que es correcto y uno que no.
    • Criterios de aceptación: tests que deben pasar. Un checklist.
    • Casos borde: qué hacer con fallos del servicio, timeouts, reintentos.
    • Política de secretos: dónde y cómo almacenar tokens.
    • Responsabilidades: quién aprueba cambios que tocan módulos críticos.

    CTA simple y directo: haz esto ahora

    Abre tu repo. Crea SPEC.md. Escribe cinco cosas:

    • Objetivo del módulo en una frase.
    • Tres reglas de arquitectura innegociables.
    • Las interfaces de los datos (TypeScript).
    • Un test de aceptación.
    • Dónde poner secretos.

    Hazlo en los próximos 60 minutos. No lo dejes para el sprint. Si quieres, respóndeme este mensaje con “Quiero la plantilla” y te mando un SPEC.md listo para pegar en tu repo.

    Urgencia real: la deuda técnica no espera

    Cada PR que aceptas sin spec es una apuesta a que nadie tocará eso en seis meses. No confíes en esa apuesta. En seis meses, otro equipo, otro deadline o un pico inesperado de usuarios lo romperán. La deuda técnica es acumulativa y compite con tu tiempo de desarrollo futuro. Actuar ahora te evita horas de rehacer.

    Cierre que no cierra (a propósito)

    Si sigues creyendo que la IA es la varita mágica que arregla todo, tienes dos opciones: aprender a gobernarla o pagar el precio después. La spec es la forma más barata y efectiva de gobernarla.

    Esto no acaba aquí. Si quieres, te doy:

    • Una plantilla de SPEC.md.
    • Ejemplos de .cursorrules para Cursor.
    • Un checklist de revisión para PRs generados por IA.

    Dime cuál quieres y te lo mando. Ahora decide: acelerar desordenadamente o correr con una brújula. Tus commits lo recordarán.

    Si te interesa llevar estas prácticas a flujos automáticos y agentes dentro de proyectos reales, revisa recursos y experimentos prácticos en Dominicode Labs. Es una continuación natural para quien quiera convertir una spec en reglas consumibles por agentes.

    FAQ

    ¿Qué es exactamente una SPEC.md y dónde debe vivir?

    Es un archivo en la raíz del repositorio que documenta objetivos, reglas, contratos y criterios de aceptación. Debe estar en el repo para que agentes y desarrolladores lo consuman fácilmente.

    ¿Cuánto detalle necesita una spec?

    Suficiente para responder las preguntas que la IA no puede inferir: objetivos, límites, interfaces, versiones y criterios de prueba. Debe ser breve y accionable, no un tratado.

    ¿La spec reemplaza la revisión de código?

    No. Reduce el foco de la revisión: ahora el senior verifica cumplimiento de la spec, escalabilidad y contratos, en lugar de escribir todo el código.

    ¿Qué pasa si olvidamos actualizar la spec?

    La spec caduca y pierde valor. Debe ser un archivo vivo; incluye una línea de responsabilidad (quién aprueba cambios) para mantenerla vigente.

    ¿Cómo integro la spec en el CI?

    Añade validaciones automáticas que verifiquen contratos (types, esquemas), reglas de lint y que los tests de aceptación definidos en la spec pasen antes del merge.

    ¿Necesito una spec para prototipos?

    No siempre. Para prototipos exploratorios puedes prescindir de una spec rígida. Pero para cualquier cambio que afecte datos, seguridad o APIs, sí debes tener una spec.