← Volver al listado de tecnologías ← Índice de Claude Code

Cap 10: Workflows de Desarrollo

2 de marzo de 2026 Por: Artiko

claude-codeworkflowsrpiplan-modedesarrollo

Vanilla Claude Code vs Workflows

Vanilla (sin configuración)

Abrir claude, escribir lo que necesitas. Funciona para tareas simples pero tiene limitaciones:

Claude puede desviarse del objetivo
No hay estructura para tareas complejas
Difícil reproducir resultados consistentes

Con Workflows

Usar commands, agents y skills para estructurar el trabajo. Beneficios:

Resultados reproducibles
Tareas complejas divididas en pasos
Conocimiento compartido entre el equipo

El workflow canónico: Explore → Plan → Implement → Commit

La guía oficial de Anthropic documenta un workflow de cuatro fases. Es el marco de referencia; RPI (la sección siguiente) es una variante de tres fases que colapsa Commit dentro de Implement.

flowchart LR
    A["Explore<br/>plan mode: leer sin editar"] --> B["Plan<br/>plan detallado, Ctrl+G para editarlo"]
    B --> C["Implement<br/>salir de plan mode y codificar<br/>verificando contra el plan"]
    C --> D["Commit<br/>commit descriptivo + PR"]

Explore: entrar en plan mode y dejar que Claude lea el codebase sin editar nada.
Plan: pedir un plan detallado. Se puede abrir con Ctrl+G para editarlo en el editor antes de ejecutarlo.
Implement: salir de plan mode y codificar verificando el resultado contra el plan.
Commit: commit descriptivo y PR.

Cuándo saltarse el plan

El plan mode tiene coste en tokens y en tiempo. La regla oficial:

«If you could describe the diff in one sentence, skip the plan.»

Para un typo, añadir un log o renombrar una variable se pide directo, sin fase de planificación.

RPI: Research → Plan → Implement

Variante de tres fases del workflow anterior, útil para tareas complejas donde la investigación merece su propio artefacto:

Fase 1: Research (Investigar)

claude "Investiga cómo funciona el sistema de autenticación actual.
Lee los archivos relevantes, identifica los componentes,
y documenta el flujo completo."

Claude explora el codebase, lee archivos, y presenta un resumen. No modifica nada.

Fase 2: Plan (Planificar)

claude "Basándote en tu investigación, crea un plan para migrar
de JWT a sesiones server-side. Lista los archivos a modificar,
el orden de cambios, y los riesgos."

Claude crea un plan detallado. Se puede usar el plan mode para esto:

claude --permission-mode plan

En plan mode las ediciones quedan bloqueadas hasta que se apruebe el plan. Si auto mode está disponible y useAutoModeDuringPlan está activo (lo está por defecto), el clasificador aprueba automáticamente los comandos de solo lectura sin preguntar.

Fase 3: Implement (Implementar)

claude "Implementa el plan que creaste. Empieza por el paso 1.
Commitea después de cada paso completado."

Claude ejecuta el plan paso a paso, commiteando incrementalmente.

Ejecutar con menos fricción: auto mode

La fase de implementación no tiene por qué correr en el modo interactivo por defecto. Hoy existen seis modos de permiso: default (etiquetado Manual en la UI), acceptEdits, plan, auto, dontAsk y bypassPermissions. La guía oficial recomienda auto mode, allowlists vía /permissions y sandboxing OS-level vía /sandbox en lugar de flags que saltan permisos.

claude --permission-mode auto -p "fix all lint errors"

Consideraciones de auto mode:

Usa un modelo clasificador aparte (Claude Sonnet 5 desde v2.1.210, no el modelo de la sesión) que revisa cada acción antes de ejecutarla. Sus llamadas cuentan para el consumo de tokens.
Tiene frenos no configurables: 3 bloqueos seguidos o 20 en total pausan auto mode y devuelven los prompts. Con -p los bloqueos repetidos abortan la sesión, porque no hay usuario a quien preguntar.

Verificación ejecutable (regla 1)

La regla número uno de la guía oficial de workflows: darle a Claude una forma ejecutable de verificar su propio trabajo. Tests, exit code del build, un linter, un script contra un fixture, un screenshot de navegador — cualquier cosa que produzca una señal objetiva.

Sin un check, «looks done» es la única señal disponible y el humano se convierte en el loop de verificación. Hay que pedir evidencia (salida de los tests, el comando ejecutado y su resultado, el screenshot), no aserciones de éxito.

«If you can’t verify it, don’t ship it.»

Cuatro niveles para forzar la verificación, de menos a más rígido:

Nivel	Mecanismo	Nota
1	Pedir el check en el mismo prompt	«Ejecuta `bun test` y pégame la salida»
2	Fijarlo como condición de `/goal`	Un evaluador separado lo revalida tras cada turno
3	Un hook `Stop` que bloquea el fin del turno	Claude Code lo anula tras 8 bloqueos consecutivos
4	Subagente verificador o workflow dinámico	Se le pide que intente refutar el resultado

Sobre el nivel 3: diseñar un gate asumiendo bloqueo indefinido es un antipatrón, precisamente porque el override existe a partir del octavo bloqueo consecutivo.

"Implementa el paso 1. Cuando termines, ejecuta bun test y muéstrame
la salida completa. No digas que está listo sin pegar el resultado."

Plan Mode

En plan mode las ediciones están bloqueadas hasta que apruebes el plan. No es una lista fija de herramientas prohibidas: con auto mode disponible y useAutoModeDuringPlan activo (el default), el clasificador aprueba sin preguntar los comandos de solo lectura, mientras que cualquier modificación queda retenida.

Tres formas de activarlo

# 1. Al iniciar la sesión
claude --permission-mode plan

# 2. Prefijando UN SOLO prompt (vuelve al modo anterior después)
/plan investiga cómo funciona el sistema de autenticación

3. Shift+Tab cicla entre modos: default → acceptEdits → plan, insertando auto y bypass cuando están habilitados.

Cuando está activo, la barra de estado muestra:

⏸ plan mode on

Editar el plan antes de ejecutarlo

Ctrl+G abre el plan en tu editor. Puedes corregir pasos, borrar los que sobran o añadir restricciones, y ejecutar la versión editada — es más barato que pedirle a Claude que re-planifique en tres mensajes.

Las cuatro opciones al aprobar el plan

Opción	Efecto
Yes, and use auto mode	Ejecuta el plan con el clasificador de auto mode aprobando acciones
Yes, manually approve edits	Ejecuta el plan pidiendo aprobación de cada edición
No, refine with Ultraplan on Claude Code on the web	Sale a Ultraplan en la web para refinar el plan
No, keep planning	Sigue en plan mode

Aceptar un plan renombra automáticamente la sesión, lo que facilita encontrarla después en /resume.

Cuándo usar plan mode

Explorar un codebase nuevo
Diseñar arquitectura antes de implementar
Auditoría de código sin riesgo de cambios accidentales
Review de PRs

Boris Feb26 Workflow

Workflow popularizado en la comunidad. Estructura disciplinada en 4 fases:

1. Definir el objetivo

Escribir exactamente qué se quiere lograr en un mensaje claro y específico.

2. Investigar primero

"Antes de hacer cualquier cambio, investiga:
- ¿Qué archivos están involucrados?
- ¿Qué dependencias hay?
- ¿Qué tests existen?
Presenta tus hallazgos."

3. Crear plan con checkpoints

"Crea un plan con pasos numerados.
Después de cada paso, commitea y verifica que los tests pasen."

4. Implementar con commits atómicos

Cada paso del plan = un commit. Si algo falla, es fácil revertir.

Commit often

Una de las mejores prácticas más importantes:

<!-- En tu CLAUDE.md -->
## Reglas de desarrollo
- Commitear después de cada cambio funcional
- Cada commit debe dejar el proyecto en estado funcional
- Ejecutar tests antes de cada commit

Beneficios:

Checkpoints naturales que complementan a /rewind
Fácil identificar qué cambio introdujo un bug
Permite paralelizar trabajo con agent teams

Por qué los commits no son opcionales aunque exista `/rewind`

Claude Code guarda un snapshot antes de cada prompt del usuario, conserva los 100 checkpoints más recientes por sesión y los limpia junto con las sesiones a los 30 días (cleanupPeriodDays).

La limitación crítica: el checkpointing solo cubre ediciones hechas con las herramientas de edición. No se restauran:

Cambios producidos por comandos bash (un sed -i, un script de migración, un npm run codemod)
Cambios externos (otro proceso, tu propio editor, un compañero)
Rutas symlink o hardlink

Esos tres huecos son exactamente lo que sí cubre un commit git. De ahí la regla de commitear seguido.

/rewind (o doble Esc con el input vacío) ofrece cinco acciones:

Acción	Qué hace
Restore code and conversation	Vuelve el código y el historial al checkpoint
Restore conversation	Solo el historial; el código queda como está
Restore code	Solo los archivos; la conversación se mantiene
Summarize from here	Resume desde ese punto en adelante
Summarize up to here	Resume todo lo anterior a ese punto

Workflow de debugging efectivo

1. "Reproduce el bug. Muéstrame el error exacto."
2. "Investiga la causa raíz. No propongas soluciones aún."
3. "Propón 2-3 soluciones con pros/contras."
4. [Usuario elige solución]
5. "Implementa la solución X. Agrega un test que verifica el fix."
6. "Ejecuta todos los tests relacionados."

