Claude Code Best Practices · 83 tips de Boris Cherny y Thariq

El repo número uno de GitHub Trending hace semanas: claude-code-best-practices de Boris Cherny (creador de Claude Code) y Thariq. 50.749 stars, 5.045 forks, MIT, mantenimiento activo. 83 tips repartidos en 14 categorías que cubren todo el flujo: desde cómo escribir el primer prompt hasta cómo cerrar la sesión del día.

Esta nota es la traducción/condensación accionable. No copia el repo — destila los tips que de verdad mueven la aguja vs. los que son cosméticos.

Las 14 categorías

1. Prompting (8 tips)
2. Planning (6 tips)
3. Context (7 tips)
4. Session (5 tips)
5. CLAUDE.md (8 tips)
6. Agents (5 tips)
7. Commands (4 tips)
8. Skills (6 tips)
9. Hooks (5 tips)
10. Workflows (8 tips)
11. Git (6 tips)
12. Debugging (7 tips)
13. Utilities (5 tips)
14. Daily (3 tips)

83 en total. Voy a sacar los más impactantes de cada categoría.

Prompting (los 3 clave)

Tip 1: "Sé específico sobre el qué y el por qué, vago sobre el cómo."

Mal: "Implementá esto con useEffect." Bien: "Necesito mostrar los productos del usuario cuando carga la página. Usuario nunca debería ver loading mayor a 200ms."

Decirle el cómo lo restringe a tu solución, que puede no ser la mejor.

Tip 2: "Forzá el modo plan cuando la tarea toca más de 3 archivos."

Es la regla simple que evita el 80% de los problemas. Si Claude va a cambiar 5+ archivos, plan mode primero.

Tip 3: "Listale las restricciones explícitas."

"No agregues nuevas dependencias." "No cambies la API pública." "Mantenè los tests existentes pasando." Estas líneas no son redundantes — Claude sin restricción optimiza por "elegancia técnica" que a veces rompe acuerdos no escritos.

Planning (los 2 clave)

Tip 1: "Pediles a Claude que liste sus suposiciones antes de planear."

Prompt: "Antes del plan, listame qué estás asumiendo sobre [contexto del proyecto]."

Vas a descubrir suposiciones erradas antes que cuesten tiempo.

Tip 2: "El plan debe incluir el rollback path para cada paso."

Cada paso del plan responde dos cosas: qué hace y cómo se deshace si algo sale mal. Si no tiene rollback claro, el paso está mal planeado.

Context (los 3 clave)

Tip 1: "Carga el contexto que importa primero, no el que existe primero."

Si Claude va a tocar 30 archivos pero los 5 críticos son los que definen el contrato, abrílos vos y referenciálos en el prompt. Claude no siempre adivina cuáles son los críticos.

Tip 2: "Liberá contexto eliminando salida de tools que ya leíste."

Si pegaste un log de 5.000 líneas y Claude lo procesó, decile "podés olvidar el log anterior". Libera tokens para razonamiento posterior.

Tip 3: "Para repos grandes, usá tree -L 2 antes que tree sin límite."

Tree sin límite te llena el contexto con basura. Limit 2 te da overview suficiente sin gastar 30k tokens.

Session (los 2 clave)

Tip 1: "Una sesión = un objetivo principal."

Si arrancaste para implementar feature A y al rato querés debuggear bug B no relacionado, cerrá la sesión de A y abrí una nueva. Mezclar objetivos en la misma sesión confunde el contexto.

Tip 2: "Cerrá la sesión con un resumen explícito."

Antes de cerrar: "Resumime qué hicimos hoy en 5 líneas. Eso lo voy a pegar al inicio de mañana." Crea continuidad si no usás memoria persistente.

CLAUDE.md (los 4 clave)

Tip 1: "Mantenelo bajo 200 líneas."

CLAUDE.md grande = contexto gastado en cada sesión. Si crece, fragmentá en imports o referencias bajo demanda.

Tip 2: "Empezá con el cuándo NO usar (exclusiones explícitas)."

Mal CLAUDE.md: empieza listando todo lo que el proyecto hace. Buen CLAUDE.md: empieza diciendo "este repo no hace X, no toques Y, no asumas Z."

Tip 3: "Una sección 'comandos del proyecto' con los 5-10 más usados."

pnpm dev, pnpm test, pnpm db:push, etc. Claude no debería tener que adivinar cómo correr cosas.

Tip 4: "Versionado de CLAUDE.md va al final del archivo, no al principio."

Si arranca con changelog de 50 líneas, Claude gasta tokens leyendo historia antes de llegar a las reglas.

Agents (los 2 clave)

Tip 1: "Sub-agentes para tareas paralelas, no para tareas secuenciales."

Si A → B → C son secuenciales, hacelos en una sesión. Si A, B, C son paralelos (3 análisis independientes), spawneá sub-agentes.

Tip 2: "Cada sub-agente con prompt que limite scope."

Sub-agente sin scope claro intenta resolver el problema entero. Decile: "Tu única responsabilidad es analizar X. No toques Y. Reportame en formato Z."

Commands (los 2 clave)

Tip 1: "Slash commands para flujos que repetís más de 3 veces por semana."

Si hacés git status + git diff + commit estructurado 5 veces al día, hacé un slash command. La fricción que ahorra compone.

