DOMINICODE

Tag: Anthropic Claude

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

  • Cómo optimizar Agentes y Skills en Claude Code para un mejor rendimiento

    Cómo optimizar Agentes y Skills en Claude Code para un mejor rendimiento

    entender Agentes vs Skills, en Claude code, trade-offs de los agentes, y los trade-offs de los modelos

    ¿Quieres que tu sistema con Claude deje de comportarse como un aprendiz despistado y empiece a trabajar como un equipo bien entrenado? entender Agentes vs Skills, en Claude code, trade-offs de los agentes, y los trade-offs de los modelos es el primer paso. No es filosofía; es diseño técnico que decide costes, latencia y confiabilidad.

    En una frase: una Skill es una herramienta; un Agente es quien decide cuándo y cómo usarla. En Claude Code (y en el Model Context Protocol) esa diferencia no es semántica: define el control flow, la observabilidad y la estrategia de modelo.

    Resumen rápido (lectores con prisa)

    Qué es: Skill = función stateless y determinista; Agente = sistema que orquesta Skills con loop de razonamiento.

    Cuándo usarlo: Skill para flujos deterministas; Agente para tareas multi-step y adaptativas.

    Por qué importa: determina latencia, coste, observabilidad y riesgo de loops.

    Cómo funciona (alto nivel): Agente observa, planifica, invoca Skills y verifica; Skills exponen APIs claras (MCP/HTTP).

    Tiempo estimado de lectura

    Tiempo estimado de lectura: 5 min

    Ideas clave

    • Skills son funciones deterministas y stateless; expónlas como APIs claras.
    • Agentes orquestan Skills y gestionan objetivo, memoria y reintentos.
    • Los agentes añaden latencia, coste e indeterminismo; requieren guardrails y observabilidad.
    • Elige modelo por trade-off: Haiku (rápido/barato), Sonnet (equilibrio), Opus (máxima calidad).
    • Patrón híbrido recomendado: router ligero → Skills directas → Agentes especializados → guardrails y tracing.

    Tabla de contenidos

    Introducción

    ¿Quieres que tu sistema con Claude deje de comportarse como un aprendiz despistado y empiece a trabajar como un equipo bien entrenado? entender Agentes vs Skills, en Claude code, trade-offs de los agentes, y los trade-offs de los modelos es el primer paso. No es filosofía; es diseño técnico que decide costes, latencia y confiabilidad.

    Agentes vs Skills: la distinción que evita catástrofes

    Skills = funciones puntuales, deterministas y stateless.

    Skills

    • readFile(path), runSQL(query), sendSlack(channel, text).
    • Implementadas como código tradicional (JS/Python) y expuestas al modelo con una firma clara (MCP/HTTP).
    • No razonan. Ejecutan.

    Agentes

    • Mantienen objetivo, memoria y loop de razonamiento (Observe → Plan → Act → Verify).
    • Un Agente puede invocar múltiples Skills, evaluar resultados, reintentar o escalar a humano.
    • En Claude Code, el Agente es la instancia del modelo que ejecuta el bucle y usa las Skills ofrecidas por el runtime.

    Técnicamente: Skills son APIs; Agentes son sistemas de control y decisión que consumen esas APIs.

    Por qué importa: trade-offs de los agentes

    Autonomía suena bien hasta que el Agente se vuelve caro o tóxico. Estos son los efectos prácticos que deberías medir.

    Latencia multiplicada

    Cada paso del bucle agrega llamadas al modelo y a Skills. Una tarea que toma 2s con una Skill directa puede tardar 15–30s con un Agente que valida y reintenta. Para workflows interactivos eso mata la UX.

    Riesgo de loops infinitos

    Si no limitas iteraciones o detectas patrones repetitivos, el Agente puede intentar la misma corrección 1000 veces. Resultado: facturas de API astronómicas y procesos bloqueados.

    Indeterminismo e idempotencia perdida

    Un Agente puede resolver la misma tarea de maneras distintas. Eso da flexibilidad ante casos abiertos, pero complica testing, CI/CD y auditoría. Necesitas validaciones basadas en propiedades (constraints) en lugar de resultados fijos.

    Observabilidad y debugging costosos

    Debuguear un flow agéntico exige trazas por cada llamada LLM ↔ Skill, snapshots de memoria y métricas de confianza. Sin esto, los fallos solo se detectan cuando el usuario se queja.

    Mitigaciones prácticas:

    • Limitar pasos y tiempo por tarea (timeouts cognitivos).
    • Implementar detección de retries repetidos y bloqueo.
    • Validación post-acción (tests automáticos, checksums, schema validation).
    • Escalada a humano cuando la confianza baja.

    Trade-offs de los modelos: elegir Sonnet, Haiku u Opus

    No todos los modelos sirven para todo. Aquí el criterio es coste versus capacidad de razonamiento.

    Claude 3.5 Sonnet — el equilibrio

    • Pros: razonamiento sólido, buen manejo de Tool Use y generación de código.
    • Contras: coste y latencia moderados.
    • Uso: cerebro del Agente para planificación y edición de código.

    Claude 3 Haiku — router / executor barato

    • Pros: rápido y barato.
    • Contras: menos capaz en razonamiento profundo; mayor riesgo de alucinación en tareas complejas.
    • Uso: clasificación, enrutamiento, pre-filtros, resumen rápido o conversión simple.

    Claude 3 Opus — máxima calidad (cuando el coste no importa)

    • Pros: razonamiento profundo y menor tasa de error en zero-shot.
    • Contras: latencia y coste altos.
    • Uso: análisis crítico donde la calidad es la prioridad absoluta.

    Arquitectura recomendada: híbrida. Usa Haiku como router inicial; Sonnet para agentes especializados; Opus solo en batches o tareas off-line costosas.

    Patrón de despliegue práctico (claude-code + MCP)

    1. Router (Haiku): decide si la petición necesita Skill directa o Agente Sonnet.

    2. Skill directa: ejecutar si el flujo es determinista (p. ej. ETL, queries, envíos).

    3. Agente Sonnet: para tareas multi-step (refactor, investigación, remediación).

    4. Guardrails: límites de iteración, chequeos de schema, registros de decisión.

    5. Observabilidad: tracing por etapa (LLM prompt/responses, llamadas Skill, costos).

    Para referencia del runtime y la integración con Skills revisa la documentación de Claude Code en el portal de Anthropic (y el repositorio de ejemplo).

    Criterio final para un Tech Lead

    Decide según tres preguntas:

    • ¿Es el flujo determinista? Usa una Skill.
    • ¿Requiere adaptación y varios pasos? Construye un Agente.
    • ¿Cuál es el SLA de latencia y el presupuesto de coste? Selecciona Haiku/Sonnet/Opus acorde al ROI.

    No es magia: es ingeniería de trade-offs. Un Agente bien diseñado reduce intervención humana y aumenta alcance, pero exige observabilidad, límites y selección cuidadosa de modelo. En Dominicode tratamos Agentes como infraestructura: medimos, protegemos y versionamos. Haz lo mismo y tu Claude Code dejará de improvisar y empezará a producir.

    Dominicode Labs

    Si trabajas con automatización, agentes o workflows, puedes encontrar recursos adicionales y experimentos en Dominicode Labs. Es un complemento práctico para aplicar patrones de despliegue, guardrails y observabilidad en proyectos reales.

    FAQ

    ¿Cuándo debería preferir una Skill sobre un Agente?

    Usa una Skill cuando el flujo sea determinista, idempotente y pueda representarse como una API con firma clara (por ejemplo ETL, consultas, envíos). Las Skills reducen latencia y coste y facilitan testing y CI/CD.

    ¿Cómo mitigo el riesgo de loops infinitos en un Agente?

    Implementa límites de iteración, timeouts cognitivos y detección de patrones de retry repetidos. Añade reglas que bloqueen acciones cuando se superan umbrales y escalamiento a humano cuando la confianza sea baja.

    ¿Qué observabilidad mínima necesito para un Agente en producción?

    Traza cada llamada LLM ↔ Skill, snapshots de memoria relevantes y métricas de confianza/decisión. Registra costos por etapa para analizar trade-offs de latencia y gasto.

    ¿Cómo selecciono entre Haiku, Sonnet y Opus?

    Elige según coste vs capacidad de razonamiento: Haiku para routing y tareas simples; Sonnet como cerebro del Agente para planificación y edición; Opus para análisis crítico donde la calidad justifica el coste.

    ¿Qué prácticas recomiendan para validar acciones de un Agente?

    Usa validación post-acción: tests automáticos, checksums y validación de esquema. Implementa constraints que verifiquen propiedades del resultado más que un valor exacto.

    ¿Debo versionar Skills y Agentes por separado?

    Sí. Trata Skills como infra y versiona sus APIs. Versiona Agentes por su política de decisión, prompts y memoria para poder reproducir y auditar comportamientos en producción.

  • Cómo crear un plugin para Anthropic Claude usando MCP

    Cómo crear un plugin para Anthropic Claude usando MCP

    Crear tu primer plugin para Anthropic Claude (Claude Code)

    Crear tu primer plugin para Anthropic Claude (Claude Code) no es magia. Es arquitectura. En vez de «pegar texto en el prompt», vas a exponer funciones ejecutables que Claude puede invocar como herramientas reales. Aquí tienes una guía práctica, técnica y directa para hacerlo funcionar en minutos.

    Tiempo estimado de lectura: 5 min

    • Convierte prompts en herramientas: expón funciones (tools) que Claude invoca mediante MCP en lugar de meter contexto en el prompt.
    • Implementa un servidor MCP: el servidor genera schemas automáticamente y maneja llamadas desde Claude (ej.: FastMCP en Python).
    • Seguridad y fiabilidad: docstrings claros, timeouts, manejo de errores y principio de menor privilegio son imprescindibles.
    • Observabilidad y versionado: registra llamadas, latencias y versiona schemas para evitar rupturas en producción.
    • Integración: estas tools pueden orquestarse en n8n u otros workflows como nodos reutilizables.

    Introducción

    Un “plugin” en Claude es, en realidad, Tool Use o Function Calling via Model Context Protocol (MCP). No le estás metiendo código al modelo: le das una API estructurada y el modelo decide cuándo llamarla. Tu servidor ejecuta la lógica real (Python/TS/Go) y el modelo actúa como cliente que conoce las herramientas disponibles mediante un schema.

    Resumen rápido (lectores con prisa)

    Qué es: Exponer funciones ejecutables (tools) que Claude puede invocar vía MCP.

    Cuándo usarlo: Cuando necesites que el asistente consulte sistemas externos, ejecute acciones o maneje datos sin inflar el prompt.

    Por qué importa: Permite acciones deterministas, auditables y seguras desde un asistente LLM.

    Cómo funciona: El modelo selecciona una tool, genera parámetros según el schema y llama al servidor MCP; el servidor responde con texto estructurado.

    ¿Qué es un “plugin” en Claude?

    Conceptualmente:

    • Claude = cliente que conoce las herramientas disponibles mediante un schema.
    • MCP = protocolo que negocia llamadas entre Claude y tu servicio (stdio, HTTP, WebSocket).
    • Tu servidor = el plugin: código real que ejecuta la lógica (Python/TS/Go).

    No le estás metiendo código al modelo. Le das una API estructurada y el modelo decide cuándo llamarla.

    ¿Qué necesitas y por qué importa?

    ¿Por qué hacerlo? Porque así conviertes un asistente en un agente capaz de:

    • consultar bases de datos internas,
    • ejecutar comprobaciones de infra,
    • automatizar workflows en n8n,

    sin inundar el prompt con contexto ni exponer credenciales en texto.

    Requisitos mínimos:

    Código mínimo: servidor MCP en Python

    Este ejemplo expone una tool que verifica el estado HTTP de una URL usando FastMCP. Copia, ajusta y ejecuta.

    from mcp.server.fastmcp import FastMCP
