Buenas prácticas de Claude Code: checklist práctica

Las buenas prácticas de Claude Code que más importan son sencillas: mantén CLAUDE.md corto, planifica antes de los cambios grandes, dale a Claude una comprobación que pueda ejecutar, trabaja con tareas pequeñas, limpia el contexto entre ellas, impón las reglas estrictas con configuración en lugar de con texto y ejecuta el trabajo en paralelo en git worktrees separados. Después, lee el diff y haz commits a menudo.

Esta página es una checklist. Cada punto dice qué hacer, muestra el comando o la configuración y enlaza a una guía más detallada cuando existe. Todo sigue la documentación oficial de Claude Code a octubre de 2026; los detalles que cambian entre versiones están marcados.

La checklist de un vistazo

1. Mantén CLAUDE.md corto y factual

Claude Code carga CLAUDE.md en cada sesión, así que cada línea del archivo ocupa un poco de atención en cada tarea, sea relevante o no. El archivo funciona mejor cuando solo contiene lo que Claude no puede deducir del código:

• Cómo confirmar el trabajo en este repo: los comandos exactos de test, typecheck y lint, y cómo ejecutar un solo archivo de tests.
• Los sitios donde el código engaña: un patrón antiguo que el código nuevo no debe copiar, un directorio que parece muerto pero no lo está.
• Las decisiones que no están en el repo: qué helper de errores eligió el equipo, cómo funcionan los despliegues.
• Todo lo que hayas tenido que corregir dos veces.

Un archivo que pasa esa prueba se mantiene pequeño:

# 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

No hace falta describir tu arquitectura ni la estructura de carpetas; Claude lee el repo. /init escribe un primer borrador y, a partir de ahí, el trabajo consiste sobre todo en borrar. La guía oficial de memoria recomienda no pasar de 200 líneas. /context confirma que el archivo se cargó y /doctor sugiere recortes. Las preferencias personales van en CLAUDE.local.md, que añades a .gitignore.

