Mejores prácticas para Claude Code

Aprovecha más Claude Code: dile a Claude lo que no puede ver, dale una verificación que ejecutar y aplica las reglas que no pueden tener excepciones.

Claude Code está diseñado de forma que, en la mayoría de los casos, tu primer prompt sencillo en una sesión nueva ya hace lo correcto, sin ninguna configuración de tu parte.

Por ejemplo:

• Para que los comandos se ejecuten de forma segura sin que tengas que aprobar cada uno, las nuevas sesiones de terminal y VS Code comienzan en modo automático, donde un clasificador revisa cualquier cosa arriesgada antes de que se ejecute.
• Para mantener tu conversación principal enfocada mientras el trabajo independiente ocurre en paralelo, Claude delega en subagentes y solo te consulta cuando es necesario.
• Para que una sesión larga siga adelante sin que tengas que gestionarla, tu conversación se compacta automáticamente antes de que se llene la ventana de contexto.

Esta página explica qué hacer cuando los valores predeterminados no son suficientes. Eso suele ocurrir cuando tu proyecto tiene conocimientos, reglas o restricciones que Claude no puede ver solo a partir del código:

• Un proceso de despliegue que vive en la cabeza de alguien
• Un archivo que nunca debe leerse
• Una verificación que tiene que pasar antes de que algo se considere terminado
• Un presupuesto que no debes superar

Ningún valor predeterminado puede saber esas cosas sobre tu proyecto, así que aquí es donde una pequeña configuración de tu parte vale la pena.

Cuando una sesión no sale como esperabas, casi siempre es por una de estas razones:

• Claude construyó algo diferente de lo que tenías en mente, o tiene que redescubrir el mismo dato al inicio de cada sesión. Le falta información que no puede obtener leyendo el repositorio. Consulta Dile a Claude lo que no puede ver.
• Claude dijo que había terminado y no era del todo así, normalmente porque no tenía forma de verificar su propio trabajo. Consulta Dale a Claude una verificación que ejecutar.
• Claude hizo algo que nunca debe ocurrir en este repositorio, u omitió un paso que siempre debe ocurrir. Un prompt por sí solo no puede garantizar ninguna de las dos cosas. Consulta Aplica las reglas que no pueden tener excepciones.
• Claude lo hizo bien, pero le llevó más tiempo, tokens o solicitudes de permiso de lo que valía la tarea. Consulta Cambia un valor predeterminado.

Deja que Claude trabaje sin ti aplica estos mismos cuatro puntos a las ejecuciones desatendidas, y Lo que puedes dejar de hacer enumera los consejos que los modelos actuales han vuelto innecesarios.

[!NOTE]

La configuración para todo un equipo está en una página aparte: Configura Claude Code para tu organización.

Instrucciones deterministas y no deterministas

Cada instrucción que le das a Claude Code es de uno de estos tipos:

1. No determinista: tú escribes la instrucción y Claude (el modelo) la lee. Puede ser tu prompt, CLAUDE.md o un skill. Luego el modelo decide qué hacer con esa información. Normalmente sigue tus indicaciones, y los modelos actuales son buenos entendiendo tu intención sin mucho contexto, pero no hay garantía de que siga tus instrucciones. Aún puede decidir no hacer cosas, o hacer otras.
2. Determinista: tú configuras la instrucción y Claude Code (el harness) tiene que ejecutarla. Puede ser un hook, una regla de denegación o una configuración administrada. Claude Code la aplica siempre, sin importar lo que haya decidido el modelo.

La mayoría de las cosas en Claude Code existen en ambas formas:

La mayor parte del tiempo, quieres que Claude decida. Casi todas las pautas tienen excepciones, y los modelos actuales son buenos leyendo el código que tienen delante y juzgando si una pauta encaja con la situación. Con el código real delante, Claude suele estar mejor posicionado para tomar esa decisión que una regla que escribiste de antemano.

El tipo determinista es para cuando quieres asegurarte de que ciertas cosas siempre ocurran (o nunca ocurran), sin importar lo que decida el modelo. No tiene que ser nada dramático. El modo automático ya bloquea las cosas dramáticas, como un despliegue a producción o un force push sobre el trabajo de otra persona. Normalmente es algo específico de tu proyecto, y puede ser tan particular como quieras:

• Nunca editar el cliente generado en src/gen/
• Siempre ejecutar el script de encabezado de licencia después de crear un archivo

Podrías haber escrito cualquiera de estas como una línea en CLAUDE.md o en tu prompt, y Claude la seguiría casi siempre. Pero no importa con cuánta fuerza lo redactes: que Claude siga esa línea en un turno dado sigue siendo decisión de Claude.

[!TIP]

Si sigues agregando énfasis a una línea de CLAUDE.md y Claude aún la pasa por alto, es señal de que esa línea debería ser un hook. Lo contrario también se cumple: si tienes hooks para cosas que solo son preferencias, elimínalos y deja que Claude decida.

Dile a Claude lo que no puede ver

[!TIP]

Escribe solo lo que Claude no puede encontrar leyendo el repositorio, o lo que de otro modo pasaría tiempo redescubriendo en cada sesión.

Claude comienza cada tarea leyendo tu código, y los modelos actuales son muy buenos en esto. Encontrarán la estructura de tus archivos, tus convenciones, tu framework de pruebas y cómo están construidos los componentes existentes, normalmente más rápido de lo que podrías explicarlos. Eso significa que Claude ya sabe la mayor parte de lo que podrías sentir la tentación de escribirle.

Lo que no puede encontrar es la información que nunca estuvo en el repositorio:

• Una decisión que tu equipo tomó en una reunión
• Un proceso de despliegue que vive en la cabeza de una persona
• La variable de entorno que necesitan tus pruebas de integración

