tesis de apertura

El asistente describe.
El agente ejecuta.

Claude Code es lo segundo. Tiene shell, tiene archivos, tiene permisos. Cuando le pides un refactor, edita el código. Cuando le pides correr tests, los corre. Cuando le pides abrir un PR, lo abre. La pregunta deja de ser "¿qué te sugiere?" y pasa a ser "¿qué le permites hacer?".

qué cambia respecto a la sesión A

Mismo modelo. Más capacidades. Más responsabilidad.

qué entrega esta sesión

Al cerrar la sesión B, debes poder configurar Code para tu equipo.

instalación CLI

Una sola línea. El resto es configuración.

Recomendación: nunca pegues la API key en el repo, ni en .env committeable. Usa ~/.zshrc o un keychain manager.

verificación rápida

Tres señales de que la instalación quedó bien.

• claude --version devuelve un número de versión actual
• claude en un directorio vacío arranca el prompt sin error
• claude doctor reporta API key configurada y permisos correctos

Si alguno falla, casi siempre es uno de tres problemas: Node 18- en lugar de 20+, API key mal exportada, o permisos de npm en macOS sin sudo ni nvm.

primer prompt en un repo de prueba

El primer comando ya no es para "probar". Es para mapear el repo.

Lee este repo. Devuelve:

1. Una línea por módulo de top level
   con su responsabilidad
2. Tres archivos de entrada
3. Tres riesgos arquitectónicos
   visibles desde la estructura

No edites nada todavía. Solo describe.

las tres capas

Global · Proyecto · Local. Cada una con un propósito distinto.

orden de carga

Code lee de menor a mayor especificidad. Lo más cercano al cwd manda.

Cuando algo "no se aplica" — casi siempre es que un nivel más específico lo está sobrescribiendo. claude /doctor muestra qué archivos cargó esta sesión.

~/.claude/CLAUDE.md

Tus preferencias. Las que aplican en cualquier proyecto.

· stack del proyecto
· convenciones del equipo
· archivos del repo
· decisiones arquitectónicas
· estructura del directorio

· idioma de respuesta
· estilo de commits que usas
· "siempre confirma antes de borrar"
· "comentarios solo cuando el porqué
   no es obvio"
· herramientas que usas en todos
  tus proyectos (vitest, etc.)

.claude/CLAUDE.md del proyecto

El contrato del repo con la IA. Versionado en git.

decisor rápido

Si lo cambias en otro proyecto, no va en proyecto.

esqueleto mínimo

Cinco campos que casi siempre están.

Ubicación: .claude/settings.json en la raíz del repo. Hay también .claude/settings.local.json para lo personal · gitignored.

modelo default y permissions

Permission rules son tu primera capa de gobernanza.

Lo que no está en allow ni deny cae en ask · te pregunta antes de ejecutar.

los otros campos

Hooks · subagents · MCP también viven aquí — los veremos en detalle.

los cuatro modos

De más conservador a más permisivo. Siempre puedes cambiar a media sesión.

decisor rápido

El modo correcto cambia con la tarea, no con la persona.

plan mode en detalle

El modo "revisar antes de actuar". Subutilizado y muy útil.

claude --permission-mode plan

# o dentro de la sesión
/permission-mode plan

# cuando apruebes el plan
/permission-mode acceptEdits

built-in que vas a usar todos los días

Cinco que justifican aprenderse.

comandos custom del equipo

Cualquier prompt repetido es candidato a custom command.

Cada archivo es un prompt en markdown. Llamarlo con /audit, /ship, etc. Versionado en git · todo el equipo los usa igual.

ejemplo · /ship

Un comando que ejecuta el ritual de "antes de mergear".

los 7 eventos

Siete momentos de la sesión donde puedes intervenir.

anatomía de un hook

Un comando shell. Un evento. Un matcher opcional.

El comando recibe vía stdin un JSON con la acción propuesta. Devuelve exit 0 para permitir, exit !=0 para bloquear con mensaje.

ejemplo · bloquear escritura a .env

Pre-tool-use que prohíbe tocar archivos sensibles.

Este hook ya no depende de que Claude "se acuerde" de no tocar .env. La regla es ejecutable y verificada por la plataforma, no por el modelo.

post · stop · notification

Lint automático tras cada Write. Resumen al cerrar.

qué son

Un subagent es Claude con un rol estrecho y herramientas acotadas.

.claude/agents/

Cada subagent es un archivo. Un rol. Una caja de herramientas.

cuándo usar subagent vs main context

Si la tarea va a generar mucho output que no necesitas leer, delega.

skills locales

Una skill es un ritual reutilizable que vive en el repo.

MCP en claude code

MCP = tools tipados de tu sistema, conectados al agente.

Servers locales viven en tu repo. Servers remotos · npm · binarios. Code los expone como tools al modelo · auditados como cualquier otra acción.

IDE · agent SDK · github actions

Code en tu editor. Code en tu CI. Code dentro de tus apps.

ejercicio 01 · primer prompt en repo de prueba

Mapea un repo desconocido en 15 minutos.

Lee este repo (no edites nada).
Devuelve en markdown:

1. Topología de top-level
   (módulos, una línea cada uno)
2. Tres entry points · ruta · función
3. Tres riesgos arquitectónicos visibles
   desde la estructura
