Los 3 Modos de Permisos

Alterna entre modos con Shift+Tab:

Atajos Esenciales

Menciones con @

Da contexto directo incluyendo archivos o directorios en tu prompt:

Comandos Integrados

Jerarquía de Scopes (Precedencia)

Las configuraciones se aplican de mayor a menor prioridad:

Ejemplo: settings.json del Proyecto

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(no_leer.txt)",
      "Read(**/*.pem)",
      "Edit(.env)",
      "Bash(rm -rf *)",
      "Bash(DROP TABLE *)"
    ],
    "allow": [
      "Bash(npm run *)",
      "Bash(npx prisma *)",
      "Bash(git *)",
      "Read",
      "Edit",
      "Write"
    ]
  }
}

Ejercicio Práctico

1. Crea el archivo .claude/settings.json con las reglas de arriba
2. Abre claude e intenta: "lee el archivo secrets.env"
3. Verifica que Claude bloquea el acceso
4. Usa /config para explorar la configuración interactiva

Jerarquía de Memoria

Template: CLAUDE.md Efectivo

# CRM Proyecto - Instrucciones para Claude

## Stack
- Runtime: Node.js 20+ con TypeScript y React 19
- Framework: Next.js 16 (App Router)
- Estilos: Tailwind CSS v4
- ORM: Prisma con PostgreSQL (Neon DB)
- Pruebas: Vitest

## Comandos
- Dev server: `npm run dev`
- Build: `npm run build`
- DB generate: `npx prisma generate`
- Linter: `npm run lint`

## Convenciones
- Componentes de UI van en `src/components/` (usamos Lucide React para íconos)
- Lógica de backend y endpoints en `src/app/api/`
- Páginas de la app van en `src/app/`
- Componentes de servidor (RSC) por defecto. Usa `"use client"` solo si necesitas interactividad o hooks de React
- Las mutaciones a la base de datos se hacen usando Server Actions o en rutas de API

## Seguridad
- NUNCA commitear archivos `.env.local` ni secrets
- NUNCA retornar objetos Prisma completos al frontend, filtra datos sensibles
- Valida entradas de usuario antes de tocar la DB

Reglas Modulares

# Convenciones de Testing

- Framework: Vitest + Supertest para tests de integración
- Cada test debe cubrir: happy path, errores, edge cases
- Nombrar tests descriptivamente:
  "should return 404 when product not found"
- Usar factories para datos de prueba, no hardcodear

Auto Memory

Puedes decirle a Claude que recuerde algo específico:

Usa /memory para revisar y editar lo que Claude ha guardado.

Generar CLAUDE.md Automáticamente

# Dentro de una sesión de Claude Code:
/init
# Claude analizará tu proyecto y generará un CLAUDE.md base

Debug Agéntico

Pega el error directamente en Claude y deja que trace la causa raíz:

Refactorización Incremental

Checkpoints y Rewind

Claude crea checkpoints automáticos antes de cada cambio. Si algo sale mal:

• Esc+Esc — Revertir al estado anterior (Rewind)
• Restore: Revierte código al checkpoint
• Summarize: Mantiene los cambios pero limpia el contexto

Git y Pull Requests

Gestión de Sesiones

# Nombrar la sesión actual
/rename bugfix-authentication

# Continuar la sesión más reciente
claude -c

# Seleccionar sesión para reanudar
claude -r

# Reanudar por nombre
claude --resume bugfix-authentication

Tipos de Conexión

# Conectar GitHub (HTTP remoto)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Conectar PostgreSQL en Neon DB
claude mcp add neon-pg -- npx -y @modelcontextprotocol/server-postgres "postgresql://usuario:password@ep-midb.aws.neon.tech/neondb?sslmode=require"

Configuración por Proyecto (.mcp.json)

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/shopflow"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/context7-mcp"]
    }
  }
}

Prompts con MCP

Gestión de Servidores

