Claude Code para principiantes: instalación, permisos seguros y primeros 30 minutos

Claude Code es un agente de programación que se usa desde la terminal. No es solo un chat donde pegas fragmentos de código: puede leer archivos del proyecto, buscar en el repositorio, proponer cambios, editar cuando lo autorizas y ejecutar comandos como pruebas o builds.

El error más común al empezar es pedir demasiado. Si el primer prompt es “mejora toda esta aplicación”, el resultado será difícil de revisar. Un mejor inicio es: leer el proyecto, explicar la estructura, elegir una tarea pequeña, aplicar un cambio controlado y verificar el resultado.

Esta guía está alineada con la documentación oficial de setup, common workflows y CLI usage. Después, conviene leer la guía de CLAUDE.md y la de gestión de contexto.

Qué es Claude Code en la práctica

Claude Code funciona mejor cuando la tarea tiene contexto y límites. Puede ayudarte a entender una base de código, localizar archivos relevantes, corregir un bug pequeño, añadir pruebas, mejorar documentación o preparar un resumen de PR.

La primera semana no deberías intentar automatizarlo todo. Usa esta secuencia:

Paso	Acción	Objetivo
1	Instalar e iniciar sesión	Confirmar que la herramienta funciona
2	Leer el proyecto sin editar	Crear un mapa mental
3	Elegir una tarea pequeña	Reducir riesgo
4	Revisar diff y pruebas	Validar evidencia
5	Guardar reglas	Repetir con más calidad

Este flujo parece lento, pero reduce horas de corrección posterior.

Preparación antes de instalar

Empieza en un repositorio donde los errores no duelan. Lo ideal es una rama nueva:

git status
git switch -c try-claude-code

Si tu versión de Git no soporta switch:

git checkout -b try-claude-code

Comprueba también:

• una cuenta de Claude con acceso a Claude Code
• conexión a internet
• la carpeta raíz del proyecto
• Git funcionando
• comandos de test o build conocidos
• una regla clara: no exponer .env, claves ni datos de clientes

En Windows, no mezcles PowerShell y CMD. Si ves PS C:\, estás en PowerShell.

Instalación

En macOS, Linux o WSL:

curl -fsSL https://claude.ai/install.sh | bash

En Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Después verifica:

claude --version
claude doctor

claude doctor es especialmente útil al principio porque detecta problemas de instalación y configuración antes de que los confundas con errores del proyecto.

También existe instalación por npm:

npm install -g @anthropic-ai/claude-code

Pero, si no tienes una razón concreta, empieza con el instalador nativo oficial. Evita sudo npm install -g, porque puede crear problemas de permisos y seguridad.

Primeros 30 minutos

Entra en la raíz del proyecto:

cd my-project
claude

Tras iniciar sesión, no pidas una funcionalidad completa. Usa un prompt de solo lectura:

Soy nuevo en este proyecto.
No edites archivos todavía. Lee el repositorio y explica:

- qué hace el proyecto
- directorios principales y responsabilidades
- posibles comandos de dev, test y build
- archivos que parecen riesgosos de cambiar
- los 5 primeros archivos que debería leer

Incluye rutas de archivos como evidencia y no afirmes lo que no esté claro.

Luego pide tareas pequeñas:

Propón 5 tareas aptas para principiantes en este repositorio.
Cada tarea debe:

- tomar unos 30 minutos
- tocar como máximo 2 archivos
- tener prueba o verificación manual
- evitar autenticación, pagos, secretos y datos de producción

Incluye riesgo y pasos de verificación.

Así conviertes Claude Code en un asistente de onboarding, no en una caja negra.

Permisos seguros

Como Claude Code puede ejecutar comandos y editar archivos, los permisos importan. Para empezar de forma conservadora:

claude --permission-mode plan

Dentro de la sesión:

/permissions

Ten mucho cuidado con bypassPermissions y --dangerously-skip-permissions. Solo tienen sentido en entornos aislados, como contenedores descartables o máquinas virtuales.

Un patrón prudente de permisos sería:

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(npm run test *)",
      "Bash(npm run build *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.env)"
    ]
  }
}

