01 Qué es este repositorio y cómo leerlo
claude-code-best-practice es un repositorio público con licencia MIT que mantiene el desarrollador Shayan Rais. Reúne más de ochenta consejos agrupados por temas (planificación, contexto, sesiones, CLAUDE.md, agentes, skills, hooks, Git, depuración) y cada uno enlaza a su fuente: publicaciones de Boris Cherny, creador de Claude Code, de Thariq, también del equipo de Anthropic, de la documentación oficial y de la comunidad.
No es documentación oficial ni un tutorial lineal. Funciona mejor como lista de comprobación: lees un bloque, comparas con tu forma de trabajar y adoptas lo que te falte. En esta guía tienes los consejos que más impacto tienen, verificados contra la documentación actual de Claude Code.
02 Planificar antes de escribir código
- ✓Empieza las tareas grandes en modo plan: /plan seguido de la tarea, o Mayús+Tab para cambiar de modo.
- ✓Parte de una especificación mínima y pide a Claude que te entreviste con preguntas antes de escribir el plan definitivo.
- ✓Ejecuta el plan en una sesión nueva: la conversación de diseño ya no aporta y ocupa contexto.
- ✓Divide el trabajo en porciones verticales que atraviesen base de datos, lógica e interfaz, en lugar de fases horizontales que retrasan la primera prueba real.
- ✓Pide una segunda opinión: otra sesión de Claude que revise el plan como lo haría un ingeniero sénior.
- ✓Si construir es barato, prototipa varias versiones antes de escribir un documento de requisitos largo.
Quiero [describe la funcionalidad en dos o tres frases]. Antes de proponer nada, entrevístame: hazme las preguntas que necesites sobre usuarios, datos, casos límite y criterios de aceptación, de tres en tres. Cuando no te quede ninguna duda importante, escribe una especificación breve en specs/[nombre].md con el alcance, lo que queda fuera y cómo comprobaremos que funciona. No escribas código todavía.03 Contexto y sesiones: la diferencia entre resultados finos y mediocres
La calidad de Claude empeora a medida que la conversación se llena de intentos fallidos, salidas de herramientas y correcciones. Varios consejos del equipo apuntan a lo mismo: controla qué se queda en el contexto. Mira el nivel con /context y, como referencia de la comunidad, plantéate cerrar o compactar cuando pases de la mitad en tareas delicadas.
| Situación | Qué hacer | Por qué |
|---|---|---|
| Claude ha seguido un camino equivocado | /rewind o Esc dos veces con el campo vacío, y vuelve a pedirlo con lo aprendido | Corregir encima deja el intento fallido ensuciando el contexto |
| Tarea a medias y conversación larga | /compact con instrucciones: qué conservar y qué descartar | La compactación automática llega cuando el modelo ya va justo |
| Empiezas algo distinto | /clear y un resumen breve de lo imprescindible | Controlas exactamente qué pasa a la nueva tarea |
| Búsquedas o lecturas masivas | Pide que lo haga un subagente | Solo vuelve la conclusión, no los veinte archivos leídos |
| Varias sesiones abiertas | /rename para etiquetarlas y /resume para retomarlas | Evitas mezclar trabajos |
04 CLAUDE.md y reglas por carpeta
La documentación oficial recomienda que cada CLAUDE.md tenga menos de 200 líneas: todo lo que contiene se carga en cada sesión. Incluye los comandos de instalación, pruebas y compilación (cualquiera debería poder decir «ejecuta los tests» y que funcione a la primera), las convenciones del proyecto y lo que no se debe hacer. Lo que solo afecta a una parte del código va en .claude/rules/ con un campo paths, y se carga solo cuando Claude toca esos archivos.
---
paths:
- "src/api/**/*.ts"
---
# Reglas de la API
- Valida siempre la entrada de cada endpoint.
- Usa el formato de error común del proyecto.
- No accedas a la base de datos desde los controladores.05 Skills, hooks y permisos
Si lo repites a diario, conviértelo en skill
Un flujo que haces más de una vez al día merece su propio comando. Escribe la descripción pensando en cuándo debe activarse, no como resumen.
Sección de trampas en cada skill
Anota los fallos que Claude comete en esa tarea. Es el contenido que más mejora el resultado con el tiempo.
Hook para formatear
Un hook PostToolUse que ejecute tu formateador tras cada edición evita fallos de integración continua por estilo.
Hook Stop para verificar
Un hook al terminar el turno puede pedir a Claude que compruebe su trabajo o siga si quedan tareas.
Modo automático, no saltarse permisos
En lugar de desactivar todos los permisos, usa el modo automático: un clasificador aprueba lo seguro y pregunta lo arriesgado.
Lista blanca a medida
/fewer-permission-prompts analiza tus sesiones y propone qué comandos de solo lectura permitir. /permissions admite comodines como Bash(npm run *).
06 Git, revisión y depuración
- ✓Pull requests pequeños y de un solo tema: se revisan y se revierten fácil.
- ✓Commits frecuentes, en cuanto termina cada tarea, para poder volver atrás sin miedo.
- ✓Revisa antes de integrar con /code-review y, si hay datos o accesos sensibles, con /security-review.
- ✓Cuando te atasques, comparte una captura de pantalla del error.
- ✓Pide a Claude que lance los servidores como tarea en segundo plano para que pueda leer sus logs.
- ✓Si algo no arranca, /doctor diagnostica la instalación y la configuración.
Antes de dar esto por terminado, demuéstrame que funciona: compara mi rama con main, enumera cada cambio de comportamiento y ejecuta las pruebas que lo cubren. Si la solución actual es un parche, dímelo y propón la versión limpia sabiendo todo lo que sabes ahora.07 Cómo usar el repositorio con Claude
git clone https://github.com/shanraisshan/claude-code-best-practice.gitLee el README de claude-code-best-practice (está en [ruta de la carpeta clonada]) y después revisa este proyecto: CLAUDE.md, .claude/settings.json, .claude/rules, skills y hooks.
Devuélveme:
1. Qué buenas prácticas ya aplico.
2. Las cinco que más me faltan, ordenadas por impacto, con el consejo del repositorio que las respalda.
3. Para cada una, el cambio concreto que harías en mis archivos.
No cambies nada hasta que te diga cuáles aplicar. Si un consejo menciona un comando que no existe en mi versión, indícalo.Reescribe el CLAUDE.md de este proyecto siguiendo los consejos del bloque CLAUDE.md de ese repositorio: menos de 200 líneas, comandos reales de instalación, pruebas y compilación comprobados ejecutándolos, convenciones que no se deducen del código y una lista breve de lo que no se debe hacer. Mueve a .claude/rules con paths lo que solo afecta a una carpeta. Enséñame el esquema antes de escribir.Preguntas frecuentes
No. Lo mantiene un desarrollador independiente, aunque muchos consejos proceden de miembros del equipo de Claude Code y de la documentación oficial, y cada uno enlaza a su fuente.
No. Escoge los cinco que resuelvan lo que más te frena ahora y vuelve a revisar la lista dentro de unas semanas.
Sí. CLAUDE.md, reglas, skills, hooks y la mayoría de comandos funcionan igual en la pestaña Code de la app y en la terminal.
Una vez al mes es suficiente. Actualiza Claude Code con frecuencia y echa un vistazo a su registro de cambios: muchos consejos dependen de funciones recientes.
Sobre el autor
Equipo editorial de appyweb
Marketing, SEO y desarrollo con IA
Especialistas de appyweb en SEO, publicidad, desarrollo web y automatización con IA.