Cómo trabajar con Claude Code: buenas prácticas
Configura CLAUDE.md, permisos, modo plan y comandos propios para que Claude Code acierte a la primera y no rompa nada.
- Cuenta de Claude con plan que incluya Claude Code (Pro, Max, Team o Enterprise) o una clave de la Claude Console
- macOS, Linux o Windows (PowerShell o WSL)
- Git instalado y un repositorio real con el que practicar
- Familiaridad básica con la terminal
- Instalar Claude Code con el instalador nativo y comprobar que todo está bien
- Escribir un CLAUDE.md útil que ahorre explicaciones en cada sesión
- Configurar permisos compartidos para trabajar rápido sin riesgos
- Aplicar el flujo explorar, planificar, implementar y verificar con modo plan
- Gestionar el contexto y crear comandos personalizados reutilizables por todo el equipo
Instalar Claude Code con el instalador nativo
Olvídate de npm: el método recomendado es el instalador nativo, que se actualiza solo y no depende de tu versión de Node. En macOS, Linux o WSL ejecuta el comando de curl del bloque de código. En Windows nativo abre PowerShell y ejecuta el equivalente con irm. Cuando termine, entra en la carpeta de tu proyecto y lanza claude. La primera vez te pedirá iniciar sesión con tu cuenta de Claude o con una clave de la Console. Después comprueba la instalación con claude doctor, que detecta problemas de PATH, versiones duplicadas o permisos. Si en tu empresa en España o LATAM trabajáis detrás de un proxy corporativo, este es el momento de descubrirlo, no a mitad de una tarea. Dentro de la sesión puedes usar /model para ver qué modelo estás usando; para tareas complejas de arquitectura conviene el modelo más capaz disponible, como claude-opus-5-5.
# macOS, Linux o WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows (PowerShell)
# irm https://claude.ai/install.ps1 | iex
# Verificar
claude --version
claude doctor
# Arrancar en tu proyecto
cd ~/proyectos/mi-app
claudeCrear y afinar el archivo CLAUDE.md
CLAUDE.md es la memoria del proyecto: Claude Code lo lee al inicio de cada sesión. Ejecuta /init dentro de la sesión para que genere un borrador analizando tu repo, y luego edítalo tú. La regla de oro: solo lo que Claude no puede deducir leyendo el código. Comandos exactos de build, test y lint; convenciones del equipo; decisiones de arquitectura; y cosas que NO debe hacer. Sé concreto y breve: un CLAUDE.md de 400 líneas diluye las instrucciones importantes. Usa frases imperativas y, para reglas críticas, enfatízalas. Commitea el archivo al repo para que todo el equipo comparta el mismo contexto. Para preferencias personales que no quieres imponer a nadie existe un archivo de memoria a nivel de usuario en tu directorio personal. El bloque de código crea un CLAUDE.md de ejemplo para un proyecto Node con TypeScript.
cat > CLAUDE.md << 'EOF'
# Proyecto: mi-app (API REST en Node + TypeScript)
## Comandos
- Instalar: npm ci
- Tests: npm run test (un solo archivo: npm run test -- ruta/al/test.ts)
- Lint y tipos: npm run lint && npm run typecheck
## Convenciones
- Código y nombres en inglés; comentarios y mensajes de commit en español
- Usa async/await, nunca callbacks
- Validación de entrada siempre con zod en src/schemas/
## Reglas importantes
- NUNCA edites archivos en src/generated/ (se regeneran con npm run codegen)
- Ejecuta lint y typecheck antes de dar una tarea por terminada
- No añadas dependencias nuevas sin preguntar
EOFConfigurar permisos compartidos en settings.json
Por defecto Claude Code pide confirmación antes de ejecutar comandos o editar archivos. Es seguro, pero aprobar veinte veces npm run test mata el ritmo. La solución es definir una lista de permitidos y denegados en .claude/settings.json dentro del proyecto. Permite los comandos de solo lectura y los scripts del proyecto que usas constantemente, y deniega explícitamente lo peligroso: leer archivos .env, borrados recursivos o pushes. Este archivo se commitea, así que todo el equipo trabaja con las mismas reglas. Para ajustes personales que no deben compartirse existe .claude/settings.local.json, que conviene añadir al .gitignore. También puedes revisar y modificar permisos de forma interactiva con el comando /permissions dentro de la sesión. Empieza restrictivo y abre permisos según veas qué apruebas una y otra vez.
{
"permissions": {
"allow": [
"Bash(npm run test:*)",
"Bash(npm run lint)",
"Bash(npm run typecheck)",
"Bash(git status)",
"Bash(git diff:*)",
"Bash(git log:*)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Bash(rm -rf:*)",
"Bash(git push:*)"
]
}
}Aplicar el flujo explorar, planificar, implementar
El error más caro con Claude Code es pedirle directamente que programe algo complejo. Separa las fases. Primero, exploración: pídele que lea los archivos relevantes y te explique cómo funciona esa parte, dejando claro que todavía no escriba código. Segundo, planificación: activa el modo plan (puedes alternar entre modos con Shift+Tab) y pídele un plan detallado. En modo plan Claude analiza y propone, pero no modifica archivos. Revisa el plan, corrígelo y, si es una tarea grande, pídele que lo guarde en un archivo markdown para retomarlo en otra sesión. Tercero, implementación: sal del modo plan y pide que ejecute el plan paso a paso, verificando cada parte. Cuarto, cierre: que ejecute tests y lint y prepare un commit con un mensaje descriptivo. Usa @ para referenciar archivos concretos y evitar que busque a ciegas. Los prompts del bloque son plantillas que puedes pegar tal cual.
# Fase 1 - Explorar (sin escribir código)
Lee @src/routes/orders.ts y @src/services/payment.ts y explícame cómo se procesa un pago. No modifiques nada todavía.
# Fase 2 - Planificar (en modo plan)
Quiero añadir reembolsos parciales. Propón un plan: archivos a tocar, cambios en el esquema, casos límite y tests necesarios. Guarda el plan en docs/plan-reembolsos.md.
# Fase 3 - Implementar
Implementa el plan de docs/plan-reembolsos.md paso a paso. Tras cada paso ejecuta npm run test y corrige lo que falle.
# Fase 4 - Cerrar
Ejecuta lint y typecheck, revisa el diff y crea un commit con un mensaje en español que explique el porqué del cambio.Gestionar el contexto entre tareas
La ventana de contexto es tu recurso más valioso. A medida que se llena con salidas de comandos, archivos leídos e intentos fallidos, Claude pierde precisión. Tres hábitos marcan la diferencia. Uno: una tarea por sesión. Cuando terminas una funcionalidad y pasas a otra no relacionada, ejecuta /clear para empezar limpio. Dos: si estás en mitad de algo largo y quieres conservar lo esencial, usa /compact, opcionalmente con instrucciones sobre qué preservar. Tres: si Claude entra en bucle intentando arreglar lo mismo, no insistas en la misma conversación; para con Escape, limpia el contexto y reformula con lo que has aprendido. Para retomar trabajo de otro día tienes claude --continue, que reabre la última conversación, y claude --resume, que te deja elegir entre sesiones anteriores. Para tareas de investigación pesadas, pídele que use subagentes: exploran en su propio contexto y solo te devuelven el resumen.
# Retomar la última sesión del proyecto
claude --continue
# Elegir entre sesiones anteriores
claude --resume
# Dentro de la sesión:
# /clear -> contexto limpio para una tarea nueva
# /compact conserva las decisiones de diseño y los archivos modificados
# /context -> ver cuánto contexto estás usandoCrear comandos personalizados para tareas repetidas
Si te encuentras escribiendo el mismo prompt varias veces por semana, conviértelo en un comando. Los archivos markdown dentro de .claude/commands/ se convierten en comandos de barra disponibles en la sesión: un archivo revisar-pr.md se invoca como /revisar-pr. Dentro puedes usar $ARGUMENTS para recibir parámetros. Al vivir en el repo, todo el equipo los comparte, lo que estandariza revisiones, creación de endpoints o corrección de issues. Es especialmente útil en equipos distribuidos entre España y LATAM con distintas costumbres de trabajo: el comando codifica el proceso acordado. El bloque crea dos comandos: uno para arreglar una issue de GitHub siguiendo vuestro flujo y otro para revisar el diff actual antes de abrir una PR. Para la issue, Claude usará la CLI gh si la tienes instalada y autenticada.
mkdir -p .claude/commands
cat > .claude/commands/arreglar-issue.md << 'EOF'
Arregla la issue de GitHub número $ARGUMENTS siguiendo estos pasos:
1. Usa `gh issue view $ARGUMENTS` para leer la issue completa.
2. Localiza el código implicado y explícame la causa antes de cambiar nada.
3. Escribe primero un test que reproduzca el fallo y confirma que falla.
4. Implementa la corrección mínima necesaria.
5. Ejecuta npm run test, npm run lint y npm run typecheck.
6. Crea un commit que referencie la issue (#$ARGUMENTS).
EOF
cat > .claude/commands/revisar-cambios.md << 'EOF'
Revisa el diff actual (git diff y git diff --staged) como un reviewer senior.
Busca: bugs, casos límite sin cubrir, problemas de seguridad, código muerto
y violaciones de las reglas de CLAUDE.md. Devuelve una lista priorizada
(crítico / mejorable / opcional) sin modificar archivos.
EOFVerificar con tests y revisar el diff antes de commitear
Claude Code rinde muchísimo más cuando tiene una forma objetiva de comprobar su trabajo. Dale un objetivo verificable: tests que deben pasar, un script que debe devolver cierto resultado o una captura que debe coincidir con un diseño. Un patrón muy fiable es TDD guiado: pídele que escriba los tests primero, confirme que fallan, los commitee, y solo entonces implemente hasta que pasen sin tocar los tests. Aun así, la responsabilidad del código es tuya. Antes de cada commit revisa el diff completo con git diff o en tu IDE; con la integración de VS Code o JetBrains ves los cambios en el visor de diferencias nativo. Trabaja en ramas y haz commits pequeños y frecuentes: son tu red de seguridad para revertir sin drama. Cuando el flujo esté maduro, puedes llevarlo a CI con el modo no interactivo claude -p para tareas acotadas como revisar PRs o actualizar changelogs.
# Rama dedicada para cada tarea
git checkout -b feat/reembolsos-parciales
# Revisar lo que ha cambiado Claude antes de aceptar
git status
git diff --stat
git diff
# Modo no interactivo (útil en scripts o CI)
claude -p "Resume en 5 viñetas los cambios de esta rama respecto a main para la descripción de la PR"Ahora tienes Claude Code instalado con el método nativo, un CLAUDE.md que le da a Claude el contexto que no puede deducir del código, permisos compartidos que te dejan avanzar rápido sin exponer secretos, y un flujo de trabajo explorar-planificar-implementar-verificar que reduce drásticamente los cambios fallidos. Sabes cuándo limpiar o compactar el contexto, has creado comandos reutilizables para tu equipo y revisas cada diff antes de commitear. Si quieres profundizar y dominar Claude Code en proyectos reales, con subagentes, hooks avanzados e integración en CI, el siguiente paso natural es un programa estructurado centrado en desarrollo asistido por IA.