4. Dos preguntas que harías al autor

No inventes. Si no hay evidencia, di
"sin evidencia". Sé breve.

ejercicio 02 · escribir tu CLAUDE.md de proyecto

Genera el CLAUDE.md del repo a partir del repo.

Genera .claude/CLAUDE.md a partir
del repo. Incluye estas secciones:

  ## Stack · ## Arquitectura ·
  ## No hacer sin confirmar ·
  ## Convenciones de tests ·
  ## Convenciones de commits ·
  ## Glosario de dominio (top 10)

Reglas:
  · solo lo que veas en el código
  · marca [verificar] cuando dudes
  · ningún consejo genérico

Output: markdown listo para commit.

ejercicio 03 · settings.json con permissions

Define qué puede y qué no puede hacer Code en este repo.

Genera .claude/settings.json con
permissions explícitos.

Deny (5):
  · escribir a .env*
  · rm -rf
  · git push --force a main
  · npm publish
  · tocar archivos en /infra/secrets/

Ask (3):
  · npm install nuevo paquete
  · cambios a config de auth
  · cambios a migrations

Allow (5):
  · npm test, lint, typecheck
  · git status, diff, log

Modelo: sonnet-4-6.

ejercicio 04 · slash command custom

Crea /test que ejecuta el ritual de testing del equipo.

Ejecuta en este orden y detente al
primer fallo:

1. npm run lint
2. npm run typecheck
3. npm test
4. npm run boundaries:check

Al terminar, reporta:
  · checks pasados
  · checks fallados
  · tiempo total

Si algún check falla, no continúes.

ejercicio 05 · hook PreToolUse · bloqueo .env

Convierte una regla "no toques .env" en código ejecutable.

en la sesión:

  "Crea un archivo .env.example
   con DATABASE_URL y ANTHROPIC_API_KEY
   como ejemplo."

resultado esperado:

  ✗ BLOQUEADO: no puedes escribir
    a .env.example desde Code.

si pasa, el hook funciona.
si no pasa, revisa el matcher
en settings.json.

ejercicio 06 · hook PostToolUse · lint automático

Después de cada Write, lint:fix sin pedirlo.

#!/usr/bin/env bash
input=$(cat)
file=$(echo "$input" | jq -r '.tool_input.file_path')

# solo si es archivo del repo
if [[ -n "$file" && -f "$file" ]]; then
  case "$file" in
    *.ts|*.tsx|*.js)
      npx eslint --fix --quiet "$file" 2>/dev/null
      ;;
    *.py)
      ruff format "$file" 2>/dev/null
      ;;
  esac
fi
exit 0

ejercicio 07 · subagent auditor

Crea un auditor que revisa el repo contra los ADRs sin ensuciar tu contexto.

"Audita el repo contra los ADRs vigentes.
Devuelve solo violaciones · severidad ·
remediación mínima. No edites nada."

Code debería:
  1. Detectar que es trabajo del auditor
  2. Lanzarlo con su contexto
  3. Recibir el reporte
  4. Devolverlo a ti sin inflar el main

Compara con hacerlo en main:
  /cost antes y después.

ejercicio 08 · skill local del proyecto

Empaqueta el ritual de "nuevo ADR" como skill.

---
name: adr-new
description: crea un nuevo ADR
  desde plantilla y registra en index
---

Pasos:
1. Lee /architecture/adr/index.md
2. Calcula próximo número (ADR-NNN)
3. Copia templates/adr.md.tmpl a
   /architecture/adr/ADR-NNN-<slug>.md
4. Rellena con el contexto que el
   usuario te dio
5. Añade entrada a index.md
6. Reporta el path final

ejercicio 09 · MCP server local

Conecta una herramienta tipada del dominio al agente.

una vez conectado:

"Usa la tool linear-search para listar
los issues en estado In Progress
asignados a mí."

Code debería:
  1. Reconocer la tool disponible
  2. Pedir confirmación si está en ask
  3. Ejecutarla con argumentos tipados
  4. Devolver resultado estructurado

si /mcp no muestra el server, revisa
la línea command y env en settings.json.

ejercicio 10 · claude code en github actions

Auto-review de PRs con Code en CI.

name: claude-review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          mode: review
          api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          deny: "Bash(*) Write(*)"

lo que ya sabes hacer

Diez capacidades que el workshop principal asume.

• Operar Cowork con projects, knowledge y system instructions contractuales
• Lanzar Claude Code en un repo y pedir un mapa estructural sin tocar nada
• Diseñar CLAUDE.md jerárquico (global · proyecto · local)
• Escribir settings.json con allow / deny / ask explícitos
• Cambiar entre permission modes según la fase de trabajo
• Crear slash commands custom y skills locales del proyecto
• Implementar hooks PreToolUse y PostToolUse para invariantes
• Definir subagents especializados en .claude/agents/
• Conectar MCP servers (locales o remotos)
• Configurar GitHub Actions con Code en CI con deny estricto

mapa pre → workshop

Cada capacidad activa un ejercicio del workshop.

acciones inmediatas

Antes de cerrar la sesión, deja tres cosas commiteadas.

Workshop principal: 16 ejercicios sobre el mismo repo, ahora con la herramienta lista. La continuidad es directa — todo lo que escribiste aquí va a usarse desde el primer ejercicio.