La idea es permitir verificaciones de bajo riesgo, bloquear secretos y dejar operaciones destructivas para aprobación humana.

Ejemplo 1: mejorar README

README es una gran primera tarea porque mejora comprensión sin tocar lógica de producción.

Quiero mejorar README.md.
Primero lee README.md y package.json.
Lista qué falta, pero no edites todavía.
Cuando apruebe, modifica solo README.md.

Después limita el cambio:

Añade solo dos secciones a README.md:

- desarrollo local
- comando de pruebas

Usa solo comandos visibles en package.json.
No inventes herramientas ni pasos de despliegue.

Ejemplo 2: corregir un bug pequeño

Una buena descripción de bug mejora mucho el resultado.

Investiga este bug.

Problema:
- Si el input de búsqueda contiene solo espacios, la app muestra todos los resultados.

Esperado:
- Un input de solo espacios debe tratarse como búsqueda vacía.

Restricciones:
- Explica primero la causa probable.
- Cambia como máximo 1 archivo.
- Indica pruebas o verificaciones manuales.

Después mira el diff:

git diff

Y pide revisión:

Revisa el git diff actual.
Busca cambios inesperados, exceso de abstracción, falta de pruebas y casos borde.
Si está bien, resume 3 verificaciones manuales.

Ejemplo 3: CTA para PDF, producto o consulta

Para un sitio de contenido, Claude Code puede mejorar el siguiente paso del lector sin rehacer todo el diseño.

Lee este artículo y propone 3 CTAs para principiantes.

Objetivos:
- reducir ansiedad del primer uso
- conectar con PDF gratis, producto o consulta
- máximo 80 caracteres cada uno
- evitar tono agresivo de venta

Luego implementa con patrones existentes:

Busca el patrón de CTA existente en páginas de artículo.
Añade un CTA al final de este artículo con el mismo tono.
No crees un componente nuevo ni cambies estilos globales.

Errores comunes

Primero: pedir demasiado. “Mejora la app” no es una tarea. “Corrige el caso de espacios en búsqueda” sí lo es.

Segundo: saltarse la lectura inicial. Si Claude Code no puede explicar la arquitectura, no debería editar todavía.

Tercero: ampliar permisos demasiado pronto. La automatización rápida no compensa un diff imposible de entender.

Cuarto: creer el mensaje final sin evidencia. Revisa pruebas, build, navegador o git diff.

Quinto: mantener una conversación larguísima. Si cambia el tema, resume y abre una sesión limpia. Lee más en gestión de contexto.

Checklist de bloqueo

• ¿Funciona claude --version?
• ¿Qué dice claude doctor?
• ¿Estás en la raíz del proyecto?
• ¿git status es comprensible?
• ¿Mezclaste PowerShell y CMD?
• ¿Usas WSL, SSH o contenedor con flujo especial de login?
• ¿Intentas leer .env o claves?
• ¿Activaste un modo de permisos peligroso?
• ¿Existe realmente el comando de test?

Prompt de diagnóstico:

Claude Code no se comporta como esperaba.
No edites archivos. Ayúdame a diagnosticar.

Entorno:
- OS:
- shell:
- comando ejecutado:
- error:
- comportamiento esperado:

Ordena las comprobaciones desde la más segura.

Nota de verificación de Masa

En ClaudeCodeLab, el patrón más fiable ha sido leer, planificar, cambiar poco y verificar. Funcionó para artículos, traducciones, CSS y scripts de despliegue. Cuando la tarea tenía límites, el diff era revisable. Cuando dejaba correr demasiado tiempo, costaba reconstruir la intención.

Mi recomendación para principiantes: durante la primera semana deja visibles los permisos, revisa cada git diff y guarda los prompts que funcionaron. Después avanza a consejos de productividad y flujos de equipo.

Siguiente paso

Hoy abre un repositorio no crítico, pide un mapa de solo lectura, elige una mejora de 30 minutos y revisa el diff.

Si quieres una hoja de referencia, descarga gratis Claude Code Quick Reference Cheatsheet. Para implementación en equipo, formación o revisión de flujo real, usa los recursos y la consulta del sitio.