Buenas prácticas para Claude Code

Fuente: code.claude.com/docs/en/best-practices

Qué cambia respecto a un chatbot

Claude Code es un entorno agéntico: lee archivos, ejecuta comandos, hace cambios y avanza solo mientras tú observas, corriges o te alejas. Describes el objetivo; Claude explora, planifica e implementa.

El recurso más escaso es la ventana de contexto. A medida que se llena —mensajes, archivos leídos, salida de comandos— el rendimiento baja y pueden perderse instrucciones anteriores.

Dar una forma de verificar el trabajo

Sin un check automático, “parece terminado” es la única señal y tú te conviertes en el bucle de verificación. Con tests, build, linter o diff contra un fixture, Claude puede iterar hasta que pase.

Opciones para el check:

En el mismo prompt: pedir que corra el check e itere.
En la sesión: definir un /goal que se reevalúe cada turno.
Como gate determinista: un hook Stop que bloquea hasta que pase un script.
Con segunda opinión: subagente o revisor que evalúa el diff sin el razonamiento previo.

Pide evidencia: salida del test, comando ejecutado, captura de pantalla.

Explorar, planificar, codificar

Saltar directo al código suele resolver el problema equivocado. Flujo recomendado:

Explorar — modo plan: leer sin cambiar.
Planificar — plan detallado; editar el plan si hace falta.
Implementar — salir del modo plan y codificar contra el plan.
Commit — mensaje descriptivo y PR.

Planificar compensa cuando el enfoque es incierto, el cambio toca varios archivos o el código es desconocido. Si el diff cabe en una frase, el plan sobra.

Instrucciones concretas

Claude infiere mucho, pero no lee la mente. Nombra archivos, restricciones y patrones de ejemplo.

Situación	Mejor
Alcance vago	“Tests para foo.py cubriendo usuario deslogueado; sin mocks”
Historia del código	“Revisa el historial git de ExecutionFactory y resume cómo surgió la API”
Seguir patrón	“Mira widgets en home y replica el patrón para el calendario”
Bug	“Login falla tras timeout de sesión; reproduce con test en src/auth/, luego arregla”

Referencias útiles: @archivo, imágenes pegadas, URLs de docs, cat error.log | claude.

Configurar el entorno

CLAUDE.md

Archivo que Claude lee al inicio de cada conversación: comandos bash, estilo de código, reglas de flujo. Manténlo corto. Por cada línea pregunta: “¿Si la quito, Claude cometerá errores?” Si no, quítala. Un CLAUDE.md hinchado hace que ignore las reglas importantes.

Incluye: comandos no obvios, estilo distinto al default, cómo correr tests, convenciones del repo, decisiones de arquitectura, variables de entorno requeridas, trampas del proyecto.

Excluye: lo que se ve en el código, convenciones estándar del lenguaje, docs largas (enlaza), listados archivo por archivo.

Trátalo como código: revisa cuando falle algo, poda con frecuencia, versiona en git.

Permisos, herramientas y extensiones

CLI (gh, aws, etc.): eficiente en contexto para servicios externos.
Servidores MCP: issues, bases de datos, diseños, workflows.
Hooks: acciones deterministas en puntos fijos del flujo.
Skills (.claude/skills/): conocimiento de dominio aplicado cuando toca.
Subagentes (.claude/agents/): contexto y herramientas propias para tareas pesadas.
Plugins: empaquetan skills, hooks, subagentes y MCP.

Comunicación y sesión

Para features grandes, que Claude te entreviste (implementación, UX, casos límite, tradeoffs) y escriba un SPEC.md. Luego abre sesión nueva solo para implementar.

Gestión de sesión:

Esc — detener acción, contexto intacto.
Esc + Esc / /rewind — volver atrás en conversación y código.
"Undo that" — revertir cambios.
/clear — reset entre tareas no relacionadas.

Si corriges más de dos veces el mismo problema, /clear y un prompt mejor casi siempre ganan a seguir en la misma sesión.

Subagentes sirven para investigar o revisar en contexto separado. Los checkpoints permiten probar algo arriesgado y volver atrás.

Automatizar y escalar

claude -p "prompt" — modo no interactivo (CI, hooks, scripts).
Sesiones paralelas: worktrees, app de escritorio, web, equipos de agentes.
Patrón escritor/revisor: dos sesiones; el revisor no vio cómo se escribió el código.
Migraciones grandes: lista de tareas + script que llama claude -p por ítem.
Revisión adversarial antes de dar por terminado: subagente que revisa el diff y reporta huecos.

Patrones de fallo frecuentes

Sesión “cajón de sastre” — mezclar tareas no relacionadas. Arreglo: /clear entre tareas.
Corregir una y otra vez — contexto contaminado. Arreglo: tras dos fallos, /clear y mejor prompt.
CLAUDE.md sobrecargado — reglas importantes se pierden. Arreglo: podar sin piedad.
Confiar sin verificar — código plausible pero incompleto. Arreglo: check obligatorio.
Exploración sin límite — “investiga” llena el contexto. Arreglo: acotar o usar subagentes.