También hay información que sí está en el repositorio pero que requiere unos minutos de búsqueda para encontrarla, y Claude tiene que repetir esa búsqueda al inicio de cada sesión.

Una buena prueba antes de escribir cualquier cosa para Claude:

1. ¿Podría encontrarlo leyendo el código?
2. ¿Realmente iría a buscarlo?

Si ambas respuestas son sí, déjalo fuera.

Escribe un prompt específico

Un prompt específico ayuda por la misma razón, porque le da a Claude información que todavía no tiene. Si nombras el archivo, describes el síntoma y dices desde el principio cómo se ve "corregido", normalmente te ahorras una ronda de correcciones más adelante.

Lo mismo aplica a una preferencia entre dos enfoques razonables: Claude no puede leerla en el código, así que si te importa cuál elige, dilo desde el principio.

Si ya tienes lo que Claude necesita, entrégaselo en lugar de describirlo:

• Un archivo: escribe @ y la ruta para incluir el contenido del archivo en tu mensaje.
• Una imagen: pega en el prompt la captura de pantalla del diseño o del error.
• Salida de un comando: canalízala desde tu shell con cat error.log | claude -p "what's going on here".

Frases como think step by step o be thorough son texto de prompt normal, no palabras clave. El control principal de cuánto piensa Claude es el nivel de esfuerzo, que se trata en Cambia el modelo y el esfuerzo. Ese tipo de redacción aún puede empujar a Claude dentro de su ajuste de esfuerzo, pero no lo elevará por encima de él.

Una frase que sí sigue ayudando es be ambitious. Claude tiende a leer una petición de forma conservadora y a construir lo mínimo que la satisface, ya que no puede ver cuánto esperabas. Cuando quieras la versión más completa, con los casos extremos resueltos y la continuación natural incluida, dilo:

build the settings page from the mockup. be ambitious: empty and error states, the save flow wired up, keyboard navigation, not just the layout

Eso le dice a Claude el alcance, que solo tú conoces, en lugar de cuánto pensar.

Y cuando estás explorando en lugar de corregir algo específico, un prompt vago como what would you improve in this file? está completamente bien. Corregirás un poco más sobre la marcha, y esa es la contrapartida.

Haz una lluvia de ideas con Claude primero

Cuando todavía no sabes exactamente lo que quieres, no tienes que resolverlo todo antes de escribir el prompt. En su lugar, pídele a Claude que te entreviste:

I want to add rate limiting to the public API but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md.

Claude vuelve con preguntas de opción múltiple sobre las partes que no has definido: límites por usuario o por clave, qué ocurre con las solicitudes que superan el límite, qué queda fuera del alcance. Sigue preguntando hasta que las respuestas formen una especificación.

Una vez que SPEC.md exista, inicia una sesión nueva para construir a partir de ella, de modo que la construcción empiece con un contexto limpio y una definición escrita de terminado. También es el archivo al que dirigirás al revisor más adelante, en Dale a Claude una verificación que ejecutar.

Mantén CLAUDE.md corto

Claude Code carga CLAUDE.md en cada sesión, lo que significa que cada línea ocupa un poco de la atención de Claude en cada tarea, sea relevante o no. Por eso el archivo funciona mejor cuando solo contiene lo que Claude no podría deducir del propio código:

• Cómo confirmar el trabajo en este repositorio: los comandos exactos de pruebas, verificación de tipos y lint, y cómo ejecutar un único archivo de pruebas
• Lugares donde el código es engañoso: un patrón antiguo que está en todas partes pero que el código nuevo no debe copiar, o un directorio que parece sin uso pero no lo está
• Decisiones que no están en el repositorio: qué helper de errores eligió el equipo, cómo funcionan los despliegues, qué necesita una revisión de migración
• Cualquier cosa que ya hayas tenido que corregir dos veces

Un CLAUDE.md que pasa esa prueba se mantiene corto:

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

En una sesión, ejecuta /context all para confirmar que Claude cargó el archivo.

Observa que la línea de verificación de tipos es solo el comando. Claude necesita conocer el comando para poder verificar su propio trabajo sobre la marcha. Si además quieres que Claude Code exija que la verificación de tipos pase antes de que Claude termine, eso es tarea de un hook Stop. Una línea como Always typecheck before you finish en este archivo funciona la mayoría de las veces, no siempre.

No tienes que escribir el archivo desde cero:

• /init genera una versión inicial a partir de tu base de código. A partir de ahí, el trabajo consiste sobre todo en eliminar líneas. La guía de memoria recomienda mantenerse por debajo de 200.
• /doctor sugiere recortes para todo lo que Claude ya puede deducir del código.
• /doctor prompt-audit marca las instrucciones que se escribieron para modelos anteriores, que apuntan a archivos que ya no existen o que se contradicen entre sí.

Tus preferencias personales van en CLAUDE.local.md en lugar de CLAUDE.md, y agregas ese archivo a .gitignore para que quede fuera del repositorio.

[!NOTE]

Si Claude sigue ignorando una línea que sí está en CLAUDE.md, agregar IMPORTANT probablemente no lo arreglará. O bien el archivo ha crecido tanto que la línea se pierde, o bien la línea es una regla que no puede tener excepciones, en cuyo caso debería ser un hook.

Limita las reglas a una parte de la base de código

Si una regla solo importa en una parte de la base de código, ponla en .claude/rules/ con un filtro paths: para que solo se cargue cuando Claude realmente esté trabajando allí. Por ejemplo, este .claude/rules/api.md se carga para los archivos TypeScript bajo src/api/:

---
paths:
  - "src/api/**/*.ts"
