Claude Code: Workshop Práctico

Resumen

Workshop hands-on de 3 horas donde los participantes aprenderán Claude Code construyendo un proyecto web real y configurando flujos de trabajo automatizados.

📅 Agenda

Workshop de 3 horas

1. Bienvenida e Introducción (10 min)
2. Instalación y Configuración (25 min)
   • Instalación de Claude Code
   • Setup inicial
3. Integración con VS Code (15 min)
4. Primera Interacción con Claude (10 min)
5. Construcción de Sitio Web (45 min)
   • Crear sitio web responsivo
   • Configuración para AWS Amplify
6. Manejo de Git con Claude (15 min)
7. Creación de Subagentes (30 min)
   • Subagente html-css-standards
   • Subagente repo-structure-manager
8. Debugging y Mejoras (20 min)
9. Servidor MCP Weather (15 min)
10. Despliegue con Amplify (15 min)
11. Q&A y Cierre (10 min)

Requisitos Previos

• Laptop con Node.js 18+ instalado
• Cuenta de Claude
• Terminal y editor de código favorito
• Conocimientos básicos de línea de comandos
• Acceso a GitHub (cuenta personal)
• uv instalado (gestor de paquetes Python moderno)

Estructura del Workshop

MÓDULO 1: Configuración y Primer Contacto (50 min)

🛠️ Lab 1: Instalación y Setup (25 min)

Objetivo: Tener Claude Code funcionando y hacer primera interacción

Enlaces oficiales de instalación:

• Node.js: https://nodejs.org/en/download/ (Requiere versión 18+)
• npm: Incluido con Node.js - https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
• npx: Incluido con npm (v5.2.0+) - https://docs.npmjs.com/cli/v7/commands/npx
• uv: https://docs.astral.sh/uv/getting-started/installation/
• Claude Code: https://docs.claude.com/en/docs/claude-code

Proceso paso a paso:

# Verificar prerequisitos
node --version  # Debe ser 18+
npm --version
npx --version   # Verificar que npx está disponible
uv --version    # Verificar que uv está instalado

# Instalación con npx (método recomendado)
# No requiere instalación global, ejecuta directamente
npx @anthropic-ai/claude-code --version

# Crear alias para uso fácil (opcional)
# En Windows (PowerShell):
echo 'function claude { npx @anthropic-ai/claude-code $args }' >> $PROFILE
# En Linux/Mac (bash/zsh):
echo 'alias claude="npx @anthropic-ai/claude-code"' >> ~/.bashrc
# Reiniciar terminal o ejecutar: source ~/.bashrc

# Alternativa: Instalación global (si npx no funciona)
npm install -g @anthropic-ai/claude-code

# Verificar instalación
npx @anthropic-ai/claude-code --version
# O si creaste el alias:
claude --version

# Crear workspace del workshop
mkdir claude-workshop
cd claude-workshop

Soluciones comunes:

• WSL: Si usas Windows, instala en WSL, no en Windows directamente
• Permisos: Usa sudo en Linux/Mac si es necesario
• Versión Node: Actualiza con nvm install 18 && nvm use 18
• uv no instalado: Instala desde https://docs.astral.sh/uv/getting-started/installation/
• npx no funciona: Verifica que npm esté correctamente instalado y actualizado

⚙️ Lab 2: IDE Integration (15 min)

VS Code Integration:

# Instalar extensión
code --install-extension anthropic.claude-code

# Configurar shortcuts
# Cmd+Esc (Mac) / Ctrl+Esc (Windows) para quick launch

Demostración práctica:

1. Seleccionar código en VS Code
2. Abrir Claude con shortcut
3. El contexto se comparte automáticamente
4. Hacer cambios en Claude
5. Ver diff integrado en VS Code

🎯 Ejercicio: Primera Interacción (10 min)

# Iniciar Claude Code (con npx o alias)
npx @anthropic-ai/claude-code
# O si tienes el alias:
claude

