DOMINICODE

Tag: Claude Code

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

  • Cómo usar Claude Code para tareas sin ser developer

    Cómo usar Claude Code para tareas sin ser developer

    Es claude code tan solo para developers ? 3 cosas que puedes hacer con claude sin ser developer

    “Tiempo estimado de lectura: 3 min”

    • Claude Code es una herramienta orientada a terminales y repos; Claude (modelo web/API) ofrece razonamiento técnico accesible sin instalar dependencias.
    • Con Claude puedes diseñar y depurar workflows en herramientas como n8n (automatización), transformar y analizar datos, y generar documentación y diagramas (Mermaid, OpenAPI).
    • La diferencia clave no es saber programar, sino estructurar problemas y validar hipótesis técnicas usando el modelo web/API.

    Introducción

    Es claude code tan solo para developers ? Si escuchaste “CLI” y cerraste la puerta, respira: la respuesta técnica es sí —pero la historia completa no es tan simple.

    Claude Code (el agente CLI de Anthropic) está pensado para terminales, repos y tareas que tocan el código. Pero Claude, el modelo, vive en la web, en APIs y en integraciones: te da razonamiento técnico sin obligarte a teclear npm install. Aquí te explico por qué importa y tres cosas concretas que puedes hacer sin ser developer.

    Resumen rápido (lectores con prisa)

    Qué es: Claude Code es un agente CLI; Claude (modelo) se accede vía web/API e integraciones.

    Cuándo usarlo: Usa Claude Code si un agente debe tocar tu repo y ejecutar tests; usa Claude Web/API para razonamiento, diseño de flujos y transformación de datos.

    Por qué importa: Permite a non-devs con criterio diseñar, validar y documentar soluciones técnicas sin convertirse en especialistas en sintaxis.

    Cómo funciona: En vez de escribir sintaxis, describes escenarios, estructuras y reglas; el modelo transforma esa descripción en snippets, esquemas y diagramas reutilizables.

    Es claude code tan solo para developers ? Lo esencial en 60 segundos

    Claude Code = herramienta para desarrolladores. Vive en la terminal. Requiere Git, variables de entorno y un repo que pueda inspeccionar y modificar.

    Claude (3.7 Sonnet y variantes) = modelo razonador accesible por web/API. No necesitas compilar nada, sí necesitas saber explicar problemas con precisión. En vez de escribir sintaxis, planteas escenarios, estructuras de datos y reglas. El peso se traslada del teclado al criterio.

    Traducción práctica: si eres product manager, automation builder o founder, puedes usar Claude como copiloto intelectual. No como quien programa, sino como quien diseña y valida soluciones.

    1) Diseñar y depurar workflows en n8n — sin tocar Node.js

    n8n es el lugar donde los flujos se vuelven reales. Pero cuando un JSON llega sucio o una API no tiene nodo nativo, la fricción aparece.

    Lo que haces con Claude:

    • Pegas el payload del webhook y pides: “Dame el fragmento JS para extraer estos campos y normalizarlos.”
    • Le pides la lógica de reintentos y manejo de errores: condiciones, backoff y notificaciones.
    • Si una API requiere HMAC o firma en cabeceras, Claude te escribe la plantilla para el nodo HTTP.

    Ejemplo (conceptual): le describes el JSON y obtienes el snippet listo para pegar en un Code Node de n8n. No tienes que memorizar async/await; solo validar la salida.

    Referencia: n8n (automatización)

    2) Transformar y analizar datos — sin pelear con hojas de cálculo eternas

    Limpiar datos es un agujero negro. Claude lo hace predecible.

    Casos concretos:

    • Generar regex para extraer emails, IDs o patrones específicos. (“Extrae solo .edu y .org que parezcan institucionales.”)
    • Convertir CSV/XML desordenados a JSON con esquema validado. Pegas 50 filas y pides el JSON-schema.
    • Redactar consultas SQL complejas: joins, ventanas, filtros por fechas. Le das la estructura de tablas y la métrica que quieres; él devuelve la query optimizada para tu caso.

    No es “codificar por ti”. Es convertir trabajo repetitivo y propenso a errores en instrucciones reproducibles.

    3) Documentación y diagramas técnicos que no te roban medio día

    El 70% del valor de una decisión técnica está en cómo se comunica. Claude entiende Mermaid.js y puede producir diagramas desde tu texto.

    Lo que recibes:

    • Código Mermaid listo para pegar en Notion o GitHub y ver el diagrama al instante.
    • Un borrador de OpenAPI a partir de la descripción de un endpoint (paths, parámetros, respuestas).
    • Un mapa de arquitectura cloud con dependencias y puntos de integración (ideal para alinear con ingeniería sin sonar inocente).

    Pequeña ventaja: llegas a la reunión con algo que se puede visualizar y discutir, no con una vaga idea.

    Docu: Mermaid (diagramas) · OpenAPI spec

    ¿Cómo decidir si usar Claude Code o Claude Web/API?

    Regla simple:

    • Si vas a dejar que un agente toque tu repo, ejecuciones y tests: Claude Code (requiere developer).
    • Si necesitas razonamiento, diseño de flujos, transformación de datos o documentación: Claude Web/API o integraciones (ideal para non-devs con criterio).

    El nuevo diferencial no es “saber programar”. Es saber estructurar problemas y validar hipótesis técnicas. Claude amplifica eso.

    Conclusión

    No conviertas la terminal en el test de tu valía. Aprende a describir problemas con precisión y tendrás una herramienta que piensa en arquitectura, no solo en sintaxis. Esto apenas comienza: la próxima ronda será cómo integrar Claude en tus procesos de despliegue y gobernanza sin romper producción.

    Fuentes útiles: Anthropic – Claude, n8n (automatización), Mermaid (diagramas), OpenAPI spec

    Para explorar implementaciones y experimentos relacionados con automatización y agentes, visita Dominicode Labs. Es una continuación lógica para quien quiere pasar del diseño a prototipos reproducibles.

    FAQ

    Respuesta: Claude Code es el agente CLI de Anthropic diseñado para operar en terminales y repos (requiere Git, variables de entorno y permisos de repo). Claude, en cambio, es el modelo accesible por web/API e integraciones y está orientado a razonamiento y generación sin necesidad de ejecutar comandos locales.

    Respuesta: No. Para acceder al razonamiento y generación de soluciones técnicas puedes usar Claude Web/API o integraciones; no necesitas ser developer, pero sí saber describir problemas con precisión.

    Respuesta: Sí. Puedes describir el payload o el problema y pedir snippets o plantillas listos para pegar en un Code Node de n8n, así evitas escribir Node.js desde cero.

    Respuesta: Generación de regex, conversión de CSV/XML a JSON con esquema validado, y redacción de consultas SQL complejas (joins, ventanas y filtros). Claude transforma tareas repetitivas en instrucciones reproducibles.

    Respuesta: Sí. Claude puede producir código Mermaid y borradores de OpenAPI que se pegan directamente en herramientas como Notion o GitHub para visualización inmediata.

    Respuesta: Elige que un agente toque tu repositorio cuando sea necesario ejecutar pruebas, aplicar cambios automáticos o inspeccionar código de forma programática. Si solo necesitas diseño, razonamiento o generación de artefactos técnicos, la web/API suele ser suficiente.

  • Implementación efectiva con Plan Mode en Claude Code

    Implementación efectiva con Plan Mode en Claude Code

    Plan Mode primero, código después: el workflow que cambia cómo trabajas con Claude Code

    Tiempo estimado de lectura: 5 min

    • Plan Mode obliga a auditar y planear antes de ejecutar cambios en código.
    • Workflow en tres fases: análisis, refinamiento y ejecución; cada fase reduce riesgo y scope de impacto.
    • Activa Plan Mode en cambios multiplataforma, código heredado o integraciones de librerías arquitectónicas.
    • Mide efectividad por integración sin rollback, estabilidad en CI y ahorro de horas en debugging.

    Plan Mode primero, código después es la regla que separa entregas limpias de correcciones interminables. Activa Plan Mode, deja que Claude analice el repositorio y produzca un plan antes de que toque una sola línea de código. Esa inversión de diez minutos evita horas de debugging por decisiones implícitas.

    Resumen rápido (lectores con prisa)

    Plan Mode obliga a auditar y planear cambios antes de codificar. Úsalo cuando el cambio implica múltiples archivos, código heredado o librerías que afectan la arquitectura. Workflow: análisis, refinamiento y ejecución. Mide por integración sin rollback y estabilidad en CI.

    Plan Mode primero, código después: qué es y por qué importa

    Plan Mode es un modo de sesión en Claude Code que obliga al agente a auditar el código existente, mapear dependencias y proponer una secuencia de cambios verificable antes de implementar. Se activa con Shift+Tab en sesiones interactivas de Claude Code; la documentación oficial lo describe como un flujo que prioriza planificación sobre ejecución (https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview y https://www.anthropic.com/claude).

    ¿Por qué importa? Porque los errores de diseño no son fallos de sintaxis: son decisiones implícitas que se propagan. Implementar primero amplifica esos errores. Planear primero los expone cuando aún cuestan cero cambios.

    Cómo funciona el workflow (práctico y repetible)

    El workflow consta de tres fases claras: análisis, refinamiento y ejecución. No son sugerencias; son pasos que los equipos efectivos repiten cuando integran agentes en su proceso.

    1) Análisis inicial (activar Plan Mode)

    Activa Plan Mode (Shift+Tab). Describe el objetivo como contrato, no como receta. Ejemplo: “Aísla la lógica de autenticación para pruebas unitarias sin DB” en vez de “usa repositorio para auth”. Deja que Claude liste archivos relevantes, dependencias directas y riesgos.

    2) Revisión y refinamiento (iterar sobre el plan)

    Lee el plan: archivos a tocar, orden propuesto, efectos secundarios y tests necesarios. Corrige límites de dominio si hace falta. Esa iteración es barata: texto, no commits. Aquí se define el alcance real y se evitan sorpresas de integración.

    3) Aprobación e implementación (ejecutar con control)

    Aprobas el plan y Claude implementa en el orden validado. Cada cambio es acotado, con tests adjuntos y notas de diseño. Si algo rompe, el impacto está limitado al módulo que se aprobó, no a toda la base de código.

    Ejemplo real de uso en migración

    Meta: migrar API REST a tRPC por módulos.

    Spec

    • Módulo A: AuthService (sin dependencias).
    • Módulo B: UserService (depende de A).
    • Módulo C: Billing (depende de B).

    Con Plan Mode, Claude devuelve: archivos a crear/modificar por módulo, tipos DTO esperados, tests unitarios y orden de merges. Implementación ocurre por sesión por módulo. Resultado: integraciones predecibles y rollback sencillo.

    Cuándo activar Plan Mode (criterio técnico)

    Activa Plan Mode cuando:

    • El cambio afecta múltiples archivos o contracts públicos.
    • Trabajas en código heredado que no conoces.
    • Vas a integrar una librería que afecta la arquitectura (auth, DB, infra).
    • La tarea es una refactorización o migración.

    No lo actives cuando:

    • El cambio es un ajuste pequeño en un único archivo.
    • Creas un archivo nuevo con una spec cerrada.
    • Resuelves un typo o validación trivial.

    El criterio es simple: a mayor riesgo arquitectónico, mayor valor del plan previo.

    Reglas prácticas para que Plan Mode funcione

    • Siempre comienza con CLAUDE.md actualizado. El agente leerá convenciones y patrones prohibidos antes de planear (si tu repo lo tiene, intégralo; si no, crea uno).
    • Exige que el plan incluya: archivos modificados, orden de cambios, tests a ejecutar y riesgos conocidos.
    • Valida el plan tú, un peer o el tech lead; las aprobaciones humanas reducen regresiones.
    • Mantén las sesiones acotadas: una sesión = un módulo. Evita planos globales indefinidos.

    Métricas que importan (no solo LOC/hora)

    Mide efectividad por:

    • Tiempo hasta integración sin rollback.
    • Número de handoffs con correcciones arquitectónicas.
    • Cobertura y estabilidad en CI tras cada merge.
    • Tiempo invertido en revisión del plan vs. horas ahorradas en debugging.

    Un plan de 10 minutos que evita 2 horas de corrección es ROI directo.

    Riesgos y límites honestos

    Plan Mode reduce errores, no elimina la necesidad de juicio humano. Si la spec es ambigua, Claude producirá una implementación ambigua más rápido. El agente no reemplaza decisiones críticas de diseño, trade-offs de rendimiento o consideraciones legales de seguridad. Su fuerza está en ejecutar lo que tú especificas mejor y antes de que toque escribir código.

    Conclusión

    Adoptar “Plan Mode primero, código después” cambia la métrica del equipo: de velocidad de salida a resiliencia de la plataforma. Si quieres que Claude Code deje de ser un generador de parches y pase a ser un colaborador técnico confiable, exige un plan. Haz que piense antes de tocar tu repo.

    Para equipos que exploran workflows, integraciones y automatización avanzada, consulta Dominicode Labs como continuación lógica del enfoque: recursos y experimentos centrados en agentes y productividad técnica.

    FAQ

    ¿Qué es Plan Mode?

    Plan Mode es un modo de sesión en Claude Code que obliga al agente a auditar el código existente, mapear dependencias y proponer una secuencia de cambios verificable antes de implementar.

    ¿Cuándo debo activarlo?

    Actívalo cuando el cambio afecta múltiples archivos, trabajas en código heredado, o integras librerías que afectan la arquitectura. Para cambios pequeños y aislados no es necesario.

    ¿Qué debe incluir un plan mínimo?

    El plan debe listar archivos a modificar, orden de cambios, tests a ejecutar y riesgos conocidos. También conviene indicar límites de dominio y criterios de aceptación.

    ¿Cómo reduce el riesgo en migraciones?

    Al definir el alcance y el orden de merge por módulo, limita el blast radius y facilita rollbacks. Permite validar la integración por partes con tests adjuntos.

    ¿Plan Mode reemplaza la revisión humana?

    No. Plan Mode reduce errores estructurales, pero las aprobaciones humanas siguen siendo necesarias para decisiones críticas y trade-offs no técnicos.

    ¿Qué métricas debe rastrear mi equipo?

    Tiempo hasta integración sin rollback, número de handoffs con correcciones arquitectónicas, cobertura y estabilidad en CI, y la relación entre tiempo de planificación y horas ahorradas en debugging.

  • Dominando Claude Code como agente CLI para automatización efectiva

    Dominando Claude Code como agente CLI para automatización efectiva

    Claude Code – La guía práctica: Ingeniería de agentes en la terminal

    Tiempo estimado de lectura: 4 min

    • Claude Code es un agente CLI que lee árbol de archivos, ejecuta bash, corre tests y propone parches; requiere sandboxes y gobernanza técnica.
    • Controla tokens y contexto desde el día 1 usando comandos operativos como /cost, /compact y flags como --safe.
    • Define prompts como contratos con contexto, tarea, restricciones, verificación y condición de parada para evitar bucles.
    • Extiende de forma segura con MCP y orquesta validaciones con n8n; nunca expongas credenciales y aísla ejecuciones en contenedores.
    • Aplica políticas de seguridad, revisión humana obligatoria y auditoría de logs antes de producción.

    Claude Code – La guía práctica es el manual operativo que necesitas si tu equipo va a delegar trabajo real en un agente CLI. Claude Code (Claude 3.7 Sonnet) no es un autocompletador: es un agente que lee el árbol de archivos, ejecuta bash, corre tests y propone parches. Dominarlo exige reglas claras, sandboxes y gobernanza técnica.

    Resumen rápido (lectores con prisa)

    Claude Code es un agente CLI capaz de operar sobre repositorios (leer archivos, ejecutar comandos, proponer parches). Úsalo con sandboxes (Docker/DevContainers), define prompts como contratos y controla costes con comandos como /cost. Extiende funciones con MCP y orquesta validaciones con n8n, manteniendo revisión humana para cambios sensibles.

    Claude Code – La guía práctica: qué aprender primero

    Arranca por lo esencial. La documentación oficial y el MCP son la base:

    Instalación básica

    Instalación global con npm:

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

    Crea un .claudeignore en la raíz para proteger secretos:

    .env*
