Guía práctica de Claude Code: de chat a sistema de trabajo con IA

Qué es Claude Code y cómo debes pensarlo

La forma correcta de entender Claude Code es esta: no es solo un chat para pedir ayuda, sino un entorno agentic que puede leer tu codebase, editar archivos, ejecutar comandos e integrarse con herramientas externas. Ese cambio mental es clave, porque deja de ser "pregúntale algo" y pasa a ser "dale un objetivo, contexto y límites para que ejecute".

El error más común es usarlo como si fuera ChatGPT copiando y pegando prompts sueltos. La práctica recomendada por Anthropic va en la dirección opuesta: definir objetivo, planear primero, luego ejecutar, y apoyarte en contexto persistente y automatizaciones reutilizables.

Las 5 piezas que debes dominar sí o sí

El flujo de trabajo óptimo en 7 fases

1. Preparar el entorno Instala Claude Code y abre el proyecto desde la carpeta raíz. Trabaja siempre dentro del contexto del repositorio real.
2. No arranques ejecutando: arranca planeando Antes de pedir "haz X", entra en Plan Mode. Claude explorar y planificará sin editar nada, y hará preguntas para aclarar el objetivo.
3. Dale un brief operativo, no un prompt suelto Un encargo completo tiene: objetivo de negocio, resultado esperado, restricciones, criterios de calidad y forma de validación.
4. Revisa el plan y corrígelo Verifica si entendió el objetivo real, si tocará los archivos correctos, si faltan riesgos y si el orden tiene sentido. Ajusta antes de gastar ciclos.
5. Ejecuta en modo normal o auto-accept Si el cambio es sensible, usa normal mode. Si confías en el plan y el alcance, auto-accept mode da mayor velocidad.
6. Pide validación explícita Exige siempre: archivos modificados, resumen de cambios, riesgos, pruebas ejecutadas, pendientes y recomendaciones siguientes.
7. Persistir aprendizaje Lo que se repite se convierte en contenido de CLAUDE.md, una Skill, una integración MCP o una configuración del proyecto. Eso transforma uso ocasional en sistema de trabajo.

Paso a paso para empezar hoy

Paso 1. Instalar Claude Code

Anthropic ofrece instalación nativa y vía Homebrew para macOS/Linux/WSL.

Paso 2. Abrir tu proyecto real

Ve a la raíz del proyecto y lanza Claude ahí. Claude Code está pensado para trabajar sobre tu base de archivos y entender el contexto del repositorio.

Paso 3. Crear CLAUDE.md

Haz esto antes de la primera gran sesión. Incluye lo que no quieres repetir cada vez:

# CLAUDE.md

## Project overview
Este proyecto es una aplicación web para [objetivo del negocio].

## Tech stack
- Frontend: React / Next.js
- Backend: Node.js / Python
- DB: PostgreSQL / MongoDB

## Architecture rules
- No introducir nuevas dependencias sin justificarlo
- Mantener separación por capas
- Priorizar cambios pequeños y verificables

## Coding standards
- TypeScript estricto
- Nombres descriptivos
- Manejo explícito de errores

## Important commands
- install:
- dev:
- test:
- lint:

## How to work
- Primero analizar y planear
- Luego proponer plan
- Después ejecutar por pasos
- Al final resumir cambios, pruebas y riesgos

Paso 4. Arrancar siempre en Plan Mode

Tu primer prompt operativo puede seguir esta estructura:

Quiero que trabajes en Plan Mode.

Objetivo:
[describe el objetivo]

Contexto:
Lee CLAUDE.md y analiza la estructura del repositorio.

Restricciones:
- no hagas cambios todavía
- identifica archivos relevantes
- detecta riesgos
- formula preguntas si falta contexto

Entregable:
Devuélveme un plan paso a paso, los archivos que tocarías,
la estrategia de validación y los riesgos principales.

Paso 5. Refinar el plan

Corrige el plan hasta que quede alineado. No busques perfección textual; busca precisión operativa.

Paso 6. Ejecutar

Ejecuta el plan aprobado.

Condiciones:
- implementa cambios mínimos y bien justificados
- explica cada bloque importante
- corre validaciones al finalizar
- si aparece un riesgo no previsto, detente y repórtalo

Paso 7. Cerrar la sesión con memoria útil

Genera un resumen final con:
1. cambios realizados
2. archivos modificados
3. pruebas ejecutadas
4. riesgos pendientes
5. recomendaciones
6. elementos que debería agregar a CLAUDE.md
7. tareas repetitivas que convendría convertir en Skills

Qué debes hacer y qué no debes hacer

Las herramientas que debes tener sí o sí

1. CLAUDE.md

Obligatoria en cualquier proyecto serio. Sin ella, Claude empieza semiciiego en cada sesión.

2. Skills

Si haces una tarea dos o tres veces, ya merece una Skill. Estructura mínima:

.claude/
  skills/
    review-feature/
      SKILL.md

Ejemplo de SKILL.md:

---
name: review-feature
description: Revisa una feature implementada y genera checklist técnico,
             riesgos y recomendaciones.
---

# Objetivo
Revisar una implementación antes de merge o demo.

# Instrucciones
1. Identifica archivos modificados.
2. Resume el propósito del cambio.
3. Evalúa riesgos técnicos.
4. Revisa errores obvios, deuda técnica y validaciones faltantes.
5. Devuelve una salida estructurada.

# Formato de salida
- Resumen
- Archivos revisados
- Riesgos
- Validaciones faltantes
- Recomendación final

3. MCP

Cuando quieras que Claude deje de vivir solo dentro del repositorio y empiece a actuar sobre tu stack real: APIs, bases de datos, herramientas externas. MCP es la puerta de entrada.

4. Settings del proyecto

Usa configuración global y por repositorio para no depender de memoria manual en cada sesión.

5. Subagents

Claude Code incluye subagentes como Explore, Plan y otros personalizables. Permiten delegar ciertos tipos de trabajo a agentes especializados dentro del mismo flujo.

6. Integración con IDE

La experiencia mejora cuando ves el plan, comentarios y cambios directamente en tu entorno de edición. Anthropic documenta integración con VS Code y cómo los modos de permiso se reflejan ahí.

Cómo estructurar un brief excelente para Claude Code

Usa siempre esta plantilla. Reemplaza el prompt ambiguo por una especificación operativa:

Objetivo de negocio:
¿Qué problema resuelve esto?

Resultado esperado:
¿Qué debe existir al final?

Contexto:
¿Qué debe leer Claude primero?
(CLAUDE.md, docs, carpetas, archivos clave)

Restricciones:
¿Qué no puede romper? ¿Qué no debe hacer?

Criterios de calidad:
¿Cómo se verá un buen resultado?

Validación:
¿Qué pruebas o chequeos debe ejecutar?

Entregable:
¿Qué quieres que te devuelva al final?

Un sistema de trabajo maduro con Claude Code

Rutina recomendada de cada sesión

1. Abre el proyecto
2. Revisa o actualiza CLAUDE.md
3. Entra en Plan Mode
4. Da objetivo + restricciones + validación
5. Corrige el plan
6. Ejecuta en modo adecuado
7. Exige resumen, pruebas y riesgos
8. Actualiza memoria del proyecto
9. Convierte repeticiones en Skills