Claude Code: los prompts y workflows que de verdad funcionan en 2026

TL;DR

El 80% del éxito con Claude Code no es el prompt, es el contexto: CLAUDE.md, .claudeignore y reglas bien definidas.
El workflow que funciona: Explorar → Planificar → Implementar → Verificar → Commit. No saltes pasos.
Usa Plan Mode (Mayús+Tab x2) para todo lo que toque más de 3 archivos.
La regla de las dos correcciones: si corriges lo mismo dos veces, /clear y empieza de nuevo con mejor prompt.
Hooks, subagentes y sesiones paralelas son multiplicadores de productividad si sabes cuándo usar cada uno.

Contexto

Claude Code es el coding agent que más momentum tiene en 2026. Pero la mayoría de devs lo usan como un chat glorificado: le pegan errores del stack trace y esperan milagros.

Eso funciona el 60% del tiempo. El otro 40% te deja con código que compila pero hace cosas raras, sesiones de contexto que se degradan, y la sensación de que podrías haberlo escrito tú más rápido.

Después de meses usándolo en proyectos reales, esto es lo que funciona de verdad.

1. CLAUDE.md: tu inversión más rentable

Si solo haces una cosa después de leer esto, que sea escribir un buen CLAUDE.md.

Es el archivo que Claude lee al inicio de cada sesión. Piensa en él como el README para tu agente, no como documentación para humanos.

La regla de oro

Para cada línea de CLAUDE.md, pregúntate: “¿Si quito esto, Claude cometería un error?” Si la respuesta es no, bórralo.

Ejemplo real

# Mi proyecto

## Stack
- Next.js 15 (App Router, output: export)
- TypeScript strict
- Tailwind CSS v4
- Contenido MDX con gray-matter

## Reglas
- Siempre TypeScript, nunca JS suelto
- Componentes server por defecto, 'use client' solo cuando sea necesario
- Tests con Vitest, colocados junto al código fuente
- No editar migraciones de base de datos sin preguntar
- No cambiar la API pública sin mencionarlo explícitamente

## Comandos
- Dev: `pnpm dev`
- Build: `pnpm build`
- Tests: `pnpm test`
- Lint: `pnpm lint`
- Test de un archivo: `pnpm test path/to/file.test.ts`

## Estructura
- `/src/app/` — páginas y rutas
- `/src/components/` — componentes React
- `/src/lib/` — utilidades y lógica compartida
- `/src/content/` — archivos MDX de contenido

Jerarquía de archivos

Claude Code soporta tres niveles:

~/.claude/CLAUDE.md — reglas globales (tu estilo personal).
./CLAUDE.md — reglas del proyecto (se commitea al repo).
./CLAUDE.local.md — reglas personales que no se commitean (gitignored).

El proyecto hereda de tu global, y el local se superpone encima. Útil para cosas como “en este proyecto prefiero usar pnpm pero a nivel global uso npm”.

`.claudeignore`: no contamines el contexto

Claude paga por cada token que lee. Si le dejas escanear node_modules/, .next/ o coverage/, estás tirando dinero y degradando la calidad de las respuestas.

node_modules/
dist/
.next/
__pycache__/
*.lock
coverage/
*.png
*.jpg
*.min.js

Claude Code es ~5.5x más eficiente que Cursor en uso de tokens, pero solo si le ayudas a no leer basura.

2. El workflow que funciona: Explorar → Planificar → Implementar

El error más común: abrir Claude Code y decirle “implementa el sistema de notificaciones”. Resultado: código que no encaja con tu arquitectura, porque Claude no la conoce.

Paso 1: Explorar (Plan Mode)

Activa Plan Mode con Mayús+Tab dos veces. En este modo Claude lee archivos pero no modifica nada.

Lee /src/auth y /src/session. Explica cómo funciona
el flujo de autenticación actual.

Espera. Lee la respuesta. Verifica que entendió.

Paso 2: Planificar

Basándote en lo que leíste, haz un plan detallado para
implementar notificaciones push. Incluye:
- Archivos a crear y modificar
- Cambios en la API
- Migraciones necesarias
- Riesgos o trade-offs

No escribas código todavía.

Pulsa Ctrl+G para abrir el plan en tu editor. Edítalo. Añade lo que falte. Esto es oro: estás alineando expectativas antes de que Claude escriba una sola línea.

Paso 3: Implementar

Cambia a modo normal. Ejecuta el plan.

Implementa el plan. Después de cada cambio significativo,
ejecuta los tests y reporta el resultado.

Paso 4: Verificar