node_modules/
dist/
secrets/
*.log

    Lee “Permissions and Security” en la docs antes de ejecutar en repos real. No es opcional.

    Fundamentos operativos: control de contexto y coste

    Claude Code consume tokens por lectura/escritura. Controla eso desde el día 1.

    Operaciones y flags

    • /cost — audita tokens de la sesión. Obliga a revisar antes de tareas largas.
    • /compact — comprime historial de conversación para evitar alucinaciones si el agente lleva horas iterando.
    • /abort — detiene loops. Úsalo rápido si ves repetición.
    • Flags: --safe (revisar comandos propuestos), --read-only (auditoría sin mutar), --detach (tareas largas en background).

    Estos comandos son tus palancas operativas para no perder control.

    Ingeniería de prompts y contratos de ejecución

    Un prompt es un contrato, no un deseo. Estructura clara:

    • Contexto (stack, convenciones).
    • Tarea (qué cambiar).
    • Restricciones (qué no tocar).
    • Verificación (tests, coverage, linter).
    • Condición de parada (máx iteraciones).

    Ejemplo compactado

    Contexto: Angular 22 Zoneless.
Tarea: Migrar src/dashboard a Standalone Components usando Signals.
Restricciones: No tocar auth-service.
Verificación: Ejecutar `vitest --coverage` y superar 90%.
Parada: Abortar si >3 iteraciones fallidas.

    Sin eso, el agente entra en bucles y consume tokens sin producir valor.

    Extensibilidad: MCP y orquestación con n8n

    MCP te permite dar herramientas seguras al agente. Monta un servidor MCP interno y expón solo capacidades limitadas (leer DB, disparar webhooks), nunca credenciales.

    Ejemplo conceptual de servidor MCP (Node.js)

    // mcp-server.js (conceptual)
