DOMINICODE

Tag: Claude Code

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

  • 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

    Respuesta:

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

    Respuesta:

    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.

    Respuesta:

    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.

    Respuesta:

    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.

    Respuesta:

    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.

    Respuesta:

    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.

  • Implementación de Agent Skills para proyectos Angular

    Implementación de Agent Skills para proyectos Angular

    Hacer post sobre los Agent Skills de angular: guía práctica para arquitectos y equipos

    Tiempo estimado de lectura: 3 min

    • Agent Skills son capacidades automatizadas para leer, analizar y proponer cambios en código Angular respetando arquitectura y límites.
    • Prioridad ahora: Standalone Components, Signals, inject() y Zoneless requieren que la IA entienda contexto antes de tocar código.
    • Flujo operativo: discovery read‑only → auditorías estáticas → propuestas mecánicas en rama con PR y revisión humana.
    • Governance: integrar skills en CI, playbooks y dashboards para trazabilidad y control de riesgos.

    Hacer post sobre los Agent Skills de angular no es levantar hype ni repetir buzzwords; es ordenar una pieza crítica del puzzle: cómo convertimos agentes de IA en revisores técnicos y refactorizadores seguros para proyectos Angular. Si tu equipo opera con monorepos, Signals y rutas lazy, necesitas que la IA entienda topología, prácticas y riesgo antes de tocar una línea de código.

    Resumen rápido (lectores con prisa)

    Agent Skills son capacidades programáticas para que un agente automatizado lea, analice y proponga cambios en un repo Angular respetando arquitectura. Úsalos para discovery read‑only, auditorías estáticas y para generar propuestas en ramas con revisión humana. Integrar skills en CI y playbooks es clave para trazabilidad y control de riesgo.

    Qué son los Agent Skills de Angular (y por qué importan)

    Los Agent Skills son capacidades programáticas que permiten a un agente automatizado leer, analizar y —con límites— transformar código Angular respetando la arquitectura del proyecto. No hablamos de completados contextuales: hablamos de habilidades concretas para mapear workspaces, auditar patrones reactivos, detectar fugas de memoria y proponer refactorizaciones alineadas con la versión del framework.

    Por qué ahora

    Angular cambió. Standalone Components, Signals, inject() y la tendencia Zoneless hacen que un snippet bien formado pueda ser, en contexto, una regresión. El objetivo de los Agent Skills es cerrar la brecha entre lo que el modelo “sabe” y lo que el repo “es”.

    Categorías de Agent Skills (práctico y accionable)

    1) Descubrimiento y topología (Read‑Only)

    Mapeo de workspace

    Mapeo de workspace: lee angular.json / project.json y detecta apps, librerías y fronteras de dominio. Referencia: Nx.

    Árbol de dependencias

    Árbol de dependencias: construye el grafo de importaciones para detectar fronteras violadas o riesgos de dependencia circular.

    Regla de oro: siempre en modo solo lectura. Ejecutar antes de cualquier propuesta.

    2) Auditoría y análisis estático (reportes)

    Detección de fugas

    Detección de fugas: localizar suscripciones sin cleanup (ngOnDestroy, takeUntilDestroyed()), event listeners no removidos o timers persistentes.

    Change detection check

    Change detection check: validar OnPush vs mutaciones por referencia que rompen el rendering.

    Compatibilidad Zoneless

    Compatibilidad Zoneless: identificar patrones que dependen de la detección implícita de zone.js. Referencia: zone.js.

    Resultado: un informe accionable con líneas de riesgo, prioridad y referencia documental.

    3) Modernización y refactorización (propuestas con revisión humana)

    Migración a Standalone

    Migración a Standalone: extraer un componente de un NgModule, aplicar standalone: true y actualizar rutas lazy.

    Refactor inject()

    Refactor inject(): reemplazar inyección por constructor cuando el patrón lo permita.

    RxJS → Signals

    RxJS → Signals: transformar estados locales sincronizados (BehaviorSubject) a signal()/computed() cuando no haya flujos asíncronos complejos.

    Nota: estas operaciones deben proponerse en PRs, nunca aplicarse directamente en main sin revisión.

    Ejemplo de flujo mínimo (adoptable hoy)

    1. PR abierto → webhook dispara workflow.
    2. Ejecutar skills Read‑Only: mapea workspace + análisis de dependencias.
    3. Ejecutar auditorías: fugas, OnPush, Zoneless. Adjuntar report con URLs de documentación (angular.dev).
    4. Si todo OK, ejecutar propuestas mecánicas (migración Standalone o inject()) en una rama de trabajo y abrir PR automático con checklist y pruebas.

    Este flujo es orquestable con n8n o runners CI que disparen agentes y persistan resultados para trazabilidad.

    Criterio técnico (lo que no debes automatizar sin control)

    • No otorgues permisos de escritura globales hasta que el agente haya corrido los skills de descubrimiento y get_best_practices.
    • Tratar la migración Zoneless como diagnóstico, no como parche automático: los efectos secundarios en tiempo de ejecución y librerías externas pueden romper producción.
    • No convertir RxJS → Signals de forma indiscriminada; define reglas: solo estado local sincronizable y sin operadores complejos.
    • Exige trazabilidad: cada recomendación viene con fragmento de doc y URL a la sección relevante de angular.dev.

    Integración con gobernanza y equipos

    Los Agent Skills dejan de ser experimentales cuando se integran en:

    • Pipelines de CI que registran outputs de los inspectores junto al PR.
    • Playbooks de revisión que establecen qué skills pueden autocorregir en ramas de feature y cuáles requieren aprobación de un Senior.
    • Dashboards de deuda técnica que priorizan hallazgos del agente (fugas, violaciones de fronteras, patrones Zoneless).

    Qué ganas — y cuánto riesgo evitas

    Implementar Agent Skills bien definidos reduce regresiones arquitectónicas, acelera migraciones repetitivas y convierte a la IA en un revisor que aporta contexto (no solo snippets). El retorno real es tiempo de arquitecto liberado para decisiones complejas y menos deuda introducida por cambios automáticos mal contextualizados.

    Cierre práctico

    1. Añadir un skill de mapeo de workspace en tu pipeline.
    2. Automatizar la auditoría de fugas por cada PR.
    3. Pilotar migraciones Standalone en ramas feature con revisión humana.

    Con eso pones la IA a trabajar para tu arquitectura, no contra ella.

    Si quieres integrar estos workflows en tus pipelines y experimentos, considera explorar recursos y experiments en Dominicode Labs. Es una continuación natural para llevar skills de inspección y orquestación a pipelines con trazabilidad y playbooks.

    FAQ

    ¿Qué son exactamente los Agent Skills en Angular?

    Son capacidades programáticas que permiten a un agente automatizado leer, analizar y, con límites, transformar código Angular respetando la arquitectura del proyecto. Incluyen discovery, auditoría estática y generación de propuestas para revisión humana.

    ¿Cuándo debo ejecutar los skills en un PR?

    El flujo recomendado es: al abrir un PR, disparar skills Read‑Only (mapeo de workspace y análisis de dependencias) y luego las auditorías (fugas, OnPush, Zoneless). Solo después de pasar estos pasos se generan propuestas mecánicas en una rama separada.

    ¿Puede el agente aplicar cambios directamente en main?

    No. Las operaciones de modificación deben proponerse en PRs y revisarse. No otorgues permisos de escritura globales hasta validar discovery y mejores prácticas. Las transformaciones automatizadas requieren trazabilidad y aprobación.

    ¿Cómo integro los reports en CI?

    Orquesta el flujo con webhooks o runners CI: al abrir PR disparas agentes que persisten los resultados junto al PR. Puedes usar herramientas como n8n para orquestación y almacenar informes para dashboards de deuda técnica.

    ¿Qué precauciones con Zoneless?

    Trata la migración Zoneless como diagnóstico, no como parche automático. Identifica patrones que dependen de zone.js y evalúa efectos secundarios en tiempo de ejecución y librerías externas antes de proponer cambios.

    ¿Cómo asegurar trazabilidad de recomendaciones?

    Cada recomendación debe incluir fragmentos de doc y un enlace a la sección relevante de angular.dev, junto con el contexto del repo (archivo, línea, grafo de dependencias) y el historial del agente que generó la sugerencia.

  • 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

    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.

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

    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.

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

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

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

    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 usar Claude Code para mejorar la productividad en desarrollo

    Cómo usar Claude Code para mejorar la productividad en desarrollo

    Como usar Claude Code como un pro

    Tiempo estimado de lectura: 4 min

    • Sesiones enfocadas: abre Claude Code en la carpeta del módulo, no en la raíz del monorepo.
    • Delega ciclos completos: pide flujos (tests → ejecutar → corregir → commit), no snippets aislados.
    • Controla contexto: evita indexar logs, binarios y secretos; limpia filtros antes de iniciar.
    • Autonomía con control: mantén confirmaciones para comandos destructivos y usa entornos efímeros para ejecuciones automáticas.

    Si quieres transformar la terminal en un entorno de ingeniería productiva, necesitas saber como usar Claude Code como un pro desde el primer comando. Claude Code no es un complemento de autocompletado: es un agente que puede leer tu repositorio, ejecutar comandos, iterar sobre fallos y aplicar cambios. Usarlo bien implica diseño de prompts, control del contexto y reglas claras de seguridad.

    Resumen rápido (lectores con prisa)

    Qué es: Un agente que puede leer repositorios, ejecutar comandos y aplicar cambios.

    Cuándo usarlo: Para flujos completos como refactorizaciones, tests y generación de PRs en entornos controlados.

    Por qué importa: Acelera tareas completas y reduce iteraciones manuales cuando se usa con límites y control de contexto.

    Cómo funciona: Indexa el directorio de sesión, ejecuta comandos permitidos y puede iterar según la salida real del sistema.

    como usar Claude Code como un pro: principios prácticos

    1) Trabaja en sesiones enfocadas (aprovecha el prompt caching)

    Claude Code indexa el directorio en el que abres la sesión. Esa indexación se cachea para reducir latencia y coste. La regla: una sesión = un microservicio o un módulo. Cambiar de contexto dentro de la misma sesión invalida la caché y dispara costes y latencia.

    Práctica: abre la CLI dentro de services/payments/, resuelve la tarea y cierra la sesión. No abras Claude Code en la raíz de un monorepo a menos que realmente necesites ver todo.

    2) Delega ciclos completos, no micro-tareas

    Un uso amateur pide snippets. Un uso profesional delega un flujo entero:

    Prompt tipo pro:
    “Refactoriza src/billing para eliminar dependencias a legacy-lib.
    Crea tests Jest que cubran el 80% de las rutas críticas.
    Ejecuta npm run test y corrige fallos hasta que la suite pase.
    Genera un changelog corto y crea un commit.”

    Resultado: código probado, commit y artefactos (tests + changelog). No más “escribe la función X”.

    3) Controla el contexto y el ruido (asegura tu entrada)

    Si la sesión indexa logs, bases SQLite locales o binarios, el modelo desperdicia tokens. Dos acciones imprescindibles:

    • Ejecuta Claude Code desde la carpeta del módulo que interesa.
    • Mantén .gitignore y filtros locales limpios; mueve o excluye archivos pesados antes de indexar.

    No inventes exclusiones mágicas: la higiene del repositorio reduce errores y mejora precisión.

    4) Define expectativas y contratos en el prompt

    Un prompt efectivo contiene: objetivo, criterios de éxito, límites y comandos permitidos. Ejemplo breve:

    • Objetivo: “Internacionalizar mensajes de error en src/errors.”
    • Criterio de éxito: “Tests de integración deben pasar y la clave i18n existir en cada error.”
    • Límite: “No modificar build/ ni archivos en vendor/.”
    • Comandos permitidos: “npm test, git add, git commit.”

    Esto evita cambios sorpresivos y deja claro qué auditar.

    Integración segura: autonomía con control

    La gran pregunta es siempre autonomía vs control. Claude Code pide confirmación antes de comandos destructivos; esa barrera debe mantenerse por defecto. Habilitar ejecución totalmente autónoma solo tiene sentido en entornos efímeros: contenedores Docker desechables o runners de CI con permisos mínimos.

    Patrón recomendado:

    • Local: Human-in-the-loop. Aprobar cambios críticos manualmente.
    • CI/CD: Sesiones automáticas dentro de contenedores con snapshot y rollback.
    • Producción: Nunca sin procesos de revisión y herramientas de observabilidad.

    Ejemplo de entorno efímero:

    docker run --rm -v $(pwd):/work -w /work node:18 bash -c "claude-code session --authed"
    (Ejecutar la CLI dentro de un contenedor permite pruebas reproducibles y segura reversión).

    Casos de uso donde Claude Code rinde como un pro

    Ejemplos claros donde aporta valor:

    • Onboarding técnico: “Lee src/ y genera un diagrama Mermaid de la arquitectura.” Resultado: documentación inicial y mapa de dependencias.
    • Refactorización transversal: “Sustituye libX por libY y ejecuta linter + tests.” Resultado: cambios aplicados + report.
    • Auditoría rápida: “Revisa el módulo de auth contra OWASP Top 10 y documenta hallazgos.” Resultado: lista priorizada de riesgos.
    • PR autopiloto: “Analiza esta rama, aplica fixes mínimos, y crea PR con descripción técnica y checklist de QA.”

    Métricas para demostrar ROI

    No es magia; mide impacto con indicadores concretos:

    • Tiempo medio para cerrar una tarea compleja (antes / después).
    • % de PRs que pasan CI en primera corrida.
    • Tiempo de onboarding de nuevos devs (documentación generada).
    • Reducción de errores por regresiones introducidas manualmente.

    Riesgos y cómo mitigarlos

    • Fugado de secretos: asegúrate de que la CLI no indexe .env con credenciales; usar vaults y secrets managers.
    • Cambios no revisados: habilita hooks que obliguen revisión humana en cambios críticos.
    • Sobredependencia: Claude Code acelera, no sustituye juicio. Mantén reglas de propiedad de código.

    Resumen rápido y acción inmediata

    Para empezar ya: instala la CLI, abre una sesión en un módulo pequeño, prueba un prompt de TDD completo (escribir tests → ejecutar → corregir) y ejecuta todo dentro de un contenedor temporal. Documenta los resultados y ajusta prompts.

    Si aprendes como usar Claude Code como un pro tendrás menos código parcheado y más flujos reproducibles. La terminal deja de ser un editor y se convierte en un orquestador: potente, pero bajo tu criterio.

    Dominicode Labs

    Si trabajas con agentes, automatización o workflows, considera continuar explorando patrones y experimentos en Dominicode Labs. Está diseñado como una continuación práctica para pruebas controladas y prototipos de integración.

    FAQ

    Respuesta: ¿Qué es Claude Code y para qué sirve?

    Claude Code es un agente que puede leer tu repositorio, ejecutar comandos, iterar sobre fallos y aplicar cambios, usado para acelerar flujos completos como refactorizaciones, tests y creación de PRs.

    Respuesta: ¿Cuándo debo abrir una sesión en la carpeta del módulo versus en la raíz?

    Abre la sesión en la carpeta del módulo cuando trabajes en una unidad cohesionada (microservicio o paquete). Evita la raíz en monorepos grandes para no invalidar caché y aumentar coste y latencia.

    Respuesta: ¿Qué debe incluir un prompt profesional?

    Debe contener objetivo, criterios de éxito, límites y comandos permitidos. Ejemplo: objetivo claro, tests necesarios, carpetas prohibidas y lista de comandos autorizados.

    Respuesta: ¿Cómo mitigo el riesgo de fugado de secretos?

    No indexes .env ni archivos con credenciales; usa vaults y secrets managers; filtra o mueve archivos sensibles antes de iniciar la sesión.

    Respuesta: ¿Es seguro habilitar ejecución autónoma en producción?

    No. Habilita ejecución autónoma solo en entornos efímeros y controlados. En producción exige revisiones humanas y observabilidad.

    Respuesta: ¿Qué métricas son útiles para medir ROI?

    Tiempo medio para cerrar tareas complejas, porcentaje de PRs que pasan CI en la primera corrida, tiempo de onboarding y reducción de errores por regresiones manuales.

    Claude Code (documentación oficial: documentación oficial) se comporta como un colaborador técnico: puede generar código, ejecutar tests y corregir errores basándose en la salida real del sistema.

  • Cómo redactar especificaciones efectivas para IA en desarrollo de software

    Cómo redactar especificaciones efectivas para IA en desarrollo de software

    ¿Quieres que la IA escriba código que aguante en producción o prefieres pagar la reescritura con horas de sueño robadas?

    Tiempo estimado de lectura: 6 min

    • Sin una spec sólida, la IA falla: la salida suele ser “lo más probable” y no lo que tu sistema necesita.
    • Una spec funciona como contrato: entradas, salidas y reglas inmutables (TS, DB, validadores).
    • Proceso y repo: coloca SPEC.md y reglas globales en el repo; pide tests antes de código.
    • Diseña para fallos: idempotencia, retries, observabilidad y mocks de LLM en CI.

    Poca gente dice esto claro: sin una spec sólida, la IA no te ayuda —te traiciona con estilo. Te da un PR brillante, lo mergeas, y dos semanas después estás en modo bombero arreglando incoherencias, dependencias raras y bugs que solo existen porque nadie le dijo al modelo las reglas del juego.

    Esto no es teoría. Es un manual corto y agresivo para escribir specs que conviertan a la IA en ejecutora precisa, no en improvisadora talentosa.

    Resumen rápido (lectores con prisa)

    La IA no entiende contexto técnico; genera lo más probable. Para usarla en producción necesitas specs como contratos: define entradas, salidas, validadores y versiones exactas del stack. Pon la spec en el repo, exige tests (mock de LLM en CI) y diseña idempotencia, retries y observabilidad desde el inicio.

    Primera verdad incómoda: la IA no piensa, predice

    Los modelos son máquinas de probabilidades. No entienden GDPR, SLAs o el negocio que hay detrás del botón. Si no les das límites, rellenan con lo más probable de su entrenamiento. Y lo más probable suele ser un parche bonito… que no encaja en tu arquitectura.

    Qué hace una spec que realmente funcione con IA

    1) Contexto de negocio (el “por qué”) — 1 párrafo

    No le cuentes la historia de tu vida. Di en una frase qué problema resuelve esta feature y qué sería un fallo. Ejemplo: “Crear usuarios con verificación por email. Éxito = usuario activo; fracaso = intento de signup duplicado.” Con eso la IA prioriza seguridad y unicidad, no UX glam.

    2) Contratos de datos inmutables — el núcleo

    Define TODAS las formas de datos:

    • Interfaces TypeScript (ej. CreateUserRequest, UserResponse).
    • Esquema de DB (SQL/Prisma).
    • Validadores (Zod schemas).

    Si el código espera un JSON con { email: string, password: string } dilo. Congela esos contratos. Si cambian, cambia la spec. Esto transforma a la IA en un generador que cumple un contrato, no en un novelista.

    3) Stack y versiones exactas — sin ambigüedades

    “Usa Next.js” es basura. Di “Next.js 14 — App Router — Node 20 — Postgres 15 — pgvector”. Lista librerías permitidas y las prohibidas. Los modelos tienden a usar patrones históricos; dar versión evita sorpresas.

    4) Reglas negativas — lo que NO se debe hacer

    La IA ama instrucciones. Si le dices “No hagas X”, lo recuerda. Lista antipatrones:

    • No exponer variables de entorno en cliente.
    • No añadir dependencias sin revisión CVE.
    • No implementar persistencia eventual en endpoints críticos.

    5) Criterios de aceptación comprobables

    Exige tests. Define qué pruebas deben pasar:

    • Unit tests (ej. hashing de password).
    • Integration tests (ej. createUser -> DB -> verify hash).
    • Tests de resiliencia (reintentos en worker).

    Pedir tests antes que código hace que la IA produzca implementaciones testables.

    Cómo estructurar la spec en el repo (hazlo ya)

    No metas la spec en Google Docs o Notion y esperes que la IA la lea. Ponla en el repo. Que el agente la tenga al lado del código. Dos archivos mínimos:

    Archivos mínimos

    • .cursorrules / .github/copilot-instructions.md — Reglas globales: stack, estilos, convenciones de nombres, políticas de seguridad. Que el agente lo lea siempre.
    • SPEC.md (micro-spec por feature) — Contexto corto, contratos TS, endpoints, criterios de aceptación, reglas negativas, responsables.

    Micro-spec vs contexto global: menos es más

    Saturar la ventana de contexto con miles de archivos confunde. Alimenta a la IA con:

    • SPEC.md del módulo.
    • Tipos globales que realmente importan.
    • Un archivo de reglas globales.

    Menos ruido, más precisión. La IA trabaja mejor con densidad técnica, no con bibliotecas de historia.

    Patrón de trabajo: plan antes de código

    Nunca pidas “haz el CRUD”. Pide un plan en pasos:

    1. Interfaces + DB schema.
    2. Contratos OpenAPI.
    3. Tests de aceptación.
    4. Implementación por sprint.

    Aprueba cada fase. Así evitas que la IA genere código que contradiga los contratos que aprobaste.

    Herramientas que convienen y por qué

    – TypeScript + Zod: transforma respuestas en contratos verificables.

    – Prisma/SQL: esquemas claros y migraciones.

    – OpenAPI: contratos de endpoint.

    – pgvector (si usas vectores): evita añadir otro servicio.

    – n8n para orquestación: sacas la lógica de integración fuera del repo y manejas retries visuales.

    RAG y seguridad: nunca lo tomes a la ligera

    Si vas a indexar documentos para chatear con ellos, cada vector debe llevar tenant_id. Punto. No mezcles tenants. Nunca. El filtro por tenant debe aplicarse en la consulta, no en la app. Si mezclas vectores, estás invitando a fugas de datos.

    Idempotencia, retries y jobs: diseña para fallos

    Asume que la IA y los servicios fallarán. Diseña:

    • Jobs con estado (pending, processing, success, failed).
    • Workers idempotentes por job_id.
    • Dead-letter queues para errores irreparables.
    • Retries con backoff exponencial y circuit breaker.

    No idempotencia = facturación duplicada + datos duplicados. No es elegante. Es caro.

    Observabilidad desde el minuto cero

    Si no mides, no mejoras. Instrumenta:

    • Traces distribuidos (OpenTelemetry).
    • Métricas: latencia por modelo, tokens por job, coste por tenant.
    • Logs estructurados con context_id.
    • Dashboards y alertas (picos de coste, aumentos de error rates).

    Tests: mockea la IA

    No dependas de la API real en CI. Mockea respuestas de LLM —positivas y negativas— y tests que simulen timeouts, respuestas malformadas y ataques de prompt injection. Así la spec y los tests te protegen cuando la IA se sale del carril.

    Plantilla mínima de SPEC.md (rápida y usable)

    Pon esto en la raíz del módulo. No lo copies sin adaptar, pero úsalo como base.

    • Título: Objetivo en una frase.
    • Contexto: 2 párrafos máximos.
    • Stack: versiones exactas.
    • Contratos: interfaces TS + esquemas SQL/Prisma.
    • Endpoints: método, path, payloads (ej. OpenAPI snippet).
    • Regla negativas: lista corta.
    • Criterios de aceptación: tests concretos.
    • Responsables: quién aprueba merge.

    El nuevo rol del senior: menos héroe, más guardián

    El valor del senior hoy no es teclear más rápido. Es decidir fronteras. Es escribir specs que no fallen en producción. Si no tienes eso, la IA solo acelera el desastre.

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

    • ¿SPEC.md está en la raíz del módulo?
    • ¿Interfaces TS y esquemas DB están definidos?
    • ¿Reglas negativas claras?
    • ¿Tests de aceptación definidos?
    • ¿El prompt obliga a devolver JSON validable?

    Si respondes no a cualquiera, no pidas código.

    CTA

    Si quieres la plantilla SPEC.md lista para pegar y un prompt maestro para Claude que funcione hoy, respóndeme “Quiero la plantilla”.

    Te la envío lista para pegar en el repo y para que la IA empiece a generar código que no te rompa la vida.

    Para quienes trabajan en automatización, agentes y workflows este enfoque encaja con prácticas de laboratorio y experimentación. Más recursos y experimentos vinculados a estos patrones están disponibles en Dominicode Labs, que complementan las plantillas y ejemplos prácticos descritos arriba.

    FAQ

    Respuesta: ¿Por qué necesito una spec si la IA puede escribir código por mí?

    Porque la IA genera lo más probable, no lo correcto para tu negocio. Una spec transforma requisitos en contratos verificables que la IA puede cumplir de forma repetible.

    Respuesta: ¿Qué debe contener obligatoriamente un SPEC.md?

    Título objetivo, contexto corto, stack con versiones exactas, contratos (TS + DB), endpoints, reglas negativas, criterios de aceptación y responsables.

    Respuesta: ¿Cómo evito fugas de datos en sistemas RAG?

    Indexa vectores con tenant_id, aplica el filtro por tenant en la consulta y evita mezclar índices entre tenants.

    Respuesta: ¿Qué pruebas debo pedir antes de revisar un PR generado por IA?

    Unit tests, integration tests que verifiquen contratos y tests de resiliencia (timeouts, retries, respuestas malformadas).

    Respuesta: ¿Cómo integro mocks de LLM en CI sin perder cobertura realista?

    Mockea escenarios positivos y negativos, timeouts y prompt injections. Mantén casos representativos que reflejen errores reales observados en producción.

    Respuesta: ¿Qué reglas negativas son las más críticas?

    No exponer env vars en cliente; no añadir dependencias sin revisión CVE; no usar persistencia eventual en endpoints críticos; exigir tests antes del merge.

  • Automatiza tareas avanzadas con Claude Code sin programar

    Automatiza tareas avanzadas con Claude Code sin programar

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

    Tiempo estimado de lectura: 4 min

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

    Introducción

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

    Resumen rápido (lectores con prisa)

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

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

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

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

    1) Orquestar automatizaciones avanzadas en n8n — sin tocar JS

    Problema común

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

    Qué pedirle al modelo

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

    Qué obtendrás

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

    Por qué importa

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

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

    Caso real

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

    Lo que puedes pedir

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

    Qué devuelve Claude

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

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

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

    Usos prácticos

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

    Qué ganas

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

    Cómo decidir: CLI o modelo web/API

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

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

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

    Dominicode Labs

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

    FAQ

    ¿Necesito instalar algo para usar Claude como modelo?

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

    ¿Cuándo debo preferir la CLI de Claude?

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

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

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

    ¿Claude puede generar consultas SQL optimizadas?

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

    ¿Es seguro usar el modelo para datos sensibles?

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

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

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

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

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

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

    Tiempo estimado de lectura: 5 min

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

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

    Fuentes para comprobar:

    Resumen rápido (lectores con prisa)

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

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

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

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

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

    Tres escenarios concretos

    1) Automatizaciones en n8n sin aprender JavaScript

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

    Qué hacer:

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

    Qué recibes:

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

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

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

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

    Qué pedir:

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

    Qué recibes:

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

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

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

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

    Qué pedir:

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

    Qué recibes:

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

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

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

    1. Muestra ejemplos concretos. No abstracciones.

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

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

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

    Una plantilla compacta:

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

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

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

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

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

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

    Dominicode Labs

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

    FAQ

    ¿Qué es Claude Code?

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

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

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

    ¿Necesito saber programar para obtener valor?

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

    ¿Cómo usar Claude con n8n?

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

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

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

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

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

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

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

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

    Tiempo estimado de lectura: 6 min

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

    Introducción

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

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

    ¿Qué debe contener un CLAUDE.md?

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

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

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

    Plantilla mínima

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

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

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

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

    ¿Dónde colocarlo en monorepos?

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

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

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

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

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

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

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

    Mantenimiento: el contrato debe evolucionar con el código

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

    Reglas simples de mantenimiento:

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

    Casos prácticos y límites

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

    Conclusión

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

    Dominicode Labs

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

    FAQ

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

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

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

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

    Respuesta: ¿Qué pasa si no lo actualizo?

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

    Respuesta: ¿Puedo incluir secretos en CLAUDE.md?

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

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

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

  • Implementación de Steering Documents para Claude Code

    Implementación de Steering Documents para Claude Code

    Steering documents: enseña a Claude tu arquitectura de una vez

    Tiempo estimado de lectura: 5 min

    • Convierte la memoria del agente en infra versionada: usa product.md, tech.md y structure.md.
    • Son contratos operativos: Claude Code los carga al arrancar y los respeta como reglas.
    • Manténlos concisos y gobernados: actualízalos como parte de la PR y asigna propietarios.

    Steering documents: enseña a Claude tu arquitectura de una vez —esa es la diferencia entre repetir contexto cada sesión y tener un agente que ya entiende tu producto, tu stack y tus límites. Si usas Claude Code en proyectos reales, necesitas tres documentos permanentes en el repo: product.md, tech.md y structure.md. Con ellos conviertes la memoria del agente en infra versionada, no en promesas inútiles de prompt.

    Resumen rápido (lectores con prisa)

    Steering documents son archivos Markdown versionados que Claude Code carga al iniciar. Son contratos operativos: product.md define dominio y reglas inmutables; tech.md define stack y prohibiciones; structure.md define mapa y reglas de dependencia. Actualízalos con la PR que cambia el dominio o stack.

    Steering documents: qué son y cómo los usa Claude Code

    Un steering document es un Markdown versionado que Claude Code lee al arrancar una sesión. No es mera documentación: es el contrato operativo que la IA debe respetar. La doc raíz CLAUDE.md debe referenciarlos para que Claude los cargue automáticamente (ver docs de Claude Code y Claude (Anthropic)).

    ¿Por qué preocuparnos? Sin estos archivos el agente:

    • Asume patrones genéricos y propone librerías no deseadas.
    • Introduce convenciones inconsistentes (nombres, capas).
    • Toma decisiones de negocio que rompen reglas críticas.

    Con steering documents, el agente aplica las mismas restricciones y expectativas que un ingeniero senior al entrar al repositorio.

    Los tres steering documents esenciales

    A continuación, la estructura práctica y mínima para cada archivo. Copia, adapta y versiona.

    product.md — contexto de negocio (qué y para quién)

    Debe explicar el dominio y las reglas que NUNCA se rompen.

    Ejemplo mínimo:

    ## Propósito