La regla de las dos correcciones

Si corregiste a Claude más de dos veces sobre lo mismo, el contexto ya está contaminado con los enfoques fallidos: cada intento anterior sigue en la ventana empujando hacia la misma dirección equivocada. La salida no es una tercera corrección, es /clear y reescribir el prompt inicial incorporando lo que aprendiste.

«A clean session with a better prompt almost always outperforms a long session with accumulated corrections.»

Los cinco patrones de falla

Patrón	Síntoma	Salida
Kitchen sink session	Una sola sesión mezcla tareas no relacionadas	`/clear` entre tareas
Correcting over and over	Tercera corrección sobre el mismo punto	`/clear` y reescribir el prompt
Over-specified CLAUDE.md	El archivo creció y las reglas se pierden	Podar, o convertir la regla en hook
Trust-then-verify gap	Se acepta «listo» sin evidencia	Verificación ejecutable siempre
Infinite exploration	Investigar sin acotar llena el contexto con cientos de archivos	Acotar el alcance o delegar en subagentes

Sobre el último: «investiga cómo funciona la app» es un prompt sin frontera. «Investiga cómo se resuelve la sesión en src/auth/, máximo 10 archivos, devuélveme un resumen» sí la tiene. Los subagentes son la otra salida, porque corren en ventanas de contexto separadas y devuelven solo el resumen.

Workflow de refactoring

1. "Asegúrate de que todos los tests pasan." (baseline)
2. "Identifica el código a refactorizar y sus dependencias."
3. "Refactoriza paso a paso, ejecutando tests después de cada cambio."
4. "Verifica que no hay regresiones."

Revisión adversarial del diff antes de cerrar

Antes de dar el trabajo por terminado, el workflow canónico añade un paso: un subagente en contexto fresco revisa el diff contra el plan. También existe la skill incluida /code-review.

"Usa un subagente para revisar el diff contra el plan.
Que marque únicamente los gaps que afecten corrección
o requisitos declarados en el plan."

El valor está en el contexto fresco: la sesión que escribió el código está sesgada hacia él. De ahí también el patrón Writer/Reviewer en dos sesiones separadas — una escribe, otra revisa sin haber visto cómo se llegó al resultado.

flowchart LR
    A["Sesión Writer<br/>implementa el plan"] --> B["diff"]
    B --> C["Sesión Reviewer<br/>contexto fresco"]
    C --> D{"¿gaps de corrección<br/>o de requisitos?"}
    D -- sí --> A
    D -- no --> E["Commit + PR"]

La advertencia que acompaña al patrón

«A reviewer prompted to find gaps will usually report some, even when the work is sound… Chasing every finding leads to over-engineering.»

Un revisor al que se le pide encontrar problemas encuentra problemas. Por eso la instrucción al revisor debe acotarse explícitamente a corrección o requisitos declarados, y los hallazgos de estilo o de «podría ser más robusto» se descartan salvo que haya una razón concreta.

Ejemplo de CLAUDE.md con workflow

## Workflow de desarrollo
1. Investigar antes de implementar
2. Crear plan para cambios > 3 archivos
3. Commitear después de cada paso funcional
4. Ejecutar tests: bun test
5. Build final: bun build

Flujo completo RPI con ramas git

Cada fase del RPI vive en su propia rama. Esto permite pausar, revisar y revertir sin contaminar main.

gitGraph
   commit id: "baseline"
   branch research
   checkout research
   commit id: "exploración plan mode"
   commit id: "hallazgos documentados"
   checkout main
   merge research id: "research completo"
   branch plan
   checkout plan
   commit id: "plan de implementación"
   commit id: "plan revisado"
   checkout main
   merge plan id: "plan aprobado"
   branch implement
   checkout implement
   commit id: "paso 1: cambio A"
   commit id: "paso 2: tests"
   commit id: "paso 3: cambio B"
   checkout main
   merge implement id: "PR mergeado"

Comandos por fase

Fase Research — solo lectura, plan mode:

git checkout -b research
claude --permission-mode plan
# Claude usa Glob, Grep, Read, WebSearch — no modifica archivos
git add notas-research.md && git commit -m "research: hallazgos del sistema de auth"
git checkout main && git merge research

Fase Plan:

git checkout -b plan
claude "Basándote en la investigación previa, crea un plan detallado..."
git add plan.md && git commit -m "plan: migración JWT → sesiones server-side"
git checkout main && git merge plan

Fase Implement:

git checkout -b implement
claude "Implementa el paso 1 del plan. Ejecuta bun test al terminar
cada paso y pégame la salida. Commitea solo si pasan."
# Claude hace commits atómicos en cada sub-paso
# Al finalizar → revisión adversarial del diff → PR review → merge a main