Ejecuta pnpm build y pnpm test. Reporta cualquier error.
Si hay tests que fallan, arréglalos y vuelve a ejecutar.

Cuándo saltarse el planning

Para tareas triviales (typos, renombres, un solo archivo), Plan Mode es overhead. Directo a implementar.

Si la tarea toca más de 3 archivos: siempre planifica primero.

3. Prompts que funcionan vs. prompts que no

El patrón: qué + por qué + verificación

Débil:

Arregla el bug del login.

Fuerte:

Los usuarios se desloguean al refrescar el dashboard.
Inspecciona src/auth y src/session.
Escribe un test que falle que reproduzca el problema.
Arregla la causa raíz sin cambiar la API pública de auth.
Ejecuta los tests de auth y reporta el resultado exacto.

La diferencia: le das contexto del problema, le dices dónde buscar, le pides un test de regresión, le das una restricción (no cambiar la API), y le exiges verificación.

La regla de la verificación

“Incluye tests, capturas de pantalla o outputs esperados para que Claude pueda verificar su propio trabajo.”

Esto es lo que Anthropic llama la regla de oro de Claude Code. Y funciona:

En vez de “implementa X”, di “implementa X; aquí están los test cases: [lista]. Ejecuta los tests después.”
Para UI: usa la extensión de Chrome para capturar screenshots y pedirle a Claude que compare.
Para bugs: pide que arregle la causa raíz, no que suprima el síntoma.

El patrón de referencia

No le describas cómo quieres algo. Enséñale un ejemplo:

Mira /api/teams y sigue el mismo patrón para la nueva
ruta de /api/notifications.

Esto es 10x más efectivo que intentar describir tu convención de API en palabras.

El patrón de entrevista

Para features grandes, pide a Claude que te entreviste a ti:

Quiero construir [descripción breve]. Entrevístame en detalle
usando la herramienta AskUserQuestion.

Pregunta sobre implementación técnica, UI/UX, edge cases,
preocupaciones y trade-offs. No preguntes lo obvio —
indaga en las partes difíciles que podría no haber considerado.

Sigue entrevistando hasta que hayamos cubierto todo,
luego escribe un spec completo en SPEC.md.

Esto previene el “efecto mariposa”: un pequeño malentendido al inicio que se convierte en un desastre arquitectónico tres PRs después.

4. Gestión de contexto: la skill que separa principiantes de avanzados

El contexto de Claude Code es finito. Cada mensaje, cada archivo que lee, cada output de comando — todo suma. Cuando se llena, Claude “olvida” instrucciones y degrada su rendimiento.

Comandos esenciales

Comando	Cuándo usarlo	Efecto
`/clear`	Entre tareas no relacionadas	Resetea todo el contexto
`/compact`	Cuando el contexto está al 70%+	Resume preservando lo clave
`Esc + Esc`	Recuperación mid-session	Vuelve a un checkpoint
`/compact Enfócate en los cambios de API`	Antes de una subtarea	Resume con sesgo hacia lo que importa

La regla de las dos correcciones

Si has corregido a Claude más de dos veces en el mismo problema, el contexto está contaminado. Haz /clear y empieza con un prompt mejor.

No perseveres en una sesión degradada. Es contraproducente.

`/btw`: preguntas sin contaminar

El comando /btw te permite hacer preguntas “por cierto” que no entran en el historial de conversación. Útil para consultar algo rápido sin gastar contexto.

5. Hooks: automatización determinista

Los hooks ejecutan comandos automáticamente cuando Claude hace ciertas acciones. Son deterministas: no dependen de que Claude “recuerde” hacer algo.

Auto-lint después de edits

En .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "pnpm lint --fix $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Ahora cada vez que Claude edita un archivo, el linter se ejecuta automáticamente. No más “recuerda ejecutar lint”.

Formateo automático

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Cuándo usar hooks vs. cuándo usar reglas

Hook: algo que DEBE pasar siempre (lint, formato, tests después de cambios).
Regla en CLAUDE.md: algo que Claude debe tener en cuenta pero que requiere juicio (convenciones de naming, arquitectura).

6. Subagentes y sesiones paralelas

Subagentes para investigación

Los subagentes corren en ventanas de contexto separadas y devuelven solo un resumen. Ahorran ~40% de tokens de input.

Usa un subagente para investigar cómo funciona el sistema
de pagos en este codebase. Busca en src/payments/,
src/webhooks/ y src/billing/. Reporta un resumen de:
- Flujo principal
- Edge cases encontrados
- Dependencias externas

