---
name: workflow-claude-code
description: >
  Patrones de flujo de trabajo diario con Claude Code: gestión de sesiones,
  atajos de teclado, Plan Mode, feature-per-session, gestión de contexto,
  jerarquía de memoria, handoff multi-sesión, niveles de esfuerzo de Opus 4.7
  (high/xhigh/max) y el patrón de delegación. Cargar cuando el usuario pregunte
  cómo usar Claude Code eficientemente, cuando necesite optimizar su flujo de
  trabajo, o cuando inicie un proyecto nuevo. NO cargar para estructura de
  proyecto (usar estructura-proyecto-claude).
version: "1.1.0"
herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
exclusiones:
  - "No cargar para configurar la estructura de directorios de un proyecto Claude-ready; usar `estructura-proyecto-claude`."
  - "No cargar para resolver problemas de degradación de contexto en mitad de una sesión larga; en ese caso ejecutar `/swl:compactar` directamente."
  - "No cargar para consultar documentación de librerías o frameworks externos; usar Context7 MCP."
  - "No cargar para ajustar permisos de herramientas en settings.json; usar editar manualmente `.claude/settings.json` o `~/.claude/settings.json`."
evolvable: true  # default para skill estandar
---
# Workflow con Claude Code

Fuente: `referencias/Claude Code WorkFlow Cheatsheet.jpg` (2026 Edition)

Esta skill cubre CÓMO trabajar con Claude Code de forma efectiva.
Para ESTRUCTURA de proyecto, usar `estructura-proyecto-claude`.

## Cuándo cargar esta skill

- El usuario pregunta cómo usar Claude Code eficientemente
- Se necesita optimizar el flujo de trabajo diario
- Se inicia un proyecto nuevo y se necesita onboarding
- Hay problemas de contexto o productividad
- Se requiere handoff entre sesiones

## Cuándo NO cargar

- Se necesita estructura de archivos para un proyecto Claude-ready (CLAUDE.md, .claude/agents/, etc.); usar `estructura-proyecto-claude`.
- El contexto ya está al 70%+ y el usuario quiere compactar ahora mismo; ejecutar `/swl:compactar` sin cargar skills adicionales.
- El usuario pregunta por una librería específica (ej: "¿cómo uso FastAPI?"); la respuesta está en Context7 MCP, no en este skill de workflow.
- Se busca configurar hooks, permisos o settings.json; editar manualmente `.claude/settings.json` o `~/.claude/settings.json`.

---

## Patrón de flujo diario

```
1. cd proyecto && claude            # Iniciar sesion
2. Shift+Tab+Tab -> Plan Mode       # Entrar a Plan Mode
3. Describir intent de la feature    # Claude planea primero
4. Shift+Tab -> Auto Accept          # Cambiar a ejecucion
5. /compact cuando sea necesario     # Liberar contexto
6. Esc Esc + rewind si algo falla    # Retroceder
7. Commit frecuentemente             # Puntos de recuperacion
8. Nueva sesion por feature          # Contexto fresco
```

**Regla de oro**: Una sesión = una feature. Sesiones largas degradan la calidad.

---

## Modos de operación

### Plan Mode (Shift+Tab+Tab)

- Claude analiza y planifica ANTES de escribir código
- NO ejecuta herramientas — solo razona
- Usar para: features complejas, decisiones de arquitectura, debugging, cambios >5 archivos

### Auto Accept Mode (Shift+Tab)

- Claude ejecuta herramientas sin pedir confirmación
- Usar para: tareas bien definidas, generación de boilerplate, tests, después de aprobar plan

### Default Mode

- Claude pide confirmación antes de cada tool use
- Usar para: operaciones destructivas, deploy, cambios en producción

---

## Atajos de teclado esenciales

| Atajo | Acción |
|-------|--------|
| `Shift+Tab` | Toggle extended thinking / Auto Accept |
| `Shift+Tab+Tab` | Plan Mode |
| `Esc Esc` | Menú de rewind (deshacer último paso) |
| `Tab` | Toggle extended thinking |
| `/compact` | Compactar contexto |
| `/init` | Generar CLAUDE.md inicial |
| `/clear` | Limpiar sesión (nueva conversación) |
| `Ctrl+C` | Interrumpir operación actual |