---
- Validate request bodies with the zod schemas in src/api/schemas/, don't hand-roll checks
- Every new endpoint needs an entry in openapi.yaml, CI fails without it

Pon los procedimientos del equipo en skills

Un modelo más capaz sabe más sobre ingeniería, pero no cómo hace tu equipo un lanzamiento, qué dice tu runbook de incidentes o cómo quieres que se escriba la documentación de la API. Ese tipo de conocimiento va en un skill: un procedimiento o un conocimiento del equipo guardado en .claude/skills/<name>/SKILL.md.

Los skills también consumen menos contexto que CLAUDE.md para este tipo de cosas. Para un skill que Claude puede iniciar por sí mismo, ve el nombre y la descripción en cada sesión, pero solo lee el archivo completo cuando la tarea lo requiere. Un procedimiento de lanzamiento largo dentro de un skill no pesa sobre tu corrección de un error no relacionado como lo haría en CLAUDE.md.

[!NOTE]

La regla de CLAUDE.md también se aplica a los skills: escribe solo lo que Claude no puede encontrar por sí mismo.

Para un flujo de trabajo con efectos secundarios, como hacer realmente ese lanzamiento, agrega disable-model-invocation: true. Así Claude no puede iniciar el skill por sí mismo, y solo se ejecuta cuando tú escribes /release. Guardado como .claude/skills/release/SKILL.md, podría verse así:

---
name: release
description: Cut a new release. Bumps the version, writes the changelog entry, tags it and pushes the tag so CI can publish.
disable-model-invocation: true
---
1. Make sure you're on main with a clean tree. If not, stop and ask.
2. Run `pnpm changeset version` and commit the result.
3. Summarize the PRs merged since the last tag into CHANGELOG.md, one line each, user-facing changes only.
4. Tag `v<new version>` and push the tag. CI publishes from there, never publish from your machine.

Conecta las herramientas que Claude necesita

Parte de lo que Claude no puede ver vive en otro sistema por completo, como tu gestor de incidencias o tu panel de errores. Si ese sistema tiene un CLI, normalmente es la forma más fácil de acceder. Con gh instalado y con la sesión iniciada, por ejemplo, Claude abrirá pull requests y leerá comentarios de revisión sin ninguna explicación de tu parte. Para un CLI que no ha visto antes, basta con indicarle --help.

Para los sistemas sin CLI, existe MCP. Agregas un servidor desde tu shell:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Luego el servidor aparece en /mcp dentro de una sesión. Los servidores conectados agregan sus nombres de herramientas e instrucciones al contexto incluso cuando no los estás usando, así que vale la pena desactivar allí los que no necesitas.

Y si trabajas en un lenguaje tipado, un plugin de inteligencia de código permite que Claude salte directamente a una definición en lugar de leer muchos archivos para encontrarla.

Dale a Claude una verificación que ejecutar

Claude se detiene cuando el trabajo parece terminado. Si no tiene nada que ejecutar que le diga si el trabajo realmente está terminado, "parece terminado" es lo único en lo que puede basarse. En la práctica, eso te convierte a ti en el conjunto de pruebas, y cada error se queda ahí hasta que lo notes por casualidad.

Si le das algo que devuelva aprobado o fallido, Claude puede cerrar ese ciclo por sí mismo. Hace el cambio, ejecuta la verificación y, si algo se rompió, lee la salida y lo corrige antes de volver a ejecutar la verificación.

[!TIP]

Dale a Claude algo que pueda ejecutar y que devuelva aprobado o fallido. Una vez que lo tenga, puede seguir trabajando por su cuenta y no tienes que estar observando.

La verificación puede ser casi cualquier cosa, siempre que Claude pueda leer el resultado:

• Un archivo de pruebas
• El código de salida de una compilación
• Un linter
• Un script que compara la salida con una fixture
• Una captura de pantalla del navegador junto al diseño

Si tu repositorio ya tiene alguna de estas, la línea más útil de tu CLAUDE.md es el comando que la ejecuta.

Qué tan estricta hagas la verificación depende de ti. Las opciones van desde que Claude decida por sí mismo hasta que Claude Code la exija:

• En el prompt: run the auth tests after, and keep going until they pass. Claude decide por sí mismo cuándo está satisfecho. Esto funciona para cualquier tarea, hoy mismo, sin configuración.
• Como objetivo: /goal all tests in tests/auth pass and lint is clean establece una condición que un modelo separado verifica contra la conversación después de cada turno, y Claude sigue trabajando hasta que se cumple. Rara vez lo necesitas tú mismo en la sesión. Importa en ejecuciones largas en segundo plano, donde Claude a veces termina un turno con un resumen del progreso mientras aún quedan elementos pendientes, y el objetivo lo hace volver al trabajo.
• Como hook Stop: un hook Stop ejecuta tu script cada vez que Claude intenta terminar su turno, y devuelve a Claude al trabajo si el script sale con el código 2. Este lo aplica Claude Code (el harness), así que el turno no termina hasta que pase la verificación de tipos o se alcance el límite de bloqueos. Hay un ejemplo más abajo.
• Por alguien que no escribió el código: en la terminal, /code-review revisa el diff en un subagente nuevo que nunca vio tu conversación. No se deja influir por el razonamiento que produjo el código.

Sea cual sea la opción que uses, pídele a Claude evidencia: el comando que ejecutó y su salida, o la captura de pantalla. "Todas las pruebas pasan" por sí solo te dice muy poco, y leer la salida es más rápido que volver a ejecutar la verificación tú mismo. Para una sesión que no estabas observando, también es la única evidencia que tienes.

[!TIP]

