Te sabes los comandos de Claude Code pero te quedas paralizado: cómo dar el primer paso seguro

El viernes por la noche un compañero me escribió por Slack: “Ya me sé todos los comandos de Claude Code, pero no sé qué escribir después y me quedo bloqueado.” Sabe decir /init, /clear y claude -p de memoria. Y aun así, cuando tiene su propio repositorio delante, los dedos se le congelan.

Esto no es un problema de capacidad. La chuleta de comandos es solo una lista de “nombres de herramientas”; no te dice qué hacer primero, hasta dónde llegar ni cómo comprobarlo antes de delegar. Por eso hay gente que, cuanto más memoriza, menos se atreve a moverse.

Este artículo trata justo de eso: cómo salir de ese “me lo sé pero me quedo quieto” dando el paso más pequeño posible.

Puntos clave

• Si te sabes los comandos y aun así te bloqueas, es porque no tienes definidas cuatro cosas: qué permites, qué archivos no se tocan, cómo se deshace y cómo se comprueba.
• Tu primer logro puede ser tan pequeño como “arreglar un solo párrafo” o “que te explique qué significa un test que falla”.
• Antes de delegar, pide “solo el plan, todavía no edites” y los accidentes se reducen drásticamente.
• Para comprobar, define de antemano un comando legible por máquina como git diff, no el ojo humano.
• Cuando ya tengas confianza, asciende a automático solo las operaciones que hayas verificado como seguras, poco a poco.

Por qué te paralizas aunque te sepas la tabla

La lista de comandos es, en términos de un mapa, como “el catálogo de señales de tráfico”. Aunque sepas el nombre de todas las señales, si no tienes claro el destino ni dónde girar, el coche no arranca.

A quien se bloquea no le falta conocimiento, le falta el hábito de poner en palabras estos cuatro puntos:

• Qué archivos dejas leer y cuáles no se tocan.
• Cuán pequeño recortas el primer cambio.
• Cuál es la condición que define “salió bien” (qué miras para saber que fue un éxito).
• Cómo vuelves atrás si algo falla.

Yo también empecé soltando un “deja este proyecto bonito” y me quedé congelado ante un diff con 30 archivos modificados. Un diff que no puedes leer no lo puedes revisar. Y un cambio que no puedes revisar da miedo adoptarlo. Por eso, al principio, lo correcto es empezar con algo ridículamente pequeño.

El primer paso puede ser así de pequeño

Cuando oyes “logro” tiendes a imaginar una gran funcionalidad nueva, pero al principio basta con este nivel:

• Mejorar la legibilidad de las 3 primeras líneas de la introducción del README.
• Añadir una sola frase al texto de aviso bajo un artículo.
• Que te explique qué significa un test que está fallando, sin arreglarlo.

El tercero es el que más recomiendo. Como no cambias ni una línea de código, no hay forma de romper nada. Y aun así obtienes la primera sensación real de “le hice leer mi repositorio a Claude Code y me devolvió una respuesta”. Quien está bloqueado debería empezar a mover los dedos justo por aquí.

Lo que delegas y lo que decides tú

El trabajo que delegas en Claude Code y la decisión que conservas tú conviene separarlos con claridad desde el principio. Si lo dejas ambiguo y lo pones a correr, casi siempre avanzará por su cuenta hasta donde debería decidir una persona.

Situación	Delegas en Claude Code	Decides tú
Definir alcance	Buscar y proponer archivos candidatos	Decisión final sobre qué se puede tocar
Editar	Borrador de texto y código	Si se adopta o no
Comprobar	Ejecutar tests, resumir el diff	Decidir si se puede publicar
Operación peligrosa	Solo proponer cómo hacerlo	Ejecutar borrados, despliegue a producción, cobros

La clave está en la columna de la derecha. Borrar, desplegar a producción, operaciones que mueven dinero y acciones difíciles de revertir como git push --force: al principio fíjalas todas en “lo aprieta una persona”. Solo lo que tú mismo hayas verificado como seguro lo vas moviendo después a la izquierda. Con solo respetar este orden, las noches con sudor frío se reducen muchísimo.