# Exploración inicial
> /help
> ¿Qué puedes decirme sobre este directorio?
> Crea un script simple "Hola Mundo" en Python que muestre la fecha actual

Objetivo: Ver inmediatamente las capacidades básicas de Claude Code.

---

MÓDULO 2: Construcción de Sitio Web con Amplify (60 min)

🌐 Lab 2: Sitio Web Sencillo para AWS Amplify (45 min)

Objetivo del Lab:

• Construir una página web básica pero profesional
• Configuración simple para AWS Amplify
• Integración básica con GitHub
• Despliegue automático
• Todo usando comandos naturales con Claude Code

Preparación del repositorio:

# Crear directorio del workshop
mkdir claude-workshop
cd claude-workshop

# Iniciar Claude Code
npx @anthropic-ai/claude-code
# O si tienes el alias:
claude

Construcción paso a paso:

Paso 1: Crear sitio web básico (15 min)

> Primero, limpia cualquier archivo existente en este directorio, luego crea un sitio web simple y limpio con:
  - Eliminar cualquier archivo HTML, CSS o de configuración existente
  - Una sola página HTML con estructura básica
  - CSS simple para un estilo limpio
  - Diseño responsivo que funcione en móviles
  - Sección hero básica con título y descripción
  - Menú de navegación simple
  - Sección de footer
  - Apariencia limpia y profesional

Paso 2: Configurar para AWS Amplify (15 min)

> Configura este sitio web simple para despliegue en AWS Amplify:
  1. Crear archivo amplify.yml básico
  2. Agregar configuración de build simple
  3. Configurar para hosting estático
  4. Agregar reglas de redirección básicas

Paso 3: Contenido específico del workshop (15 min)

> Actualiza el contenido del sitio web para el workshop de Claude Code:
  - Cambia el título principal a "Claude Code Workshop"
  - En la sección hero: título "Workshop Práctico de Claude Code" y subtítulo sobre aprender a programar con IA
  - Actualiza navegación y botones con contenido relevante al workshop
  - Agrega descripción breve de qué es Claude Code
  - Mantén el diseño visual actual

📋 Git manejado por Claude (15 min)

Configuración inicial:

Nota: Si necesitas autenticarte en GitHub, consulta la documentación oficial: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github

> ¿Puedes verificar si git está disponible y mostrarme el estado actual de git?

> Por favor configura git para conectar con mi repositorio existente:
  - Inicializar repositorio git si es necesario
  - Conectar al repositorio remoto: [USUARIO DEBE INDICAR SU REPOSITORIO AQUÍ]
  - Configurar rama principal como main
  - Verificar que la conexión funcione correctamente

Workflow automatizado:

> Por favor maneja las operaciones de git para nuestro sitio web:
  1. Agregar todos los archivos a git
  2. Crear un mensaje de commit apropiado para este nuevo sitio web
  3. Hacer push a la rama principal
  4. Configurar git adecuadamente si es necesario

---

MÓDULO 3: Subagentes y Automatización (50 min)

🧪 Lab 3: Subagentes - Creación y Uso (30 min)

Método recomendado: Usar CLI de Claude Code

# Iniciar Claude Code
npx @anthropic-ai/claude-code
# O si tienes el alias:
claude

# Explorar comandos de subagentes
> /agents
> /help

# Crear subagentes interactivamente
> Crea un nuevo subagente llamado "html-css-standards":
  - Nombre: html-css-standards
  - Descripción: Revisa código HTML/CSS para cumplimiento de estándares
  - Herramientas: Read, Edit, Write
  - Propósito: Verificar calidad de código, convenciones de nombres, estructura
  - Ubicación: Específico del proyecto (.claude/agents/)
  - Regla principal: Asegurar que todos los nombres de archivo estén en minúsculas (index.html, style.css, no Index.HTML)