---

## Gestión de contexto

### Rangos de uso

| Rango | Acción | Señal |
|-------|--------|-------|
| **0-40%** | Trabajar normalmente | Verde |
| **40-70%** | Monitorear — considerar compactar pronto | Amarillo |
| **70-90%** | Ejecutar `/compact` inmediatamente | Naranja |
| **90-100%** | `/clear` o nueva sesión obligatoria | Rojo |

### Señales de degradación de contexto (context rot)

- Claude repite preguntas que ya respondió
- Olvida decisiones tomadas anteriormente
- Genera código inconsistente con lo que acaba de escribir
- Más de 40 turnos en la conversación

### Estrategias anti context rot

1. **Una feature por sesión** — El patrón más importante
2. **Commits frecuentes** — Punto de recuperación ante compactación
3. **CLAUDE.md < 200 líneas** — Reduce carga base de contexto
4. **Subagentes** — Delegan trabajo a contextos frescos
5. **`.claude/rules/` con paths** — Carga lazy, solo lo necesario
6. **/compact proactivo** — No esperar a que se degrade

---

## Jerarquía de memoria

### CLAUDE.md en cascada

```
~/.claude/CLAUDE.md              # User — aplica a TODOS tus proyectos
   |
   +-- /CLAUDE.md                # Project — compartido via git
       |
       +-- /frontend/CLAUDE.md   # Subdirectory — scoped context
       +-- /backend/CLAUDE.md    # Subdirectory — scoped context
```

**Reglas**:
- Cada nivel **agrega** al anterior, NUNCA sobreescribe
- Mantener cada archivo bajo **200 líneas**
- Subdirectorios se cargan **lazy** (solo al trabajar con archivos en esa ruta)

### Qué poner en cada nivel

| Nivel | Contenido | Ejemplo |
|-------|-----------|---------|
| **User** (`~/.claude/CLAUDE.md`) | Preferencias globales | "Usar conventional commits" |
| **Project** (`./CLAUDE.md`) | Stack, arquitectura, convenciones | "Python 3.12 + FastAPI" |
| **Subdirectory** | Convenciones de un módulo | "Angular 20 con signals" |
| **Auto Memory** | Aprendizajes de sesiones previas | "El usuario prefiere pnpm" |

---

## Handoff entre sesiones

### Cuándo cerrar sesión

- Feature completada y commiteada
- Contexto >70% usado
- Más de 40 turnos
- Cambio de tarea/dominio significativo

### Protocolo de handoff

1. **Commit** todo el trabajo en progreso
2. **Documentar** estado actual (qué está listo, qué falta, decisiones pendientes)
3. **Compactar o nueva sesión**
4. En proyectos SWL, usar `/swl:checkpoint` para guardar estado

---

## Mejores prácticas

### Lo que SÍ hacer

1. Correr `/init` primero — Genera un CLAUDE.md inicial
2. Ser específico en instrucciones — "Agrega endpoint POST /invoices" > "agrega facturación"
3. Referenciar archivos con `@` — Carga el archivo en contexto
4. Commitear para compartir aprendizaje — CLAUDE.md en git = equipo alineado
5. Usar subagentes para tareas independientes

### Lo que NO hacer

1. Sesiones largas (más de 40 turnos = degradación)
2. CLAUDE.md gigante (más de 200 líneas)
3. Ignorar /compact en 70%+
4. Todo en una sesión
5. Secretos en CLAUDE.md

---

## Patrón de delegación con Opus 4.7 (desde abril 2026)

Opus 4.7 introduce un shift operativo importante: **rinde mejor tratado como un
ingeniero al que delegas, no como un pair programmer al que guías línea por línea**.
Fuente: https://claude.com/blog/best-practices-for-using-claude-opus-4-7-with-claude-code

### Tres cambios en el workflow

1. **Especificar tareas completas desde el inicio**
   - Dar intent + constraints + acceptance criteria + file locations en el
     primer prompt, no fragmentado en varios turnos.
   - Un prompt completo al inicio es más eficiente que 5 turnos de refinamiento.
   - Ejemplo: en lugar de "agrega autenticación" → "agrega JWT auth en
     `src/auth/jwt.ts` usando `jose` v5, con refresh tokens de 15min,
     tests en `tests/auth.test.ts`, sin tocar la capa de BD".