Pide primero “solo el plan”

El truco es no dejar que edite de golpe. En la primera petición, que no mueva las manos: que solo te diga el plan. Puedes pegar el siguiente prompt tal cual.

Voy a pedirte un solo cambio pequeño. Todavía NO edites nada.
Primero, devuélveme estos 4 puntos en forma de lista:

1. El archivo que vas a tocar (solo uno)
2. Los archivos que NO vas a tocar (nunca toques .env ni nada de autenticación o cobros)
3. El contenido del cambio (no cambies el comportamiento, solo el texto)
4. El comando con el que yo lo comprobaré después (por ejemplo git diff)

Empieza a editar solo después de que yo apruebe estos 4 puntos.

Mira los 4 puntos que te devuelve: si el archivo a tocar está reducido a uno y trae hasta el comando de comprobación, el tamaño de la petición es el adecuado. En cambio, si la respuesta es algo como “voy a revisar todo el repositorio”, es señal de que tu petición sigue siendo demasiado amplia. Estrecha el alcance y vuelve a pedirlo con el mismo formato.

Si sientes que no te sale escribir buenas peticiones, el diseño de prompts en Claude Code y cómo escribir tu CLAUDE.md son la base. Si le entregas antes las reglas del proyecto, la calidad del plan sube un nivel.

Checklist del primer paso, lista para copiar

Escribir esos 4 puntos en un archivo cada vez es engorroso. Por eso te dejo un pequeño script que genera una “nota del primer paso” solo con responder. Funciona si tienes Node.js.

// first-win.mjs — genera en 1 minuto una nota para verbalizar tu primer paso
// Uso: node first-win.mjs

const plan = {
  objetivo: "lograr 1 cambio pequeño y seguro con Claude Code",
  archivosATocar: ["README.md"],                 // reduce a uno
  archivosBloqueados: [".env", "autenticación", "cobros", "BD de producción"],
  primerComando: "git status --short",           // confirma el estado actual
  contenidoDelCambio: "mejorar 3 líneas de la introducción. No cambia el comportamiento",
  comoComprobar: "git diff -- README.md",         // ¿el diff es legible?
  comoRevertir: "git checkout -- README.md",      // si falla, rehacer al instante
};

// Comprobación: ¿el archivo a tocar está reducido a uno?
if (plan.archivosATocar.length !== 1) {
  console.error("⚠ Al principio reduce a un solo archivo");
  process.exit(1);
}

console.log("=== Nota del primer paso ===");
for (const [clave, valor] of Object.entries(plan)) {
  const texto = Array.isArray(valor) ? valor.join(", ") : valor;
  console.log(`${clave}: ${texto}`);
}
console.log("\nPega esta nota en Claude Code y pídele: 'devuelve el plan antes de editar'");

Ejecutarlo es solo esto:

node first-win.mjs

La nota que sale la pegas tal cual en Claude Code y la usas junto con el prompt de “solo el plan” de arriba. Como está hecho para detenerse en la primera línea si hay 2 o más archivos a tocar, también sirve de freno cuando te entran ganas de abarcar demasiado.

Tres usos que funcionaron de verdad

Te dejo tres ejemplos que yo y la gente a mi alrededor elegimos como “primer paso” y con los que de verdad avanzamos.

1. Arreglar la introducción del README. Para el lector que llega buscando comandos, simplifica solo las 3 primeras líneas. Como la comprobación se resuelve solo con git diff, obtienes en el menor tiempo posible la sensación de poder leer el diff. Aquí ganas confianza.

2. Añadir una frase al texto de aviso bajo un artículo. Donde la explicación sea pobre, añade solo una frase y comprueba en la URL pública que el enlace de destino sigue vivo. Como es un cambio solo de texto, no hay riesgo de romper código.