> Crea un nuevo subagente llamado "repo-structure-manager":
  - Nombre: repo-structure-manager
  - Descripción: Administra la estructura del repositorio y flujos de trabajo git
  - Herramientas: Read, Edit, Write, Bash(git:*)
  - Propósito: Estandarizar la organización del repositorio
  - Ubicación: Específico del proyecto (.claude/agents/)
  - Regla principal: Siempre requerir un archivo README.md con descripción del proyecto en el directorio raíz

Uso efectivo de subagentes:

# Verificar subagentes creados
> /agents

# Usar subagentes específicos
> Usa el subagente html-css-standards para revisar mis archivos HTML y CSS
> Haz que el subagente repo-structure-manager organice la estructura de nuestro proyecto

# Encadenamiento avanzado
> Primero usa el subagente html-css-standards para revisar nuestros archivos, luego haz que el subagente repo-structure-manager cree la documentación adecuada y organice el proyecto

🔄 Lab 4: Debugging y Mejoras (20 min)

Ejemplo de debugging:

<!-- Archivo con errores básicos -->
<!DOCTYPE html>
<html>
<head>
  <title>Workshop</title>
  <!-- Bug 1: No responsive viewport -->
  <style>
    body { margin: 0; }
    .header { width: 800px; } /* Bug: Fixed width */
    .text { color: #ccc; background: white; } /* Bug: Poor contrast */
  </style>
</head>
<body>
  <div class="header">
    <h1>Claude Code Workshop</h1>
    <p class="text">Learn to code with AI</p>
  </div>
</body>
</html>

Proceso de debugging:

> Depura este archivo HTML simple y corrige estos problemas:
  1. Hazlo responsivo para móviles
  2. Corrige problemas de contraste de colores
  3. Agrega meta tags faltantes
  4. Mejora la accesibilidad básica

---

MÓDULO 4: Integraciones y Despliegue (30 min)

🤖 Lab 5: Crear Servidor MCP Weather (15 min)

Objetivo: Crear exactamente el mismo servidor MCP weather siguiendo la guía oficial

Vamos a seguir la guía oficial: https://modelcontextprotocol.io/docs/develop/build-server

Paso 1: Crear el proyecto

# Crear directorio del proyecto weather
uv init weather
cd weather

# Crear entorno virtual y activarlo
uv venv
.venv\Scripts\activate  # En Windows
# source .venv/bin/activate  # En Linux/Mac

# Instalar dependencias
uv add mcp[cli] httpx

# Crear archivo del servidor
new-item weather.py  # En Windows
# touch weather.py    # En Linux/Mac

Paso 2: Crear el archivo weather.py

import asyncio
import logging
from mcp.server.models import InitializationOptions
from mcp.server import NotificationOptions, Server
from mcp.types import Resource, Tool, TextContent, ImageContent, EmbeddedResource
import mcp.types as types
import httpx

# Set up logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("weather-server")

# Create a server instance
server = Server("weather-server")

# National Weather Service API base URL
NWS_API_BASE = "https://api.weather.gov"

async def get_forecast(latitude: float, longitude: float) -> dict:
    """Get forecast for a given latitude and longitude."""
    async with httpx.AsyncClient() as client:
        # First, get the grid point
        points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
        points_response = await client.get(points_url)
        points_response.raise_for_status()
        points_data = points_response.json()
        
        # Get the forecast URL
        forecast_url = points_data["properties"]["forecast"]
        forecast_response = await client.get(forecast_url)
        forecast_response.raise_for_status()
        
        return forecast_response.json()

async def get_alerts(state: str) -> dict:
    """Get weather alerts for a given state."""
    async with httpx.AsyncClient() as client:
        alerts_url = f"{NWS_API_BASE}/alerts"
        params = {"area": state}
        alerts_response = await client.get(alerts_url, params=params)
        alerts_response.raise_for_status()
        
        return alerts_response.json()

@server.list_tools()
async def handle_list_tools() -> list[types.Tool]:
    """
    List available tools.
    Each tool specifies its arguments using JSON Schema validation.
    """
    return [
        types.Tool(
            name="get_forecast",
            description="Get weather forecast for a location",
            inputSchema={
                "type": "object",
                "properties": {
                    "latitude": {
                        "type": "number",
                        "description": "Latitude of the location"
                    },
                    "longitude": {
                        "type": "number", 
                        "description": "Longitude of the location"
                    }
                },
                "required": ["latitude", "longitude"]
            }
        ),
        types.Tool(
            name="get_alerts",
            description="Get weather alerts for a state",
            inputSchema={
                "type": "object",
                "properties": {
                    "state": {
                        "type": "string",
                        "description": "Two-letter state code (e.g., CA, NY)"
                    }
                },
                "required": ["state"]
            }
        )
    ]

@server.call_tool()
async def handle_call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    """
    Handle tool calls.
    Tools can modify server state and notify clients of changes.
    """
    if name == "get_forecast":
        latitude = arguments.get("latitude")
        longitude = arguments.get("longitude")
        
        try:
            forecast_data = await get_forecast(latitude, longitude)
            periods = forecast_data["properties"]["periods"]
            
            forecast_text = f"Weather forecast for {latitude}, {longitude}:\n\n"
            for period in periods[:5]:  # Show next 5 periods
                forecast_text += f"{period['name']}: {period['detailedForecast']}\n\n"
                
            return [types.TextContent(
                type="text",
                text=forecast_text
            )]
            
        except Exception as e:
            return [types.TextContent(
                type="text", 
                text=f"Error getting forecast: {str(e)}"
            )]
            
    elif name == "get_alerts":
        state = arguments.get("state")
        
        try:
            alerts_data = await get_alerts(state)
            features = alerts_data.get("features", [])
            
            if not features:
                return [types.TextContent(
                    type="text",
                    text=f"No active weather alerts for {state}"
                )]
            
            alerts_text = f"Active weather alerts for {state}:\n\n"
            for alert in features:
                properties = alert["properties"]
                alerts_text += f"• {properties['headline']}\n"
                alerts_text += f"  Area: {properties.get('areaDesc', 'N/A')}\n"
                alerts_text += f"  Severity: {properties.get('severity', 'N/A')}\n\n"
                
            return [types.TextContent(
                type="text",
                text=alerts_text
            )]
            
        except Exception as e:
            return [types.TextContent(
                type="text",
                text=f"Error getting alerts: {str(e)}"
            )]
            
    else:
        raise ValueError(f"Unknown tool: {name}")

async def main():
    # Run the server using stdin/stdout streams
    from mcp.server.stdio import stdio_server
    
    async with stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name="weather-server",
                server_version="1.0.0",
                capabilities=server.get_capabilities(
                    notification_options=NotificationOptions(),
                    experimental_capabilities={},
                ),
            ),
        )

