Claude Code: guía práctica para desarrolladores

Tienes una idea, abres el editor y aparece la pregunta de siempre: ¿por dónde empiezo? Claude Code puede ayudarte a recorrer ese camino. Para mí, la parte interesante llega cuando dejas de pedirle «hazme una app» y empiezas a trabajar con objetivos pequeños, instrucciones claras y resultados que puedes comprobar.

Voy a usar una app sencilla como hilo conductor: Taskboard, un tablero para apuntar tareas, marcarlas como hechas y filtrarlas. El ejemplo usa Next.js y TypeScript, pero el método te sirve para una web personal, una API o una herramienta de terminal. Si acabas de empezar, sigue los pasos. Si ya programas, guarda la chuleta y adapta las plantillas.

Dos formas de leer: recorre la guía con tu proyecto al lado o salta al kit descargable y a la referencia de comandos. Los ejemplos son propios; las funciones de Claude Code enlazan a su documentación oficial. Revisado el 2 de noviembre de 2026.

01. De una idea a la primera sesión

Claude Code es una herramienta de desarrollo que puede explorar tu repositorio, proponer cambios y utilizar herramientas durante una sesión. Aquí trabajaremos desde la terminal: la carpeta del proyecto importa porque será el punto de partida de la conversación. Para instalarlo e iniciar sesión, sigue el inicio rápido oficial de tu plataforma.

En un repositorio existente, abre su carpeta. Para un proyecto nuevo, prepara primero una carpeta vacía. Después, ejecuta esto en la terminal:

claude --permission-mode plan

Dentro de Claude Code, empieza con una petición de reconocimiento:

Quiero crear Taskboard, un tablero personal de tareas.
Revisa esta carpeta y dime qué existe, qué falta y cuál sería
la primera entrega útil. Si está vacía, propón una estructura
con Next.js, TypeScript y Tailwind. No implementes todavía.

El modo plan permite estudiar la tarea antes de entrar en la implementación; también puedes activarlo con /plan en una sesión. Revisa el plan, resuelve las decisiones pendientes y cambia a un modo que permita editar cuando quieras construir. Referencia del flujo de planificación.

No necesitas preparar todas las extensiones el primer día. Este selector te ayuda a elegir la pieza que corresponde a cada necesidad:

02. Pide algo que puedas comprobar

«Haz un gestor de tareas bonito» deja demasiadas decisiones abiertas. Un encargo útil describe qué debe poder hacer alguien y dónde termina esta entrega. No hace falta escribir una especificación enorme: tres ejemplos concretos pueden orientar mejor que una página de adjetivos.

Prueba esta estructura: objetivo + contexto + límites + criterios de aceptación. Es mi plantilla de trabajo para este ejemplo:

Objetivo: crear la primera versión de Taskboard.
Contexto: Next.js App Router, TypeScript y Tailwind.
Alcance: una pantalla; datos en memoria; sin cuentas ni servidor.

Criterios de aceptación:
1. Puedo crear una tarea con un título no vacío.
2. Puedo marcarla como hecha y volver a dejarla pendiente.
3. Puedo filtrar todas, pendientes y completadas.

Incluye un estado vacío y controles utilizables con teclado.
Antes de editar, enumera los archivos que cambiarías.
Al terminar, indica cómo comprobar cada criterio.

Fíjate en «datos en memoria»: al recargar, las tareas desaparecerán. No es un fallo escondido, sino una decisión explícita para que la primera entrega sea pequeña. La persistencia será el siguiente paso. Así puedes probar el flujo antes de añadir cuentas, base de datos y despliegue.

Si la propuesta crece demasiado, vuelve al caso de uso: «Por ahora, implementa solo crear y completar; deja los filtros para la siguiente entrega». El tamaño del cambio también forma parte del encargo.

03. Dale buenas reglas al proyecto

CLAUDE.md puede recoger instrucciones estables; .claude/rules/ permite organizarlas y acotarlas con paths. Son contexto para el modelo, no barreras de seguridad. Referencia de instrucciones y memoria.