Tu sesión principal permanece limpia para implementar.

El patrón Writer/Reviewer

Sesión A (Writer): Implementa el feature.
Sesión B (Reviewer): Sesión fresca que revisa el diff buscando edge cases y bugs de seguridad.

# En una sesión fresca:
Revisa los últimos cambios en este repo (git diff HEAD~1).
Busca:
- Bugs de seguridad (inyección SQL, XSS, auth)
- Edge cases no manejados
- Código muerto o importaciones no usadas
- Cambios que rompan la API pública

El código generado por IA tiene 1.5-2x más bugs de seguridad que el código humano. Una segunda opinión fresca vale la pena.

Sesiones paralelas con fan-out

Para features grandes, divide y vencerás:

# Terminal 1: Backend
claude --session auth-backend
> Implementa la API de notificaciones en /api/notifications

# Terminal 2: Frontend  
claude --session auth-frontend
> Implementa el componente de notificaciones en /src/components/notifications

# Terminal 3: Tests
claude --session auth-tests
> Escribe tests de integración para el sistema de notificaciones

Cada sesión tiene contexto aislado. Resuelve la degradación de contexto en tareas grandes.

7. Comandos personalizados

Puedes crear atajos en .claude/commands/ para flujos repetitivos.

`.claude/commands/new-feature.md`

Estoy empezando una nueva feature: $ARGUMENTS

1. Entrevístame sobre lo que necesito usando AskUserQuestion
2. Escribe un spec en SPEC.md
3. Haz un plan de implementación
4. Espera mi aprobación antes de escribir código

Uso: /new-feature sistema de notificaciones push

`.claude/commands/review.md`

Revisa los cambios no commiteados en este repo.
Busca:
- Bugs de seguridad
- Edge cases no manejados
- Código que no sigue las convenciones del proyecto
- Tests faltantes para código nuevo

Reporta un resumen con severidad (crítico/medio/bajo).

`.claude/commands/fix-test.md`

El test $ARGUMENTS está fallando.

1. Ejecuta el test y captura el error
2. Investiga la causa raíz
3. Propón un fix
4. No implementes hasta que yo apruebe

8. Costes reales y cómo optimizarlos

Claude Code no es barato. Una sesión de refactoring puede costar $2-5 en API. Un feature grande puede llegar a $10-20.

Estrategias de ahorro

CLAUDE.md completo: evita repetir contexto en cada prompt.
.claudeignore agresivo: no pagues por tokens que no necesita.
Plan Mode para exploración: en Plan Mode, Claude solo lee y piensa. Más barato que implementar y corregir.
/compact regular: reduce el contexto antes de que crezca demasiado.
Subagentes para investigación: ahorra ~40% de tokens vs. investigar en la sesión principal.
Plan de $20/mes (Pro): para uso regular, el plan Pro con límites generosos suele ser más económico que API pura.

El espectro de delegación

No delegues todo igual. Clasifica por riesgo:

Riesgo	Delegar libremente	Supervisar de cerca
Código	Boilerplate, scaffolding	Auth, pagos, mutaciones de datos
Refactoring	Renombres, formato	Contratos de API, lógica de seguridad
Debugging	Errores de lint/tipo	Race conditions, memory leaks

Problemas comunes

Claude hace cambios que no pediste: Añade a tu prompt: “Solo cambia los archivos necesarios para esta tarea. No refactorices componentes no relacionados.”

Claude “olvida” instrucciones a mitad de sesión: El contexto se llenó. Haz /compact o /clear y reformula.

Claude repite el mismo error: Dos correcciones y sigue igual → /clear y empieza de nuevo con un prompt más específico.

Los costes se disparan: Revisa tu .claudeignore. Comprueba si Claude está leyendo archivos innecesarios. Usa --model para tareas simples.

Claude no encuentra el bug: No le pegues el error. Dale contexto: qué esperabas, qué pasó, dónde miraste, qué descartaste. Pídele que escriba un test que reproduzca el problema antes de intentar arreglarlo.

Siguientes pasos

Si nunca has usado Claude Code: instala, ejecuta /init en tu proyecto, y prueba el workflow Explorar → Planificar → Implementar con una tarea pequeña.
Si ya lo usas: revisa tu CLAUDE.md con la regla de oro. ¿Cada línea previene un error concreto? Si no, simplifica.
Para ir más profundo: configura hooks, crea comandos personalizados, y prueba el patrón Writer/Reviewer en tu próximo PR.

Fuentes: Anthropic Best Practices, MorphLLM Guide, AIorg 15 Tips, DIY AI Rules