← Volver al listado de tecnologías ← Índice de Claude Code

Cap 20: Tips de Productividad

2 de marzo de 2026 Por: Artiko

claude-codetipsproductividadbest-practices

Checklist de configuración inicial

Sobre `/sandbox`: qué hace realmente por defecto

El sandbox corre en macOS (Seatbelt), Linux y WSL2; Windows nativo y WSL1 no están soportados. Por defecto:

Permite escritura solo en el directorio de trabajo y en el $TMPDIR de la sesión.
Permite lectura de todo el equipo, salvo directorios denegados explícitamente.
Si el sandbox no arranca, se emite un warning y los comandos corren sin sandbox: falla abierto. Para que falle cerrado hay que poner sandbox.failIfUnavailable: true.

En aislamiento de red no hay dominios pre-permitidos: el proxy pide aprobación en el primer uso y, desde v2.1.191, un «Yes» permite ese host durante el resto de la sesión. Se pre-permite con sandbox.network.allowedDomains o con reglas allow WebFetch(domain:...).

Sobre commitear `.claude/settings.json`: el gotcha de los scopes

Las reglas de permisos no siguen la precedencia normal de settings: se fusionan entre todos los scopes.

Un deny en cualquier scope bloquea un allow de cualquier otro, incluido --allowedTools.
Orden de evaluación: deny → ask → allow; la primera coincidencia decide.
La especificidad no altera nada: Bash(aws *) en deny bloquea Bash(aws s3 ls) aunque esté en allow.
permissions.allow de un settings de proyecto solo aplica tras aceptar el diálogo de workspace trust (deny y ask no lo requieren).
Desde v2.1.211 las aprobaciones «Yes, don’t ask again» se guardan en .claude/settings.local.json en la raíz del repo git, y ese archivo se carga desde ahí aunque arranques en un subdirectorio.

Regla número uno: dale una forma ejecutable de verificar

Antes que cualquier otro tip: dale a Claude una manera de comprobar su propio trabajo — tests, exit code del build, un linter, un script contra un fixture, un screenshot del navegador. Sin un check, «looks done» es la única señal disponible y el humano termina siendo el bucle de verificación.

Pide evidencia, no aserciones: la salida de los tests, el comando ejecutado y su resultado, el screenshot. «If you can’t verify it, don’t ship it.»

Cuatro niveles para forzarlo, de menos a más determinista:

Pedir el check en el mismo prompt.
Fijarlo como condición de /goal, que un evaluador separado revalida tras cada turno.
Un hook Stop que bloquea el fin del turno. Ojo: Claude Code lo anula tras 8 bloqueos consecutivos, así que diseñar un gate asumiendo bloqueo indefinido es un antipatrón.
Un subagente verificador o un workflow dinámico que intente refutar el resultado.

flowchart LR
  A[Prompt con el check] --> B["/goal revalidado por evaluador"]
  B --> C["Hook Stop determinista"]
  C --> D[Subagente verificador]

CLAUDE.md menor a 200 líneas

CLAUDE.md se concatena en cada sesión. El objetivo documentado es menos de 200 líneas por archivo, y el criterio de poda se aplica línea por línea: «Would removing this cause Claude to make mistakes?». Si la respuesta es no, se borra.

La advertencia canónica es directa: «Bloated CLAUDE.md files cause Claude to ignore your actual instructions!». El diagnóstico correspondiente: si Claude sigue haciendo algo que tienes prohibido por escrito, lo más probable es que el archivo sea demasiado largo y la regla se esté perdiendo.

# CLAUDE.md
## Comandos
bun dev / bun test / bun build

## Stack
Astro 5 + React 19 + TypeScript strict + Tailwind

## Convenciones
- Commits: feat: / fix: / refactor:
- Archivos `< 150 líneas`
- Arquitectura hexagonal

Qué incluir: comandos bash no adivinables, reglas de estilo que difieren del default, instrucciones de testing, etiqueta del repo, decisiones arquitectónicas y gotchas del entorno. Qué excluir: lo deducible leyendo el código, convenciones estándar del lenguaje, documentación de API detallada (mejor enlazarla), descripciones archivo por archivo y obviedades tipo «write clean code».

Alternativa modular: `.claude/rules/`