Sistema B2B para facturación y gestión de suscripciones.

## Usuarios
Admin (gestiona planes), Cliente (visualiza facturas), Billing Ops.

## Conceptos de dominio
- Factura: documento inmutable que refleja obligación de pago.
- Suscripción: contrato con ciclo y estado (active, trial, cancelled).

## Reglas inmutables
- Una factura con estado "paid" no puede mutarse.
- Cambios de plan aplican solo desde el próximo ciclo de facturación.

    Product.md evita que Claude implemente validaciones técnicamente correctas pero comercialmente inválidas.

    tech.md — contrato técnico (qué usar y qué evitar)

    Enumera stack, patrones aprobados, patrones prohibidos y comandos de validación.

    Ejemplo mínimo:

    ## Stack aprobado
- Frontend: Next.js 14 (App Router), TypeScript
- Backend: Node + Fastify
- DB: PostgreSQL + Drizzle

## Patrones aprobados
- Feature-based folders
- Estado: Zustand
- Validaciones: Zod

## Prohibiciones
- No usar `any` en TS
- No añadir dependencias sin RFC y PR

    Incluye comandos que Claude puede ejecutar para validar cambios: pnpm test, pnpm lint, pnpm build.

    structure.md — mapa del repositorio y reglas de dependencia

    Describe la topología y las reglas de importación.

    Ejemplo mínimo:

    ## Árbol principal