# Listar servidores conectados
claude mcp list

# Eliminar servidor
claude mcp remove postgres

🏪 Marketplaces y Repositorios Útiles

⭐ Mi Top 5 MCPs

🔧 Cómo Instalar cada MCP

1. GitHub MCP (HTTP remoto)

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

2. Context7

claude mcp add context7 -- npx -y @anthropic-ai/context7-mcp

3. PostgreSQL / NeonDB

# Reemplaza con tu connection string de Neon DB
claude mcp add neon-pg -- npx -y @modelcontextprotocol/server-postgres \
  "postgresql://usuario:password@ep-midb.aws.neon.tech/neondb?sslmode=require"

4. Vercel

claude mcp add --transport http vercel https://mcp.vercel.com/sse

5. Sequential Thinking

claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking

Las Skills son carpetas con un archivo SKILL.md en .claude/skills/<nombre-skill>/SKILL.md. Puedes invocarlas con /nombre o dejar que Claude las active automáticamente según la descripción.

Anatomía de una Skill

---
name: ui-audit
description: Audita componentes React/Tailwind y detecta problemas de accesibilidad, semántica y UX. Úsalo al revisar UIs o PRs frontend.
argument-hint: "[ruta-opcional]"
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Bash(npm run lint*)
---

# Auditoría de Interfaz

Audita la ruta: `$ARGUMENTS`.
Si no se pasó argumento, usa `src/components`.

Checklist:
1. Ejecuta `npm run lint` y resume errores/warnings relevantes
2. Detecta HTML no semántico (`div` clickable, falta de `button`, headings mal jerarquizados)
3. Verifica estados `hover`, `focus-visible` y contraste mínimo
4. Revisa labels/aria en inputs, formularios e icon buttons
5. Entrega `docs/ui-audit.md` con:
   - Hallazgos críticos
   - Hallazgos medios
   - Fixes sugeridos con snippets

Invocar una Skill

# Dentro de una sesión de Claude Code:
/ui-audit

# Con argumentos:
/ui-audit src/components/Dashboard.tsx

Otra Skill: Generar Documentación API

---
name: generate-api-docs
description: Genera documentación técnica de endpoints a partir de rutas API (Next.js/Express/Fastify) con ejemplos y errores.
argument-hint: "[ruta-api]"
disable-model-invocation: true
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob, Write
---

# Generar Documentación de API

Genera docs para `$ARGUMENTS`.
Si no hay argumento, usa `src/app/api`.

1. Descubre rutas y handlers (`GET/POST/PUT/PATCH/DELETE`)
2. Extrae params, query, body, headers y códigos de respuesta
3. Documenta ejemplos request/response y casos de error comunes
4. Crea/actualiza `docs/API.md` en formato consistente
5. Nunca incluyas secretos, credenciales ni schema interno sensible

Mini Tutorial: Crear una Skill desde Terminal

mkdir -p .claude/skills/review-pr

cat > .claude/skills/review-pr/SKILL.md <<'EOF'
---
name: review-pr
description: Revisa un PR y reporta riesgos, regresiones y faltantes de test.
argument-hint: "[numero-pr o rama]"
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Bash(gh pr *), Bash(git diff*)
---

Revisa el PR `$ARGUMENTS`:
1. Resume cambios clave
2. Detecta bugs y regresiones de comportamiento
3. Señala gaps de testing
4. Entrega reporte con severidad (alta/media/baja) y archivos afectados
EOF

claude
/review-pr 128

Mejores Prácticas (Skills)

• Usa carpeta + SKILL.md: .claude/skills/nombre/SKILL.md, no un archivo suelto
• Description específica: incluye qué hace y cuándo usarla (mejora auto-disparo)
• Controla invocación: disable-model-invocation: true para tareas con efectos secundarios
• Aplica mínimo privilegio: limita con allowed-tools
• Define argumentos: usa argument-hint + $ARGUMENTS / $ARGUMENTS[n]
• Separa contexto pesado: deja SKILL.md corto y mueve detalle a archivos de apoyo
• Aísla tareas complejas: usa context: fork en skills largas o de investigación