En vez de un CLAUDE.md gigante, usa .claude/rules/*.md (y ~/.claude/rules/): markdown modular con frontmatter paths: (globs) que solo se carga al tocar archivos que matcheen. Las reglas sin paths cargan al inicio, con la misma prioridad que .claude/CLAUDE.md.

<!-- .claude/rules/frontend.md -->
---
paths:
  - "src/components/**"
  - "src/pages/**"
---

- Componentes en TSX, sin default export.
- Estilos solo con clases Tailwind.

Nota importante: dividir con imports @ruta organiza pero no reduce contexto — los imports se expanden al inicio (máximo 4 niveles de profundidad).

Auto memory: el sistema complementario

Además de CLAUDE.md existe la auto memory, activada por defecto: Claude escribe sus propias notas en ~/.claude/projects/<project>/memory/, con un MEMORY.md índice del que se cargan las primeras 200 líneas o 25KB por sesión; los archivos de tema se leen bajo demanda. Se navega con /memory y se desactiva con autoMemoryEnabled: false.

Para saber qué se cargó de verdad en la sesión actual, /context lista los memory files efectivos.

Enrutamiento: dónde va cada instrucción

Tipo de instrucción	Dónde va
Aplica siempre, en cada turno	CLAUDE.md
Conocimiento de dominio o flujo ocasional	Skill (carga bajo demanda)
Debe ocurrir sin excepción	Hook (CLAUDE.md es advisory, no forzado)

Gestión de contexto: el toolkit completo

La restricción que sostiene toda la guía: «Claude’s context window fills up fast, and performance degrades as it fills». El contexto es el recurso más importante que gestionas.

Herramienta	Para qué
`/clear`	Entre tareas no relacionadas
`/compact <instrucciones>`	Compactación dirigida: le dices qué preservar
Esc	Interrumpir preservando el contexto
Esc+Esc o `/rewind`	Volver atrás en código y/o conversación
`/btw`	Preguntas laterales cuya respuesta no entra al historial

También puedes bajar el umbral de auto-compact para no llegar a la zona en la que Claude ya perdió información:

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 claude

Commits frecuentes (y por qué `/rewind` no los reemplaza)

Cada cambio funcional = un commit. Esto proporciona historial claro, revert fácil y mejor colaboración con agent teams.

/rewind ayuda, pero tiene límites concretos:

Se guarda un snapshot antes de cada prompt del usuario.
Se conservan los 100 checkpoints más recientes por sesión.
Solo cubre ediciones hechas con las herramientas de edición: los cambios producidos por comandos bash o por herramientas externas no se restauran. Por eso el commit sigue siendo necesario.

/rewind (o doble Esc con el input vacío) ofrece cinco acciones, incluidas Summarize from here y Summarize up to here. Desde v2.1.191 puede además reanudar la conversación anterior a un /clear ejecutado en el mismo proceso.

Feature-specific sub-agents

En lugar de agentes genéricos (“code-reviewer”, “test-writer”), crea agentes específicos por feature:

<!-- .claude/agents/auth-specialist.md -->
---
name: auth-specialist
description: Especialista en el módulo de autenticación (OAuth2, JWT, RBAC)
skills: ["security-rules", "auth-patterns"]
tools: ["Read", "Edit", "Bash", "Grep"]
disallowedTools: ["WebFetch"]
model: inherit
effort: high
---

Especialista en el módulo de autenticación.
Conoce OAuth2, JWT, sesiones y RBAC.

El default de model es inherit (acepta también el alias fable). El frontmatter admite bastante más que name/description/tools/model: disallowedTools, permissionMode, maxTurns, mcpServers, hooks, memory, background, effort, isolation e initialPrompt.

Comportamiento actual que conviene tener presente:

Desde v2.1.198 los subagentes corren en background por defecto y heredan la configuración de extended thinking de la sesión principal; /agents ya no abre el asistente interactivo.
En v2.1.217 no generan subagentes anidados por defecto y hay un tope de 20 concurrentes.

Advertencia clave: los subagentes NO son una frontera de seguridad — «subagents run in the same process as the parent session and use the same sandbox configuration». Su valor real es el aislamiento de contexto y la restricción de herramientas, no el confinamiento.

Plan mode primero

Para tareas no triviales, empieza en plan mode. Tres formas de activarlo:

claude --permission-mode plan

Shift+Tab cicla los modos hasta plan.
/plan <prompt> aplica plan mode a un único prompt.

Mientras estás en plan mode, la barra de estado muestra ⏸ plan mode on. Antes de ejecutar, Ctrl+G abre el plan en tu editor para corregirlo a mano — suele salir más barato que discutirlo en el chat.

Al aprobar el plan aparecen cuatro opciones: Yes, and use auto mode / Yes, manually approve edits / No, refine with Ultraplan on Claude Code on the web / No, keep planning. Aceptar un plan renombra la sesión automáticamente.

Plan mode tiene coste. Para un typo, añadir un log o renombrar una variable se pide directo: «If you could describe the diff in one sentence, skip the plan.»

Permisos: auto mode, allowlists y sandbox

La guía actual no recomienda saltarse los permisos. Nombra tres mecanismos:

Auto mode — el principal para trabajo autónomo.
Allowlists vía /permissions.
Sandboxing OS-level vía /sandbox.

Ejemplo canónico de trabajo autónomo:

claude --permission-mode auto -p "fix all lint errors"

Auto mode usa un modelo clasificador aparte que revisa cada acción antes de ejecutarla. Desde v2.1.210 ese clasificador corre en Claude Sonnet 5 (no en el modelo de la sesión) y sus tokens se facturan. Está generalizado en todos los planes.

Tiene frenos no configurables: 3 bloqueos seguidos o 20 en total pausan auto mode y devuelven los prompts al usuario. Con -p, los bloqueos repetidos abortan la sesión, porque no hay nadie a quien preguntar.

Para las allowlists, dos detalles que rompen configuraciones heredadas:

Desde v2.1.210 solo Edit(path) y Read(path) se evalúan en los chequeos de permisos de archivo. Write(path), NotebookEdit(path) y Glob(path) se aceptan pero nunca coinciden y emiten warning.
Desde v2.1.214 un patrón de un solo segmento como Edit(src/**) coincide solo con src en el directorio de trabajo. Para cualquier profundidad hay que escribir Edit(**/src/**).

{
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep",
      "Bash(git *)", "Bash(bun *)",
      "Edit(**/src/**)"
    ]
  }
}

Variables de entorno útiles

Variable	Valor	Efecto
`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`	`50`	Compactar al 50%
`BASH_MAX_TIMEOUT_MS`	`300000`	5 min timeout para bash
`MAX_MCP_OUTPUT_TOKENS`	`25000`	Límite de salida de herramientas MCP
`CLAUDE_CODE_TASK_LIST_ID`	`mi-proyecto`	Tareas compartidas entre sesiones

Esfuerzo: `/effort`, no una variable

El nivel de esfuerzo no se controla con una variable de entorno. Se ajusta con /effort dentro de la sesión o con --effort al arrancar, y los niveles son low | medium | high | xhigh | max en Fable 5, Sonnet 5, Opus 4.8 y Opus 4.7. El default es high.

El menú de /effort incluye además ultracode: no es un nivel del modelo, sino un ajuste de Claude Code que envía xhigh y hace que Claude orqueste dynamic workflows; aplica solo a la sesión actual.

En la API el equivalente es output_config: {effort: "..."}, ya GA y sin cabecera beta.

Thinking: ya no se presupuesta en tokens

El antiguo thinking: {type:"enabled", budget_tokens:N} está eliminado en Fable 5, Opus 4.8, Opus 4.7 y Sonnet 5 (devuelve 400); se sustituye por thinking: {type:"adaptive"}. Solo Haiku 4.5 (y, deprecados, Opus 4.6 y Sonnet 4.6) mantienen budget_tokens. Sonnet 5 trae thinking adaptativo activado por defecto.

Output style según contexto

Los estilos integrados son Default, Proactive, Explanatory y Learning.

Situación	Estilo
Codebase nuevo	`Explanatory` — explica cada paso
Aprendizaje	`Learning` — enseña mientras trabaja
Trabajo autónomo con iniciativa	`Proactive`
Producción	Custom conciso — solo lo necesario

Cómo se cambian hoy: /output-style fue deprecado en v2.1.73 y eliminado en v2.1.91. Se usa /config o se edita el campo outputStyle en settings, y el cambio requiere /clear o una sesión nueva. Los output styles no aplican a subagentes (sí a forks).

Model aliases

Alias vigentes: default, best, fable, sonnet, opus, haiku, sonnet[1m], opus[1m], opusplan.

Tarea	Modelo
Exploración rápida	`haiku`
Desarrollo diario	`sonnet` (Sonnet 5)
Arquitectura compleja	`opus` (Opus 4.8)
Planificar + ejecutar	`opusplan` (opus al planificar, sonnet al ejecutar)
Tareas largas y autónomas	`fable`

sonnet apunta a Sonnet 5, que ya tiene ventana nativa de 1M tokens y thinking adaptativo por defecto: para codebases grandes ya no hace falta pedir sonnet[1m] como caso aparte.

Claude Fable 5 es el modelo más capaz disponible en Claude Code para tareas largas y autónomas. No es el default: se elige con /model fable y requiere v2.1.170+.

Skills y comandos son el mismo sistema

Los comandos personalizados se fusionaron con las skills: .claude/commands/deploy.md y .claude/skills/deploy/SKILL.md generan ambos /deploy y comparten el mismo frontmatter. Ante colisión de nombre gana la skill, y la URL /docs/en/slash-commands sirve hoy la página «Extend Claude with skills».

En la práctica: no pienses en “crear un command” versus “crear una skill”. Es una sola decisión de formato — archivo suelto en commands/ para algo corto, directorio en skills/ cuando necesitas archivos de apoyo y divulgación progresiva.

Terminal recomendado

Usa un emulador de terminal dedicado (iTerm2, Ghostty, Alacritty) en lugar del terminal integrado del IDE. El terminal del IDE puede tener problemas con sesiones largas.

Workflow diario recomendado

El workflow canónico tiene cuatro fases, no tres:

flowchart LR
  E[Explore] --> P[Plan]
  P --> I[Implement]
  I --> C[Commit]

Explore — en plan mode, leer sin editar.
Plan — plan detallado; Ctrl+G para editarlo antes de aprobarlo.
Implement — salir de plan mode y codificar verificando contra el plan.
Commit — commit descriptivo y PR.

Sáltatelo cuando el diff cabe en una frase.

Aplicado al día:

Mañana: claude -c para continuar la sesión de ayer.
Nueva feature: Explore → Plan → Implement → Commit.
Bug fix: “Reproduce el bug, investiga la causa, propón soluciones”.
Review: revisión adversarial del diff antes de dar por terminado.
Final del día: commitear trabajo en progreso.

Revisión adversarial del diff

Antes de cerrar, un subagente en contexto fresco revisa el diff contra el plan, o usas la skill incluida /code-review. También funciona el patrón Writer/Reviewer en dos sesiones separadas: un contexto fresco no está sesgado hacia el código que acaba de escribir.

Con una advertencia: «A reviewer prompted to find gaps will usually report some, even when the work is sound… Chasing every finding leads to over-engineering». Indícale explícitamente que solo marque gaps que afecten corrección o requisitos declarados.

Antipatrones a evitar

Antipatrón	Mejor alternativa
Trust-then-verify gap: aceptar «listo» sin comprobar	Check ejecutable + evidencia en el mismo prompt
Kitchen sink session: mezclar tareas no relacionadas	`/clear` entre tareas
Correcting over and over: corregir lo mismo tres veces	`/clear` tras dos correcciones y reescribir el prompt inicial
Over-specified CLAUDE.md: `> 200 líneas`	Podar, mover a skills o convertir en hook
Infinite exploration: investigar sin acotar	Acotar el alcance o delegar en subagentes
`--dangerously-skip-permissions`	Auto mode, allowlists vía `/permissions`, `/sandbox`
`Edit(src/**)` esperando cualquier profundidad	`Edit(/src/)`
`Write(...)` en reglas de permisos	`Edit(...)` (Write nunca coincide desde v2.1.210)
Agentes genéricos	Agentes por feature con skills
No compactar	`/clear`, `/compact <instrucciones>`, `/btw`
No commitear	Commit después de cada paso
Un solo prompt gigante	Explore → Plan → Implement → Commit
Esperar que Claude adivine	Instrucciones específicas en CLAUDE.md

La regla de las dos correcciones

Si corregiste a Claude más de dos veces sobre lo mismo, el contexto ya está contaminado con enfoques fallidos: /clear y reescribe el prompt inicial. «A clean session with a better prompt almost always outperforms a long session with accumulated corrections.»

Resumen: 10 reglas de oro

Dale una forma ejecutable de verificar y pide evidencia, no aserciones
CLAUDE.md conciso (< 200 líneas), podado línea por línea
Enrutar: CLAUDE.md siempre / skills ocasional / hooks sin excepción
Gestionar contexto activamente (/clear, /compact, /btw, /rewind)
Commitear después de cada cambio funcional (/rewind no cubre cambios por bash)
Plan mode antes de implementar, salvo que el diff quepa en una frase
Auto mode, allowlists y /sandbox, nunca bypass
Sub-agentes específicos por feature: aislamiento de contexto, no de seguridad
Revisión adversarial del diff antes de cerrar
Explore → Plan → Implement → Commit para tareas complejas

Siguiente: Prompt Engineering & Structured Output — Volver al índice