Una vez que Claude diga que terminó, también puedes ejecutar /verify en la sesión, lo que hace que Claude compile y ejecute la aplicación y revise el resultado. Eso detecta el tipo de problema que las pruebas y la verificación de tipos pasan por alto.

Revisa contra tu especificación

Si prefieres que la revisión compare el trabajo con tu plan en lugar de buscar errores en general, escribe tú mismo el prompt de revisión:

use a subagent to review the rate limiter diff against SPEC.md, check every requirement is implemented and the listed edge cases have tests, report gaps that affect correctness and skip style

[!NOTE]

No quites la parte skip style de ese prompt. Un revisor al que se le pide encontrar problemas siempre encontrará algo. Si corriges cada hallazgo, terminas con capas de abstracción adicionales y pruebas para casos que no pueden ocurrir.

Exige la verificación con un hook Stop

La versión con hook Stop de la regla de verificación de tipos son unas pocas líneas en .claude/settings.json. El código de salida 2 es lo que bloquea la detención. Lo que el comando imprima en stderr vuelve a Claude como la razón por la que aún no puede terminar, por eso la salida del compilador se redirige allí:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
        ]
      }
    ]
  }
}

Para verlo funcionar, pídele a Claude un cambio que rompa un tipo: en lugar de terminar, recibe los errores del compilador y sigue trabajando hasta que tsc pase. Si el hook bloquea ocho detenciones seguidas sin ninguna llamada a herramienta entre ellas, Claude Code sobrescribe el siguiente bloqueo y termina el turno. Para aumentar el límite, establece CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

Aplica las reglas que no pueden tener excepciones

[!TIP]

Si algo tiene que ocurrir siempre, conviértelo en un hook, una regla de denegación o una configuración administrada. CLAUDE.md es para pautas, y Claude puede decidir que una pauta no aplica.

Toma tres reglas que podrías tener hoy en CLAUDE.md: Never read .env, Always run the formatter after editing, Don't touch the migrations folder. Claude las seguirá casi siempre. Para las pocas en las que "casi" no es suficiente, sácalas de CLAUDE.md y pásalas a una configuración que Claude Code (el harness) aplica por sí mismo. A partir de entonces, el resultado no depende de lo que el modelo recuerde o decida.

Exige pasos con hooks

Los hooks ejecutan algo tuyo en puntos fijos del ciclo de Claude: antes o después de una llamada a herramienta, cuando Claude intenta detenerse, cuando comienza una sesión, etc. Ese algo puede ser:

• Un comando de shell (el caso habitual)
• Un POST a un endpoint HTTP
• Una llamada a herramienta en uno de tus servidores MCP
• Un hook prompt o agent, que deja que un modelo decida

Un hook prompt o agent le pide a otro modelo que decida, así que tampoco es determinista. Para una aplicación real, usa un hook command o http, y agrega onFailure: "block" si la acción también debe detenerse cuando el propio hook falla o agota el tiempo de espera. Para un hook que analiza commits en busca de secretos, por ejemplo, preferirías bloquear el commit antes que dejarlo pasar sin analizar mientras el escáner está caído.

Aquí está la regla del formateador como un hook PostToolUse. Se ejecuta después de cada Edit o Write, y ya no importa si Claude recuerda la regla, porque no es Claude quien la ejecuta:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }
        ]
      }
    ]
  }
}

Para comprobar el hook, pídele a Claude que agregue una línea mal indentada a un archivo que Prettier formatea. El archivo guardado vuelve con la indentación corregida.

La regla de migraciones se convierte en un hook PreToolUse que sale con el código 2 para cualquier ruta bajo migrations/. No tienes que escribirlo tú mismo: write a hook that blocks edits to the migrations folder funciona como prompt, y /hooks muestra el resultado. Pero no te excedas: un hook es para una regla con cero excepciones, y Prefer named exports tiene muchas, así que esa se queda en CLAUDE.md.

Limita el acceso con reglas de permisos y el sandbox

Las reglas de permisos deciden qué puede ejecutar, leer y obtener Claude. Las reglas deny se mantienen en todos los modos de permisos, incluidos el automático y bypassPermissions, y precisamente por eso la regla de .env va ahí:

{
  "permissions": {
    "allow": ["Bash(pnpm tsc --noEmit)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
  }
}

Con esto guardado, preguntarle a Claude qué hay en .env falla, tanto con la herramienta Read como con cat .env.

Las reglas coinciden con llamadas a herramientas, no con intenciones, así que conviene saber dónde están los límites:

• La regla Read sí detecta cat .env, porque Claude Code reconoce los comandos comunes de lectura de archivos.
• No detectará un script que abra el archivo.
• Una regla de denegación de WebFetch para un dominio no hace nada contra curl a ese mismo dominio, a menos que el sandbox esté activado.

Para un límite a nivel del sistema operativo sobre el acceso al sistema de archivos o a la red, activa el sandbox con /sandbox en una sesión. Confina los comandos de shell de Claude en macOS, Linux y WSL2 y también incorpora tus reglas de denegación de Read y tus reglas WebFetch(domain:...), así que para cualquier cosa relacionada con la seguridad quieres ambos.

De forma predeterminada, Claude aún puede pedir reintentar un comando bloqueado fuera del sandbox, y esa petición pasa por el flujo normal de permisos. El modo estricto del sandbox, en la pestaña Overrides de /sandbox, desactiva ese reintento.

[!WARNING]

El modo automático es un modelo clasificador que juzga cada acción, no una regla rígida. Lo hace bien, pero como cualquier juicio, puede equivocarse. Además, puedes ajustar lo que considera arriesgado, y tu organización puede desactivarlo por completo, así que tus reglas de "nunca" deben estar en reglas de denegación o en hooks.

Elige a quién se aplica una regla

Dónde vive una regla decide a quién se aplica:

• .claude/settings.local.json y ~/.claude/settings.json son solo tuyos. Cuando seleccionas Yes, and don't ask again para un comando, Claude Code guarda esa regla en el archivo local.
• .claude/settings.json y los hooks que contiene pertenecen al repositorio. Una vez que haces commit de ellos, se aplican a todos los que trabajan en el repositorio. Sus reglas de denegación se aplican de inmediato. Sus reglas allow esperan hasta que cada persona acepta el diálogo de confianza para esa carpeta, y la confianza del espacio de trabajo también decide cuándo empiezan a ejecutarse sus hooks en su máquina.
• La configuración administrada pertenece a la organización. Proviene de la consola de administración, de MDM o de un archivo managed-settings.json, y ningún archivo de configuración personal puede sobrescribirla, lo que la convierte en el único lugar para la política de un equipo de seguridad. Si eres la persona que la establece, consulta Configura Claude Code para tu organización.

Sea cual sea el alcance, mantén pequeño el conjunto de reglas aplicadas. Cada hook y regla de denegación se activará ocasionalmente cuando no debería, y alguien tiene que mantener cada uno. Si alguna vez te encuentras con cuarenta, la mayoría probablemente son preferencias que Claude podría haber sopesado por sí mismo.

Cambia un valor predeterminado

[!TIP]

Los valores predeterminados son lo bastante buenos como para dejarlos como están hasta que una tarea cueste más tiempo, tokens o interrupciones de lo que debería. Cuando eso ocurra, ejecuta /usage en la sesión para ver en qué se fue.

Una sesión nueva ya toma varias decisiones por ti:

• Las sesiones interactivas de terminal y VS Code comienzan en modo automático.
• Ejecuta Claude Opus 5.5 con esfuerzo medio en la mayoría de los planes y proveedores.
• Delega trabajo en subagentes cuando ve una razón para hacerlo.
• Compacta la conversación a medida que crece.

La mayor parte del tiempo nunca piensas en estas cosas. Cuando una tarea sí cuesta más de lo que debería, normalmente la causa es una de estas cuatro.

Cambia el modo de permisos

Ambos extremos del rango de permisos tienen un costo:

• Modo Manual: apruebas tú mismo cada edición y cada comando que no sea de solo lectura. Es seguro, pero después de la décima solicitud empiezas a aprobar sin leer, y nada avanza mientras estás lejos del teclado.
• bypassPermissions: aprueba todo lo que tus reglas deny y ask no cubren, lo cual solo tiene sentido en un contenedor desechable.

El modo automático se sitúa entre ambos, y es el modo en el que comienzan las sesiones interactivas de terminal y VS Code. Claude trabaja sin detenerse para aprobaciones rutinarias, y un modelo clasificador separado revisa las acciones en un orden fijo antes de que se ejecuten. Se concentra en las cosas que querrías que una persona detuviera:

• curl | bash
• Despliegues y migraciones a producción
• Force pushes sobre el trabajo de otras personas
• Datos sensibles enviados a endpoints externos
• Acciones que parecen impulsadas por contenido que Claude leyó y no por ti

Cuando el modo automático bloquea una acción, recibes una notificación y la acción aparece en Recently blocked en /permissions, donde puedes aprobar la acción para que Claude pueda reintentarla. Después de tres bloqueos seguidos (o veinte en total), el modo automático se pausa y vuelve a preguntarte.

Nada de esto reemplaza tus controles deterministas, porque se ejecuta después de ellos. Las reglas deny y ask y los hooks PreToolUse se aplican antes de que el clasificador vea nada, así que una regla de denegación bloquea en modo automático exactamente igual que en cualquier otro lugar. El sandbox sigue confinando los comandos de shell que envuelve.

[!NOTE]

También puedes decir don't push until I've reviewed en la conversación, y el clasificador lo trata como una señal de bloqueo. Sigue siendo un modelo leyendo la transcripción, y la frase puede perderse cuando la conversación se compacta, así que cualquier cosa que importe debe estar en una regla de denegación.

El problema opuesto es que el clasificador detenga repetidamente algo que es rutinario en tu entorno. En lugar de aprobarlo manualmente cada vez, agrégalo a autoMode.allow o describe tu infraestructura de confianza en la configuración del modo automático. Está en inglés sencillo y no en patrones, y /auto-mode-setup puede redactar la parte environment por ti a partir de tu proyecto y tus sesiones recientes:

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.com/example-org and every repo under it",
      "Trusted internal domains: *.internal.example.com"
    ],
    "allow": [
      "$defaults",
      "Deploying to the staging namespace is fine, it's isolated from production and resets nightly"
    ]
  }
}

[!WARNING]

Mantén "$defaults" en cada lista que establezcas, porque sin él tus entradas reemplazan las reglas integradas de esa lista en lugar de sumarse a ellas. Para environment y allow perderías el contexto y las excepciones integrados, y una lista soft_deny sin él elimina los bloqueos integrados sobre force pushes y despliegues a producción.

El bloque autoMode también tiene que estar en ~/.claude/settings.json y no en el proyecto, porque el clasificador ignora autoMode en la configuración del proyecto.

Si prefieres ver cada edición y comando antes de que ocurran, Shift+Tab en la sesión recorre los modos de permisos, incluido Manual, o empieza con claude --permission-mode manual desde tu shell. Y si Manual luego pregunta demasiado, /fewer-permission-prompts analiza tus transcripciones recientes en busca de llamadas comunes de solo lectura de Bash y MCP y las agrega a una lista de permitidos en .claude/settings.json.