Dos herramientas relacionadas mantienen ligero el archivo principal. Las reglas que solo importan en una zona van en .claude/rules/*.md con un filtro paths:, de modo que solo se cargan cuando Claude trabaja allí. Los procedimientos del equipo, como una checklist de release, van en una skill en .claude/skills/<name>/SKILL.md; Claude solo ve su nombre y su descripción hasta que necesita el texto completo. La guía completa está en Cómo escribir CLAUDE.md y AGENTS.md.

Si Claude sigue ignorando una línea, escribir IMPORTANT en mayúsculas rara vez ayuda. O el archivo es demasiado largo, o la línea es una regla sin excepciones, que debería ir en un hook (mira el punto 6).

2. Escribe prompts que digan dónde, qué y cómo comprobarlo

Un prompt vago obliga a Claude a adivinar. Uno concreto nombra el síntoma, dónde mirar y cómo demostrar el arreglo:

Los usuarios informan de que el inicio de sesión falla después de que caduca la sesión. Revisa la renovación del token en src/auth/, escribe un test que falle y reproduzca el problema y luego arréglalo.

Señala archivos con @, pega capturas de pantalla y pasa los logs por pipe en lugar de describirlos. Cuando todavía no sabes lo que quieres, deja que Claude te entreviste primero:

Quiero añadir rate limiting a la API pública, pero todavía no lo he pensado a fondo. Entrevístame hasta que puedas escribir la especificación y luego escríbela en SPEC.md.

Después abre una sesión nueva que construya a partir de SPEC.md. La implementación empieza con un contexto limpio y una definición escrita de “terminado”, y la especificación es lo que el revisor usará después para comparar. Hay más patrones de prompts en Cómo escribir prompts para agentes de programación con IA.

Dos hábitos que puedes abandonar: frases como “think hard” no aumentan el esfuerzo de razonamiento (usa /effort high o pon ultrathink en un prompt concreto), y el énfasis EN MAYÚSCULAS sobre todo hace que Claude aplique una regla en exceso.

3. Planifica antes de los cambios de varios pasos

Para todo lo que toque varios archivos, separa el pensar del editar. Plan mode deja que Claude lea el código y proponga un plan sin cambiar nada. Puedes entrar en él con Shift+Tab o arrancar una sesión directamente en ese modo:

claude --permission-mode plan

Lee el plan, corrígelo y solo entonces deja que Claude implemente. Una suposición errónea detectada en el plan cuesta un mensaje; detectada en el diff, cuesta reescribir. Los arreglos pequeños y obvios no necesitan plan. Los detalles, incluido cómo editar un plan antes de aprobarlo, están en Plan mode de Claude Code.

4. Dale a Claude una comprobación que pueda ejecutar

Este es el hábito que más rinde. Claude solo puede saber que ha terminado si tiene algo que ejecutar: una suite de tests, un typecheck, un comando de lint, el código de salida de un build, un script que compara la salida con un fixture. Si tu repo tiene uno, la línea más útil de CLAUDE.md es el comando que lo ejecuta.

Tú eliges con qué rigor se aplica la comprobación:

• En el prompt. “Ejecuta después los tests de auth y sigue hasta que pasen.” Funciona para cualquier tarea sin configurar nada.
• Como objetivo. /goal all tests in tests/auth pass and lint is clean fija una condición que un modelo aparte comprueba después de cada turno. Es lo más útil en ejecuciones largas.
• Como hook Stop. Claude Code ejecuta tu script cuando Claude intenta terminar su turno y lo devuelve al trabajo si el script sale con código 2.
• Con un revisor independiente. /code-review revisa el diff en un subagente nuevo que nunca vio tu conversación.

La versión con hook Stop de “el typecheck debe pasar” vive en .claude/settings.json:

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

Stderr vuelve a Claude como el motivo por el que todavía no puede parar, y por eso la salida del compilador se redirige allí. Si el hook bloquea ocho paradas seguidas sin ninguna llamada a herramientas entre medias, Claude Code termina el turno de todos modos; CLAUDE_CODE_STOP_HOOK_BLOCK_CAP sube ese límite.

Elijas lo que elijas, pide pruebas: el comando que ejecutó Claude y su salida. “Todos los tests pasan”, sin más, te dice poco. Tras un cambio de interfaz, /verify hace que Claude compile y ejecute la app y mire el resultado.

5. Mantén las tareas pequeñas y el contexto limpio

Una sesión, un objetivo. Una conversación que ha acumulado tres tareas no relacionadas las vuelve a enviar todas en cada turno de la cuarta, lo que cuesta más y hace que las respuestas estén menos enfocadas.

• /clear entre tareas no relacionadas. /clear oauth-migration además pone nombre a la sesión que dejas para que puedas volver a ella.
• /compact keep the API changes and the test commands acorta una sesión larga conservando lo importante. En una sesión larga, /compact es en sí una petición grande.
• /usage muestra en qué se va tu uso, incluido por subagente, skill y servidor MCP en los planes de suscripción.

A octubre de 2026, la mayoría de los modelos actuales tienen una ventana de 1M de tokens y la compactación se ejecuta sola, así que quedarse sin contexto es raro. Limpiar tiene que ver con el enfoque y el coste, no con sobrevivir. La caché de prompts dura aproximadamente una hora con una suscripción y unos cinco minutos con una API key, así que una sesión que estuvo parada durante la comida sale más cara de continuar que una nueva. La mecánica está en Gestión del contexto en Claude Code.

6. Pon en la configuración las reglas que no pueden doblarse

CLAUDE.md contiene pautas, y Claude puede decidir que una pauta no aplica. Para las pocas reglas en las que “casi siempre” no basta, usa controles que aplica el propio Claude Code.

Reglas de permisos. Permite lo que es seguro y frecuente, pregunta por lo arriesgado, deniega lo que nunca debe ocurrir:

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

Las reglas deny se aplican en todos los modos de permisos, y la regla Read también atrapa los comandos de shell habituales que leen archivos, como cat .env. No atrapa un script que abra el archivo, así que para el trabajo sensible en seguridad activa además el sandbox con /sandbox, que confina los comandos de shell a nivel del sistema operativo en macOS, Linux y WSL2.

Hooks. Un formateador que se ejecuta después de cada edición ya no depende de que Claude se acuerde:

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

Usa hooks solo para reglas sin ninguna excepción; “prefiere exports con nombre” se queda en CLAUDE.md. La guía de hooks de Claude Code cubre cada evento y cada código de salida.

Modos de permisos. A octubre de 2026, las sesiones interactivas nuevas empiezan en modo auto, donde un clasificador revisa las acciones arriesgadas en lugar de preguntarte por cada una. Funciona bien, pero es un juicio, así que tus reglas de “nunca” siguen perteneciendo a las reglas deny y los hooks. Si prefieres aprobar cada paso, Shift+Tab pasa a Manual, o arranca con claude --permission-mode manual. Cuando Manual pregunta demasiado, /fewer-permission-prompts añade tus comandos de solo lectura habituales a una lista de permitidos. Por qué saltarse los permisos por completo es un mal trato se explica en Saltarse los permisos en Claude Code.

7. Corrige pronto y reinicia en lugar de discutir

Observa el primer minuto de cada tarea. Los controles son pocos:

• Esc detiene a Claude en mitad de una acción y conserva todo lo hecho hasta ese momento, para que puedas redirigirlo.
• /rewind, o Esc dos veces con el prompt vacío, devuelve el código, la conversación o ambos a un prompt anterior.
• /clear empieza de cero. Tras dos correcciones fallidas, una tercera sobre todo añade otro intento fallido que Claude tiene que volver a leer. Limpia y escribe un único prompt mejor que incluya lo que has aprendido.

Los checkpoints cubren los archivos que Claude cambió con sus propias herramientas de edición; un archivo que solo tocó un comando Bash no se restaura. Funcionan junto a git, no en su lugar. Para trabajo que dura varios días, /rename oauth-migration pone nombre a la sesión y claude --resume oauth-migration la retoma más tarde.

8. Usa subagentes con intención

Claude Code ya delega por su cuenta: las búsquedas amplias van al agente Explore integrado y los subagentes se ejecutan en segundo plano por defecto. Cada subagente envía sus propias peticiones, así que cuesta tokens, y no hace más inteligente una respuesta. Úsalos para:

• Trabajos independientes que pueden ejecutarse al mismo tiempo.
• Mantener fuera de la conversación principal salidas largas, como una ejecución completa de tests.
• Un revisor que no ha visto cómo se escribió el código.
• Una tarea que debería tener menos herramientas que la sesión principal.

Un revisor de solo lectura es un archivo corto en .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.

Para trabajos sencillos, como reunir los archivos que importan un módulo, añade model: haiku a la definición. Después pide:

Haz que el revisor compare el rate limiter con SPEC.md.

Hay más patrones en Subagentes de Claude Code.

9. Ejecuta el trabajo en paralelo en worktrees

Dos sesiones editando el mismo checkout se sobrescriben entre sí. Da a cada una su propio git worktree:

claude -w feature-auth

Un worktree es un checkout nuevo, así que los archivos ignorados por git como .env no están y las dependencias no están instaladas. Lista los archivos pequeños ignorados por git en .worktreeinclude, en la raíz del repo, y Claude Code los copia en cada worktree que crea:

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

No pongas node_modules ahí; se copia en lugar de enlazarse. Mejor deja el comando de instalación en CLAUDE.md, o usa el ajuste worktree.symlinkDirectories. Cuando sales de una sesión de worktree sin nombre y sin cambios, Claude Code la elimina; si no, te pregunta. Para un cambio mecánico grande, /batch divide el trabajo en unidades, ejecuta cada una en su propio worktree y abre un PR por unidad. Más en Git worktrees para agentes en paralelo.

10. Lee el diff, haz commits pequeños y el push hazlo tú

El agente escribe; tú apruebas. Antes de aceptar un turno, lee git diff, no el resumen. Haz commit después de cada paso que funcione, para que un mal paso siguiente esté a un git reset de distancia. Deja los push, los merges y los despliegues en manos de una persona: la regla ask sobre git push * de más arriba hace exactamente eso. Una segunda sesión que revise @src/middleware/rateLimiter.ts sin haber visto cómo se escribía es el revisor independiente más barato que tienes.

Extra: antes de dejar a Claude sin supervisión

La documentación oficial enumera cinco preguntas para cualquier ejecución que nadie está mirando. Son un buen control final:

1. ¿Sabe cómo es “terminado”? Un objetivo, un archivo de especificación, un test que falla.
2. ¿Puede comprobar su propio trabajo? Tests, un hook Stop, un paso de revisión.
3. ¿Qué puede tocar? Reglas de permisos, dontAsk, el sandbox, un worktree.
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 y una persona que aprueba el merge.

Para ejecuciones con scripts y en CI, consulta Modo headless de Claude Code.

Cómo hacerlo con AgentVera

La mayor parte de esta checklist es cuestión de disciplina; AgentVera facilita algunos puntos cuando ejecutas más de una sesión. Cada panel del workspace es la terminal real de Claude Code, así que Shift+Tab, plan mode, los hooks y tu CLAUDE.md funcionan como siempre. Puedes crear un worktree por agente desde el panel de Git, y la coordinación de agentes avisa cuando dos agentes editan el mismo archivo.

Para el punto 4, la revisión de código automática hace que un modelo de Claude que tú eliges revise los cambios de cada turno y liste los hallazgos con su gravedad y archivo:línea, y puede devolvérselos al agente. Verify (Pro y Team) convierte tu mensaje en criterios de aceptación y hace que un verificador aparte los compruebe con pruebas cuando termina el turno. Para el punto 7, los checkpoints guardan una instantánea de cada turno en una ref oculta de git y conservan los últimos 60 por agente. La cuadrícula, los worktrees, la revisión de código y los checkpoints están en el plan gratuito; descarga AgentVera para probarlos.

Para terminar

Si solo adoptas tres puntos, que sean estos: un CLAUDE.md corto con tus comandos reales, una comprobación que Claude ejecuta antes de decir “terminado” y /clear entre tareas. Añade reglas deny y hooks para lo que nunca debe ocurrir, worktrees cuando ejecutes sesiones en paralelo, y guárdate para ti la revisión final y el push.