Para pasos mecánicos y verificables (lint, formateo, migraciones repetitivas) esta fase puede correr con auto mode en vez del modo interactivo:

claude --permission-mode auto -p "fix all lint errors"

Workflow de Developer Productivity (Scenario 4)

Onboarding rápido a codebase desconocido

Cuando entras a un proyecto nuevo, la secuencia óptima es: ampliar → enfocar → profundizar.

flowchart TD
    A["Codebase desconocido"] --> B["Glob: estructura general<br/>*.config.* / src/**"]
    B --> C{"¿Entiendo la arquitectura?"}
    C -- no --> D["Grep: funciones clave<br/>main / handler / router"]
    C -- sí --> E["Read: archivos críticos<br/>config, entry points"]
    D --> E
    E --> F{"¿Hay patrones claros?"}
    F -- no --> G["Grep: patrones de naming<br/>convenciones de tests"]
    F -- sí --> H["Hacer pregunta específica<br/>a Claude"]
    G --> H
    H --> I["Contexto suficiente<br/>para contribuir"]

Prompt de onboarding efectivo:

"Tengo 30 minutos para entender este proyecto antes de hacer un cambio.
1. ¿Cuál es el flujo principal de datos?
2. ¿Dónde viven los tests?
3. ¿Qué convenciones de naming usa el proyecto?
4. ¿Cuáles son los archivos que más frecuentemente se modifican?
Solo lee, no cambies nada."

Autocompletar boilerplate con patrones del proyecto

En lugar de describir cómo quieres el código, muestra ejemplos existentes:

"Lee estos tres archivos que son similares a lo que necesito:
- src/handlers/user-handler.ts
- src/handlers/product-handler.ts
- src/handlers/order-handler.ts

Ahora crea src/handlers/invoice-handler.ts siguiendo exactamente
el mismo patrón: estructura, naming, manejo de errores, tipos de retorno.
No improvises — copia el patrón."

Claude infiere: estructura de imports, convención de nombres de funciones, manejo de errores, tipos compartidos, y tests esperados.

Automatizar tareas repetitivas

Ejemplo real: renombrar variables con criterio semántico

"En todos los archivos de src/models/, renombra las variables que usen
el prefijo 'tmp_' por nombres descriptivos basados en su uso.
Por ejemplo: tmp_data → parsedData, tmp_result → validationResult.
Muéstrame una lista de cambios propuestos ANTES de aplicarlos."

Cuándo usar Ralph Loop vs comando directo:

Tarea	Usar	Razón
Renombrar en 1-3 archivos conocidos	Comando directo (`Edit`)	Más rápido, menos tokens
Renombrar con criterio semántico en N archivos	Ralph Loop	Claude necesita leer para decidir
Transformar formato de datos en tests	Comando directo	Patrón mecánico, no requiere juicio
Refactorizar para mejorar legibilidad	Ralph Loop	Requiere entender el contexto
Agregar logging en puntos de error	Ralph Loop	Claude identifica los puntos

Ralph Loop = Research → Proponer lista → Aprobar → Apply. Nunca apply directo sin ver la lista primero.

Cuándo NO usar Claude Code en workflows

Hay situaciones donde Claude Code no debe ser el tomador de decisiones, aunque pueda ejecutar los cambios técnicamente.

Situaciones de alto riesgo

Contexto de negocio opaco: Claude no sabe que “renombrar el campo legacy_id” rompe 3 integraciones con sistemas externos no documentados
Decisiones de arquitectura transversales: Si el cambio afecta la estructura de directorios de toda la empresa o el contrato público de una API
Operaciones irreversibles sin backup confirmado: Migraciones de base de datos en producción, eliminación de datos de usuarios, cambios de schema sin rollback

Tabla de decisión

Tarea	Recomendación
Agregar un endpoint nuevo	Usar Claude Code
Decidir si usar GraphQL o REST para el sistema	No usar — decisión de arquitectura
Escribir tests para código existente	Usar Claude Code
Eliminar una feature completa con usuarios activos	No usar — requiere contexto de negocio
Refactorizar una función de utilidades	Usar Claude Code
Migrar base de datos en producción	Usar con supervisión — generar script, revisar, ejecutar manualmente
Renombrar variables internas en un módulo	Usar Claude Code
Cambiar el contrato público de una API	Usar con supervisión — verificar todos los consumidores primero
Corregir un bug con test reproducible	Usar Claude Code
Decidir qué deuda técnica priorizar	No usar — decisión estratégica del equipo

Regla práctica: Si la pregunta empieza por “¿deberíamos…?”, es decisión humana. Si empieza por “¿cómo…?”, Claude Code puede ayudar.

Siguiente: Agent Teams y Worktrees