Cambia el modelo y el esfuerzo

El esfuerzo es el control principal de cuánto tiempo piensa Claude, y reemplaza la mayor parte de lo que la gente solía hacer con la redacción del prompt. Claude Opus 5.5, Sonnet 5.5 y Haiku 5.5 usan medium de forma predeterminada, lo cual es suficiente para el trabajo cotidiano en funcionalidades con un alcance claro. Los momentos en que lo cambiarías, con /effort en la sesión:

• Súbelo con /effort high o /effort xhigh cuando hacerlo bien dependa de casos fáciles de pasar por alto. Piensa en un error en código que no escribiste, una prueba inestable o un cambio de esquema en el que Claude tiene que encontrar cada lector de la forma antigua. Claude entonces revisa más casos extremos y verifica más de su trabajo antes de responder, y ahí es donde se van el tiempo y los tokens adicionales.
• Bájalo con /effort low cuando estás yendo y viniendo rápidamente y revisando cada resultado de todos modos: lluvia de ideas, un primer boceto, un cambio de nombre en unos pocos archivos. Claude te da un punto de partida antes, y como estás dirigiendo cada paso, la deliberación adicional no habría cambiado mucho aparte de la espera.
• Reserva max para un problema difícil que quieres que Claude resuelva sin ti, como buscar una vulnerabilidad de seguridad. En tareas ordinarias tiende a pensar de más, así que pagas más por una respuesta que puede no ser mejor que la que te habría dado high.
• Cuando solo el siguiente mensaje lo necesita, como una pregunta complicada en medio de un trabajo por lo demás rutinario, pon ultrathink en ese prompt en lugar de cambiar el ajuste.

En cuanto al modelo en sí, Opus 5.5, el predeterminado, maneja bien la mayor parte de la programación, y Sonnet cuesta menos en el trabajo rutinario. Claude Fable 5.1 está disponible cuando lo seleccionas explícitamente con /model fable, y Haiku encaja bien para subagentes que hacen trabajos sencillos. Configuración del modelo tiene la lista completa por plan y proveedor.

Conoce lo que cuestan los subagentes

Claude delega en subagentes por su cuenta:

• Las búsquedas amplias en la base de código van al agente Explore integrado.
• Las tareas secundarias se bifurcan mientras el modo de bifurcación está activado (el valor predeterminado).
• Los subagentes que inicia se ejecutan en segundo plano de forma predeterminada, así que tu conversación principal sigue avanzando.

Rara vez necesitas pedir nada de esto, pero ayuda saber qué obtienes y cuánto cuesta.

Los subagentes valen la pena en estas situaciones:

• Ejecutar trabajos independientes al mismo tiempo, para que toda la tarea termine antes
• Mantener la salida larga, como una ejecución completa de pruebas o una búsqueda amplia, fuera de tu conversación principal, donde de lo contrario viajaría contigo el resto de la sesión
• Obtener un revisor que no ha visto cómo se escribió el código
• Darle a una tarea menos herramientas de las que tiene la sesión principal, como un revisor que puede leer pero no editar

Lo que te cuestan es sobre todo tokens, ya que cada subagente envía sus propias solicitudes y estas cuentan contra el mismo uso que tu conversación principal. A veces también cuestan tiempo: un subagente nuevo primero tiene que reunir el contexto que tu conversación ya tenía, así que puede terminar siendo más lento que hacer la tarea donde estás.

Y de forma predeterminada es el mismo modelo (o uno más pequeño) en la misma tarea. Obtienes paralelismo o una mirada nueva, pero no una respuesta más inteligente.

Para gastar menos en ellos:

• Establece model: haiku en la definición de un subagente si su trabajo es sencillo, como recopilar los archivos que importan un módulo o verificar los enlaces de la documentación. Ese tipo de trabajo no necesita el modelo más grande, y Haiku cuesta mucho menos por solicitud.
• Pide resúmenes cortos de vuelta, para que veinte resultados no llenen tu contexto de todos modos.
• Revisa /usage para ver qué proporción de tu uso consume cada tipo de subagente, y así saber cuáles justifican su costo.
• Dale a un subagente personalizado en .claude/agents/ solo tools: Read, Grep, Glob. Ahora es un revisor que no puede editar nada, y ese límite lo aplica Claude Code en lugar de solicitarse en un prompt.

Ese revisor es un archivo corto, .claude/agents/reviewer.md:

---
name: reviewer
description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
tools: Read, Grep, Glob
---
You're reviewing code you didn't write. Compare the changed files against the spec you're given,
check that every requirement is implemented and the listed edge cases have tests,
and report only the gaps that affect correctness. Skip style.

Pídele a Claude have the reviewer compare the rate limiter against SPEC.md y las brechas vuelven a tu sesión, donde Claude puede corregirlas.

Reduce el costo y el contexto

Con una ventana de 1M de tokens en la mayoría de los modelos actuales y la compactación cerca del tope, rara vez te quedarás sin contexto. Aun así, puedes pagar por contexto que no necesitas. Cada solicitud envía la conversación completa, así que una sesión que ha acumulado tres tareas no relacionadas vuelve a leer las tres en cada turno de la cuarta. Eso tiene descuento mientras la caché está activa y precio completo una vez que expira.

/usage es el primer lugar donde mirar. En Pro, Max, Ultra, Team y Enterprise desglosa tu uso por skill, subagente, plugin y servidor MCP. También señala patrones como un contexto largo o fallos frecuentes de caché una vez que alguno supera el 10% de tu uso. A partir de ahí, las soluciones habituales:

