04
Nivel 04 · Experto

Diseñar el harness

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:

DisparadorAgrega
Claude se equivoca dos veces en una convención o comandoUna línea en CLAUDE.md
Pides una y otra vez respuestas más cortas o en cierto formatoUn output style
Escribes el mismo prompt para empezar una tareaUna skill invocable por el usuario
Pegas el mismo procedimiento por tercera vezUna skill
Copias datos de una pestaña que Claude no puede verUn servidor MCP
Claude lee muchos archivos buscando dónde se define un símboloUn plugin de code intelligence
Una tarea lateral inunda tu conversación de salidaUn subagente
Quieres que algo pase siempre, sin pedirloUn hook
Un segundo repo necesita el mismo setupUn 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.

MecanismoCuándo cargaQué cargaCosto
CLAUDE.mdInicio de sesiónContenido completoEn cada request
Output styleInicio y al cambiarInstrucciones del estilo activoEn cada request
SkillsInicio + al usarseDescripciones al inicio; contenido al usarseBajo (cero con disable-model-invocation)
MCPInicioNombres de herramientas; schemas bajo demandaBajo hasta que se usa una herramienta
Code intelligenceTras editar y bajo demandaDiagnósticos y ubicaciones de símbolosBajo; reduce lecturas de archivos
SubagentesAl lanzarseContexto propio y limpioAislado de tu sesión
HooksEn su eventoNada (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ónEjemplo
Skill + MCPMCP 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 + skillsCLAUDE.md dice "sigue nuestras convenciones de API"; una skill contiene la guía completa
Hook + MCPUn 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.
A fondoSettings a fondoScopes, simulador de precedencia, explorador de claves y diagnóstico.→
Lección 4.4

Anatomía de un repo preparado

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.

EnfoqueQué esÚsalo cuando
SubagentesTrabajadores dentro de una sesión que devuelven un resumenUna tarea lateral inundaría tu conversación
Agent view previewclaude agents: una pantalla para despachar y vigilar sesiones en segundo planoTienes varias tareas independientes para delegar y revisar después
Agent teams experimentalSesiones coordinadas por un líder, con lista de tareas compartida y mensajesQuieres que Claude reparta un proyecto y mantenga sincronizados a los trabajadores
Dynamic workflowsUn script que corre muchos subagentes y contrasta resultadosEl trabajo supera a un puñado de subagentes o necesitas verificación cruzada
Projects betaUna conversación continua en la web o escritorio que lanza hilos en la nubeTrabajo 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/.
.claude/workflows/audit-routes.js
export const meta = {
  name: 'audit-routes',
  description: 'Audita cada route handler buscando auth faltante',
}

const found = await agent('Lista cada archivo .ts bajo src/routes/.', {
  schema: { type: 'object', required: ['files'],
            properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audita ${file} buscando chequeos de autenticación faltantes.`, { label: file }),
)

return audits.filter(Boolean)

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.

settings.json
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
prompt
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.
SubagentesAgent teams
ComunicaciónDevuelven resultado a quien los llamóSe escriben directamente entre ellos
CoordinaciónEl agente principal gestiona todoLista de tareas compartida y autocoordinación
Ideal paraTareas enfocadas donde solo importa el resultadoTrabajo que requiere discusión y colaboración
CostoMenorMayor: 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

EnfoqueEl siguiente turno empiezaSe detiene cuando
/goalAl terminar el turno anteriorUn modelo confirma la condición o la juzga imposible
/loopAl cumplirse un intervaloLo detienes, Claude decide que terminó o pasan 7 días
Hook StopAl terminar el turno anteriorTu 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 enLa nubeTu máquinaTu máquina
Requiere máquina encendidaNoSíSí
Requiere sesión abiertaNoNoSí
Acceso a archivos localesNo (clon nuevo)SíSí
Intervalo mínimo1 hora1 minuto1 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.
.github/workflows/claude.yml
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: "--max-turns 10 --model claude-sonnet-5"
  • 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.

QuieresUsa
Integrar el agente de Claude Code en tu app, en un proceso que tú operasAgent SDK
Desarrollo interactivo o tareas puntuales desde la terminalClaude Code CLI
Llamar la API directamente y escribir tu propio loop de herramientasClient SDK
Que Anthropic hospede el agente, configurado vía APIManaged 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

Distribuir con un marketplace

.claude-plugin/marketplace.json
{
  "name": "mi-org",
  "owner": { "name": "Plataforma" },
  "plugins": [
    { "name": "harness-ecommerce", "source": "./plugins/harness-ecommerce",
      "description": "Harness del equipo ecommerce" },
    { "name": "reviewer", "source": { "source": "github", "repo": "mi-org/reviewer-plugin" } }
  ]
}
usuarios
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:
bash
npx claude-code-templates@latest                 # navegador interactivo
npx claude-code-templates@latest --agent development-team/frontend-developer
Como con cualquier plugin de terceros, revisa qué instala antes de usarlo en un repo de trabajo.
Lección 4.14

Gobernanza, seguridad y costos

Qué va en settings gestionados y qué en CLAUDE.md gestionado

NecesidadConfigúralo en
Bloquear herramientas, comandos o rutasManaged settings: permissions.deny
Forzar sandboxManaged settings: sandbox.enabled
Variables de entorno y proveedor de APIManaged settings: env
Método de login y organizaciónManaged settings: forceLoginMethod, forceLoginOrgUUID
Quitar modospermissions.disableBypassPermissionsMode, disableAutoMode
Solo reglas gestionadasallowManagedPermissionRulesOnly, allowManagedHooksOnly
Guías de estilo, cumplimiento, comportamientoCLAUDE.md gestionado (o la clave claudeMd)

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óndeCó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 EnterpriseLí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 FoundryLos 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