DOMINICODE

Tag: AI

  • Diseña interfaces con IA sin necesidad de diseño previo

    Diseña interfaces con IA sin necesidad de diseño previo

    UI/UX con IA: diseña interfaces profesionales sin saber diseñar

    Tiempo estimado de lectura: 3 min

    • Automatiza la entrega de UI conectando contratos de datos con generadores de componentes (ej. v0).
    • Diseño por prompt: define estructura, tipos y estados en el prompt para evitar deuda técnica.
    • Pipeline técnico: exporta componentes al repo, añade tests y linters, y orquesta workflows (ej. n8n).
    • Usa herramientas accesibles y tipado estricto para entregar interfaces reproducibles y auditables.

    UI/UX con IA: diseña interfaces profesionales sin saber diseñar. No es un titular rimbombante: es la forma práctica de pasar del boceto a componentes de producción en horas, manteniendo controles que evitan deuda técnica. Si eres desarrollador o fundador técnico, este artículo te da el camino concreto y reproducible.

    Resumen rápido (lectores con prisa)

    Definición: Generar UI tipada y exportable mediante modelos y herramientas que producen componentes (ej. v0).

    Cuándo usarlo: validar flujos rápido, iterar sin diseñador, o para MVPs y paneles internos.

    Por qué importa: acelera entregas manteniendo control técnico si se exige tipado, accesibilidad y tests.

    Cómo funciona: define contratos (TS/JSON), genera componentes por prompt, integra en repo, añade tests y orquesta workflows.

    UI/UX con IA: diseña interfaces profesionales sin saber diseñar — qué es y cuándo usarlo

    La IA ya no entrega solamente imágenes. Herramientas como v0 generan componentes React + Tailwind listos para importar. Si agregas un contrato de datos estricto y un pipeline claro, obtienes interfaces profesionales sin dominar Figma ni teoría tipográfica.

    Úsalo cuando:

    • Necesitas validar UX/flow rápido (MVP, panel interno).
    • Tienes control técnico para auditar el código generado.
    • Quieres iterar diseños sin depender de un diseñador en cada cambio.

    Evítalo si necesitas identidad visual muy distinta o dirección de arte avanzada.

    Herramientas clave (URLs y roles)

    • v0 — Generador UI: v0.dev
    • shadcn/ui — Sistema de componentes accesibles: ui.shadcn.com
    • Cursor — IDE asistido por IA para mantener contexto de repo: cursor.com
    • n8n — Orquestación y workflows: n8n.io
    • Supabase — Base de datos y auth: supabase.com
    • Anthropic / Claude — Modelos LLM para prompts estructurados: anthropic.com/docs

    Framework práctico: cómo hacerlo, paso a paso

    1) Define contratos de datos (TypeScript)

    • Archivo: ticket.types.ts, por ejemplo.
    • Ejemplo:
    interface Ticket { id: string; status: 'pending'|'active'|'cancelled'; amount: number; createdAt: string; logs?: string[] }

    Beneficio: cualquier UI generada consume tipos reales y no inventa propiedades.

    2) Crea el prompt técnico (Design‑by‑Prompt)

    Elementos del prompt:

    • Estructura: grid/columns, sidebar, header.
    • Contrato de datos: incluye el TypeScript o JSON schema.
    • Estados: loading skeleton, empty state, error state.
    • Accesibilidad: aria-labels, contraste AA.

    “Genera un componente React/TSX en Next.js + Tailwind que muestre un Dashboard con sidebar y tabla. Consume Tickets[] con {id,status,amount,createdAt}. Incluye skeleton loader, estado vacío con CTA y badges semánticos para status. Usa componentes shadcn/ui.”

    3) Scaffolding en v0

    • Pega el prompt en v0 y itera visualmente.
    • Exporta el componente como módulo importable.
    • Resultado: componentes tipados y estilizados con Tailwind, listos para conectar.

    4) Integra y sustituye mocks

    • Importa a tu repo.
    • Sustituye datos mock por hooks (React Query, useSWR) o Server Components.
    • Conecta a Supabase si necesitas datos reales.

    5) Cablea la lógica compleja en Cursor

    • Usa Cursor para que el agente genere tests unitarios (Vitest) y funciones que mantengan firmas.
    • Flujo: tests → fallan → implementación hasta pasar tests. TDD evita parches.

    6) Orquesta y despliega

    • Para pipelines (forms, uploads) usa n8n.
    • Añade validación en el extremo antes de persistir para evitar corrupción de datos.
    • Versiona workflows y exporta JSON al repo.

    Reglas prácticas para evitar deuda técnica

    • Tipado por delante: siempre. Si la UI no consume tus tipos, romperá en producción.
    • Prompt como contrato: incluye schema JSON/TS en el prompt.
    • Accesibilidad no negociable: pide aria y contraste AA.
    • Exporta código generado al repo y revísalo en CI con linters y tests.
    • Versiona prompts y componentes como plantillas en tu monorepo.

    Ejemplo de prompt minimalista (plantilla reutilizable)

    “Instrucciones: genera un componente TSX para Next.js que reciba prop tickets: Ticket[] (adjunto el TypeScript). Layout: sidebar izquierdo, header con search, tabla paginada. Estados: loading skeleton, empty state con CTA ‘Crear ticket’. Accesibilidad: aria-labels, keyboard navigation. Estilo: Tailwind + shadcn/ui.”

    Pega esto en v0 y ajusta el contrato según tu dominio.

    Límites y responsabilidad del técnico

    La IA entrega ejecución; tú defines criterio. Los modelos saturan el espacio de soluciones probadas (estilo SaaS), lo que es ideal para MVPs y herramientas internas. No esperes creatividad de marca radical ni decisiones estratégicas de UX. El diseñador del futuro para productos técnicos es quien define métricas, flujos y prioridades; la IA ejecuta la capa visual.

    Implementar UI/UX con IA acelera validación y reduce costes, pero obliga a una disciplina técnica: contratos, tests y revisiones. Hazlo bien: define tipos, genera componentes, integra, prueba y versiona. Y repite. Esto no acaba aquí; convierte estas plantillas en cultura de producto y haz que el diseño generado trabaje para tus métricas.

    Para equipos interesados en aplicar automatización, agentes y workflows en pipelines de UI/UX con IA, vea los experimentos y plantillas de Dominicode Labs. Es una continuación natural para quien integra herramientas como n8n o Cursor en sus procesos.

    FAQ

    ¿Qué tipo de proyectos son adecuados para UI/UX con IA?

    Proyectos orientados a MVPs, herramientas internas y paneles administrativos son los más adecuados. Requieren rapidez de validación y control técnico para auditar el código generado.

    ¿Cómo evito deuda técnica con UI generado por IA?

    Define contratos de datos (TS/JSON) antes de generar UI, exige estados (loading/empty/error), añade tests y linters en CI, y revisa el código exportado al repo.

    ¿Qué herramientas debo priorizar en el stack?

    Prioriza generadores de UI tipados (v0), sistemas de componentes accesibles (shadcn/ui), un backend con auth/DB (Supabase) y herramientas de orquestación (n8n).

    ¿Es necesario un diseñador si uso IA para UI?

    No siempre. Para entregas técnicas y rápidas un equipo con criterio y tipos puede prescindir de un diseñador. Para identidad de marca y dirección de arte avanzada sí se necesita un diseñador.

    ¿Cómo asegurar accesibilidad en componentes generados?

    Incluye requisitos de accesibilidad en el prompt (aria-labels, contraste AA), usa componentes accesibles (ej. shadcn/ui) y añade pruebas automatizadas que verifiquen etiquetas y navegación por teclado.

    ¿Cuál es el flujo mínimo viable para integrar componentes generados al repo?

    Flujo mínimo: 1) definir tipos; 2) generar componente en v0 con el prompt; 3) exportar al repo; 4) reemplazar mocks por hooks; 5) añadir tests y CI.

  • Cómo utilizar Angular MCP Tools Read-Only para mejorar tu flujo de trabajo

    Cómo utilizar Angular MCP Tools Read-Only para mejorar tu flujo de trabajo

    Angular MCP Tools: Read-Only RAG e Inspectors

    Tiempo estimado de lectura: 4 min

    • Inspección primero: agentes que leen y razonan antes de proponer cambios.
    • Read-Only RAG: evita escrituras automáticas y exige trazabilidad técnica.
    • Inspectors prácticos: seis herramientas diseñadas para entender monorepos Angular y recomendar con contexto.
    • Flujo recomendado: list_projects → get_best_practices → search_documentation antes de aceptar PRs.

    Introducción

    ¿Quieres que un agente de IA deje de romper tu repo y empiece a trabajar como un colega inteligente? Entonces presta atención: las Angular MCP Tools no son un juguete, son el sentido común aplicado a la colaboración entre LLMs y bases de código Angular.

    Resumen rápido (lectores con prisa)

    MCP (Model Context Protocol) para Angular: agentes que inspeccionan repos antes de proponer cambios. El subconjunto Read-Only RAG & Inspectors viene activado por defecto: lee, razona y recomienda, sin escribir. Úsalo para obtener recomendaciones trazables y alineadas con la versión del proyecto.

    Qué es esto en una línea

    MCP (Model Context Protocol) + herramientas específicas para Angular = agentes que primero leen y entienden tu proyecto antes de proponer código. El subconjunto Read-Only RAG & Inspectors viene activado por defecto: lee, razona, recomienda. No escribe nada sin permiso.

    Por qué importa

    Porque los LLMs bien entrenados siguen fallando cuando no entienden topologías reales: monorepos, versiones mezcladas, patrones legacy. Aquí no se trata de velocidad, sino de coherencia y seguridad. En vez de “generar y rezar”, el agente inspecciona y explica sus sugerencias con referencias trazables.

    La suite Read-Only: Inspectors

    La suite de inspectores Read-Only incluye seis herramientas prácticas. Úsalas en orden o según la necesidad. Todas buscan hacer que la IA actúe como un ingeniero senior que conoce tu repo.

    1) list_projects — Descubre la topología del monorepo

    Qué hace: mapea apps, librerías y fronteras del workspace (Nx, Angular CLI, etc.).

    Por qué importa: evita que la IA proponga cambios en la librería equivocada o que recomiende imports que rompen dependencias.

    Práctica: pídele al agente “list_projects” y revisa el mapa antes de aceptar cualquier PR sugerido.

    Docs útiles: nx.dev, angular.io

    2) get_best_practices — Inyecta reglas alineadas a la versión

    Qué hace: detecta la versión de Angular y carga reglas (p. ej. cuándo usar Standalone Components vs NgModules).

    Por qué importa: previene que te sugieran patrones obsoletos.

    Práctica: ejecuta get_best_practices antes de aceptar snippets generados.

    3) search_documentation — Consultas en vivo contra angular.dev

    Qué hace: realiza búsquedas en la documentación oficial en tiempo real y adjunta referencias.

    Por qué importa: elimina alucinaciones técnicas del modelo.

    Práctica: exige que cualquier recomendación venga con el enlace a la sección de la doc (p. ej. angular.io o angular.dev).

    4) find_examples — Base de ejemplos modernos y validados

    Qué hace: recupera patrones de implementación contemporáneos (Signals, reactive forms modernos, composición con inject()).

    Por qué importa: evita soluciones “copy-paste” de 2016.

    Práctica: pide ejemplos concretos y compara con tu arquitectura antes de adaptar código.

    5) ai_tutor — Personas de coaching con RAG

    Qué hace: arranca un “persona” contextual: mentor junior, code reviewer, o arquitecto.

    Por qué importa: adapta la profundidad de la explicación según quien pregunte.

    Práctica: usa ai_tutor para onboarding técnico: deja que el tutor genere una mini guía de cambios antes de ejecutarlos.

    6) onpush_zoneless_migration — Analiza compatibilidad zoneless

    Qué hace: inspecciona componentes para detectar riesgos al migrar fuera de zone.js (ChangeDetectionStrategy, suscripciones, side effects).

    Por qué importa: la migración zoneless puede romper renderizado en bordes finos; conviene planear.

    Práctica: ejecuta este inspector y revisa los hallazgos con un dev senior. Referencia: github.com/angular/zone.js

    Un flujo práctico de trabajo (mini checklist)

    • 1) list_projects: entiende el repo.
    • 2) get_best_practices: fija reglas por versión.
    • 3) search_documentation: valida APIs oficiales.
    • 4) find_examples: trae patrones comprobados.
    • 5) ai_tutor: genera explicación para tu equipo.
    • 6) onpush_zoneless_migration: si planeas ir zoneless, ejecuta auditoría.

    Consejos de criterio técnico (no obviedades)

    • No des permisos de escritura hasta que el agente haya corrido list_projects y get_best_practices.
    • No confíes ciegamente en migraciones zoneless: son útiles, pero experimentalidad y casos límite existen.
    • Exige trazabilidad: cada recomendación debe traer el fragmento de doc o ejemplo (URL incluido).
    • Integra estas herramientas en pipelines de revisión (p. ej. n8n.io o flujos de CI) para mantener trazabilidad y auditoría.

    Qué ganarás realmente

    Velocidad no es la métrica. Ganarás coherencia entre código y arquitectura, menos deuda técnica introducida por sugerencias automáticas y mayor confianza para delegar revisiones automáticas en la IA —siempre con controles.

    No es magia, es disciplina

    El Read-Only RAG no limita a la IA: la pone en su lugar. Primero inspecciona, luego propone. Tu trabajo es aplicar criterio humano en la etapa final. Si lo haces, el agente deja de ser un generador de snippets y se convierte en un asistente técnico con contexto real.

    Haz esto ahora

    En tu siguiente sesión con el agente, obliga este orden: list_projects → get_best_practices → search_documentation. Si quieres, pásame el resultado y te devuelvo un plan de migración o un checklist de PRs. Apúntalo: la IA que entiende tu repo es la que te ahorra horas y noches de debugging.

    Dominicode Labs

    Si integras estas herramientas en flujos de automatización y revisión, puede ser útil explorar recursos y experimentos continuos en Dominicode Labs. Considera Dominicode Labs como una continuación lógica para prototipado de pipelines y auditorías técnicas.

    FAQ

    ¿Qué hace exactamente list_projects?

    list_projects mapea apps, librerías y fronteras del workspace (por ejemplo Nx o Angular CLI) para mostrar la topología del monorepo y prevenir cambios en lugares incorrectos.

    ¿Cuándo debo ejecutar get_best_practices?

    Ejecuta get_best_practices al inicio de una auditoría o antes de aceptar snippets generados para alinear recomendaciones a la versión de Angular y evitar patrones obsoletos.

    ¿Cómo evita search_documentation las alucinaciones?

    Realiza búsquedas en la documentación oficial en tiempo real y adjunta referencias verificables (por ejemplo angular.io), lo que obliga al agente a justificar sus sugerencias.

    ¿Qué tipos de ejemplos trae find_examples?

    Recupera patrones modernos y validados, como uso de Signals, formularios reactivos modernos y composición con inject(), para evitar soluciones anticuadas.

    ¿Para qué sirve ai_tutor en un equipo?

    ai_tutor crea una persona contextual (mentor, code reviewer, arquitecto) que adapta la profundidad de la explicación y puede generar guías de cambios para onboarding o revisiones.

    ¿Qué riesgos detecta onpush_zoneless_migration?

    Analiza compatibilidad zoneless y detecta riesgos relacionados con ChangeDetectionStrategy, suscripciones y efectos secundarios que pueden romper renderizado fuera de zone.js. Referencia: github.com/angular/zone.js

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

  • Desarrollo de un MVP funcional en 48 horas utilizando IA

    De la idea al MVP en un fin de semana usando solo IA (caso real)

    Tiempo estimado de lectura: 4 min

    Ideas clave

    • Contratos primero: escribir tipos/JSON schema/SQL antes de lógica reduce alucinaciones y facilita parsing.
    • Secuencia reproducible: Specification‑Driven Development → generación UI → TDD asistido por modelos → orquestación.
    • Herramientas: usar Cursor, v0, n8n, Supabase y Anthropic cuando puedas auditar y tolerar llamadas a APIs externas.
    • Entregables en 48h: webhook → LLM → DB y dashboard tipado con tests básicos.

    Introducción

    De la idea al MVP en un fin de semana usando solo IA (caso real). No es marketing; es un flujo reproducible que combina Specification‑Driven Development, generación de UI, desarrollo asistido por modelos y orquestación visual. Si aplicas la secuencia correcta, una sola persona puede entregar un MVP funcional y mantenible en 48 horas.

    Úsalas cuando tengas control técnico y urgencia de validación. Evítalas si no puedes auditar el código generado o si las políticas de seguridad prohíben exfiltrar datos a APIs externas.

    Resumen rápido (lectores con prisa)

    Definición: un flujo reproducible para convertir una idea en MVP en 48 horas usando IA y contratos.

    Cuándo usarlo: cuando necesitas validar rápido y puedes auditar código/llamadas a APIs externas.

    Por qué importa: reduce alucinaciones, crea artefactos tipados y pone guardrails mediante tests.

    Cómo funciona: escribir contratos primero → generar UI y backend asistidos por modelos → orquestar ingestión y persistencia con n8n.

    Viernes: contratos primero (Specification‑Driven Development)

    Contratos y artefactos iniciales

    La primera noche no se escribe “lógica”. Se escriben contratos.

    Crea un archivo TypeScript con los tipos del dominio. Ejemplo mínimo: ticket.types.ts

    • Campos de ejemplo:
      • urgency: “low” | “medium” | “critical”
      • userId: string
      • logs: string[]
      • metadata: Record<string,string>

    Define también el esquema SQL para Supabase y el JSON schema que el LLM debe devolver. Esto obliga a la IA a producir Structured Output; reduce alucinaciones y facilita el parsing.

    Decisiones prácticas

    • Usa Result<T, E> en funciones de persistencia para evitar exceptions no controladas.
    • Documenta casos límite (emails sin logs, attachments binarios) en el contrato.
    • Escribe tests de contrato simples (validación de forma) que actúen como guardrails.

    Sábado: frontend con v0 + backend con Cursor y TDD

    Frontend (v0)

    Divide el día en dos hilos paralelos.

    Prompt preciso: “Genera un dashboard Next.js + Tailwind con una tabla tipada Tickets[], sidebar oscuro, componente de logs con resaltado.”

    v0 entrega componentes listos para importar; evita reescribir CSS básico. Integra Server Components/SSR de Next.js si necesitas datos rápidos desde Supabase.

    Herramienta citada: v0

    Backend (Cursor + Claude + Vitest)

    Orden: generar tests → ver tests fallar → implementar hasta pasar tests (TDD).

    Pide a Cursor que lea los tipos y genere pruebas Vitest que cubran:

    • Validación de schema
    • Normalización de logs
    • Manejo de urgencia critical

    Usa Claude 3.7 Sonnet para implementar funciones que pasen los tests sin cambiar firmas.

    Resultado: código tipado, con cobertura mínima y sin “parches” manuales.

    Herramientas citadas: Cursor (IDE + LLM), Anthropic (Claude API), Vitest.

    La combinación TDD + Spec evita la deuda técnica típica de sprints rápidos: lo que sale ya tiene contratos y pruebas.

    Domingo: orquestación con n8n y despliegue mínimo

    Workflow n8n propuesto

    1. Webhook Trigger: recibe el payload del proveedor de correo.
    2. Nodo LLM (Anthropic/GPT): prompt que obliga a Structured JSON según ticket.types.ts.
    3. Code/DB Node: valida JSON, transforma y upsert en Supabase.
    4. Error Trigger Workflow: si el LLM devuelve formato inválido o la inserción falla, guarda el payload en una tabla de errores y alerta por Slack.

    Buenas prácticas n8n:

    • Retries exponenciales y circuit breaker en llamadas HTTP.
    • Validación estricta antes de la inserción para evitar corrupción de datos.
    • Versiona los workflows exportando el JSON al repo (infra-as-code).

    Despliegue mínimo

    • Supabase para DB y autenticación. Herramienta citada: Supabase
    • Vercel para frontend.
    • n8n en una instancia Docker (o n8n Cloud si no quieres infra). Herramienta citada: n8n
    • Monitor básico: health check cron en n8n que verifique endpoints y envíe alertas a PagerDuty/Slack.

    Resultados y aprendizajes del caso real

    En 48 horas se obtuvo:

    • Webhook activo y pipeline LLM → DB.
    • Dashboard funcional con tickets tipados.
    • Suite básica de tests que evita regresiones inmediatas.

    Lecciones claras

    • Contratos + TDD son imprescindibles cuando delegas generación de código a modelos.
    • v0 y Cursor reducen horas de trabajo repetitivo, no la necesidad de criterio técnico.
    • n8n convierte integraciones en piezas mantenibles si añades manejo de errores y versionado.

    Próximo paso: convertirlo en repetible

    No te quedes con un MVP aislado. Exporta tus tipos, workflows y prompts como plantillas en tu repo. Automatiza despliegues y crea un playbook para replicar este flujo en futuros proyectos. La IA te acelera la ejecución; el criterio define el producto que sobrevive.

    Mención: Dominicode Labs

    Si buscas plantillas y playbooks para automatización, orquestación y workflows reproducibles, considera este recurso como continuación lógica de este flujo: Dominicode Labs.

    La mención está situada para ser una extensión práctica — plantillas, prompts y ejemplos aplicables a pipelines LLM → DB → UI.

    FAQ

    ¿Qué herramientas se usaron en el caso real?

    Se mencionaron Cursor (https://www.cursor.com), v0 (https://v0.dev), n8n (https://n8n.io), Supabase (https://supabase.com) y Anthropic (https://www.anthropic.com/docs).

    ¿Por qué escribir contratos primero?

    Porque obliga a la IA a entregar Structured Output, reduce alucinaciones y facilita la validación y los tests automáticos.

    ¿Cuándo no deberías usar este enfoque?

    Evítalo si no puedes auditar el código generado o si las políticas de seguridad prohíben exfiltrar datos a APIs externas.

    ¿Cómo aplicar TDD con modelos?

    Genera tests primero (Vitest), observa fallos, pide a la IA que implemente funciones respetando firmas hasta pasar tests. Mantén firmas y contratos estables.

    ¿Qué debe incluir el workflow de n8n?

    Webhook trigger, nodo LLM que obliga a JSON estructurado, validación/transformación y upsert en Supabase, y un flujo de errores que persista fallos y notifique por Slack.

    ¿Cómo manejar errores y retries?

    Implementa retries exponenciales, circuit breaker en llamadas HTTP y valida estrictamente antes de insertar en la base de datos.

    ¿Qué entregables esperar en 48 horas?

    Un webhook activo con pipeline LLM → DB, un dashboard tipado y una suite básica de tests que cubra casos críticos.

  • 5 workflows de n8n para optimizar la productividad en startups

    5 workflows de n8n para optimizar la productividad en startups

    5 workflows de n8n que todo emprendedor debería tener corriendo hoy

    Tiempo estimado de lectura: 4 min

    • Ideas clave
    • Automatiza tareas repetitivas críticas: soporte, leads, pagos, health checks y ETL nocturno.
    • Usa una instancia autoalojada de n8n cuando manejes PII o necesites control total.
    • Activa siempre un Error Trigger Workflow para capturar fallos silenciosos y generar alertas automáticas.
    • Versiona workflows como JSON en tu repo y protege endpoints y secretos con vaults o allowlists.

    Introducción

    Si tienes una startup técnica, cada minuto que pasas contestando correos, conciliando pagos o pegando datos en hojas de cálculo es tiempo robado al producto. Aquí tienes los 5 workflows de n8n que todo emprendedor debería tener corriendo hoy: flujos prácticos, probados y diseñados para reducir trabajo manual, mejorar la fiabilidad y proteger tus datos. Implementarlos tarda horas; el retorno es inmediato. Antes de entrar en cada flujo: usa una instancia autoalojada de n8n siempre que manejes PII o quieras control total. Activa el Error Trigger Workflow en cada flujo para capturar fallos silenciosos (timeouts, cambios de contrato en APIs) y generar alertas automáticas.

    Resumen rápido (lectores con prisa)

    Qué: Cinco workflows operativos para soporte, enriquecimiento de leads, pagos, monitorización y ETL.

    Cuándo usar: Desde el primer equipo con usuarios activos y facturación recurrente.

    Por qué importa: Reduce trabajo manual, baja churn y asegura continuidad operativa.

    Cómo funciona (breve): Triggers (webhooks/schedule/IMAP) → procesamiento (LLMs, búsqueda vectorial, HTTP) → acciones (CRM, tickets, emails, DB).

    5 workflows de n8n que todo emprendedor debería tener corriendo hoy

    1) Triaje de soporte asistido por IA (Agente de operaciones)

    • Objetivo: Soporte rápido y bien clasificado para reducir churn y evitar interrupciones de los ingenieros.
    • Arquitectura mínima:
    • Trigger: nodo IMAP o Webhook (formularios).
    • Procesamiento: nodo LLM (por ejemplo, Claude 3.7 Sonnet via Anthropic o GPT-4o) con prompt estricto para extraer urgencia, categoría y metadatos (user_id, plan).
    • Enriquecimiento: búsqueda en base vectorial (documentación interna).
    • Acción: crear ticket en Jira/HubSpot o enviar alerta a Slack/Canal de emergencias.

    Resultado: tickets críticos escalados en <2 minutos; respuestas a FAQs generadas automáticamente y guardadas como borradores en el CRM.

    2) Enriquecimiento automático de leads B2B

    • Objetivo: Convertir un email en un perfil accionable para priorización comercial instantánea.
    • Arquitectura mínima:
    • Trigger: inserción en DB (Supabase/Postgres) o webhook de formulario.
    • Llamada: HTTP Request a un servicio de enriquecimiento (ej. Clearbit).
    • Transformación: nodo Code (JavaScript) que normaliza y filtra campos.
    • Acción: upsert en CRM y notificación a Sales si es Enterprise.

    Esto convierte leads fríos en perfiles accionables y reduce la fricción del SDR al 0.

    3) Ciclo de vida de pagos con Stripe (recuperación y facturación)

    • Objetivo: Automatizar cobros, reintentos y envío de recibos para bajar churn y limpieza contable.
    • Arquitectura mínima:
    • Trigger: webhook de Stripe para eventos invoice.payment_succeeded / invoice.payment_failed.
    • Lógica: nodo Switch para bifurcar según evento; en fallos, programar reintentos y enviar correos de recuperación personalizados; en éxitos, generar PDF de recibo (HTML→PDF).
    • Acción: enviar recibo por SendGrid/AWS SES y registrar la transacción en tu contabilidad.

    Beneficio: menos churn por pagos fallidos y documentación fiscal automática.

    4) Health check y alertas proactivas (DevOps liviano)

    • Objetivo: Detectar regresiones antes de que los usuarios las noten.
    • Arquitectura mínima:
    • Trigger: Schedule cada 1–5 minutos.
    • Checks: HTTP Request a endpoints críticos y consultas básicas a DB.
    • Evaluación: nodo If con umbrales (status ≠ 200, latencia > 1500ms).
    • Acción: alerta a PagerDuty/SMS/Slack con contexto (endpoint, status, respuesta).

    Este workflow detecta regresiones y documenta incidentes automáticamente.

    5) ETL nocturno para métricas de negocio (MRR, churn, CAC)

    • Objetivo: Consolidar métricas clave para decisiones informadas.
    • Arquitectura mínima:
    • Trigger: Schedule nocturno (ej. 02:00).
    • Extracción paralela: Postgres (usuarios), Stripe (ingresos), Google Analytics (tráfico).
    • Transformación: nodo Merge + nodo Code para calcular MRR, churn, LTV, CAC.
    • Acción: insertar en tabla de BI o enviar reporte matutino al equipo.

    No necesitas Airflow ni invertir en data infra compleja; n8n cubre la fase inicial con credibilidad analítica.

    Buenas prácticas y consideraciones técnicas

    • Controla la latencia: usa retries exponenciales y circuit breakers en llamadas HTTP para evitar cascadas.
    • Versiona los workflows: exporta y guarda los JSON de cada flujo en tu repo (infra-as-code para n8n).
    • Seguridad: cuando autoalojes n8n, protege endpoints con VPN o IP allowlists y almacena secretos en un vault.
    • Monitoreo de costos: para integraciones pagas (Clearbit, Stripe), aplica caching y límites para no disparar facturas.
    • Documenta contratos: cada trigger debe tener un contrato de entrada claro (schema). Si cambian las APIs externas, el Error Trigger Workflow debe notificar al canal de desarrollo.

    Recursos y enlaces

    Automatizar estos cinco procesos no te convierte en menos técnico; te vuelve más efectivo. Configura los workflows, prueba los casos límite y deja que las máquinas hagan lo repetitivo. Lo que queda será trabajo de alto valor: producto, estrategia y mejoras que realmente importan. Convierte estos flujos en plantillas reproducibles para tu equipo y haz de la automatización parte de la cultura operativa.

    Continúa la implementación y experimentación con plantillas y control de versiones en tu repo. Para recursos y prototipos experimentales relacionados con automatización y agentes, revisa Dominicode Labs como continuación lógica de esta práctica.

    FAQ

    ¿Por qué autoalojar n8n en lugar de usar la nube gestionada?

    Autoalojar te da control sobre datos sensibles (PII), permite aplicar políticas de red (VPN/IP allowlists) y elegir dónde se almacenan secretos. Es la opción recomendada si cumples regulaciones o quieres evitar dependencias externas para datos críticos.

    ¿Qué es un Error Trigger Workflow y cómo lo configuro?

    Un Error Trigger Workflow es un flujo que captura fallos emitidos por otros workflows (timeouts, errores de contrato, cambios en APIs). Configúralo como destino de notificaciones de error en cada workflow y envía alertas a un canal de DevOps o a PagerDuty.

    ¿Cómo integras un LLM sin filtrar PII?

    Filtra o tokeniza PII antes de enviarla al LLM; usa entornos autoalojados para model serving cuando sea necesario. Aplica prompts que no soliciten datos sensibles y audita logs para confirmar que no se exporta información prohibida.

    ¿Cuándo conviene generar recibos como PDF vs simplemente enviar email?

    Genera PDF cuando necesitas documentación fiscal, firmas o archivado formal. Para comunicaciones transaccionales simples, el email con contenido HTML suele ser suficiente y más barato.

    ¿Cómo evitar costos inesperados con APIs pagas?

    Implementa caching de respuestas, límites de llamada y lógica de backoff. Monitoriza uso y facturación y aplica reglas en los workflows para bloquear solicitudes si superan umbrales de coste.

    ¿Cuál es la mejor práctica para versionar workflows en equipo?

    Exporta workflows como JSON y guárdalos en el repo. Mantén ramas por feature, revisiones PR y tags de versión. Documenta schemas de entrada y salida para cada trigger.

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

  • Cómo SDD y TDD optimizan el desarrollo con Claude Code

    Cómo SDD y TDD optimizan el desarrollo con Claude Code

    SDD + TDD: el combo que convierte a Claude Code en un dev senior

    Tiempo estimado de lectura: 4 min

    • SDD reduce las decisiones del agente; TDD valida de forma determinista.
    • Especificación primero, tests después: contratos claros y criterios ejecutables.
    • Aplica cuando hay lógica crítica, APIs públicas y repositorios tipados.

    Introducción

    SDD + TDD: el combo que convierte a Claude Code en un dev senior. Poca gente lo practica en equipos que prueban agentes, y sin embargo es la diferencia entre recibir código usable o un cajón de sorpresas que rompe en producción.

    Claude Code (motor basado en Claude 3.7 Sonnet) puede leer tu repo, ejecutar comandos y escribir código. Genial. También puede inventar abstracciones, tocar capas que no debe y aplicar convenciones que no son las tuyas. La solución no es pedir menos; es pedir mejor: especificación primero, tests después.

    Resumen rápido (lectores con prisa)

    SDD = especificaciones codificadas (tipos, interfaces, reglas). TDD = tests que hacen las especificaciones ejecutables. Juntos reducen la improvisación del agente y transforman código generado en artefactos verificables y mantenibles.

    Por qué SDD + TDD: el combo que convierte a Claude Code en un dev senior

    Un modelo de lenguaje es, por naturaleza, probabilístico. Sin restricciones explícitas, el agente construirá “la versión más probable” de tu feature, no la versión correcta para tu sistema. SDD (Specification-Driven Development) fuerza el contrato: tipos, firmas, reglas y límites. TDD (Test-Driven Development) convierte esos contratos en criterios ejecutables: rojo, verde, refactor.

    Juntos funcionan así:

    • SDD reduce el espacio de decisiones del agente.
    • TDD da un criterio determinista para validar el trabajo.
    • Claude Code deja de improvisar y se limita a cumplir pruebas que tú definiste.

    Referencias útiles: Anthropic (Claude) docs, TDD (Martin Fowler).

    Qué debe incluir una SDD práctica para agentes

    No es un brief largo: es el mínimo necesario para quitar decisiones al modelo.

    • Tipos e interfaces visibles en código
      TypeScript: exporta types / interfaces antes de pedir implementación. (TypeScript: docs)
      Python: define modelos Pydantic para entradas/salidas. (Pydantic)
    • Reglas explícitas de efectos secundarios
      “Función pura — sin DB, sin llamadas HTTP” o “Permitido: escribir en tabla payments; Prohibido: llamar a servicios externos”.
    • Manejo de errores y contratos de retorno
      `Result<T, E>` vs excepciones. Si decides una convención, documenta y hazla código.
    • Casos límite documentados
      Inputs inválidos, límites numéricos, retries, timeouts, políticas de deduplicación.

    Escribe esto en archivos que el agente pueda leer (por ejemplo *.types.ts, *.schema.py, .md con reglas) y no lo dejes solo en un prompt.

    El ciclo TDD que hace verificable al agente

    Con la spec lista, el flujo TDD para Claude Code es práctico y repetible:

    • Fase Roja — Generar tests.
      Prompt: claude “Lee payment.types.ts y las reglas en comments. Genera tests en Vitest que cubran todos los casos límite. Ejecuta los tests y reporta fallos.”
      Resultado esperado: tests fallando (porque no hay implementación).
    • Fase Verde — Implementación mínima.
      Prompt: claude “Implementa payment.ts respetando los tipos. Ejecuta los tests y corrige hasta que pasen en verde. No cambies firmas ni añadas dependencias externas.”
    • Refactor — Mejorar con seguridad.
      Prompt: claude “Refactoriza para reducir la complejidad ciclomática, manteniendo todos los tests en verde.”

    Herramientas recomendadas para el ciclo: Vitest o Jest, integradas en la terminal que usa Claude Code.

    Ejemplo práctico (resumen)

    En vez de: “Crea validación de email”, escribe:

    • types.ts:
      – interface CreateUser { email: string; name?: string }
      – type Result = { ok: true; value: T } | { ok: false; error: string }
    • Comentario en createUser.ts:
      // Función pura. Rechaza dominios genéricos (gmail.com, hotmail.com). Retorna Result. No lanza excepciones.
    • Prompts:
      • Genera tests → ejecuta → confirma fallo.
      • Implementa hasta pasar tests → refactor.

    La diferencia es mínima en tiempo de setup y enorme en predictibilidad.

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

    Aplica SDD + TDD cuando:

    • Construyes lógica de negocio crítica o APIs públicas.
    • Trabajas en repositorios compartidos y tipados.
    • Necesitas trazabilidad y responsabilidad en cambios.

    No lo apliques para:

    • Scripts one-off o hacks exploratorios.
    • Prototipos que requieren máxima velocidad de experimentación.

    Lo que cambian estas prácticas en tu equipo

    La escritura de código se convierte en commodity; el verdadero valor pasa a:

    • Diseñar contratos claros.
    • Anticipar edge cases.
    • Traducir decisiones de producto a reglas verificables.

    Claude Code seguirá escribiendo código — pero ahora ese código será verificable y, lo que es más importante, mantenible. Si defines la partitura (SDD) y pones el metrónomo (TDD), el agente tocará afinado.

    Fuentes y lectura recomendada

    FAQ

    ¿Qué es SDD y en qué se diferencia de un brief tradicional?

    SDD (Specification-Driven Development) codifica las decisiones clave —tipos, interfaces, reglas de efectos secundarios— en artefactos que el agente puede leer. Un brief tradicional suele ser texto libre; SDD es código y contrato.

    ¿Por qué es necesario TDD cuando uso un agente capaz de ejecutar tests?

    TDD transforma la especificación en criterios ejecutables (tests). Sin tests, el agente puede producir la solución más probable; con tests, debe producir la solución que pasa los criterios que definiste (rojo → verde → refactor).

    ¿Qué archivos debo incluir en la SDD para que el agente los use?

    Archivos legibles por el agente: *.types.ts, *.schema.py, y .md con reglas y comentarios. Define tipos, modelos y reglas de efectos secundarios en esos archivos.

    ¿Puedo usar este flujo con agentes distintos a Claude Code?

    Sí. El patrón SDD + TDD es aplicable a agentes que puedan leer repositorios y ejecutar comandos. Se basa en contratos verificables y tests automatizados, no en peculiaridades de un motor concreto.

    ¿Qué herramientas recomiendan para ejecutar el ciclo TDD?

    Herramientas recomendadas: Vitest o Jest. Integradas en la terminal del agente para ejecutar fases Roja/Verde/Refactor.

    ¿Cómo manejo cambios de contrato sin romper downstream?

    Versiona tipos y contratos, introduce migraciones y añade tests de compatibilidad. Documenta cambios en la SDD y agrega pruebas que verifiquen compatibilidad hacia atrás cuando sea necesario.

    ¿Cuándo NO debo aplicar SDD + TDD?

    No lo apliques para scripts one-off, hacks exploratorios o prototipos donde la prioridad es iterar rápido sin garantías fuertes.

  • Implementación de Managed Agents en la Plataforma de Anthropic

    Implementación de Managed Agents en la Plataforma de Anthropic

    Anthropic lanzó Managed Agents — agentes de largo plazo en la plataforma

    Tiempo estimado de lectura: 4 min

    • Managed Agents mueve la responsabilidad de ejecutar agentes de largo plazo desde tu infraestructura hacia la plataforma de Anthropic.
    • Proporciona primitivas críticas: sesiones estables, sandboxes con estado duradero, harnesses de ejecución y gestión segura de herramientas/credenciales.
    • La Rate Limits API permite orquestar y escalar controlando capacidad disponible antes de lanzar trabajos.
    • Patrón práctico: usar un orquestador (ej. n8n) para desacoplar el lanzamiento y la finalización de las sesiones agénticas.
    • Riesgos: vendor lock-in, observabilidad limitada, fuga de datos temporales y límites de tasa; requieren políticas y controles explícitos.

    Introducción

    Anthropic lanzó Managed Agents — agentes de largo plazo en la plataforma el 25 de abril de 2026. Esta funcionalidad en Claude Platform no es una mejora menor: cambia la responsabilidad operativa de ejecutar agentes agénticos prolongados desde tu infraestructura hacia la plataforma de Anthropic. Fuente: Anthropic Platform Docs

    Resumen rápido (lectores con prisa)

    Managed Agents ofrece sesiones estables, sandboxes con estado duradero, harnesses y gestión de herramientas/credenciales en la plataforma. Reduce engineering necesario para ejecutar agentes asíncronos largos y añade una Rate Limits API para orquestación segura. Útil cuando priorizas velocidad de entrega; no es apropiado si necesitas control forense total sobre ejecución y datos.

    Qué significa que Anthropic lanzó Managed Agents — agentes de largo plazo en la plataforma

    La noticia clave es de infraestructura, no de modelo. Managed Agents provee primitivas que antes tenías que inventar: sesiones estables, sandboxes con estado duradero, harnesses de ejecución y acceso seguro a herramientas. Eso corrige tres cuellos de botella clásicos de agentes autónomos en producción:

    • Persistencia de estado entre pasos (que evita reinyectar historial en cada request).
    • Aislamiento y ejecución segura de código (sandboxes duraderos).
    • Gestión segura de credenciales y herramientas (Secure Tool Use).

    Estos elementos transforman agentes episódicos y frágiles en procesos asíncronos confiables que pueden correr horas sin reinyectar contexto manualmente.

    Componentes técnicos y por qué importan

    Interfaces estables para sesiones

    Managed Agents expone IDs de sesión y APIs para consultar su estado. Eso permite diseños desacoplados: lanzas un agente, recibes un session_id y vuelves más tarde por el resultado. En prácticas reales esto reduce el acoplamiento entre orquestador (n8n, cron, Lambda) y ejecución agéntica.

    Harnesses y sandboxes con estado duradero

    El harness controla la inyección de prompts y la ejecución de herramientas; el sandbox es el runtime persistente donde sobreviven variables, artefactos y dependencias entre pasos. Esto elimina el cold-start continuo y permite construcciones incrementales (tests encadenados, scraping por lotes, refactors multi-archivo) sin retransmitir todo el contexto en cada llamada.

    Acceso seguro a herramientas

    Anthropic gestiona credenciales y permisos en la plataforma. El agente consume interfaces a servicios externos sin exponer secrets dentro del texto del prompt o logs de razonamiento. Es un requisito mínimo para producción: evita fugas accidentales de credenciales y facilita auditoría centralizada.

    Startup optimizado

    Reducir la latencia de arranque entre pasos cambia el coste operativo de tareas largas. Si tu agente ejecuta cientos de scripts por sesión, el ahorro acumulado en tiempo y coste es real y medible.

    Rate Limits API: control programático del escalado

    El 25 de abril Anthropic también lanzó la Rate Limits API, que permite consultar programáticamente los límites de tokens y uso de la organización. Si vas a orquestar docenas de agentes concurrentes, necesitas este dato antes de lanzar trabajos. Patrón operativo recomendado:

    • Consulta la Rate Limits API antes de encolar un agente.
    • Si la capacidad disponible es < 20% (umbral configurable), encola la tarea y reintenta más tarde.
    • Prioriza trabajos críticos y aplica un backoff exponencial en la cola.

    Ejemplo (pseudocurl): curl -H “Authorization: Bearer $ANTHROPIC_KEY” Rate Limits API

    Integración práctica con n8n (patrón de arquitectura)

    n8n es el orquestador natural para este enfoque. Patrón de integración:

    1. n8n recibe trigger (webhook, cron, evento).
    2. Llama a Rate Limits API; decide lanzamiento o encolado.
    3. Si hay cuota, invoca Managed Agent con contexto y guarda session_id.
    4. n8n cierra la ejecución; recibe webhook de finalización o consulta el estado con polling.
    5. Procesa y distribuye resultado (commit a Git, notificación Slack, inserción en DB).

    Este patrón desacopla totalmente el tiempo real de ejecución del agente del flujo orquestador, permitiendo escalado horizontal sin mantener hilos abiertos.

    Riesgos, límites y controles que debes imponer

    1. Vendor lock-in y compliance: durante la ejecución, código e inputs residirán en la plataforma de Anthropic. Para entornos regulados (SOC 2, HIPAA) exige SLA/Docs de retención y capacidad de auditoría antes de producción.
    2. Observabilidad y debugging: cuando una sesión falla dentro del sandbox, las herramientas forenses pueden ser menos ricas que en tu propio Kubernetes. Diseña checkpoints y exporta artefactos intermedios a tu almacenamiento controlado (S3 cifrado) con permisos limitados.
    3. Fugas de datos temporales: define políticas de redacción y minimización de datos en prompts; sanea PII antes de enviar a la plataforma.
    4. Rate limits y resiliencia: no asumas disponibilidad ilimitada. Implementa encolado, prioridad y backoff; monitoriza 429 y métricas de latencia.

    Cuándo delegar y cuándo no

    Delegar a Managed Agents tiene sentido cuando ahorrarás semanas de ingeniería en infra (sandboxes, orquestación, secretos) y necesitas fiabilidad en tareas asíncronas prolongadas. No lo uses si tu negocio requiere retención forense total o control absoluto sobre ejecución (por ejemplo, datos regulados que no pueden salir de tu red). En esos casos, preferir un cluster interno con un harness local y un modelo autohospedado —aunque más coste inicial— puede ser la opción correcta.

    Conclusión operativa

    Anthropic lanzó Managed Agents para abstraer la parte más aburrida y frágil de la ejecución agéntica: estado, aislamiento y herramientas. La plataforma acelera adopción, pero no elimina la responsabilidad del equipo: gobernanza, observabilidad y políticas de datos siguen siendo necesarias. Integra la Rate Limits API, usa un orquestador (n8n) para desacoplar, y define reglas rígidas de handoff, checkpoints y retención para evitar que un avance operativo se convierta en una deuda técnica costosa.

    Si quieres explorar patrones de integración y pruebas alrededor de orquestación y agentes, consulta Dominicode Labs para recursos y ejemplos prácticos que complementan este enfoque.

    FAQ

    ¿Qué son Managed Agents y cuándo se lanzaron?

    Managed Agents son agentes de largo plazo gestionados por la plataforma de Anthropic; la funcionalidad fue lanzada el 25 de abril de 2026.

    ¿Qué problemas resuelven Managed Agents?

    Resuelven persistencia de estado entre pasos, aislamiento y ejecución segura (sandboxes), harnesses para ejecutar herramientas y gestión segura de credenciales, reduciendo la necesidad de infraestructura propia para agentes asíncronos largos.

    ¿Cómo ayuda la Rate Limits API a la orquestación?

    La Rate Limits API permite consultar los límites de tokens y uso organizacional de forma programática, lo que te deja decidir antes de encolar o lanzar agentes y aplicar encolado/prioridad/backoff cuando la capacidad es limitada.

    ¿Por qué usar n8n con Managed Agents?

    n8n sirve como orquestador desacoplado: recibe triggers, consulta Rate Limits API, lanza Managed Agents guardando session_id y luego procesa resultados con webhooks o polling, evitando mantener hilos abiertos y facilitando escalado horizontal.

    ¿Cuáles son los riesgos principales a considerar?

    Riesgos clave: vendor lock-in y requisitos de compliance, menor observabilidad forense dentro del sandbox, posible fuga de datos temporales y dependencia en límites de tasa; se requieren políticas, checkpoints y exportación controlada de artefactos.

    ¿Cuándo no es recomendable delegar en Managed Agents?

    No delegues si tu negocio exige retención forense total o control absoluto sobre la ejecución y datos (por ejemplo, datos regulados que no pueden salir de tu red). En esos casos, considera un cluster interno con harness local y modelo autohospedado.

  • Cómo orquestar subagentes de IA para un desarrollo eficaz

    Cómo orquestar subagentes de IA para un desarrollo eficaz

    Subagentes como equipo de desarrollo: orquestación con Claude Code

    Tiempo estimado de lectura: 4 min

    Ideas clave

    • Plan, delega, commit, valida: estructura que convierte a un asistente en un equipo con coordinador y subagentes.
    • Riesgos mitigados: degradación de contexto, decisiones implícitas y falta de trazabilidad.
    • Regla de commit inquebrantable: cada subagente debe hacer un commit atómico antes de avanzar.
    • DAG y paralelismo: lanzar en paralelo solo nodos sin dependencias y revisar diffs antes de desbloquear dependientes.
    • Requisitos para producción: CLAUDE.md, pipelines rápidos, política de revisión y auditoría de commits.

    Introducción

    Subagentes como equipo de desarrollo: orquestación con Claude Code es el patrón que convierte a un asistente de IA en un equipo real: un coordinador que descompone trabajo y subagentes que ejecutan tareas atómicas, hacen commits y devuelven resultados auditables. Si vas a automatizar entregas complejas, empieza por esta estructura: plan, delega, commit, valida.

    Resumen rápido (lectores con prisa)

    Patrón que transforma un asistente en un equipo con un coordinador que define la spec y un conjunto de subagentes que implementan tareas atómicas. Útil cuando puedes separar trabajo por interfaces claras y hay necesidad de trazabilidad y rollback atómico. Requiere commits por subagente, pipelines rápidos y un CLAUDE.md como referencia.

    Subagentes como equipo de desarrollo: por qué importa y cómo cambia el riesgo

    La diferencia entre generar código rápido y entregar cambios sostenibles no está en la velocidad de la IA, sino en cómo gestionas el contexto y las decisiones. Un agente que trabaja solo acumula contexto y toma decisiones implícitas; eso produce deuda técnica que emerge en integración. Orquestar subagentes reduce tres riesgos claves:

    • Degradación de contexto: cada subagente opera con una ventana limitada y relevante.
    • Propagación de decisiones implícitas: el coordinador valida outputs antes de avanzar.
    • Falta de trazabilidad: cada subagente hace un commit atómico, facilitando revertir y revisar.

    Documentación útil: Claude Code overview y Claude (Anthropic)

    Cómo funciona el flujo: roles, primitives y regla del commit

    1. Agente principal (coordinador)

    – Define la spec global y el DAG de dependencias.
    – Descompone el trabajo en tareas atómicas.
    – Lanza subagentes con la primitiva task.

    2. Subagentes (desarrolladores)

    – Reciben una tarea acotada: archivos relevantes, firmas esperadas, criterios de aceptación.
    – Implementan cambios, añaden tests y hacen un commit.
    – Devuelven al coordinador el diff, logs de test y un resumen de riesgos pendientes.

    3. Regla inquebrantable: cada subagente hace un commit antes de que el coordinador asigne la siguiente tarea dependiente

    Beneficios: aislamiento de errores, validación incremental, trazabilidad en Git.

    Ejemplo de secuencia para migración

    • Task 1: migrar modelo de pagos → commit “payments: migrate model v2”
    • Task 2: actualizar servicio de facturación (depende de Task 1) → commit “billing: use payments v2”
    • Task 3: actualizar tests e2e (paralelo) → commit “tests: update e2e for payments v2”

    Reglas operativas: cómo escribir tareas para subagentes

    Una mala especificación produce malos resultados, aunque el subagente sea capaz. Sigue estas reglas:

    • Objetivo claro en 1–2 líneas.
    • Alcance: archivos y módulos permitidos.
    • Contratos: firmas, DTOs, errores esperados.
    • Criterios de aceptación automatizables (tests unitarios o comandos de CI).
    • Comando de commit esperado y mensaje sugerido.
    • Limitar tiempo/recursos si procede.

    Plantilla mínima para una tarea

    • Título: actualizar UserService para usar AuthV2
    • Archivos permitidos: src/services/userService.ts, src/types/auth.ts
    • Contrato: getUser(id): UserDto
    • Tests: añadir unit tests para getUser con mocks de AuthV2
    • Commit: “user: migrate to AuthV2 — tests added”

    Integración, paralelismo y control de dependencias

    – Construye un DAG (grafo acíclico) de tareas. Lanza en paralelo solo nodos sin dependencias entre sí.
    – Siempre inspecciona el diff tras cada commit. El coordinador puede ejecutar hooks o pipelines ligeros antes de desbloquear tareas dependientes.
    – Si una tarea paralela falla, su rollback es local: revertir su commit o patch específico, sin tocar el trabajo válido previo.

    Requisitos previos para producción

    • CLAUDE.md actualizado en la raíz: stack, patrones prohibidos, comandos CI. Los subagentes la leerán al iniciar. (Ver ejemplo de uso de CLAUDE.md en prácticas de equipo).
    • Pipelines de CI rápidos: que verifiquen commits intermedios (lint, tests unitarios).
    • Política de revisión: define qué commits requieren revisión humana inmediata (p. ej., cambios en auth, DB).
    • Mecanismo de auditoría: etiquetas de commit que identifiquen subagente y tarea.

    Cuándo aplicar este patrón (y cuándo no)

    Úsalo cuando

    • Puedes descomponer trabajo en módulos con interfaces claras.
    • Hay paralelismo real entre módulos.
    • Necesitas trazabilidad y rollback atómico.

    No lo uses cuando

    • La tarea es totalmente secuencial o indivisible.
    • Las interfaces son ambiguas o el proyecto carece de convenciones documentadas.
    • El overhead de coordinación supera el beneficio (scripts pequeños, fixes triviales).

    Métricas que importan para medir éxito

    • Tiempo medio desde task creada hasta merge sin rework.
    • Número de reverts por milestone.
    • % de tasks que pasan CI en primer commit.
    • Latencia de integración (tiempo entre commit de dependencia y comienzo de tareas dependientes).

    Un aumento en la proporción de merges sin rework y una caída en los reverts indican que la orquestación está funcionando.

    Limitaciones honestas

    El patrón amplifica capacidad, no sustituye criterio. Si el coordinador delega mal —tareas vagas, contratos inconsistentes— obtendrás implementaciones rápidas y equivocadas. La diferencia está en quién escribe las specs: la IA ejecuta, el humano decide.

    Dominicode Labs

    Para seguir explorando patrones de orquestación y automatización aplicados a equipos mixtos humano+IA, consulta Dominicode Labs. Es una continuación lógica para pruebas de concepto y plantillas de CLAUDE.md en equipos de ingeniería.

    FAQ

    ¿Qué es exactamente el patrón de subagentes?

    Es una estructura donde un coordinador descompone trabajo en tareas atómicas y subagentes ejecutan esas tareas, hacen commits atómicos y devuelven diffs, logs y riesgos pendientes.

    ¿Cuándo debería aplicar este patrón?

    Cuando puedes descomponer trabajo en módulos con interfaces claras, hay paralelismo real y necesitas trazabilidad y capacidad de rollback atómico.

    ¿Qué debe incluir una tarea bien escrita para un subagente?

    Objetivo en 1–2 líneas, alcance (archivos permitidos), contratos (firmas/DTOs), criterios de aceptación automatizables, comando de commit esperado y límites de tiempo/recursos si procede.

    ¿Qué herramientas de CI se recomiendan?

    Se recomiendan pipelines rápidos que verifiquen commits intermedios con lint y tests unitarios. No se prescribe una herramienta específica en este texto.

    ¿Cómo se maneja el rollback si una tarea falla?

    El rollback es local: revertir el commit o aplicar un patch específico de la tarea fallida, sin tocar el trabajo válido previo.

    ¿Qué debe haber en CLAUDE.md?

    Debe incluir stack, patrones prohibidos y comandos CI. Los subagentes la leerán al iniciar y sirve como referencia de equipo.

    ¿Qué métricas indican que la orquestación funciona?

    Aumentos en merges sin rework, caída en reverts, tiempo medio hasta merge menor, alto % de tasks que pasan CI en primer commit y baja latencia de integración.

  • Cómo aplicar la regla del 60% en la gestión de contexto para LLMs

    Cómo aplicar la regla del 60% en la gestión de contexto para LLMs

    Gestión de contexto: la regla del 60% para sesiones en Claude Code

    Tiempo estimado de lectura: 5 min

    • Regla operativa: nunca dejes que una sesión consuma más del 60% de la ventana de contexto sin persistir el estado y limpiar la memoria.
    • Patrón de trabajo: dividir tareas en Research → Plan → Implement → Validate, con artefactos en disco y limpieza de contexto entre fases.
    • Artefactos clave: /CLAUDE.md, /RESEARCH.md, /PLAN.md, /TASK_STATE.md, /VALIDATION_REPORT.md y commits atómicos por módulo.
    • Señales y métricas: observar contradicciones, repeticiones de contexto y fallos por “olvidos”; medir % de tareas con rework y tiempo de retoma.

    Introducción

    La frase “gestión de contexto: la regla del 60%” no es un eslogan. Es la regla operativa que evita que sesiones largas con agentes como Claude Code produzcan código coherente hoy y deuda técnica mañana. Si trabajas con LLMs en ingeniería, aplica esto desde el primer día: nunca dejes que una sesión consuma más del 60% de la ventana de contexto sin persistir el estado y limpiar la memoria.

    Resumen rápido (lectores con prisa)

    La regla del 60% limita cuánto de la ventana de contexto puede usar una sesión antes de persistir el estado. Úsala para fragmentar trabajo en sesiones controladas y guardar artefactos versionados (archivos en el repo). Aplica especialmente con agentes que leen/escriben repositorios como Claude Code.

    Qué significa “Gestión de contexto: la regla del 60%” y por qué importa

    Los modelos de lenguaje tienen una ventana finita de tokens. Cuando esa ventana se aproxima a su límite —y en la práctica cuando supera el 60%— el modelo comienza a priorizar lo más reciente. Eso no produce errores ruidosos: produce decisiones de diseño que olvidan criterios definidos al inicio, bugs detectados temprano y validaciones que ya no se tienen en cuenta.

    La regla del 60% obliga a fragmentar el trabajo en sesiones controladas y a externalizar el estado en artefactos versionados (archivos en el repo). Con Claude Code esto es práctico y repetible porque el agente puede leer/escribir el repositorio: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview y https://www.anthropic.com/claude.

    El patrón operativo: 4 fases limpias por sesión

    Divide cualquier tarea compleja en cuatro fases: Research → Plan → Implement → Validate. Cada fase debe terminar con un artefacto en disco y una limpieza explícita del contexto antes de pasar a la siguiente.

    1) Research — auditoría

    – Objetivo: mapear dependencias, puntos de dolor y deuda técnica sin cambiar nada.

    – Salida: RESEARCH.md con módulos auditados, preguntas abiertas y riesgos priorizados.

    – Acción: cerrar sesión. No cargar más archivos que los estrictamente necesarios.

    2) Plan — diseño acotado

    – Objetivo: con RESEARCH.md + CLAUDE.md (contrato del proyecto) definir módulos, orden y criterios de aceptación.

    – Salida: PLAN.md con tareas atómicas y criterios verificables.

    – Acción: validar el plan con un humano; cerrar sesión.

    3) Implement — sesiones por módulo

    – Objetivo: una sesión por módulo. Cargar solo PLAN.md, CLAUDE.md y archivos del módulo.

    – Salida por módulo: commit atómico + actualización de TASK_STATE.md (estado por módulo) y tests unitarios.

    – Acción: limpiar contexto entre módulos (reiniciar sesión o instanciar subagente nuevo).

    4) Validate — verificación objetiva

    – Objetivo: sesión en blanco que lea PLAN.md y ejecute validaciones (tests unitarios, integración, contratos).

    – Salida: VALIDATION_REPORT.md con pass/fail y pasos de corrección.

    – Acción: abrir PR / merge si pasa; en caso contrario, agregar tareas correctivas al plan y repetir ciclo.

    Ejemplo práctico (prompt y artefactos)

    Estructura de archivos mínima:

    /CLAUDE.md