Dentro de Claude Code, /init ayuda a preparar un punto de partida. Léelo después como si fuese la incorporación de una persona al equipo: ¿podría localizar el código y saber qué comprobar? Quita frases vacías como «escribe buen código» y añade decisiones concretas de tu proyecto.

Esta plantilla de CLAUDE.md es un ejemplo editable, no una descripción de tu repositorio actual:

# Taskboard

## Producto
Un tablero personal para crear tareas, completarlas y filtrarlas por estado.
Stack: Next.js App Router, TypeScript, Tailwind CSS.

## Acuerdos de trabajo
- Revisa el repositorio antes de proponer archivos o dependencias.
- Entrega un flujo de usuario pequeño cada vez.
- Mantén los secretos fuera del código y de los ejemplos generados.
- Consulta antes de añadir una dependencia o cambiar un contrato público.

## Comprobaciones
Confirma que estos scripts existen en package.json antes de utilizarlos:
- npm run typecheck
- npm test
- npm run build

## Criterio de entrega
Resume qué cambió, qué se comprobó y qué queda pendiente.

Los nombres de los scripts deben existir en package.json. Si aún no hay pruebas, escribe ese hecho y decide qué comprobación necesitas; pedir «ejecuta todos los tests» no crea una suite por sí solo.

Para la interfaz de Taskboard, guardaría esta convención en .claude/rules/frontend.md:

---
paths:
  - "src/app/**/*.tsx"
  - "src/components/**/*.tsx"
---

# Convenciones de interfaz
- Usa HTML semántico y controles con etiqueta.
- Incluye estados vacíos, de carga y de error cuando sean necesarios.
- Mantén la lógica de negocio fuera de los componentes de presentación.

Los patrones son relativos al proyecto. Ajusta las rutas si tu aplicación no utiliza src/. Mi criterio: una norma debe explicar una decisión útil; si repites el mismo párrafo en cinco sitios, simplifica antes de añadir otra regla.

04. Convierte un buen procedimiento en una skill

Una skill empaqueta instrucciones reutilizables en un SKILL.md. En este ejemplo, disable-model-invocation: true hace que la ejecutes expresamente; $ARGUMENTS recibe tu petición. Referencia oficial de skills.

Crea .claude/skills/feature-plan/SKILL.md con este contenido:

---
name: feature-plan
description: Prepara un plan pequeño y verificable para una función del repositorio.
argument-hint: "[funcionalidad]"
disable-model-invocation: true
---

Planifica esta función: $ARGUMENTS

1. Lee CLAUDE.md y revisa los archivos relacionados.
2. Define el objetivo y criterios de aceptación observables.
3. Enumera los cambios mínimos y las pruebas existentes que utilizarás.
4. Identifica las decisiones que necesita tomar el desarrollador.
5. Devuelve el plan; no lo implementes en este paso.

Después, escribe esto dentro de Claude Code:

/feature-plan Añadir filtros de tareas pendientes y completadas

La ventaja práctica es la repetición: la próxima funcionalidad empieza con los mismos criterios de calidad. Una skill útil describe pasos y una salida esperada. «Sé un desarrollador experto» no te dice qué revisar; «enumera criterios, archivos y comprobaciones» sí.

El nombre y la descripción deben ayudar a reconocer cuándo usarla. Las skills también pueden activarse automáticamente según su configuración. allowed-tools preautoriza herramientas; no convierte por sí solo la skill en un entorno de solo lectura. Si vienes de .claude/commands/, esos comandos personalizados siguen siendo compatibles. Configuración e invocación.

05. Construye, comprueba, repite

Imagina que el primer tablero ya funciona. El siguiente encargo será conservar las tareas al recargar. Antes de pedir código, define qué significa «conservar»: en este navegador, entre dispositivos o para varias personas. Cada opción tiene consecuencias distintas.

Para seguir con una versión local, esta petición deja una prueba muy fácil de reproducir:

Añade persistencia local al tablero actual.
Reutiliza la estructura existente y evita nuevas dependencias.

Comprueba estos casos:
- Creo una tarea, recargo y sigue apareciendo.
- Marco una tarea como hecha, recargo y conserva su estado.
- Si los datos guardados no son válidos, la app muestra
  un estado recuperable y no se rompe al abrirse.