if __name__ == "__main__":
    asyncio.run(main())

Paso 3: Configurar en Claude Desktop

Agregar al archivo de configuración MCP:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\<User Windows>\\Documents\\claude-code-workshop\\claude-workshop-v2\\claude-workshop\\dalia-claude-code-workshop\\weather",
        "run",
        "weather.py"
      ]
    }
  }
}

Paso 4: Probar el servidor

# Activar el entorno virtual si no está activo
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/Mac

# Probar el servidor directamente
uv run python weather.py

# Reiniciar Claude Desktop
# Ir a Settings > Developer > Local MCP servers
# Verificar que aparece "weather" en la lista

Demostración práctica:

Una vez configurado, puedes probar en Claude Desktop:

# Obtener pronóstico del tiempo
> ¿Cuál es el pronóstico del tiempo para Sacramento? (Latitud: 38.5816, Longitud: -121.4944)

# Obtener alertas meteorológicas
> ¿Hay alguna alerta meteorológica para California? (Código de estado: CA)

# Comparar diferentes ubicaciones
> Compara el pronóstico del tiempo entre Sacramento y Nueva York (40.7128, -74.0060)

Verificar funcionamiento:

En Claude Desktop deberías ver:

• Servidor "weather" listado en Local MCP servers
• Estado "Connected"
• Respuestas con información meteorológica real
• Ícono "W" para herramientas weather en las conversaciones