Tip 2: "Documentá cada custom command en CLAUDE.md."

Si tu equipo agarra el proyecto y ve un comando custom que no conoce, tiene que poder googlear (en CLAUDE.md, no en internet) qué hace.

Skills (los 3 clave)

Tip 1: "Description corta + triggers explícitos + exclusiones explícitas."

Las descriptions vagas son el error #1 en skills. Listá triggers concretos y al menos 1 exclusión.

Tip 2: "Si la skill solo aplica a un lenguaje, ponelo en el name."

format-python es más claro que format-code.

Tip 3: "Skills globales son contagiosas — revisá las que tenés activas."

Una skill global con triggers muy laxos se carga en proyectos donde no aporta. Cada 2-3 meses, listá skills globales y desinstalá las que no usás.

Hooks (los 2 clave)

Tip 1: "Hooks de pre-commit son baratos; hooks de pre-session son caros."

Pre-commit corre de a uno cuando vos commiteás. Pre-session corre cada vez que abrís el proyecto. Si tu hook tarda 5 segundos, multiplicalo por 20 sesiones al día.

Tip 2: "Logueá lo que el hook hace en un archivo, no en stdout."

Hooks que escupen output ensucian la conversación. Si quieren loggear, que escriban a .claude/logs/.

Workflows (los 3 clave)

Tip 1: "Un flow nuevo, validalo en repo sandbox antes de adoptarlo."

Antes de meter un workflow nuevo en tu repo principal, probalo en un repo de prueba. Si rompe ahí, no rompe tu producción.

Tip 2: "TDD inverso: pedile a Claude que escriba el test después, pero git diff ambos."

Pedile primero el código, después los tests, y compará. Si los tests pasan trivialmente, el código falla en cubrir casos. Si los tests fallan, te muestran qué falta.

Tip 3: "Para refactors grandes: branch + commits chicos + auto-merge nightly."

Trabajás en una branch, hacés commits diarios chicos, mergeás a main cada noche con auto-merge si tests pasan. Reduce riesgo vs. el "big bang merge" al final.

Git (los 2 clave)

Tip 1: "Cada PR de Claude lleva un footer 'Generated with Claude'."

Trazabilidad. Cuando seis meses después te preguntás "¿por qué este patrón raro?", el footer te lleva a la conversación.

Tip 2: "Antes de pedirle a Claude que toque tu repo, git stash cosas no commiteadas."

Si tenés cambios sin commitear, Claude puede sobreescribirlos sin querer. Stash → trabajo de Claude → stash pop → resolver conflictos.

Debugging (los 2 clave)

Tip 1: "El primer mensaje del debug debe incluir reproducción exacta."

Mal: "esto no anda." Bien: "Cuando corro pnpm test app/auth.test.ts, falla en línea 32 con 'TypeError'. Mira stack trace adjunto."

Tip 2: "Si el bug es intermitente, decílo explícito y pedí 'instrumentación temporal'."

Bugs raceCondition o flaky tests requieren logging extra. Pedile a Claude que agregue logs/asserts temporales en ramas separadas para diagnosticar antes de fixear.

Utilities (los 2 clave)

Tip 1: "Aliasea claude a un wrapper que setea defaults."

alias claude='claude --model opus --temperature 0.3 --skill-set agora'. Sin alias, terminás escribiendo flags repetitivos.

Tip 2: "Mantenè un ~/.claude/snippets/ con prompts reutilizables."

Tu top 10 prompts que repetís — guardalos como archivos. Cuando los necesitás, los pegás.

Daily (los 3 enteros)

Tip 1: "Repasá las skills globales activas una vez por semana."

Cinco minutos los lunes. Sacá las que no usás.

Tip 2: "Cerrá el día con /aprende o equivalente."

Si tenés una skill de memoria, corrégela al cerrar. No la dejes para "después".

Tip 3: "Una vez al mes, sentate sin distracciones a actualizar tu CLAUDE.md y AGENTS.md."

Lo que era cierto hace 6 meses puede no serlo hoy. La doc vieja desinforma a Claude.

Cómo usar el repo

git clone https://github.com/anthropic/claude-code-best-practices

El repo está organizado por categoría. Lo recomendable: leer entero una vez (no toma más de 2 horas), después volver cada vez que enfrentás un problema en una categoría específica. Los tips no son solo lista — cada uno tiene contexto, ejemplo y "cuándo NO aplicar".

Lo que el repo NO cubre

Para que sepas:

• Setup inicial específico de stack. Es agnóstico de tu stack.
• Comparación con otros agentes (Cursor, Aider, Codex). Solo Claude Code.
• Pricing y tier limits. Va a la doc oficial para eso.

Conclusión

83 tips es mucho para asimilar de una. La recomendación es: leelo entero una vez, marcá los 10-15 que te resuenan más, y aplicálos en las próximas dos semanas. Después relee el repo en un mes — los tips que antes te parecieron irrelevantes empezarán a tener sentido cuando hayas chocado con los problemas que resuelven.

El repo es vivo. Tiene PRs constantes con tips nuevos. Suscribite a watch para enterarte de los aportes de la comunidad.

Tags: claude-code-best-practices, best-practices, boris-cherny, thariq, 83-tips, anthropic