Acá hay dos cosas: errores de método (cómo le pedís a Claude Code) y errores técnicos reales (los mensajes que te van a saltar en pantalla). Los dos te frenan. Los dos tienen solución.

📌 Nivel 1 de la ruta: Empezar

Paso 0 — Antes de arrancar

Para seguir esta guía necesitás Claude Code andando:

• Node instalado (nodejs.org, LTS) → verificá con node -v. • Cuenta de Claude → plan Pro (~20 USD/mes) o Max. • Instalado → npm install -g @anthropic-ai/claude-code, después claude dentro de tu carpeta y login en el navegador con tu cuenta (no API key — eso factura por token y sale más caro).

Si todavía no lo tenés, arrancá por Cómo iniciar cualquier proyecto con Claude Code.

Parte 1 — Errores de método

Estos 10 caen en tres fases: definir, construir, validar. Si los ves agrupados así, te das cuenta más rápido de en cuál estás fallando.

1. Problema mal definido

Cómo se ve cuando lo cometés

Le pediste "una app de turnos" y Claude arrancó a construir cosas que vos no querías. Estás corrigiendo rumbo en cada respuesta.

Solución

Obligar claridad antes de escribir código.

Prompt

Quiero que actúes como un arquitecto de software senior.

Antes de escribir código, haceme todas las preguntas necesarias para definir con claridad:
- Qué estoy construyendo
- Para quién
- Qué problema resuelve
- Qué resultado final espero

No avances hasta tener total claridad.

Resultado

Un scope claro que evita el 80% de errores.

2. Prompts vagos o genéricos

Solución

Dar contexto + objetivo + restricciones.

Prompt

Quiero que construyas [X].

Contexto:
- Proyecto: [descripción]
- Stack: [tecnologías]
- Objetivo: [resultado esperado]

Restricciones:
- Mantené el código simple
- No agregues complejidad innecesaria

Generá una solución clara y funcional.

Resultado

Outputs más precisos y alineados.

3. No usar CLAUDE.md

Solución

Crear el "cerebro" del proyecto desde el inicio.

Prompt

Creá un archivo CLAUDE.md para este proyecto.

Incluí:
- Descripción
- Objetivo
- Usuario
- Stack
- Arquitectura
- Reglas (qué hacer y qué evitar)
- Convenciones
- Cómo correr el proyecto

Resultado

Claude toma mejores decisiones en todo momento.

4. Empezar sin plan

Solución

Nunca codear sin roadmap.

Prompt

Generá un plan completo del proyecto.

Dividilo en features pequeñas.

Para cada feature incluí:
- Qué hace
- Archivos involucrados
- Orden de implementación

No escribas código todavía.

Resultado

Dirección clara y ejecución ordenada.

5. No dividir en features

Solución

Trabajar siempre en bloques pequeños.

Prompt

Dividí este proyecto en features independientes y pequeñas.

Cada una debe poder desarrollarse y testearse por separado.

Resultado

Menos errores y más control.

6. No validar cada paso

Solución

Forzar validación constante.

Prompt

Generá esta feature y agregá:
- Validaciones básicas
- Manejo de errores
- Cómo testearla manualmente

Resultado

Menos bugs acumulados.

7. Sobrecargar contexto

Solución

Mantener prompts limpios y enfocados.

Prompt

Resumí el contexto actual del proyecto en lo mínimo necesario para seguir trabajando correctamente.

Resultado

Claude responde con más precisión.

8. No refinar prompts

Solución

Iterar como si fuera un sistema, no magia.

Prompt

Este fue el resultado anterior: [output]

No es lo que esperaba por esto:
[explicación]

Corregilo manteniendo lo que sí funciona y mejorando lo demás.

Resultado

Mejora progresiva del output.

9. Cambiar constantemente de dirección

Solución

Re-alinear antes de seguir.

Prompt

Hubo cambios en el proyecto.

Actualizá el plan y el enfoque en base a este nuevo objetivo:
[explicación]

Mostrame cómo seguimos desde acá.

Resultado

Evita código roto o incoherente.

10. Confiar ciegamente en el output

Solución

Usar a Claude como builder + reviewer.

Prompt

Revisá este código como si fueras un senior.

Detectá:
- Errores
- Malas prácticas
- Problemas de escalabilidad

Proponé mejoras concretas.

Resultado

Código más sólido y profesional.

11. No cerrar el alcance con el cliente (el error que te cuesta plata)

Cómo se ve cuando lo cometés