src/
├─ app/
├─ features/
├─ shared/
└─ lib/

## Reglas de dependencia
- features -> shared|lib
- shared !-> features
- lib !-> features|shared

    Structure.md previene importaciones cruzadas, acoples y mal colocación de código.

    Cómo integrarlos en CLAUDE.md y en el flujo de trabajo

    Incluye estas líneas al inicio de CLAUDE.md:

    Lee antes de cualquier tarea:
- @product.md
- @tech.md
- @structure.md

    Eso obliga a Claude Code a tratarlos como memoria base. Además, convierte a estos archivos en el primer artefacto que se consulta en cada sesión, reduciendo la necesidad de prompts largos.

    Reglas operativas prácticas:

    • Actualiza steering docs como parte de la PR que introduce el cambio (no después).
    • Cada PR que modifica stack o dominio debe incluir cambios en tech.md o product.md.
    • Los commits deben referenciar el documento afectado: e.g., tech: add pgvector to approved libs.

    Mantenimiento y gobernanza

    Los steering documents son infra; trátalos como tal:

    • Mantén un owner (Staff/Tech Lead) responsable de aprobar cambios.
    • Usa PR con plantilla: “¿Este cambio requiere actualizar product/tech/structure?”.
    • Revisión obligatoria para cambios que rompan reglas prohibidas.

    Medir impacto:

    • % de PRs que violan tech.md (debe bajar).
    • Tiempo medio para onboarding de IA (leer docs vs. explicar manualmente).
    • Reverts causados por decisiones del agente (debe descender).

    Límite y advertencia práctica

    No conviertas estos archivos en una lista viva de todo el código. Son contratos, no specs línea por línea. Manténlos concisos, explícitos y estables. Si permites que entren cambios experimentales sin governance, el agente aplicará reglas obsoletas y causará más fricción que ahorro.

    Implementar steering documents: enseña a Claude tu arquitectura de una vez

    Implementar steering documents: enseña a Claude tu arquitectura de una vez. Es trabajo de equipo al principio; ahorro de tiempo y coherencia técnica permanente después. Si quieres que la IA actúe como ingeniero efectivo, no le des hints: dale el contrato.

    Para equipos que automatizan workflows, integran agentes o aplican IA en procesos de ingeniería, también puede ser útil revisar recursos prácticos y experimentales en Dominicode Labs. Esa referencia complementa estrategias de gobernanza y pruebas para agentes en repositorios reales.

    FAQ

    ¿Qué es un steering document?

    Un steering document es un archivo Markdown versionado que Claude Code lee al arrancar. Funciona como un contrato operativo que la IA debe respetar.

    ¿Por qué necesito product.md, tech.md y structure.md?

    Porque juntos convierten la memoria del agente en infra versionada: product.md define el dominio y reglas inmutables; tech.md define stack y prohibiciones; structure.md define topología y reglas de dependencia.

    ¿Cómo se cargan estos archivos en Claude Code?

    La doc raíz CLAUDE.md debe referenciarlos para que Claude los cargue automáticamente al arrancar una sesión. Incluye al inicio: Lee antes de cualquier tarea: – @product.md – @tech.md – @structure.md.

    ¿Qué poner en tech.md?

    Enumera stack aprobado, patrones aprobados, prohibiciones y comandos de validación (por ejemplo: pnpm test, pnpm lint, pnpm build).

    ¿Cómo gestiono cambios en estos documentos?

    Actualízalos como parte de la PR que introduce el cambio y asigna un owner responsable de aprobar actualizaciones. Usa plantillas de PR que pregunten si los steering docs requieren cambios.

    ¿Pueden ser demasiado detallados?

    No. Deben ser concisos y estables. Evita convertirlos en una lista viva de todo el código; son contratos, no especificaciones línea por línea.

    ¿Qué pasa si el agente viola una regla?

    Si el agente toma decisiones que violan las reglas, revisa y refuerza los steering docs y la gobernanza: owner, PRs obligatorias y métricas de impacto (PRs que violan tech.md, reverts, tiempo de onboarding).