import httpx

mcp = FastMCP("WebChecker")

@mcp.tool()
async def check_website_status(url: str) -> str:
    """
    Verifica el estado HTTP de una URL.
    Args:
      url: URL completa (ej: https://dominicode.com)
    Returns:
      Mensaje con código y razón, o error legible.
    """
    try:
        async with httpx.AsyncClient(timeout=5.0) as client:
            r = await client.get(url, follow_redirects=True)
            return f"Status: {r.status_code} - {r.reason_phrase}"
    except Exception as e:
        return f"Error: {str(e)}"

if __name__ == "__main__":
    mcp.run()

    FastMCP genera automáticamente el schema de la tool a partir de los type hints y docstrings. No escribes JSON a mano.

    Registrar el plugin en Claude Desktop / CLI

    Para que Claude vea tu servidor local, añade una entrada en la configuración de Claude Desktop:

    – macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
    – Windows: %APPDATA%\Claude\claude_desktop_config.json

    Ejemplo:

    {
  "mcpServers": {
    "web-checker": {
      "command": "python",
      "args": ["/ruta/absoluta/a/server.py"]
    }
  }
}

    Reinicia Claude. Deberías ver el servidor activo (icono de enchufe).

    Flujo de ejecución (Thinking Loop)

    Cuando pides: “Claude, comprueba si dominicode.com responde”, sucede:

    1. Claude detecta necesidad de herramienta.
    2. Selecciona check_website_status.
    3. Genera parámetros (url).
    4. Llama al plugin vía MCP.
    5. El plugin responde con texto estructurado.
    6. Claude formatea la respuesta humana.

    Todo ordenado, trazable y auditable.

    Buenas prácticas imprescindibles

    Docstrings son contratos

    Escribe docstrings claros. El modelo usa esa información para construir la llamada. Ambigüedad = invocación errónea.

    Errores controlados

    Nunca dejes que tu plugin haga crash. Captura excepciones y devuelve mensajes legibles. Si tu proceso muere, Claude pierde acceso a todo ese servidor.

    Timeouts defensivos

    Usa timeouts explícitos (ej. httpx timeout=5s). No querrás procesos colgados.

    Principio de menor privilegio

    No implementes tools como exec_shell(cmd) a la ligera. Restringe rutas, usuarios y operaciones. Si necesitas ejecutar comandos, envuelve y valida cada input.

    Observabilidad

    Loguea prompts recibidos, respuestas, latencias y costes. Traza cada call LLM ↔ tool. Para infra, añade métricas que permitan alertas (ERRORES, RETRIES, LATENCIA).

    Gestión de versiones

    Versiona schemas y tools. Cambiar la firma de una función sin versionado rompe agentes y workflows en producción.

    Escalada humana

    Si el agente entra en loop o baja de confianza, define una regla clara: cortar, crear ticket y notificar a un responsable.

    Integración con workflows y n8n

    Estas tools son bloques reutilizables. Úsalas como nodos en n8n o como pasos en un orquestador de agentes. Por ejemplo:

    • Nodo n8n invoca tu API plugin para obtener estado.
    • Resultado condicional dispara un PR automático o un Slack alert.

    Recursos y lectura adicional

    Cierre operativo

    Crear un plugin para Claude Code es convertir una idea en una API que el modelo puede invocar de forma determinista. No es magia; es ingeniería de interfaces. Empieza con una tool pequeña, aplícala en un workflow y añade observabilidad. Si lo haces bien, tu Claude dejará de hablar y empezará a actuar.

    Esto no acaba aquí: construye la siguiente tool, versiona el schema y orquesta esas tools con un agente. Tu siguiente despliegue será la prueba.

    Dominicode Labs

    Si quieres prototipar y validar pipelines de agentes y automatizaciones, revisa Dominicode Labs. Es una continuación natural para integrar tools, pruebas y orquestación en entornos de trabajo técnico.

    FAQ

    ¿Qué diferencia hay entre un plugin y poner contexto en el prompt?

    Un plugin expone funciones ejecutables con schemas; el modelo invoca esas funciones. Poner contexto en el prompt implica enviar datos y lógica de forma textual, sin capacidad de ejecución externa ni trazabilidad.

    ¿Qué es MCP?

    MCP (Model Context Protocol) es el protocolo que negocia llamadas entre el modelo y tu servicio (stdio, HTTP, WebSocket), permitiendo que el modelo conozca y llame herramientas.

    ¿Por qué usar docstrings en lugar de JSON manual?

    Frameworks como FastMCP generan schemas automáticamente a partir de type hints y docstrings, reduciendo errores y manteniendo documentación y contratos sincronizados.

    ¿Cómo manejo errores para que Claude no pierda acceso?

    Captura excepciones, devuelve mensajes legibles y usa timeouts defensivos. No permitas que el proceso principal haga crash; implementa reinicios supervisados y health checks.

    ¿Qué precauciones de seguridad debo tomar?

    Aplica principio de menor privilegio, valida y sanitiza inputs, restringe rutas y comandos, y evita exponer credenciales en texto plano.

    ¿Puedo integrar estas tools en n8n?

    Sí. Usa las tools como nodos o llamadas API desde n8n; el resultado puede condicionar flujos, crear PRs o enviar alertas en Slack.