DOMINICODE

Category: Claude Code

  • Errores comunes al adoptar Claude Code en equipos de desarrollo

    Errores comunes al adoptar Claude Code en equipos de desarrollo

    Errores comunes al adoptar Claude Code en un equipo

    Tiempo estimado de lectura: 4 min

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

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

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

    Resumen rápido (lectores con prisa)

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

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

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

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

    Solución práctica:

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

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

    2) Lanzar prompts sin specs (Spec-First)

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

    Solución práctica:

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

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

    3) Ignorar costos y permitir bucles infinitos

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

    Solución práctica:

    • .claudeignore es obligatorio (igual que .gitignore). Ejemplo:
    node_modules/
.next/
dist/
*.sqlite
logs/
package-lock.json
    • Imponer límites en el prompt: "Si los tests no pasan después de 3 intentos, detén la ejecución y reporta errores con stack traces".
    • Monitorización y alertas: trackea consumo de tokens y costes con dashboards; define budgets por equipo y bloquea continuaciones si se supera el umbral.

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

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

    Solución práctica:

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

    Controles operativos y guardrails que funcionan

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

    Conclusión breve y accionable

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

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

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

    FAQ

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

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

    Respuesta: Impone límites en el prompt (por ejemplo, máximo 3 intentos de test), usa .claudeignore para reducir el volumen de datos procesados y monitoriza consumo de tokens con dashboards y budgets por equipo. Bloquea continuaciones automáticas si se supera el umbral.

    Respuesta: .claudeignore funciona como .gitignore para el agente: evita enviar al modelo directorios pesados o irrelevantes (node_modules, dist, logs, etc.), reduciendo costes y ruido en la señal.

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

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

  • 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.

  • Implementando IA Generativa con Claude Code en la Terminal

    Implementando IA Generativa con Claude Code en la Terminal

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

    “Tiempo estimado de lectura: 4 min”

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

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

    Resumen rápido (lectores con prisa)

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

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

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

    Arquitectura mínima del flujo

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

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

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

    Dónde aporta

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

    Dónde falla o es peligroso

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

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

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

    No hablo de marcas por postureo. Comparo por arquitectura:

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

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

    Riesgos técnicos y cómo mitigarlos

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

    Medidas prácticas

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

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

    Qué cambia en la cultura de ingeniería

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

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

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

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

    Próxima entrega

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

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

    FAQ

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

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

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

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

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

    Respuesta: Claude Code está pensado para flujos terminal-first y pipelines CLI, pero puede integrarse en flujos más visuales mediante orquestación. Si prefieres autocompletados en el IDE, herramientas como Copilot o Cursor ofrecen mejor experiencia GUI.
  • Cómo evitar la amnesia del agente en Claude Code entre sesiones

    Cómo evitar la amnesia del agente en Claude Code entre sesiones

    Cómo evitar la amnesia del agente entre sesiones con Claude Code

    Tiempo estimado de lectura: 5 min

    Ideas clave

    • Externalizar el estado del agente al repositorio (archivos versionados) para persistencia entre sesiones.
    • Usar un archivo TASK_STATE.md como fuente de verdad y exigir su lectura al iniciar cada sesión.
    • Dividir el trabajo por módulos y actualizar TASK_STATE.md antes de cada commit para evitar pérdida de contexto.
    • Mantener ventanas de contexto pequeñas cargando sólo archivos relevantes del módulo más TASK_STATE.md.
    • Medir retoma y reducción de rework para validar la efectividad del sistema.

    Tabla de contenidos

    Introducción

    Saber exactamente cómo evitar la amnesia del agente entre sesiones es lo que separa las automatizaciones frágiles de las que realmente escalan. Si cierras una terminal con Claude Code a mitad de tarea, la siguiente sesión no recordará decisiones, bugs ni el alcance ya cubierto. Esa falta de persistencia —junto a la contaminación de contexto dentro de sesiones largas— exige una solución estructural: externalizar el estado del agente en el repositorio.

    Resumen rápido (lectores con prisa)

    Externaliza el estado del agente en archivos versionados (ej. TASK_STATE.md). Lee TASK_STATE.md al iniciar cada sesión y actualízalo antes de cada commit. Divide el trabajo por módulos para mantener la ventana de contexto pequeña y evitar contaminación. Usa commits atómicos y especifica tareas en /tasks para handoffs confiables.

    Cómo evitar la amnesia del agente entre sesiones: sistema de tareas en disco

    La estrategia que funciona en entornos productivos es simple y técnica: tratar el árbol de archivos como la memoria persistente del agente. En vez de confiar en la memoria efímera de la sesión, haces que Claude escriba su estado, incidencias y decisiones en archivos versionados antes de cada commit. Al abrir una nueva sesión, el agente lee ese archivo y retoma exactamente donde quedó.

    Referencias útiles: la documentación de Claude Code y la página de Claude explican las capacidades de ejecución y acceso a repositorio que hacen esto posible.

    Componentes del sistema de estado

    • TASK_STATE.md — memoria de trabajo (temporal, versionada)
    • /tasks/*.md — specs atómicas por tarea (entradas para subagentes)
    • CLAUDE.md — contrato del proyecto (stack, convenciones, patrones prohibidos)

    Estructura mínima recomendada

    /CLAUDE.md
/TASK_STATE.md
/tasks/
  auth-migration.md
  billing-refactor.md

    Ejemplo práctico: TASK_STATE.md (plantilla)

    ## Estado actual
- Tarea: Migración AuthService → AuthV2
- Fase: 2/4
- Último commit: a3f92c1

## Módulos completados
- [x] UserModel
- [x] AuthService
- [ ] AuthController

## Bugs identificados
- UserService.getById no valida usuarios inactivos (línea 47)
- Token refresh: edge-case con cambio de email

## Notas de diseño
- Mantener compatibilidad token-legacy 30 días
- No migrar OAuth hasta fase 3

    Prompt de recuperación (instrucción inicial)

    Al iniciar una nueva sesión, la primera instrucción debe ser innegociable:

    Lee TASK_STATE.md antes de ejecutar cualquier acción. Retoma desde la fase indicada y no repitas trabajo ya marcado como completado.

    Ese prompt convierte el archivo en la “fuente de verdad” para el agente.

    Cómo evita esto la contaminación de contexto

    La contaminación ocurre cuando una sesión larga excede la ventana de tokens y el modelo comienza a “olvidar” detalles previos. La solución práctica es dividir la tarea en sesiones acotadas por módulo:

    • Cada sesión se centra en un módulo concreto.
    • Solo se cargan en contexto los archivos del módulo, las firmas de interfaces adyacentes y TASK_STATE.md.
    • Los bugs se registran inmediatamente en TASK_STATE.md antes de pasar al siguiente módulo.

    Así mantienes la ventana de contexto pequeña y relevante, y cualquier hallazgo se persiste en disco aunque el modelo lo “olvide” en memoria volátil.

    Flujo operativo recomendado (paso a paso)

    1. Preparación: crea CLAUDE.md y una spec por tarea en /tasks.
    2. Inicio: abre sesión y ejecuta prompt de recuperación para leer TASK_STATE.md.
    3. Trabajo por módulo: el agente modifica archivos permitidos, añade tests y actualiza TASK_STATE.md antes del commit.
    4. Commit atómico: cada checkpoint importante tiene commit con mensaje estructurado.
    5. Handoff: si otro desarrollador o sesión retoma, lee TASK_STATE.md y continúa.
    6. Cierre: cuando la tarea se completa, merge y eliminación de TASK_STATE.md.

    Regla clave: actualizar TASK_STATE.md antes de cada commit. Si la terminal cae, el estado queda preservado hasta el último punto sincronizado.

    Decisiones de cuándo aplicar esto

    Implementa este sistema cuando:

    • La tarea requiere múltiples sesiones o días.
    • Debes auditar y modificar más de 5–6 archivos interconectados.
    • Necesitas handoffs confiables entre sesiones o personas.

    No lo uses para cambios triviales que se completan en una sesión corta; el overhead no compensa.

    Medir si funciona

    Indicadores prácticos:

    • Tiempo medio de retoma (desde abrir sesión hasta reanudar trabajo) < 5 minutos.
    • % de tareas que requieren rework por amnesia o contexto < 5%.
    • Reducción en reverts por decisiones olvidadas.
    • Número de bugs registrados en TASK_STATE.md vs. bugs no documentados detectados tras merge (debe bajar).

    Límites y advertencias

    Esto no convierte a Claude en un “ingeniero permanente”. Externalizar estado aumenta resiliencia, pero no suple la necesidad de especificaciones claras. Si la spec es ambigua, el agente persistirá ambigüedades más rápido. Tampoco es sustituto de revisiones humanas en handoffs críticos (auth, infra, contratos externos).

    Dominicode Labs

    Para equipos que aplican automatización y agentes en flujos de trabajo, una continuación natural es explorar prácticas y experimentos en Dominicode Labs. Allí se documentan plantillas y patrones aplicables a sistemas de estado basados en repositorio.

    FAQ

    ¿Qué es TASK_STATE.md y para qué sirve?

    TASK_STATE.md es un archivo versionado que actúa como memoria de trabajo del agente: registra el estado de la tarea, módulos completados, bugs y notas de diseño. Sirve como fuente de verdad para retomar trabajo entre sesiones.

    ¿Cómo se usa TASK_STATE.md al inicio de una sesión?

    La primera instrucción al iniciar una sesión debe ser leer TASK_STATE.md antes de ejecutar cualquier acción. El agente debe retomar desde la fase indicada y evitar repetir trabajo ya marcado como completado.

    ¿Qué información debe contener TASK_STATE.md?

    Debe incluir estado actual (tarea, fase, último commit), módulos completados, bugs identificados y notas de diseño relevantes. El ejemplo en el artículo muestra una plantilla con secciones claras para cada aspecto.

    ¿Por qué dividir el trabajo por módulos?

    Dividir por módulos mantiene la ventana de contexto pequeña y relevante, reduce la contaminación de contexto y facilita la persistencia de hallazgos en disco aunque el agente pierda memoria en la sesión.

    ¿Cuándo no es apropiado este sistema?

    No es apropiado para cambios triviales que se completan en una sola sesión; el overhead de mantener TASK_STATE.md y specs por tarea puede no compensar en esos casos.

    ¿Qué hacer si la spec es ambigua?

    Externalizar ambigüedades amplifica problemas: el agente persistirá decisiones ambiguas. La medida correcta es clarificar la spec durante el proceso y registrar las decisiones en TASK_STATE.md, además de mantener revisiones humanas en handoffs críticos.

  • 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 garantizar gobernanza en especificaciones y código usando Plum

    Cómo garantizar gobernanza en especificaciones y código usando Plum

    ¿Y si te dijera que tu “spec perfecta” es solo un espejismo que te está dejando con más ruina que beneficio?

    Tiempo estimado de lectura: 7 min

    • Ideas clave:
    • Specs y tests no capturan intención; la implementación revela decisiones que deben registrarse.
    • Sin trazabilidad y gobernanza, la velocidad con agentes de IA genera deuda técnica no asignable.
    • Convierte decisiones efímeras en artefactos auditables: captura, exige aprobación humana y sincroniza spec↔tests↔código.

    Introducción

    Poca gente habla claro de esto: en el mundo real, sometimes specs and tests aren’t sufficient. Y cuando metes agentes de IA en la ecuación, la ilusión se convierte en problema de verdad. No es opinable. Es práctico. Y te va a doler si no te preparas.

    La promesa era bonita. Escribe la especificación, lanza unos tests, suelta un agente, y voilà: código. Suena como un truco de magia barato. Pero la magia no limpia deudas técnicas. La magia solo las acelera.

    Resumen rápido (lectores con prisa)

    Qué es: Capturar decisiones técnicas efímeras como artefactos auditable (spec, tests y registro de decisiones).

    Cuándo usarlo: Siempre que agentes de IA o cambios rápidos modifiquen comportamiento crítico.

    Por qué importa: Sin trazabilidad las decisiones quedan en chats y commits huérfanos; eso genera deuda técnica no atribuible.

    Cómo funciona (resumido): Leer diffs, extraer decisiones, pedir aprobación humana y actualizar spec/tests con registro.

    Por qué las specs y los tests fallan

    Un código que pasa todos los tests puede ser un desastre elegante. Puede consumir memoria, colapsar bajo concurrencia o romper la invariant que nadie documentó.

    Los tests —por sí solos— no capturan intención. Capturan salida. Y la intención es lo que de verdad se rompe cuando un Product Manager cambia una regla a las tres de la madrugada.

    Tests vs intención

    Recuerda a Margaret Hamilton con su pila de papeles y cinta adhesiva. Ella no estaba haciendo “scripts”; estaba diseñando resiliencia. Llevaba la arquitectura en la cabeza porque no había alternativa. Hoy no se trata de memoria humana: se trata de contexto. Y los LLMs lo tienen fragmentado.

    Escribir el código no es el paso final. Es la lupa que revela lo que la spec olvidó. Implémentalo y la spec te devolverá correcciones. No al revés. Ese es el flujo honesto que muchos olvidan.

    Implementación y decisiones

    Speedrun histórico: estamos reinventando problemas ya resueltos. La comunidad de IA está “speedrunneando” la historia del software: volver a tropezar con acoplamientos, incoherencias, dependencias ocultas. Cuando ni tú ni la IA pueden sostener la visión completa, lo que obtienes no es progreso: es ruido estructural.

    Esto no es una discusión teórica. Mira los proyectos que intentan ejecutar Python en Rust. Tests completos. Especificaciones martilladas. Y aún así—hilos de 20 comentarios sobre cómo debería comportarse una función. ¿Por qué? Porque el comportamiento observado y el comportamiento deseado no siempre coinciden en el mundo real. La implementación revela las zonas grises. Y las zonas grises necesitan decisiones, no conjeturas.

    Decisión = intención registrada. Si una IA sugiere “arreglar X así” y nadie lo documenta, ¿quién responde cuando eso explota? Sin trazabilidad, la autoría desaparece. Los commits quedan huérfanos. Las decisiones quedan atrapadas en chats. Eso es un cáncer técnico que se expande silencioso.

    Necesitas convertir intención en artefacto. No más “lo arreglé en local”. No más “lo discutimos en Slack”. Necesitas un registro auditable: qué se decidió, por qué, quién lo aprobó, y en qué rama quedó.

    Plum y trazabilidad

    Ahí entra Plum. No porque sea mágico, sino porque cumple una tarea concreta: transforma decisiones efímeras en evidencia material. Lee diffs. Escanea traces. Extrae decisiones. Te pregunta “¿lo apruebas?”.

    Si dices que sí, actualiza la spec y genera un registro .jsonl con la decisión, la autoría y la traza. Es la plomada para tu triángulo spec ↔ tests ↔ código.

    No es la única forma, pero la idea es la idea:

    • captura las decisiones,
    • exige aprobación humana,
    • sincroniza spec y tests,
    • y audita la intención.

    Práctico: cómo empezar sin reinventar la rueda

    1. Escribe la spec como contrato, no como aspiración. Si falta un caso límite, añádelo. Si no se puede automatizar, hazlo explícito.
    2. Invierte en tests que describan intención, no solo outputs. Los property tests y las invariantes sistémicas son el equivalente a los checks de seguridad en un avión.
    3. Captura los traces del agente. Que estén en el repo. Que no vivan solo en la ventana del chat.
    4. Extrae decisiones en cada commit. Pide aprobación humana antes de actualizar la spec.
    5. Bloquea merges si la spec—tests—código no están sincronizados. Sí: pon reglas duras en CI.

    Si tu respuesta inmediata es “nuestra organización no hará eso”, entonces ya perdiste. La opción no es hacerlo o no hacerlo. Es hacerlo hoy o pagar por horas de desastre mañana.

    Modularidad extrema, o el arte de no romper todo con una línea

    Si un agente necesita entender 50 archivos para cambiar una feature, tu arquitectura es culpable. Divide, desacopla, define boundaries estrictas. Interfaces claras. Contratos pequeños y firmes. Haz que los cambios sean locales y verificables. Así los agentes tienen probabilidades reales de acertar.

    Limitaciones de los LLMs

    No te engañes: los LLMs son herramientas brutales. También son miopes por diseño: ventana de contexto, sesgo de prompt, falta de visión de producto. Los modelos pueden sugerir refactors; no pueden entender roadmaps ni retener trade-offs históricos. La validación humana no es ornamental. Es esencial.

    Valor actual: tests y especificaciones vivas

    El valor actual ya no está en la sintaxis. Está en la suite de tests. En las especificaciones vivas. En los artefactos de decisión. El código se deja atrás. Los tests y las especificaciones sobrevivirán a generaciones de actores.

    Un ejemplo real —y sencillo

    Imagina que tu PM cambia la regla de cálculo de una comisión. Un ingeniero empuja el hotfix, el test unitario pasa. ¿Y el resto?

    • ¿Se actualizaron las pruebas de integración?
    • ¿Las reglas de caching se siguen cumpliendo?
    • ¿Se respetan las invariantes fiscales?

    Si la respuesta es “no lo sé”, fallaste en gobernanza. Si la respuesta es “sí, lo sabemos y está registrado”, ganaste.

    Cultura + Herramienta = Supervivencia

    No puedes automatizar cultura. Pero puedes diseñarla. Exige que cada decisión relevante tenga un artefacto. Añade a tu pipeline la obligatoriedad de reconciliar spec↔tests↔código antes del merge.

    Esto suena duro. Lo es. Pero sin esas reglas, el “move fast” vuelve rápidamente a ser “move fast and break everything—and then no one knows why”.

    ¿Quieres algo fácil de ejecutar ahora?

    Instala plum-dev en una rama pequeña. Apunta Plum a tu carpeta de specs y a tu suite de tests. Ejecuta un par de commits con agentes. Observa cómo las decisiones dejan de evaporarse en chat. Si no puedes hacerlo hoy, al menos empieza a exigir que cada PR documente la decisión que justifica el cambio.

    No se trata de quitar velocidad. Se trata de mantenerla con control. Agentes que generan código a la velocidad de la luz + procesos que no controlan la intención = desorden a escala.

    FAQ

     

     

    Respuesta: ¿Qué hace Plum y por qué es relevante?

    Plum transforma decisiones efímeras en evidencia material: lee diffs, escanea traces, extrae decisiones y solicita aprobación humana para actualizar specs y generar registros .jsonl con decisión, autoría y traza.

    Respuesta: ¿Por qué registrar decisiones en vez de confiar en commits y chats?

    Porque los commits y chats no proporcionan trazabilidad estructurada: la autoría se pierde, las decisiones quedan huérfanas y no hay un artefacto auditable que explique el porqué de un cambio.

     

    Respuesta: ¿Cómo se integra esto en CI sin frenar al equipo?

    Implementando reglas de bloqueo en CI que exijan sincronía spec—tests—código y aprobaciones humanas para cambios relevantes. Esto añade pasos obligatorios, no burocracia: evita horas futuras de investigación y corrección.

    Respuesta: ¿Qué tipo de tests son prioritarios?

    Tests que describan intención: property tests, pruebas de integración e invariantes sistémicas. Prioriza pruebas que validen contratos y comportamientos críticos, no solo outputs unitarios.

    Respuesta: ¿Cómo evito que los agentes provoquen ruido estructural?

    Diseña arquitectura modular con boundaries claros, interfaces pequeñas y cambios locales verificables. Captura traces y decisiones en el repo y exige aprobación humana antes de aplicar cambios en specs.

    Respuesta: ¿Qué límites tienen los agentes y los LLMs?

    Son herramientas con ventana de contexto y sesgos de prompt; no retienen trade-offs históricos ni entienden roadmaps. Pueden sugerir refactors, pero requieren validación humana para decisiones estratégicas.

  • Ultraplan y Computer Use: Mejora de procesos para validación y trazabilidad

    Ultraplan y Computer Use: Mejora de procesos para validación y trazabilidad

    Claude Code — Ultraplan + Computer Use en preview

    Tiempo estimado de lectura: 6 min

    • Ultraplan añade trazabilidad: planes auditablez y checkpoint de aprobación antes de ejecutar acciones automatizadas.
    • Computer Use permite interacción visual y de UI desde el CLI, cerrando parte del loop de validación visual.
    • El comando /resume reduce latencia en sesiones largas (hasta 67% según changelog) mediante optimización de Prompt Caching.
    • Adopción segura exige sandboxing, revisión humana y pipelines CI como árbitros finales.

    Claude Code — Ultraplan + Computer Use en preview aparece en el changelog publicado por Releasebot / Claude Code Changelog (6–10 abr 2026) y cambia dos conversaciones que llevábamos años teniendo: la auditablez de los agentes y su capacidad para interactuar con interfaces nativas. En las primeras líneas: Ultraplan separa planificación, revisión y ejecución; Computer Use permite que Claude abra apps, haga clics y verifique cambios visuales desde el CLI. Fuente: Releasebot / Claude Code Changelog (6–10 abr 2026).

    Resumen rápido (lectores con prisa)

    Ultraplan genera planes auditablez (árbol de decisiones) que requieren aprobación humana antes de ejecutar en entornos remotos. Computer Use permite interacciones GUI desde el CLI para validar cambios visuales. /resume mejora rehidratación de sesiones mediante Prompt Caching, reduciendo latencia al retomar contextos largos.

    Claude Code — Ultraplan + Computer Use en preview: qué hace cada pieza

    Ultraplan

    • Planifica desde el CLI: describes el objetivo y Claude genera un árbol de decisiones (archivos a tocar, comandos, condiciones de éxito).
    • Revisión en editor web: el plan se exporta para auditarlo de forma asíncrona (aprobación humana antes de ejecutar).
    • Ejecución remota: tras la aprobación, la ejecución corre en entornos remotos, no en la máquina local.

    Impacto: trazabilidad y cumplimiento. Ultraplan introduce un checkpoint explícito, similar a un PR de alto nivel, pero orientado a acciones automatizadas.

    Computer Use (research preview)

    • Desde el CLI, Claude puede abrir aplicaciones nativas, interactuar con UI (clics, formularios) y comprobar resultados visuales.
    • Caso de uso: implementar un modal en React → el agente levanta el dev server, abre el navegador, hace clic en “Login”, valida el modal y corrige CSS si detecta fallos visuales.

    Impacto: cierra el loop de validación visual que hasta ahora exigía intervención humana. Riesgo: fragilidad frente a resoluciones, animaciones y latencia.

    Comando /resume: hasta 67% más rápido

    • Mejora en rehidratación de sesiones largas: optimización de Prompt Caching que reduce la latencia al retomar contextos extensos.
    • Traducción práctica: retomar una sesión de debugging o un ticket de refactor en un monorepo deja de ser un dolor de cabeza.

    Fuentes principales: Releasebot changelog y documentación general de Anthropic sobre Claude.

    Por qué esto importa (y por qué no hay que lanzarse a ciegas)

    1) Auditoría y cumplimiento ya no son excusas.

    Ultraplan convierte un plan opaco en un artefacto revisable antes de ejecutar comandos destructivos. Eso es imprescindible en empresas con compliance y requisitos de trazabilidad. Si tu flujo de trabajo no permite revisar planes antes de ejecutar, no deberías usar agentes que escriben directamente en master.

    2) Validación visual automatizada acelera ciclos UX, pero es frágil.

    Computer Use es útil para comprobaciones rápidas en entornos controlados: smoke tests visuales, validaciones de flujo end-to-end en dev VMs, tests de regresión visual sencillos. No es adecuado todavía para pruebas deterministas en CI conectado a producción sin un sandbox robusto.

    3) Latencia reducida = sesiones realmente usables.

    El /resume más rápido no es solo confort; cambia la ergonomía de trabajo con agentes en proyectos reales. Si tu equipo ya trabaja con sesiones largas, esto mejora la adopción práctica.

    Limitaciones y recomendaciones técnicas

    • Sandbox obligatorio: correr Computer Use en máquinas con credenciales activas es irresponsable. Usa VMs o contenedores dedicados sin acceso a secretos.
    • No relies on pixel clicks: las pruebas deben combinar visión con checks DOM y tests automatizados. Si el agente actúa solo por coordenadas, esperen fallos por cambios menores de UI.
    • Revisión humana no es opcional: Ultraplan mitiga, pero no elimina, la necesidad de un Tech Lead que apruebe estrategias y revise trade-offs.
    • CI como árbitro final: cualquier PR o cambio generado por un agente debe pasar pipelines de integración, análisis estático y escaneo de dependencias antes del merge.
    • Documenta reglas de actuación: RULES.md, ADRs y guías de seguridad orientan al agente y reducen decisiones erráticas.

    Cuándo adoptar y cuándo esperar

    Adopta Ultraplan y Computer Use en preview si:

    • Necesitas acelerar refactorizaciones repetitivas con revisión humana.
    • Tienes capacidad de desplegar entornos aislados y pipelines robustos.
    • Quieres reducir el ciclo manual de validación visual en prototipos y pruebas de integración.

    No las uses en producción abierta si:

    • No puedes aislar el entorno del agente.
    • Tu UI depende de animaciones o resoluciones variables sin fallback DOM.
    • Tu organización no acepta un nuevo paso de auditoría humana en el flujo Dev→Prod.

    Conclusión

    Claude Code — Ultraplan + Computer Use en preview no es solamente una actualización de features; es una promesa operativa: agentes que planifican con trazabilidad y que pueden verificar visualmente cambios. La recompensa es real — velocidad y cierre de loops de validación—, pero la adopción requiere disciplina: sandboxing, CI riguroso y aprobación humana como norma.

    Lee el changelog original (Releasebot / Claude Code Changelog, 6–10 abr 2026) para detalles de versión. Para referencia del motor de razonamiento y mejores prácticas en agentes, consulta Anthropic.

    Integra estas capacidades en entornos aislados, añade reglas de seguridad y deja que la primera iteración falle allí antes de llevarlo a tus repositorios críticos. Esto no acaba aquí: lo que hoy es preview será mañana estándar—prepárate con criterio.

    FAQ

    ¿Qué es Ultraplan?

    Ultraplan es una funcionalidad que genera un árbol de decisiones desde el CLI (archivos a tocar, comandos, condiciones de éxito), permite revisión asíncrona en un editor web y ejecuta acciones en entornos remotos tras aprobación humana.

    ¿Qué permite Computer Use?

    Computer Use permite a Claude abrir aplicaciones nativas, interactuar con la interfaz de usuario (clics, formularios) y verificar resultados visuales desde el CLI, en un research preview.

    ¿Es seguro ejecutar Computer Use en máquinas con credenciales?

    No. Se recomienda ejecutar Computer Use en VMs o contenedores aislados sin acceso a secretos; correrlo en máquinas con credenciales activas es irresponsable.

    ¿Qué significa que /resume sea hasta 67% más rápido?

    Según el changelog, /resume mejora la rehidratación de sesiones largas mediante optimización de Prompt Caching, lo que reduce la latencia al retomar contextos extensos y hace las sesiones más ergonómicas.

    ¿Debo confiar en validaciones solo por clicks en píxeles?

    No. Las pruebas deben combinar visión con checks DOM y tests automatizados. Confiar únicamente en coordenadas de píxel es frágil frente a cambios menores en la UI.

    ¿Qué proceso de revisión recomiendan?

    Mantener aprobación humana explícita (Tech Lead) sobre planes generados por Ultraplan, someter cualquier cambio a pipelines CI, análisis estático y escaneo de dependencias antes del merge.

    ¿Dónde puedo leer el changelog y la documentación?

    El changelog está en Releasebot / Claude Code Changelog (6–10 abr 2026). La documentación y mejores prácticas de agente se encuentran en Anthropic.

  • Cómo mantener la sincronización en arquitecturas con IA

    Cómo mantener la sincronización en arquitecturas con IA

    Sincronización Arquitectónica: Código, Especificaciones y Agentes de IA

    Tiempo estimado de lectura: 4 min

    • La sincronía entre spec, tests y código es la unidad de trabajo esencial en equipos con agentes de IA.
    • Decisiones efímeras (commits, chats de agentes) sin trazabilidad crean deuda técnica y riesgo.
    • Herramientas como Plum convierten decisiones en artefactos auditables para alinear intentos y ejecución.

    Sincronización Arquitectónica: Código, Especificaciones y Agentes de IA. Si un Product Manager cambia algo hoy, ¿el resto del sistema se adapta mañana? La respuesta habitual es no. Y con agentes de IA escribiendo código, ese desajuste ya no es un fallo aislado: es una bomba de tiempo.

    El problema es simple y profundo: el código evoluciona en commits. Las specs siguen en un README. Los hotfixes saltan directo al trunk. Los agentes generan decisiones en chats y desaparecen con el log. Resultado: intención sin rastro, comportamiento sin documentación y deuda técnica que crece en silencio.

    Resumen rápido (lectores con prisa)

    La sincronización entre spec, tests y código es crítica cuando agentes de IA participan. Convierte decisiones efímeras en artefactos rastreables en el momento del commit. Usa aprobación humana para validar cambios que afectan gobernanza y negocio.

    El Triángulo: Spec, Tests, Código

    Piensa en spec, tests y código como los tres vértices de un triángulo. Tradicionalmente trabajábamos en una línea: spec → código → tests. Con IA esto falla. La implementación revela nuevas decisiones que deben volver a la spec y a los tests. Si no, todo se desincroniza.

    El verdadero trabajo de ingeniería hoy no es escribir más código. Es mantener ese triángulo alineado. Si mejoras el vértice del código, la spec y las pruebas deben moverse al mismo tiempo. Si no lo hacen, la arquitectura entra en drifting y el proyecto se vuelve inmanejable.

    Señales que indican desincronización

    • Commits que no referencian cambios en la spec.
    • PRs que pasan tests unitarios pero rompen invariantes de negocio.
    • Conversaciones con agentes sin registro estructurado.
    • Falta de trazabilidad entre decisión y autoría.

    Si reconoces cualquiera de estas, ya estás en modo emergencia controlada.

    Plum: la plomada para decisiones

    Plum es la herramienta que propone convertir decisiones efímeras en artefactos rastreables. No es un generador de código; es una plomada digital que alinea intención y ejecución.

    Cómo funciona, en cuatro pasos

    1. Al hacer commit, Plum revisa los diffs y los traces del agente.
    2. Extrae decisiones técnicas (qué se decidió, por qué).
    3. Presenta esas decisiones para aprobación humana.
    4. Si las apruebas, actualiza la spec y reporta gaps entre spec, tests y código.

    Plum genera además un archivo .jsonl con cada decisión: la pregunta, la respuesta, quién la aprobó y en qué rama quedó. Eso convierte la intención en un artefacto auditable.

    Por qué eso importa para equipos reales

    • Auditabilidad: Ya no dependes del recuerdo del autor del commit.
    • Gobernanza: Puedes diferenciar decisiones humanas de sugerencias de un LLM.
    • Recuperabilidad: Si un PM cambia una regla, puedes medir el impacto y forzar actualizaciones en spec/tests.
    • Escalabilidad: En equipos con múltiples agentes o muchos desarrolladores, reduce choques de integración.

    Limitaciones prácticas hoy

    • Plum, en su versión inicial, está acoplado a pytest para análisis de coverage. Si tu stack usa otro runner, la integración requiere trabajo.
    • Funciona mejor cuando la spec va por delante del código. Backfilling de specs desde bases legacy masivas sigue siendo difícil.
    • Los LLMs pueden sugerir decisiones razonables pero sin visión de negocio a largo plazo. La aprobación humana no es opcional.

    Patrón operativo recomendado

    1. Escribe spec antes de generar código. Hazla lo más concreta posible.
    2. Cubre casos límite en tests automáticos. No confíes en el “lo arreglamos después”.
    3. Usa Plum o una herramienta equivalente para capturar decisiones en el momento del commit.
    4. Ejecuta un pipeline de sync: spec ↔ tests ↔ código. Fallas: bloqueo del merge hasta que todo esté alineado.
    5. Mantén el .jsonl como fuente de verdad para auditorías y retroalimentación del producto.

    Casos prácticos y referencias

    Los equipos que han escalado Spec-Driven Development reutilizan suites de tests maduras (CPython, Bash). Ejemplos relevantes:

    No es trivial. Requiere inversión en especificaciones y disciplina en procesos. Pero sin eso, delegar en agentes solo acelera la creación de un monolito incomprensible.

    Cierre con criterio

    Si quieres que un cambio de producto active el resto del sistema de forma fiable, no te obsesiones con generar más código. Obsesiónate con capturar decisiones. Haz que tus specs sean artefactos vivos. Instrumenta los traces de los agentes. Automatiza la sincronía. Convierte la intención en datos auditable.

    Instala la plomada. Pruébala en una rama pequeña. Verás cómo las discusiones pasan de “qué falló” a “qué decidimos y por qué”. Esa es la arquitectura que realmente escala cuando la IA entra en la ecuación.

    Dominicode Labs

    Para equipos interesados en experimentar con patrones de sincronización y captura de decisiones, Dominicode Labs ofrece recursos y experimentos relacionados que pueden servir como continuación lógica a este enfoque.

    FAQ

    ¿Qué es la desincronización arquitectónica?

    La desincronización ocurre cuando spec, tests y código divergen: decisiones implementadas no reflejadas en la spec o tests, cambios en tests que no documentan intención, o commits sin trazabilidad. Resulta en comportamiento no documentado y deuda técnica creciente.

    ¿Qué hace Plum?

    Plum revisa diffs y traces del agente al hacer commit, extrae decisiones técnicas, las presenta para aprobación humana y, si se aprueban, actualiza la spec y reporta gaps entre spec, tests y código. Además genera un archivo .jsonl con registro auditable de cada decisión.

    ¿Cómo integrar esto en mi pipeline?

    Incorpora la captura de decisiones en el paso de commit: ejecutar revisión automática de diffs y traces, bloquear merges si el sync falla, y mantener el registro .jsonl como fuente de verdad. Preferible integración con runners de tests compatibles (ej. pytest para la versión inicial de Plum).

    Limitaciones al usar Plum

    En su versión inicial está acoplado a pytest para análisis de coverage; la integración con otros runners requiere trabajo. Funciona mejor con specs que preceden al código y requiere aprobación humana para decisiones de negocio.

    ¿Qué conservar del proceso?

    Conserva la disciplina de escribir specs antes de código, cubrir casos límite en tests, capturar decisiones en cada commit y mantener el .jsonl como registro auditable.

    ¿Qué hago si detecto deuda técnica por agentes?

    Identifica los commits o decisiones sin trazabilidad, prioriza backfilling de specs y tests para las áreas críticas, y aplica bloqueo de merges hasta que el triángulo spec‑tests‑código vuelva a alinearse.

  • 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.