const { createServer } = require('mcp');
const server = createServer({
  capabilities: {
    read_file: true,
    execute_shell: { shell: 'bash', workingDir: '/workspace' },
    trigger_n8n: { url: 'http://localhost:5678/webhook' }
  }
});
server.listen(8080);

    Integra con Claude Code: /mcp add --url http://localhost:8080.

    Flujo n8n recomendado

    1. Claude genera diff + artefactos.
    2. MCP envia payload a n8n.
    3. n8n ejecuta validaciones (linters, tests), crea ticket y notifica Slack.

    Así mantienes trazabilidad y control humano.

    Seguridad y sandboxing: reglas innegociables

    • Nunca ejecutes tareas destructivas en la host machine. Usa Docker/DevContainers.
    • .claudeignore obligatorio y auditado por SAST.
    • Políticas de gasto: quotas por usuario/equipo en Anthropic Console.
    • Revisión humana obligatoria para cambios que modifiquen infra o credenciales.
    • Logs y auditoría: guarda transcripts de sesiones y resultados de /cost.

    Riesgos comunes y mitigaciones rápidas

    • Bucles por flaky tests → define max_iterations en prompt; usa --safe.
    • Consumo inesperado de tokens → descompón tareas; monitoriza /cost.
    • Fuga de secretos → .claudeignore + escaneo pre-run.
    • Dependencias legacy (p. ej. zone.js en Angular) → audita npm ls previo y fija tests que cubran edge cases.

    Cuándo adoptarlo (criterio para Tech Leads)

    Adopta Claude Code si:

    • Tienes stack moderno (TypeScript, Angular 22+, Next.js).
    • La base tiene tests automáticos (Vitest/Playwright).
    • Puedes aislar ejecuciones en contenedores y aplicar políticas de gasto.

    Pospón si:

    • Repo monolítico sin cobertura.
    • Equipo sin habilidades de prompt engineering.
    • Restricciones presupuestarias que no toleran picos de tokens.

    Roadmap práctico (4 semanas)

    • Semana 1: Sandbox + --safe, .claudeignore, métricas /cost.
    • Semana 2: Prompts estructurados y pruebas automáticas con Vitest.
    • Semana 3: Implementa servidor MCP mínimo y flujo n8n.
    • Semana 4: Políticas de gobernanza, cuotas, playbook de incidentes.

    Claude Code no es magia; es ingeniería aplicada. Monta sandbox, define contratos de prompts, limita el alcance con MCP y registra todo. Hazlo bien y convertirás la terminal en un colaborador que acelera refactors y tareas repetitivas sin apagar el control humano. Esto empieza hoy: configura el sandbox y documenta las reglas internas; el resto viene después.

    Dominicode Labs

    Para equipos que diseñan flujos de automatización y orquestación con agentes, una fuente útil de referencia y experimentación es Dominicode Labs. Puede servir como continuación lógica para prototipar MCP + n8n y playbooks de gobernanza.

    Referencias y recursos

    FAQ

    ¿Qué es Claude Code y en qué se diferencia de un autocompletador?

    Claude Code es un agente CLI que puede leer el árbol de archivos, ejecutar comandos de shell, correr tests y proponer parches. No es solo un autocompletador: realiza acciones sobre el repositorio y requiere control operativo y políticas de seguridad.

    ¿Cómo evito que el agente consuma tokens excesivos?

    Monitorea con /cost, descompón tareas largas, establece max_iterations en prompts y usa /compact para reducir historial. Usa flags como --safe para revisar comandos propuestos.

    ¿Qué medidas de seguridad son obligatorias antes de ejecutar en repos reales?

    Usar sandboxes (Docker/DevContainers), tener .claudeignore auditado por SAST, cuotas en Anthropic Console y revisión humana para cambios que modifiquen infra o credenciales.

    ¿Qué es MCP y por qué usarlo?

    MCP (Model Context Protocol) permite exponer capacidades limitadas y seguras al agente (leer archivos, ejecutar shell controlado, disparar webhooks) sin revelar credenciales. Facilita gobernanza y trazabilidad.

    ¿Cuándo debo usar --safe o --read-only?

    Usa --safe para revisar comandos propuestos por el agente en tareas de riesgo, y --read-only para auditorías o análisis sin mutar el repositorio.

    ¿Cómo integro validaciones automáticas con n8n?

    Configura MCP para enviar payloads a n8n; n8n ejecuta linters y tests, crea tickets y notifica Slack. El flujo recomendado: Claude genera diff, MCP envía a n8n, n8n valida y crea trazabilidad.

    ¿Qué debe incluir un prompt para evitar bucles?

    Un prompt debe contener: contexto (stack), tarea específica, restricciones explícitas, criterios de verificación (tests, coverage) y condición de parada (máx iteraciones).

  • Cómo formar equipos efectivos en el uso de Claude Code

    Cómo formar equipos efectivos en el uso de Claude Code

    Claude code : ¿Recursos de formación?

    Tiempo estimado de lectura: 6 min

    • Prioriza seguridad operativa y control de contexto para evitar fugas de secretos y alucinaciones.
    • Entrenamiento práctico y medible: prompts con criterios de aceptación, tests y métricas (tokens/tarea, errores introducidos).
    • Monta MCP interno y políticas de gobernanza antes de permitir ejecuciones automáticas en repositorios importantes.

    Introducción

    Claude code : ¿Recursos de formación? Si eres Tech Lead o developer, no buscas cursos genéricos: buscas un plan operativo que reduzca riesgos y te haga productivo rápido. Claude Code (CLI de Anthropic impulsado por Claude 3.7 Sonnet) exige entrenamiento práctico, no diplomas. Aquí tienes la ruta técnica, recursos verificados y una hoja de ruta para formar equipos sin incendiar el repo.

    Resumen rápido (lectores con prisa)

    Qué es: Claude Code es un CLI de Anthropic (Claude 3.7 Sonnet) para automatizar tareas de desarrollo con capacidades de ejecución y acceso a contexto.

    Cuándo usarlo: Scaffolding, refactors controlados y generación asistida donde haya tests y sandboxing.

    Por qué importa: Acelera tareas repetibles, pero introduce riesgos operativos que requieren políticas claras.

    Cómo funciona (alto nivel): Usa prompts CLI, puede integrarse con MCP para exponer servicios internos y ejecutar comandos en entornos controlados.

    Claude code : ¿Recursos de formación? Fuentes primarias y por dónde empezar

    No hay atajos. Prioriza estas fuentes oficiales y documentación técnica.

    • Documentación oficial de Anthropic: Lee primero “Permissions and Security”. Aprende /compact, /cost, modos --safe y .claudeignore.
    • Model Context Protocol (MCP): MCP es la puerta para integrar Claude Code con servicios internos (DB, n8n, CI).
    • Repositorios ejemplo y utilidades comunitarias (audita antes de usar): busca en GitHub ejemplos oficiales y experimentos MCP.

    Instalación mínima y .claudeignore

    Instalación mínima:

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

    Y un .claudeignore básico:

    .env
