Buenas prácticas de Claude Code: la versión corta

Según la documentación de Anthropic, en la mayoría de los casos tu primera petición normal en una sesión nueva ya hace lo correcto. Preparar cosas compensa cuando tu proyecto tiene algo que Claude no puede ver solo con el código: un proceso de despliegue que está en la cabeza de alguien, un archivo que nunca debe leer, una comprobación que tiene que pasar, un presupuesto. Esta página es la versión corta, con enlaces a las guías largas.

Cuando una sesión sale mal, casi siempre es una de cuatro cosas

1. Claude construyó algo distinto de lo que tenías en mente, o redescubre el mismo dato en cada sesión. Le falta información que no puede sacar del repositorio.
2. Dijo que había terminado y no era verdad, normalmente porque no tenía forma de comprobar su propio trabajo.
3. Hizo algo que nunca debe pasar, o se saltó un paso que siempre debe darse. Una petición sola no garantiza ninguna de las dos cosas.
4. Lo hizo bien, pero costó más tiempo, tokens o avisos de permisos de lo que valía la tarea.

Dos tipos de instrucción

Todo lo que le dices a Claude Code es de uno de dos tipos. Decide Claude: tu petición, CLAUDE.md, una skill. Suele seguirlas, pero nada lo garantiza. Lo hace cumplir Claude Code: un hook, una regla de denegación, un ajuste gestionado. Se aplican siempre, decida lo que decida el modelo. Casi siempre quieres que decida Claude. Deja el tipo obligatorio para reglas sin excepciones. Si sigues añadiendo énfasis a una línea de CLAUDE.md y Claude la sigue saltando, según la documentación esa línea probablemente es un hook. Y al revés: un hook que solo impone una preferencia sobra.

1. Dile a Claude lo que no puede ver

Claude lee bien tu código, así que escribe solo lo que no puede encontrar, o lo que perdería tiempo en redescubrir en cada sesión. Una prueba antes de escribir nada: ¿lo encontraría leyendo el código y de verdad iría a mirar? Si las dos respuestas son sí, déjalo fuera.

• Sé concreto en la petición. Nombra el archivo, describe el síntoma, di cómo se ve «arreglado». «Arregla el error de exportar» pasa a ser «el botón de exportar no hace nada con informes de más de 1.000 filas; el controlador está en src/export/; escribe primero un test que falle y luego arréglalo».
• Entrega las cosas en vez de describirlas. Escribe @ y una ruta para incluir un archivo, pega una captura, o pasa la salida por tubería: cat error.log | claude -p "qué está pasando aquí".
• Si aún no sabes lo que quieres, pídele a Claude que te entreviste hasta poder escribir la especificación, y que la guarde en un archivo como SPEC.md. Luego construye desde ese archivo en una sesión nueva.
• Mantén CLAUDE.md corto. Cada línea gasta un poco de atención en cada tarea. Buen contenido: los comandos exactos de tests, comprobación de tipos y lint, los sitios donde el código engaña, las decisiones que no están en el repositorio, lo que has tenido que corregir dos veces. /init escribe uno de partida; el trabajo es después sobre todo borrar líneas. Las preferencias personales van en CLAUDE.local.md, fuera de git.
• Limita las reglas a una parte del código con un archivo en .claude/rules/ con un filtro paths:, para que solo se cargue cuando Claude trabaje ahí.
• Los procedimientos del equipo, en skills. Una lista de pasos de publicación dentro de una skill no pesa en las tareas ajenas como lo haría en CLAUDE.md. Para un flujo con efectos secundarios, añade disable-model-invocation: true y solo se ejecuta cuando tú lo escribes.
• Conecta lo que vive en otro sitio. Una herramienta de línea de comandos en la que ya has iniciado sesión (como gh) suele ser la entrada más fácil; si no, añade un servidor MCP. Los servidores añaden los nombres de sus herramientas al contexto aunque no los uses, así que desactiva los que no necesites en /mcp.

# Commands
- Run one test file: npm test -- path/to/file.test.js
- Typecheck: npx tsc --noEmit

# Gotchas
- src/legacy/ is still live, but do not copy its patterns into new code
- Integration tests need DATABASE_URL, see .env.example

Mira la guía de memoria y cómo escribir una skill.

2. Dale a Claude una comprobación que ejecutar

Claude para cuando el trabajo parece terminado. Si no tiene nada que ejecutar que responda «pasa» o «falla», «parece terminado» es lo único que tiene, y el test eres tú. Dale un archivo de tests, el código de salida de una compilación, un linter, o un script que compare la salida con un archivo esperado, y podrá hacer un cambio, ejecutar la comprobación, leer lo que falló y arreglarlo. Si tu repositorio ya tiene una, la línea más útil de CLAUDE.md es el comando que la ejecuta.

Tú eliges lo estricto que quieres ser:

• En la petición: «ejecuta después los tests de autenticación y sigue hasta que pasen». Claude decide cuándo está satisfecho.
• Con un objetivo: las versiones recientes tienen un comando /goal que fija una condición que otro modelo comprueba tras cada turno. Importa sobre todo en ejecuciones largas sin supervisión.
• Con un hook Stop: tu script se ejecuta cuando Claude intenta terminar y lo devuelve al trabajo si el script sale con código 2. Esto sí lo hace cumplir Claude Code. Tras varios bloqueos seguidos deja que el turno acabe, así que no puede quedarse en bucle para siempre.
• Con un revisor nuevo: una segunda sesión, o una revisión en un subagente que no vio la conversación, no se deja influir por el razonamiento que produjo el código. Dile qué comprobar y que se salte el estilo, o siempre encontrará algo.