3. Hacer que explique qué significa un test que falla. Aquí no dejas que lo arregle. Pide solo tres cosas: “qué significa el error”, “qué archivos podrían estar relacionados” y “dónde debería mirar después una persona”. Es práctica para hacerte una idea de la causa sin tocar ni una línea de código.

Lo que tienen en común los tres es que la comprobación se acaba con un comando y que, aunque falle, vuelves atrás en un segundo. Si no eres desarrollador, leer también el uso de Claude Code para perfiles no técnicos te ayudará a elegir mejor un primer paso centrado en texto.

Errores comunes y cómo corregirlos

Error 1: pedir “mejora este repositorio” justo después de ver la tabla. El alcance es demasiado amplio y el diff que vuelve se vuelve ilegible. La corrección es simple: estrecha hasta “1 archivo, 1 párrafo”. Cuanto más estrecho, más seguro es tu primer logro.

Error 2: dejar la comprobación para después. Si lo pones a correr sin decidir qué mirar para saber que fue un éxito, aunque salga un resultado convincente no sabrás si puedes adoptarlo. Escribe desde el principio en la petición un comando de comprobación como git diff.

Error 3: delegar de golpe una operación peligrosa. Si automatizas desde el inicio borrar archivos o desplegar a producción, acabas en un accidente irreversible. Al principio fíjalo todo en “lo aprieta una persona” y asciende a automático solo lo que hayas verificado como seguro.

Preguntas frecuentes

P. ¿Cuántos comandos debería saberme antes de empezar? R. Con tres basta: /init, /clear y git diff para comprobar los cambios. El resto lo buscas cuando llegue el momento de usarlo y vas sobrado. Mover algo pequeño antes de memorizar es, al final, la forma más rápida de aprenderlo.

P. ¿Cuál es la tarea más adecuada para el primer paso? R. Hacer que “solo explique” qué significa un test que falla. Como no cambias código no hay forma de romper nada, y obtienes únicamente la sensación de hacerle leer el repositorio. El flujo básico también está recopilado en la guía de iniciación.

P. Pido el plan pero empieza a editar enseguida. R. Pon al principio del prompt “todavía NO edites nada” y al final añade “espera mi aprobación”. Si aun así avanza, suele ser porque el alcance del cambio es ambiguo, así que limita el archivo a tocar a uno, nombrándolo explícitamente.

P. ¿No basta con comprobar a ojo humano? R. En un día con prisas falla seguro. Si defines de antemano comprobaciones que entienda la máquina —número de caracteres, diff, resultado de los tests—, reduces los descuidos. El truco es reservar el juicio humano solo para “si se adopta o no”.

P. Cuando ya tenga confianza, ¿qué hago después? R. Amplía la misma “nota del primer paso” a una tarea algo mayor. Aunque crezcan los comandos de comprobación, no cambies el principio de que la persona controla las operaciones peligrosas. Para trabajar más rápido te servirán los consejos para subir la productividad.

Lo que comprobé al probarlo de verdad

A mi compañero del principio le hice empezar por el paso de “que solo explique qué significa un test que falla”. No tocar código. Lo que volvió fue el nombre del archivo causante y la ubicación de la función que debía mirar después. Dijo “esto sí lo puedo hacer” y ese mismo día llegó a corregir las 3 líneas del README.

Yo mismo, desde que dejé de soltarlo todo y empecé a intercalar el “devuelve solo el plan”, casi desapareció el tiempo que pasaba congelado ante un diff ilegible. No pedir más que lo que se puede comprobar con git diff; que la persona apriete las operaciones peligrosas. Con solo respetar estos dos puntos, el primer paso sale sorprendentemente ligero. No hace falta memorizar todos los comandos. Mueve algo pequeño y verifica el rango al que puedes volver atrás. Empezando por ahí es suficiente.

Si quieres llevar tu aprendizaje un paso más allá, mira el catálogo de materiales; si quieres asesorarte sobre cómo introducirlo en el trabajo de tu empresa, échale un ojo a formación y consultoría. Para el comportamiento detallado de los comandos, la documentación oficial es la fuente primaria más fiable.