node_modules/
secrets/
*.log

    Qué debes enseñar primero (y por qué)

    Estos temas son controles de supervivencia, no “trucos”.

    Seguridad operativa

    Claude Code puede ejecutar bash local. Enseña flags --safe y --read-only.

    Política: nunca ejecutar en prod sin contenedor y revisión.

    Gestión de contexto

    Usar /compact cada X iteraciones para evitar alucinaciones por tokens.

    Cost control

    Monitorizar /cost y establecer cuotas.

    Prompt engineering en CLI

    Prompts con criterios de aceptación, límites de iteración y pasos verificables.

    Integración MCP

    Cómo exponer solo lo necesario a través de un servidor MCP interno.

    Plan de formación práctico (4 semanas, orientado a resultados)

    Semana 0 — Preparación

    Semana 0 — Preparación

    • Crea sandbox: repo pequeño (ej. componente Angular a migrar).
    • Prepara contenedor Docker con volumen montado y user no-root.
    • Añade .claudeignore y política de secrets.

    Semana 1 — Básicos y prompts

    • Ejercicios: pedir refactor simple (un componente), revisar diffs.
    • Métricas: tokens/tarea, tiempo ahorrado, errores introducidos.

    Semana 2 — Tests y seguridad

    • Forzar ejecución de tests antes de merge (Vitest/Playwright).
    • Practicar --safe y revisión manual de comandos. Simular flaky tests.

    Semana 3 — MCP y orquestación

    • Implementa un servidor MCP mínimo y conecta un flujo con n8n para almacenar artefactos.
    • Ejercicio: scaffolding + pruebas + push a rama canaria.

    Semana 4 — Operaciones y gobernanza

    • Policies: gasto por dev (p. ej. $10–20/dev/día inicial), logs y auditoría.
    • Playbook de incidentes: cómo abortar, revertir y analizar.

    Ejemplo mínimo de servidor MCP (concepto)

    mcp-server.js (conceptual)

    // mcp-server.js (conceptual)