Ubicaciones de Skills

• .claude/skills/ — Skills del proyecto (compartidas via Git)
• ~/.claude/skills/ — Skills personales (todos los proyectos)

🏪 Marketplaces y Repositorios de Skills

⭐ Mi Top 5 Skills

Eventos del Ciclo de Vida

Ejemplo Completo de Hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
        }]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{
          "type": "command",
          "command": "echo $CLAUDE_TOOL_INPUT | jq -r '.file_path' | grep -q 'prisma/schema.prisma' && echo '{\"decision\":\"block\",\"reason\":\"No editar schema.prisma directamente.\"}' || true"
        }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "notify-send 'Claude Code' 'Necesita tu atención' 2>/dev/null || true"
        }]
      }
    ]
  }
}

🏪 Marketplaces y Repositorios de Hooks

⭐ Mi Top 5 Hooks

Subagentes Integrados

Crear un Subagente Personalizado

---
description: Genera tests unitarios e integración para módulos
model: sonnet
tools:
  - Read
  - Edit
  - Write
  - Bash
  - Glob
  - Grep
---

# Test Writer Agent

Eres un agente especializado en escribir tests unitarios de React.

## Reglas
- Framework: Jest + React Testing Library (o Vitest)
- Probar que los componentes de la interfaz como `Sidebar` y `CustomerTable` se renderizan sin crashear
- Simula clics (ej. `fireEvent.click`) interactuando con elementos accesibles (role="button")
- Mockear `next/navigation` useRouter/usaPathname y llamadas a base de datos de Prisma
- Nombrar tests descriptivamente: "al hacer clic en Guardar, llama a onSubmit"

## Proceso
1. Lee el componente objetivo en `src/components/`
2. Construye los escenarios de prueba
3. Genera el archivo en la carpeta `__tests__` o con extensión `.test.tsx`
4. Ejecuta pruebas parciales para confirmar que pasan

Otro Ejemplo: Code Reviewer

---
description: Revisa código buscando bugs, seguridad y mejoras
model: haiku
tools:
  - Read
  - Grep
  - Glob
---

# Code Reviewer

Revisa el código buscando:
1. Vulnerabilidades de seguridad (SQL injection, XSS)
2. Bugs lógicos (null references, race conditions)
3. Code smells (funciones largas, duplicación)
4. Mejoras de rendimiento

Genera un reporte con prioridad: CRITICAL > HIGH > MEDIUM > LOW

Modo Headless (-p)

Ejecuta Claude en modo no-interactivo para integrarlo en scripts y pipelines:

# Query simple
claude -p "explica qué hace la función processPayment"

# Piping: analizar logs
cat error.log | claude -p "explica este error y sugiere la solución"

# Output JSON estructurado
claude -p "lista los endpoints de la API" --output-format json

# Limitar presupuesto
claude -p "revisa seguridad del proyecto" --max-budget-usd 2.00

# Linter semántico con Claude
git diff main --name-only -- '*.ts' | while read file; do
  cat "$file" | claude -p \
    "Busca bugs lógicos y vulnerabilidades. Formato: ARCHIVO:LINEA - PROBLEMA" \
    --output-format text --max-budget-usd 0.50
done

Monitoreo de Costos

GitHub Actions — Claude como Revisor de PRs

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]

jobs:
  claude-review:
    if: |
      (github.event_name == 'pull_request') ||
      (github.event_name == 'issue_comment' &&
       contains(github.event.comment.body, '@claude'))
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: sonnet

Con esta configuración, puedes escribir @claude revisa este código en cualquier PR y Claude lo revisará automáticamente según las reglas del CLAUDE.md del repo.

¿Cuándo Usar Agent Teams?