Elijas lo que elijas, pide pruebas: el comando que ejecutó y su salida. «Todos los tests pasan» a secas dice poco.

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

Eso va en .claude/settings.json. La salida del compilador se redirige a stderr porque es lo que recibe Claude como motivo de que aún no puede terminar. Más en tres hooks para pegar.

3. Haz cumplir las reglas que no admiten excepciones

«Nunca leas .env», «ejecuta siempre el formateador», «no toques la carpeta de migraciones»: Claude las seguirá casi siempre. Cuando «casi» no basta, sácalas de CLAUDE.md y llévalas a una configuración que aplique Claude Code por sí mismo.

• Los hooks ejecutan tu comando en puntos fijos: antes o después de una llamada a una herramienta, cuando Claude intenta parar, al empezar la sesión. Un hook PostToolUse con el patrón Edit|Write puede ejecutar tu formateador tras cada edición, se acuerde Claude de la regla o no. Para cumplimiento real usa un hook de comando o HTTP; uno que pide a otro modelo que decida no es determinista.
• Las reglas de denegación valen en todos los modos de permisos. "deny": ["Read(./.env)", "Read(./secrets/**)"] en tus ajustes bloquea la herramienta Read y los comandos habituales de lectura de archivos como cat .env. Las reglas casan con llamadas a herramientas, no con intenciones: un script que abre el archivo no se detecta, y una denegación de dominio para descargas web no hace nada contra curl si el sandbox no está activo.
• El sandbox (/sandbox) limita el acceso a archivos y red a nivel de sistema operativo. La documentación indica macOS, Linux y WSL2.
• El modo automático es un clasificador, un modelo que juzga cada acción, no una regla dura. Pon tus «nunca» en reglas de denegación o en hooks.

Dónde vive una regla decide a quién se aplica: .claude/settings.local.json y ~/.claude/settings.json son solo tuyos, .claude/settings.json del repositorio se aplica a todos los que trabajan ahí (sus reglas de permitir y sus hooks esperan a que cada persona acepte la carpeta), y los ajustes gestionados pertenecen a una organización. Mantén pequeño el conjunto obligatorio; cada hook y regla de denegación saltará alguna vez cuando no debe, y alguien tiene que mantenerlo. Mira un archivo de permisos de partida, los modos de permisos y qué archivo de ajustes manda.

4. Dirige la sesión y controla el gasto

• Vigila el primer minuto y pulsa Esc en cuanto Claude se desvíe. Se detiene a mitad de acción y conserva todo hasta ese punto.
• /rewind (o Esc dos veces con la entrada vacía) devuelve el código, la conversación o ambos a una petición anterior, así que probar el enfoque más atrevido tiene poco riesgo. Los puntos de control cubren los archivos editados con las herramientas de archivos de Claude, no los que solo tocó un comando de shell, y funcionan junto a git, no en su lugar.
• Tras dos correcciones fallidas, /clear y escribe una petición mejor que incluya lo que aprendiste. Una tercera corrección sobre todo añade más a una conversación que ya contiene dos intentos fallidos.
• /clear entre tareas distintas. Cada petición envía toda la conversación, así que una sesión que ha juntado tres tareas relee las tres en la cuarta. /usage muestra en qué se fue tu uso, y /compact acepta un enfoque como «conserva los cambios de la API y los comandos de test».
• Ponle nombre al trabajo largo. /rename oauth-migration dentro de la sesión, y luego claude --resume oauth-migration desde tu shell la retoma más tarde.

Mira deshacer cambios y gastar menos cuota.

Antes de dejar una ejecución sin supervisión

Repasa cinco preguntas para esa tarea concreta: ¿sabe cómo se ve «terminado»?; ¿puede comprobar su propio trabajo?; ¿qué puede tocar?; ¿qué lo para (un tope de turnos o de gasto)?; y ¿adónde va el resultado y quién lo aprueba? Claude llevará una tarea larga hasta el final por sí solo. Lo que sigue siendo tuyo es arrancarla, decidir qué significa «terminado» esta vez y aprobar la fusión. Mira ejecutar desde un script y sesiones en paralelo con worktrees.

Lo que ya puedes dejar de hacer

• Gritar en mayúsculas (IMPORTANT, ALWAYS). Los modelos actuales siguen una línea bien redactada, y el énfasis excesivo tiende a que Claude aplique la regla de más. Si una regla no puede ceder, hazla un hook o una regla de denegación; si una línea se pierde, el archivo es demasiado largo.
• «Piensa a fondo» y «sé minucioso». Es texto normal de la petición. El control de cuánto piensa Claude es el nivel de esfuerzo.
• «Sigue, no seas vago». Darle a Claude una comprobación que pasar es distinto, y sigue valiendo la pena.
• Describir tu arquitectura y la estructura de archivos en CLAUDE.md. Claude lee el repositorio por sí mismo.

Para ver cómo encajan las piezas, mira cómo funciona Claude Code. Si algo no se comporta, depura la configuración. Todas las guías están en el índice de guías.

Esta página sigue la documentación de buenas prácticas de Anthropic tal como la leemos en octubre de 2026. No tenemos relación con Anthropic. La escribimos a partir de la documentación y no hemos probado todos los casos. Los comandos, los valores por defecto y el modo de permisos con el que empieza una sesión cambian entre versiones, y donde esta página y la documentación no coincidan, manda la documentación.

Mira también: Flujos de cada día.

La skill gratis loop-stop da a las tareas largas un límite y una regla de parada. Si quieres una segunda mirada a tu CLAUDE.md y a tus ajustes, el Tune-Up Kit es una lista de comprobación para eso (la ficha está en inglés).