Antes de implementar, señala cualquier problema de hidratación
que debamos tener en cuenta con Next.js.
Después, muestra el diff y las comprobaciones realizadas.

Mi ciclo recomendado tiene cuatro pasos: entender → proponer → cambiar → verificar. Lee el diff, ejecuta las comprobaciones reales y prueba los tres casos con el navegador. Una respuesta convincente no demuestra que la funcionalidad funcione. La guía de buenas prácticas insiste en dar a Claude formas de verificar su trabajo.

Cuando algo falle, comparte evidencia: acción exacta, resultado esperado, resultado observado y error. Por ejemplo: «Al recargar después de completar una tarea, vuelve a pendiente; esperaba que siguiera completada». Es una pista de depuración mucho mejor que «la persistencia está mal».

Un pequeño reto: antes de continuar, inventa un caso que rompa tu primera solución. ¿Un título con espacios? ¿Datos antiguos en el almacenamiento? ¿Dos tareas con el mismo texto? Ahí empieza una revisión interesante.

06. Permisos, hooks y ayuda extra

Permisos: define qué requiere revisión

Las preferencias compartidas van en .claude/settings.json; las personales pueden ir en .claude/settings.local.json. Si creas el archivo local manualmente, exclúyelo del repositorio. Ubicaciones y configuración.

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(secrets/**)"
    ],
    "ask": [
      "Bash(git push *)",
      "PowerShell(git push *)"
    ]
  }
}

Este ejemplo deniega lecturas coincidentes y solicita confirmación para los comandos de subida indicados. Revísalo con /permissions. Las reglas Read cubren herramientas de archivos y ciertos comandos reconocidos, no cualquier acceso de un subproceso. Alcance de los permisos. Para aislamiento a nivel de proceso, consulta sandboxing.

Hooks: automatiza una comprobación concreta

Un hook reacciona a un evento. Este ejemplo opcional lanza npm run check tras Edit o Write: úsalo únicamente si ese script existe y es suficientemente rápido. Integra la clave hooks en tu configuración, conservando permissions.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run check",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

PostToolUse actúa después: puede informar de un fallo, pero no deshace la edición. Para bloquear una acción antes de ejecutarla, revisa PreToolUse. Guía de hooks. No se incluye este hook en el kit para evitar lanzar un script que todavía no has configurado.

Subagentes: una revisión con una tarea acotada

Un subagente permite dedicar un contexto a una tarea. Guarda este ejemplo en .claude/agents/task-reviewer.md; su lista de herramientas permite inspeccionar archivos sin darle herramientas de edición ni terminal. Referencia de subagentes.

---
name: task-reviewer
description: Revisa una funcionalidad terminada frente a sus criterios de aceptación.
tools: Read, Grep, Glob
---

Lee el código relevante y busca errores, casos límite y criterios sin cubrir.
Devuelve hallazgos con archivo y motivo. No modifiques archivos.
Si falta evidencia, indícalo; no afirmes que has ejecutado pruebas.

Puedes pedir una revisión de la funcionalidad con ese subagente y contrastar sus hallazgos. Una segunda lectura ayuda a encontrar puntos ciegos; no sustituye probar el flujo. Este ejemplo hace revisión estática y no puede ejecutar tu suite.

MCP: cuando el contexto vive fuera del repositorio

MCP conecta herramientas y datos externos. Una skill describe cómo trabajar; una conexión MCP proporciona acceso a un servicio. Consulta qué expone cada integración y revísala con /mcp. Guía de MCP. Para Taskboard no hace falta conectar nada: añade una integración cuando una necesidad concreta la justifique.

07. Prepara tu kit de instrucciones

Ahora sí: adapta el nombre, la tecnología y el gestor de paquetes. Puedes copiar un archivo o descargar los cuatro en un ZIP. El kit contiene instrucciones, no el código de una aplicación. Descomprímelo aparte, compara su contenido con tus archivos y fusiona los cambios que te sirvan; no sobrescribas una configuración existente a ciegas.

Para un equipo, acordad qué merece compartirse. Las convenciones del producto suelen pertenecer al repositorio; una ruta exclusiva de tu ordenador no ayuda a otra persona. Después de cambiar instrucciones, prueba una tarea pequeña y comprueba si la salida mejora de una forma observable.

08. Cheatsheet: el comando que necesitas

Guarda esta sección. Busca por intención, filtra por tipo de tarea y copia el comando. Los que empiezan por claude se ejecutan en la terminal; los que empiezan por /, dentro de la sesión. CLI y comandos oficiales.

Ver todos los comandos en una tabla

Dónde	Comando	Para qué sirve
Terminal	claude	Abrir sesión interactiva
Terminal	claude --permission-mode plan	Iniciar en modo de planificación
Terminal	claude -p "Resume la arquitectura del proyecto"	Consulta no interactiva
Claude Code	/help	Ver los comandos disponibles
Claude Code	/init	Preparar el CLAUDE.md inicial
Claude Code	/memory	Revisar instrucciones y memoria
Claude Code	/plan	Planificar antes de editar
Claude Code	/permissions	Inspeccionar permisos
Claude Code	/context	Consultar el uso del contexto
Claude Code	/compact	Resumir la conversación actual
Claude Code	/resume	Retomar una conversación
Claude Code	/doctor	Diagnosticar la instalación
Claude Code	/agents	Gestionar subagentes
Claude Code	/mcp	Revisar conexiones MCP

/context ayuda a ver en qué se utiliza el contexto; /compact resume la conversación. Conserva las decisiones duraderas en tus archivos del proyecto. Si un comando no coincide con tu versión, consulta /help y la referencia actual. Referencia de sesión.

09. Los tropiezos que merece la pena evitar

«He añadido veinte reglas y el resultado empeora»

Busca contradicciones y normas que ya no describan el repositorio. Prueba una sola tarea antes y después de simplificar. Mi regla de edición: si una instrucción no cambia una decisión, probablemente no necesita estar ahí.

«¿Necesito una skill para cada prompt?»

Empieza con una petición normal. Cuando repitas un procedimiento y puedas explicar su entrada y su salida, conviértelo en skill. En Taskboard, planificar funcionalidades se repite; corregir una errata aislada apenas gana nada con una plantilla.

«Dice que está listo, ¿puedo publicarlo?»

Lee qué se ha comprobado realmente. Distingue «he escrito una prueba» de «he ejecutado la prueba y pasa». Antes de compartir una app, revisa los estados vacíos y de error, el uso con teclado, el comportamiento móvil y cualquier dato sensible. Para esta primera versión, además, explica que los datos permanecen en un solo navegador.

«No soy experto: ¿también puedo seguirlo?»

Sí: reduce el alcance y pide explicaciones ligadas al código que estás viendo. Por ejemplo: «Antes de cambiar esta función, explícame qué recibe, qué devuelve y cómo puedo comprobarla». Puedes avanzar aprendiendo, siempre que verifiques los pasos y entiendas las decisiones que estás aceptando.

«¿Claude Code y el chat de Claude son lo mismo?»

Esta guía se centra en Claude Code y en su trabajo con un proyecto. Los archivos, permisos y comandos mostrados corresponden a esa herramienta; no asumas que pegar un SKILL.md en cualquier conversación activa la misma configuración. Punto de partida oficial.

10. Tu checklist antes de la siguiente entrega

Marca lo que ya tienes. La lista guarda el progreso en este navegador y lo conserva al cambiar entre castellano e inglés. Úsala como recordatorio de tu revisión, no como una certificación automática del código.

Para empezar hoy, basta con una entrega pequeña: crea una tarea, comprueba qué ocurre y mejora el siguiente paso. Un repositorio comprensible y una prueba concreta de que algo funciona tienen más valor que una carpeta llena de instrucciones que nadie ha contrastado.

Documentación para seguir profundizando

Esta entrada es una guía independiente con ejemplos originales; no es documentación oficial de Anthropic. Consulta las referencias para las opciones disponibles en tu versión:

• Instalación y primer uso · Flujos de trabajo
• CLAUDE.md, rules y memoria · Skills y argumentos
• Settings · Permisos · Sandboxing
• Hooks · Subagentes · MCP
• Referencia del CLI · Comandos de sesión · Buenas prácticas