Agent Teams es ideal para tareas que se benefician del trabajo paralelo y coordinado:

Agent Teams vs Subagentes

Habilitar Agent Teams

Agent Teams es una feature experimental. Actívala con la variable de entorno o en settings:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Lanzar tu Primer Equipo

Simplemente describe la tarea y pide un equipo. Claude creará los teammates automáticamente:

Controlar tu Equipo

Modos de Visualización

// Forzar modo in-process (sin tmux)
{ "teammateMode": "in-process" }

// O desde la línea de comandos:
// claude --teammate-mode in-process

Comunicarte con Teammates

Especificar Modelos y Pedir Aprobación

Gestionar el Equipo

# Pedir a un teammate que se detenga
"Pide al teammate investigador que se detenga"

# Limpiar el equipo completo cuando termines
"Limpia el equipo"

# Esperar a que terminen antes de continuar
"Espera a que tus teammates completen sus tareas antes de continuar"

Hooks para Quality Gates

Usa hooks específicos de Agent Teams para controlar calidad:

Arquitectura Interna

Comunicación y Contexto

• 📨 Entrega automática — Cuando un teammate envía un mensaje, se entrega automáticamente al destinatario
• 🔔 Notificaciones idle — Cuando un teammate termina, notifica automáticamente al líder
• 📋 Lista de tareas compartida — Todos los agentes ven el estado y pueden reclamar trabajo disponible
• 💬 message — Envía a un teammate específico
• 📣 broadcast — Envía a todos simultáneamente (usar con moderación por costos)

Casos de Uso Prácticos

Code Review en Paralelo

Debugging con Hipótesis Competidoras

Feature Cross-Layer para el CRM

Mejores Prácticas

Troubleshooting

Limitaciones Actuales

Descarga

Visita antigravity.google/download para descargar Google Antigravity.

Requisitos del Sistema

Autenticación

Antigravity requiere una cuenta personal de Google (@gmail.com). Las cuentas de Workspace pueden tener restricciones según la organización.

Actualizaciones

La aplicación muestra una notificación cuando hay actualizaciones disponibles. Solo necesitas hacer clic en "Restart to Update" para aplicar la última versión.

Primer Inicio

1. Descarga e instala Antigravity para tu plataforma
2. Abre la aplicación — se abrirá el Agent Manager
3. Inicia sesión con tu cuenta de Google
4. Crea tu primer Workspace conectando un repositorio

Dos Vistas Principales

Antigravity tiene dos vistas que se complementan:

Atajos de Navegación

Flujo de Navegación

Desde el Agent Manager, selecciona un workspace y haz clic en "Open Editor" — o usa Cmd+E. Desde el Editor, el botón en la barra superior o Cmd+E te regresa al Agent Manager.

¿Qué es un Workspace?

Un Workspace es la unidad de trabajo en Antigravity. Conecta un repositorio Git y proporciona el contexto donde el agente opera.

Crear un Workspace

1. Abre el Agent Manager
2. Haz clic en "New Workspace"
3. Conecta un repositorio: GitHub, GitLab, o repositorio local
4. El agente clonará e indexará el repositorio automáticamente

Lanzar una Sesión

Una vez creado el workspace, describe tu tarea en lenguaje natural:

El agente seguirá un flujo estructurado:

Gestión de Sesiones

El Editor de Antigravity

El editor está basado en Monaco (el mismo motor de VS Code), lo que significa que ya conoces la mayoría de los atajos:

Chat del Agente en el Editor

En el panel lateral del editor puedes interactuar con el agente en contexto:

Revisando Cambios del Agente

Cuando el agente hace cambios, los verás como:

• 📝 Diffs inline — Cambios resaltados directamente en el archivo
• ✅ Botón "Accept" — Para aceptar los cambios propuestos
• ↩️ Botón "Revert" — Para rechazar y volver al estado anterior
• 💬 Comentar — Pide ajustes sin aceptar ni rechazar

