Ya no se trata de usar Claude Code, sino de diseñar el sistema alrededor del modelo: qué mecanismo usar para cada necesidad, cuánto contexto cuesta, cómo paralelizar, cómo correr sin humanos y cómo gobernarlo en un equipo.
Lección 4.1
Elegir el mecanismo correcto
La decisión de arquitectura más frecuente: ¿esto va en CLAUDE.md, un hook, una skill, un subagente, MCP, permisos, un plugin o CI? Elige el mecanismo para cada escenario y revisa el razonamiento.
¿Qué mecanismo usarías?0/10
Construye tu setup con el tiempo
No configures todo de entrada. Cada mecanismo tiene un disparador reconocible:
Disparador
Agrega
Claude se equivoca dos veces en una convención o comando
Una línea en CLAUDE.md
Pides una y otra vez respuestas más cortas o en cierto formato
Un output style
Escribes el mismo prompt para empezar una tarea
Una skill invocable por el usuario
Pegas el mismo procedimiento por tercera vez
Una skill
Copias datos de una pestaña que Claude no puede ver
Un servidor MCP
Claude lee muchos archivos buscando dónde se define un símbolo
Un plugin de code intelligence
Una tarea lateral inunda tu conversación de salida
Un subagente
Quieres que algo pase siempre, sin pedirlo
Un hook
Un segundo repo necesita el mismo setup
Un plugin
Lección 4.2
Costo de contexto por mecanismo
Cada extensión consume contexto de forma distinta. Demasiado llena la ventana y además mete ruido: las skills dejan de activarse bien o Claude pierde de vista tus convenciones.
Mecanismo
Cuándo carga
Qué carga
Costo
CLAUDE.md
Inicio de sesión
Contenido completo
En cada request
Output style
Inicio y al cambiar
Instrucciones del estilo activo
En cada request
Skills
Inicio + al usarse
Descripciones al inicio; contenido al usarse
Bajo (cero con disable-model-invocation)
MCP
Inicio
Nombres de herramientas; schemas bajo demanda
Bajo hasta que se usa una herramienta
Code intelligence
Tras editar y bajo demanda
Diagnósticos y ubicaciones de símbolos
Bajo; reduce lecturas de archivos
Subagentes
Al lanzarse
Contexto propio y limpio
Aislado de tu sesión
Hooks
En su evento
Nada (corren fuera)
Cero, salvo que devuelvan texto
Cómo se combinan entre niveles
Ojo: cada mecanismo tiene su propio orden. No es un error: lo que se suma (CLAUDE.md, hooks) no necesita ganador, y lo que se sobrescribe por nombre (skills, subagentes, MCP) resuelve el choque con su propia regla. No lo compares con la precedencia de settings de la lección siguiente.
CLAUDE.md se suma: todos los niveles aportan a la vez. Si chocan, Claude decide cómo reconciliarlos.
Skills y subagentes se sobrescriben por nombre: skills managed > usuario > proyecto; subagentes managed > flag CLI > proyecto > usuario > plugin. Los de plugins llevan prefijo para no chocar.
MCP se sobrescribe por nombre: local > proyecto > usuario.
Hooks se suman: todos los registrados corren en su evento, vengan de donde vengan.
Patrones de combinación
Patrón
Ejemplo
Skill + MCP
MCP conecta a tu base de datos; una skill documenta el schema y los patrones de consulta
Skill + subagentes
/audit lanza subagentes de seguridad, rendimiento y estilo en contextos aislados
CLAUDE.md + skills
CLAUDE.md dice "sigue nuestras convenciones de API"; una skill contiene la guía completa
Hook + MCP
Un hook post-edición avisa en Slack cuando se modifican archivos críticos
Lección 4.3
Jerarquía de settings
Para un valor como model, gana la capa más alta que lo define. Las listas (como permissions.allow) se combinan entre capas, y un deny en cualquier capa gana. Define model en cada nivel y mira cuál manda:
Simulador de precedencia
Managed llega por settings gestionados desde la consola de claude.ai, MDM o un managed-settings.json. Nada lo sobrescribe. Un model gestionado es un default; los candados reales son availableModels y deniedModels.
Línea de comandos:--settings archivo-o-json aplica solo a esa sesión.
.claude/settings.local.json queda fuera de git automáticamente cuando Claude Code lo crea; ahí se guardan tus "Yes, and don't ask again".
Algunas reglas del archivo del proyecto esperan a que cada compañero confíe en la carpeta (allow, directorios adicionales, la mayoría de env); deny y ask aplican de inmediato.
Los cambios a settings se recargan en vivo, salvo model y effort (usa /model y /effort).
/status muestra la línea Setting sources; claude doctor lista entradas rechazadas. Agrega "$schema" para autocompletado en tu editor.
Así se ve un repositorio con el harness de equipo bien armado. Explora cada pieza:
Explorador del harness
← elige un archivo
MonoreposPon un CLAUDE.md raíz breve con lo transversal y CLAUDE.md o rules por paquete, que cargan solo cuando Claude trabaja ahí. Las skills y workflows también pueden vivir en <paquete>/.claude/. Usa claudeMdExcludes para ignorar instrucciones de otros equipos.
Lección 4.5
Mapa del trabajo en paralelo
Claude Code tiene cinco formas de trabajar en varias tareas a la vez. Se diferencian en quién coordina, si los trabajadores se comunican y si corren en tu máquina o en la nube.
Enfoque
Qué es
Úsalo cuando
Subagentes
Trabajadores dentro de una sesión que devuelven un resumen
Una tarea lateral inundaría tu conversación
Agent view preview
claude agents: una pantalla para despachar y vigilar sesiones en segundo plano
Tienes varias tareas independientes para delegar y revisar después
Agent teams experimental
Sesiones coordinadas por un líder, con lista de tareas compartida y mensajes
Quieres que Claude reparta un proyecto y mantenga sincronizados a los trabajadores
Dynamic workflows
Un script que corre muchos subagentes y contrasta resultados
El trabajo supera a un puñado de subagentes o necesitas verificación cruzada
Projects beta
Una conversación continua en la web o escritorio que lanza hilos en la nube
Trabajo de días o semanas que debe seguir con tu máquina apagada
¿Qué enfoque te conviene?
Responde las preguntas.
Herramientas de apoyo: worktrees aíslan archivos, cross-session messaging permite que tus sesiones se pasen hallazgos (/list-agents), y /batch empaqueta subagentes con worktrees. Para monitorear: claude agents (sesiones de fondo), /tasks (todo lo de fondo en esta sesión) y /workflows.
CostoCorrer varias sesiones o subagentes a la vez multiplica el consumo de tokens.
Lección 4.6
Dynamic workflows
Un workflow dinámico es un script JavaScript que Claude escribe y un runtime ejecuta en segundo plano mientras tu sesión sigue libre. La diferencia con los subagentes es quién tiene el plan: con subagentes, Claude decide turno a turno; en un workflow, el script tiene el loop, las ramas y los resultados intermedios, así tu contexto solo recibe la respuesta final.
Fan-out / fan-in con verificación
Tarea: "audita la seguridad del módulo de pagos antes del release". Toca orquestar para ver cómo el script reparte el trabajo, junta los resultados y los verifica antes de entregártelos. La barra de cada caja es el contexto que usa.
Cómo lanzar uno
Incluye la palabra ultracode o pide "usa un workflow" en tu prompt.
/effort ultracode deja que Claude planifique un workflow para cada tarea sustancial de la sesión (más tokens y más tiempo por pedido).
/deep-research <pregunta> es el workflow incluido: busca en la web desde varios ángulos, contrasta fuentes y entrega un reporte citado.
/workflows muestra el progreso por fase y agente; con s guardas el script como comando reutilizable en .claude/workflows/.
agent() lanza un subagente, pipeline() uno por elemento de una lista y parallel() varios a la vez. Límites: 16 agentes concurrentes por defecto y 1.000 por corrida. Un workflow pausado se reanuda; uno que pasa los 25 agentes o 1,5 M de tokens proyectados muestra la advertencia "Large workflow".
Prompts que encajan"usa un workflow para auditar cada handler en src/routes/ y verifica adversarialmente cada hallazgo antes de reportarlo" · "usa un workflow para migrar cada componente de src/components/ a TypeScript, cada archivo en su copia aislada" · "usa un workflow para correr tsc y seguir arreglando hasta que pase o dos rondas seguidas no avancen".
Lección 4.7
Agent teams experimental
Varias instancias de Claude Code trabajando como equipo: una sesión es el líder (coordina, asigna, sintetiza) y los compañeros trabajan cada uno con su contexto, se escriben directamente y comparten una lista de tareas. Están desactivados por defecto.
Los usuarios reportan que la app se desconecta tras un mensaje. Lanza 5 compañeros
que investiguen hipótesis distintas. Que se escriban entre ellos para intentar refutar
las teorías de los demás, como un debate científico. Actualiza el doc de hallazgos
con el consenso que surja.
Subagentes
Agent teams
Comunicación
Devuelven resultado a quien los llamó
Se escriben directamente entre ellos
Coordinación
El agente principal gestiona todo
Lista de tareas compartida y autocoordinación
Ideal para
Tareas enfocadas donde solo importa el resultado
Trabajo que requiere discusión y colaboración
Costo
Menor
Mayor: cada compañero es una instancia completa
Tamaño: empieza con 3 a 5 compañeros y 5 a 6 tareas por compañero. Tres enfocados suelen rendir más que cinco dispersos.
Conflictos: no usan worktrees: reparte el trabajo para que cada uno sea dueño de archivos distintos.
Contexto: cargan CLAUDE.md, MCP y skills, pero no el historial del líder: pon los detalles en el prompt de creación.
Calidad: los hooks TeammateIdle, TaskCreated y TaskCompleted con exit 2 imponen compuertas.
Visualización: en proceso (cualquier terminal) o paneles divididos con tmux o iTerm2 (teammateMode).
Límites: un equipo por sesión, sin equipos anidados, y /resume no restaura compañeros en proceso.
Por dónde empezarTareas con bordes claros que no escriben código: revisar un PR desde tres ángulos (seguridad, rendimiento, cobertura), investigar una librería o depurar con hipótesis en competencia.
Lección 4.8
Autonomía: /goal, /loop y tareas programadas
/goal fija una condición de término y Claude sigue trabajando turno tras turno sin que lo empujes. Después de cada turno, un modelo pequeño y rápido evalúa la condición contra lo que Claude mostró en la conversación: si no se cumple, Claude empieza otro turno usando la razón como guía.
en la sesión
/goal todos los tests de test/auth pasan y el lint está limpio
/goal # ver estado: condición, duración, turnos, tokens
/goal clear # cancelar
Escribe condiciones demostrables: el evaluador no corre comandos ni lee archivos; juzga lo que Claude mostró. Incluye un estado final medible, cómo se prueba ("npm test sale con 0") y restricciones ("sin modificar otros tests").
Acotar: agrega "o detente tras 20 turnos" a la condición.
Combínalo con modo auto para que los turnos corran sin prompts por herramienta. Funciona también con claude -p "/goal …".
Se limpia sola al cumplirse, si el evaluador la juzga imposible o ante errores que debes arreglar tú (auth, créditos, modelo no disponible).
Comparar formas de seguir trabajando
Enfoque
El siguiente turno empieza
Se detiene cuando
/goal
Al terminar el turno anterior
Un modelo confirma la condición o la juzga imposible
/loop
Al cumplirse un intervalo
Lo detienes, Claude decide que terminó o pasan 7 días
Hook Stop
Al terminar el turno anterior
Tu script o prompt lo decide
/loop
/loop 5m revisa si terminó el deploy y dime qué pasó
/loop revisa si pasó el CI y atiende los comentarios de review # intervalo elegido por Claude
/loop 20m /review-pr 1234 # repetir una skill
/loop # prompt de mantenimiento (o .claude/loop.md)
Programar fuera de la sesión
Nube (/schedule)
Escritorio
/loop
Corre en
La nube
Tu máquina
Tu máquina
Requiere máquina encendida
No
Sí
Sí
Requiere sesión abierta
No
No
Sí
Acceso a archivos locales
No (clon nuevo)
Sí
Sí
Intervalo mínimo
1 hora
1 minuto
1 minuto
Recordatorios de una vez en lenguaje natural: "recuérdame a las 3pm pushear la rama de release". Las horas se interpretan en tu zona horaria local.
Lección 4.9
Headless y scripts
Con -p Claude Code corre sin interfaz: recibe un prompt, trabaja y devuelve el resultado. Es la puerta para pipelines, pre-commit hooks y fan-outs. Sale con código 0 si tuvo éxito.
bash
# modo bare: no carga hooks, skills, MCP, CLAUDE.md ni auto memory (recomendado en CI)
claude --bare -p "resume README.md" --allowedTools "Read"
# salida estructurada validada contra un schema → campo structured_output
claude -p "extrae los nombres de funciones de auth.py" --output-format json \
--json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
| jq '.structured_output'
# corrida desatendida: herramientas exactas, sin prompts, con tope de turnos y gasto
claude -p "corre los tests y arregla los que fallen" \
--allowedTools "Read,Edit,Bash(pnpm test *)" \
--permission-mode dontAsk --max-turns 20 --max-budget-usd 5.00
# commit con herramientas acotadas
claude -p "revisa mis cambios staged y crea un commit apropiado" \
--allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
# continuar una conversación concreta
sid=$(claude -p "inicia una revisión" --output-format json | jq -r '.session_id')
claude -p "continúa esa revisión" --resume "$sid"
Fan-out con un loop
bash
for file in $(cat files.txt); do
claude -p "Migra $file de Python 2 a Python 3. Responde OK o FAIL." \
--allowedTools "Edit,Bash(git commit *)" \
--permission-mode dontAsk
done
Formatos: text, json (con result, session_id, uso y total_cost_usd) y stream-json (un evento por línea; agrega --verbose).
--permission-prompts none deniega todo lo que pediría aprobación cuando nadie puede responder.
Sin --bare, -p no muestra el diálogo de confianza: corre los hooks del .claude/settings.json del repo y conecta sus servidores .mcp.json aunque nunca hayas confiado en esa carpeta.
En -p funcionan las skills invocadas en el prompt (/mi-skill), no los comandos solo de interfaz.
Prueba en pocos y luego escalaAjusta el prompt con lo que falla en los primeros 2 o 3 archivos y recién entonces corre el lote completo.
Lección 4.10
GitHub Actions y Code Review
La acción anthropics/claude-code-action@v1 corre Claude Code dentro de tus workflows. Sin prompt trabaja en modo interactivo: responde a @claude en issues y PRs. Con prompt trabaja en modo automatización ante cualquier evento, incluido cron.
Setup rápido:/install-github-app dentro de Claude Code instala la app, guarda el secreto y abre el PR con el workflow.
Secretos:ANTHROPIC_API_KEY (Claude Console) o CLAUDE_CODE_OAUTH_TOKEN generado con claude setup-token para usar tu suscripción.
claude_args acepta cualquier flag del CLI: --max-turns, --model, --allowedTools, --mcp-config.
prompt también acepta una skill: /code-review:code-review --comment … instalando el plugin con plugin_marketplaces y plugins.
Solo usuarios con permiso de escritura y actores humanos (salvo allowed_bots) pueden disparar corridas.
El CLAUDE.md del repo se lee en cada corrida: mantenlo conciso para bajar costos. Limita con --max-turns, timeouts y controles de concurrencia.
Para GitLab existe una integración equivalente de CI/CD; para Bedrock, Agent Platform o Foundry, use_bedrock, use_vertex o use_foundry con OIDC.
Code Review gestionadoSi quieres que cada PR se revise automáticamente sin mantener un workflow, un Owner puede activar Code Review, el servicio gestionado de revisión sobre GitHub. Se personaliza con un archivo REVIEW.md en el repo.
Lección 4.11
Agent SDK
El Agent SDK te da las mismas herramientas, el mismo loop agéntico y la misma gestión de contexto que Claude Code, programables en Python y TypeScript. Úsalo cuando el agente es parte de tu producto o servicio.
Quieres
Usa
Integrar el agente de Claude Code en tu app, en un proceso que tú operas
Agent SDK
Desarrollo interactivo o tareas puntuales desde la terminal
Claude Code CLI
Llamar la API directamente y escribir tu propio loop de herramientas
Client SDK
Que Anthropic hospede el agente, configurado vía API
Managed Agents
TypeScript
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Revisa src/payments y reporta riesgos de seguridad",
options: {
allowedTools: ["Read", "Grep", "Glob"],
permissionMode: "default",
maxTurns: 20,
},
})) {
if (message.type === "result") console.log(message.result);
}
Disponible en el SDK: herramientas incluidas, hooks, subagentes, MCP, permisos, sesiones (retomar o bifurcar), skills, comandos, memoria y plugins, que cargan desde .claude/ igual que en Claude Code. También hay herramientas personalizadas, salida estructurada, checkpointing de archivos, seguimiento de costos y OpenTelemetry.
Autenticación y marcaSalvo aprobación previa, los productos de terceros construidos con el SDK deben usar API key, no login de claude.ai. Puedes llamarlo "Claude Agent" o "TuAgente Powered by Claude", pero no "Claude Code". Revisa la referencia del SDK antes de producción.
Lección 4.12
Nube y Remote Control
Una sesión en la nube corre en una VM aislada (de Anthropic o de un entorno self-hosted de tu organización). Sigue trabajando con tu laptop cerrado y la puedes revisar desde cualquier dispositivo. Remote Control es lo inverso: la sesión corre en tu máquina y la manejas desde el navegador o el celular.
bash
# planifica en local y ejecuta en la nube
claude --permission-mode plan
claude --cloud "Ejecuta el plan de migración en docs/migration-plan.md"
# varias tareas en paralelo, cada una en su sesión
claude --cloud "Arregla el test inestable de auth.spec.ts"
claude --cloud "Actualiza la documentación de la API"
# traer una sesión de la nube a tu terminal (rama + conversación)
claude --teleport
# enviar un mensaje a una sesión en la nube ya corriendo
claude -p "agrega también tests de borde" --cloud session_01...
# hacer accesible una sesión local desde claude.ai o la app
claude --remote-control "Mi proyecto"
La VM clona el remoto de GitHub en tu rama actual, no tu checkout local: haz push antes. Sin GitHub, Claude Code sube un bundle del repo local (bajo 100 MB).
Conecta GitHub con la GitHub App o con /web-setup (usa el token de tu CLI gh).
/autofix-pr lanza una sesión en la nube que vigila el PR de tu rama y empuja arreglos cuando falla el CI o llegan comentarios de review.
Cada entorno en la nube define acceso de red, variables de entorno y scripts de setup. Las credenciales de git quedan fuera de la VM, detrás de un proxy.
En la nube, .claude/settings.json del repo aplica, pero tus settings de usuario y locales no viajan.
Lección 4.13
Plugins y marketplaces
Un plugin empaqueta skills, subagentes, hooks, servidores MCP, servidores LSP y estilos en una unidad instalable. Es cómo llevas el harness a 5 o 500 desarrolladores sin copiar archivos.
estructura
harness-ecommerce/
├── .claude-plugin/
│ └── plugin.json ← solo el manifiesto va aquí
├── skills/
│ └── nueva-migracion/SKILL.md → /harness-ecommerce:nueva-migracion
├── agents/code-reviewer.md
├── hooks/hooks.json ← mismo formato que "hooks" en settings
└── .mcp.json
.claude-plugin/plugin.json
{
"name": "harness-ecommerce",
"description": "Skills, agentes y hooks del equipo ecommerce",
"version": "1.0.0",
"author": { "name": "Equipo Plataforma" }
}
desarrollo
claude plugin init mi-tool # scaffold en ~/.claude/skills/
claude plugin validate ./harness-ecommerce # revisa manifiesto y frontmatter
claude --plugin-dir ./harness-ecommerce # cargar solo en esta sesión
/reload-plugins # aplicar cambios sin reiniciar
claude plugin eval # medir si el plugin cambia el comportamiento
claude plugin marketplace add mi-org/claude-plugins
claude plugin install harness-ecommerce@mi-org
# o dentro de la sesión: /plugin
Las skills y agentes de un plugin llevan el nombre del plugin como prefijo (/plugin:skill), así dos plugins pueden tener una skill hello.
Mantén igual el name de la entrada del marketplace y el del plugin.json.
El marketplace oficial de Anthropic es claude-plugins-official. El plugin plugin-dev te guía a crear plugins con /plugin-dev:create-plugin.
Instala plugins de code intelligence para tu lenguaje: navegación por símbolos y errores de tipos tras cada edición.
Las organizaciones controlan qué marketplaces se permiten (strictKnownMarketplaces, blockedMarketplaces) y pueden exigir plugins.
Comunidad: Claude Code Templatesaitmpl.com es un proyecto del chileno Daniel Ávila con un catálogo de más de 1.900 componentes listos para usar: agentes, comandos, skills, hooks, configuraciones de servidores MCP y settings. Puedes explorarlo en el navegador o instalar un componente con un comando:
Los settings los impone el cliente sin importar lo que decida Claude; CLAUDE.md orienta el comportamiento pero no es una capa de enforcement.
Seguridad
Protecciones contra prompt injection: sistema de permisos, aprobación de comandos de red como curl, contexto separado para web fetch, verificación de confianza al abrir un repo nuevo o un servidor MCP nuevo, y detección de inyección de comandos.
Con contenido no confiable: revisa comandos antes de aprobar, no hagas pipe de contenido no confiable directo a Claude y usa VMs o dev containers.
Audita o bloquea cambios de configuración durante la sesión con hooks ConfigChange; monitorea uso con OpenTelemetry.
Reporta vulnerabilidades por el programa de HackerOne de Anthropic, nunca públicamente.
Costos de referencia
En despliegues empresariales, el promedio es cerca de US$13 por desarrollador por día activo y US$150–250 al mes; el 90% de los usuarios queda bajo US$30 por día activo. /usage muestra el costo de la sesión, las barras del plan y recomendaciones (en planes de suscripción, la tecla f aplica las que puede). Los procesos de fondo cuestan típicamente menos de US$0,04 por sesión. Los agent teams en plan mode usan cerca de 7 veces más tokens que una sesión estándar.
Topes de gasto
Dónde
Cómo se limita
Scripts y CI (claude -p)
--max-budget-usd 5 detiene la corrida al llegar a ese gasto estimado, contando subagentes; puede pasarse un poco, así que deja margen. --max-turns 20 limita los turnos. Sin flags, una corrida headless no tiene tope.
Claude for Teams y Enterprise
Límites de gasto por organización, grupo o miembro en la consola de administración, cuando el uso extra está activado. Cada puesto además tiene su ventana de 5 horas y su ventana semanal.
Claude Console (API)
Límites de gasto por workspace. Claude Code crea solo un workspace "Claude Code" para separar su consumo.
Bedrock, Vertex y Foundry
Los controles de costo del proveedor cloud.
Medir el consumo del equipo
Con OpenTelemetry, la métrica claude_code.token.usage separa los tokens por tipo: input, output, cacheRead y cacheCreation. Una proporción baja de cacheRead delata sesiones que rompen el caché (lección 2.8).
claude_code.cost.usage da el costo en US$, y el evento api_request trae los tokens de caché de cada petición.
Los costos que muestra Claude Code son estimaciones a precio de lista; si tu organización tiene precios negociados, configúralos con modelPricing.
Checklist de gobernanza
Marca lo que ya tienes
Quiz final
Quiz · Nivel Experto
Responde todas correctamente para aprobar
Documentación oficial
Claude Code se actualiza cada semana. Verifica flags e inputs exactos antes de producción.