2. **Reducir interacciones turn-by-turn**
   - Cada turno suma overhead de razonamiento.
   - Agrupar preguntas: "A, B y C" en un solo turno > tres turnos separados.
   - No interrumpir a mitad de una tarea larga salvo que sea bloqueante.

3. **Usar auto mode cuando sea apropiado**
   - Disponible para usuarios Max de Claude Code.
   - Ideal para tareas de larga duración donde confías en la ejecución autónoma.
   - El modelo notifica cuando la tarea se completa.

### Niveles de esfuerzo (xhigh es el nuevo default)

| Nivel | Cuándo usar | Comportamiento |
|-------|-------------|----------------|
| `high` | Tareas mecánicas, refactors simples | Balance inteligencia/costo/velocidad |
| `xhigh` (default) | **La mayoría** de tareas de coding agentic | Razonamiento extendido sin overthinking |
| `max` | Problemas genuinamente difíciles | Más pensamiento pero diminishing returns — no abusar |

Toggle con `Shift+Tab`. No existe más el `extended thinking con budget fijo` —
el modelo decide dinámicamente cuánto razonar según la tarea.

### Sub-agentes: paralelismo explícito

Opus 4.7 usa menos sub-agentes por defecto que 4.6. Si una tarea se beneficia
de ejecución paralela, declararlo en el prompt:

- "Ejecuta estos 3 análisis en paralelo" > confiar en que lo decidirá solo.
- Especificar qué tool uses van en paralelo en una sola respuesta.

### Instrucciones literales

Opus 4.7 interpreta instrucciones de forma más literal. Los prompts ambiguos
que 4.6 resolvía por inferencia ahora se ejecutan al pie de la letra. Invertir
tiempo en eliminar ambigüedad al inicio ahorra iteraciones.

### Tokenizer actualizado (impacto en presupuesto)

El mismo contenido produce 1.0–1.35× más tokens en 4.7 que en 4.6. Las reglas
de context management del sistema SWL se recalibraron:
- Umbral de compactación: 60% → 50% del contexto
- `context-builder` budget default: 2000 → 2500 tokens

Consultar skill `compactacion-contexto` para protocolo completo.

Para skills bundled de Claude Code, patrones de productividad por tarea
y quick reference completa, ver [recursos/referencia-completa.md](recursos/referencia-completa.md).

## Gotchas / Errores comunes no obvios

- **Sesión de >40 turnos sin compactar**: el agente no monitorea el conteo de turnos y continúa trabajando hasta que Claude empieza a "olvidar" decisiones tomadas temprano en la sesión. Causa: no se aplica la señal de context rot (40 turnos). Solución: al llegar a 40 turnos, ejecutar `/swl:compactar` antes de la siguiente tarea grande — no esperar a que la degradación sea visible en la calidad del output.
- **CLAUDE.md superando 200 líneas sin subdirectorios**: el proyecto crece y todo el contexto se acumula en el CLAUDE.md raíz, incrementando la carga base de contexto de cada conversación. Causa: no se crean CLAUDE.md de subdirectorio para módulos como `backend/` o `frontend/`. Solución: extraer convenciones específicas de módulo a su propio `<directorio>/CLAUDE.md`; el CLAUDE.md raíz mantiene solo lo global.
- **Auto Accept Mode activado en operaciones destructivas**: el usuario activa `Shift+Tab` para acelerar trabajo y olvida cambiarlo antes de un deploy o borrado de archivos. Causa: el modo no tiene contexto de operación. Solución: volver a Default Mode explícitamente antes de operaciones irreversibles (`Shift+Tab` de vuelta) — Auto Accept es para generación de código, no para operaciones con blast radius alto.
- **Tokenizer 4.7 subestimado en presupuesto de contexto**: el mismo CLAUDE.md que ocupaba el 30% del contexto en Opus 4.6 ocupa hasta 40% en 4.7 debido al tokenizer más granular. Causa: el umbral de compactación no se recalibró al migrar de modelo. Solución: con Opus 4.7, bajar el umbral de compactación de 70% a 50% tal como indica el skill `compactacion-contexto`.