Arrancaste a construir, el cliente pidió "una cosita más", después otra, y ahora estás trabajando gratis el doble de horas. Eso es scope creep y es el error #1 del que vende.

Solución

Cerrar por escrito qué entrás, qué no entrás y cuántas revisiones, antes de tocar código.

Prompt

Voy a venderle [solución] a [tipo de negocio].

Armame un documento corto de alcance que pueda mandarle al cliente:
- Qué incluye exactamente (lista cerrada)
- Qué NO incluye (para evitar pedidos extra)
- Cuántas rondas de revisión entran
- Qué cuesta cada cosa fuera de alcance

Tono claro y directo, en español rioplatense.

Resultado

Un alcance firmado. Cada pedido extra ahora se cobra aparte, sin discusión.

Parte 2 — Errores técnicos reales y cómo salir

Estos no son de método. Son los mensajes literales que vas a ver en pantalla. El público suele estar en Windows, así que la mayoría apuntan ahí.

A. 'npm' no se reconoce como comando

Node no quedó en el PATH.

→ Cerrá y reabrí la terminal (a veces alcanza). → Si sigue, reinstalá Node desde nodejs.org (LTS) y reiniciá la máquina. → Verificá con node -v y npm -v.

B. Error de permisos al instalar con -g

En Windows npm install -g puede fallar por permisos.

→ Abrí PowerShell como administrador (clic derecho → "Ejecutar como administrador"). → Volvé a correr npm install -g @anthropic-ai/claude-code.

C. Rutas con espacios o C:\Users\...

Si el comando rompe al entrar a una carpeta con espacios en el nombre:

→ Metela entre comillas: cd "C:\Users\Tu Nombre\proyecto".

D. "Context low" / el agente se queda sin contexto

En sesiones largas Claude Code se llena de contexto y pierde precisión.

→ Pedile: Resumí el estado actual del proyecto y arrancá una sesión limpia con ese resumen. → Para proyectos largos, instalá memoria persistente (Nivel 3: claude-mem).

E. El agente pide aprobar cada comando

No es un error: es seguridad. Al principio te pide permiso para cada acción.

→ Cuando confíes en lo que hace, podés aprobar acciones repetidas para que no te corte el flujo. No le des permiso total a ciegas en un proyecto con datos reales.

F. Un MCP no conecta

Si conectaste un MCP y no aparece o tira error:

→ Reiniciá Claude Code (cerrá y volvé a correr claude). → Revisá que la API key o el endpoint del MCP estén bien escritos. → En Windows, el firewall o el antivirus pueden bloquear el proceso en background: dale permiso cuando lo pida. → Qué es un MCP y cómo se conecta bien lo cubrimos en el Nivel 2: Qué es un MCP.

Sistema final

Para qué te sirve esto si vendés

Cada error de esta lista, en un proyecto pagado, se traduce en plata.

→ Problema mal definido o sin alcance cerrado → trabajás gratis y el cliente queda disconforme igual. → Confiar ciegamente en el output → entregás algo con bugs y quemás tu reputación (mala reseña, pedido de reembolso). → Errores técnicos sin resolver → te trabás, entregás tarde, perdés al cliente.

Saber salir rápido de cada uno es lo que te deja entregar en tiempo y cobrar como profesional.

Tu turno

Repasá la semana: ¿cuántos de estos 11 errores cometiste? Sé honesto.

Checklist de autodiagnóstico:

• [ ] ¿Arrancaste a codear algo sin definir bien el problema? • [ ] ¿Le tiraste un prompt vago y zafaste con lo que salió? • [ ] ¿Tenés CLAUDE.md y plan en tu último proyecto? • [ ] ¿Cerraste el alcance por escrito antes de prometerle algo a alguien? • [ ] ¿Te trabaste con un error técnico y no supiste de dónde venía?

Cada casilla sin tildar es un punto a corregir esta semana. Elegí uno y aplicá su prompt hoy.

Siguiente paso

Terminaste el Nivel 1. Ahora pasás a Fundamentos: entender qué es un MCP, la pieza que convierte la IA en algo que ejecuta de verdad (y que vas a vender).

→ Qué es un MCP y cómo convierte la IA en un asistente operativo

La mejor comunidad de IA

Esto no termina acá. En la comunidad compartimos lo que funciona de verdad: proyectos reales, precios que cierran y los nudos de llevar esto a clientes que pagan.

→ Sumate a la comunidad de WhatsApp 🚀