• /clear entre tareas no relacionadas. No cuesta nada, y significa que la siguiente tarea no sigue pagando por el historial de la anterior. /clear oauth-migration le pone nombre a la sesión que dejas, para que puedas volver a ella más tarde.
• /compact con un enfoque, como /compact keep the API changes and the test commands. En una sesión larga, /compact es en sí mismo una solicitud grande, ya que lee toda la conversación para resumirla, y más aún una vez que la caché ha expirado.
• Vigila el trabajo en segundo plano: un /loop, la verificación de un objetivo después de cada turno y los propios subagentes de Claude siguen enviando solicitudes mientras no estás escribiendo.

[!NOTE]

La caché de prompts dura aproximadamente una hora con una suscripción y cinco minutos con una clave de API, un proveedor de nube o créditos de uso. Los subagentes obtienen cinco minutos a menos que lo cambies.

Con la caché de una hora, una sesión de más de unos 200K tokens que queda inactiva se compacta poco antes de que la caché expire, así que después del almuerzo continúas desde un resumen. Si no necesitas el historial en absoluto, una sesión nueva sigue costando menos.

Dirige la sesión

[!TIP]

Observa el primer minuto, presiona Esc en cuanto Claude se desvíe y, después de dos correcciones fallidas, ejecuta /clear y escribe un prompt mejor en lugar de una tercera.

Ninguna configuración reemplaza observar el primer minuto e intervenir cuando Claude se dirige a donde no pretendías. Solo hay unos pocos controles para eso, y vale la pena conocerlos de memoria:

• Esc detiene a Claude a mitad de una acción y conserva todo hasta ese punto, para que puedas redirigirlo sin perder trabajo.
• /rewind, o Esc dos veces con el prompt vacío, abre el menú de rebobinado, donde puedes devolver el código, la conversación o ambos a un prompt anterior. Eso hace que sea poco arriesgado probar primero el enfoque más audaz y rebobinar si no funciona. El mismo menú también puede resumir parte de la conversación cuando se ha quedado obsoleta.
• /clear empieza de nuevo. Si has corregido lo mismo dos veces y sigue estando mal, una tercera corrección sobre todo agrega más a una conversación que ya contiene dos intentos fallidos que Claude sigue releyendo. /clear más un prompt nuevo que incorpore lo que aprendiste funciona mejor casi siempre.

[!WARNING]

Los checkpoints cubren los archivos que Claude editó con sus propias herramientas de archivos en tu conversación principal, así que un archivo que solo tocó un comando Bash no se restaura. Funcionan junto con git, no lo reemplazan.

Dos más pequeños: /btw responde una pregunta rápida sin agregar nada al historial. Y para un trabajo que abarca varios días, /rename oauth-migration en la sesión le pone nombre, de modo que claude --resume oauth-migration desde tu shell la retoma más tarde, checkpoints incluidos. claude --continue reanuda la más reciente.

Deja que Claude trabaje sin ti

[!TIP]

Antes de dejar una ejecución desatendida, asegúrate de que sepa cómo se ve el trabajo terminado, pueda verificar su propio trabajo y solo pueda tocar lo que debe. Dale un límite de turnos o de gasto, y haz que una persona apruebe el resultado al final.

Todo lo de esta página importa un poco más cuando no estás presente para detectar errores. Mientras observas, que a Claude le falte algo de contexto no es gran cosa: lo notas en uno o dos mensajes y se lo dices. En una ejecución que iniciaste antes de irte a dormir, nadie se lo dice, y a la mañana siguiente descubres que pasó toda la noche construyendo sobre una suposición equivocada.

Antes de dejar una tarea ejecutándose por su cuenta, vale la pena repasar estas cinco preguntas pensando en esa tarea concreta:

1. ¿Sabe cómo se ve el trabajo terminado? Una condición de objetivo, un archivo de especificación o una prueba fallida que tiene que poner en verde.
2. ¿Puede verificar su propio trabajo? El conjunto de pruebas, un hook Stop, algún tipo de paso de revisión.
3. ¿Qué puede tocar? Reglas de permisos, dontAsk, el sandbox, un worktree, la única rama a la que puede hacer push.
4. ¿Qué lo detiene? --max-turns, --max-budget-usd, un límite de gasto.
5. ¿Adónde va el resultado y quién da el visto bueno? Un PR, un comentario o un resumen, y luego una persona que aprueba la fusión, el despliegue o cualquier otra cosa que no se pueda deshacer.

Una vez en marcha, Claude llevará adelante una tarea larga por su cuenta. Las partes que quedan en tus manos son iniciarla, decidir qué significa "terminado" esta vez y aprobar la fusión al final.

Ejecuta Claude desde un script

claude -p "prompt" se ejecuta una vez y termina, y así es como Claude Code acaba en trabajos de CI, hooks de git y bucles de shell.

En un script casi siempre querrás algunos flags más:

• --bare omite hooks, skills, plugins, servidores MCP y archivos CLAUDE.md, tanto los del repositorio como los de la máquina, para que la ejecución haga lo mismo dondequiera que se ejecute. Tampoco toca nunca tu inicio de sesión de claude.ai: la autenticación proviene de ANTHROPIC_API_KEY, de un apiKeyHelper en el archivo que pasas con --settings o de las credenciales de tu proveedor de nube.
• --append-system-prompt, --mcp-config y --settings pasan explícitamente lo que la ejecución sí necesita. Los hooks que pasas con --settings no se ejecutan con --bare, así que no uses --bare en una ejecución que los necesite.
• --allowedTools aprueba previamente sus herramientas, y --permission-mode dontAsk rechaza cualquier otra cosa que habría pedido aprobación.
• --output-format json te da un único objeto de resultado para analizar, y stream-json con --verbose transmite los eventos a medida que ocurren.

Todo junto, se ve así:

for file in $(cat files.txt); do
  claude --bare -p "Migrate $file to the new logger API and commit. Reply OK or FAIL." \
    --allowedTools "Read,Edit,Bash(git add *),Bash(git commit *)" \
    --permission-mode dontAsk \
    --max-turns 20
done

Cuando una ejecución termina, Claude responde OK o FAIL, y una ejecución que alcanza el límite de turnos sale con un error en su lugar. Pruébalo primero con tres archivos, observa qué sale mal, corrige el prompt y luego ejecuta el resto.

El modo automático también funciona con -p si pasas --permission-mode auto. En una ejecución no interactiva, un bloqueo del clasificador deniega esa acción concreta y Claude continúa, y los bloqueos repetidos no pausan la ejecución como lo hacen en una terminal. Lee cómo se aplican allí los umbrales antes de confiar en ello.

Inicia ejecuciones según un horario o un evento

Una vez que una ejecución está en marcha, Claude puede encargarse del resto por sí mismo. Lo único que no puede hacer es decidir empezar, así que algo tiene que hacerlo: tú, un temporizador o un evento como una verificación de CI fallida o un nuevo PR.

Dentro de una sesión abierta, eso es /loop, que repite un prompt en un intervalo:

/loop 15m check CI on this branch, and if it's red pull the failing job's log, fix it and push

Cada ejecución es otro turno en la misma sesión, así que no dejes uno en marcha en una conversación larga. Para cualquier cosa que deba ocurrir mientras tu portátil está cerrada, /schedule configura una tarea programada en la nube que se ejecuta con un temporizador. Necesita un inicio de sesión de claude.ai en lugar de una clave de API. Puedes agregar un disparador de eventos de GitHub pidiéndoselo a Claude, o un disparador de API en claude.ai/code/routines.

[!WARNING]

Antes de dejar una tarea programada en la nube en ejecución, protege main con una regla de rama de GitHub que la tarea no pueda eludir. Y observa las primeras ejecuciones de cualquier cosa nueva antes de confiar en ella sin supervisión.

Ejecuta sesiones en paralelo

Cuando tienes varios trabajos separados en marcha a la vez, dale a cada uno su propio checkout para que las ediciones no choquen. claude -w feature-auth inicia una sesión en un nuevo worktree, la aplicación de escritorio ejecuta varias de estas una al lado de otra, y las sesiones en la nube las ejecutan en la nube en lugar de en tu máquina.

Un worktree es un checkout nuevo, lo que significa que los archivos ignorados por git como .env no están ahí y las dependencias no están instaladas. Para lo primero, enumera los archivos ignorados por git que necesitas en un .worktreeinclude en la raíz del repositorio (misma sintaxis que .gitignore) y Claude Code los copia en cada worktree que crea:

.env
.env.local
config/dev-credentials.json

Limítalo a archivos pequeños: copia en lugar de enlazar, así que tener node_modules ahí significaría una copia completa por worktree. Para directorios grandes existe el ajuste worktree.symlinkDirectories, o bien mantén el comando de instalación en CLAUDE.md para que Claude lo ejecute cada vez que empiece en un checkout nuevo.

Rara vez tienes que limpiar nada de esto tú mismo:

• Cuando sales de una sesión de worktree sin nombre, Claude Code elimina el worktree si no hay nada en él. Para una sesión con nombre, o una con cambios, te pregunta qué hacer.
• Los worktrees de subagentes desaparecen cuando el subagente termina sin cambios.
• Los worktrees de subagentes y de sesiones en segundo plano que sí quedan se eliminan una vez que superan cleanupPeriodDays y no contienen trabajo.

[!NOTE]

Una ejecución claude -p --worktree es una que limpias tú mismo, ya que termina sin preguntar. Elimínalas con git worktree remove <path> y, si git se niega porque el worktree está bloqueado, primero ejecuta git worktree unlock <path>.

Para un gran cambio mecánico en muchos archivos, /batch migrate every handler to the v2 response helpers divide el trabajo en entre 5 y 30 unidades y te muestra el plan. Una vez que lo apruebas, cada unidad obtiene su propio worktree y abre un PR o informa lo que ocurrió. Desde tu shell, claude agents (todavía en vista previa de investigación) te da una sola pantalla para todo lo que se ejecuta en segundo plano en tu máquina.

Una segunda sesión es también el revisor independiente más fácil que puedes conseguir. Una sesión escribe el limitador de velocidad, otra revisa @src/middleware/rateLimiter.ts sin haber visto cómo se escribía, y tú pegas los hallazgos de vuelta en la primera. Es la misma idea que /code-review, pero eres tú quien lleva los mensajes.

Lo que puedes dejar de hacer

Cada uno de estos fue un buen consejo cuando se escribió. La mayoría eran soluciones alternativas para algo que el modelo todavía no podía hacer de forma fiable, y desde entonces los modelos se han puesto al día. Si algunos siguen siendo hábitos, aquí está por qué es seguro abandonarlos.

Si algún otro consejo de esta página empieza a parecerte trabajo innecesario, probablemente sea señal de que también pertenece a esta tabla.

Recursos relacionados

• Cómo funciona Claude Code: el bucle, las herramientas y lo que se carga al inicio
• Explora la ventana de contexto: qué ocupa espacio en una sesión y cuándo se carga
• Extiende Claude Code: cómo elegir entre skills, hooks, MCP, subagentes y plugins
• Elige un modo de permisos y Configura los permisos
• Gestiona los costos de forma eficaz
• Ejecuta Claude Code mediante programación y Automatiza el trabajo con tareas programadas en la nube
• Para líderes de equipo y administradores: Configura Claude Code para tu organización