Casos de uso para el workshop:

# Demostrar herramientas con parámetros
> Obtén el pronóstico del tiempo para la ubicación del workshop

# Mostrar manejo de errores
> Intenta obtener alertas para un código de estado inválido

# Combinar múltiples herramientas  
> Obtén tanto el pronóstico como las alertas para Texas (Latitud: 31.9686, Longitud: -99.9018, Estado: TX)

Casos de Uso Útiles para Desarrolladores

Una vez que tengas el servidor MCP weather funcionando, aquí algunos casos de uso prácticos que puedes implementar en tu trabajo diario como desarrollador:

1. Integración en aplicaciones:

# Verificar condiciones antes de despliegues
> Verifica las condiciones meteorológicas en nuestras ubicaciones de centros de datos antes del despliegue

# Planificación de releases
> ¿Cuál es el pronóstico del tiempo para los próximos 3 días en nuestras oficinas principales?

2. Automatización de workflows:

# Alertas para equipos remotos
> Obtén alertas meteorológicas para todos los estados donde están ubicados nuestros miembros de equipos remotos

# Decisiones de infraestructura
> Verifica si hay alertas meteorológicas severas que puedan afectar nuestras regiones de AWS

3. Desarrollo de features relacionadas con clima:

# Testing con datos reales
> Obtén datos meteorológicos actuales para probar nuestras funciones basadas en ubicación

# Validación de APIs
> Compara nuestros datos meteorológicos con los pronósticos oficiales de NWS para pruebas de precisión

4. Integración con otras herramientas:

• Combinar con calendarios para planificar eventos outdoor
• Integrar con sistemas de monitoreo para correlacionar clima con performance
• Usar en chatbots internos para respuestas contextuales

🚀 Lab 6: Despliegue con Amplify (15 min)

Crear configuración de deployment:

# amplify.yml - Configuración básica
version: 1
frontend:
  phases:
    build:
      commands:
        - echo "Building simple website..."
  artifacts:
    baseDirectory: /
    files:
      - '**/*'

GitHub Action básica:

# .github/workflows/deploy.yml
name: Deploy to Amplify
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Amplify
        run: echo "Deploying simple website to AWS Amplify"

---

Recursos Continuos

Repositorio del Workshop:

dalia-claude-code-workshop/
├── index.html              # Página principal simple
├── style.css               # Estilos básicos
├── amplify.yml             # Configuración Amplify
├── .claude/
│   ├── agents/             # Subagentes del proyecto
│   └── commands/           # Comandos personalizados
├── .github/workflows/      # CI/CD básico
├── README.md               # Instrucciones
├── weather/                # Proyecto MCP Weather
│   ├── weather.py          # Servidor MCP
│   └── .venv/              # Entorno virtual
└── docs/setup-guide.md     # Guía de setup

Community y Soporte:

• Discord: Claude Developers
• GitHub Discussions
• Weekly office hours
• Documentación oficial: https://docs.anthropic.com/en/docs/claude-code
• Documentación uv: https://docs.astral.sh/uv/

Enlaces de Referencia Rápida

Instalación de Herramientas:

• Node.js: https://nodejs.org/en/download/
• npm: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
• npx: https://docs.npmjs.com/cli/v7/commands/npx (incluido con npm v5.2.0+)
• uv (Python package manager): https://docs.astral.sh/uv/getting-started/installation/
• Claude Code: https://docs.claude.com/en/docs/claude-code
• VS Code Extension: https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code

Documentación Técnica:

• Model Context Protocol (MCP): https://modelcontextprotocol.io/docs/develop/build-server
• AWS Amplify: https://docs.amplify.aws/
• Git: https://git-scm.com/docs