/RESEARCH.md
/PLAN.md
/TASK_STATE.md
/VALIDATION_REPORT.md
/tasks/auth-migration.md

    Prompt de recuperación inicial (Research → Plan):

    Lee /RESEARCH.md y /CLAUDE.md. Propón un PLAN.md que divida la migración de Auth en módulos atómicos,
cada uno con criterios de aceptación y tests mínimos. No implementes código.
Guarda PLAN.md y termina la sesión.

    Prompt para Implement (módulo user-service):

    Lee PLAN.md y CLAUDE.md. Trabaja únicamente en src/services/user-service.* según el criterio de la tarea "UserService".
Agrega tests unitarios que validen los criterios. Actualiza TASK_STATE.md antes de hacer commit.
No toques otros módulos.

    Regla inquebrantable: actualizar TASK_STATE.md y hacer commit antes de terminar la sesión.

    Señales de que estás cruzando el 60% (y qué hacer)

    – Necesitas repetir contextos largos en prompts para que el agente recuerde una regla inicial.

    – El agente empieza a contradecir decisiones anteriores sin justificación.

    – Validaciones fallan por “olvidos” de requisitos que estaban en el RESEARCH.md.

    Si ves cualquiera de estas señales: persiste el estado en disco, cierra la sesión y reinicia con el artefacto correspondiente.

    Ventajas prácticas y métricas que importan

    Aplicar la regla del 60% reduce ruido y mejora trazabilidad:

    • Menos reverts por decisiones olvidadas.
    • Mayor porcentaje de tasks que pasan CI en el primer commit.
    • Tiempo de retoma por sesión < 5 minutos (leer artefacto) en vez de re-auditar todo.

    Mide: % de tareas con rework, número de bugs registrados en TASK_STATE.md, tiempo desde apertura de sesión hasta reanudación efectiva.

    Límites y advertencias

    Esto no sustituye especificaciones claras ni revisiones humanas. Si la planifica es ambigua, la IA persistirá ambigüedades más rápido. El patrón reduce riesgos operativos, no el riesgo conceptual de malas decisiones de diseño. Además, no necesitas este overhead para fixes rápidos o scripts aislados: aplica la regla cuando el alcance y la duración lo justifiquen.

    La regla del 60% es una disciplina: no es bonita, pero evita que la IA genere parches brillantes que fallan en integración. Si automatizas en serio, diseña tu flujo con RESEARCH.md, PLAN.md, TASK_STATE.md y VALIDATION_REPORT.md, obliga a commits atómicos y reinicia sesiones a tiempo. Con eso, la memoria del modelo deja de ser un talón de Aquiles y se convierte en parte auditable de tu pipeline.

    Continuación práctica y recursos: Dominicode Labs

    FAQ

    ¿Qué es la regla del 60%?

    Es una regla operativa que limita el uso de la ventana de contexto: nunca permitir que una sesión consuma más del 60% sin persistir estado y limpiar la memoria.

    ¿Cuándo debo aplicarla?

    Aplica siempre en sesiones largas con LLMs y agentes que manejan proyectos no triviales; evita su uso solo en fixes rápidos o scripts aislados.

    ¿Por qué importa con Claude Code?

    Porque Claude Code puede leer y escribir el repositorio; fragmentar el trabajo y persistir artefactos hace el flujo práctico y repetible.

    ¿Cuáles son los artefactos mínimos?

    /CLAUDE.md, /RESEARCH.md, /PLAN.md, /TASK_STATE.md, /VALIDATION_REPORT.md y archivos de tareas (por ejemplo /tasks/auth-migration.md).

    ¿Cómo se mide el éxito?

    Métricas: % de tareas con rework, número de bugs registrados en TASK_STATE.md y tiempo desde apertura de sesión hasta reanudación efectiva.

    ¿Qué hacer si detecto que crucé el 60%?

    Persistir el estado en disco, cerrar la sesión y reiniciar con el artefacto correspondiente.