const { createServer } = require('mcp');
const server = createServer({
  capabilities: {
    read_file: true,
    execute_shell: { shell: 'bash', workingDir: '/workspace' }
  }
});
server.listen(8080);

    Conecta con Claude Code usando: /mcp --url http://localhost:8080.

    Riesgos reales y cómo mitigarlos

    • Bucles infinitos por flaky tests. Mitigación: max_iterations: 5 en prompt y monitor /cost.
    • Fuga de secretos. Mitigación: .claudeignore obligatorio + escaneo SAST.
    • Consumo de tokens impredecible. Mitigación: descomponer tareas; usar --safe; cuotas y alertas.
    • Dependencias legacy. Mitigación: auditoría npm ls y tests en staging.

    Gobernanza: reglas mínimas que debes imponer

    • No ejecuciones directas en machines prod. Siempre contenedor.
    • .claudeignore estándar global en org.
    • Revisiones de diffs obligatorias; CI falla si el agente hace cambios sin tests.
    • MCP servers sólo internos; no permitir servers MCP remotos sin revisión.

    Integración con n8n y workflows

    Claude Code es bueno para scaffolding y refactors; n8n gana cuando necesitas orquestar artefactos: enviar reportes, crear tickets o almacenar previews. Con MCP puedes:

    • Ejecutar tarea en sandbox (Claude Code).
    • n8n recoge el diff, ejecuta linters y notifica en Slack.
    • CI valida y programa canary deployment.

    ¿Invertir ahora o esperar?

    Invierte si tu equipo tiene:

    • Stack moderno (TypeScript, frameworks recientes).
    • Tests automatizados y capacidad para aislar ejecuciones.
    • Recursos para gobernanza y auditoría.

    Pospón si tu repo es un monolito sin tests o si no puedes aislar ejecuciones. La automatización sin controles es una bomba de relojería.

    Conclusión

    Claude code : ¿Recursos de formación? no se responde con un curso; se responde con un programa práctico, controles operativos y playbooks internos. Monta el sandbox hoy, documenta los patrones que funcionen y publica tu propio “manual corporativo” —ese será tu mejor recurso de formación. Esto no acaba aquí: empieza con un sprint y conviértelo en conocimiento institucional.

    Dominicode Labs

    Como continuación lógica para equipos que implementan automatización y workflows internos, considera consultar recursos y experimentos adicionales en Dominicode Labs. Puede servir como referencia para pruebas de concepto y playbooks operativos.

    FAQ

    ¿Qué es Claude Code y qué modelo usa?

    Claude Code es un CLI de Anthropic diseñado para automatizar tareas de desarrollo; en el contexto descrito utiliza Claude 3.7 Sonnet.

    ¿Por qué es importante usar .claudeignore?

    Para evitar exponer secretos, archivos grandes o directorios sensibles al agente. El documento incluye un ejemplo básico de .claudeignore.

    ¿Qué es MCP y para qué sirve?

    MCP (Model Context Protocol) es un estándar para exponer contexto y capacidades a modelos/agents. Permite integrar Claude Code con DBs, n8n, CI y otros servicios internos de manera controlada.

    ¿Cómo mitigo el riesgo de bucles infinitos?

    Establece max_iterations en prompts (por ejemplo 5), monitoriza /cost y aplica cuotas y alertas.

    ¿Cuándo no debería usar Claude Code?

    No lo uses si tu repo es un monolito sin tests, si no puedes aislar ejecuciones o si no tienes políticas de gobernanza y auditoría claras.

    ¿Qué métricas debo recoger durante el entrenamiento?

    Tokens por tarea, tiempo ahorrado, número de errores introducidos y tasa de fallos en CI. Estas métricas permiten validar eficacia y seguridad del modelo en workflows reales.