Sleep y Sesiones Activas

Si un agente está ejecutándose, Antigravity evitará que tu computadora entre en modo sleep para no interrumpir la tarea. Esto sucede automáticamente mientras haya una sesión activa.

Tipos de Artefactos

En la orquestación asíncrona, el agente produce artefactos — documentos estructurados que contienen su trabajo:

Flujo de Trabajo con Artefactos

Paralelismo de Agentes

Una de las ventajas más poderosas de Antigravity es lanzar múltiples agentes en paralelo:

Cada agente trabaja de forma independiente con su propia rama y ventana de contexto. Los resultados se entregan como PRs independientes que puedes revisar y aprobar.

El Problema del "Silo de Contexto"

Cuando cada desarrollador tiene su propio historial de chat, la IA no aprende del equipo. La solución:

• Project Knowledge (Harness): Fuentes de verdad compartidas (.claude/rules, CLAUDE.md a nivel de organización)
• Prompts como Infraestructura: Versionado de Skills en el repositorio para que todo el equipo use los mismos estándares
• Artefactos Compartidos: El equipo colabora sobre el output generado (comentarios, iteraciones, hand-off humano-máquina)

Planes de Acceso

Google Antigravity está vinculado al ecosistema de Google AI. Existen varias formas de acceder:

Para más detalles sobre rate limits específicos, consulta la documentación de Planes.

Preguntas Frecuentes

¿Por qué no puedo autenticarme?

• Antigravity está disponible para cuentas personales de Google en geografías aprobadas
• Si tienes problemas con cuentas Workspace, prueba con un @gmail.com
• Debes ser mayor de 18 años. Verifica tu edad aquí

¿Puedo usar Antigravity con herramientas de terceros?

Privacidad y Datos

Puedes optar por no compartir datos en cualquier momento desde el panel de Settings. Consulta los Términos de Servicio para detalles completos.

¿Se soportan Git Worktrees?

No por el momento. Cada workspace opera con un solo working directory.

¿Qué pasa cuando mi computadora entra en modo sleep?

Si un agente está activo, Antigravity previene automáticamente que tu computadora entre en modo sleep para no interrumpir la ejecución.

Soporte

Visita la página de soporte y las comunidades oficiales.

Ejercicio 1: Setup del Workspace

1. Abre Antigravity y accede al Agent Manager
2. Crea un nuevo workspace conectando un repositorio de GitHub o un proyecto local
3. Espera a que el agente indexe el código base
4. Explora la interfaz: sidebar de archivos, vista de sesiones, panel de artefactos

Ejercicio 2: Tu Primera Tarea

Lanza una tarea sencilla para ver el flujo completo:

Observa cómo el agente:

• 📂 Escanea la estructura de archivos
• 📖 Lee archivos clave (package.json, configs, entry points)
• 📋 Genera un Plan de Implementación como artefacto
• 🧪 Propone cambios verificables

Ejercicio 3: Tarea con Implementación

Para este ejercicio, practica:

1. Revisar el plan — ¿El agente entendió correctamente los requisitos?
2. Aprobar con ajuste — Comenta pidiendo un cambio antes de aprobarlo
3. Revisar diffs — Cambia al Editor con Cmd+E y revisa los cambios
4. Verificar tests — Confirma que los tests fueron creados y pasan

Ejercicio 4: Paralelismo

Lanza dos sesiones simultáneas en el mismo workspace:

Observa cómo cada sesión trabaja en su propia rama sin interferir con la otra.

Checklist Final: ¿Completaste el Taller?

• ☐ Workspace creado y repositorio conectado
• ☐ Primera tarea de análisis completada y artefactos revisados
• ☐ Tarea de implementación con plan aprobado y código verificado
• ☐ Dos sesiones paralelas lanzadas exitosamente
• ☐ Navegación fluida entre Agent Manager y Editor (Cmd+E)

Recursos Adicionales